Browse the reference ⌄
Artefact published

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

Full source list ↓ Source index →

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 ops toolchain.

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 / roleSource fileValidated exampleUsed on
/aes/v0.1.0/audit_evidence_schema.jsonAES predicate, JSON Schema draft 2020-12audit_evidence_schema.v0.1.0.jsonexamples/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.jsonCAB change file: input to ops cab evaluatecab_change.v0.1.0.jsonexamples/cs_v2.4.0_change.jsonChange governance
/aes/v0.1.0/cab_decision.jsonCAB decision record: outputcab_decision.v0.1.0.jsonexamples/cs_v2.4.0_decision.json (go-with-conditions)Change governance
/aes/v0.1.0/deployer_manifest.jsonDeployer manifest: input to ops deploydeployer_manifest.v0.1.0.jsonexamples/cs_v2.4.0_manifest.jsonRelease 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 forCurrent state on this siteConsequence for adopters
A spec landing at /spec/ with schema badge, status, signer, changelog and book cross-referencesNot presentNo public statement of status or changelog beyond this page
Versioned URLs of the form /spec/audit-evidence-schema/v0.1.0/schema.jsonNot used; files are served at the $id path /aes/v0.1.0/<name>.jsonThe 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 JSONIntegrity 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 presenceNot presentVerification must be done with your own tooling
Signed release notes per versionNot present; this site’s /releases/ collection is for product release notes, not the specificationTrack 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:

  1. Vendor the three schema files into your own repository.
  2. Record the SHA-256 digest of each file and the date you fetched it.
  3. Validate producers against your vendored copy.
  4. 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.

ComponentIntended licence (Supporting Tools README; D11.1 as amended; D33)
Specification content: JSON Schemas, normative documents, conformance vectors as dataCC-BY-4.0
Reference implementation: CLI, services, infrastructure, portal, plugins, harness runnerBusiness 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 exampleCDLA-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:

  1. the Statement is a valid in-toto v1 Statement;
  2. predicateType equals https://www.deixei.com/aes/v0.1.0;
  3. predicate validates 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.

ArtefactWrapped asaction.parametersoutcome.output
CAB evaluationkind = cab.evaluate, action.verb = evaluated-changethe cab_changethe cab_decision
Deployment applykind = deployer.apply (Deployer README)the manifestthe 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.

FieldRequiredRule
schema_versionyes^\d+\.\d+\.\d+$
record_idyesnon-empty string; ULID or UUID recommended
session_idyesnon-empty; join key for one work unit
kindyes^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$: exactly two lower-case segments, no hyphens
change_idnostring or null; join key for a change
payloadnoobject, untyped; kind-specific extension
parameters_schema_refnoURI of a kind-specific schema constraining action.parameters, outcome.output and payload

The nine groups

Group (question)Required insideEnums and conditional rules
initiator (who initiated?)type, then per branch: human user_upn, channel, session_start; agent upstream_agent_id; scheduled schedule_id, trigger_eventoneOf 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, zonezone ∈ {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_cadencememory.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, classificationoperation ∈ {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, roleoptional 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, rationaleif 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 data and model arrays 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.output or payload. Constrain it by publishing a kind-specific schema and pointing at it with parameters_schema_ref. The use-case documents call this field payload_schema_ref; the schema field is parameters_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)

FieldRequiredRule
schema_version, change_id, summary, descriptionyesnon-empty strings; version pattern as for AES
change_typeyes∈ {app_deploy, infra_change, data_migration, emergency_fix, config_change, other}
submitteryesteam, submitted_at required, plus exactly one of user_upn (human) or agent_id (orchestrator agent)
targetyesenvironment, systems[] (at least one); regions[] optional
riskyeslevel ∈ {low, medium, high, critical}, rationale
customer_impactyesexpected (boolean), description; blast_radius optional
rollbackyesplan_description; command_ref optional
test_evidence[]yeseach: type ∈ {test_run, scan, review, other}, ref, result ∈ {pass, fail, n/a}
monitoringyesdashboards[], alerts[], post_change_check_window (ISO 8601 duration)
security_complianceyesimpact (boolean), description, chk_guidance_refs[]
approvers_required[]yeseach: role; specific_upn optional
policy_template, policy_template_versionyesthe CAB template the change is evaluated against
target_windownostart, end

CAB decision record v0.1.0 (cab_decision.json)

FieldRequiredRule
decisionyes∈ {go, go-with-conditions, no-go, needs-review, superseded}
policy_template, policy_template_version, change_refyeschange_ref names the change evaluated
conditions[]yeseach: id, description, must_complete_before ∈ {deploy, promote, continue, other}, evidence_required. Must be non-empty when decision = go-with-conditions.
reasoning[]yes, at least oneeach: rule_id, passed, rationale. Records every rule, passed or failed (D18.4), so “why did this pass” is auditable.
evidence_consulted[]yeseach: type, ref; the same shape as AES evidence_pointers
approvers_required[]yeseach: role, fulfilled; fulfilled = true requires upn and approval_record_ref
expires_atnodate-time after which the decision cannot be relied on
superseded_byconditionalrequired when decision = superseded

Operating rules from the use cases:

  • Decisions are never edited, only superseded.
  • An expired template with risk high or 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 from no-go and superseded.

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).

