feat(catalog): implement stable content index

.github/workflows/validate.yml

@@ -80,3 +80,15 @@ jobs:
             <(jq -S . compatibility/m1-corpus-baseline.json) \
             <(jq -S . build/m1-corpus-report.json)
           jq . build/m1-corpus-report.json | tee -a "${GITHUB_STEP_SUMMARY}"
+
+      - name: Audit whole-corpus catalog references
+        working-directory: toolkit
+        run: |
+          cargo run --locked --package atrinik-catalog --example corpus -- \
+            --root ../corpus \
+            --revision 01b1fdb65c2243df4bafe9c8109fc93229df0121 \
+            >build/m2-catalog-corpus-report.json
+          diff -u \
+            <(jq -S . compatibility/m2-catalog-corpus-baseline.json) \
+            <(jq -S . build/m2-catalog-corpus-report.json)
+          jq . build/m2-catalog-corpus-report.json | tee -a "${GITHUB_STEP_SUMMARY}"

README.md

@@ -54,6 +54,30 @@ Clippy-as-errors, unit/doc/property/adversarial tests, dependency/license and
 vulnerability checks, provenance validation, public fixture/CLI conformance,
 release builds, and a release dry run.
 
+## Stable catalog and diagnostics
+
+`atrinik-catalog` exposes the shared headless catalog API used by CI, CLI, and
+editor integrations. `CatalogId` combines an explicit domain, namespace, and
+locale-independent local ID for archetypes, maps, faces, animations, treasures,
+factions, interfaces, quests, and resources. Ordered indexes resolve canonical
+IDs, aliases, inheritance, and typed references. `Query` and `preview` return
+bounded metadata without retaining or reparsing resource payloads.
+
+Catalog inputs carry their source revision and schema version. A generation is
+derived deterministically from those inputs, while `update_document` and
+`remove_document` report the exact changed identities and their transitive
+dependents. An unchanged document is a no-op, and an incremental result is
+identical to a clean build over the same documents.
+
+`atrinik-diagnostics` is the single structured diagnostic representation. Each
+diagnostic has a stable code, severity, source span, related locations,
+semantic path, message, optional fix hint, and explicit suppression state.
+Catalog conflicts use `catalog.duplicate_id`, `catalog.ambiguous_alias`,
+`catalog.missing_reference`, `catalog.ambiguous_reference`, and
+`catalog.inheritance_cycle`. Only diagnostics explicitly marked suppressible
+can be suppressed, and diagnostic count, related-location count, text size, and
+semantic-path depth are bounded.
+
 `Content toolkit corpus` checks out the authored `arch`/`maps` corpus at the
 immutable revision recorded in `provenance/reuse.json`, byte-round-trips every
 selected authored file or returns a bounded classified failure, and publishes
@@ -66,6 +90,22 @@ cargo run --locked --package atrinik-source --example corpus -- \
   --revision 01b1fdb65c2243df4bafe9c8109fc93229df0121
 ```
 
+The same CI job builds the cross-file catalog from every supported semantic
+document, indexes every bounded regular file as a resource and every PNG media
+identity as a face, resolves supported references, and emits bounded diagnostic
+counts plus a deterministic digest of their source/span/path/message identities:
+
+```sh
+cargo run --locked --package atrinik-catalog --example corpus -- \
+  --root /absolute/content/checkout \
+  --revision 01b1fdb65c2243df4bafe9c8109fc93229df0121
+```
+
+`compatibility/m2-catalog-corpus-baseline.json` pins the resulting generation,
+domain-definition totals, severity-qualified diagnostic counts, and diagnostic
+identity digest. CI fails on any drift, including a newly unresolved,
+ambiguous, duplicate, or cyclic edge even when aggregate counts are unchanged.
+
 The M1 baseline is 5,590 authored files, 61,379,370 bytes, zero diagnostics or
 truncation, and digest
 `8cc6a362dcf20ed7760ec2b9813fff9dbdb7803017247c4530e5575a20ffa5e3`.

compatibility/m2-catalog-corpus-baseline.json

@@ -0,0 +1,24 @@
+{
+  "schema_version": 1,
+  "corpus_revision": "01b1fdb65c2243df4bafe9c8109fc93229df0121",
+  "generation": "c0c85cc10a39f93d28a172dfcae9b4c5196ab9277ba5d02685940bb6c2831230",
+  "documents": 5678,
+  "definitions": 33372,
+  "diagnostics": 254,
+  "diagnostic_digest": "5d77c014f0dbc27882be7655872adfe6bf017782a80de4dd1bbc1b80ff36c13e",
+  "codes": {
+    "catalog.missing_reference:error": 245,
+    "catalog.missing_reference:warning": 9
+  },
+  "domains": {
+    "animation": 775,
+    "archetype": 3784,
+    "face": 9413,
+    "faction": 56,
+    "interface": 67,
+    "map": 3666,
+    "quest": 16,
+    "resource": 15453,
+    "treasure": 142
+  }
+}

crates/atrinik-catalog/Cargo.toml

@@ -9,4 +9,6 @@ rust-version.workspace = true
 version.workspace = true
 
 [dependencies]
+atrinik-diagnostics.workspace = true
 atrinik-source.workspace = true
+sha2.workspace = true