feat(spec): reconcile execution-control contracts with current runtime surfaces

docs/execution-control-reconciliation-v0.3.md

@@ -0,0 +1,81 @@
+# Execution Control Reconciliation v0.3
+
+Status: planning baseline  
+Base: current `main` after agent harness, runtime observability, OpsHistory, reasoning, Agent Machine, local runtime, browser, and shell receipt tranches.
+
+## Purpose
+
+This note reconciles the proposed execution-control contract pack with the newer contract families already present in `sourceos-spec`.
+
+The goal is to avoid duplicate schema classes while preserving the missing control-plane vocabulary needed by downstream consumers.
+
+## Upstream families already present
+
+Recent upstream work already covers several adjacent domains:
+
+- Agent harness execution receipts: local runtime, shell, browser, host mutation, and download artifact receipt boundaries.
+- Runtime observability and capability governance: capability ledger, browser automation receipt, Git workspace state, orphan event receipt, and runtime install receipt.
+- OpsHistory: local-first operational history and redaction vocabulary.
+- Reasoning contracts: reasoning event, run, receipt, replay plan, and benchmark surfaces.
+- Agent Machine / model carry projections: model residency, inference provider, placement facts, and machine receipts.
+- Local runtime, browser history, shell receipt, and local-first service manifest surfaces.
+
+## Reuse-first decisions
+
+| Need | Reuse existing upstream surface | Net-new surface only if needed |
+|---|---|---|
+| Runtime receipt / execution proof | `AgentHarnessExecutionReceipts`, `RunRecord`, `SessionReceipt`, `TruthSurface`, `DeltaSurface` | No new generic run receipt in this tranche |
+| Browser, shell, terminal, host, and download evidence | Existing local-runtime, browser/shell, OpsHistory, and runtime observability receipts | No generic replacement evidence schema in this tranche |
+| Capability truth after reconciliation | `CapabilityLedger`, `Policy`, `PolicyDecision`, `CapabilityToken` | Optional `ToolExposurePolicy` for presentation-layer tool visibility only |
+| Workflow / validation program shape | `WorkflowSpec`, `WorkflowNode`, `WorkflowEdge`, `SkillManifest` | No new `ValidationProgram` schema in this tranche |
+| Agent skill packaging | `SkillManifest` | No new `AgentSkillBundle` schema in this tranche |
+| Lightweight environment fork | No exact current top-level schema | `ExecutionFork` remains net-new |
+| Request/session routing into a fork | No exact current top-level schema | `RoutingContract` remains net-new |
+| Team/developer runtime quota controls | No exact current top-level schema | `QuotaPolicy` remains net-new |
+| Runner image and primitive bundle | No exact current top-level schema | `RunnerGroup` remains net-new |
+| Protocol server test harness | No exact current top-level schema | `ProtocolWorkbench` remains net-new |
+| Generic artifact index | Partly covered by download/runtime receipts and Memory Mesh pointers | Defer `ArtifactDescriptor` until it aligns with existing artifact-pointer conventions |
+
+## Proposed v0.3 net-new tranche
+
+Add only these top-level schemas first:
+
+1. `ExecutionFork`
+2. `RoutingContract`
+3. `ToolExposurePolicy`
+4. `QuotaPolicy`
+5. `RunnerGroup`
+6. `ProtocolWorkbench`
+
+Defer or profile instead of adding:
+
+- `CapabilityPolicy`: use existing `Policy`, `PolicyDecision`, `CapabilityToken`, and `CapabilityLedger` until a genuine missing shape is proven.
+- `ArtifactDescriptor`: reconcile first with AgentHarness download artifact receipts, RuntimeInstall receipts, and Memory Mesh artifact pointer conventions.
+- `ValidationProgram`: profile `WorkflowSpec`.
+- `AgentSkillBundle`: profile `SkillManifest`.
+- `GovernedRun`: profile `RunRecord` and `AgentHarnessExecutionReceipts`.
+- `CairnEvidenceManifest`: profile `TruthSurface`, `DeltaSurface`, and existing provenance/receipt contracts.
+
+## Downstream alignment
+
+- `SocioProphet/agentplane`: consume `ExecutionFork`, `RoutingContract`, `RunnerGroup`, and `ProtocolWorkbench` as runtime orchestration inputs.
+- `SocioProphet/policy-fabric`: consume `ToolExposurePolicy` and `QuotaPolicy`; continue using existing policy decision/token flows for authority.
+- `SocioProphet/TriTRPC`: bind routing/workbench/session events to protocol frames.
+- `SourceOS-Linux/openclaw`: consume `ProtocolWorkbench` and `ToolExposurePolicy` for agent workbench and skill execution defaults.
+- `SourceOS-Linux/agent-term`, `TurtleTerm`, `sourceos-shell`, `BearBrowser`, and `agent-machine`: continue emitting the receipt families already added upstream.
+- `SociOS-Linux/workstation-contracts`: publish a workstation-safe subset profile.
+- `SocioProphet/socioprophet-agent-standards`: own conformance profiles, not canonical schemas.
+
+## Non-goals
+
+- No ADR in this tranche.
+- No replacement of current receipt or runtime-observability families.
+- No direct external-system wire compatibility promise.
+- No catalog count update until the exact schema tranche stabilizes.
+
+## Validation plan
+
+1. Add schemas and examples for the six net-new top-level objects.
+2. Add focused validators only after the shape stabilizes.
+3. Add OpenAPI/AsyncAPI patch entries later, when runtime producers are ready.
+4. Add derived profiles in downstream standards repos after canonical merge.

