diff --git a/docs/integration/systema-capability-radius.md b/docs/integration/systema-capability-radius.md new file mode 100644 index 0000000..ba7e66c --- /dev/null +++ b/docs/integration/systema-capability-radius.md @@ -0,0 +1,51 @@ +# Agent Machine: Systema Capability Radius Integration + +## What This Documents + +Agent Machine's alignment with Systema's R0–R5 capability radius semantics. The radius defines the maximum scope within which an AgentPod may exercise capabilities. + +## Radius Levels in Agent Machine Context + +| Radius | Systema label | Agent Machine meaning | +|---|---|---| +| R0 | observe-only | Read probes, health checks, non-mutating queries. No filesystem writes, no network calls beyond mesh. | +| R1 | local-bounded | Read/write within declared workspace directory only. No subprocess execution, no network. | +| R2 | local-execution | Subprocess execution within declared workspace. No network calls. No filesystem access outside workspace. | +| R3 | local-network | R2 + declared outbound network endpoints only (e.g., `127.0.0.1:8080` for local steering). No internet. | +| R4 | mesh-connected | R3 + Prophet Mesh endpoints. No arbitrary internet. | +| R5 | internet-connected | Full internet access within declared capability declaration. Requires explicit policy admission. | + +## Mapping to Agent Machine Contracts + +### capability-declaration.schema.json + +The `capabilityRadius` field (to be added in a follow-on tranche) maps to R0–R5. Until then, the effective radius is inferred from the combination of: +- `allowedFilesystemPaths[]` → R0 if empty, R1 if set +- `allowedSubprocesses[]` → R2 if set +- `allowedNetworkEndpoints[]` → R3/R4/R5 based on endpoint class + +### policy-admission.schema.json + +Policy decisions reference the declared radius. A request for a capability beyond the declared radius is automatically denied without policy evaluation. + +### activation-decision.schema.json + +Activation decisions carry the effective radius assigned at admission time. The runtime enforces this radius for the pod's lifetime. + +## Radius Enforcement + +Enforcement is fail-closed: if a capability request cannot be verified as within the pod's assigned radius, it is denied and a policy-admission record with `verdict: denied` and `rationale: "outside-capability-radius"` is emitted. + +In-flight radius downgrades (e.g., due to grant revocation) terminate the pod via `lifecycle.schema.json` `terminated` event. + +## Example Radius Profiles + +See: +- `examples/reachability/agent-machine-capability-radius.example.json` — R0, R2, R4 examples + +## Referenced Schemas + +- `contracts/capability-declaration.schema.json` +- `contracts/activation-decision.schema.json` +- `contracts/policy-admission.schema.json` +- `contracts/lifecycle.schema.json` diff --git a/docs/integration/systema-membrane-boundary.md b/docs/integration/systema-membrane-boundary.md new file mode 100644 index 0000000..68f1c89 --- /dev/null +++ b/docs/integration/systema-membrane-boundary.md @@ -0,0 +1,71 @@ +# Agent Machine: Systema Membrane Boundary Integration + +## What This Documents + +Agent Machine's role in Systema's membrane accounting model. Agent Machine owns the machine-local runtime layer; every activation, deployment, and side-effect crosses a membrane that must be declared, admitted, and witnessed. + +## Membranes in Agent Machine + +### 1. Activation Membrane + +The activation membrane controls whether an AgentPod may start executing on this machine. + +**Crossing direction:** `declared → preflight → admitted | blocked` + +**Admitted when:** +- Policy Fabric returns `admitted` or `conditional` for the AgentPod's capability declaration +- Steering artifact receipts are present and valid (if steering is requested) +- Boot phase is `unlocked-user-session` or later +- Agent Registry grant exists and is not revoked + +**Blocked when:** +- Policy Fabric returns `denied` +- Required capability is `not_configured` (fail-closed) +- Artifact receipt is missing or digest mismatch +- Boot phase is insufficient (e.g., `pre-login`) + +**Logged:** Every crossing attempt emits an `activation-decision.schema.json` record. + +**Witnessed:** `agentplane-runtime-evidence.schema.json` carries a reference to the admission decision. + +**Revoked:** If an in-flight AgentPod's grant is revoked, the pod's execution is terminated and a `lifecycle.schema.json` `terminated` event is emitted. + +### 2. Side-Effect Membrane + +The side-effect membrane controls what mutations a running AgentPod may emit beyond its declared capability radius. + +**Crossing direction:** `requested-mutation → policy-check → applied | suppressed` + +**Applied when:** the mutation falls within the pod's declared `capability-declaration.schema.json` scope and the policy check passes. + +**Suppressed when:** the mutation targets a path, resource, or service outside the declared scope, or the policy denies it. + +**Transformed:** Some mutations are rewritten (e.g., write to a sandboxed path rather than the declared path) when the policy returns `conditional`. + +### 3. Storage Membrane + +The storage membrane governs which volumes an AgentPod may read or write. + +**Crossing direction:** `volume-mount-request → storage-receipt-gate → mounted | refused` + +**Mounted when:** `storage-receipt.schema.json` exists for the volume, encryption posture meets sensitivity policy, and quota allows. + +**Refused when:** receipt is absent, sensitivity is `raw-prompt` or `credentials` (always forbidden), or quota is exceeded. + +## Behavior Matrix + +| Membrane | admitted | blocked | transformed | logged | witnessed | revoked | +|---|---|---|---|---|---|---| +| Activation | ✓ pod starts | ✓ pod not started, receipt emitted | — | ✓ activation-decision | ✓ runtime-evidence | ✓ lifecycle.terminated | +| Side-effect | ✓ mutation applied | ✓ mutation suppressed, receipt emitted | ✓ rewritten to sandboxed path | ✓ policy-admission record | ✓ runtime-evidence | ✓ grant revoked mid-flight | +| Storage | ✓ volume mounted | ✓ mount refused, receipt emitted | — | ✓ storage-receipt | ✓ runtime-evidence | ✓ volume unmounted | + +## Referenced Schemas + +- `contracts/activation-decision.schema.json` +- `contracts/capability-declaration.schema.json` +- `contracts/policy-admission.schema.json` +- `contracts/agentplane-runtime-evidence.schema.json` +- `contracts/storage-receipt.schema.json` +- `contracts/lifecycle.schema.json` +- `contracts/agent-registry-grant.schema.json` diff --git a/examples/membranes/agent-machine-activation-membrane.example.json b/examples/membranes/agent-machine-activation-membrane.example.json new file mode 100644 index 0000000..be6ed60 --- /dev/null +++ b/examples/membranes/agent-machine-activation-membrane.example.json @@ -0,0 +1,48 @@ +{ + "_comment": "Agent Machine activation membrane crossing examples — admitted, blocked, and revoked cases.", + "examples": [ + { + "case": "admitted", + "description": "Steering AgentPod admitted after successful preflight: artifact receipts present, policy grants R3, boot phase unlocked.", + "activationDecision": { + "id": "urn:agent-machine:activation-decision:gpt2-steer-20260718-001", + "specVersion": "0.1.0", + "agentPodId": "urn:agent-machine:agentpod:gpt2-steer-001", + "verdict": "admitted", + "capabilityRadius": "R3", + "grantRef": "urn:agent-registry:grant:gpt2-steer-op-001", + "policyRef": "urn:policy-fabric:decision:gpt2-steer-preflight-001", + "artifactReceiptRef": "urn:agent-machine:steering-artifact-receipt:gpt2-small-res-jb-001", + "bootPhase": "unlocked-user-session", + "admittedAt": "2026-07-18T10:00:00Z" + } + }, + { + "case": "blocked", + "description": "Activation blocked: artifact receipt missing for gpt2-small.res-jb. Fail-closed: pod not started.", + "activationDecision": { + "id": "urn:agent-machine:activation-decision:gpt2-steer-missing-receipt-001", + "specVersion": "0.1.0", + "agentPodId": "urn:agent-machine:agentpod:gpt2-steer-002", + "verdict": "denied", + "rationale": "steering-artifact-receipt-missing", + "failClosedStatus": "not_configured", + "bootPhase": "unlocked-user-session", + "blockedAt": "2026-07-18T10:05:00Z" + } + }, + { + "case": "revoked", + "description": "In-flight pod grant revoked by policy-fabric. Pod terminated, lifecycle event emitted.", + "lifecycleEvent": { + "id": "urn:agent-machine:lifecycle:gpt2-steer-revoked-001", + "specVersion": "0.1.0", + "agentPodId": "urn:agent-machine:agentpod:gpt2-steer-001", + "event": "terminated", + "reason": "grant-revoked", + "grantRef": "urn:agent-registry:grant:gpt2-steer-op-001", + "revokedAt": "2026-07-18T10:30:00Z" + } + } + ] +} diff --git a/examples/reachability/agent-machine-capability-radius.example.json b/examples/reachability/agent-machine-capability-radius.example.json new file mode 100644 index 0000000..ffcf21c --- /dev/null +++ b/examples/reachability/agent-machine-capability-radius.example.json @@ -0,0 +1,45 @@ +{ + "_comment": "Agent Machine capability radius examples — R0 (observe-only), R2 (local-execution), R4 (mesh-connected).", + "examples": [ + { + "radius": "R0", + "label": "observe-only", + "description": "Probe-only pod: reads hardware/runtime facts, emits health receipts. No writes, no network beyond probe endpoints.", + "effectiveConstraints": { + "allowedFilesystemPaths": ["/proc", "/sys", "/etc/os-release"], + "allowedFilesystemOperations": ["read"], + "allowedSubprocesses": [], + "allowedNetworkEndpoints": [], + "mutationPermitted": false + } + }, + { + "radius": "R2", + "label": "local-execution", + "description": "Local coding agent: reads/writes within declared workspace, may spawn subprocesses. No network.", + "effectiveConstraints": { + "allowedFilesystemPaths": ["/home/user/.sourceos/workspace/coding-agent-001"], + "allowedFilesystemOperations": ["read", "write", "execute"], + "allowedSubprocesses": ["python3", "cargo", "node"], + "allowedNetworkEndpoints": [], + "mutationPermitted": true + } + }, + { + "radius": "R4", + "label": "mesh-connected", + "description": "Reasoning pod with local steering + mesh routing. Restricted to declared local and mesh endpoints.", + "effectiveConstraints": { + "allowedFilesystemPaths": ["/home/user/.sourceos/workspace/reasoning-agent-001"], + "allowedFilesystemOperations": ["read", "write"], + "allowedSubprocesses": [], + "allowedNetworkEndpoints": [ + "127.0.0.1:8080", + "mesh.socioprophet.ai:443", + "127.0.0.1:11435" + ], + "mutationPermitted": true + } + } + ] +}