Skip to content

Commit 3932bae

Browse files
mdhellermdheller
authored
Add Agent Machine and model carry SourceOS projections
Add additive SourceOS/SociOS typed-contract projections for the Prophet Intelligence Foundry runtime path: SourceOSModelCarryRef, InferenceProvider, ModelResidency, PlacementFact, and AgentMachineReceipt. Includes conforming examples, contract-additions placement note, and changelog entry. Validation: - Locally validated all five schemas with jsonschema.Draft202012Validator.check_schema. - Locally validated all five examples against their schemas. - Confirmed PR mergeable with no status checks returned by connector.
1 parent 6fe198f commit 3932bae

12 files changed

Lines changed: 257 additions & 0 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
99
## [Unreleased]
1010

1111
### Added
12+
- Agent Machine / Model Carry schemas: `SourceOSModelCarryRef`, `InferenceProvider`, `ModelResidency`, `PlacementFact`, and `AgentMachineReceipt` with canonical examples and a contract-additions placement note.
1213
- NLBoot object schemas: `NLBootPlan`, `ArtifactCacheRecord`, `BootProofRecord`, `AppleSiliconAdapterEvidence` with canonical examples and validation (`tools/validate_nlboot_examples.py`)
1314
- Compression Commons: `CompressionEvaluation` schema and canonical example (`examples/compressionevaluation.json`)
1415
- 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‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Agent Machine and Model Carry Contract Additions — May 2026
2+
3+
Status: Draft additive contract family
4+
5+
## Purpose
6+
7+
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.
8+
9+
## Added schemas
10+
11+
| Schema | Purpose | URN prefix |
12+
| --- | --- | --- |
13+
| `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:` |
14+
| `InferenceProvider` | Backend-neutral local, clustered, or governed remote inference provider description. | `urn:srcos:inference-provider:` |
15+
| `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:` |
16+
| `PlacementFact` | Machine-local scheduling and policy fact for model, agent, cache, isolation, and runtime placement decisions. | `urn:srcos:placement-fact:` |
17+
| `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:` |
18+
19+
## Boundary rules
20+
21+
1. `SourceOSModelCarryRef` is reference-only governance metadata. It must not embed mutable model weights or adapters into SourceOS images.
22+
2. `InferenceProvider` describes serving capability. It must not authorize use by itself.
23+
3. `ModelResidency` is observed state. It is not a release decision and not a routing policy.
24+
4. `PlacementFact` informs scheduling and policy. It must not replace PolicyDecision, CapabilityToken, or AgentPlane run evidence.
25+
5. `AgentMachineReceipt` proves runtime events. It must not replace AgentPlane RunCapsule, model-governance-ledger release evidence, or Sociosphere workspace state.
26+
27+
## Integration path
28+
29+
```text
30+
functional-model-surfaces
31+
→ model-governance-ledger
32+
→ model-router
33+
→ sourceos-model-carry
34+
→ agent-machine
35+
→ agentplane
36+
→ sociosphere / SourceOS operator surfaces
37+
```
38+
39+
## Validation posture
40+
41+
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.
42+
43+
## Non-goals
44+
45+
- No model weights.
46+
- No training data.
47+
- No runtime implementation.
48+
- No new boot behavior.
49+
- No authorization grant beyond existing `PolicyDecision` and `CapabilityToken` concepts.
50+
- No replacement for AgentPlane run capsules or model-governance-ledger release decisions.

‎examples/agentmachinereceipt.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"id": "urn:srcos:agent-machine-receipt:m2-asahi-observation-20260504t170000z",
3+
"type": "AgentMachineReceipt",
4+
"specVersion": "2.1.0",
5+
"machineRef": "urn:srcos:agent-machine:m2-asahi-local",
6+
"receiptClass": "probe",
7+
"issuedAt": "2026-05-04T17:00:10Z",
8+
"taskRef": "urn:prophet:run-capsule:local-observation-20260504",
9+
"agentPodRef": "urn:srcos:agent-pod:local-observation-0001",
10+
"placementFactRefs": ["urn:srcos:placement-fact:m2-asahi-local-20260504t170000z"],
11+
"modelResidencyRefs": ["urn:srcos:model-residency:m2-local-llama32-3b-20260504t170000z"],
12+
"inferenceProviderRefs": ["urn:srcos:inference-provider:llama-cpp-cpu-arm64-local"],
13+
"policyDecisionRef": "urn:srcos:decision:runtime-observation-20260504",
14+
"verdict": "observed",
15+
"metrics": {
16+
"durationMs": 142.0,
17+
"providerCount": 1,
18+
"residentModelCount": 1
19+
},
20+
"evidenceHash": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
21+
"evidenceRefs": ["sha256:5555555555555555555555555555555555555555555555555555555555555555"]
22+
}

‎examples/inferenceprovider.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"id": "urn:srcos:inference-provider:llama-cpp-cpu-arm64-local",
3+
"type": "InferenceProvider",
4+
"specVersion": "2.1.0",
5+
"providerClass": "llama.cpp",
6+
"endpointMode": "local-http",
7+
"executionProfile": "cpu-arm64",
8+
"trustPosture": "local-sandboxed",
9+
"supportedModalities": ["text", "code", "embedding"],
10+
"openAICompatible": true,
11+
"requiresNetwork": false,
12+
"evidenceRefs": ["sha256:1111111111111111111111111111111111111111111111111111111111111111"]
13+
}

‎examples/modelresidency.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"id": "urn:srcos:model-residency:m2-local-llama32-3b-20260504t170000z",
3+
"type": "ModelResidency",
4+
"specVersion": "2.1.0",
5+
"machineRef": "urn:srcos:agent-machine:m2-asahi-local",
6+
"modelCarryRef": "urn:srcos:model-carry-ref:local-llama32-3b-office-assist",
7+
"providerRef": "urn:srcos:inference-provider:llama-cpp-cpu-arm64-local",
8+
"residencyState": "cached",
9+
"quantization": "q4_k_m",
10+
"bytesOnDisk": 2147483648,
11+
"cacheTier": "nvme",
12+
"observedAt": "2026-05-04T17:00:00Z",
13+
"evidenceRefs": ["sha256:2222222222222222222222222222222222222222222222222222222222222222"]
14+
}

‎examples/placementfact.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"id": "urn:srcos:placement-fact:m2-asahi-local-20260504t170000z",
3+
"type": "PlacementFact",
4+
"specVersion": "2.1.0",
5+
"machineRef": "urn:srcos:agent-machine:m2-asahi-local",
6+
"observedAt": "2026-05-04T17:00:00Z",
7+
"hardware": {
8+
"arch": "aarch64",
9+
"accelerators": ["cpu", "vulkan-probe"],
10+
"memoryBytes": 25769803776,
11+
"storageBytesAvailable": 107374182400
12+
},
13+
"isolation": {
14+
"runtime": "rootless-podman",
15+
"networkDefault": "policy-gated",
16+
"filesystemDefault": "workspace-scoped-rw"
17+
},
18+
"trustPosture": "sandboxed-local",
19+
"modelResidencyRefs": ["urn:srcos:model-residency:m2-local-llama32-3b-20260504t170000z"],
20+
"providerRefs": ["urn:srcos:inference-provider:llama-cpp-cpu-arm64-local"],
21+
"cacheNotes": ["NVMe model cache available; KV cache reuse requires identity and policy match."],
22+
"evidenceRefs": ["sha256:3333333333333333333333333333333333333333333333333333333333333333"]
23+
}

‎examples/sourceosmodelcarryref.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"id": "urn:srcos:model-carry-ref:local-llama32-3b-office-assist",
3+
"type": "SourceOSModelCarryRef",
4+
"specVersion": "2.1.0",
5+
"modelRef": "urn:prophet:model:llama32-3b-local-office-assist",
6+
"governanceRef": "urn:prophet:model-release-decision:local-llama32-3b-office-assist-20260504",
7+
"routerProfileRef": "urn:srcos:model-router-profile:local-first-office-assist",
8+
"releaseSetRefs": ["urn:srcos:release-set:sourceos-workstation-m2-20260504"],
9+
"launchProfileRefs": ["urn:srcos:model-launch-profile:llama-cpp-local-office-assist"],
10+
"fallbackRefs": [],
11+
"carryPolicy": "download-on-demand",
12+
"cachePolicy": "weights-cache-allowed",
13+
"mutableModelState": false,
14+
"evidenceRefs": ["sha256:2e7f1c7f0a6a4bbd9ef000000000000000000000000000000000000000000"]
15+
}

