Add Agent Machine and model carry SourceOS projections

CHANGELOG.md

@@ -9,6 +9,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- Agent Machine / Model Carry schemas: `SourceOSModelCarryRef`, `InferenceProvider`, `ModelResidency`, `PlacementFact`, and `AgentMachineReceipt` with canonical examples and a contract-additions placement note.
 - NLBoot object schemas: `NLBootPlan`, `ArtifactCacheRecord`, `BootProofRecord`, `AppleSiliconAdapterEvidence` with canonical examples and validation (`tools/validate_nlboot_examples.py`)
 - Compression Commons: `CompressionEvaluation` schema and canonical example (`examples/compressionevaluation.json`)
 - Truth Plane: `TruthSurface` and `DeltaSurface` schemas + canonical examples (`examples/truth_surface.json`, `examples/delta_surface.json`)

docs/contract-additions/2026-05-agent-machine-model-carry-contracts.md

@@ -0,0 +1,50 @@
+# Agent Machine and Model Carry Contract Additions — May 2026
+
+Status: Draft additive contract family
+
+## Purpose
+
+This contract addition projects the Prophet Intelligence Foundry runtime path into SourceOS/SociOS typed contracts. It gives `SourceOS-Linux/agent-machine`, `SourceOS-Linux/sourceos-model-carry`, `SocioProphet/model-router`, `SocioProphet/agentplane`, and `SocioProphet/policy-fabric` a common schema vocabulary for local model references, inference provider capability, model residency, placement facts, and runtime receipts.
+
+## Added schemas
+
+| Schema | Purpose | URN prefix |
+| --- | --- | --- |
+| `SourceOSModelCarryRef` | Approved on-device reference to a governed model or model-service profile carried by SourceOS without embedding mutable model state. | `urn:srcos:model-carry-ref:` |
+| `InferenceProvider` | Backend-neutral local, clustered, or governed remote inference provider description. | `urn:srcos:inference-provider:` |
+| `ModelResidency` | Point-in-time evidence that a governed model reference is unavailable, cached, loaded, warm, pinned, evictable, or failed on an Agent Machine. | `urn:srcos:model-residency:` |
+| `PlacementFact` | Machine-local scheduling and policy fact for model, agent, cache, isolation, and runtime placement decisions. | `urn:srcos:placement-fact:` |
+| `AgentMachineReceipt` | Runtime evidence emitted by Agent Machine after probing, placement, execution, cache reuse, model load/unload, or policy-mediated side-effect handling. | `urn:srcos:agent-machine-receipt:` |
+
+## Boundary rules
+
+1. `SourceOSModelCarryRef` is reference-only governance metadata. It must not embed mutable model weights or adapters into SourceOS images.
+2. `InferenceProvider` describes serving capability. It must not authorize use by itself.
+3. `ModelResidency` is observed state. It is not a release decision and not a routing policy.
+4. `PlacementFact` informs scheduling and policy. It must not replace PolicyDecision, CapabilityToken, or AgentPlane run evidence.
+5. `AgentMachineReceipt` proves runtime events. It must not replace AgentPlane RunCapsule, model-governance-ledger release evidence, or Sociosphere workspace state.
+
+## Integration path
+
+```text
+functional-model-surfaces
+→ model-governance-ledger
+→ model-router
+→ sourceos-model-carry
+→ agent-machine
+→ agentplane
+→ sociosphere / SourceOS operator surfaces
+```
+
+## Validation posture
+
+Each schema has a conforming lowercase example under `examples/`. The examples are intentionally narrow and represent an M2 Asahi/local llama.cpp-style path without requiring a real model download, model execution, network call, or runtime mutation.
+
+## Non-goals
+
+- No model weights.
+- No training data.
+- No runtime implementation.
+- No new boot behavior.
+- No authorization grant beyond existing `PolicyDecision` and `CapabilityToken` concepts.
+- No replacement for AgentPlane run capsules or model-governance-ledger release decisions.

