Add authoritative public API catalog

RUSTREWRITE.md

@@ -20,6 +20,10 @@ Generated inventories are intentionally checked in:
   crate/module/type and source line.
 - `api/SURFACE.tsv` records every public declaration line in the 13 library
   projects, including a SHA-256 digest.
+- `api/public-api.json` is the authoritative compiled-metadata catalog for all
+  13 library assemblies after all six source generators run. It also records
+  every external type referenced by a public signature as a pending Rust
+  mapping obligation.
 - `tests/upstream-tests.json` records every NUnit invocation and the SHA-256 of
   its C# method body.
 - `tests/PARITY.md` maps every NUnit invocation to its Rust test name.
@@ -27,9 +31,11 @@ Generated inventories are intentionally checked in:
   nine sample/tool projects.
 
 Run `python3 tools/generate_surface.py` after deliberately changing the pinned
-upstream snapshot. The generator rejects a test count other than 1,295 so an
-upstream drift cannot silently remove tests. Update the commit constant and
-review all ledger diffs in the same change.
+upstream snapshot, then run `python3 tools/extract_public_api.py` to rebuild the
+authoritative metadata catalog twice and require byte-identical output. The
+source generator rejects a test count other than 1,295 so upstream drift cannot
+silently remove tests. Update both commit constants and review all ledger diffs
+in the same change.
 
 ### Current shell status
 
@@ -38,6 +44,9 @@ The current workspace is a structural baseline, not a working client:
 - all 13 public .NET library projects have corresponding Rust crates;
 - 1,705 public C# type declarations produce compiling Rust type/trait shims;
 - 12,195 public declaration lines are retained in the API ledger;
+- compiled metadata records 3,066 public types and 30,789 public members with
+  matching independent ECMA-335 counts, plus 142 external signature types that
+  still require explicit Rust mapping decisions;
 - all 1,295 NUnit `[Test]`/`[TestCase]` invocations have compiling Rust test
   entries that intentionally panic with their source identity and body hash;
 - all nine sample/tool projects have compiling Rust binary targets;
@@ -184,12 +193,16 @@ for every public/nested-public:
 - event and delegate payload;
 - base type, implemented interface and relevant public attribute.
 
-Create `api/public-api.json` as that catalog and `api/RUST-MAPPING.tsv` with one
-row per C# member: stable C# documentation ID, C# signature, Rust crate/path,
-Rust signature, mapping decision, and status. A coverage checker must fail for
-missing members, duplicate Rust destinations, unresolved types, or stale source
-IDs. `api/SURFACE.tsv` remains useful for source navigation but is not the
-coverage authority.
+`api/public-api.json` is that catalog. Its `external_types` section records each
+non-LibreMetaverse type used by a public signature, its defining assembly, and
+every owning LibreMetaverse documentation ID; it intentionally does not copy
+the external assembly's member surface. Create `api/RUST-MAPPING.tsv` with one
+row per C# member and resolve every external entry to Rust core/std, an adopted
+crate, or a native MetaCrate replacement: stable C# documentation ID, C#
+signature, Rust crate/path, Rust signature, mapping decision, and status. A
+coverage checker must fail for missing members, duplicate Rust destinations,
+unresolved external types, or stale source IDs. `api/SURFACE.tsv` remains useful
+for source navigation but is not the coverage authority.
 
 Each mapped Rust item must actually compile and be callable: