spec: referential-integrity gate for contracts/ + schemas/ (P2.11)

Makefile

@@ -1,5 +1,5 @@
-.PHONY: engine-guards validate validate-repo validate-regis-acr-integration smoke-regis-acr-service validate-provable-ai-ops-exchange docs-check drift-check standards-check topology-check chronos-evidence-loop-readout-validate lattice-surfaces-check lattice-surface-ingestor-smoke lattice-studio-smoke grlplus-service-smoke grl-mesh-smoke sophos-reasoner-smoke entity-resolution-smoke validate-ops-fabric validate-search-academy-deploy validate-search-image-release validate-lampstand-lifecycle validate-zone-stack-audit policy-fabric-endpoint-client-smoke policy-fabric-guarded-workflow-smoke zone-router-publication-local-publish-smoke zone-router-publication-failure-evidence-smoke zone-router-publication-retry-state-smoke zone-router-publication-remote-broker-seam-smoke zone-router-publication-dead-letter-smoke validate-workroom-update-contract validate-professional-intelligence-manifest validate-wallguard-professional-workroom validate-wallguard-professional-workroom-runtime validate-svf-agent-contract validate-live-sociosphere-svf-contract validate-fogstack-svf-signadot-adapter-readiness validate-environment-validate-change-v2 validate-trust-chain-contracts validate-channel-runtime-gates test-go test-python-apps test-tools smoke smoke-health smoke-eval-fabric smoke-evidence-receipts smoke-evidence-console validate-phase3 lampstand-smoke validate-phase4 lampstand-vertical-slice-smoke lampstand-zone-smoke zone-router-publication-smoke zone-router-publication-enqueue-smoke semantic-bridge-zone-validation-smoke validate-fogstack validate-storage-suite trustops-art-runner-smoke validate-workspace-services test-workspace smoke-workspace workspace-up workspace-down workspace-logs workspace-build prometheus-local-demo validate-workroom-scope-d-adversarial devsecops-workroom-demo validate-proof-artifacts validate-evidence-cover-graph validate-adr-035-contracts validate-helper-causal-receipts validate-svc-substrate-source-control validate-systema-bridge validate-workroom-schemas validate-device-orchestration validate-mutation-evidence validate-fogstack-svf-p2-evidence-gates validate-repo-governance-contracts validate-semantic-governance validate-orggov-runtime-demo validate-cronjob-script-mirrors
-validate: validate-repo validate-regis-acr-integration validate-workspace-prophet-membrane-e2e validate-provable-ai-ops-exchange drift-check standards-check topology-check chronos-evidence-loop-readout-validate lattice-surfaces-check lattice-surface-ingestor-smoke lattice-studio-smoke grlplus-service-smoke grl-mesh-smoke sophos-reasoner-smoke entity-resolution-smoke validate-ops-fabric validate-search-academy-deploy validate-search-image-release validate-lampstand-lifecycle validate-zone-stack-audit policy-fabric-endpoint-client-smoke policy-fabric-guarded-workflow-smoke zone-router-publication-local-publish-smoke zone-router-publication-failure-evidence-smoke zone-router-publication-retry-state-smoke zone-router-publication-remote-broker-seam-smoke zone-router-publication-dead-letter-smoke validate-workroom-update-contract validate-professional-intelligence-manifest validate-wallguard-professional-workroom validate-wallguard-professional-workroom-runtime validate-svf-agent-contract validate-live-sociosphere-svf-contract validate-fogstack-svf-signadot-adapter-readiness validate-environment-validate-change-v2 validate-trust-chain-contracts validate-channel-runtime-gates test-go validate-phase4 test-python-apps test-tools validate-fogstack validate-storage-suite trustops-art-runner-smoke validate-workroom-scope-d-adversarial devsecops-workroom-demo validate-proof-artifacts validate-evidence-cover-graph validate-adr-035-contracts validate-helper-causal-receipts validate-svc-substrate-source-control validate-systema-bridge validate-workroom-schemas validate-device-orchestration validate-mutation-evidence validate-semantic-governance validate-orggov-runtime-demo validate-cronjob-script-mirrors
+.PHONY: engine-guards validate validate-repo validate-regis-acr-integration smoke-regis-acr-service validate-provable-ai-ops-exchange docs-check drift-check standards-check topology-check chronos-evidence-loop-readout-validate lattice-surfaces-check lattice-surface-ingestor-smoke lattice-studio-smoke grlplus-service-smoke grl-mesh-smoke sophos-reasoner-smoke entity-resolution-smoke validate-ops-fabric validate-search-academy-deploy validate-search-image-release validate-lampstand-lifecycle validate-zone-stack-audit policy-fabric-endpoint-client-smoke policy-fabric-guarded-workflow-smoke zone-router-publication-local-publish-smoke zone-router-publication-failure-evidence-smoke zone-router-publication-retry-state-smoke zone-router-publication-remote-broker-seam-smoke zone-router-publication-dead-letter-smoke validate-workroom-update-contract validate-professional-intelligence-manifest validate-wallguard-professional-workroom validate-wallguard-professional-workroom-runtime validate-svf-agent-contract validate-live-sociosphere-svf-contract validate-fogstack-svf-signadot-adapter-readiness validate-environment-validate-change-v2 validate-trust-chain-contracts validate-channel-runtime-gates test-go test-python-apps test-tools smoke smoke-health smoke-eval-fabric smoke-evidence-receipts smoke-evidence-console validate-phase3 lampstand-smoke validate-phase4 lampstand-vertical-slice-smoke lampstand-zone-smoke zone-router-publication-smoke zone-router-publication-enqueue-smoke semantic-bridge-zone-validation-smoke validate-fogstack validate-storage-suite trustops-art-runner-smoke validate-workspace-services test-workspace smoke-workspace workspace-up workspace-down workspace-logs workspace-build prometheus-local-demo validate-workroom-scope-d-adversarial devsecops-workroom-demo validate-proof-artifacts validate-evidence-cover-graph validate-adr-035-contracts validate-helper-causal-receipts validate-svc-substrate-source-control validate-systema-bridge validate-workroom-schemas validate-device-orchestration validate-mutation-evidence validate-fogstack-svf-p2-evidence-gates validate-repo-governance-contracts validate-semantic-governance validate-orggov-runtime-demo validate-cronjob-script-mirrors validate-schema-references
+validate: validate-repo validate-regis-acr-integration validate-workspace-prophet-membrane-e2e validate-provable-ai-ops-exchange drift-check standards-check topology-check chronos-evidence-loop-readout-validate lattice-surfaces-check lattice-surface-ingestor-smoke lattice-studio-smoke grlplus-service-smoke grl-mesh-smoke sophos-reasoner-smoke entity-resolution-smoke validate-ops-fabric validate-search-academy-deploy validate-search-image-release validate-lampstand-lifecycle validate-zone-stack-audit policy-fabric-endpoint-client-smoke policy-fabric-guarded-workflow-smoke zone-router-publication-local-publish-smoke zone-router-publication-failure-evidence-smoke zone-router-publication-retry-state-smoke zone-router-publication-remote-broker-seam-smoke zone-router-publication-dead-letter-smoke validate-workroom-update-contract validate-professional-intelligence-manifest validate-wallguard-professional-workroom validate-wallguard-professional-workroom-runtime validate-svf-agent-contract validate-live-sociosphere-svf-contract validate-fogstack-svf-signadot-adapter-readiness validate-environment-validate-change-v2 validate-trust-chain-contracts validate-channel-runtime-gates test-go validate-phase4 test-python-apps test-tools validate-fogstack validate-storage-suite trustops-art-runner-smoke validate-workroom-scope-d-adversarial devsecops-workroom-demo validate-proof-artifacts validate-evidence-cover-graph validate-adr-035-contracts validate-helper-causal-receipts validate-svc-substrate-source-control validate-systema-bridge validate-workroom-schemas validate-device-orchestration validate-mutation-evidence validate-semantic-governance validate-orggov-runtime-demo validate-cronjob-script-mirrors validate-schema-references
 .PHONY: engine-guards validate validate-repo validate-regis-acr-integration smoke-regis-acr-service validate-provable-ai-ops-exchange docs-check drift-check standards-check validate-argocd-source-sovereignty topology-check chronos-evidence-loop-readout-validate lattice-surfaces-check lattice-surface-ingestor-smoke lattice-studio-smoke grlplus-service-smoke grl-mesh-smoke sophos-reasoner-smoke entity-resolution-smoke validate-ops-fabric validate-search-academy-deploy validate-search-image-release validate-lampstand-lifecycle validate-zone-stack-audit policy-fabric-endpoint-client-smoke policy-fabric-guarded-workflow-smoke zone-router-publication-local-publish-smoke zone-router-publication-failure-evidence-smoke zone-router-publication-retry-state-smoke zone-router-publication-remote-broker-seam-smoke zone-router-publication-dead-letter-smoke validate-workroom-update-contract validate-professional-intelligence-manifest validate-wallguard-professional-workroom validate-wallguard-professional-workroom-runtime validate-svf-agent-contract validate-live-sociosphere-svf-contract validate-fogstack-svf-signadot-adapter-readiness validate-environment-validate-change-v2 validate-trust-chain-contracts validate-channel-runtime-gates test-go test-python-apps test-tools smoke smoke-health smoke-eval-fabric smoke-evidence-receipts smoke-evidence-console validate-phase3 lampstand-smoke validate-phase4 lampstand-vertical-slice-smoke lampstand-zone-smoke zone-router-publication-smoke zone-router-publication-enqueue-smoke semantic-bridge-zone-validation-smoke validate-fogstack validate-storage-suite trustops-art-runner-smoke validate-workspace-services test-workspace smoke-workspace workspace-up workspace-down workspace-logs workspace-build prometheus-local-demo validate-workroom-scope-d-adversarial devsecops-workroom-demo validate-proof-artifacts validate-evidence-cover-graph validate-adr-035-contracts validate-helper-causal-receipts validate-svc-substrate-source-control validate-systema-bridge validate-workroom-schemas validate-device-orchestration validate-mutation-evidence validate-fogstack-svf-p2-evidence-gates validate-repo-governance-contracts validate-semantic-governance validate-orggov-runtime-demo
 validate: validate-repo validate-regis-acr-integration validate-workspace-prophet-membrane-e2e validate-provable-ai-ops-exchange drift-check standards-check validate-argocd-source-sovereignty topology-check chronos-evidence-loop-readout-validate lattice-surfaces-check lattice-surface-ingestor-smoke lattice-studio-smoke grlplus-service-smoke grl-mesh-smoke sophos-reasoner-smoke entity-resolution-smoke validate-ops-fabric validate-search-academy-deploy validate-search-image-release validate-lampstand-lifecycle validate-zone-stack-audit policy-fabric-endpoint-client-smoke policy-fabric-guarded-workflow-smoke zone-router-publication-local-publish-smoke zone-router-publication-failure-evidence-smoke zone-router-publication-retry-state-smoke zone-router-publication-remote-broker-seam-smoke zone-router-publication-dead-letter-smoke validate-workroom-update-contract validate-professional-intelligence-manifest validate-wallguard-professional-workroom validate-wallguard-professional-workroom-runtime validate-svf-agent-contract validate-live-sociosphere-svf-contract validate-fogstack-svf-signadot-adapter-readiness validate-environment-validate-change-v2 validate-trust-chain-contracts validate-channel-runtime-gates test-go validate-phase4 test-python-apps test-tools validate-fogstack validate-storage-suite trustops-art-runner-smoke validate-workroom-scope-d-adversarial devsecops-workroom-demo validate-proof-artifacts validate-evidence-cover-graph validate-adr-035-contracts validate-helper-causal-receipts validate-svc-substrate-source-control validate-systema-bridge validate-workroom-schemas validate-device-orchestration validate-mutation-evidence validate-semantic-governance validate-orggov-runtime-demo
 
