Skip to content

Commit f53eebc

Browse files
mdhellermdheller
committed
Replay contract pack
1 parent cec88e3 commit f53eebc

9 files changed

Lines changed: 381 additions & 0 deletions

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Execution Control Reconciliation v0.3
2+
3+
Status: planning baseline
4+
Base: current `main` after agent harness, runtime observability, OpsHistory, reasoning, Agent Machine, local runtime, browser, and shell receipt tranches.
5+
6+
## Purpose
7+
8+
This note reconciles the proposed execution-control contract pack with the newer contract families already present in `sourceos-spec`.
9+
10+
The goal is to avoid duplicate schema classes while preserving the missing control-plane vocabulary needed by downstream consumers.
11+
12+
## Upstream families already present
13+
14+
Recent upstream work already covers several adjacent domains:
15+
16+
- Agent harness execution receipts: local runtime, shell, browser, host mutation, and download artifact receipt boundaries.
17+
- Runtime observability and capability governance: capability ledger, browser automation receipt, Git workspace state, orphan event receipt, and runtime install receipt.
18+
- OpsHistory: local-first operational history and redaction vocabulary.
19+
- Reasoning contracts: reasoning event, run, receipt, replay plan, and benchmark surfaces.
20+
- Agent Machine / model carry projections: model residency, inference provider, placement facts, and machine receipts.
21+
- Local runtime, browser history, shell receipt, and local-first service manifest surfaces.
22+
23+
## Reuse-first decisions
24+
25+
| Need | Reuse existing upstream surface | Net-new surface only if needed |
26+
|---|---|---|
27+
| Runtime receipt / execution proof | `AgentHarnessExecutionReceipts`, `RunRecord`, `SessionReceipt`, `TruthSurface`, `DeltaSurface` | No new generic run receipt in this tranche |
28+
| 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 |
29+
| Capability truth after reconciliation | `CapabilityLedger`, `Policy`, `PolicyDecision`, `CapabilityToken` | Optional `ToolExposurePolicy` for presentation-layer tool visibility only |
30+
| Workflow / validation program shape | `WorkflowSpec`, `WorkflowNode`, `WorkflowEdge`, `SkillManifest` | No new `ValidationProgram` schema in this tranche |
31+
| Agent skill packaging | `SkillManifest` | No new `AgentSkillBundle` schema in this tranche |
32+
| Lightweight environment fork | No exact current top-level schema | `ExecutionFork` remains net-new |
33+
| Request/session routing into a fork | No exact current top-level schema | `RoutingContract` remains net-new |
34+
| Team/developer runtime quota controls | No exact current top-level schema | `QuotaPolicy` remains net-new |
35+
| Runner image and primitive bundle | No exact current top-level schema | `RunnerGroup` remains net-new |
36+
| Protocol server test harness | No exact current top-level schema | `ProtocolWorkbench` remains net-new |
37+
| Generic artifact index | Partly covered by download/runtime receipts and Memory Mesh pointers | Defer `ArtifactDescriptor` until it aligns with existing artifact-pointer conventions |
38+
39+
## Proposed v0.3 net-new tranche
40+
41+
Add only these top-level schemas first:
42+
43+
1. `ExecutionFork`
44+
2. `RoutingContract`
45+
3. `ToolExposurePolicy`
46+
4. `QuotaPolicy`
47+
5. `RunnerGroup`
48+
6. `ProtocolWorkbench`
49+
50+
Defer or profile instead of adding:
51+
52+
- `CapabilityPolicy`: use existing `Policy`, `PolicyDecision`, `CapabilityToken`, and `CapabilityLedger` until a genuine missing shape is proven.
53+
- `ArtifactDescriptor`: reconcile first with AgentHarness download artifact receipts, RuntimeInstall receipts, and Memory Mesh artifact pointer conventions.
54+
- `ValidationProgram`: profile `WorkflowSpec`.
55+
- `AgentSkillBundle`: profile `SkillManifest`.
56+
- `GovernedRun`: profile `RunRecord` and `AgentHarnessExecutionReceipts`.
57+
- `CairnEvidenceManifest`: profile `TruthSurface`, `DeltaSurface`, and existing provenance/receipt contracts.
58+
59+
## Downstream alignment
60+
61+
- `SocioProphet/agentplane`: consume `ExecutionFork`, `RoutingContract`, `RunnerGroup`, and `ProtocolWorkbench` as runtime orchestration inputs.
62+
- `SocioProphet/policy-fabric`: consume `ToolExposurePolicy` and `QuotaPolicy`; continue using existing policy decision/token flows for authority.
63+
- `SocioProphet/TriTRPC`: bind routing/workbench/session events to protocol frames.
64+
- `SourceOS-Linux/openclaw`: consume `ProtocolWorkbench` and `ToolExposurePolicy` for agent workbench and skill execution defaults.
65+
- `SourceOS-Linux/agent-term`, `TurtleTerm`, `sourceos-shell`, `BearBrowser`, and `agent-machine`: continue emitting the receipt families already added upstream.
66+
- `SociOS-Linux/workstation-contracts`: publish a workstation-safe subset profile.
67+
- `SocioProphet/socioprophet-agent-standards`: own conformance profiles, not canonical schemas.
68+
69+
## Non-goals
70+
71+
- No ADR in this tranche.
72+
- No replacement of current receipt or runtime-observability families.
73+
- No direct external-system wire compatibility promise.
74+
- No catalog count update until the exact schema tranche stabilizes.
75+
76+
## Validation plan
77+
78+
1. Add schemas and examples for the six net-new top-level objects.
79+
2. Add focused validators only after the shape stabilizes.
80+
3. Add OpenAPI/AsyncAPI patch entries later, when runtime producers are ready.
81+
4. Add derived profiles in downstream standards repos after canonical merge.