examples/agentmachinereceipt.json

@@ -0,0 +1,22 @@
+{
+  "id": "urn:srcos:agent-machine-receipt:m2-asahi-observation-20260504t170000z",
+  "type": "AgentMachineReceipt",
+  "specVersion": "2.1.0",
+  "machineRef": "urn:srcos:agent-machine:m2-asahi-local",
+  "receiptClass": "probe",
+  "issuedAt": "2026-05-04T17:00:10Z",
+  "taskRef": "urn:prophet:run-capsule:local-observation-20260504",
+  "agentPodRef": "urn:srcos:agent-pod:local-observation-0001",
+  "placementFactRefs": ["urn:srcos:placement-fact:m2-asahi-local-20260504t170000z"],
+  "modelResidencyRefs": ["urn:srcos:model-residency:m2-local-llama32-3b-20260504t170000z"],
+  "inferenceProviderRefs": ["urn:srcos:inference-provider:llama-cpp-cpu-arm64-local"],
+  "policyDecisionRef": "urn:srcos:decision:runtime-observation-20260504",
+  "verdict": "observed",
+  "metrics": {
+    "durationMs": 142.0,
+    "providerCount": 1,
+    "residentModelCount": 1
+  },
+  "evidenceHash": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
+  "evidenceRefs": ["sha256:5555555555555555555555555555555555555555555555555555555555555555"]
+}

examples/inferenceprovider.json

@@ -0,0 +1,13 @@
+{
+  "id": "urn:srcos:inference-provider:llama-cpp-cpu-arm64-local",
+  "type": "InferenceProvider",
+  "specVersion": "2.1.0",
+  "providerClass": "llama.cpp",
+  "endpointMode": "local-http",
+  "executionProfile": "cpu-arm64",
+  "trustPosture": "local-sandboxed",
+  "supportedModalities": ["text", "code", "embedding"],
+  "openAICompatible": true,
+  "requiresNetwork": false,
+  "evidenceRefs": ["sha256:1111111111111111111111111111111111111111111111111111111111111111"]
+}

examples/modelresidency.json

@@ -0,0 +1,14 @@
+{
+  "id": "urn:srcos:model-residency:m2-local-llama32-3b-20260504t170000z",
+  "type": "ModelResidency",
+  "specVersion": "2.1.0",
+  "machineRef": "urn:srcos:agent-machine:m2-asahi-local",
+  "modelCarryRef": "urn:srcos:model-carry-ref:local-llama32-3b-office-assist",
+  "providerRef": "urn:srcos:inference-provider:llama-cpp-cpu-arm64-local",
+  "residencyState": "cached",
+  "quantization": "q4_k_m",
+  "bytesOnDisk": 2147483648,
+  "cacheTier": "nvme",
+  "observedAt": "2026-05-04T17:00:00Z",
+  "evidenceRefs": ["sha256:2222222222222222222222222222222222222222222222222222222222222222"]
+}

examples/placementfact.json

@@ -0,0 +1,23 @@
+{
+  "id": "urn:srcos:placement-fact:m2-asahi-local-20260504t170000z",
+  "type": "PlacementFact",
+  "specVersion": "2.1.0",
+  "machineRef": "urn:srcos:agent-machine:m2-asahi-local",
+  "observedAt": "2026-05-04T17:00:00Z",
+  "hardware": {
+    "arch": "aarch64",
+    "accelerators": ["cpu", "vulkan-probe"],
+    "memoryBytes": 25769803776,
+    "storageBytesAvailable": 107374182400
+  },
+  "isolation": {
+    "runtime": "rootless-podman",
+    "networkDefault": "policy-gated",
+    "filesystemDefault": "workspace-scoped-rw"
+  },
+  "trustPosture": "sandboxed-local",
+  "modelResidencyRefs": ["urn:srcos:model-residency:m2-local-llama32-3b-20260504t170000z"],
+  "providerRefs": ["urn:srcos:inference-provider:llama-cpp-cpu-arm64-local"],
+  "cacheNotes": ["NVMe model cache available; KV cache reuse requires identity and policy match."],
+  "evidenceRefs": ["sha256:3333333333333333333333333333333333333333333333333333333333333333"]
+}

