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

Agent Revision Markup Extension Surface 0.1

Status: proposed compatibility addition.

1. Purpose

Agent Revision Markup must stay small enough for independent tools to implement while still allowing vendors and customers to carry domain-specific traceability.

The v0.1 tested kernel does not yet include signed extension objects. This document defines the intended extension surface that should land with implementation support before public interop claims.

2. Principle

The core record should answer the questions every compatible tool needs:

who acted
under what authority
what changed
what human approved
where it maps to the document
how to verify it

Everything vendor-specific belongs in namespaced extensions.

3. Extension Shape

Extensible objects should carry an extensions object:

{
  "extensions": {
    "com.example.trace.v1": {
      "runRef": "run_123"
    }
  }
}

Extension ids SHOULD use reverse DNS naming:

com.example.playbookTrace.v1

Extension ids under org.agentrevisionmarkup.* are reserved for future standard extensions.

4. Required Implementation Rules

When extensions become normative:

readers MAY ignore unknown extensions
writers MUST preserve unknown extensions
signed objects MUST include their extensions in the signed hash
extensions MUST NOT redefine core fields
extensions that affect provenance or user-visible decisions MUST be inside the signed object they affect

5. Privacy

Extensions are not a privacy escape hatch.

Extensions MUST NOT include:

private keys
raw private playbooks
hidden strategy
internal chain-of-thought or model reasoning
secrets or access tokens

Sensitive traceability SHOULD use opaque references, hashes, encrypted payloads, or off-file references.

6. Example: Playbook Traceability

The standard should not require a universal playbook version field. A customer or vendor can carry its own traceability with a namespaced extension.

{
  "extensions": {
    "com.northwind.playbookTrace.v1": {
      "playbookRef": "pb_48291",
      "playbookVersionRef": "pbv_2026_06_10",
      "runRef": "run_8831"
    }
  }
}

This lets a system answer "which internal playbook produced this?" without forcing every other implementation to understand that vendor's playbook model.

7. First Landing Point

The first implementation target should be turn.body.extensions.

Reason: customer traceability is usually tied to a specific action, not the whole manifest. Putting the extension inside the signed turn body makes the traceability tamper-evident without exposing private playbook contents.

Extensions

On this page