‎examples/execution_fork.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"id": "urn:srcos:execution-fork:checkout-example",
3+
"type": "ExecutionFork",
4+
"specVersion": "2.0.0",
5+
"name": "checkout-example",
6+
"substrate": "kubernetes",
7+
"baselineRef": "urn:srcos:truth-surface:baseline-example",
8+
"baselineDigest": "sha256:baseline-example",
9+
"routingContractRef": "urn:srcos:routing-contract:checkout-example",
10+
"runnerGroupRef": "urn:srcos:runner-group:validation-standard",
11+
"quotaPolicyRef": "urn:srcos:quota:team-default",
12+
"isolationRefs": ["urn:srcos:isolation:database-partition-example"],
13+
"workloads": [
14+
{
15+
"name": "checkout",
16+
"targetRef": "urn:srcos:workload:checkout",
17+
"imageRef": "image.local/checkout:example",
18+
"localPath": null,
19+
"writePolicy": "isolated_only",
20+
"envOverrides": { "FEATURE_MODE": "example" }
21+
}
22+
],
23+
"ttl": "8h",
24+
"cleanupPolicy": "destroy_with_evidence_retained",
25+
"tags": ["example", "validation"]
26+
}

‎examples/routing_contract.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"id": "urn:srcos:routing-contract:checkout-example",
3+
"type": "RoutingContract",
4+
"specVersion": "2.0.0",
5+
"name": "checkout-example",
6+
"selectors": {
7+
"headers": [
8+
{ "name": "x-routing-key", "op": "equals", "value": "checkout-example" }
9+
],
10+
"actorRef": "urn:srcos:session:agent-example",
11+
"branchRef": "checkout-example",
12+
"missionRef": "urn:srcos:workflow:checkout-validation",
13+
"trustClass": "low"
14+
},
15+
"targets": [
16+
{
17+
"name": "checkout-http",
18+
"targetRef": "urn:srcos:workload:checkout",
19+
"port": 8080,
20+
"fallback": "baseline",
21+
"writePolicy": "isolated_only"
22+
}
23+
],
24+
"propagation": {
25+
"traceContext": "w3c",
26+
"extraHeaders": ["x-routing-key", "x-agent-session"]
27+
},
28+
"defaultDeny": false,
29+
"requireCapabilityToken": true,
30+
"readOnlySurface": false
31+
}

