Skip to content

Commit 2f905e6

Browse files
mdhellermdheller
authored
Add deterministic release evidence bundle
Adds ReleaseEvidenceBundle schema, example, deterministic generator, validation wrapper, Makefile validation stage, package import validation, and release bundle architecture docs. Validation run 25335379781 passed successfully before merge.
1 parent 21957fb commit 2f905e6

10 files changed

Lines changed: 684 additions & 3 deletions

‎Makefile‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: validate validate-json validate-yaml validate-quadlet validate-render validate-evidence validate-governance validate-activation validate-supply-chain validate-package validate-cli validate-formula doctor probe
1+
.PHONY: validate validate-json validate-yaml validate-quadlet validate-render validate-evidence validate-governance validate-activation validate-supply-chain validate-release-bundle validate-package validate-cli validate-formula doctor probe
22

33
PYTHON ?= python3
44
RUBY ?= ruby
@@ -20,7 +20,7 @@ DECIDED_AT := 2026-05-04T12:51:00Z
2020
PYCLI := PYTHONPATH=src $(PYTHON) -m agent_machine.cli
2121
PYMOD := PYTHONPATH=src $(PYTHON) -m
2222

23-
validate: validate-json validate-yaml validate-quadlet validate-render validate-evidence validate-governance validate-activation validate-supply-chain validate-package validate-cli validate-formula
23+
validate: validate-json validate-yaml validate-quadlet validate-render validate-evidence validate-governance validate-activation validate-supply-chain validate-release-bundle validate-package validate-cli validate-formula
2424

2525
validate-json:
2626
$(PYTHON) scripts/validate-json.py
@@ -62,6 +62,10 @@ validate-supply-chain:
6262
$(PYTHON) scripts/validate-supply-chain.py
6363
$(PYMOD) agent_machine.supply_chain $(PINNED_AGENTPOD) --strict
6464

65+
validate-release-bundle:
66+
$(PYTHON) scripts/validate-release-bundle.py
67+
$(PYTHON) scripts/generate-release-evidence.py --pretty >/tmp/agent-machine-release-evidence-bundle.json
68+
6569
validate-package:
6670
$(PYTHON) scripts/validate-package.py
6771