examples/execution_fork.json

@@ -0,0 +1,26 @@
+{
+  "id": "urn:srcos:execution-fork:checkout-example",
+  "type": "ExecutionFork",
+  "specVersion": "2.0.0",
+  "name": "checkout-example",
+  "substrate": "kubernetes",
+  "baselineRef": "urn:srcos:truth-surface:baseline-example",
+  "baselineDigest": "sha256:baseline-example",
+  "routingContractRef": "urn:srcos:routing-contract:checkout-example",
+  "runnerGroupRef": "urn:srcos:runner-group:validation-standard",
+  "quotaPolicyRef": "urn:srcos:quota:team-default",
+  "isolationRefs": ["urn:srcos:isolation:database-partition-example"],
+  "workloads": [
+    {
+      "name": "checkout",
+      "targetRef": "urn:srcos:workload:checkout",
+      "imageRef": "image.local/checkout:example",
+      "localPath": null,
+      "writePolicy": "isolated_only",
+      "envOverrides": { "FEATURE_MODE": "example" }
+    }
+  ],
+  "ttl": "8h",
+  "cleanupPolicy": "destroy_with_evidence_retained",
+  "tags": ["example", "validation"]
+}

examples/routing_contract.json

@@ -0,0 +1,31 @@
+{
+  "id": "urn:srcos:routing-contract:checkout-example",
+  "type": "RoutingContract",
+  "specVersion": "2.0.0",
+  "name": "checkout-example",
+  "selectors": {
+    "headers": [
+      { "name": "x-routing-key", "op": "equals", "value": "checkout-example" }
+    ],
+    "actorRef": "urn:srcos:session:agent-example",
+    "branchRef": "checkout-example",
+    "missionRef": "urn:srcos:workflow:checkout-validation",
+    "trustClass": "low"
+  },
+  "targets": [
+    {
+      "name": "checkout-http",
+      "targetRef": "urn:srcos:workload:checkout",
+      "port": 8080,
+      "fallback": "baseline",
+      "writePolicy": "isolated_only"
+    }
+  ],
+  "propagation": {
+    "traceContext": "w3c",
+    "extraHeaders": ["x-routing-key", "x-agent-session"]
+  },
+  "defaultDeny": false,
+  "requireCapabilityToken": true,
+  "readOnlySurface": false
+}