SectionRequired insideRules
manifest_id, schema_versionyesas above
artefactname, version, kindkind ∈ {container_image, helm_chart, terraform_module, bicep_module, function_app, static_files, custom}; optional digest.sha256 (64 hex) or digest.sha512 (128 hex)
targetenvironment, systems[] (at least one)regions[] optional
backendtype, configtype ∈ {helm, kubernetes, terraform, opentofu, bicep, azure_cli, aws_cli, gcp_cli, docker, ssh, custom}; config untyped, constrained by optional config_schema_ref
preflightchecks[], required_chk_guidance[], required_cab_decisionrequired_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.
applyintent, program, args[], timeout (ISO 8601 duration)env map optional
verifywait_window, health_checks[]at least one health check
rollbackintent, program, args[], timeout, verification[]verification required (there is no unverified rollback path); automatic_triggers[] optional and metric-only in v0.1
metadataowner_team, agent_wrangler_upna deployment without a named human owner cannot run
promotionoptional; 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 kindRequired fields
httpid, description, kind, url, expected_status (100–599), timeout
commandid, description, kind, program, expected_exit_code, timeout
metricid, 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-conditions decision 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

RuleSource
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:

SchemaPositive casesRequired negative cases (must fail)
AESpredicate example validates; the in-toto example is a valid Statement with the right predicateType and a valid predicateapproval removed; approval.required = true without workflow_id or approvers
CABchange example and decision example validate; a change with an agent submitter and no user_upn validatessubmitter 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
Deployermanifest example validates; required_cab_decision = null with a populated cab_exemption_rationale validatesnull 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):

  1. Run every positive and negative case above in CI on each producer change.
  2. Add one negative case per conditional rule you rely on.
  3. Fail the build if a negative case passes.
  4. 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.

KindRequired payload fieldsNotable negative rules
cab.refuserefuser_upn, refusal_reason, refuses_decision_record_idempty reason fails
rollback.signalrollback_id, deployment_id, trigger_metric, threshold, measured_value, signalled_atat-most-once delivery; rollback_id unique within 24 h
alert.routedalert_id, source_kind, severity ∈ {P1, P2, P3, info}, destinations[] (each target, delivery_outcome)empty destinations fail
gateway.requestgateway_id, model_id, prompt_hash (SHA-256), tool_signatures[], request_optionsevery gateway record carries a registry-resolved executing_agent.agent_id_claim and a session_id joining request to response
gateway.responsegateway_id, response_hash, model_id, finish_reason ∈ {stop, length, tool_use, refusal, error}, cost (token counts, currency, total)negative token counts fail
gateway.refusalrefusal_class ∈ {safety, policy, capability, other}, refusal_text_hash, model_id
gateway.tool_usetool_name, tool_version, tool_invocation_id, parameters_hash, result_hash, duration_msone record per tool call
gateway.safety_eventclassifier_id, classifier_version, triggered_category, severity, action_taken ∈ {blocked, flagged, passed_with_note}
pack.publishpack_id, pack_version, pack_class ∈ {advisory, controlled, mandatory}, publisher_upns[], approver_upns[], signature_refno sole author above advisory; a recall sets recall_reason and must name a previously published version
agent.provisioned / agent.retiredprovisioned: 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_idprovisioning is idempotent: a replay yields the same record, not a duplicate
retention.delete, legalhold.applied, legalhold.releaseddelete: 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_rationalea delete overlapping an active hold is rejected; a release without a prior hold fails
conformance.runcandidate_implementation, test_pack_id, test_pack_version, outcome ∈ {pass, fail, partial}, result_summarypassed + failed + skipped must equal total
query.runrequester_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.backoffchaos: exercise_id, exercise_class, start_at, end_at, outcome, measured_rto_ms, measured_rpo_ms; forwarder: batch and acknowledgement fieldsan 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:

  1. Which pack ID and version, against which spec version?
  2. Hosted or self-service?
  3. When does the badge expire?
  4. 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:

