diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a2e9a3..6da4f03 100644 --- a/CHANGELOG.md +++ b/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`) diff --git a/docs/contract-additions/2026-05-agent-machine-model-carry-contracts.md b/docs/contract-additions/2026-05-agent-machine-model-carry-contracts.md new file mode 100644 index 0000000..af32428 --- /dev/null +++ b/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. diff --git a/examples/agentmachinereceipt.json b/examples/agentmachinereceipt.json new file mode 100644 index 0000000..c04c403 --- /dev/null +++ b/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"] +} diff --git a/examples/inferenceprovider.json b/examples/inferenceprovider.json new file mode 100644 index 0000000..867162a --- /dev/null +++ b/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"] +} diff --git a/examples/modelresidency.json b/examples/modelresidency.json new file mode 100644 index 0000000..8844280 --- /dev/null +++ b/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"] +} diff --git a/examples/placementfact.json b/examples/placementfact.json new file mode 100644 index 0000000..5dda4a0 --- /dev/null +++ b/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"] +} diff --git a/examples/sourceosmodelcarryref.json b/examples/sourceosmodelcarryref.json new file mode 100644 index 0000000..d5cd5d7 --- /dev/null +++ b/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"] +} diff --git a/schemas/AgentMachineReceipt.json b/schemas/AgentMachineReceipt.json new file mode 100644 index 0000000..8bdcdc5 --- /dev/null +++ b/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:" }, + "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" } } + } +} diff --git a/schemas/InferenceProvider.json b/schemas/InferenceProvider.json new file mode 100644 index 0000000..1289a3a --- /dev/null +++ b/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:" }, + "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" } } + } +} diff --git a/schemas/ModelResidency.json b/schemas/ModelResidency.json new file mode 100644 index 0000000..b77657f --- /dev/null +++ b/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:" }, + "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" } } + } +} diff --git a/schemas/PlacementFact.json b/schemas/PlacementFact.json new file mode 100644 index 0000000..29f4d92 --- /dev/null +++ b/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:" }, + "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" } } + } +} diff --git a/schemas/SourceOSModelCarryRef.json b/schemas/SourceOSModelCarryRef.json new file mode 100644 index 0000000..9bdedb2 --- /dev/null +++ b/schemas/SourceOSModelCarryRef.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/SourceOSModelCarryRef.json", + "title": "SourceOSModelCarryRef", + "description": "Approved SourceOS on-device reference to a governed model or model-service profile that may be carried by a ReleaseSet or BootReleaseSet without embedding mutable model state.", + "type": "object", + "additionalProperties": false, + "required": ["id", "type", "specVersion", "modelRef", "governanceRef", "routerProfileRef", "carryPolicy", "cachePolicy", "mutableModelState"], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:model-carry-ref:", "description": "Stable URN identifier. Pattern: urn:srcos:model-carry-ref:" }, + "type": { "const": "SourceOSModelCarryRef", "description": "Discriminator constant — always \"SourceOSModelCarryRef\"." }, + "specVersion": { "type": "string", "description": "Spec version of this document, e.g. \"2.1.0\"." }, + "modelRef": { "type": "string", "description": "Governed model, adapter, or service reference approved by model-governance-ledger and consumable by model-router." }, + "governanceRef": { "type": "string", "description": "Reference to the model governance ledger release decision or factsheet record authorizing this carry reference." }, + "routerProfileRef": { "type": "string", "pattern": "^urn:srcos:model-router-profile:", "description": "Model-router profile URN that describes route constraints for this carried reference." }, + "releaseSetRefs": { "type": "array", "description": "Optional ReleaseSet or BootReleaseSet URNs allowed to carry this reference.", "items": { "type": "string", "pattern": "^urn:srcos:release-set:" } }, + "launchProfileRefs": { "type": "array", "description": "Optional SourceOS launch profile URNs for local service startup.", "items": { "type": "string" } }, + "fallbackRefs": { "type": "array", "description": "Fallback model carry references used when this route is unavailable or disallowed.", "items": { "type": "string", "pattern": "^urn:srcos:model-carry-ref:" } }, + "carryPolicy": { "type": "string", "enum": ["reference-only", "download-on-demand", "preload-reference", "disabled"], "description": "How SourceOS may carry or prepare the referenced model/service without embedding mutable model state." }, + "cachePolicy": { "type": "string", "enum": ["none", "metadata-only", "weights-cache-allowed", "kv-cache-allowed", "embedding-cache-allowed"], "description": "Highest cache behavior allowed for this reference under local policy." }, + "mutableModelState": { "type": "boolean", "const": false, "description": "Whether the OS image carries mutable model weights or adapters. Must remain false." }, + "evidenceRefs": { "type": "array", "description": "Evidence URNs or content hashes supporting approval, cache policy, and release binding.", "items": { "type": "string" } } + } +}