examples/sourceosmodelcarryref.json

@@ -0,0 +1,15 @@
+{
+  "id": "urn:srcos:model-carry-ref:local-llama32-3b-office-assist",
+  "type": "SourceOSModelCarryRef",
+  "specVersion": "2.1.0",
+  "modelRef": "urn:prophet:model:llama32-3b-local-office-assist",
+  "governanceRef": "urn:prophet:model-release-decision:local-llama32-3b-office-assist-20260504",
+  "routerProfileRef": "urn:srcos:model-router-profile:local-first-office-assist",
+  "releaseSetRefs": ["urn:srcos:release-set:sourceos-workstation-m2-20260504"],
+  "launchProfileRefs": ["urn:srcos:model-launch-profile:llama-cpp-local-office-assist"],
+  "fallbackRefs": [],
+  "carryPolicy": "download-on-demand",
+  "cachePolicy": "weights-cache-allowed",
+  "mutableModelState": false,
+  "evidenceRefs": ["sha256:2e7f1c7f0a6a4bbd9ef000000000000000000000000000000000000000000"]
+}

schemas/AgentMachineReceipt.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/AgentMachineReceipt.json",
+  "title": "AgentMachineReceipt",
+  "description": "Runtime evidence emitted by Agent Machine after probing, placement, execution, cache reuse, model load/unload, or policy-mediated side-effect handling.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "machineRef", "receiptClass", "issuedAt", "placementFactRefs", "policyDecisionRef", "verdict"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:agent-machine-receipt:", "description": "Stable URN identifier. Pattern: urn:srcos:agent-machine-receipt:<local-id>" },
+    "type": { "const": "AgentMachineReceipt", "description": "Discriminator constant — always \"AgentMachineReceipt\"." },
+    "specVersion": { "type": "string", "description": "Spec version of this document, e.g. \"2.1.0\"." },
+    "machineRef": { "type": "string", "pattern": "^urn:srcos:agent-machine:", "description": "Agent Machine URN that emitted the receipt." },
+    "receiptClass": { "type": "string", "enum": ["probe", "placement", "execution", "cache-reuse", "model-load", "model-unload", "side-effect"], "description": "Class of runtime event this receipt records." },
+    "issuedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the receipt was issued." },
+    "taskRef": { "type": ["string", "null"], "description": "Optional AgentPlane task, run, or work item reference associated with this receipt." },
+    "agentPodRef": { "type": ["string", "null"], "pattern": "^urn:srcos:agent-pod:", "description": "Optional AgentPod URN associated with the runtime placement." },
+    "placementFactRefs": { "type": "array", "minItems": 1, "description": "PlacementFact URNs used for this receipt.", "items": { "type": "string", "pattern": "^urn:srcos:placement-fact:" } },
+    "modelResidencyRefs": { "type": "array", "description": "ModelResidency URNs observed or changed during this receipt.", "items": { "type": "string", "pattern": "^urn:srcos:model-residency:" } },
+    "inferenceProviderRefs": { "type": "array", "description": "InferenceProvider URNs used or probed during this receipt.", "items": { "type": "string", "pattern": "^urn:srcos:inference-provider:" } },
+    "policyDecisionRef": { "type": "string", "pattern": "^urn:srcos:decision:", "description": "PolicyDecision URN authorizing, denying, or constraining this runtime action." },
+    "verdict": { "type": "string", "enum": ["allowed", "denied", "deferred", "failed", "observed"], "description": "Receipt outcome." },
+    "metrics": { "type": "object", "description": "Optional runtime metrics captured by the receipt.", "additionalProperties": { "type": ["string", "number", "integer", "boolean", "null"] } },
+    "evidenceHash": { "type": "string", "pattern": "^sha256:[a-fA-F0-9]{64}$", "description": "Hash of the canonical receipt evidence payload or bundle." },
+    "evidenceRefs": { "type": "array", "description": "Additional evidence URNs or hashes for logs, probes, run capsules, and artifacts.", "items": { "type": "string" } }
+  }
+}