InconsistencyWhereEffect
outcome.result values such as SUBMITTED, REFUSED, ROUTED, PUBLISHED, SUPERSEDED and SIGNAL_SENTevent-kind packsoutside 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 channelevent-kinds README; packsthe 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)packseach case is invalid before its payload is even checked
gateway_id placed in executing_agentgateway packexecuting_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-requiredpacks; ops use casesthe 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.decisionschema kind description; use casesconsumers keyed on kind names will miss records
outcome.status = failure, outcome = unknown, redaction_applied, initiator.agent_id and an agent-branch on_behalf_ofops run and ops deploy use casesnone of these fields or values exist in the schema
cab_decision_max_age used to refuse stale decisionsUC-deploy-2not a field in the closed manifest schema
Emergency changes “auto-marked superseded” when attestation lapsesUC-cab-4a superseded decision requires superseded_by, and none exists in this path
payload_schema_refuse-case READMEthe schema field is parameters_schema_ref
Three test packs at launch (D31.1) versus five (M11 section 5); “seven” deployer negatives versus six listeddecisions log; M11; conformance READMEconformance scope is ambiguous
/spec/<name>/v0.1.0/schema.json versus /aes/v0.1.0/<name>.jsonwebsite spec section 2.2; schema $idtwo 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 erroruse casesautomation 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 = scheduled where 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)

SubcommandConcept toolPurposeSub-actionsMain AES kinds
ops runopsWraps a command with mandatory intent; signed JSONL(wrap)ops.run, session.open, session.close
ops logopslogTyped, append-only journal of intent, decisions, observations, risksnew, append, show, searchlog.intent, log.decision, log.observation, log.risk, log.append, log.search
ops cabcabCAB evaluation and attestationevaluate, attest, supersede, showcab.evaluate, cab.attest
ops deploydeployerManifest-driven deploymentplan, preflight, apply, verify, rollback, showdeploy.preflight, deploy.apply.* (see inconsistencies)
ops chkchkSituation-specific guidance from approved, signed packsadvise, lint, show, refreshchk.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 identity module for workload identity binding, Entra Agent ID claim resolution, and signing and verification;
  • a registry module 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)

RuleBehaviour
--intent is always requiredMissing intent → exit 2, nothing runs, no record. Only --help and --version are exempt.
Every invocation is a recordkind = 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 evidencestdin, 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-redactRefused with exit 4 unless the session was opened with the redaction_optional claim, which only some roles carry
No automatic retryRetries are the operator’s decision and produce additional records
Sessionsops 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-idFills the top-level change_id. A change whose decision is no-go is refused (exit 4).
Offline leafRecords 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 fieldsWorking 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:

  1. workload identity;
  2. agent identity claim;
  3. signing (sign and verify a no-op);
  4. agent and model registry lookups;
  5. an mTLS handshake to the edge API gateway;
  6. pack expiry;
  7. current session;
  8. 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.

