DOCX Carriage
Rendered from packages/spec/v0.1/docx-carriage.md
Generated from
packages/spec/v0.1/docx-carriage.md. Edit the source file, not this page.
DOCX Carriage Profile 0.1
Status: implementer draft.
1. Purpose
This profile defines how the Agent Revision Markup kernel is carried inside DOCX files.
The core data model is JSON. DOCX carriage uses custom XML parts as containers for canonical JSON payloads. The XML wrapper exists so OOXML tools can discover and preserve the payload.
2. Tested Parts
The v0.1 reference implementation writes and reads:
- manifest projection
- cache projection
A full record projection is the expected next carriage addition, but it is not part of the tested v0.1 kernel yet.
3. Wrapper Shape
Each custom XML part contains a root element and exactly one payload element.
The payload element MUST have:
encoding="application/json"The text content of the payload is escaped canonical JSON.
The reference namespaces and root names are:
| Projection | Root | Namespace |
|---|---|---|
| Manifest | agentRevisionManifest | urn:agentrevisionmarkup:docx:manifest:0.1 |
| Cache | agentRevisionCache | urn:agentrevisionmarkup:docx:cache:0.1 |
4. Versioning
The wrapper version attribute is the carriage version. The JSON schemaVersion field is the core wire schema version.
A reader MUST treat wrapper version and payload schema version as independent.
5. Manifest Projection
The manifest projection carries enough information for a compatible runtime to discover the session and decide whether to contact an external service.
The payload MUST include:
schemaVersionmanifestKindsessionIdserverRefautoCallmanifestHashmanifest
autoCall MUST be false. A runtime MUST NOT contact serverRef without user consent or trusted local configuration.
6. Cache Projection
The cache projection is a disposable summary for fast UI and continuity.
The payload MUST include:
schemaVersioncacheKindsessionIdserverRefautoCallmanifestHashledgerHeadturnCountupdatedAt- party summaries
- anchor summaries
- turn summaries
The cache projection MUST NOT be treated as a complete verifiable record. It carries summaries, not signed turn bodies.
If a cache projection exists without the full record, a reader MAY display summary state but MUST NOT claim full ledger verification.
7. Package Shape
A writer SHOULD create the custom XML part, item properties part, custom XML relationship, content type override, and document relationship required by OOXML custom XML storage.
A Level 0 Preserver SHOULD round-trip unknown Agent Revision Markup custom XML parts and their relationships unchanged.
8. Native Visible Artifacts
DOCX comments, tracked insertions, tracked deletions, and content controls are the human-visible surface.
The Agent Revision Markup record is the machine-readable source for artifact content and provenance. Native Word ids are optional hints and MUST NOT be required for verification or reconstruction.
If native comments or tracked changes are stripped but the Agent Revision Markup record survives, a runtime SHOULD rebuild visible artifacts from the record and anchors.
If Agent Revision Markup custom XML is stripped but native visible artifacts survive, a runtime MAY show those artifacts as ordinary Word artifacts but MUST NOT claim it has verified the Agent Revision Markup record.
If both custom XML and durable anchors are stripped, in-place reconstruction is not possible from the file alone. A runtime MAY recover from an external custodian if the user consents.
9. Degradation Matrix
| Manifest | Full record | Cache | Native artifacts | Reader behavior |
|---|---|---|---|---|
| present | present | any | any | parse and verify full record |
| present | absent | present | present | show summary and visible artifacts, do not claim full verification |
| present | absent | present | absent | show summary only, offer recovery from custodian with consent |
| present | absent | absent | present | show manifest presence and native artifacts only |
| absent | absent | absent | present | ordinary DOCX behavior |
| absent | absent | absent | absent | no Agent Revision Markup state |
The first row is not fully implemented until full record carriage lands.
10. Security Requirements
A reader MUST treat all custom XML payloads as untrusted until parsed and verified.
A reader MUST NOT feed raw verifier errors or untrusted document text to an agent as instructions.
serverRef is a locator, not a trust root. Trust in a server origin must come from runtime configuration, a trusted manifest signature profile, or explicit user consent.