Draft specification · Parity with CAOP v0.2

MAOP v1 parity with CAOP v0.2

DRAFTVersion 1.0.0-draft.1November 22, 2026Source commit ccc48b5
DRAFT · Implementation status. MAOP v1 (1.0.0-draft.1) is a proposal published for review; it is not stable and is not yet implemented. The Creasura reference runtime implements CAOP v0.2, the current published version.
On this page
  1. Parity rule
  2. Baseline pin
  3. Summary
  4. Operations
  5. Schema definitions
  6. Examples
  7. Normative guarantees
  8. Supplementary lower-case requirements
  9. Additions
  10. Improvements over CAOP v0.2
  11. Acceptance criteria checklist
  12. Regenerating

Status: DRAFT · MAOP version: 1.0.0-draft.1 · Baseline: CAOP v0.2 at commit 8c7bd07939171efc2d39079bd018904175ea8db2

This document shows that MAOP v1 (Multi-Agent Orchestration Protocol) covers every operation, schema definition, example and normative guarantee of CAOP v0.2, and lists what MAOP adds. The machine-readable version is tests/parity.json. Both are generated from the files at the pinned baseline commit, not typed by hand: the generator, tests/parity_gen.py, reads SPEC.md, schema/caop-v0.2.schema.json, openapi/caop-v0.2.openapi.yaml and examples/*.json from git at that commit, validates every example, and extracts every line of SPEC.md that contains MUST, MUST NOT, SHALL, SHOULD or REQUIRED. Line numbers refer to SPEC.md at the baseline commit. Regenerate both files with python tests/parity_gen.py all; see Regenerating.

The specification itself is docs/maop-v1.md; migration and compatibility are in docs/maop-v1-migration.md.

Parity rule

MAOP v1 keeps all 17 CAOP v0.2 operations with the same operationIds, methods, sub-paths, request and response bodies and semantics, under the path prefix /maop/v1 instead of /v1. It keeps all 95 CAOP v0.2 definitions under the same names; a definition may only be refined additively (new optional properties, new enum values, vendor-neutral descriptions), never weakened. Every CAOP v0.2 example is therefore a valid instance of the same-named MAOP definition. Parity holds by construction; the improvements are additive.

Baseline pin

Commit: 8c7bd07939171efc2d39079bd018904175ea8db2 (branch main when MAOP work started).

These nine historical contract files are frozen. The sha256 values were computed from the files at the baseline commit, and the working tree was checked against them when this file was generated.

Filesha256Unchanged in working tree
openapi/caop-v0.1.2.openapi.json6b727a0fa60efc1f487fe154d3eb3fe63c3f1e7121a89962a553116b04b005a8yes
openapi/caop-v0.1.2.openapi.yaml05dd1dfbe6449cc5447420023f336aa48c7221d229219cbd17396da4bf9be8b4yes
openapi/caop-v0.1.openapi.json076a128385a1bc7d4841d1447cf3b2a4eedfc612ad393c3b14d0714f9857a4ebyes
openapi/caop-v0.1.openapi.yaml272fd7face00997359c9d185851995d9397281846ce6166d25a32e98f16a622fyes
openapi/caop-v0.2.openapi.json699fc607a7b0473d8b2c08bac3d1f59b11687f2f6670cb391d86ec4b1aa7fcd6yes
openapi/caop-v0.2.openapi.yamlaaf1ae25400fd3db9483c737b787e36a31976415434d9bb615ca3481ec790e42yes
schema/caop-v0.1.2.schema.json3a72213ecf506df646cfb8c455b564349e2eae819bf3b6b9686f6868cfdbf000yes
schema/caop-v0.1.schema.json4cc2cda6f49926efa8521aa5dabd66803b23691ce8a7488c51f0477798005dedyes
schema/caop-v0.2.schema.json7a4e7ce9fdd5328d10a93595fe0269e63ba9a8fb9bce21b300dd6c7020a45f75yes

Summary

CategoryCAOP v0.2 countKeptRefinedReplacedRemoved
Operations1717000
Schema definitions9594100
Examples7171000
Normative guarantees (MUST/SHALL/SHOULD/REQUIRED lines)1612400
Supplementary lower-case requirements (informative check)1715200

Nothing is removed or replaced, so no removal needs a justification. Of the 16 guarantee lines, 10 are normative statements and 6 are entries in SPEC.md's editorial history that quote those statements; the history entries are tracked so the count matches a plain keyword search, and each points at the guarantee it records.

MAOP v1 adds 6 operations and 15 definitions, for 23 operations and 110 definitions in total.

Generation note. Statuses were derived by structurally comparing schema/maop-v1.schema.json and openapi/maop-v1.openapi.yaml with CAOP v0.2, ignoring descriptions. All 17 operations have the same method, sub-path, request body and response codes and bodies. 94 of 95 definitions are structurally identical. 1 are refined additively (new optional properties or enum values only; see the Note column): Error. 6 kept definitions have reworded, vendor-neutral descriptions only (EntityRef, Fact, Capability, ObservationCreate, LoopDriver, AuthCustodian), and their status stays kept. Re-run python tests/parity_gen.py all after any contract change; an additive change shows as refined, and any other change is flagged CHECK.

Operations

#operationIdCAOP v0.2MAOP v1RequestSuccess responseStatus
1observations.ingestPOST /v1/observationsPOST /maop/v1/observationsObservationCreate202: ObservationAcceptedkept
2context.resolvePOST /v1/context/resolvePOST /maop/v1/context/resolveContextResolveRequest200: ContextBundlekept
3commitments.createPOST /v1/commitmentsPOST /maop/v1/commitmentsCommitmentCreate201: Commitmentkept
4commitments.listGET /v1/commitmentsGET /maop/v1/commitmentsnone200: CommitmentListkept
5plans.createPOST /v1/plansPOST /maop/v1/plansPlanCreate201: Plankept
6executions.startPOST /v1/executionsPOST /maop/v1/executionsExecutionCreate202: ExecutionAcceptedkept
7executions.getGET /v1/executions/{execution_id}GET /maop/v1/executions/{execution_id}none200: Executionkept
8executions.submit_resultPOST /v1/executions/{execution_id}/resultsPOST /maop/v1/executions/{execution_id}/resultsResultSubmission202: Executionkept
9executions.transitionPOST /v1/executions/{execution_id}/transitionsPOST /maop/v1/executions/{execution_id}/transitionsTransitionRequest200: Transitionkept
10verifications.evaluatePOST /v1/verificationsPOST /maop/v1/verificationsVerificationRequest200: Verificationkept
11records.commitPOST /v1/records/commitPOST /maop/v1/records/commitRecordCommit200: RecordCommittedkept
12reviews.evaluatePOST /v1/reviewsPOST /maop/v1/reviewsReviewRequest200: Reviewkept
13approvals.decidePOST /v1/approvals/{approval_request_id}/decisionPOST /maop/v1/approvals/{approval_request_id}/decisionApprovalDecision200: Approvalkept
14compact.pulsePOST /v1/compact/pulsePOST /maop/v1/compact/pulsePulseInput200: PulseResponsekept
15compact.stage_workPOST /v1/compact/stage-workPOST /maop/v1/compact/stage-workStageWorkInput200: StageWorkResultkept
16compact.dispatch_workPOST /v1/compact/dispatch-workPOST /maop/v1/compact/dispatch-workDispatchWorkInput200: DispatchWorkResultkept
17compact.settle_receiptPOST /v1/compact/settle-receiptPOST /maop/v1/compact/settle-receiptSettleReceiptInput200: SettlementResultkept

Every operation keeps its error responses (Error envelope, same codes). Note for all rows: Same operationId, method, sub-path, request and response definitions and semantics under the /maop/v1 prefix.

Schema definitions

#DefinitionMAOP nameIntroducedStatusNote
1PrincipalRefPrincipalRefv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
2EntityRefEntityRefv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json. Description reworded (vendor-neutral), no structural change.
3EvidenceRefEvidenceRefv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
4ArtifactRefArtifactRefv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
5ExpressionExpressionv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
6CriterionCriterionv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
7ConstraintConstraintv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
8AuthorizationPolicyAuthorizationPolicyv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
9GoalGoalv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
10WorkItemWorkItemv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
11FactFactv0.1keptIntroduced in CAOP v0.1. Example: examples/Fact.json. Structure identical in schema/maop-v1.schema.json. Description reworded (vendor-neutral), no structural change.
12CapabilityCapabilityv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json. Description reworded (vendor-neutral), no structural change.
13PolicyPolicyv0.1keptIntroduced in CAOP v0.1. Example: examples/Policy.json. Structure identical in schema/maop-v1.schema.json.
14CapabilityDescriptorCapabilityDescriptorv0.1keptIntroduced in CAOP v0.1. Example: examples/CapabilityDescriptor.json. Structure identical in schema/maop-v1.schema.json.
15CapabilityInvocationCapabilityInvocationv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
16CapabilityResultCapabilityResultv0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
17ExecutionStateExecutionStatev0.1keptIntroduced in CAOP v0.1. Structure identical in schema/maop-v1.schema.json.
18ObservationCreateObservationCreatev0.1keptIntroduced in CAOP v0.1. Used directly by observations.ingest. Example: examples/ObservationCreate.json. Structure identical in schema/maop-v1.schema.json. Description reworded (vendor-neutral), no structural change.
19ObservationAcceptedObservationAcceptedv0.1keptIntroduced in CAOP v0.1. Used directly by observations.ingest. Example: examples/ObservationAccepted.json. Structure identical in schema/maop-v1.schema.json.
20ContextResolveRequestContextResolveRequestv0.1keptIntroduced in CAOP v0.1. Used directly by context.resolve. Example: examples/ContextResolveRequest.json. Structure identical in schema/maop-v1.schema.json.
21ContextBundleContextBundlev0.1keptIntroduced in CAOP v0.1. Used directly by context.resolve. Example: examples/ContextBundle.json. Structure identical in schema/maop-v1.schema.json.
22CommitmentCreateCommitmentCreatev0.1keptIntroduced in CAOP v0.1. Used directly by commitments.create. Example: examples/CommitmentCreate.json. Structure identical in schema/maop-v1.schema.json.
23CommitmentCommitmentv0.1keptIntroduced in CAOP v0.1. Used directly by commitments.create. Example: examples/Commitment.json. Structure identical in schema/maop-v1.schema.json.
24CommitmentListCommitmentListv0.1keptIntroduced in CAOP v0.1. Used directly by commitments.list. Structure identical in schema/maop-v1.schema.json.
25PlanCreatePlanCreatev0.1keptIntroduced in CAOP v0.1. Used directly by plans.create. Example: examples/PlanCreate.json. Structure identical in schema/maop-v1.schema.json.
26PlanPlanv0.1keptIntroduced in CAOP v0.1. Used directly by plans.create. Example: examples/Plan.json. Structure identical in schema/maop-v1.schema.json.
27ExecutionCreateExecutionCreatev0.1keptIntroduced in CAOP v0.1. Used directly by executions.start. Example: examples/ExecutionCreate.json. Structure identical in schema/maop-v1.schema.json.
28ExecutionAcceptedExecutionAcceptedv0.1keptIntroduced in CAOP v0.1. Used directly by executions.start. Example: examples/ExecutionAccepted.json. Structure identical in schema/maop-v1.schema.json.
29ExecutionExecutionv0.1keptIntroduced in CAOP v0.1. Used directly by executions.get, executions.submit_result. Example: examples/Execution.json. Structure identical in schema/maop-v1.schema.json.
30TransitionRequestTransitionRequestv0.1keptIntroduced in CAOP v0.1. Used directly by executions.transition. Example: examples/TransitionRequest.json. Structure identical in schema/maop-v1.schema.json.
31TransitionTransitionv0.1keptIntroduced in CAOP v0.1. Used directly by executions.transition. Example: examples/Transition.json. Structure identical in schema/maop-v1.schema.json.
32ResultSubmissionResultSubmissionv0.1keptIntroduced in CAOP v0.1. Used directly by executions.submit_result. Example: examples/ResultSubmission.json. Structure identical in schema/maop-v1.schema.json.
33VerificationRequestVerificationRequestv0.1keptIntroduced in CAOP v0.1. Used directly by verifications.evaluate. Example: examples/VerificationRequest.json. Structure identical in schema/maop-v1.schema.json.
34VerificationVerificationv0.1keptIntroduced in CAOP v0.1. Used directly by verifications.evaluate. Example: examples/Verification.json. Structure identical in schema/maop-v1.schema.json.
35RecordCommitRecordCommitv0.1keptIntroduced in CAOP v0.1. Used directly by records.commit. Example: examples/RecordCommit.json. Structure identical in schema/maop-v1.schema.json.
36RecordCommittedRecordCommittedv0.1keptIntroduced in CAOP v0.1. Used directly by records.commit. Example: examples/RecordCommitted.json. Structure identical in schema/maop-v1.schema.json.
37ReviewRequestReviewRequestv0.1keptIntroduced in CAOP v0.1. Used directly by reviews.evaluate. Example: examples/ReviewRequest.json. Structure identical in schema/maop-v1.schema.json.
38ReviewReviewv0.1keptIntroduced in CAOP v0.1. Used directly by reviews.evaluate. Example: examples/Review.json. Structure identical in schema/maop-v1.schema.json.
39ApprovalDecisionApprovalDecisionv0.1keptIntroduced in CAOP v0.1. Used directly by approvals.decide. Example: examples/ApprovalDecision.json. Structure identical in schema/maop-v1.schema.json.
40ApprovalApprovalv0.1keptIntroduced in CAOP v0.1. Used directly by approvals.decide. Example: examples/Approval.json. Structure identical in schema/maop-v1.schema.json.
41EventEnvelopeEventEnvelopev0.1keptIntroduced in CAOP v0.1. Example: examples/EventEnvelope.json. Structure identical in schema/maop-v1.schema.json.
42ErrorErrorv0.1refinedIntroduced in CAOP v0.1. Used directly by approvals.decide, commitments.create, commitments.list, compact.dispatch_work, compact.pulse, compact.settle_receipt, compact.stage_work, context.resolve, executions.get, executions.start, executions.submit_result, executions.transition, observations.ingest, plans.create, records.commit, reviews.evaluate, verifications.evaluate. Example: examples/Error.json. Additive refinement: /properties/error/properties/code/enum +['MAOP_403_AUTHORITY_INVALID', 'MAOP_403_AUTHORITY_WIDENING', 'MAOP_403_SEPARATION_OF_DUTIES', 'MAOP_403_TRUST_FLOOR', 'MAOP_409_IDEMPOTENCY_KEY_REUSED', 'MAOP_409_LEASE_CONFLICT', 'MAOP_409_LEASE_FENCED', 'MAOP_409_OUTCOME_UNRECONCILED', 'MAOP_410_LEASE_EXPIRED', 'MAOP_422_BUDGET_EXCEEDED', 'MAOP_422_EVIDENCE_MISMATCH', 'MAOP_422_GUARD_FAILED']. Description reworded (vendor-neutral).
43MetricNodeMetricNodev0.1keptIntroduced in CAOP v0.1. Example: examples/MetricNode.json. Structure identical in schema/maop-v1.schema.json.
44ApprovalRoutingRuleApprovalRoutingRulev0.1keptIntroduced in CAOP v0.1. Example: examples/ApprovalRoutingRule.json. Structure identical in schema/maop-v1.schema.json.
45LoopDriverLoopDriverv0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json. Description reworded (vendor-neutral), no structural change.
46ExecutionLocusExecutionLocusv0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json.
47AuthCustodianAuthCustodianv0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json. Description reworded (vendor-neutral), no structural change.
48AttestationTierAttestationTierv0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json.
49ConformanceProfileIdConformanceProfileIdv0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json.
50ConformanceProfileConformanceProfilev0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/ConformanceProfile.json. Structure identical in schema/maop-v1.schema.json.
51PromotionPolicyPromotionPolicyv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/PromotionPolicy.json. Structure identical in schema/maop-v1.schema.json.
52CapabilityRegistrationCapabilityRegistrationv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/CapabilityRegistration.json. Structure identical in schema/maop-v1.schema.json.
53EpistemicStatusEpistemicStatusv0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json.
54FreshnessFreshnessv0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json.
55DependsOnAlternativesDependsOnAlternativesv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/DependsOnAlternatives.json. Structure identical in schema/maop-v1.schema.json.
56InvalidationContextInvalidationContextv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/InvalidationContext.json. Structure identical in schema/maop-v1.schema.json.
57FactProvenanceFactProvenancev0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/FactProvenance.json. Structure identical in schema/maop-v1.schema.json.
58BitemporalFactBitemporalFactv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/BitemporalFact.json. Structure identical in schema/maop-v1.schema.json.
59StateConfigStateConfigv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/StateConfig.json. Structure identical in schema/maop-v1.schema.json.
60PreCommitHookPreCommitHookv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/PreCommitHook.json. Structure identical in schema/maop-v1.schema.json.
61PolicyRegistrationPolicyRegistrationv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/PolicyRegistration.json. Structure identical in schema/maop-v1.schema.json.
62FailedHookFailedHookv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/FailedHook.json. Structure identical in schema/maop-v1.schema.json.
63ExecuteSubStateExecuteSubStatev0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json.
64CommitSubStateCommitSubStatev0.1.2keptIntroduced in CAOP v0.1.2. Structure identical in schema/maop-v1.schema.json.
65DispatchStepDispatchStepv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/DispatchStep.json. Structure identical in schema/maop-v1.schema.json.
66DispatchDirectiveDispatchDirectivev0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/DispatchDirective.json. Structure identical in schema/maop-v1.schema.json.
67GoalPulseSLAGoalPulseSLAv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/GoalPulseSLA.json. Structure identical in schema/maop-v1.schema.json.
68PulseInputPulseInputv0.1.2keptIntroduced in CAOP v0.1.2. Used directly by compact.pulse. Example: examples/PulseInput.json. Structure identical in schema/maop-v1.schema.json.
69StageWorkInputStageWorkInputv0.1.2keptIntroduced in CAOP v0.1.2. Used directly by compact.stage_work. Example: examples/StageWorkInput.json. Structure identical in schema/maop-v1.schema.json.
70DispatchWorkInputDispatchWorkInputv0.1.2keptIntroduced in CAOP v0.1.2. Used directly by compact.dispatch_work. Example: examples/DispatchWorkInput.json. Structure identical in schema/maop-v1.schema.json.
71SettleReceiptInputSettleReceiptInputv0.1.2keptIntroduced in CAOP v0.1.2. Used directly by compact.settle_receipt. Example: examples/SettleReceiptInput.json. Structure identical in schema/maop-v1.schema.json.
72OpenLeaseOpenLeasev0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/OpenLease.json. Structure identical in schema/maop-v1.schema.json.
73StaleCommitmentStaleCommitmentv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/StaleCommitment.json. Structure identical in schema/maop-v1.schema.json.
74UnassignedBlockerUnassignedBlockerv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/UnassignedBlocker.json. Structure identical in schema/maop-v1.schema.json.
75RankedNextActionRankedNextActionv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/RankedNextAction.json. Structure identical in schema/maop-v1.schema.json.
76SystemAdvisorySystemAdvisoryv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/SystemAdvisory.json. Structure identical in schema/maop-v1.schema.json.
77ResumeBriefResumeBriefv0.1.2keptIntroduced in CAOP v0.1.2. Example: examples/ResumeBrief.json. Structure identical in schema/maop-v1.schema.json.
78PulseResponsePulseResponsev0.1.2keptIntroduced in CAOP v0.1.2. Used directly by compact.pulse. Example: examples/PulseResponse.json. Structure identical in schema/maop-v1.schema.json.
79StageWorkResultStageWorkResultv0.1.2keptIntroduced in CAOP v0.1.2. Used directly by compact.stage_work. Example: examples/StageWorkResult.json. Structure identical in schema/maop-v1.schema.json.
80SettlementResultSettlementResultv0.1.2keptIntroduced in CAOP v0.1.2. Used directly by compact.settle_receipt. Example: examples/SettlementResult.json. Structure identical in schema/maop-v1.schema.json.
81DispatchWorkResultDispatchWorkResultv0.1.2keptIntroduced in CAOP v0.1.2. Used directly by compact.dispatch_work. Example: examples/DispatchWorkResult.json. Structure identical in schema/maop-v1.schema.json.
82SteeringDeltaSteeringDeltav0.2keptIntroduced in CAOP v0.2. Example: examples/SteeringDelta.json. Structure identical in schema/maop-v1.schema.json.
83Phase2DeferredCheckPhase2DeferredCheckv0.2keptIntroduced in CAOP v0.2. Example: examples/Phase2DeferredCheck.json. Structure identical in schema/maop-v1.schema.json.
84TwoPhaseVerificationTwoPhaseVerificationv0.2keptIntroduced in CAOP v0.2. Example: examples/TwoPhaseVerification.json. Structure identical in schema/maop-v1.schema.json.
85VerifySubStateVerifySubStatev0.2keptIntroduced in CAOP v0.2. Example: examples/VerifySubState.json. Structure identical in schema/maop-v1.schema.json.
86RecordSubStateRecordSubStatev0.2keptIntroduced in CAOP v0.2. Example: examples/RecordSubState.json. Structure identical in schema/maop-v1.schema.json.
87OutcomeVerificationOutcomeVerificationv0.2keptIntroduced in CAOP v0.2. Example: examples/OutcomeVerification.json. Structure identical in schema/maop-v1.schema.json.
88IsolationPolicyIsolationPolicyv0.2keptIntroduced in CAOP v0.2. Example: examples/IsolationPolicy.json. Structure identical in schema/maop-v1.schema.json.
89DistilledReturnPayloadDistilledReturnPayloadv0.2keptIntroduced in CAOP v0.2. Example: examples/DistilledReturnPayload.json. Structure identical in schema/maop-v1.schema.json.
90ChildWorkChildWorkv0.2keptIntroduced in CAOP v0.2. Example: examples/ChildWork.json. Structure identical in schema/maop-v1.schema.json.
91CompactionModeCompactionModev0.2keptIntroduced in CAOP v0.2. Example: examples/CompactionMode.json. Structure identical in schema/maop-v1.schema.json.
92CapabilityStubCapabilityStubv0.2keptIntroduced in CAOP v0.2. Example: examples/CapabilityStub.json. Structure identical in schema/maop-v1.schema.json.
93HydratedCapabilityHydratedCapabilityv0.2keptIntroduced in CAOP v0.2. Example: examples/HydratedCapability.json. Structure identical in schema/maop-v1.schema.json.
94DispatchWorkInputV02DispatchWorkInputV02v0.2keptIntroduced in CAOP v0.2. Example: examples/DispatchWorkInputV02.json. Structure identical in schema/maop-v1.schema.json.
95PulseInputV02PulseInputV02v0.2keptIntroduced in CAOP v0.2. Example: examples/PulseInputV02.json. Structure identical in schema/maop-v1.schema.json.

Examples

Each example file is matched by filename to the definition of the same name and validated against CAOP v0.2 (JSON Schema 2020-12) during generation. 71 of 71 validate.

#FileDefinitionValid (v0.2)MAOP status
1examples/Approval.jsonApprovalyeskept
2examples/ApprovalDecision.jsonApprovalDecisionyeskept
3examples/ApprovalRoutingRule.jsonApprovalRoutingRuleyeskept
4examples/BitemporalFact.jsonBitemporalFactyeskept
5examples/CapabilityDescriptor.jsonCapabilityDescriptoryeskept
6examples/CapabilityRegistration.jsonCapabilityRegistrationyeskept
7examples/CapabilityStub.jsonCapabilityStubyeskept
8examples/ChildWork.jsonChildWorkyeskept
9examples/Commitment.jsonCommitmentyeskept
10examples/CommitmentCreate.jsonCommitmentCreateyeskept
11examples/CompactionMode.jsonCompactionModeyeskept
12examples/ConformanceProfile.jsonConformanceProfileyeskept
13examples/ContextBundle.jsonContextBundleyeskept
14examples/ContextResolveRequest.jsonContextResolveRequestyeskept
15examples/DependsOnAlternatives.jsonDependsOnAlternativesyeskept
16examples/DispatchDirective.jsonDispatchDirectiveyeskept
17examples/DispatchStep.jsonDispatchStepyeskept
18examples/DispatchWorkInput.jsonDispatchWorkInputyeskept
19examples/DispatchWorkInputV02.jsonDispatchWorkInputV02yeskept
20examples/DispatchWorkResult.jsonDispatchWorkResultyeskept
21examples/DistilledReturnPayload.jsonDistilledReturnPayloadyeskept
22examples/Error.jsonErroryeskept
23examples/EventEnvelope.jsonEventEnvelopeyeskept
24examples/Execution.jsonExecutionyeskept
25examples/ExecutionAccepted.jsonExecutionAcceptedyeskept
26examples/ExecutionCreate.jsonExecutionCreateyeskept
27examples/Fact.jsonFactyeskept
28examples/FactProvenance.jsonFactProvenanceyeskept
29examples/FailedHook.jsonFailedHookyeskept
30examples/GoalPulseSLA.jsonGoalPulseSLAyeskept
31examples/HydratedCapability.jsonHydratedCapabilityyeskept
32examples/InvalidationContext.jsonInvalidationContextyeskept
33examples/IsolationPolicy.jsonIsolationPolicyyeskept
34examples/MetricNode.jsonMetricNodeyeskept
35examples/ObservationAccepted.jsonObservationAcceptedyeskept
36examples/ObservationCreate.jsonObservationCreateyeskept
37examples/OpenLease.jsonOpenLeaseyeskept
38examples/OutcomeVerification.jsonOutcomeVerificationyeskept
39examples/Phase2DeferredCheck.jsonPhase2DeferredCheckyeskept
40examples/Plan.jsonPlanyeskept
41examples/PlanCreate.jsonPlanCreateyeskept
42examples/Policy.jsonPolicyyeskept
43examples/PolicyRegistration.jsonPolicyRegistrationyeskept
44examples/PreCommitHook.jsonPreCommitHookyeskept
45examples/PromotionPolicy.jsonPromotionPolicyyeskept
46examples/PulseInput.jsonPulseInputyeskept
47examples/PulseInputV02.jsonPulseInputV02yeskept
48examples/PulseResponse.jsonPulseResponseyeskept
49examples/RankedNextAction.jsonRankedNextActionyeskept
50examples/RecordCommit.jsonRecordCommityeskept
51examples/RecordCommitted.jsonRecordCommittedyeskept
52examples/RecordSubState.jsonRecordSubStateyeskept
53examples/ResultSubmission.jsonResultSubmissionyeskept
54examples/ResumeBrief.jsonResumeBriefyeskept
55examples/Review.jsonReviewyeskept
56examples/ReviewRequest.jsonReviewRequestyeskept
57examples/SettleReceiptInput.jsonSettleReceiptInputyeskept
58examples/SettlementResult.jsonSettlementResultyeskept
59examples/StageWorkInput.jsonStageWorkInputyeskept
60examples/StageWorkResult.jsonStageWorkResultyeskept
61examples/StaleCommitment.jsonStaleCommitmentyeskept
62examples/StateConfig.jsonStateConfigyeskept
63examples/SteeringDelta.jsonSteeringDeltayeskept
64examples/SystemAdvisory.jsonSystemAdvisoryyeskept
65examples/Transition.jsonTransitionyeskept
66examples/TransitionRequest.jsonTransitionRequestyeskept
67examples/TwoPhaseVerification.jsonTwoPhaseVerificationyeskept
68examples/UnassignedBlocker.jsonUnassignedBlockeryeskept
69examples/Verification.jsonVerificationyeskept
70examples/VerificationRequest.jsonVerificationRequestyeskept
71examples/VerifySubState.jsonVerifySubStateyeskept

The files stay in examples/ unchanged. New MAOP examples live in examples/maop-v1/.

Normative guarantees

MAOP section names refer to topics in docs/maop-v1.md.

G-001 · SPEC.md line 789 · kept

Every fact and commitment in the State API MUST carry one of three epistemic states (adoption), and separately a freshness value: [Q1]

G-002 · SPEC.md line 845 · refined

Whenever a new fact F_new supersedes an existing fact F_old (setting F_old.transaction_time.superseded_at), the Creasura kernel MUST, synchronously and within the same database transaction, re-evaluate every dependent commitment or fact reachable through reverse depends_on_fact_ids and depends_on_alternatives edges: [Q2]

G-003 · SPEC.md line 850 · kept

  • The kernel MUST enforce a declared max_invalidation_subgraph limit. An update whose affected subgraph exceeds it is rejected before commit with CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE (HTTP 413, in the v0.1 error envelope), and nothing is partially applied. [Q2]

G-004 · SPEC.md line 895 · kept

The kernel MUST reject unknown or cross-workspace fact IDs in depends_on_fact_ids or depends_on_alternatives with CAOP_422_PRECOMMIT_UNKNOWN_FACT_ID. [Q3]

G-005 · SPEC.md line 925 · kept

Every capability registered in the Capability API MUST declare its execution locus, credential custodian, lease timeout, provider-specific receipt verification keys, and Stage-2 promotion thresholds.

G-006 · SPEC.md line 955 · kept

To prevent conversational LLMs from treating dispatch as a completed turn and replying to the user before invoking their native tool, caop_dispatch_work in Stage 1 MUST return the following continuation envelope:

G-007 · SPEC.md line 996 · refined

A workspace thread MAY hold at most one unsettled EXECUTE_DISPATCHED or EXECUTE_EXPIRED invocation at a time. Any call to caop_stage_work or caop_dispatch_work while a lease is open MUST be rejected with CAOP_409_UNSETTLED_EXECUTION_LEASE, forcing the host client to verify whether the previous native tool call succeeded and settle the receipt via caop_settle_receipt first.

G-008 · SPEC.md line 1252 · refined

Deployments operating in ChatGPT (Custom GPT Instructions) or Claude (Project / MCP System Prompt) MUST include the following normative instruction block:

G-009 · SPEC.md line 1386 · kept

An APPROVE_WITH_STEERING_DELTA decision binds the approval to the patched plan, not the staged one. The kernel MUST apply the delta, re-run every Policy pre-commit hook and minimum_attestation check on the patched plan, and dispatch only if all pass; otherwise the work item returns to CANDIDATE_PROPOSAL with CAOP_422_PRECOMMIT_HOOK_FAILED. A delta can only narrow authority: added_policy_constraints may add restrictions but never remove existing ones. [c]

G-010 · SPEC.md line 1398 · refined

  • Hierarchical Sub-Agent Context Isolation: Heavy research or artifact-generation steps spawn an isolated child Work scope (parent_work_id) with its own ephemeral scratchpad. When the child completes RECORD, its raw intermediate turns are discarded and only the ratified commitment and distilled bitemporal facts merge back into the parent control plane. Pruning removes raw traces from the active context, not from provenance: every promoted fact MUST keep a provenance pointer (child work_id, invocation IDs and a content hash of the pruned trace). Raw traces MAY be deleted only under a declared retention policy. [d]

G-011 · SPEC.md line 1494 · kept

  • Informative note in §14.7 (the “MUST include” text is kept verbatim): “Conformance is determined by kernel behaviour; the kernel cannot verify that a host deployment includes this prompt.”

G-012 · SPEC.md line 1502 · kept

  • “MUST carry one of four epistemic states:” → “MUST carry one of three epistemic states (adoption), and separately a freshness value:”

G-013 · SPEC.md line 1511 · kept

  • §14.2.3 rewritten. Submitted text: “Whenever a new fact F_new supersedes an existing fact F_old (setting F_old.transaction_time.superseded_at), the Creasura kernel MUST synchronously traverse all reverse edges where depends_on_fact_ids contains F_old.fact_id and transition every active dependent commitment or fact to epistemic_status: "STALE_UPSTREAM_PREMISE" within the same database transaction.” Now: synchronous re-evaluation in the same transaction of every dependent reachable through reverse depends_on_fact_ids and depends_on_alternatives edges; a dependent becomes stale only when a required premise has no remaining CURRENT support; optional depends_on_alternatives groups interchangeable supports; staleness propagates transitively; a declared max_invalidation_subgraph limit rejects oversized updates before commit with CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE, nothing partially applied; re-support restores CURRENT; superseded facts and history are never rewritten. The §14.2.1 STALE_UPSTREAM_PREMISE definition gains “, under the support rule of §14.2.3”.

G-014 · SPEC.md line 1513 · kept

  • Sentence added in §14.3: “The kernel MUST reject unknown or cross-workspace fact IDs in depends_on_fact_ids or depends_on_alternatives with CAOP_422_PRECOMMIT_UNKNOWN_FACT_ID.”

G-015 · SPEC.md line 1541 · kept

  • Normative paragraph added after the caop_dispatch_work schema: “An APPROVE_WITH_STEERING_DELTA decision binds the approval to the patched plan, not the staged one. The kernel MUST apply the delta, re-run every Policy pre-commit hook and minimum_attestation check on the patched plan, and dispatch only if all pass; otherwise the work item returns to CANDIDATE_PROPOSAL with CAOP_422_PRECOMMIT_HOOK_FAILED. A delta can only narrow authority: added_policy_constraints may add restrictions but never remove existing ones.”

G-016 · SPEC.md line 1543 · kept

  • Added to the sub-agent isolation bullet, after “its raw intermediate turns are discarded …”: “Pruning removes raw traces from the active context, not from provenance: every promoted fact MUST keep a provenance pointer (child work_id, invocation IDs and a content hash of the pruned trace). Raw traces MAY be deleted only under a declared retention policy.” The IsolationPolicy and DistilledReturnPayload schemas gain the optional fields trace_hash and retention_policy.

Supplementary lower-case requirements

Not counted as guarantees (the keyword rule is upper case), but checked so that no lower-case obligation in the normative text is lost. Lines in code blocks and in the editorial history are skipped.

IDLineCAOP sectionTextMAOP mappingStatus
S-00180Implementation status- In the reference kernel, a verification capability (verification_capability_id) must be side-effect-free: it may only read external state. Dispatch refuses a deferred check whose capability is not registered as side-effect-free.Two-phase verification and approval steeringkept
S-00291Runtime checks beyond the schema- Receipt nonce: a Stage-1 receipt must echo the required_nonce from dispatch (CAOP_422_VERIFY_ARTIFACT_MISMATCH otherwise).Receipts and evidencekept
S-00392Runtime checks beyond the schema- Required receipt fields: the receipt’s raw_output must hold every field in the capability’s required_receipt_fields.Receipts and evidencekept
S-0041882.3 State> Critical requirement: provenance. Every material fact should have a traceable origin.Core abstractionskept
S-0052062.4 CapabilityA capability contract should describe what an operation can do, not merely what an agent is instructed to attempt.Core abstractionskept
S-0062222.5 Policy> Advisory vs. enforced. A policy written in an assistant’s instructions is advisory. A policy enforced by a runtime before executing an action is an actual control. Every Creasura policy must state which it is.Core abstractionsrefined
S-0072694.1 Observe> Invariant: replaying the same source event must not create duplicate observations.Outer supervision lifecyclekept
S-0082944.2 UnderstandThis operation should distinguish retrieved facts from inferred interpretations.Outer supervision lifecyclekept
S-0093384.4 PlanThe planner may use an LLM. The runtime must still validate the generated plan against schemas, dependencies, and policy constraints.Outer supervision lifecyclekept
S-0103694.6 VerifyVerification can include deterministic checks, human approval, or model-based evaluation. The verdict must identify which checks were performed.Outer supervision lifecyclekept
S-0113864.7 Record> Invariant: a conflicting state version must reject the transaction or invoke an explicitly defined conflict-resolution policy.Outer supervision lifecyclekept
S-0124105. Execution state machineThe eight lifecycle stages should not be confused with execution states.Child lifecycle (execution state machine)kept
S-0134435. Execution state machineThe API must reject invalid transitions.Child lifecycle (execution state machine)kept
S-0144545. Execution state machineA transition from CREATED directly to COMPLETED should be rejected unless the work type explicitly supports that shortcut. The runtime persists each accepted transition with an actor, timestamp, reason, and correlation ID.Child lifecycle (execution state machine)kept
S-0154646. Capability APIThe boundary between the OS and the assistants and services that do the work. The OS must not assume every provider supports the same features.Capabilities: registration and lazy discoveryrefined
S-0165176.1 Native assistant mapping> Note: Programmatic invocation of an assistant’s native work surfaces must use an explicitly supported interface. Do not assume arbitrary sessions can be launched through MCP.Capabilities: registration and lazy discoverykept
S-0175387. Cross-cutting contracts> v0.2: An approval can steer the work it approves: APPROVE_WITH_STEERING_DELTA binds the approval to a patched plan, which must pass every policy check again. See §15.1.Two-phase verification and approval steeringkept

Additions

New operations

operationIdMethod and pathJustification
agents.registerPOST /maop/v1/agentsCAOP has principals but no agent identity: roles and capabilities could not be declared per agent, so separation of duties (implementer != reviewer != approver) could not be checked. Capabilities are advertised as stubs and hydrated lazily, preserving v0.2 lazy discovery.
delegations.createPOST /maop/v1/delegationsv0.2 isolates child work (parent_work_id, isolation_policy) but only through stage_work. A first-class delegation lets a supervisor hand work to another agent with an isolation policy, a budget and an authority subset that can only narrow the parent's authority (Act->Coordinate edge).
delegations.getGET /maop/v1/delegations/{delegation_id}Read model for a delegation and its child lifecycle state, so a supervisor can re-evaluate without polling executions one by one.
leases.renewPOST /maop/v1/leases/{lease_id}/renewv0.2 leases have a timeout but no renewal or fencing. Renewal with a monotonic fencing_token prevents a holder whose lease expired from settling a receipt after another holder took over (split-brain).
receipts.getGET /maop/v1/receipts/{receipt_id}Receipts were only returned inline by settle_receipt. A stable read path with idempotency_key, outcome (including outcome_unknown) and causal_parents makes recovery and audit possible after a crash.
supervision.evaluatePOST /maop/v1/supervision/{work_id}/evaluateCAOP re-evaluates only on pulse. Event-driven re-evaluation of durable guards returns the next outer transition (including Act->Decide, Act->Coordinate, Verify->Act and any->Recover) with the guards that passed and failed.

New definitions

DefinitionJustification
AgentIdentityStable identity of an agent (who acts), distinct from PrincipalRef (who is accountable).
AgentRoleEnum supervisor, planner, implementer, reviewer, verifier, approver, observer: needed for separation-of-duties guards.
AgentRegistrationRequest/response body of agents.register: identity, roles and lazily advertised capability stubs.
DelegationFirst-class supervisor-to-child work record: isolation policy, budget, authority subset, child lifecycle state.
DelegationCreateRequest body of delegations.create.
AuthorityGrantExplicit, expiring, scoped authority with trust_level (T0_relayed, T1_attested); delegation and steering can only narrow it.
LeaseFenced execution lease (lease_id, holder, fencing_token, expires_at); generalises OpenLease.
LeaseRenewalRequest body of leases.renew; the runtime rejects a stale fencing_token.
ReceiptDurable action receipt (idempotency_key, outcome incl. outcome_unknown, evidence_refs, causal_parents) for audit and recovery.
SupervisionStageEnum of outer-lifecycle stages observe ... closed, including recover, so transitions are machine-checkable.
ChildLifecycleStateEnum of child-work states proposed ... expired, mapping delegated work onto the inner lifecycle.
GuardDurable guard (authority, policy, evidence, freshness, lease, separation_of_duties, budget) re-evaluated on events, not only at commit.
SupervisionEvaluationRequest/response body of supervision.evaluate.
TransitionDecisionResult of evaluation: from_stage, to_stage, trigger, guards_passed, guards_failed, next_action.
CausalEvidenceEvidence item with digest, derived_from and bitemporal times, linking receipts, facts and guards causally.

Improvements over CAOP v0.2

Each improvement is additive: a CAOP v0.2 client that ignores it still gets the v0.2 behaviour.

  1. Vendor-neutral protocol. MAOP names no vendor and no product in its title, ids, paths or schema $id, and does not position itself as an operating system. CAOP text that named a vendor kernel or specific hosts (G-002, G-008, S-006, S-015) is reworded so the obligation falls on "the runtime" or "the host"; the obligation itself is unchanged. Wire tokens are kept exactly as they are so that existing clients keep working: the error codes (CAOP_409_UNSETTLED_EXECUTION_LEASE, CAOP_422_PRECOMMIT_* and the others), the AuthCustodian enum value CREASURA_VAULT, and the compact tool names (caop_pulse, caop_stage_work, caop_dispatch_work, caop_settle_receipt, carried in x-maop-mcp-tool). Renaming these is listed as an open question in the migration guide.
  2. A normative outer lifecycle. CAOP defines eight lifecycle stages and an execution state machine but no supervisor loop around them. MAOP adds SupervisionStage (observe, decide, plan, coordinate, act, verify, review, approve, record, recover, closed) with explicit back-edges: Act→Decide (a guard fails or new evidence invalidates the plan), Act→Coordinate (a child needs re-delegation), Verify→Act (a phase-2 deferred check fails), any→Recover (lease lost or outcome unknown) and Recover→Decide.
  3. An explicit inner (child) lifecycle. ChildLifecycleState (proposed, delegated, leased, executing, submitted, verifying, accepted, rejected, cancelled, expired) maps delegated work onto the CAOP execution states instead of leaving it implicit in parent_work_id.
  4. Durable guards and event-driven re-evaluation. CAOP checks pre-commit hooks at COMMIT and re-evaluates on pulse. MAOP makes each guard (authority, policy, evidence, freshness, lease, separation_of_duties, budget) a durable record that supervision.evaluate re-checks whenever an event arrives, such as a superseded fact, an expired lease or a returned receipt. The result is a TransitionDecision that lists the guards that passed and failed and the next action.
  5. Fenced leases. CAOP v0.2 allows one open lease per thread, but a lease has no renewal and no fencing. Lease.fencing_token is monotonic and leases.renew extends a lease. A holder with a stale token cannot settle, which closes the split-brain case in which an expired worker reports after a new one has taken over.
  6. Receipts that support recovery. Receipt adds outcome_unknown alongside succeeded and failed, plus an idempotency_key and causal_parents, and receipts.get reads a receipt back after a crash. Recovery becomes a lifecycle stage instead of a manual procedure.
  7. Agent identity and separation of duties. agents.register with AgentIdentity and AgentRole lets the runtime enforce rules such as "implementer ≠ reviewer ≠ approver". CAOP had principals but could not check this.
  8. Authority as data. AuthorityGrant makes authority explicit, scoped and expiring, with a trust level (T0_relayed or T1_attested). A delegation or a steering delta can only narrow a grant, which states CAOP's "a delta can only narrow authority" rule (G-009) in general form.
  9. First-class delegation. delegations.create and delegations.get carry the isolation policy, the budget and the authority subset. The v0.2 sub-agent isolation and provenance-pointer rule (G-010) is preserved and extended.
  10. Causal evidence. CausalEvidence (with digest, derived_from and bitemporal times) links receipts, facts and guards, so an invalidation (G-002) can be traced to the guards and transitions it affects.

All five v0.2 mechanisms are preserved unchanged: two-phase verification (TwoPhaseVerification, Phase2DeferredCheck, VerifySubState, OutcomeVerification), approval steering (SteeringDelta, G-009), sub-agent isolation (IsolationPolicy, ChildWork, DistilledReturnPayload, G-010), compaction (CompactionMode) and lazy discovery (CapabilityStub, HydratedCapability).

Acceptance criteria checklist

"Owner" names the workstream that writes each file. Rows that depend on another workstream's file need checking against that file before the PR is opened.

#CriterionSatisfied byState
1Pin the CAOP v0.2 baseline and map all 17 operations, 95 schema definitions, 71 examples and normative guarantees to MAOP or justify improvements.tests/parity.json and tests/parity_gen.py (counts asserted at generation: 17 / 95 / 71, 16 guarantees; reproducibility checked by tests/validate.py check 10); this file (baseline pin, full tables, Additions, Improvements)Done (parity)
2Historical CAOP contracts unchanged; document migration and compatibility.The baseline pin table above (sha256 of the 9 frozen files, checked against the working tree); docs/maop-v1-migration.md; tests/validate.py (conformance)Done for documentation; hash check in CI depends on tests/validate.py
3Vendor-neutral MAOP, with no Creasura protocol branding or operating system positioning.docs/maop-v1.md (spec); schema/maop-v1.schema.json (relative $id); openapi/maop-v1.openapi.yaml/.json (placeholder server); Improvement 1 aboveDepends on spec and contract workstreams
4A normative outer and inner lifecycle, including Act→Decide and Act→Coordinate, durable guards and event-driven re-evaluation.docs/maop-v1.md (lifecycle sections); SupervisionStage, ChildLifecycleState, Guard, TransitionDecision in schema/maop-v1.schema.json; supervision.evaluate in the OpenAPI; Improvements 2–4Depends on spec and contract workstreams
5Preserve two-phase verification, approval steering, sub-agent isolation, compaction, lazy discovery, receipts, authority and recovery.tests/parity.json: guarantees G-006–G-010 and the definitions listed in the paragraph above, all kept; additions Receipt, AuthorityGrant, Lease, the recover stageDone (parity); the semantics are stated in docs/maop-v1.md
6Versioned MAOP OpenAPI, JSON Schema, examples and automated conformance checks.openapi/maop-v1.openapi.yaml, openapi/maop-v1.openapi.json, schema/maop-v1.schema.json, examples/maop-v1/*.json, tests/validate.py, tests/README.mdDepends on contract and conformance workstreams
7A Northstar A–K trace with the outer stage, child lifecycle, trigger, guard, authority, evidence and transition.docs/maop-v1.md (Northstar A–K section: one end-to-end scenario, one row per step)Depends on spec workstream
8Submit a reviewable PR; do not merge or deploy.A pull request from design/maop-v1 into main (not a file)Open at integration; not merged or deployed

Regenerating

tests/parity.json and the tables in this file are generated by tests/parity_gen.py, which is committed with them. From a clone whose history contains the baseline commit, run:

pip install jsonschema pyyaml          # jsonschema >= 4.18
python tests/parity_gen.py all         # rewrites tests/parity.json and docs/maop-v1-parity.md
python tests/parity_gen.py json        # only tests/parity.json
python tests/parity_gen.py md          # only this file, rendered from tests/parity.json
python tests/parity_gen.py all --out /tmp/parity   # write to another directory instead

The generator:

  1. reads the baseline files from git at the pinned commit (git show 8c7bd07939171efc2d39079bd018904175ea8db2:<path>), never from the working tree;
  2. asserts the nine sha256 values and the 17/95/71 counts;
  3. validates every example;
  4. extracts the guarantee lines; and
  5. compares the MAOP contracts in the working tree with the baseline, ignoring descriptions: an identical structure is kept; new optional properties, new enum values, new oneOf/anyOf branches, new response codes, new optional parameters and annotation-only keywords are refined; anything else (a removed property or enum value, a newly required property, a new constraint keyword, a changed value) is CHECK.

The output is deterministic: it has no timestamps, and sets are sorted. tests/validate.py check 10 (parity-reproducible) runs the generator into a temporary directory and fails unless both files are byte-identical to the committed ones, so any change to the MAOP schema or OpenAPI must be followed by a regeneration.

Hand-written content lives in tests/parity_gen.py and this template (tests/parity_tail.md): the status judgements for the 10 normative guarantees, the section-to-topic map, the justifications for the additions, and the prose sections of this file. A reviewer can recompute the counts independently with:

git show 8c7bd07939171efc2d39079bd018904175ea8db2:SPEC.md | grep -cE '\b(MUST|SHALL|SHOULD|REQUIRED)\b'   # 16
ls examples/*.json | wc -l                                                                                 # 71
python -c "import json;print(len(json.load(open('schema/caop-v0.2.schema.json'))['\$defs']))"            # 95