# Public API catalog

`public-api.json` is the authoritative compiled-metadata inventory for the 13
LibreMetaverse library assemblies at the pinned upstream commit. It contains:

- stable C# documentation IDs and complete public type/member metadata;
- nullability, constraints, bases, interfaces, overload parameters, accessors,
  constants, events, delegates, enum values, and public attributes;
- assembly identities and independent reflection/ECMA-335 count checks;
- hashes for the outputs of all six upstream source generators;
- `external_types`, the non-LibreMetaverse types used by public signatures and
  every LibreMetaverse API that uses them.

External entries are replacement obligations, not copied dependency APIs.
`RUST-TYPES.tsv` resolves every entry to Rust core/std, an adopted
cross-platform crate, or a native MetaCrate type. Third-party API objects use
project-owned boundary types so their eventual backend can be replaced without
exposing SkiaSharp, SIPSorcery, MessagePack, CoreJ2K, or another foreign member
surface. `RUST-MAPPING.tsv` records one reviewed destination and full Rust
signature for every catalog member. `MAPPING-COVERAGE.md` is the readable gate
summary.

Regenerate from the clean pinned upstream checkout:

```sh
python3 tools/extract_public_api.py
```

The command builds the upstream libraries into a temporary directory, runs the
extractor twice against the same compiled metadata, rejects count mismatches or
duplicate documentation IDs, and writes the result only when both outputs are
byte-identical. The extractor is development-only and is absent from every
Cargo manifest and published Rust dependency graph.

Regenerate or validate the Rust mapping with only Python's standard library:

```sh
python3 tools/generate_rust_mapping.py
python3 tools/generate_rust_mapping.py --check
python3 tools/generate_api_shims.py
python3 tools/generate_api_shims.py --check
python3 tools/check_api_coverage.py
```

The checker rejects duplicate C# IDs, duplicate Rust destinations, invalid
statuses, stale or missing catalog entries, unresolved signature types,
assemblies without representative mappings, and platform-specific API targets.
It also rejects generated `Default` shims, plausible false/zero/empty/nil
fallbacks, and generated function bodies that do not use the standardized
`NotImplemented` error or `unimplemented_api!` panic.
The two support traits in `RUST-TYPES.tsv` are included because compiled public
inheritance records reference them even though they are absent from the public
type table.

`generate_api_shims.py` consumes the catalog and reviewed mapping ledger,
formats all 13 generated Rust assemblies deterministically, and generates the
standalone `tests/api-compile` downstream fixture. `check_api_coverage.py`
compares catalog IDs, mapping rows, exported shim IDs, and fixture probes;
rejects stale, missing, duplicate, or erased entries; and verifies
`API-COVERAGE.md`. Regenerate that report with
`python3 tools/check_api_coverage.py --write`.