MetaCrate/api

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:

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:

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, with the decisions and migration recipes rendered in 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:

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.