Enforce declared platform interface inventory

docs/PLATFORM_CONTROL_PLANE.md

@@ -25,6 +25,7 @@ releases, module boundaries, migrations, and security controls.
 | Labels and translations | Generated translation catalogs plus source usage |
 | Fields and help coverage | Shared form components plus generated TypeScript AST inventory |
 | API use by the WebUI | Typed API clients plus generated static reference inventory |
+| Stable platform interface IDs | Typed manifest/WebUI declarations plus line-independent source anchors for low-level controls |
 | Effective configuration | Owning module data plus Policy provenance |
 
 Runtime introspection is authoritative for an installed system. Static source
@@ -45,7 +46,9 @@ The command writes:
 - `audit-reports/platform-inventory/platform-interface-inventory.json`
 - `audit-reports/platform-inventory/platform-interface-inventory.md`
 
-Use `--strict` for the combined translation and endpoint audit. Use
+Use `--strict` for the combined translation, endpoint, and declaration audit.
+Use `--strict-declarations` for duplicate/stale/undeclared interface checks
+without making existing translation coverage a release blocker. Use
 `--strict-endpoints` in the endpoint-surface CI gate so unrelated translation
 catalog work cannot disable route classification enforcement. Both strict modes
 require every backend endpoint without a statically visible WebUI path to have
@@ -75,6 +78,16 @@ It combines:
 2. TypeScript AST extraction of fields, label attributes, visible text,
    translations, frontend routes, navigation, capabilities, and API references
 3. Python AST extraction of FastAPI route decorators and router prefixes
+4. normalized runtime declarations from every loaded `ModuleManifest`
+
+The declaration set covers routes, navigation, View surfaces, fields, actions,
+help references, translations, admin/settings sections, widgets, search
+objects, permissions, provided interfaces, and backend capabilities. Typed
+module contributions keep their declared IDs. Shared controls may declare
+`interfaceId` and `helpTopicId`; otherwise the extractor assigns a deterministic
+source anchor based on repository, file, component context, control type, and
+semantic label rather than a line number. The JSON records which identity
+source was used.
 
 The JSON includes exact repository, file, and line evidence. A missing-help
 entry is a review candidate because dynamic parent components may supply help.
@@ -82,11 +95,41 @@ A backend route without a static frontend reference is also a review candidate:
 public APIs, workers, callbacks, health checks, connectors, and dynamic URL
 assembly are valid explanations.
 
-The module matrix enforces endpoint declarations with `--strict-endpoints`.
+The module matrix enforces endpoint and interface declarations with
+`--strict-endpoints --strict-declarations`.
 Combined `--strict` additionally fails when used translation keys are absent
 from generated locale catalogs. Help-text findings remain review candidates
 rather than a release gate because dynamic parent components can supply help.
 
+## Runtime Comparison
+
+Core exposes a sanitized read-only catalog at
+`GET /api/v1/platform/interface-catalog`. Access requires
+`admin:module:read` or `system:settings:read`. Tenant module entitlements are
+applied before serialization, so the response describes only the effective
+installed combination. It contains IDs, paths, authorization metadata,
+versions, counts, and canonical digests; it excludes factories, callbacks,
+credentials, and mutable runtime state.
+
+Capture and compare a running installation:
+
+```bash
+curl --fail --silent \
+  -H "Authorization: Bearer $GOVOPLAN_ACCESS_TOKEN" \
+  "$GOVOPLAN_URL/api/v1/platform/interface-catalog" \
+  > /tmp/govoplan-runtime-interface.json
+
+./.venv/bin/python tools/inventory/platform-interface-inventory.py \
+  --runtime-snapshot /tmp/govoplan-runtime-interface.json \
+  --strict-declarations \
+  --strict-endpoints
+```
+
+The comparison accepts any installed subset. Every module present in the
+runtime response must have the same contract version, module version, and
+declaration digest as the static release inventory. Unknown, duplicate, or
+mismatched runtime modules fail strict declaration mode.
+
 ## Admin Information Architecture
 
 The Admin host uses a tree because system, tenant, group, user, and module
@@ -139,13 +182,20 @@ Custom code, new routes, arbitrary SQL, and executable workflow nodes remain
 release artifacts. Modeling them as ordinary configuration would create an
 unreviewed code-execution and migration channel.
 
-## Next Enforcement Slices
+## Enforced Contract
 
-1. Require every WebUI module route and admin/settings contribution to have
-   matching manifest metadata or a reviewed exception.
-2. Add stable field IDs and optional help-topic IDs to shared field components.
-3. Classify each statically unreferenced backend endpoint by consumer type.
-4. Compare a running installation's OpenAPI and module registry against the
-   release inventory.
-5. Publish the sanitized installed-system structure through Ops/Docs for
-   authorized administrators.
+1. Public WebUI routes and View surfaces must reconcile with runtime manifest
+   metadata; stale runtime routes and source-only public surfaces fail CI.
+2. Duplicate stable IDs fail CI. Shared controls support explicit field/action
+   and help-topic identities; fallback anchors remain visible review evidence.
+3. Every statically unreferenced backend endpoint has an exact reviewed
+   consumer classification, and stale classifications fail CI.
+4. Runtime module combinations can be compared exactly with static release
+   evidence through versioned per-module digests.
+5. Runtime introspection is authorized, tenant-filtered, and read-only. It is
+   safe for Ops/Docs projection but is not a generic configuration or code
+   mutation channel.
+
+Generated JSON and Markdown remain build/audit artifacts. Do not hand-edit or
+use them as a backlog; change the owning manifest, typed WebUI contribution,
+translation/help declaration, or exact endpoint classification instead.