schemas/ExecutionFork.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ExecutionFork.json",
+  "title": "ExecutionFork",
+  "description": "A delta execution environment that overlays changed workloads, local mappings, and isolation references onto a shared baseline.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name", "substrate", "baselineRef", "routingContractRef", "workloads", "cleanupPolicy"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:execution-fork:" },
+    "type": { "const": "ExecutionFork" },
+    "specVersion": { "type": "string" },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "substrate": { "type": "string", "enum": ["kubernetes", "local", "hybrid", "container", "vm"] },
+    "baselineRef": { "type": "string" },
+    "baselineDigest": { "type": "string" },
+    "routingContractRef": { "type": "string", "pattern": "^urn:srcos:routing-contract:" },
+    "runnerGroupRef": { "type": ["string", "null"], "pattern": "^urn:srcos:runner-group:" },
+    "quotaPolicyRef": { "type": ["string", "null"], "pattern": "^urn:srcos:quota:" },
+    "isolationRefs": { "type": "array", "items": { "type": "string" } },
+    "workloads": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "targetRef"],
+        "properties": {
+          "name": { "type": "string" },
+          "targetRef": { "type": "string" },
+          "imageRef": { "type": ["string", "null"] },
+          "localPath": { "type": ["string", "null"] },
+          "writePolicy": { "type": "string", "enum": ["inherit", "isolated_only", "blocked"] },
+          "envOverrides": { "type": "object", "additionalProperties": { "type": "string" } }
+        }
+      }
+    },
+    "ttl": { "type": ["string", "null"] },
+    "cleanupPolicy": { "type": "string", "enum": ["destroy_with_evidence_retained", "destroy_all", "retain_for_debug"] },
+    "tags": { "type": "array", "items": { "type": "string" } }
+  }
+}

schemas/ProtocolWorkbench.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ProtocolWorkbench.json",
+  "title": "ProtocolWorkbench",
+  "description": "A typed workbench for developing, testing, and validating protocol-facing servers such as MCP, TriTRPC, HTTP APIs, gRPC services, or A2A endpoints against an execution fork.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name", "protocol", "executionForkRef", "serverUnderTest"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:workbench:" },
+    "type": { "const": "ProtocolWorkbench" },
+    "specVersion": { "type": "string" },
+    "name": { "type": "string" },
+    "protocol": { "type": "string", "enum": ["mcp", "a2a", "tritrpc", "http_api", "grpc"] },
+    "executionForkRef": { "type": "string", "pattern": "^urn:srcos:execution-fork:" },
+    "routingContractRef": { "type": ["string", "null"], "pattern": "^urn:srcos:routing-contract:" },
+    "serverUnderTest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["entrypoint"],
+      "properties": {
+        "entrypoint": { "type": "string" },
+        "localMapping": { "type": "boolean" },
+        "previewUrlEnabled": { "type": "boolean" }
+      }
+    },
+    "clientProfiles": { "type": "array", "items": { "type": "string" } },
+    "trafficCapture": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "captureRequests": { "type": "boolean" },
+        "captureResponses": { "type": "boolean" },
+        "captureToolCalls": { "type": "boolean" },
+        "redactSensitiveFields": { "type": "boolean" }
+      }
+    },
+    "transcriptMode": { "type": "string", "enum": ["request_response", "tool_call", "mixed"] },
+    "validationRefs": { "type": "array", "items": { "type": "string" } },
+    "artifactClasses": {
+      "type": "array",
+      "items": { "type": "string", "enum": ["transcript", "screenshot", "request_log", "response_log", "schema_diff", "tool_trace", "preview_link"] }
+    }
+  }
+}

schemas/QuotaPolicy.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/QuotaPolicy.json",
+  "title": "QuotaPolicy",
+  "description": "A typed quota and resource allocation policy for execution forks, runs, protocol workbenches, and artifact retention windows.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name", "version", "scope", "limits", "behaviorOnExceed"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:quota:" },
+    "type": { "const": "QuotaPolicy" },
+    "specVersion": { "type": "string" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "scope": { "type": "string", "enum": ["organization", "team", "actor", "mission", "repo", "environment_class"] },
+    "selectors": { "type": "object", "additionalProperties": true },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sandboxesCreatedPerWindow": { "type": "integer", "minimum": 0 },
+        "concurrentExecutionForks": { "type": "integer", "minimum": 0 },
+        "concurrentProtocolWorkbenches": { "type": "integer", "minimum": 0 },
+        "concurrentGovernedRuns": { "type": "integer", "minimum": 0 },
+        "testInvocationsPerWindow": { "type": "integer", "minimum": 0 },
+        "artifactStorageBytes": { "type": "integer", "minimum": 0 },
+        "logRetentionHours": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "window": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "unit": { "type": "string", "enum": ["hour", "day", "week", "month"] },
+        "value": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "behaviorOnExceed": { "type": "string", "enum": ["reject", "queue", "degrade_read_only", "require_human_approval"] },
+    "accountingMode": { "type": "string", "enum": ["admission_only", "admission_and_runtime"] }
+  }
+}