ModeUseExtra rules
defaultfirst-run bootstrapexit 0 only if every check passes; each failure names the fixing tool
--json --verboseincident debuggingadds per-check timing and last-known-good times (last forwarder batch, last pack refresh); a crash exits 6
--strictgate before a high-risk deploy or orchestrated runpack 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-failautomated fleet scansa 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 codeMeaningAutomation response
0Successproceed
2Usage error (bad flags, missing input)fix the invocation; never retry
3Validation failure (schema mismatch, invalid signature, stale pack)fix the input or refresh; never retry blindly
4Policy refusal (CAB no-go, preflight refusal)stop and escalate to a human
5Transient infrastructure error (edge unreachable, key vault timeout)retry with backoff
6Internal errorstop and raise an incident

Two traps:

  • ops cab evaluate exits 0 for go, go-with-conditions and needs-review. Pipelines must read the decision field, not the exit code alone.
  • ops run passes 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.

PluginFires when the agent is about to…Routes to
claude-plugin-opsrun a shell, build, test, lint, package-manager, cloud-CLI or file-system-affecting commandops run
claude-plugin-opslogstart a task, change plan, record a decision, identify a risk, hit a blocker or hand offops log
claude-plugin-cabmake a production-impacting, risky infrastructure, data-migration or security-sensitive change, or a go/no-go callops cab
claude-plugin-deployerplan, preview, apply, verify, promote or roll back a deploymentops deploy
claude-plugin-chktouch compliance, security, privacy, regulated data, customer-impacting risk or policy interpretationops 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 opslog observation.

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.

AreaConvention
TransportgRPC (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
AuthenticationOIDC. 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.
AuthorisationRoles 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.
IdempotencyEvery 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.
CollectionsCursor pagination only (limit default 100, maximum 1000, next_cursor); gRPC server streaming; no offset pagination
Rate limitsPer 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.
Observabilityservice.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.
HealthUnauthenticated 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 pickDurable property it binds toSubstitution rule
CLI-first tooling (a 2024 pick, graded “aged well”)Deterministic flags, machine-readable output and clear exit codes are what agents can operateA tool with no CLI surface is invisible to agents. This is why ops is a CLI.
Claude Code as the coding-agent harnessPlan-then-execute, subagents, review loops, attributable evidenceThe slot is fixed; the harness is a named, replaceable component. The evidence format, workspace, toolchain and review gate stay fixed.
Locked per-domain toolchainsOne sanctioned language, IaC, CI/CD and observability stack per domain, declared in context filesChanged 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 repositoryThe repository, not documents and boards, holds governance
MCP as the agent-facing contract, with A2A beside itA governed, identity-bound, evidenced contract between agents and systemsNeither protocol says what an agent may do for a client; that stays with the gateway and broker
A provider-agnostic router over three hosting routesExit: per-request routing by data class, with a warm self-hosted floorConcrete models are deliberately temporary
Pattern names and recipe families over framework namesNames that outlive frameworksThe pattern arbiter versions the catalogue
The testable specTestabilityThe 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 --strict preflight, 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)

← All AI Delivery Factory guidance

On this page

  1. What is hosted, and its status
    1. Publication gaps to close before treating the URLs as a trust anchor (b05-07)
    2. Reuse and licence terms (b05-72)
  2. How the records are layered on the wire
  3. Audit Evidence Schema v0.1.0
    1. Envelope fields
    2. The nine groups
  4. CAB change file v0.1.0 (cab_change.json)
  5. CAB decision record v0.1.0 (cab_decision.json)
  6. Deployer Manifest v0.1.0 (deployer_manifest.json)
  7. Versioning and compatibility
  8. Conformance
    1. v0.1.0 vectors for the three schemas (b05-56)
    2. Event-kind payload contracts (b05-57)
    3. The conformance harness and badges (b05-55)
  9. Known inconsistencies inside the source specification (b05-58)
  10. The ops reference toolchain (designed, not built)
    1. One binary: five subcommands and a diagnostic (b05-21)
    2. ops run: intent and redaction are not optional (b05-22)
    3. ops doctor: read-only entry gate (b05-25)
    4. Shared flags and exit codes (b05-24)
    5. Claude plugins that enforce context (b05-26)
  11. Shared service API conventions (b05-59)
  12. Technology picks bound to durable properties (b02c-90)
  13. Source and status

All pages in Reference →