# 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 and plausible false/zero/empty/nil
fallbacks. Failure-only bodies must use the standardized
`Error::NotImplemented` result or `unimplemented_api!` panic; reviewed native
member hooks must call an explicitly registered hand-written implementation.
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`.

The reviewed first-release public surface is stored in
[`SEMVER-BASELINE.json`](SEMVER-BASELINE.json), with the decisions and migration
recipes rendered in [`SEMVER-AUDIT.md`](SEMVER-AUDIT.md). The audit compares
mapping/export coverage, normalized Rust declarations, feature sets, ownership,
async and error contracts, thread-safety boundaries, and public dependency
types. Record a deliberate baseline only after reviewing its SemVer impact,
then verify it and write reproducible evidence:

```sh
cargo run --locked -p metacrate-ci-matrix -- api-baseline-write
cargo run --locked -p metacrate-ci-matrix -- api-audit \
  --evidence /tmp/metacrate-api-audit.json
cmp /tmp/metacrate-api-audit.json ci/evidence/api-audit.json
```

Native implementations replace whole generated types where practical. The
generated module retains the catalog markers and re-exports the hand-written
type; member-level implementations use an explicit generator registry. This
keeps regeneration deterministic without moving behavioral code into Python.
`SHIM-COVERAGE.md` reports native type/member totals separately from remaining
failure-only surfaces.