‎schemas/ExecutionFork.json‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.srcos.ai/v2/ExecutionFork.json",
4+
"title": "ExecutionFork",
5+
"description": "A delta execution environment that overlays changed workloads, local mappings, and isolation references onto a shared baseline.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["id", "type", "specVersion", "name", "substrate", "baselineRef", "routingContractRef", "workloads", "cleanupPolicy"],
9+
"properties": {
10+
"id": { "type": "string", "pattern": "^urn:srcos:execution-fork:" },
11+
"type": { "const": "ExecutionFork" },
12+
"specVersion": { "type": "string" },
13+
"name": { "type": "string" },
14+
"description": { "type": "string" },
15+
"substrate": { "type": "string", "enum": ["kubernetes", "local", "hybrid", "container", "vm"] },
16+
"baselineRef": { "type": "string" },
17+
"baselineDigest": { "type": "string" },
18+
"routingContractRef": { "type": "string", "pattern": "^urn:srcos:routing-contract:" },
19+
"runnerGroupRef": { "type": ["string", "null"], "pattern": "^urn:srcos:runner-group:" },
20+
"quotaPolicyRef": { "type": ["string", "null"], "pattern": "^urn:srcos:quota:" },
21+
"isolationRefs": { "type": "array", "items": { "type": "string" } },
22+
"workloads": {
23+
"type": "array",
24+
"items": {
25+
"type": "object",
26+
"additionalProperties": false,
27+
"required": ["name", "targetRef"],
28+
"properties": {
29+
"name": { "type": "string" },
30+
"targetRef": { "type": "string" },
31+
"imageRef": { "type": ["string", "null"] },
32+
"localPath": { "type": ["string", "null"] },
33+
"writePolicy": { "type": "string", "enum": ["inherit", "isolated_only", "blocked"] },
34+
"envOverrides": { "type": "object", "additionalProperties": { "type": "string" } }
35+
}
36+
}
37+
},
38+
"ttl": { "type": ["string", "null"] },
39+
"cleanupPolicy": { "type": "string", "enum": ["destroy_with_evidence_retained", "destroy_all", "retain_for_debug"] },
40+
"tags": { "type": "array", "items": { "type": "string" } }
41+
}
42+
}

‎schemas/ProtocolWorkbench.json‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.srcos.ai/v2/ProtocolWorkbench.json",
4+
"title": "ProtocolWorkbench",
5+
"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.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["id", "type", "specVersion", "name", "protocol", "executionForkRef", "serverUnderTest"],
9+
"properties": {
10+
"id": { "type": "string", "pattern": "^urn:srcos:workbench:" },
11+
"type": { "const": "ProtocolWorkbench" },
12+
"specVersion": { "type": "string" },
13+
"name": { "type": "string" },
14+
"protocol": { "type": "string", "enum": ["mcp", "a2a", "tritrpc", "http_api", "grpc"] },
15+
"executionForkRef": { "type": "string", "pattern": "^urn:srcos:execution-fork:" },
16+
"routingContractRef": { "type": ["string", "null"], "pattern": "^urn:srcos:routing-contract:" },
17+
"serverUnderTest": {
18+
"type": "object",
19+
"additionalProperties": false,
20+
"required": ["entrypoint"],
21+
"properties": {
22+
"entrypoint": { "type": "string" },
23+
"localMapping": { "type": "boolean" },
24+
"previewUrlEnabled": { "type": "boolean" }
25+
}
26+
},
27+
"clientProfiles": { "type": "array", "items": { "type": "string" } },
28+
"trafficCapture": {
29+
"type": "object",
30+
"additionalProperties": false,
31+
"properties": {
32+
"captureRequests": { "type": "boolean" },
33+
"captureResponses": { "type": "boolean" },
34+
"captureToolCalls": { "type": "boolean" },
35+
"redactSensitiveFields": { "type": "boolean" }
36+
}
37+
},
38+
"transcriptMode": { "type": "string", "enum": ["request_response", "tool_call", "mixed"] },
39+
"validationRefs": { "type": "array", "items": { "type": "string" } },
40+
"artifactClasses": {
41+
"type": "array",
42+
"items": { "type": "string", "enum": ["transcript", "screenshot", "request_log", "response_log", "schema_diff", "tool_trace", "preview_link"] }
43+
}
44+
}
45+
}

