Generated from packages/spec/v0.1/decisions.md. Edit the source file, not this page.

Agent Revision Markup Design Decisions

Status: living draft.

D001: JSON Is The Core Model

Decision: Agent Revision Markup core objects are JSON. JSON Schema is the validation surface. Canonical JSON is the hashing and signing surface.

Reason: Agent runtimes, web runtimes, CLMs, services, and SDKs all handle JSON naturally. JSON also gives a clear canonicalization path for signatures.

Consequence: XML is a carriage wrapper in DOCX, not the semantic model.

D002: DOCX Uses Custom XML Wrappers

Decision: DOCX carriage stores canonical JSON payloads inside custom XML parts.

Reason: DOCX is an OOXML package. Custom XML is the native extension point for structured payloads that should travel with the file.

Consequence: Readers parse the JSON payload as the semantic object. XML summary elements are discovery hints.

D003: Record-Defined Artifacts Are The Source Of Truth

Decision: Visible artifacts are defined by Agent Revision Markup records and mapped to the document. Native Word ids are optional hints.

Reason: Word comment ids and revision ids are not stable across editors, saves, and round-trips.

Consequence: A runtime must be able to regenerate visible artifacts from record artifact content and anchors.

D004: Approval Is A Binding, Not A Standalone Event

Decision: Human approval is carried inside a turn authority object.

Reason: Approval only has protocol meaning when it is bound to the exact draft and turn it approved.

Consequence: A standalone "approve" event is not sufficient for human-approved agent turns.

D005: Extensions Are Namespaced And Preserved

Decision: Vendor or customer metadata belongs in namespaced extensions, but the extension mechanism is not normative in the v0.1 tested kernel.

Reason: The standard must support traceability needs such as internal playbook refs without making private business fields universal.

Consequence: The next implementation change should add an extension object with preserve and signature rules. Until then, v0.1 examples do not include extensions in signed objects.

D006: Server References Are Locators, Not Trust Roots

Decision: serverRef cannot prove authority.

Reason: A malicious document can point to a malicious server.

Consequence: Trust must come from local configuration, explicit consent, or a future issuer or countersignature profile.

D007: Contract Negotiation Is Profile One

Decision: Contract negotiation is the first profile, not the whole core standard.

Reason: Cross-party negotiation is where signed, file-carried verification is necessary. Internal audit is useful, but one platform can already keep an internal log.

Consequence: Contract-specific topics and workflows stay in the profile. Core stays format-neutral and use-case-neutral.

D008: Raw Ed25519 Is The Initial Signature Path

Decision: Draft 0.1 uses raw Ed25519 over canonical JSON signing payloads.

Reason: The reference implementation already exercises Web Crypto Ed25519 and the payloads are simple. JWS and COSE add implementation surface that is not needed for this draft.

Consequence: JWS and COSE are deferred. A future profile may define them if interoperability demand appears.

D009: V0.1 Uses Reference Implementation Vocabulary

Decision: The v0.1 draft uses the current wire names: sessionId, authorPartyId, decision, visibleArtifacts, and ontologyRefs.

Reason: The tested reference implementation and adversarial tests already protect those semantics. Fresh names such as recordId, actor, or artifacts flatten distinctions the verification model depends on.

Consequence: Public renames must be explicit migrations. The draft must not define a cleaner but untested protocol beside the implementation.

D010: Full Record DOCX Carriage Is Deferred

Decision: The DOCX carriage profile documents manifest and cache projections as tested v0.1 behavior. Full signed record carriage is the next addition.

Reason: The current code writes manifest and cache projections. The cache carries summaries, not signed turn bodies.

Consequence: Readers may show cache continuity but must not claim full record verification from cache alone.