spec: image-trust contracts — measured, not asserted, for OS and agent images

CHANGELOG.md

@@ -9,6 +9,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- Image-trust contracts — the Assay's measured-not-asserted discipline applied to images, for both OS and agents: `ImageTrustReport` (per-dimension trust checks — reproducibility, attestation_verify, sbom_completeness, signature_verify, measured_boot, provenance_depth — each carrying a `Measurement` via `$ref`, plus a render-time `projectedTrust` ok/sad/bad verdict; unifies OS and agent images through `subjectKind`) and `AgentImage` (agent runtime-artifact identity + provenance parallel to `OSImage`, distinct from process-level `AgentPassport`). `ImagePromotionGate` now requires a `trustReportRef` when `decision: approved` (non-breaking if/then), and the new `validate-image-trust-examples` target enforces projection soundness plus the cross-document rule that an approval must reference a report projecting `ok` — closing, for images, the self-assertable-approval gap the Assay hardening closed for verifiers. Reuses `Measurement`'s gate-eligibility invariants for free via `$ref` (a declared/assumed check cannot reach `ok`). All invariants verified biting. See `schemas/image-trust.README.md`.
 - Assay fleet-tier contracts (cloud-mesh): `AssayRollup` (fleet/cohort aggregate of `ReasoningAssay` verdicts over a window — ok/sad/bad distribution, calibration-drift view of which `AssayStandard` versions are live across the fleet, unassayed-reason breakdown) and `AssayStandardRollout` (canary→widen/halt promotion of a new `AssayStandard` version across cohorts, gated on an observed `AssayRollup`; rides the release-bundle + lifecycle machinery). New `validate-assay-fleet-examples` target enforces aggregation/rollout soundness (distribution sums, drift-flag agreement, rolloutPct vs node share, decision/phase consistency, and no-promotion-by-hope), all verified biting. This is the boundary between prophet-mesh single-user-local (node self-view, no fleet dashboards, structural) and cloud-mesh (rollup + rollout + dashboards). See `schemas/assay-fleet.README.md`.
 - Trained DataClass classifiers — adversarial hardening (follow-up to #264): stronger fixture where BOTH monotone features (token_magnitude, decimal_places) genuinely drive the label so the monotone constraint actually BINDS (was vacuous — decimal_places held constant); standardiser fit on the TRAIN split only (no test leakage); ModelManifest named honestly `monotone-logistic` (a realisation of the declared tf-lattice-wide-and-deep contract, not a full lattice). Validator now checks BOTH per-class heads monotone AND asserts the constraint binds (non-vacuous), and compares reproduced accuracy at the stored 4-decimal precision (fixes a latent tolerance bug the trivial 1.0-accuracy fixture had masked). 8 teeth.
 - Trained DataClass classifiers v0.1 — specified→trained→registered→reproduced (closes the program's last owed thread): `tools/train_dataclass_classifiers.py` trains real per-class LOGISTIC (one-vs-rest) + per-table SOFTMAX heads, MONOTONE-constrained in `monotonicFeatures` (weight >=0 projection = TF-Lattice essence), deterministically; emits trained weights + a conformant `ModelManifest` (id=DataClass modelRef) + train/eval `RunRecord`s (ids=runRef/evalRunRef) so the previously-dangling DataClass classifier references now RESOLVE. `validate-trained-classifiers` (recompute-don't-trust): digest matches weight bytes; eval accuracy REPRODUCED from weights+fixture (inflated claim fails); model verified genuinely monotone (perturb up → score never drops); refs resolve; artifacts schema-conform. Teeth-verified (tampered weights refused). Uses numpy.

Makefile

@@ -1,12 +1,16 @@
-.PHONY: validate validate-resource-contract validate-measurement validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-ingestion-pipeline-examples validate-data-acquisition-examples validate-glossary-alignment-examples validate-data-class-examples validate-table-keys validate-dag-loop validate-vocab-currency-loop vocab-currency-dogfood validate-glossary-promotion validate-agreement validate-stopword-analysis stopword-analysis-live validate-kgram-differential validate-learned-dictionary train-dataclass-classifiers validate-assay-fleet-examples validate-schema-references
+.PHONY: validate validate-resource-contract validate-measurement validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-ingestion-pipeline-examples validate-data-acquisition-examples validate-glossary-alignment-examples validate-data-class-examples validate-table-keys validate-dag-loop validate-vocab-currency-loop vocab-currency-dogfood validate-glossary-promotion validate-agreement validate-stopword-analysis stopword-analysis-live validate-kgram-differential validate-learned-dictionary train-dataclass-classifiers validate-assay-fleet-examples validate-image-trust-examples validate-schema-references
 
-validate: validate-data-class-examples validate-glossary-alignment-examples validate-data-acquisition-examples validate-ingestion-pipeline-examples validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-resource-contract validate-table-keys validate-dag-loop validate-vocab-currency-loop validate-glossary-promotion validate-agreement validate-stopword-analysis validate-kgram-differential validate-learned-dictionary validate-trained-classifiers validate-multiverseal-twin-examples validate-assay-fleet-examples validate-schema-references
+validate: validate-data-class-examples validate-glossary-alignment-examples validate-data-acquisition-examples validate-ingestion-pipeline-examples validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples validate-knowledge-nugget-examples validate-semantic-action-examples validate-epistemic-kernel-examples validate-ab-update-examples validate-device-service-examples validate-duplicate-schema-ids validate-value-type validate-source-locator validate-sourceos-repo-manifest validate-mesh-action-registry validate-lawful-dispatch-receipt validate-architectural-building-block validate-agent-passport-examples validate-seam-definition-examples validate-agent-system-vocabulary validate-genesis-inception-examples validate-measurement validate-world-model-examples validate-eval-item-examples validate-resource-contract validate-table-keys validate-dag-loop validate-vocab-currency-loop validate-glossary-promotion validate-agreement validate-stopword-analysis validate-kgram-differential validate-learned-dictionary validate-trained-classifiers validate-multiverseal-twin-examples validate-assay-fleet-examples validate-image-trust-examples validate-schema-references
 	@echo "OK: validate"
 
 validate-assay-fleet-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_assay_fleet_examples.py
 
+validate-image-trust-examples:
+	python3 -m pip install --user jsonschema referencing >/dev/null
+	python3 tools/validate_image_trust_examples.py
+
 # General referential-integrity gate: every schema is a valid JSON Schema and every
 # $ref resolves. The per-example validators only exercise schemas that ship examples;
 # this catches a dangling/renamed/typo'd $ref in ANY of the 300+ schemas — a

examples/agent_image.json

@@ -0,0 +1,19 @@
+{
+  "id": "urn:srcos:agent-image:michael-agent",
+  "type": "AgentImage",
+  "specVersion": "2.0.0",
+  "agentClass": "intelligence_automation",
+  "artifact": "oci",
+  "architecture": "aarch64",
+  "digest": "sha256:1f2e3d4c5b6a70819f2e3d4c5b6a70811f2e3d4c5b6a70819f2e3d4c5b6a7081",
+  "runtime": {
+    "language": "python",
+    "entrypoint": "prophet_mesh.cli:main"
+  },
+  "provenance": {
+    "statementRef": "urn:srcos:attestation:michael-agent-v1",
+    "slsaPredicateRef": "urn:srcos:slsa:michael-agent-v1",
+    "sbomRef": "urn:srcos:sbom:michael-agent-v1",
+    "signatureRef": "urn:srcos:signature:michael-agent-v1"
+  }
+}

examples/image_promotion_gate.json

@@ -14,6 +14,7 @@
     "scenario-pass",
     "promotion-evidence-complete"
   ],