‎contracts/release-evidence-bundle.schema.json‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "urn:srcos:agent-machine:schema:release-evidence-bundle:v0.1.0",
4+
"title": "ReleaseEvidenceBundle",
5+
"description": "Secret-free release evidence bundle tying together validation proof, commit identity, schema inventory, rendered artifact digests, supply-chain posture, and known blockers.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": [
9+
"specVersion",
10+
"id",
11+
"kind",
12+
"release",
13+
"source",
14+
"validation",
15+
"inventories",
16+
"renderedArtifacts",
17+
"supplyChain",
18+
"readiness",
19+
"knownBlockers",
20+
"receiptSafety",
21+
"generatedAt"
22+
],
23+
"properties": {
24+
"specVersion": { "type": "string", "const": "0.1.0" },
25+
"id": {
26+
"type": "string",
27+
"pattern": "^urn:srcos:agent-machine:release-evidence-bundle:[a-z0-9][a-z0-9-]*$"
28+
},
29+
"kind": { "type": "string", "const": "ReleaseEvidenceBundle" },
30+
"release": {
31+
"type": "object",
32+
"additionalProperties": false,
33+
"required": ["name", "maturity", "productionReady"],
34+
"properties": {
35+
"name": { "type": "string" },
36+
"maturity": { "type": "string", "enum": ["prototype", "bootstrap-ready", "release-candidate", "production-blocked", "production-ready"] },
37+
"productionReady": { "type": "boolean" },
38+
"notes": { "type": "array", "items": { "type": "string" } }
39+
}
40+
},
41+
"source": {
42+
"type": "object",
43+
"additionalProperties": false,
44+
"required": ["repository", "branch", "commitSha"],
45+
"properties": {
46+
"repository": { "type": "string" },
47+
"branch": { "type": "string" },
48+
"commitSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
49+
"pullRequest": { "type": ["integer", "null"], "minimum": 1 }
50+
}
51+
},
52+
"validation": {
53+
"type": "object",
54+
"additionalProperties": false,
55+
"required": ["canonicalCommand", "status", "workflowRunId", "workflowJobName"],
56+
"properties": {
57+
"canonicalCommand": { "type": "string" },
58+
"status": { "type": "string", "enum": ["passed", "failed", "unknown", "not-run"] },
59+
"workflowRunId": { "type": ["integer", "null"], "minimum": 1 },
60+
"workflowJobName": { "type": ["string", "null"] },
61+
"validatedAt": { "type": ["string", "null"] }
62+
}
63+
},
64+
"inventories": {
65+
"type": "object",
66+
"additionalProperties": false,
67+
"required": ["schemas", "examples", "docs"],
68+
"properties": {
69+
"schemas": { "$ref": "#/$defs/digestedFileList" },
70+
"examples": { "$ref": "#/$defs/digestedFileList" },
71+
"docs": { "$ref": "#/$defs/digestedFileList" }
72+
}
73+
},
74+
"renderedArtifacts": {
75+
"type": "array",
76+
"items": {
77+
"type": "object",
78+
"additionalProperties": false,
79+
"required": ["name", "artifactKind", "digest"],
80+
"properties": {
81+
"name": { "type": "string" },
82+
"artifactKind": { "type": "string" },
83+
"path": { "type": ["string", "null"] },
84+
"digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
85+
}
86+
}
87+
},
88+
"supplyChain": {
89+
"type": "object",
90+
"additionalProperties": false,
91+
"required": ["strictModeAvailable", "strictExamples", "mutableBootstrapExamples"],
92+
"properties": {
93+
"strictModeAvailable": { "type": "boolean" },
94+
"strictExamples": { "$ref": "#/$defs/digestedFileList" },
95+
"mutableBootstrapExamples": { "$ref": "#/$defs/digestedFileList" }
96+
}
97+
},
98+
"readiness": {
99+
"type": "object",
100+
"additionalProperties": false,
101+
"required": ["bootstrapReady", "productionReady", "releaseGateRef"],
102+
"properties": {
103+
"bootstrapReady": { "type": "boolean" },
104+
"productionReady": { "type": "boolean" },
105+
"releaseGateRef": { "type": "string" },
106+
"statusRef": { "type": ["string", "null"] }
107+
}
108+
},
109+
"knownBlockers": {
110+
"type": "array",
111+
"items": { "type": "string" },
112+
"uniqueItems": true
113+
},
114+
"receiptSafety": {
115+
"type": "object",
116+
"additionalProperties": false,
117+
"required": ["includeRawContent", "rawPromptContentIncluded", "rawKvCacheContentIncluded", "secretValuesIncluded", "privateMemoryIncluded"],
118+
"properties": {
119+
"includeRawContent": { "type": "boolean", "const": false },
120+
"rawPromptContentIncluded": { "type": "boolean", "const": false },
121+
"rawKvCacheContentIncluded": { "type": "boolean", "const": false },
122+
"secretValuesIncluded": { "type": "boolean", "const": false },
123+
"privateMemoryIncluded": { "type": "boolean", "const": false }
124+
}
125+
},
126+
"generatedAt": { "type": "string" }
127+
},
128+
"$defs": {
129+
"digestedFileList": {
130+
"type": "array",
131+
"items": {
132+
"type": "object",
133+
"additionalProperties": false,
134+
"required": ["path", "digest"],
135+
"properties": {
136+
"path": { "type": "string" },
137+
"digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
138+
}
139+
}
140+
}
141+
}
142+
}

