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

Agent Revision Markup Core 0.1

Status: implementer draft.

This draft documents the smallest tested kernel of Agent Revision Markup. It intentionally uses the reference implementation's wire vocabulary. Future public renames must be explicit migrations, not silent spec drift.

1. Purpose

Agent Revision Markup is track changes for agents: a signed, document-carried revision record that says who acted, under what authority, what changed, what a human approved, and how another tool can check it.

Agent Revision Markup does not replace comments or tracked changes. It defines the structured record beneath them.

2. Minimal Kernel

The v0.1 kernel defines:

a session manifest
an ordered ledger of signed turns
human approval as a binding inside a turn authority
record-defined visible artifacts
canonical JSON hashing and signing
DOCX custom XML carriage for manifest and cache projections

Everything else is profile or extension surface.

3. Non Goals

Agent Revision Markup is not:

an agent runtime
an e-signature format for final execution
a co-editing or keystroke sync protocol
a CLM platform
a smart contract system
a certified identity system

There is no agent in the file. The document carries a record, not a runtime.

4. Data Model

The canonical data model is JSON. Protocol objects are serialized as canonical JSON for hashing and signing.

The current reference implementation uses numeric schemaVersion: 2. The spec version is 0.1. These are intentionally separate until the first public migration.

The core objects are:

manifest: parties, public signing keys, documents, anchors, and hash-pinned ontology references.
record: a manifest plus an ordered ledger.
turn: a signed revision event.
authority: the reason a turn was allowed.
humanApproval: a human approval binding inside authority.
visibleArtifact: a record-defined comment, insertion, deletion, or replacement.

5. Manifest

A manifest states the session participants and public verification material.

A manifest MUST include:

schemaVersion
sessionId
createdAt
ontologyRefs
parties
documents
anchors

Identity strings in a manifest are stated. They are not certified identity unless a future issuer or countersignature profile says otherwise.

6. Turns

A turn is the unit of recorded document work.

A turn body MUST include:

schemaVersion
sessionId
manifestHash
turnId
sequence
previousTurnHash
authorPartyId
createdAt
anchorId
clauseTopic
decision
authority
visibleArtifacts

visibleArtifacts MUST contain at least one artifact. This is intentional: a recorded turn must stay connected to the human-visible document surface.

A turn MUST be signed. A verifier MUST reject a turn if:

the body hash does not match the body
the turn hash does not match the signed turn
the signature does not verify against the author key
previousTurnHash does not match the prior turn
sequence does not match the turn position
turnId duplicates an earlier turn id in the same record
sessionId does not match the manifest
manifestHash does not match the presented manifest
clauseTopic is outside the manifest ontology references
anchorId is missing from the manifest
clauseTopic does not match the anchor topic

The current decision vocabulary is:

propose
counter
accept
reject
escalate

Profiles may restrict how these decision kinds appear in product UI.

7. Authority

The core authority kinds are:

direct-party-signature
human-approved-agent-draft

If a signing key is marked turnsRequireHumanApproval: true, a verifier MUST reject turns from that key unless the authority kind is human-approved-agent-draft.

8. Human Approval Binding

Approval is not a standalone event. Approval is an authority binding inside a turn.

A human approval MUST bind:

schemaVersion
sessionId
manifestHash
approvalId
mandateId
approved
approvedBy
approvedAt
approvalSubjectHash
approvedDraftHash
approvalSignature

A verifier MUST reject a human-approved turn if:

the approval sessionId does not match the turn sessionId
the approval manifestHash does not match the turn manifestHash
the approval mandateId does not match the authority mandateId
the approval time does not match the turn signature time
the approval signature time does not match the approval time
the approved draft hash does not match the committed turn draft
the approval signature does not verify against the approver key

9. Visible Artifacts

Visible artifacts are defined by the record and mapped to the document. They are not defined by native Word ids.

A visible artifact MUST include:

artifactId
kind
anchorId
clauseTopic
authorPartyId
text

Native references are optional hints to a carriage profile. They MUST NOT be the source of truth. A conforming runtime MUST be able to rebuild visible artifacts from record-defined artifact data and anchors.

10. Canonicalization And Hashing

Agent Revision Markup uses canonical JSON for hashing and signing.

The target canonicalization is RFC 8785 JSON Canonicalization Scheme with stricter input restrictions:

no undefined
no non-finite numbers
no sparse arrays
no non-plain objects
no functions or symbols

This draft treats RFC 8785 compatibility as a conformance requirement that still needs an explicit test vector in the reference implementation.

All hashes use SHA-256 and are encoded as:

sha256:<64 lowercase hex characters>

11. Signatures

The default signature algorithm is raw Ed25519 over the canonical JSON signing payload. Public keys are represented as JWK or PEM.

Private key material MUST NOT appear in a manifest, record, turn, approval, visible artifact, or DOCX custom XML payload.

12. Extension Boundary

The v0.1 tested kernel does not yet include an extensions object in signed core schemas.

The extension mechanism in extensions.md is the next compatibility addition. It is included because vendor and customer traceability is a real requirement, but it is not normative for v0.1 until the reference implementation accepts, preserves, signs, and verifies it.

13. Conformance Levels

Level 0: Preserver

Preserves Agent Revision Markup custom XML parts and relationships when reading and writing a document.
Does not need to parse or verify the record.

Level 1: Reader

Finds Agent Revision Markup parts.
Parses the manifest and cache payloads.
Displays that a record is present.
Does not append turns.

Level 2: Verifier

Performs all Reader requirements.
Verifies hashes, signatures, sequence, manifest binding, duplicate turn ids, ontology membership, anchor matching, and approval bindings.

Level 3: Writer

Performs all Verifier requirements.
Appends valid turns.
Updates DOCX carriage payloads.

Level 4: Collaborating Runtime

Performs all Writer requirements.
Maps record-defined visible artifacts to document-native artifacts.
Rebuilds visible artifacts from the record when native artifacts are missing.
Implements at least one profile.

14. Forks

A fork occurs when two valid turns claim the same prior head and sequence in different copies of a record.

A verifier MUST detect forks when it sees them. This draft does not define automatic fork resolution. Profiles MAY define reconciliation flows. A runtime MUST NOT silently merge forks.

Core Model