+  "trustReportRef": "urn:srcos:image-trust:sourceos-workstation-v0",
   "decision": "approved",
   "reasonCodes": [
     "all-required-checks-passed"

examples/image_trust_report.agent.json

@@ -0,0 +1,43 @@
+{
+  "id": "urn:srcos:image-trust:michael-agent-v1",
+  "type": "ImageTrustReport",
+  "specVersion": "2.0.0",
+  "subjectRef": "urn:srcos:agent-image:michael-agent",
+  "subjectKind": "agent-image",
+  "checks": [
+    {
+      "dimension": "reproducibility",
+      "measurement": {
+        "schemaVersion": "0.1.0", "kind": "Measurement",
+        "label": "rebuild digest matches",
+        "value": true, "source": "measured", "instrument": "srcos-rebuild 2.1 (hermetic)", "gateEligible": true
+      },
+      "passed": true
+    },
+    {
+      "dimension": "signature_verify",
+      "measurement": {
+        "schemaVersion": "0.1.0", "kind": "Measurement",
+        "label": "artifact signature verified",
+        "value": true, "source": "measured", "instrument": "cosign verify 2.4", "gateEligible": true
+      },
+      "passed": true
+    },
+    {
+      "dimension": "sbom_completeness",
+      "measurement": {
+        "schemaVersion": "0.1.0", "kind": "Measurement",
+        "label": "SBOM coverage",
+        "value": "vendor-attested-complete",
+        "source": "declared",
+        "gateEligible": false,
+        "note": "SBOM completeness was asserted by the build manifest, not measured by an SBOM scanner. A declared measurement is gate-ineligible by shape, so the agent image cannot reach 'ok' on trust until a real scan is run."
+      },
+      "passed": true
+    }
+  ],
+  "projectedTrust": "sad",
+  "unmetReason": "sbom_completeness:declared",
+  "measuredAt": "2026-07-05T00:00:00Z",
+  "evaluator": "srcos-image-trust-harness"
+}

examples/image_trust_report.os.json

@@ -0,0 +1,51 @@
+{
+  "id": "urn:srcos:image-trust:sourceos-workstation-v0",
+  "type": "ImageTrustReport",
+  "specVersion": "2.0.0",
+  "subjectRef": "urn:srcos:osimage:so1-workstation",
+  "subjectKind": "os-image",
+  "checks": [
+    {
+      "dimension": "reproducibility",
+      "measurement": {
+        "schemaVersion": "0.1.0", "kind": "Measurement",
+        "label": "hermetic rebuild digest matches the published digest",
+        "value": true, "source": "measured", "instrument": "srcos-rebuild 2.1 (hermetic, pinned toolchain)", "gateEligible": true
+      },
+      "passed": true,
+      "evidenceRef": "urn:srcos:slsa:sourceos-workstation-v0"
+    },
+    {
+      "dimension": "attestation_verify",
+      "measurement": {
+        "schemaVersion": "0.1.0", "kind": "Measurement",
+        "label": "in-toto/SLSA statement verified against the release key",
+        "value": true, "source": "measured", "instrument": "cosign verify-attestation 2.4", "gateEligible": true
+      },
+      "passed": true,
+      "evidenceRef": "urn:srcos:attestation:sourceos-workstation-v0"
+    },
+    {
+      "dimension": "signature_verify",
+      "measurement": {
+        "schemaVersion": "0.1.0", "kind": "Measurement",
+        "label": "image signature verified",
+        "value": true, "source": "measured", "instrument": "cosign verify 2.4", "gateEligible": true
+      },
+      "passed": true
+    },
+    {
+      "dimension": "measured_boot",
+      "measurement": {
+        "schemaVersion": "0.1.0", "kind": "Measurement",
+        "label": "PCR7 matches the expected measured-boot value",
+        "value": true, "source": "measured", "instrument": "tpm2_quote + BootProofRecord cross-check", "gateEligible": true
+      },
+      "passed": true,
+      "evidenceRef": "urn:srcos:boot-proof:so1-workstation-2026-04-15"
+    }
+  ],
+  "projectedTrust": "ok",
+  "measuredAt": "2026-07-05T00:00:00Z",
+  "evaluator": "srcos-image-trust-harness"
+}

schemas/AgentImage.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/AgentImage.json",
+  "title": "AgentImage",
+  "description": "Immutable identity and provenance contract for an agent RUNTIME ARTIFACT — the deployable agent image/bundle — parallel to OSImage for the OS substrate. Distinct from AgentPassport: AgentPassport classifies a running process on a host; AgentImage identifies the built artifact that process was launched from, so an agent image can be measured for trust (via ImageTrustReport) exactly the way an OS image is. Shares OSImage's provenance shape deliberately, so one ImageTrustReport applies to both.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "agentClass", "artifact", "architecture", "digest", "provenance"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:agent-image:[a-z0-9][a-z0-9._-]*$", "description": "Stable URN. Pattern: urn:srcos:agent-image:<local-id>." },
+    "type": { "const": "AgentImage" },
+    "specVersion": { "type": "string" },
+    "agentClass": {
+      "enum": ["system_core", "intelligence_automation", "app_helper", "legacy_bridge", "third_party"],
+      "description": "The five-class agent model shared with AgentPassport — the class the built artifact is authorized to run as."
+    },
+    "artifact": {
+      "enum": ["oci", "wheel", "npm", "binary", "bundle"],
+      "description": "Rendered artifact form for the agent image."
+    },
+    "architecture": {
+      "enum": ["x86_64", "aarch64", "any"],
+      "description": "Target architecture ('any' for a pure-interpreted bundle)."
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$",
+      "description": "Content digest of the built agent artifact — the identity a reproducibility check re-derives."
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional declared runtime binding.",
+      "properties": {
+        "language": { "type": "string", "description": "e.g. python, node, rust." },
+        "entrypoint": { "type": "string", "description": "The invoked entrypoint." }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "description": "Attestation and provenance references for the agent artifact — same shape as OSImage.provenance so both images are measured by one ImageTrustReport.",
+      "additionalProperties": false,
+      "required": ["statementRef", "slsaPredicateRef"],
+      "properties": {
+        "statementRef": { "type": "string", "pattern": "^urn:srcos:attestation:[a-z0-9][a-z0-9._:-]*$", "description": "URN reference to the in-toto or equivalent attestation statement." },
+        "slsaPredicateRef": { "type": "string", "pattern": "^urn:srcos:slsa:[a-z0-9][a-z0-9._:-]*$", "description": "URN reference to the SLSA provenance predicate artifact." },
+        "sbomRef": { "type": "string", "description": "Optional URN or URL reference to the SBOM for this agent image." },
+        "signatureRef": { "type": "string", "description": "Optional URN or URL reference to the signature verification material." }
+      }
+    }
+  }
+}