schemas/InferenceProvider.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/InferenceProvider.json",
+  "title": "InferenceProvider",
+  "description": "Backend-neutral description of a local, clustered, or governed remote inference provider that Agent Machine and model-router may reason about.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "providerClass", "endpointMode", "executionProfile", "trustPosture", "supportedModalities"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:inference-provider:", "description": "Stable URN identifier. Pattern: urn:srcos:inference-provider:<local-id>" },
+    "type": { "const": "InferenceProvider", "description": "Discriminator constant — always \"InferenceProvider\"." },
+    "specVersion": { "type": "string", "description": "Spec version of this document, e.g. \"2.1.0\"." },
+    "providerClass": { "type": "string", "enum": ["llama.cpp", "vllm", "sglang", "ollama-compatible", "openai-compatible", "mlx-compatible", "remote-governed", "custom"], "description": "Provider implementation family or compatibility class." },
+    "endpointMode": { "type": "string", "enum": ["local-process", "local-http", "unix-socket", "kubernetes-service", "remote-http", "stdio"], "description": "How clients communicate with the provider." },
+    "executionProfile": { "type": "string", "description": "Runtime profile such as cpu-arm64, vulkan, cuda, hip, metal-compatible, or remote-governed." },
+    "trustPosture": { "type": "string", "enum": ["local-trusted", "local-sandboxed", "cluster-governed", "remote-governed", "untrusted"], "description": "Trust posture used by Policy Fabric and Agent Machine admission." },
+    "supportedModalities": { "type": "array", "minItems": 1, "description": "Modalities the provider can serve.", "items": { "type": "string", "enum": ["text", "code", "embedding", "reranking", "vision", "audio", "video", "multimodal", "tool-calling"] } },
+    "openAICompatible": { "type": "boolean", "description": "Whether the provider exposes an OpenAI-compatible API surface." },
+    "requiresNetwork": { "type": "boolean", "description": "Whether the provider requires network egress beyond loopback/local IPC." },
+    "evidenceRefs": { "type": "array", "description": "Evidence URNs or hashes for provider validation, binary provenance, and compatibility testing.", "items": { "type": "string" } }
+  }
+}

schemas/ModelResidency.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ModelResidency.json",
+  "title": "ModelResidency",
+  "description": "Point-in-time evidence that a governed model reference is available, loaded, warm, pinned, evictable, or unavailable on an Agent Machine.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "machineRef", "modelCarryRef", "providerRef", "residencyState", "observedAt"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:model-residency:", "description": "Stable URN identifier. Pattern: urn:srcos:model-residency:<local-id>" },
+    "type": { "const": "ModelResidency", "description": "Discriminator constant — always \"ModelResidency\"." },
+    "specVersion": { "type": "string", "description": "Spec version of this document, e.g. \"2.1.0\"." },
+    "machineRef": { "type": "string", "pattern": "^urn:srcos:agent-machine:", "description": "Agent Machine URN where residency was observed." },
+    "modelCarryRef": { "type": "string", "pattern": "^urn:srcos:model-carry-ref:", "description": "SourceOSModelCarryRef URN for the governed model/service reference." },
+    "providerRef": { "type": "string", "pattern": "^urn:srcos:inference-provider:", "description": "InferenceProvider URN serving or expected to serve the model." },
+    "residencyState": { "type": "string", "enum": ["unavailable", "downloadable", "cached", "loading", "loaded-cold", "loaded-warm", "pinned", "evictable", "failed"], "description": "Observed model residency state." },
+    "quantization": { "type": ["string", "null"], "description": "Quantization or precision label when known, such as q4_k_m, int8, fp16, or null." },
+    "bytesOnDisk": { "type": ["integer", "null"], "minimum": 0, "description": "Observed model bytes on local storage, or null when unknown." },
+    "cacheTier": { "type": ["string", "null"], "enum": ["ram", "nvme", "object-store", "network-cache", "none", null], "description": "Primary cache tier currently holding the model or null when unknown." },
+    "observedAt": { "type": "string", "format": "date-time", "description": "Timestamp when residency was observed." },
+    "evidenceRefs": { "type": "array", "description": "Evidence URNs or content hashes for probe output, checksums, and provider state.", "items": { "type": "string" } }
+  }
+}

