feat: Systema membrane boundary and capability radius integration docs

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`

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`

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"
+      }
+    }
+  ]
+}

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
+      }
+    }
+  ]
+}