‎schemas/QuotaPolicy.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.srcos.ai/v2/QuotaPolicy.json",
4+
"title": "QuotaPolicy",
5+
"description": "A typed quota and resource allocation policy for execution forks, runs, protocol workbenches, and artifact retention windows.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["id", "type", "specVersion", "name", "version", "scope", "limits", "behaviorOnExceed"],
9+
"properties": {
10+
"id": { "type": "string", "pattern": "^urn:srcos:quota:" },
11+
"type": { "const": "QuotaPolicy" },
12+
"specVersion": { "type": "string" },
13+
"name": { "type": "string" },
14+
"version": { "type": "string" },
15+
"scope": { "type": "string", "enum": ["organization", "team", "actor", "mission", "repo", "environment_class"] },
16+
"selectors": { "type": "object", "additionalProperties": true },
17+
"limits": {
18+
"type": "object",
19+
"additionalProperties": false,
20+
"properties": {
21+
"sandboxesCreatedPerWindow": { "type": "integer", "minimum": 0 },
22+
"concurrentExecutionForks": { "type": "integer", "minimum": 0 },
23+
"concurrentProtocolWorkbenches": { "type": "integer", "minimum": 0 },
24+
"concurrentGovernedRuns": { "type": "integer", "minimum": 0 },
25+
"testInvocationsPerWindow": { "type": "integer", "minimum": 0 },
26+
"artifactStorageBytes": { "type": "integer", "minimum": 0 },
27+
"logRetentionHours": { "type": "integer", "minimum": 1 }
28+
}
29+
},
30+
"window": {
31+
"type": "object",
32+
"additionalProperties": false,
33+
"properties": {
34+
"unit": { "type": "string", "enum": ["hour", "day", "week", "month"] },
35+
"value": { "type": "integer", "minimum": 1 }
36+
}
37+
},
38+
"behaviorOnExceed": { "type": "string", "enum": ["reject", "queue", "degrade_read_only", "require_human_approval"] },
39+
"accountingMode": { "type": "string", "enum": ["admission_only", "admission_and_runtime"] }
40+
}
41+
}

‎schemas/RoutingContract.json‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.srcos.ai/v2/RoutingContract.json",
4+
"title": "RoutingContract",
5+
"description": "A typed routing and propagation contract that selects requests, tool calls, or sessions and directs them toward an execution fork or baseline target.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["id", "type", "specVersion", "name", "targets"],
9+
"properties": {
10+
"id": { "type": "string", "pattern": "^urn:srcos:routing-contract:" },
11+
"type": { "const": "RoutingContract" },
12+
"specVersion": { "type": "string" },
13+
"name": { "type": "string" },
14+
"description": { "type": "string" },
15+
"selectors": {
16+
"type": "object",
17+
"additionalProperties": false,
18+
"properties": {
19+
"headers": {
20+
"type": "array",
21+
"items": {
22+
"type": "object",
23+
"required": ["name", "op", "value"],
24+
"additionalProperties": false,
25+
"properties": {
26+
"name": { "type": "string" },
27+
"op": { "type": "string", "enum": ["equals", "contains", "prefix"] },
28+
"value": { "type": "string" }
29+
}
30+
}
31+
},
32+
"actorRef": { "type": ["string", "null"] },
33+
"branchRef": { "type": ["string", "null"] },
34+
"missionRef": { "type": ["string", "null"] },
35+
"trustClass": { "type": ["string", "null"] }
36+
}
37+
},
38+
"targets": {
39+
"type": "array",
40+
"items": {
41+
"type": "object",
42+
"required": ["name", "targetRef", "fallback", "writePolicy"],
43+
"additionalProperties": false,
44+
"properties": {
45+
"name": { "type": "string" },
46+
"targetRef": { "type": "string" },
47+
"port": { "type": ["integer", "null"], "minimum": 1, "maximum": 65535 },
48+
"fallback": { "type": "string", "enum": ["baseline", "deny"] },
49+
"writePolicy": { "type": "string", "enum": ["inherit", "isolated_only", "blocked"] }
50+
}
51+
}
52+
},
53+
"propagation": {
54+
"type": "object",
55+
"additionalProperties": false,
56+
"properties": {
57+
"traceContext": { "type": "string", "enum": ["w3c", "b3", "none"] },
58+
"extraHeaders": { "type": "array", "items": { "type": "string" } }
59+
}
60+
},
61+
"defaultDeny": { "type": "boolean" },
62+
"requireCapabilityToken": { "type": "boolean" },
63+
"readOnlySurface": { "type": "boolean" }
64+
}
65+
}