schemas/RoutingContract.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/RoutingContract.json",
+  "title": "RoutingContract",
+  "description": "A typed routing and propagation contract that selects requests, tool calls, or sessions and directs them toward an execution fork or baseline target.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name", "targets"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:routing-contract:" },
+    "type": { "const": "RoutingContract" },
+    "specVersion": { "type": "string" },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "selectors": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "headers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "op", "value"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string" },
+              "op": { "type": "string", "enum": ["equals", "contains", "prefix"] },
+              "value": { "type": "string" }
+            }
+          }
+        },
+        "actorRef": { "type": ["string", "null"] },
+        "branchRef": { "type": ["string", "null"] },
+        "missionRef": { "type": ["string", "null"] },
+        "trustClass": { "type": ["string", "null"] }
+      }
+    },
+    "targets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "targetRef", "fallback", "writePolicy"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "targetRef": { "type": "string" },
+          "port": { "type": ["integer", "null"], "minimum": 1, "maximum": 65535 },
+          "fallback": { "type": "string", "enum": ["baseline", "deny"] },
+          "writePolicy": { "type": "string", "enum": ["inherit", "isolated_only", "blocked"] }
+        }
+      }
+    },
+    "propagation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "traceContext": { "type": "string", "enum": ["w3c", "b3", "none"] },
+        "extraHeaders": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "defaultDeny": { "type": "boolean" },
+    "requireCapabilityToken": { "type": "boolean" },
+    "readOnlySurface": { "type": "boolean" }
+  }
+}

schemas/RunnerGroup.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/RunnerGroup.json",
+  "title": "RunnerGroup",
+  "description": "A versioned runtime bundle that supplies pinned images, built-in primitives, custom primitive extensions, and execution defaults for validations or protocol workbenches.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name", "version", "runtime", "imageRef", "imageDigestPinned"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:runner-group:" },
+    "type": { "const": "RunnerGroup" },
+    "specVersion": { "type": "string" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "runtime": { "type": "string", "enum": ["container", "wasm", "local", "hybrid"] },
+    "imageRef": { "type": "string" },
+    "imageDigestPinned": { "type": "boolean" },
+    "builtInPrimitives": { "type": "array", "items": { "type": "string" } },
+    "customPrimitiveRefs": { "type": "array", "items": { "type": "string" } },
+    "dependencyProfiles": { "type": "array", "items": { "type": "string" } },
+    "networkPolicyRef": { "type": ["string", "null"] },
+    "filesystemPolicy": { "type": "string", "enum": ["ephemeral", "retained", "read_only_base"] },
+    "cachePolicy": { "type": "string", "enum": ["none", "ephemeral", "shared_read_only"] }
+  }
+}

schemas/ToolExposurePolicy.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/ToolExposurePolicy.json",
+  "title": "ToolExposurePolicy",
+  "description": "A presentation-layer policy describing which tools or toolsets are exposed on an interaction surface. It can only reduce visibility relative to authority granted by existing policy and capability-token flows.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "name", "version", "transport", "exposureMode"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^urn:srcos:tool-exposure:" },
+    "type": { "const": "ToolExposurePolicy" },
+    "specVersion": { "type": "string" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "transport": { "type": "string", "enum": ["mcp", "tritrpc", "cli", "api"] },
+    "exposureMode": { "type": "string", "enum": ["full", "read_only", "allow_list", "deny_list", "consent_gated"] },
+    "policyRefs": { "type": "array", "items": { "type": "string" } },
+    "defaultToolsets": { "type": "array", "items": { "type": "string" } },
+    "includeTools": { "type": "array", "items": { "type": "string" } },
+    "excludeTools": { "type": "array", "items": { "type": "string" } },
+    "requireMutationConsent": { "type": "boolean" },
+    "sensitiveDataMode": { "type": "string", "enum": ["blocked", "redacted", "allowed"] },
+    "lockdownMode": { "type": "boolean" }
+  }
+}