A2F/1.0 Specification

01The four formats

The division of labor is deliberate: .spec says what is meant, .arch says what is allowed, .script says how it proceeds, and .orch proves what happened. A document that mixes those concerns can smuggle execution inside evidence — the exact failure the profile system below exists to prevent.

02Runtime semantics

A compliant A2F runtime, given a package of these documents, proceeds in one order:

load .arch     → determine capabilities, budgets and policy
parse .spec    → determine intent, participants and constraints
execute        → only through capabilities the .arch grants
emit .orch     → the append-only trace: events, receipts,
                 policy decisions, lifecycle transitions

Governance precedes intent, intent precedes execution, and evidence is emitted rather than reconstructed. In the shipped implementation the load step is the session’s capability scope, execution passes the TARG gate operation by operation, and the emitted trace is the orchestration graph serialised.

03Conformance profiles

The precedent is instructive: archival document profiles forbid scripting precisely to keep long-term rendering deterministic, while executable notebooks learned to gate untrusted outputs behind a trust model. A2F adopts both lessons as first-class profiles instead of afterthoughts.

04The .spec document

A .spec wraps the orchestration spec in the family envelope. This is the same shape the Studio’s OPI accepts — saving one and loading it back runs the same orchestration:

{
  "a2f":   "a2f/1.0",
  "kind":  "spec",
  "at":    1786959866608,
  "title": "two-part comparison",
  "spec": {
    "title":    "two-part comparison",
    "parallel": true,
    "approval": false,
    "steps": [
      { "kind": "research", "query": "…", "depth": 1 },
      { "kind": "research", "query": "…", "depth": 1 }
    ]
  }
}

05The .arch document

A generated .arch is the session’s governance, exported: the tool roster and the per-session budgets the runtime actually enforced. It is marked generated because authoring one grants nothing — in 1.0 the scope is decided by the runtime, and the document is its honest reflection:

{
  "a2f":       "a2f/1.0",
  "kind":      "arch",
  "generated": true,
  "session":   "s_…",
  "tools":     ["live_lookup", "fetch_page", "live_ui_create", "orch_run", …],
  "capabilities": { "*": 60, "live_ui_create": 24, "fetch_page": 20, … }
}

06The .orch document (generated)

The trace below was exported from a production run of the reference implementation — an orchestration invoked over PAP, its lifecycle receipts intact. It is reproduced verbatim except for elision marks:

{
  "a2f":     "a2f/1.0",
  "kind":    "orch",
  "profile": "archive",
  "session": "pap",
  "at":      1786959869906,
  "digests": null,
  "events":   [ … ],
  "receipts": [ … ],
  "policy":   [ … ],
  "orchestrations": [{
    "id": "O1",
    "title": "what year was the transistor invented",
    "state": "done",
    "progress": "1/1",
    "policy": { "parallel": false, "approval": false, "retries": 0 },
    "participants": 1,
    "steps": [{ "i": 0, "kind": "research", "state": "done", "attempts": 1 }],
    "receipts": [
      { "verb": "addParticipant", "note": "research",  "at": 1786959866608 },
      { "verb": "delegate", "note": "research: what year …", "at": 1786959866608 },
      { "verb": "create",   "at": 1786959866608 },
      { "verb": "queued",   "at": 1786959866608 },
      { "verb": "start",    "at": 1786959866609 },
      { "verb": "done",     "at": 1786959869732 }
    ],
    "createdAt": 1786959866608,
    "endedAt":   1786959869732
  }]
}

Four sections, ordered by time: events (tool operations with outcomes and durations), receipts (surface actions with their five-valued verified/attempted/blocked/failed/held outcomes), policy (every governance refusal, with the stage that objected), and orchestrations (lifecycle snapshots, receipt by receipt). The document is append-only in construction: sections accumulate; nothing is rewritten.

07The reference implementation

In LabsAI Studio: the Work view’s download controls export the live session’s .orch and any orchestration’s .spec; the OPI accepts wrapped .spec documents back; and the PAP endpoint’s export capability returns the .orch of any recorded protocol run. Spoken, the work these documents record arrives as Speech‑to‑Action and Speech‑to‑Orchestration Voice Commands — the trace is what those commands leave behind.

08Security posture, inherited deliberately

A2F’s safety model borrows from the format families that learned these lessons expensively. From archival documents: restricting dynamic features is what keeps a record deterministic for decades — hence a2f-archive forbids embedded execution outright rather than sandboxing it. From executable notebooks: outputs that can run are a trust decision, not a rendering decision — hence a2f-exec requires the consuming runtime to sandbox and capability-scope embedded agents, never trusting the document’s own word. From modern supply chains: packages become trustworthy through signing, attestation and content addressing — which is A2F’s standardization path, stated in §06 as direction. A format for evidence must be hardest to abuse exactly where it claims the most.

One consequence is worth making explicit: because an archive-profile .orch can execute nothing, forwarding one is always safe — the reader risks only being informed. The profile boundary, not scanning or heuristics, is what makes the trace shareable.

09Versioning & changelog