‎schemas/RunnerGroup.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.srcos.ai/v2/RunnerGroup.json",
4+
"title": "RunnerGroup",
5+
"description": "A versioned runtime bundle that supplies pinned images, built-in primitives, custom primitive extensions, and execution defaults for validations or protocol workbenches.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["id", "type", "specVersion", "name", "version", "runtime", "imageRef", "imageDigestPinned"],
9+
"properties": {
10+
"id": { "type": "string", "pattern": "^urn:srcos:runner-group:" },
11+
"type": { "const": "RunnerGroup" },
12+
"specVersion": { "type": "string" },
13+
"name": { "type": "string" },
14+
"version": { "type": "string" },
15+
"runtime": { "type": "string", "enum": ["container", "wasm", "local", "hybrid"] },
16+
"imageRef": { "type": "string" },
17+
"imageDigestPinned": { "type": "boolean" },
18+
"builtInPrimitives": { "type": "array", "items": { "type": "string" } },
19+
"customPrimitiveRefs": { "type": "array", "items": { "type": "string" } },
20+
"dependencyProfiles": { "type": "array", "items": { "type": "string" } },
21+
"networkPolicyRef": { "type": ["string", "null"] },
22+
"filesystemPolicy": { "type": "string", "enum": ["ephemeral", "retained", "read_only_base"] },
23+
"cachePolicy": { "type": "string", "enum": ["none", "ephemeral", "shared_read_only"] }
24+
}
25+
}

‎schemas/ToolExposurePolicy.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.srcos.ai/v2/ToolExposurePolicy.json",
4+
"title": "ToolExposurePolicy",
5+
"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.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["id", "type", "specVersion", "name", "version", "transport", "exposureMode"],
9+
"properties": {
10+
"id": { "type": "string", "pattern": "^urn:srcos:tool-exposure:" },
11+
"type": { "const": "ToolExposurePolicy" },
12+
"specVersion": { "type": "string" },
13+
"name": { "type": "string" },
14+
"version": { "type": "string" },
15+
"transport": { "type": "string", "enum": ["mcp", "tritrpc", "cli", "api"] },
16+
"exposureMode": { "type": "string", "enum": ["full", "read_only", "allow_list", "deny_list", "consent_gated"] },
17+
"policyRefs": { "type": "array", "items": { "type": "string" } },
18+
"defaultToolsets": { "type": "array", "items": { "type": "string" } },
19+
"includeTools": { "type": "array", "items": { "type": "string" } },
20+
"excludeTools": { "type": "array", "items": { "type": "string" } },
21+
"requireMutationConsent": { "type": "boolean" },
22+
"sensitiveDataMode": { "type": "string", "enum": ["blocked", "redacted", "allowed"] },
23+
"lockdownMode": { "type": "boolean" }
24+
}
25+
}

0 commit comments

Comments
 (0)