‎docs/architecture/release-evidence-bundle.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Release Evidence Bundle
2+
3+
Agent Machine release evidence bundles are deterministic, secret-free summaries of what was validated, what source revision was evaluated, which contract/example/doc inventories were present, which rendered artifacts were derived, what supply-chain posture was available, and which blockers remain.
4+
5+
A bundle is not a signature by itself. It is the structured payload that future signing, transparency, and release-promotion flows can sign and publish.
6+
7+
## Decision
8+
9+
Agent Machine defines a `ReleaseEvidenceBundle` contract for bootstrap and release-candidate evidence.
10+
11+
The bundle records:
12+
13+
- repository identity;
14+
- branch and commit SHA;
15+
- optional pull request number;
16+
- validation command and workflow run ID;
17+
- schema inventory with file digests;
18+
- example inventory with file digests;
19+
- documentation inventory with file digests;
20+
- rendered artifact digests;
21+
- supply-chain strict-mode availability;
22+
- readiness state;
23+
- known blockers;
24+
- receipt-safety flags.
25+
26+
## Current implementation
27+
28+
Implemented now:
29+
30+
- `contracts/release-evidence-bundle.schema.json`;
31+
- `examples/release-evidence-bundle.bootstrap.json`;
32+
- `src/agent_machine/release_bundle.py`;
33+
- `scripts/generate-release-evidence.py`;
34+
- `scripts/validate-release-bundle.py`;
35+
- `make validate-release-bundle`.
36+
37+
## Validation commands
38+
39+
Generate a bundle from the current checkout:
40+
41+
```bash
42+
python3 scripts/generate-release-evidence.py --pretty
43+
```
44+
45+
Validate bundle example and generated output:
46+
47+
```bash
48+
python3 scripts/validate-release-bundle.py
49+
```
50+
51+
Full validation:
52+
53+
```bash
54+
make validate
55+
```
56+
57+
## Bootstrap behavior
58+
59+
The bootstrap bundle is intentionally secret-free and production-blocked. It may report `validation.status=unknown` when generated outside CI, but it still validates its schema, inventories, rendered artifact digests, supply-chain posture, known blockers, and receipt-safety posture.
60+
61+
## Release-candidate behavior
62+
63+
A release candidate should set:
64+
65+
```text
66+
validation.status = passed
67+
validation.workflowRunId = <green run id>
68+
source.commitSha = <validated commit sha>
69+
source.pullRequest = <PR number, if applicable>
70+
```
71+
72+
It must also have no unresolved release-candidate blockers for the relevant maturity level.
73+
74+
## Production blockers
75+
76+
The current bundle deliberately retains production blockers, including:
77+
78+
- main-branch CI visibility and branch protection policy;
79+
- real image signature/provenance verification;
80+
- real Policy Fabric client or endpoint;
81+
- real Agent Registry grant resolver;
82+
- real AgentPlane evidence submission or staging client;
83+
- local LVM provisioning/probe implementation;
84+
- TopoLVM runtime integration beyond skeleton manifests;
85+
- provider discovery and controlled provider activation;
86+
- M2 Asahi host measurement and provider readiness data;
87+
- signed release evidence bundle;
88+
- rollback, teardown, and wipe workflows.
89+
90+
## Future hardening
91+
92+
Future release bundle work should add:
93+
94+
- signed bundle envelopes;
95+
- provenance attestation references;
96+
- transparency-log submission references;
97+
- generated SBOM references;
98+
- real image signature verification result;
99+
- branch protection status;
100+
- release artifact digests;
101+
- rollback and wipe evidence references.

‎docs/index.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Agent Machine is a bootstrap runtime-control substrate for SourceOS agent worklo
2121
| [Deployment safety](architecture/deployment-safety.md) | Skeleton-vs-production manifest rules and safety gates. |
2222
| [Receipt chain](architecture/receipt-chain.md) | AgentPod source to plan, manifest, receipt, policy, registry, and AgentPlane evidence. |
2323
| [Image digest pinning and provenance](architecture/image-digest-pinning-and-provenance.md) | Supply-chain strict-mode gate for digest-pinned release-candidate artifacts. |
24+
| [Release evidence bundle](architecture/release-evidence-bundle.md) | Deterministic validation/source/inventory/render/supply-chain/readiness bundle. |
2425
| [Runtime package layout](architecture/runtime-package-layout.md) | Migration from loose scripts to `src/agent_machine/` package modules. |
2526
| [Homebrew Python dependencies](architecture/homebrew-python-dependencies.md) | Current dependency strategy for render/evaluation commands. |
2627
| [Local LVM and TopoLVM profile](architecture/local-lvm-and-topolvm-profile.md) | Local and Kubernetes storage/cache/evidence profile. |
@@ -71,6 +72,7 @@ Important contract families:
7172
| `PolicyAdmission` | Policy Fabric admission decision/stub. |
7273
| `AgentRegistryGrant` | Agent Registry grant/stub. |
7374
| `ActivationDecision` | Final dry-run activation decision. |
75+
| `ReleaseEvidenceBundle` | Secret-free release validation/source/inventory/render/supply-chain/readiness evidence. |
7476