@@ -42,6 +42,13 @@ controls-census:
 # gate fails the build if any such copy drifts from its source — two scripts, one truth.
 validate-cronjob-script-mirrors:
 	python3 tools/verify_cronjob_script_mirrors.py
+
+# Referential-integrity gate for contracts/ + schemas/: every JSON Schema is valid and every
+# $ref resolves. Generalizes the sourceos-spec ref-gate (#277) to this repo's ~288 schemas; only
+# files declaring $schema/$id are checked (data/examples are skipped). Self-testing; make validate.
+validate-schema-references:
+	python3 -m pip install --user jsonschema >/dev/null 2>&1 || true
+	python3 tools/validate_schema_references.py
 # Sovereignty gate: every ArgoCD Application must pull from our own git or the sovereign
 # registry, not a public Helm CDN. Shrink-only ratchet — a NEW external source fails; the ~6
 # charts still on public CDNs are allowlisted and must be migrated to zot then deleted. #1343.

tools/tests/test_validate_schema_references.py

@@ -0,0 +1,58 @@
+"""The ref-gate must DISCRIMINATE: a dangling $ref fails, a resolving one passes, and data files
+are not mistaken for schemas. Tested on synthetic inputs so it never depends on the live tree."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "tools"))
+import validate_schema_references as v  # noqa: E402
+
+
+def test_is_schema_discriminates_data_from_schema():
+    assert v._is_schema({"$id": "x", "type": "object"}) is True
+    assert v._is_schema({"$schema": "..."}) is True
+    assert v._is_schema({"foo": "bar"}) is False           # an example / data file
+    assert v._is_schema(["not", "an", "object"]) is False
+
+
+def test_resolve_pointer_walks_defs_and_arrays():
+    doc = {"$defs": {"a": {"type": "string"}}, "allOf": [{"x": 1}]}
+    assert v.resolve_pointer(doc, "/$defs/a") is True
+    assert v.resolve_pointer(doc, "/allOf/0") is True
+    assert v.resolve_pointer(doc, "/$defs/missing") is False
+    assert v.resolve_pointer(doc, "/allOf/9") is False
+
+
+def test_resolve_ref_by_id_name_and_dangling():
+    good = {"$id": "https://x/Good.json", "$defs": {"a": {}}}
+    p = Path("/tmp/x.json").resolve()
+    kw = dict(by_path={p: good}, by_name={"Good.json": good}, by_id={good["$id"]: good})
+    assert v.resolve_ref("Good.json", from_path=p, **kw)[0] is True
+    assert v.resolve_ref(good["$id"], from_path=p, **kw)[0] is True
+    assert v.resolve_ref("Nope.json", from_path=p, **kw)[0] is False
+
+
+def test_external_metaschema_ref_is_not_a_false_positive():
+    # adversarial: a legit $ref to the standard meta-schema must NOT be flagged as dangling…
+    p = Path("/tmp/x.json").resolve()
+    kw = dict(by_path={}, by_name={}, by_id={})
+    assert v.resolve_ref("https://json-schema.org/draft/2020-12/schema", from_path=p, **kw)[0] is True
+    # …but an UNKNOWN external URL still fails (vendor it, or it's a typo — the gate stays strict)
+    assert v.resolve_ref("https://evil.example.com/schema.json", from_path=p, **kw)[0] is False
+
+
+def test_end_to_end_catches_a_dangling_ref(tmp_path, monkeypatch):
+    (tmp_path / "contracts").mkdir()
+    (tmp_path / "contracts" / "Good.json").write_text('{"$id":"g","$defs":{"a":{"type":"string"}}}')
+    (tmp_path / "contracts" / "Bad.json").write_text('{"$id":"b","properties":{"x":{"$ref":"#/$defs/nope"}}}')
+    (tmp_path / "contracts" / "example.json").write_text('{"just":"data"}')  # skipped, not a schema
+    monkeypatch.setattr(v, "ROOT", tmp_path)
+    findings, n, refs = v.check_all(tmp_path)
+    assert n == 2  # only the two schemas, not the data file
+    assert any("Bad.json" in name for name, _ in findings)
+
+
+def test_self_test_exit_code_is_zero(capsys):
+    assert v.main(["--self-test"]) == 0