Schemas, Conformance Packs and the ops Toolchain
What the versioned Supporting Tools schemas hosted under /aes/v0.1.0/ require, how to validate against them, where the source specification contradicts itself, and what the planned ops CLI, Claude plugins and service conventions define.
- Version
- 0.1.0
- Owner
- DEIXEI
- Last reviewed
- Reading time
- 30 min
For Ai Architect · Platform Engineer · Release Engineer · Risk And Assurance · Internal Audit
Sources and details
- Section
- Reference
- Source works
- Supporting Tools · Book 1 · Book 2 · Book 3 · Research Series
- Source appendices
- 01:B, 02:A, 02:B, 04:E, 04:J
- Tool specifications
- audit_evidence_schema@0.1.0, cab_decision_record@0.1.0, deployer_manifest@0.1.0
- Refresh trigger
- source change
This page is the field reference for the machine-readable contracts behind the audit spine. Use it when you are:
- building a producer that must emit valid records;
- writing a validator or consumer;
- reviewing whether a vendor’s “conformance” claim means anything;
- deciding whether to adopt the planned
opstoolchain.
How to use the records is covered elsewhere. Audit evidence explains how to design and read records, change governance covers CAB decisions, and release engineering covers deployment gates. The glossary defines the vocabulary.
What is hosted, and its status
All three specifications are v0.1.0, candidate status, in the Supporting Tools work-stream. The JSON files below are served by this site at the URLs that match each schema’s $id. The schema bodies are identical to the Supporting Tools source files. The example files were edited for publication: hostnames and user names use the reserved documentation domain bank-a.example. Every example describes the Bank A composite credit-scoring agent, not a real deployment.
| File (served URL) | $id / role | Source file | Validated example | Used on |
|---|---|---|---|---|
/aes/v0.1.0/audit_evidence_schema.json | AES predicate, JSON Schema draft 2020-12 | audit_evidence_schema.v0.1.0.json | examples/credit_scoring_action.predicate.json; examples/credit_scoring_action.intoto.json (full in-toto Statement) | Audit evidence, Enterprise control plane, Agent lifecycle, Control map |
/aes/v0.1.0/cab_change.json | CAB change file: input to ops cab evaluate | cab_change.v0.1.0.json | examples/cs_v2.4.0_change.json | Change governance |
/aes/v0.1.0/cab_decision.json | CAB decision record: output | cab_decision.v0.1.0.json | examples/cs_v2.4.0_decision.json (go-with-conditions) | Change governance |
/aes/v0.1.0/deployer_manifest.json | Deployer manifest: input to ops deploy | deployer_manifest.v0.1.0.json | examples/cs_v2.4.0_manifest.json | Release engineering, Landing zone |
The three CAB and deployer examples form one chain. (The AES example is a separate scoring action with change_id: null.) Change chg-2026-05-14-cs-v2.4.0 produces a go-with-conditions decision whose change_ref names that change. The manifest depl-2026-05-15-cs-v2.4.0 then points at the same change through preflight.required_cab_decision. All five example files validated against their schemas when this page was written (Draft 2020-12 validator, 14 November 2026).
Not hosted on this site. The chk_pack_format specification, the conformance test packs, the event-kind payload schemas, the OpenAPI files and any CLI binary exist only in the Supporting Tools source or not at all. The site serves no index page at /aes/ or /aes/v0.1.0/, although Book 3 Appendix E cites https://www.deixei.com/aes/ as the specification’s home.
Publication gaps to close before treating the URLs as a trust anchor (b05-07)
The Supporting Tools website specification (sections 2.2 to 2.5) describes more than the site currently provides:
| Website specification calls for | Current state on this site | Consequence for adopters |
|---|---|---|
A spec landing at /spec/ with schema badge, status, signer, changelog and book cross-references | Not present | No public statement of status or changelog beyond this page |
Versioned URLs of the form /spec/audit-evidence-schema/v0.1.0/schema.json | Not used; files are served at the $id path /aes/v0.1.0/<name>.json | The two path conventions conflict inside the source. This page follows the $id values, because validators resolve $id and the books cite /aes/. |
Signed publication: Sigstore identity, Rekor entries, key fingerprints, rotation log at /trust/ | Not present; no signature or checksum files next to the JSON | Integrity of a fetched schema cannot be verified against a published trust root |
An in-browser verifier at /verify/ checking pack signature, in-toto envelope, AES validity and transparency-log presence | Not present | Verification must be done with your own tooling |
| Signed release notes per version | Not present; this site’s /releases/ collection is for product release notes, not the specification | Track version changes from this page and the Supporting Tools source |
The site specification’s editorial rule is that versioned URLs are forever: content at a versioned path does not move, and errata are added rather than files rewritten. Treat that as the owner’s stated intent, not yet as a published commitment.
Recommendation for adopters, pending trust roots:
- Vendor the three schema files into your own repository.
- Record the SHA-256 digest of each file and the date you fetched it.
- Validate producers against your vendored copy.
- Re-fetch and compare digests before moving to a new version.
Never resolve the schema live from a production validator.
Reuse and licence terms (b05-72)
The owner has not yet confirmed the reuse terms for the hosted files. Until a licence statement is published beside them, treat their reuse terms as unconfirmed. The source records the intended terms below; they are the source’s statement, not a grant made by this page.
| Component | Intended licence (Supporting Tools README; D11.1 as amended; D33) |
|---|---|
| Specification content: JSON Schemas, normative documents, conformance vectors as data | CC-BY-4.0 |
| Reference implementation: CLI, services, infrastructure, portal, plugins, harness runner | Business Source License 1.1, each release converting to Apache 2.0 four years after release. Additional Use Grant: production use inside a single legal entity is permitted; offering it across legal entities (as a service, packaged in a vendor product, multi-tenant) needs a commercial licence. |
| Example content: sample packs, example AES records, the credit-scoring worked example | CDLA-Permissive-2.0 |
Two further intentions are stated in the source. A vendor implementing the API specification independently needs no licence from the owner, only the wire format and conformance (API conventions section 12). Commercial licence terms are to be published at deixei.com/license/. That page does not exist on this site. The spec is governed by the owner and not donated to a foundation; donation is a deferred decision. [FACT-CHECK: owner to confirm the licence for each hosted file and publish a LICENSE notice under /aes/ before external reuse is invited.]
How the records are layered on the wire
Sigstore signature (not redefined by the spec)
└── in-toto v1 Statement (not redefined by the spec)
├── _type: "https://in-toto.io/Statement/v1"
├── subject: [ {name, digest:{sha256}} ]
├── predicateType: "https://www.deixei.com/aes/v0.1.0"
└── predicate: AES record ← the only part audit_evidence_schema.json validates
The specification owns the predicate only. predicateType is an identifier and does not resolve to a document. A full conformance check of a Statement has three parts:
- the Statement is a valid in-toto v1 Statement;
predicateTypeequalshttps://www.deixei.com/aes/v0.1.0;predicatevalidates against the AES schema.
The CAB and deployer artefacts can stand alone as JSON. The CAB README is explicit that only the AES-wrapped form is evidentially defensible.
| Artefact | Wrapped as | action.parameters | outcome.output |
|---|---|---|---|
| CAB evaluation | kind = cab.evaluate, action.verb = evaluated-change | the cab_change | the cab_decision |
| Deployment apply | kind = deployer.apply (Deployer README) | the manifest | the deployment result |
parameters_schema_ref may point at either schema. The CAB decision has no record identifier of its own. Its identity is the wrapping AES record_id, which is what later events such as cab.refuse cite.
Audit Evidence Schema v0.1.0
Envelope fields
additionalProperties: false applies at the top level and inside every group. A producer cannot add fields anywhere except inside the three free-form objects described below.
| Field | Required | Rule |
|---|---|---|
schema_version | yes | ^\d+\.\d+\.\d+$ |
record_id | yes | non-empty string; ULID or UUID recommended |
session_id | yes | non-empty; join key for one work unit |
kind | yes | ^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$: exactly two lower-case segments, no hyphens |
change_id | no | string or null; join key for a change |
payload | no | object, untyped; kind-specific extension |
parameters_schema_ref | no | URI of a kind-specific schema constraining action.parameters, outcome.output and payload |
The nine groups
| Group (question) | Required inside | Enums and conditional rules |
|---|---|---|
initiator (who initiated?) | type, then per branch: human user_upn, channel, session_start; agent upstream_agent_id; scheduled schedule_id, trigger_event | oneOf on type ∈ {human, agent, scheduled}. Only the human branch allows on_behalf_of {is_delegation, access_package} and session_ref; the agent branch allows chain[]. |
executing_agent (which agent?) | agent_id, agent_version, deployment_environment, zone | zone ∈ {development, diagnostic, remediation, privileged-incident}; optional system_prompt_sha256 must be 64 lower-case hex; optional agent_id_claim, system_prompt_version, control_plane_registry_record |
envelope_snapshot (under what envelope?) | registry_version, mandate_digest, means.tools[] (each name, version), memory.read_scopes[], memory.write_scopes[], monitoring.workspace, monitoring.rule_set, monitoring.evaluation_cadence | memory.retention optional |
action (what action?) | verb, target.entity, target.id, parameters (object) | downstream_effects[], target.label, target.context_ref optional |
data[] (on what data?) | each entry: operation, dataset_id, classification | operation ∈ {read, write, read_write}; classification ∈ {public, internal, confidential, restricted, regulated}; an empty array is a valid, explicit “no data” |
model[] (with which model?) | each entry: model_id, role | optional model_sha256, registry_record, endpoint, region, deployment_id; an empty array is a valid, explicit “no model” |
approval (approved by whom?) | required, policy_decision_id, policy_version, rationale | if required = true then workflow_id and approvers[] are required; each approver needs upn, role, timestamp (ticket_ref optional). required = false still needs the policy decision and rationale that allowed it. |
time (when?) | initiation, completion (date-time), duration_ms (≥ 0) | optional end_to_end_latency_ms, clock_source, clock_last_sync, clock_drift_ms |
outcome (with what outcome?) | result, output (object), evidence_pointers[] (each type, ref) | result ∈ {SUCCESS, FAILURE, PARTIAL}; side_effects[] optional |
Key rules for producers:
- Every record answers all nine groups. Empty
dataandmodelarrays are answers; absent groups are failures. - “No approval” is still evidence. The record must carry the policy decision, its version and a rationale.
- Domain detail goes only in
action.parameters,outcome.outputorpayload. Constrain it by publishing a kind-specific schema and pointing at it withparameters_schema_ref. The use-case documents call this fieldpayload_schema_ref; the schema field isparameters_schema_ref. - Data classification uses the AES enum, not your local labels. Agree the mapping from the firm’s scale once (see the glossary data-class crosswalk).
- Timestamps are UTC with sub-second precision (schema description of
time). Record clock source and drift where the producer can.
CAB change file v0.1.0 (cab_change.json)
| Field | Required | Rule |
|---|---|---|
schema_version, change_id, summary, description | yes | non-empty strings; version pattern as for AES |
change_type | yes | ∈ {app_deploy, infra_change, data_migration, emergency_fix, config_change, other} |
submitter | yes | team, submitted_at required, plus exactly one of user_upn (human) or agent_id (orchestrator agent) |
target | yes | environment, systems[] (at least one); regions[] optional |
risk | yes | level ∈ {low, medium, high, critical}, rationale |
customer_impact | yes | expected (boolean), description; blast_radius optional |
rollback | yes | plan_description; command_ref optional |
test_evidence[] | yes | each: type ∈ {test_run, scan, review, other}, ref, result ∈ {pass, fail, n/a} |
monitoring | yes | dashboards[], alerts[], post_change_check_window (ISO 8601 duration) |
security_compliance | yes | impact (boolean), description, chk_guidance_refs[] |
approvers_required[] | yes | each: role; specific_upn optional |
policy_template, policy_template_version | yes | the CAB template the change is evaluated against |
target_window | no | start, end |
CAB decision record v0.1.0 (cab_decision.json)
| Field | Required | Rule |
|---|---|---|
decision | yes | ∈ {go, go-with-conditions, no-go, needs-review, superseded} |
policy_template, policy_template_version, change_ref | yes | change_ref names the change evaluated |
conditions[] | yes | each: id, description, must_complete_before ∈ {deploy, promote, continue, other}, evidence_required. Must be non-empty when decision = go-with-conditions. |
reasoning[] | yes, at least one | each: rule_id, passed, rationale. Records every rule, passed or failed (D18.4), so “why did this pass” is auditable. |
evidence_consulted[] | yes | each: type, ref; the same shape as AES evidence_pointers |
approvers_required[] | yes | each: role, fulfilled; fulfilled = true requires upn and approval_record_ref |
expires_at | no | date-time after which the decision cannot be relied on |
superseded_by | conditional | required when decision = superseded |
Operating rules from the use cases:
- Decisions are never edited, only superseded.
- An expired template with risk
highor above is refused (exit 4). - Emergency decisions need approver attestation after the fact within 24 hours. If attestation does not arrive, the centre raises a high-priority alert (UC-cab-4).
- A chair’s refusal of an evaluated decision is a separate event kind,
cab.refuse, distinct fromno-goandsuperseded.
Deployer Manifest v0.1.0 (deployer_manifest.json)
A manifest reads top to bottom as the workflow ops deploy executes:
artefact → target → backend → preflight → apply → verify → rollback
All of these sections are required. There is one artefact per manifest; multi-artefact orchestration sits above the schema in CI/CD and is joined by change_id (D19.1).
| Section | Required inside | Rules |
|---|---|---|
manifest_id, schema_version | yes | as above |
artefact | name, version, kind | kind ∈ {container_image, helm_chart, terraform_module, bicep_module, function_app, static_files, custom}; optional digest.sha256 (64 hex) or digest.sha512 (128 hex) |
target | environment, systems[] (at least one) | regions[] optional |
backend | type, config | type ∈ {helm, kubernetes, terraform, opentofu, bicep, azure_cli, aws_cli, gcp_cli, docker, ssh, custom}; config untyped, constrained by optional config_schema_ref |
preflight | checks[], required_chk_guidance[], required_cab_decision | required_cab_decision is always present: a CAB change_id reference or null. If null, a non-empty cab_exemption_rationale citing the exempting policy is required. |
apply | intent, program, args[], timeout (ISO 8601 duration) | env map optional |
verify | wait_window, health_checks[] | at least one health check |
rollback | intent, program, args[], timeout, verification[] | verification required (there is no unverified rollback path); automatic_triggers[] optional and metric-only in v0.1 |
metadata | owner_team, agent_wrangler_upn | a deployment without a named human owner cannot run |
promotion | optional; if present from_environment, to_environment, approval_required |
Checks. preflight.checks, verify.health_checks and rollback.verification share one check definition, a union on kind:
| Check kind | Required fields |
|---|---|
http | id, description, kind, url, expected_status (100–599), timeout |
command | id, description, kind, program, expected_exit_code, timeout |
metric | id, description, kind, query_kind ∈ {kql, promql, other}, query, expected_condition, evaluation_window |
Each check also has required, defaulting to true. The centre’s exception engine evaluates automatic rollback triggers and signals down through edge to leaf. The ops deploy use cases add run-time refusals the schema cannot express:
- the referenced decision is missing or
no-go; - a
go-with-conditionsdecision still has an unmet condition; - any preflight check fails (exit 4).
A network failure during apply is never auto-retried; it goes to a human.
Versioning and compatibility
| Rule | Source |
|---|---|
Strict semantic versioning. The whole 0.x series is one compatibility band: optional fields, new kind values and backward-compatible tightening may be added; existing names, required lists and types do not change. | versioning.md; D13.3 |
| Anything that breaks a conforming 0.x producer or consumer needs a major bump. 1.0.0 locks the structural contract; each later major comes with a documented deprecation window for the previous one. | versioning.md |
Books pin a floor and an implicit ceiling at the next major: conforming to any version >= 0.1.0, < 1.0.0 satisfies a book written against 0.1.0. | versioning.md; Book 3 App E |
| Patch or minor within the floor’s major: no book change. New major: reprint or erratum, depending on whether prose claims are affected. | versioning.md |
Services advertise their supported range in /version and in a response header, X-AES-Version-Range: >=0.1.0,<1.0.0. The previous API major stays at a versioned path for at least 12 months of overlap. | API conventions section 10 |
Acceptance check for a consumer: it rejects a record whose schema_version major is above what it declares it understands, and it accepts unknown optional fields only where the 0.x band allows them. In v0.1.0 that means only inside the free-form objects, because every group is closed.
Conformance
v0.1.0 vectors for the three schemas (b05-56)
Conformance is a release artefact, not a runtime check. A producer claims conformance to a version by running its output through that version’s vectors. The README lists these cases:
| Schema | Positive cases | Required negative cases (must fail) |
|---|---|---|
| AES | predicate example validates; the in-toto example is a valid Statement with the right predicateType and a valid predicate | approval removed; approval.required = true without workflow_id or approvers |
| CAB | change example and decision example validate; a change with an agent submitter and no user_upn validates | submitter with neither user_upn nor agent_id; go-with-conditions with empty conditions; superseded without superseded_by; approver fulfilled = true without upn or approval_record_ref |
| Deployer | manifest example validates; required_cab_decision = null with a populated cab_exemption_rationale validates | null CAB reference without rationale; unknown check kind (for example tcp); http check without url; backend.type outside the enum (for example ansible); empty verify.health_checks; rollback without verification |
The harness specification (M11 section 5) refers to “seven negative cases” for the deployer. The conformance README lists six. Test the six, and treat the seventh as unspecified until the source defines it.
Recommended producer acceptance gate (this page’s recommendation):
- Run every positive and negative case above in CI on each producer change.
- Add one negative case per conditional rule you rely on.
- Fail the build if a negative case passes.
- Keep the run output as release evidence.
Event-kind payload contracts (b05-57)
A later pass over the source added about 20 kind values for service-tier events. Each one keeps the AES envelope and requires specific payload fields. The source calls them normative at v0.1.0 for producers and consumers, but each kind is also labelled “draft v0.1”, and no payload schemas are published.
| Kind | Required payload fields | Notable negative rules |
|---|---|---|
cab.refuse | refuser_upn, refusal_reason, refuses_decision_record_id | empty reason fails |
rollback.signal | rollback_id, deployment_id, trigger_metric, threshold, measured_value, signalled_at | at-most-once delivery; rollback_id unique within 24 h |
alert.routed | alert_id, source_kind, severity ∈ {P1, P2, P3, info}, destinations[] (each target, delivery_outcome) | empty destinations fail |
gateway.request | gateway_id, model_id, prompt_hash (SHA-256), tool_signatures[], request_options | every gateway record carries a registry-resolved executing_agent.agent_id_claim and a session_id joining request to response |
gateway.response | gateway_id, response_hash, model_id, finish_reason ∈ {stop, length, tool_use, refusal, error}, cost (token counts, currency, total) | negative token counts fail |
gateway.refusal | refusal_class ∈ {safety, policy, capability, other}, refusal_text_hash, model_id | |
gateway.tool_use | tool_name, tool_version, tool_invocation_id, parameters_hash, result_hash, duration_ms | one record per tool call |
gateway.safety_event | classifier_id, classifier_version, triggered_category, severity, action_taken ∈ {blocked, flagged, passed_with_note} | |
pack.publish | pack_id, pack_version, pack_class ∈ {advisory, controlled, mandatory}, publisher_upns[], approver_upns[], signature_ref | no sole author above advisory; a recall sets recall_reason and must name a previously published version |
agent.provisioned / agent.retired | provisioned: agent_id, agent_id_claim, envelope_version, wrangler_upn, signing_key_ref, first_pack_versions[], acb_approval_record_id; retired: agent_id, retirement_reason, retention_start_at, retention_class, final_session_id, acb_retirement_record_id | provisioning is idempotent: a replay yields the same record, not a duplicate |
retention.delete, legalhold.applied, legalhold.released | delete: retention_class, target_records[], policy_version; applied: hold_id, applied_by_upn, legal_matter_ref, target_filter, applied_at; released: hold_id, released_by_upn, released_at, release_rationale | a delete overlapping an active hold is rejected; a release without a prior hold fails |
conformance.run | candidate_implementation, test_pack_id, test_pack_version, outcome ∈ {pass, fail, partial}, result_summary | passed + failed + skipped must equal total |
query.run | requester_upn, reader_role ∈ {wrangler, auditor, soc, supervisor, second_line, internal_audit, regulator}, query_filter, record_count, duration_ms, output_format ∈ {streaming_jsonl, bulk_parquet} | queries on the spine are themselves recorded |
chaos.exercise; forwarder.batch.sent, forwarder.batch.acked, forwarder.backoff | chaos: exercise_id, exercise_class, start_at, end_at, outcome, measured_rto_ms, measured_rpo_ms; forwarder: batch and acknowledgement fields | an ack without a prior send fails; backoff needs attempt ≥ 1 |
The gateway examples in the source name a Claude model and an Azure AI Foundry gateway identifier. They are illustrations dated May 2026, not statements about which models or regions are available [FACT-CHECK: current model identifiers and Foundry regions before reusing them]. Some rules, such as the sum check on result_summary or “a prior send must exist”, cannot be expressed in JSON Schema. A harness must check them with code.
The executable packs live in spec/conformance/event_kinds/: 9 pack files and 43 cases. The README counts 20 positive and 23 negative cases; the files contain 21 and 22. Each pack declares test_pack_id, test_pack_version, covers_kinds, covers_adrs and spec_version. Each case has case_id, expected (validate_pass or validate_fail), an expected_error_path (JSONPath) for negatives, and a full AES record.
The conformance harness and badges (b05-55)
The source specifies an M11 conformance harness, to be hosted at deixei.com/conformance/. It is not built, and no such page exists on this site.
- Modes. In hosted mode the vendor submits an endpoint or container and the harness runs the tests. In self-service mode the vendor downloads a signed pack with a reference runner and submits signed results.
- Badge variants.
passing;passing-with-notes(non-fatal warnings such as missing optional fields);not-passing, which is never published (the endpoint returns 404 and the report is kept internally). - Badge discipline. A spec maintainer reviews the report by hand before any badge is published; the badge is an endorsement, not an automatic grant. Badges expire after 12 months, and keeping one live requires re-submission against the latest version. Re-submission after a failure carries no penalty.
- Targets. Test run p99 within 10 minutes; harness availability at least 99.5%; badge update within 1 hour of a pass; packs published within 24 hours of a spec release; vendor false-pass rate 0%.
- Self-audit. Every run emits
conformance.run, plus badge-published, badge-expired and re-submitted events. - Licence acknowledgement. Passing grants use of the badge, not a licence to redistribute the implementation.
The harness’s test pack format (a zip with manifest.yaml, vectors/, behavioural/ and runner/) differs from the single-JSON pack files in event_kinds/. The source does not reconcile them. Behavioural assertions, such as an emit-latency budget at p99, appear only in the zip format.
How to read a vendor’s conformance claim. Ask four questions:
- Which pack ID and version, against which spec version?
- Hosted or self-service?
- When does the badge expire?
- Can you see the report?
Until the harness exists, there is no public badge, so any “AES-conformant” claim is self-asserted.
Known inconsistencies inside the source specification (b05-58)
These are contradictions inside the Supporting Tools material, recorded here so that adopters do not discover them in production. The author corrects the source; this site does not change the schemas.
On 14 November 2026 this page’s author validated all 43 event-kind test cases against the hosted AES v0.1.0 schema with a JSON Schema Draft 2020-12 validator. All 21 positive cases fail. The 22 negative cases fail too, but none fails at its expected_error_path. They fail on envelope errors instead, and because no payload schemas are published, the AES schema cannot reach the payload rules those negatives target. The packs therefore cannot yet show conformance either way. The causes:
| Inconsistency | Where | Effect |
|---|---|---|
outcome.result values such as SUBMITTED, REFUSED, ROUTED, PUBLISHED, SUPERSEDED and SIGNAL_SENT | event-kind packs | outside the enum {SUCCESS, FAILURE, PARTIAL}; a lifecycle state is being carried in a result field |
initiator.type = "service" with service_id (19 cases); agent initiators using agent_id and channel | event-kinds README; packs | the AES union admits only human, agent (upstream_agent_id) and scheduled; service-tier events have no valid initiator |
Required envelope fields left out (action.parameters, approval.rationale, approval.policy_decision_id, approval.policy_version, time.duration_ms, outcome.evidence_pointers, envelope means, memory and monitoring) | packs | each case is invalid before its payload is even checked |
gateway_id placed in executing_agent | gateway pack | executing_agent is closed (additionalProperties: false) |
Kind names with three segments or hyphens: forwarder.batch.sent, forwarder.batch.acked, deploy.apply.start, deploy.apply.end, deploy.preflight.exempt, chk.advise.warning, chk.refresh.signature-invalid, cab.followup-required | packs; ops use cases | the kind pattern allows exactly two segments of [a-z0-9_] |
Kind-name drift: the schema description and Deployer README say deployer.apply, the use cases emit deploy.apply.*; the schema description says opslog.decision, ops log emits log.decision | schema kind description; use cases | consumers keyed on kind names will miss records |
outcome.status = failure, outcome = unknown, redaction_applied, initiator.agent_id and an agent-branch on_behalf_of | ops run and ops deploy use cases | none of these fields or values exist in the schema |
cab_decision_max_age used to refuse stale decisions | UC-deploy-2 | not a field in the closed manifest schema |
| Emergency changes “auto-marked superseded” when attestation lapses | UC-cab-4 | a superseded decision requires superseded_by, and none exists in this path |
payload_schema_ref | use-case README | the schema field is parameters_schema_ref |
| Three test packs at launch (D31.1) versus five (M11 section 5); “seven” deployer negatives versus six listed | decisions log; M11; conformance README | conformance scope is ambiguous |
/spec/<name>/v0.1.0/schema.json versus /aes/v0.1.0/<name>.json | website spec section 2.2; schema $id | two URL conventions (b05-07) |
| Exit code 5 used for an approver failing MFA (UC-cab-2), while the shared convention defines 5 as a transient infrastructure error | use cases | automation may retry an authorisation failure |
What to do until the source is corrected:
- Do not treat the event-kind packs as passing evidence.
- Validate your own records against the published schema, which is the normative artefact, and file a deviation against the source rather than relaxing the schema locally.
- If you need service-originated events now, pick one documented workaround and record it as an ADR. Two options: emit them with
initiator.type = scheduledwhere a schedule triggered them, or keep them outside the AES stream until a schema version admits a service initiator. Neither option is sanctioned by the source.
The ops reference toolchain (designed, not built)
As of the source’s last status, the CLI binaries, crates, plugins and centre runtime are not implemented. They are scheduled for a later roadmap phase. Everything below describes intended behaviour. Use it to shape your own tooling or to evaluate the implementation when it ships.
One binary: five subcommands and a diagnostic (b05-21)
| Subcommand | Concept tool | Purpose | Sub-actions | Main AES kinds |
|---|---|---|---|---|
ops run | ops | Wraps a command with mandatory intent; signed JSONL | (wrap) | ops.run, session.open, session.close |
ops log | opslog | Typed, append-only journal of intent, decisions, observations, risks | new, append, show, search | log.intent, log.decision, log.observation, log.risk, log.append, log.search |
ops cab | cab | CAB evaluation and attestation | evaluate, attest, supersede, show | cab.evaluate, cab.attest |
ops deploy | deployer | Manifest-driven deployment | plan, preflight, apply, verify, rollback, show | deploy.preflight, deploy.apply.* (see inconsistencies) |
ops chk | chk | Situation-specific guidance from approved, signed packs | advise, lint, show, refresh | chk.advise, chk.lint, chk.refresh |
ops doctor | (diagnostic) | Read-only leaf health check | (single) | doctor.run |
The shared library ops-core holds:
- event models;
- local JSONL storage (SQLite optional);
- redaction;
- a signed-update client;
- policy result types;
- an
identitymodule for workload identity binding, Entra Agent ID claim resolution, and signing and verification; - a
registrymodule that enriches each record at emit time from the agent and model usage registries; - the shared CLI conventions.
Identity and registry are deliberately not subcommands. Administering them stays in the identity provider, the CMDB and the model registry (D14). The source gives three reasons for a single binary (D15): one artefact to allow-list, sign and update across thousands of leaves; consistent flags; and the shape used by mainstream CLIs. The books keep the “five tools” framing. [FACT-CHECK: Entra Agent ID claim names and availability against current Microsoft documentation.]
ops run: intent and redaction are not optional (b05-22)
| Rule | Behaviour |
|---|---|
--intent is always required | Missing intent → exit 2, nothing runs, no record. Only --help and --version are exempt. |
| Every invocation is a record | kind = ops.run, with argv in action.parameters and the result in outcome.output. A non-zero exit from the wrapped command still produces a record, and ops run exits with the wrapped command’s code. |
| Redaction before evidence | stdin, stdout and stderr are captured. The redaction rules (high-entropy strings; named patterns for connection strings, JWTs and API keys) run before anything reaches the record. The unredacted output is never written to disk; a hash of it is kept as proof that redaction happened. |
--no-redact | Refused with exit 4 unless the session was opened with the redaction_optional claim, which only some roles carry |
| No automatic retry | Retries are the operator’s decision and produce additional records |
| Sessions | ops session open --intent ... and ops session close --closure clean group runs under one session_id. An unclosed session is auto-closed with closure_kind = timeout by the exception engine, which raises an anomaly. |
--change-id | Fills the top-level change_id. A change whose decision is no-go is refused (exit 4). |
| Offline leaf | Records are signed locally and back-filled by the forwarder when the network returns. Warnings start at 80% local disk. Expired cached signing material → exit 3, with a pointer to ops doctor. |
| Location fields | Working directory, operator UPN, hostname and OS user are captured on every record. Where they sit inside the closed schema is not specified. |
ops doctor: read-only entry gate (b05-25)
ops doctor checks, in order:
- workload identity;
- agent identity claim;
- signing (sign and verify a no-op);
- agent and model registry lookups;
- an mTLS handshake to the edge API gateway;
- pack expiry;
- current session;
- supported AES major.minor.
It emits kind = doctor.run with payload.findings. Each check has a stable check_id (for example signing.key.present, edge.reachable, pack.fresh) so results can be aggregated across the fleet. Output is human-readable by default, or JSON with --json, and the JSON shape is stable across 0.x minors.
| Mode | Use | Extra rules |
|---|---|---|
| default | first-run bootstrap | exit 0 only if every check passes; each failure names the fixing tool |
--json --verbose | incident debugging | adds per-check timing and last-known-good times (last forwarder batch, last pack refresh); a crash exits 6 |
--strict | gate before a high-risk deploy or orchestrated run | pack expiry at least 7 days away; signing-key rotation within the policy’s N days; last successful forwarder batch within 1 hour |
--emit-only-on-fail | automated fleet scans | a normal run always emits, so an auditor’s sampling run is itself recorded |
It never provisions identities, rotates keys, registers agents, republishes packs, opens sessions or triggers rollback (D14.4). The fleet-wide doctor success rate is proposed as a control-function KPI. Acceptance check: wire ops doctor --strict, or your equivalent, as a required preflight check in the deployer manifest of every T2+ deployment.
Shared flags and exit codes (b05-24)
Every subcommand inherits --config, --quiet, --json and --session-id from ops-core (D15.5).
| Exit code | Meaning | Automation response |
|---|---|---|
| 0 | Success | proceed |
| 2 | Usage error (bad flags, missing input) | fix the invocation; never retry |
| 3 | Validation failure (schema mismatch, invalid signature, stale pack) | fix the input or refresh; never retry blindly |
| 4 | Policy refusal (CAB no-go, preflight refusal) | stop and escalate to a human |
| 5 | Transient infrastructure error (edge unreachable, key vault timeout) | retry with backoff |
| 6 | Internal error | stop and raise an incident |
Two traps:
ops cab evaluateexits 0 forgo,go-with-conditionsandneeds-review. Pipelines must read the decision field, not the exit code alone.ops runpasses through the wrapped command’s exit code on the success path, so a 4 from the wrapped program is not a policy refusal.
Claude plugins that enforce context (b05-26)
The source plans five Claude plugins, one per context, all invoking the same binary (D15.4). They are not yet drafted.
| Plugin | Fires when the agent is about to… | Routes to |
|---|---|---|
claude-plugin-ops | run a shell, build, test, lint, package-manager, cloud-CLI or file-system-affecting command | ops run |
claude-plugin-opslog | start a task, change plan, record a decision, identify a risk, hit a blocker or hand off | ops log |
claude-plugin-cab | make a production-impacting, risky infrastructure, data-migration or security-sensitive change, or a go/no-go call | ops cab |
claude-plugin-deployer | plan, preview, apply, verify, promote or roll back a deployment | ops deploy |
claude-plugin-chk | touch compliance, security, privacy, regulated data, customer-impacting risk or policy interpretation | ops chk |
Design rules (plugins README):
- The CLI is the system of record; plugins are thin adapters.
- Business rules, storage, redaction and policy evaluation stay in the CLI.
- Plugins fail closed for production, security, data and deployment contexts.
- They fail open only for low-risk local exploration, and even then emit an
opslogobservation.
Recommendation (this page, not the source). Until the plugins exist, implement the same routing with Claude Code’s enforcing layer rather than with instructions alone. Use permission rules that deny direct use of deployment and cloud CLIs, plus a pre-tool-use hook that refuses those commands unless they are wrapped in the approved tool. Deliver both through managed settings so users cannot override them. This applies the “skills advise, hooks enforce” rule in the glossary. Research Paper 3 sets out the managed-settings, MCP and hook controls at /research/securing-claude-code-in-the-enterprise/#sec-5-3. As of May 2026, per Book 3 Appendix J, Claude Code exposes lifecycle hooks including PreToolUse and PostToolUse, with managed settings at the highest precedence [FACT-CHECK: current Claude Code hook events, plugin packaging and managed-settings keys against Anthropic documentation].
Shared service API conventions (b05-59)
The planned centre services (M1 to M11) inherit these conventions. Use them as a checklist when you build or buy an equivalent.
| Area | Convention |
|---|---|
| Transport | gRPC (primary) and HTTP/JSON (one-to-one mapping, snake_case); OpenAPI 3.1 generated from protobuf; mTLS terminated at the API gateway and between services, with client certificates bound to workload identity |
| Authentication | OIDC. Human principals use UPN and groups, with MFA and a compliant device required for any human write or attest. Workload and agent principals carry agent_id_claim. Tokens default to 60 minutes. |
| Authorisation | Roles namespaced per service, plus seven canonical reader roles (wrangler, auditor, soc, supervisor, second_line, internal_audit, regulator). Scope claims: agent_scope, entity_scope, jurisdiction_scope, time_scope. Every refusal is recorded as auth.refused; a silent refusal is a gap the exception engine cannot see. |
| Errors | {error_class, error_code, message, details, trace_id, audit_record_id}. Classes: validation 400, auth 401, refusal 403, not_found 404, conflict 409, rate_limited 429, internal 500, upstream 502/503. error_code is namespaced <service>.<short_code>. Every error points at the AES record that captured it. |
| Idempotency | Every state-changing request carries an Idempotency-Key (UUIDv7 recommended). The same key returns the original response; the same key with a different payload returns 409 <service>.idempotency_conflict. Keys are retained for 24 hours by default and flow into the resulting AES records. |
| Collections | Cursor pagination only (limit default 100, maximum 1000, next_cursor); gRPC server streaming; no offset pagination |
| Rate limits | Per principal, by default: 100 reads/s, 10 writes/s, 5 concurrent streams. Time-bounded raises for audit engagements. 429 responses carry Retry-After and audit_record_id. |
| Observability | service.request, service.response, service.error and service.degraded meta-records, each with service_name, service_version, W3C trace_id and span_id, method and path, duration_ms and caller_principal. Dashboards for the four golden signals. |
| Health | Unauthenticated GET /health, /ready and /version (which includes the supported AES range) |
| Deployment (informative) | Azure Container Apps, or AKS where stronger isolation is needed; workload identity; Sigstore-signed images with admission control refusing unsigned ones; mTLS-only ingress behind API Management; Key Vault references, no inline secrets [FACT-CHECK: service names and capabilities against current Azure documentation] |
Technology picks bound to durable properties (b02c-90)
Book 2 Appendix B (Draft 4, 10 November 2026; product timestamps as of mid-2026) grades the author’s 2024 tool choices and makes 2026 picks. The lesson it draws: bind each slot to a durable property, and keep the product filling the slot substitutable. These are author recommendations.
| 2026 pick | Durable property it binds to | Substitution rule |
|---|---|---|
| CLI-first tooling (a 2024 pick, graded “aged well”) | Deterministic flags, machine-readable output and clear exit codes are what agents can operate | A tool with no CLI surface is invisible to agents. This is why ops is a CLI. |
| Claude Code as the coding-agent harness | Plan-then-execute, subagents, review loops, attributable evidence | The slot is fixed; the harness is a named, replaceable component. The evidence format, workspace, toolchain and review gate stay fixed. |
| Locked per-domain toolchains | One sanctioned language, IaC, CI/CD and observability stack per domain, declared in context files | Changed only through the recipe-upgrade path |
| GitHub as source of truth (for greenfield) | Code, the intent, spec and plan chain, the living BOM and recipe, and ADR and GIP records in one repository | The repository, not documents and boards, holds governance |
| MCP as the agent-facing contract, with A2A beside it | A governed, identity-bound, evidenced contract between agents and systems | Neither protocol says what an agent may do for a client; that stays with the gateway and broker |
| A provider-agnostic router over three hosting routes | Exit: per-request routing by data class, with a warm self-hosted floor | Concrete models are deliberately temporary |
| Pattern names and recipe families over framework names | Names that outlive frameworks | The pattern arbiter versions the catalogue |
| The testable spec | Testability | The technique, not a product |
The appendix records one 2024 pick as dead: Azure Blueprints, which Microsoft is retiring in favour of Deployment Stacks and Template Specs [FACT-CHECK: retirement dates against current Microsoft documentation]. It is the cautionary case for naming products inside recipes. Practitioners apply the same rule to these specifications: bind your producers to the schema’s properties, and keep the ops implementation, which does not yet exist, a replaceable component.
Source and status
Source claims: schema fields, enums and conditional rules are taken from the hosted JSON, which is identical to the Supporting Tools source files. CLI, plugin, harness and API behaviour come from the Supporting Tools design documents, all first drafts dated May 2026 and describing unbuilt software. Licence terms are the source’s stated intent.
This page’s own work:
- the validation results (14 November 2026) and the inconsistency table;
- the publication-gap table;
- the adopter recommendations: vendoring and digest pinning, the CI acceptance gate, the
ops doctor --strictpreflight, plugin routing through Claude Code managed settings and hooks, and the service-initiator workarounds.
Owner decisions pending:
- licence notices for the hosted files;
- whether to publish
/trust/and/verify/pages, or remove them from the specification; - which URL convention is canonical;
- correction of the event-kind packs and use cases before they are cited as normative.
Review trigger: any new file under /aes/, a schema version beyond 0.1.0, publication of trust roots or a conformance harness, or the first release of the ops binary.
Source material
- Supporting Tools, README (Governance and licensing) and spec/README
- Supporting Tools, spec/audit_evidence_schema: Audit Evidence Schema v0.1.0, README and versioning.md
- Supporting Tools, spec/cab_decision_record: cab_change and cab_decision v0.1.0 and README
- Supporting Tools, spec/deployer_manifest: Deployer Manifest v0.1.0 and README
- Supporting Tools, spec/conformance: README, phase_5_event_kinds.md and event_kinds test packs
- Supporting Tools, docs/api/01_conventions.md and m11_conformance_harness.md
- Supporting Tools, docs/use_cases 00 to 06 (ops run, log, cab, deploy, chk, doctor)
- Supporting Tools, cli/README.md and plugins/claude/README.md
- Supporting Tools, docs/website/01_deixei_com_specification.md (sections 2.2 to 2.5)
- Supporting Tools, planning/decisions_log.md (D11.1, D13, D15, D18, D19, D31, D33)
- Book 1, Appendix B, Audit Evidence Schema
- Book 2, Appendix A, Glossary (Audit spine, CAB Decision Record, Deployer Manifest, ops)
- Book 2, Appendix B, Technology Choices Revisited, 2024 to 2026 (CLI-first tooling; the 2026 picks)
- Book 3, Appendix E, Audit Evidence Schema for Claude Actions (overview)
- Book 3, Appendix J, Glossary (Claude Code hooks and managed settings, as of May 2026)
- Research Paper 3, Securing Claude Code in the Enterprise (section 5.3)
Related research
Related guidance
-
The Audit Spine and the Evidence RecordHow to capture, join, protect, retain and prove per-action evidence: the AES v0.1.0 record contract, three capture points and one correlation ID, tiered immutable storage, retention and legal hold, replay rehearsal, the route-approval evidence gate, and the Claude-specific ways evidence goes missing. -
Change Governance for Agent-Enabled DeliveryRoute agent-speed change by risk without losing the approver: control values that always reach a person, a routing gate that reads the right signals, autonomy earned per change family, a Virtual CAB that prepares a complete dossier, and three bodies with defined escalation. -
Release Engineering for Agent-Written ChangeMove agent-speed change into production through five evidence-emitting stations: one change type per change, a reversal decided at authoring, a valid Deployer Manifest, a gateway that cannot be bypassed, hard health gates and at-most-once rollback. -
The Enterprise Agent Control PlaneThe firm-owned services that make every agent action identifiable, decidable, approvable and reconstructable: the ownership boundary, six planes and their contracts, the Policy Decision API with its latency budget, the persistence schema, the build sequence and the tests that show it works. -
Operate the Agent LifecycleInventory, register, sign, zone, review, suspend, recover and retire agents through a six-stage lifecycle with named human ownership, zone-specific authority and evidence at every transition. -
Glossary and Vocabulary CrosswalkThe controlled vocabulary of the AI Delivery Factory reference, with a crosswalk for the places where the books, working papers and specifications use different words for the same thing.