7577
## Validation
7678

@@ -91,6 +93,7 @@ validate-evidence
9193
validate-governance
9294
validate-activation
9395
validate-supply-chain
96+
validate-release-bundle
9497
validate-package
9598
validate-cli
9699
validate-formula
@@ -111,5 +114,5 @@ Current blockers:
111114
- TopoLVM runtime integration beyond skeleton manifests;
112115
- provider discovery and controlled provider activation implementation;
113116
- M2 Asahi host measurement/provider readiness data;
114-
- release evidence bundle;
117+
- signed release evidence bundle;
115118
- rollback, teardown, and wipe workflows.

‎examples/release-evidence-bundle.bootstrap.json‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
{
2+
"specVersion": "0.1.0",
3+
"id": "urn:srcos:agent-machine:release-evidence-bundle:bootstrap-v0-example",
4+
"kind": "ReleaseEvidenceBundle",
5+
"release": {
6+
"name": "agent-machine-bootstrap-v0",
7+
"maturity": "bootstrap-ready",
8+
"productionReady": false,
9+
"notes": [
10+
"Example bundle shape only.",
11+
"The generator produces a complete bundle from repository contents."
12+
]
13+
},
14+
"source": {
15+
"repository": "SourceOS-Linux/agent-machine",
16+
"branch": "main",
17+
"commitSha": "0cba4c4774982ce4705c27f7c4ec1c0bcdfb0725",
18+
"pullRequest": 11
19+
},
20+
"validation": {
21+
"canonicalCommand": "make validate",
22+
"status": "passed",
23+
"workflowRunId": 25327418937,
24+
"workflowJobName": "Validate contracts, examples, CLI, formula, and docs",
25+
"validatedAt": "2026-05-04T15:21:00Z"
26+
},
27+
"inventories": {
28+
"schemas": [
29+
{
30+
"path": "contracts/release-evidence-bundle.schema.json",
31+
"digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
32+
}
33+
],
34+
"examples": [
35+
{
36+
"path": "examples/local-podman-llama-cpp.agent-pod.json",
37+
"digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
38+
}
39+
],
40+
"docs": [
41+
{
42+
"path": "BOOTSTRAP_STATUS.md",
43+
"digest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
44+
}
45+
]
46+
},
47+
"renderedArtifacts": [
48+
{
49+
"name": "local-agentpod-plan",
50+
"artifactKind": "AgentPodDeploymentPlan",
51+
"path": null,
52+
"digest": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
53+
}
54+
],
55+
"supplyChain": {
56+
"strictModeAvailable": true,
57+
"strictExamples": [
58+
{
59+
"path": "examples/local-podman-llama-cpp.pinned.agent-pod.json",
60+
"digest": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
61+
}
62+
],
63+
"mutableBootstrapExamples": [
64+
{
65+
"path": "examples/local-podman-llama-cpp.agent-pod.json",
66+
"digest": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
67+
}
68+
]
69+
},
70+
"readiness": {
71+
"bootstrapReady": true,
72+
"productionReady": false,
73+
"releaseGateRef": "docs/architecture/world-class-release-gate.md",
74+
"statusRef": "BOOTSTRAP_STATUS.md"
75+
},
76+
"knownBlockers": [
77+
"main-branch-ci-visibility-and-branch-protection-policy",
78+
"real-policy-fabric-client-or-endpoint",
79+
"real-agentplane-evidence-submission-or-staging-client"
80+
],
81+
"receiptSafety": {
82+
"includeRawContent": false,
83+
"rawPromptContentIncluded": false,
84+
"rawKvCacheContentIncluded": false,
85+
"secretValuesIncluded": false,
86+
"privateMemoryIncluded": false
87+
},
88+
"generatedAt": "2026-05-04T15:21:00Z"
89+
}

0 commit comments

Comments
 (0)