schemas/PlacementFact.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/PlacementFact.json",
+  "title": "PlacementFact",
+  "description": "Machine-local scheduling and policy fact emitted by Agent Machine for model, agent, cache, isolation, and runtime placement decisions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "machineRef", "observedAt", "hardware", "isolation", "trustPosture", "modelResidencyRefs"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:placement-fact:", "description": "Stable URN identifier. Pattern: urn:srcos:placement-fact:<local-id>" },
+    "type": { "const": "PlacementFact", "description": "Discriminator constant — always \"PlacementFact\"." },
+    "specVersion": { "type": "string", "description": "Spec version of this document, e.g. \"2.1.0\"." },
+    "machineRef": { "type": "string", "pattern": "^urn:srcos:agent-machine:", "description": "Agent Machine URN that emitted the placement fact." },
+    "observedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the placement fact was observed." },
+    "hardware": { "type": "object", "description": "Hardware and runtime capacity summary relevant to scheduling.", "additionalProperties": false, "required": ["arch", "accelerators", "memoryBytes"], "properties": { "arch": { "type": "string", "description": "Host architecture such as aarch64, x86_64, or riscv64." }, "accelerators": { "type": "array", "description": "Detected accelerators or acceleration APIs available to runtime providers.", "items": { "type": "string" } }, "memoryBytes": { "type": "integer", "minimum": 0, "description": "Approximate host memory available for placement reasoning." }, "storageBytesAvailable": { "type": ["integer", "null"], "minimum": 0, "description": "Approximate local storage bytes available for cache/model/scratch placement, or null when unknown." } } },
+    "isolation": { "type": "object", "description": "Isolation posture available for the workload.", "additionalProperties": false, "required": ["runtime", "networkDefault", "filesystemDefault"], "properties": { "runtime": { "type": "string", "enum": ["process", "bubblewrap", "rootless-podman", "toolbox", "systemd", "quadlet", "kubernetes-pod", "vm"], "description": "Primary runtime isolation mechanism." }, "networkDefault": { "type": "string", "enum": ["deny", "loopback-only", "policy-gated", "allow"], "description": "Default network posture for workloads on this placement surface." }, "filesystemDefault": { "type": "string", "enum": ["read-only", "workspace-scoped-rw", "policy-gated-rw", "host-rw"], "description": "Default filesystem posture for workloads on this placement surface." } } },
+    "trustPosture": { "type": "string", "enum": ["trusted-local", "sandboxed-local", "cluster-governed", "remote-governed", "untrusted"], "description": "Trust posture attached to this placement fact." },
+    "modelResidencyRefs": { "type": "array", "description": "ModelResidency URNs observed on this machine.", "items": { "type": "string", "pattern": "^urn:srcos:model-residency:" } },
+    "providerRefs": { "type": "array", "description": "InferenceProvider URNs available on this machine.", "items": { "type": "string", "pattern": "^urn:srcos:inference-provider:" } },
+    "cacheNotes": { "type": "array", "description": "Human-readable cache locality or eviction notes.", "items": { "type": "string" } },
+    "evidenceRefs": { "type": "array", "description": "Evidence URNs or hashes supporting this placement fact.", "items": { "type": "string" } }
+  }
+}