‎schemas/AgentMachineReceipt.json‎

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

‎schemas/InferenceProvider.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.srcos.ai/v2/InferenceProvider.json",
4+
"title": "InferenceProvider",
5+
"description": "Backend-neutral description of a local, clustered, or governed remote inference provider that Agent Machine and model-router may reason about.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["id", "type", "specVersion", "providerClass", "endpointMode", "executionProfile", "trustPosture", "supportedModalities"],
9+
"properties": {
10+
"id": { "type": "string", "pattern": "^urn:srcos:inference-provider:", "description": "Stable URN identifier. Pattern: urn:srcos:inference-provider:<local-id>" },
11+
"type": { "const": "InferenceProvider", "description": "Discriminator constant — always \"InferenceProvider\"." },
12+
"specVersion": { "type": "string", "description": "Spec version of this document, e.g. \"2.1.0\"." },
13+
"providerClass": { "type": "string", "enum": ["llama.cpp", "vllm", "sglang", "ollama-compatible", "openai-compatible", "mlx-compatible", "remote-governed", "custom"], "description": "Provider implementation family or compatibility class." },
14+
"endpointMode": { "type": "string", "enum": ["local-process", "local-http", "unix-socket", "kubernetes-service", "remote-http", "stdio"], "description": "How clients communicate with the provider." },
15+
"executionProfile": { "type": "string", "description": "Runtime profile such as cpu-arm64, vulkan, cuda, hip, metal-compatible, or remote-governed." },
16+
"trustPosture": { "type": "string", "enum": ["local-trusted", "local-sandboxed", "cluster-governed", "remote-governed", "untrusted"], "description": "Trust posture used by Policy Fabric and Agent Machine admission." },
17+
"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"] } },
18+
"openAICompatible": { "type": "boolean", "description": "Whether the provider exposes an OpenAI-compatible API surface." },
19+
"requiresNetwork": { "type": "boolean", "description": "Whether the provider requires network egress beyond loopback/local IPC." },
20+
"evidenceRefs": { "type": "array", "description": "Evidence URNs or hashes for provider validation, binary provenance, and compatibility testing.", "items": { "type": "string" } }
21+
}
22+
}

‎schemas/ModelResidency.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.srcos.ai/v2/ModelResidency.json",
4+
"title": "ModelResidency",
5+
"description": "Point-in-time evidence that a governed model reference is available, loaded, warm, pinned, evictable, or unavailable on an Agent Machine.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["id", "type", "specVersion", "machineRef", "modelCarryRef", "providerRef", "residencyState", "observedAt"],
9+
"properties": {
10+
"id": { "type": "string", "pattern": "^urn:srcos:model-residency:", "description": "Stable URN identifier. Pattern: urn:srcos:model-residency:<local-id>" },
11+
"type": { "const": "ModelResidency", "description": "Discriminator constant — always \"ModelResidency\"." },
12+
"specVersion": { "type": "string", "description": "Spec version of this document, e.g. \"2.1.0\"." },
13+
"machineRef": { "type": "string", "pattern": "^urn:srcos:agent-machine:", "description": "Agent Machine URN where residency was observed." },
14+
"modelCarryRef": { "type": "string", "pattern": "^urn:srcos:model-carry-ref:", "description": "SourceOSModelCarryRef URN for the governed model/service reference." },
15+
"providerRef": { "type": "string", "pattern": "^urn:srcos:inference-provider:", "description": "InferenceProvider URN serving or expected to serve the model." },
16+
"residencyState": { "type": "string", "enum": ["unavailable", "downloadable", "cached", "loading", "loaded-cold", "loaded-warm", "pinned", "evictable", "failed"], "description": "Observed model residency state." },
17+
"quantization": { "type": ["string", "null"], "description": "Quantization or precision label when known, such as q4_k_m, int8, fp16, or null." },
18+
"bytesOnDisk": { "type": ["integer", "null"], "minimum": 0, "description": "Observed model bytes on local storage, or null when unknown." },
19+
"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." },
20+
"observedAt": { "type": "string", "format": "date-time", "description": "Timestamp when residency was observed." },
21+
"evidenceRefs": { "type": "array", "description": "Evidence URNs or content hashes for probe output, checksums, and provider state.", "items": { "type": "string" } }
22+
}
23+
}

0 commit comments

Comments
 (0)