reference

Data structures

Leaf's state is JSON: the reading the server sends a page's browser, the events a page's log records, and the records Leaf keeps beside the log. Each table below lists one structure's fields with their types, whether each is required, and what it means.

The tables are generated from the schemas Leaf validates and tests against, so they change when the code does. An event kind's meaning is written once, in Events and threads, which each kind below links to. How the pieces fit together is on How it works.

Served state

The page's runtime reads the state from GET /api/state. The definitions at the end of this section are the JSON answers to its posts; a user-view or interaction post answers with no body. leaf page state prints a selection of the same reading.

`GET /api/state`

The answer GET /api/state serves a page's runtime, which the POST /api/event answer carries as state and leaf.page publishes as /_leaf/state/*.json: Reading, which served_state.page.read_served_page composes, with what the serving route adds. Leaf alone writes it, so nothing validates it in flight; the tests validate real readings against this schema, and the browser build generates its type from it (build/browser/contract-types.mjs) and holds it to the schema pages vendored at the current protocol read (build/browser/protocol.mjs). leaf:event refers to any kernel event record, leaf:event/<kind> to one kind's and leaf:verb to an x-state verb, as registry.schema.leaf_resources composes them; an object here adding served fields to an event record closes it again with unevaluatedProperties.

Type: Reading.

Field	Type	Required	Description
`others`	array of object	yes	The machine's other live pages, each its compact row (`server_rows.py`), named by `page_key` and linked by `url` (`presence.other_leaves`). A row is open: a neighbor's Leaf may publish fields this one ignores. An export holds none.
`others[].page_key`	string	yes
`others[].url`	string	yes
`others[].title`	string	yes
`others[].session_cwd`	string or null	yes
`others[].activity`	object	yes
`reading`	string	yes	The news token of the facts this answer read (`served_state.reading`), which the tab's freshness reads compare.
`leaf`	Provenance		The Leaf serving the page, as `layer.payload_provenance` reads it, sent only where it is another than the one that vendored the page.
`release`	string		The leaf.page release that served the page.

`Reading`

One page's state as served_state.page.read_served_page composes it from one transaction, before the serving route adds its neighbors and token. Before the page has an active revision, active and browser are null.

Field	Type	Required	Description
`layer`	object	yes	The identity of the layer the shown revision was read under, or the vendored layer's before a revision exists (`layer-registry.md`). A layer another Leaf at this protocol vendored may carry more.
`layer.generation`	string	yes
`layer.fingerprint`	string	yes
`layer.server`	string
`layer.packages`	array of string
`layer.producer`	Provenance
`now`	string	yes	The server clock used to calibrate browser timestamps and relative ages; a laptop an hour out would otherwise date new comments an hour out too. An edge host refreshes this and `taken` together at delivery; captured event timestamps and already-folded activity keep their original dates.
`working_grace_ms`	integer	yes	How long working may go unheard before it reads as quiet, measured on the `now` clock. `activity` is already folded; a package dating a worker's own reports asks `quietSince`, which reads this rather than a copy.
`taken`	number	yes	The moment this answer was taken, for a tab holding two. Answers cross (two sockets, one held by a proxy or a test while a later one lands, a POST's answer beside a read), and the log's sequence orders everything in a state but the reading and its data, which are hashes with no order of their own. Live answers are stamped inside their page transaction; an edge host dates a fresh read of its stored publication at delivery. The wall clock rather than a counter, which would start over with the server and make a tab open across that restart refuse every answer until the count caught up.
`active`	Revision or null	yes	The revision the live root serves (`files.document_descriptor`), or null before the first.
`versions`	array of object	yes	Each public version with its revision and address (`files.version_descriptors`).
`versions[].version`	integer	yes	The public version number, `vN`'s `N`.
`versions[].revision`	integer	yes	The immutable revision the version stamped.
`versions[].url`	string	yes	The version's address.
`revision_labels`	map of string	yes	Each revision's public name, `vN` or a draft's, by revision number (`files.revision_label`).
`source_error`	string or null	yes	Why activating the page's authored source failed, or null.
`data`	object	yes	The page's data sources as a browser reads them (`data.browser_data_from`). An answer to a tab that names this `version` in `Leaf-Data-Version` leaves out `sources`, which the tab restores from the reading it holds.
`data.version`	string	yes
`data.sources`	map of object
`data.sources.*.contract`	string	yes
`data.sources.*.revision`	string
`data.sources.*.run`	string
`data.sources.*.updated`	string
`data.sources.*.value`	any
`data.sources.*.error`	string
`files`	map of string	yes	Each bound file's stamp, by binding, which moves when the file may have: an editor reads its file only when this stamp does.
`status`	object	yes	The agent's declaration, the newest `status` event (`activity.declaration`), as `presence.presence_with_activity` reads it; that module owns the presence fields below.
`status.state`	string	yes	`waiting` on the user or `idle`, done with the page; `waiting` before the agent declares anything.
`status.detail`	string	yes	The declaration's words; empty before the first declaration and where a start reopened an idle page.
`status.ts`	string		When the agent declared it, or when a start reopened an idle page; absent before the first declaration.
`listening`	boolean	yes	Whether a wait lease on the page is held: the active claimant session's, or the page's own where no session claims it.
`session_alive`	boolean or null	yes	Whether the claimant's lifetime stands, or null where nothing claimed the page.
`live_turn`	object or null	yes	What the claimant's harness says of its turn now (`Harness.live_turn`), or null.
`live_turn` when `state` is `"busy"` \| `"waiting"` \| `"idle"`.
`live_turn.state`	`"busy"` \| `"waiting"` \| `"idle"`	yes
`live_turn.since`	string	yes
`cursor`	integer	yes	The acknowledgement cursor, the greatest `through` a `receipt` in the log holds: the updates through it reached their durable consumer.
`pending`	integer	yes	How many of the user's events past the cursor the agent hasn't taken in.
`agent`	string	yes	The name the page calls its agent (`presence.page_agent`).
`claim_session`	string or null	yes	The claimant session, or null.
`claim_turn`	string or null	yes	The claimant's current turn, which an opened delivery names, or null.
`turn_closed`	string or null	yes	When the claimant's current turn closed, or null while it is open or nothing claims the page.
`turn_opened`	string or null	yes	When that turn opened or was last renewed, or null where nothing claims the page.
`turn_takes_input`	boolean	yes	Whether an open turn of the claimant's takes new input before it ends (`Harness.turn_takes_input`).
`session_cwd`	string or null	yes	Where the claimant was working when it claimed the page, or null for a page nothing claimed.
`activity`	Activity	yes	Where the agent's work on the whole page stands (`activity.py`), which the Leaf panel reads.
`workflows`	array of Workflow	yes	The page's workflows, strongest first (`served_state.work.served_workflows`).
`browser`	Browser or null	yes	The browser's reading of the shown and active revisions (`served_state.browser.browser_state`), or null before the first revision.
`events`	array of Event	yes	The log, as logged: a message's text is Markdown the page's vendored runtime renders, and its markup the fragment the CLI gate validated. The wire adds nothing, so the only vocabulary a page's frozen layer has to keep speaking is the log's own, which `$events` already stamps.
`preview`	object		The identity a developer preview shows in browser chrome, as `leaf-dev preview` wrote it (`server.preview_metadata`); absent on a page that is not a preview.
`preview.example`	string	yes	The name of the source file the preview serves, without its extension.
`preview.checkout`	string	yes	The checkout whose Leaf serves it.
`preview.interaction`	`"user"` \| `"author"`	yes	`user` for a `--user` preview, whose presses reach the session that claimed it; `author` for a plain one.
`preview.started`	string	yes	When the preview started.
`preview.input`	object	yes	The fixture publication the preview's watcher last applied.
`preview.input.source`	string	yes
`preview.input.authored`	string	yes
`publication`	object		On leaf.page, who answers a published page and where to install Leaf; absent elsewhere.
`publication.agent`	string	yes	Who answers the published page.
`publication.install_url`	string	yes	Where to install Leaf.
`publication.kind`	string	yes

`Event`

One logged event, exactly as $events declares its kind.

Type: event.

`EventReference`

The admitted gesture an answer or ending came from (obligations.event_reference).

Field	Type	Required
`id`	string	yes
`kind`	string	yes
`seq`	integer	yes
`ts`	string	yes
`author`	string	yes

`Provenance`

Where a Leaf payload came from (layer.payload_provenance): its commit and dirty bit, and its age as committed or installed.

Field	Type	Required	Description
`path`	string
`commit`	string
`dirty`	boolean
`committed`	string
`installed`	string

`Revision`

One revision's live address, public stamp or draft label, and captured identity (files.document_descriptor).

Field	Type	Required	Description
`revision`	integer	yes	The revision's number.
`version`	integer or null	yes	The public version that stamped it, or null for a draft.
`url`	string	yes	The revision's address.
`label`	string	yes	Its public name, `vN` or a draft's (`files.revision_label`).
`executable`	string	yes	The capture's executable identity, independent of public stamps, which a client compares with its delivered document.
`activated_at`	string	yes	When it went live.

`Subject`

What a workflow or to-do stands on.

Field	Type	Required
when `kind` is `"thread"` \| `"widget"` \| `"element"`.
`kind`	`"thread"` \| `"widget"` \| `"element"`	yes
`id`	string	yes
when `kind` is `"page"`.
`kind`	`"page"`	yes

`Activity`

The page's one reading of agent activity (activity.canonical_activity), without its workflows and to-dos, which the state serves on their own.

Field	Type	Required	Description
`kind`	`"away"` \| `"closed"` \| `"unheld"` \| `"working"` \| `"stalled"` \| `"listening"`	yes
`held`	boolean	yes
`dropped`	boolean	yes
`detail`	string	yes
`detail_source`	object or null	yes
`detail_source.event_id`	string	yes
`detail_source.item`	string	yes
`observed`	string	yes
`observed_kind`	WorkKind or null	yes
`awaiting`	boolean	yes
`counts`	object	yes
`counts.active`	integer	yes
`counts.handling`	integer	yes
`counts.handling_comments`	integer	yes
`counts.queued`	integer	yes
`counts.picked_up`	integer	yes
`counts.pending`	integer	yes
`counts.overdue`	integer	yes
`counts.total`	integer	yes
`ts`	string or null	yes
`next_transition_at`	string or null	yes
`obligations`	array of string	yes	The ids of the update records whose next actor is the agent: the answers it owes (`activity.canonical_activity`).

`WorkKind`

The step a harness observed the agent taking (activity.WORK_KINDS, read from here): working, thinking, using a tool, waiting on the user in its own window for an approval, an answer or a dialog it does not name (the awaiting_ kinds), or replying. The browser words each one (runtime/activity-words.js).

`ReplyEvidence`

A provisional reply's settlement evidence, without its text (activity._reply_evidence).

Field	Type	Required
`state`	string	yes
`turn`	string	yes
`settles`	boolean	yes
`attempt`	string	yes

`Workflow`

One update the user handed over that has not settled (workflows.py).

Field	Type	Required	Description
`id`	string	yes
`input`	string	yes
`message`	string or null	yes	The message a thread input is said in, which shows its delivery: its own, or for a revision the message it rewrote.
`seq`	integer	yes
`revision`	integer or null	yes
`subject`	Subject	yes
`coordinate`	array of string	yes
`obligation`	string or null	yes	The id of the obligation record this update serves (`workflows.handed_over`): its own, or for an older input in a run of turns the newest's; null for an update that owes nothing.
`stage`	Stage	yes
`ts`	string or null	yes
`delivery_seq`	integer or null	yes
`delivery_session`	string or null	yes
`delivery_turn`	string or null	yes
`detail`	string or null	yes
`detail_seq`	integer or null	yes	The log position of the start whose line `detail` is, which places the thread's working message among its messages.
`agent`	string or null	yes
`session`	string or null	yes
`activity`	array of object	yes
`activity[].kind`	`"working"` \| `"replying"` \| `"response"`	yes
`activity[].detail`	string or null	yes
`activity[].ts`	string or null	yes
`activity[].session`	string or null	yes
`activity[].turn`	string or null	yes
`condition`	object or null	yes
`condition` when `kind` is `"ended"` \| `"interrupted"` \| `"stale"` \| `"failed"` and `operation` is `"delivery"` \| `"work"` \| `"response"`.
`condition.kind`	`"ended"` \| `"interrupted"` \| `"stale"` \| `"failed"`	yes
`condition.operation`	`"delivery"` \| `"work"` \| `"response"`	yes
`response`	object or ReplyEvidence or null	yes
`response` when `state` is `"failed"`. The failure record that answered the update.
`response.id`	string	yes
`response.attempt`	string or null	yes
`response.state`	`"failed"`	yes
`started_by`	array of object	yes	The starts that take the update in hand, which the Stop hook reads.
`started_by[].item`	string	yes
`started_by[].session`	string or null	yes
`started_by[].turn`	string or null	yes
`started_by[].seq`	integer	yes
`at_work`	boolean	yes	Whether the agent is at work on it: at `working` or `replying`, whatever its condition.
`thread`	string or null	yes	The thread it stands in: a thread input's own, a widget frozen into a message's thread, or null for a page widget.

`Start`

The start running on a to-do (todos.running).

Field	Type	Required
`id`	string	yes
`item`	string	yes
`text`	string	yes
`seq`	integer	yes
`ts`	string	yes
`agent`	string or null	yes
`session`	string or null	yes
`turn`	string or null	yes

`Todo`

One to-do, open or ended (work_reading.WorkReading.page_todos). The start that holds an open one is running; one gone quiet holds nothing.

Field	Type	Required	Description
`id`	string	yes
`owner`	`"agent"` \| `"user"`	yes
`subject`	Subject	yes
`title`	string	yes
`state`	`"open"` \| `"done"` \| `"failed"` \| `"dropped"`	yes
`seq`	integer	yes
`ts`	string	yes
`agent`	string or null	yes
`session`	string or null	yes
`revision`	integer or null	yes
`running`	Start or null	yes
`outcome`	object or null	yes	How it ended: the `todo_end` in force, or the stamped version that completed it.
`outcome.id`	string	yes
`outcome.seq`	integer	yes
`outcome.ts`	string	yes
`outcome.detail`	string or null	yes
`outcome.author`	string	yes
`outcome.agent`	string or null	yes
`outcome.session`	string or null	yes
`thread`	string or null	yes

`PlanStep`

One step of the plan (plans.plan_reading): plain, or naming a to-do or obligation whose title, owner and state it shows; done of total counts its children, dropped ones left out.

Field	Type	Required
`title`	string or null	yes
`state`	`"open"` \| `"working"` \| `"done"` \| `"failed"` \| `"dropped"`	yes
`owner`	`"agent"` \| `"user"`	yes
`item`	object or null	yes
`item` when `kind` is `"todo"` \| `"obligation"`.
`item.kind`	`"todo"` \| `"obligation"`	yes
`item.id`	string	yes
`running`	Start or null	yes
`since`	string or null	yes
`steps`	array of PlanStep	yes
`done`	integer	yes
`total`	integer	yes

`HistoryRow`

One logged event as a history feed reads it (history.history). Which of the optional fields a row carries follows its kind.

Field	Type	Required
`id`	string	yes
`ts`	string	yes
`kind`	`"comment"` \| `"reply"` \| `"edit"` \| `"resolve"` \| `"unresolve"` \| `"action"` \| `"report"` \| `"note"` \| `"done"`	yes
`author`	string	yes
`agent`	string or null	yes
`undone`	boolean	yes
`thread`	object or null
`thread.id`	string	yes
`anchor`	Anchor
`about`	`comment`'s `about` or null
`token`	string
`holds`	`comment`'s `holds` or null
`drawing`	boolean
`excerpt`	string or null
`widget`	string
`gesture`	object
`gesture.form`	`"choice"` \| `"move"` \| `"edit"` \| `"add"` \| `"verb"`	yes
`gesture.chosen`	array of string
`gesture.unit`	string
`gesture.to`	string
`gesture.words`	string
`gesture.verb`	string
`value`	any
`version`	integer

`Browser`

What the browser reads of the page's revisions and the work on them (served_state.browser.browser_state).

Field	Type	Required	Description
`basis`	object	yes	The log position the reading was taken through.
`basis.through_seq`	integer	yes
`history`	array of HistoryRow		The newest rows, newest first, sent only to a page holding a widget that declares `x-history`.
`views`	map of View	yes	Each projected revision's view, by revision number.
`approval_history`	array of `done`	yes	Approvals in force across every stamp, for Threads' event timeline. Current-version approval state lives only in its obligation.
`todos`	array of Todo	yes	Every to-do, open and ended, the one record the browser reads each from.
`plan`	object or null	yes	The agent's outline of the work, its steps naming to-dos and obligations by id (`plans.plan_reading`), or null.
`plan.id`	string	yes
`plan.ts`	string	yes
`plan.agent`	string or null	yes
`plan.session`	string or null	yes
`plan.steps`	array of PlanStep	yes
`receipts`	array of Event	yes	Every logged event a browser attempt wrote, which carries its `attempt`.
`thread_memberships`	map of array of string	yes	Every thread whose history each logged event changes (`thread_context.thread_memberships`), which the browser reads for the gesture an unsent undo takes back or an unsent action replaces.
`version_notes`	map of string	yes	Each version's note, by version.

`View`

One revision's view: its document, the frozen threads as its registry reads them, and the work and undo readings drawn on it.

Field	Type	Required	Description
`basis`	object	yes
`basis.revision`	integer	yes
`basis.through_seq`	integer	yes
`document`	object	yes
`document.revision`	integer	yes
`document.projection`	Projection	yes
`thread`	object	yes	The frozen threads as this revision reads them: its registry classifies their widgets' decisions, and so the obligations and attention those give.
`thread.projection`	Projection	yes
`thread.threads`	array of Thread	yes
`obligations`	array of Obligation	yes	Every obligation record of this view, its document's then its frozen threads', answered and withdrawn ones included. The one copy of each: a list row and `approval_blocking` name an obligation by `id`.
`reports`	array of object	yes	The view's report feed, in log order (`projection.canonical_reports`).
`reports[].id`	string	yes
`reports[].target`	object	yes
`reports[].target.kind`	`"widget"`	yes
`reports[].target.id`	string	yes
`reports[].source`	`"report"`	yes
`reports[].action`	string	yes
`reports[].detail`	object	yes
`reports[].text`	string or null	yes
`reports[].ts`	string	yes
`reports[].revision`	integer	yes
`reports[].seq`	integer	yes
`reports[].agent`	string or null	yes
`reports[].session`	string or null	yes
`reports[].disposition`	`"effective"` \| `"outranked"` \| `"settled"`	yes
`undo`	array of object	yes	The user's gestures this document can take back, newest first (`served_state.document.browser_undo_candidates`); `newest` marks the user's newest gesture.
`undo[].event`	Event	yes
`undo[].coordinate`	array of string
`undo[].newest`	`true`
`coverage`	array of object	yes	Each widget event and undo with the coordinate it is classified at in this view, or null.
`coverage[].event`	Event	yes
`coverage[].coordinate`	array of string or null	yes
`published_at`	string or null	yes
`queues`	object	yes	On me and On <agent> and what each has finished (`served_state.queues`).
`queues.on_user`	array of QueueRow	yes
`queues.on_agent`	array of QueueRow	yes
`queues.done`	array of DoneRow	yes
`approval_blocking`	array of string	yes	The obligations approving this version waits on (`obligations.approval_blocking`).

`Projection`

One declared state projection (served_state.wire.browser_projection).

Field	Type	Required	Description
`entries`	array of object	yes
`entries[].event`	`action` or `report`	yes
`entries[].coordinate`	[string, string, string]	yes
`entries[].spec`	x-state verb	yes	The operation the event was admitted under, by the immutable registry of the revision that interpreted it, which may differ from the active document's. Browser folds read this rather than reinterpreting history through whichever registry the current DOM selected.
`entries[].value`	any	yes
`entries[].scope`	`"document"` \| `"thread"`	yes
`entries[].restated`	array of string	yes
`entries[].absorbed`	boolean	yes	Whether a later revision absorbed this move, whose markup places the unit.
`entries[].stands`	boolean	yes	Whether nothing has taken this action back or retracted it, so it stands at its coordinate once every newer one is withdrawn.
`actions`	array of string	yes
`reports`	array of string	yes
`desired`	array of string	yes

`Obligation`

One request and its contained answer (obligations.py, which owns the statuses): what a widget or a version's sign-off waits on the user for, or what an update the user handed over is owed (workflows.handed_over). The source owns the canonical value; identity includes its kind so authored ids and message ids cannot collide.

Field	Type	Required	Description
`id`	string	yes
`source`	object	yes
`source` when `kind` is `"widget"`.
`source.kind`	`"widget"`	yes
`source.id`	string	yes
`source.tag`	string	yes
`source` when `kind` is `"approval"`.
`source.kind`	`"approval"`	yes
`source.version`	integer	yes
`source` when `kind` is `"update"`. An update the user handed over: `id` is the input's event, `subject` the thread or widget it stands on.
`source.kind`	`"update"`	yes
`source.id`	string	yes
`source.subject`	Subject	yes
`thread`	string or null	yes
`message`	string or null	yes
`prompt`	object	yes
`prompt.text`	string or null	yes
`prompt.target`	string or null	yes	Where the user goes to answer: the id of a widget's prompt context, or of the thread or widget an update stands on; null for an approval, which asks about the version as a whole.
`answer`	object or null	yes
`answer.value`	any	yes
`answer.event`	EventReference or null	yes
`status`	`"open"` \| `"answered"` \| `"answered_elsewhere"` \| `"withdrawn"`	yes
`end`	object or null	yes	The agent's `leaf task end` that retired a question answered in words: where the answer is, or why the obligation no longer applies.
`end.detail`	string or null	yes
`end.event`	object	yes	The ending's reference, which names no kind: every ending is a `todo_end`.
`end.event.id`	string	yes
`end.event.seq`	integer	yes
`end.event.ts`	string	yes
`end.event.author`	string	yes
`next_actor`	`"user"` \| `"agent"` \| `null`	yes

`QueueRow`

One row of On me or On <agent> (served_state.queues); owner names its list and live whether the agent has it in hand now. A record's row names its obligation by id, whose record is the view's obligations entry, and a to-do row names its to-do by id, whose record is the page's todos entry.

Type: ObligationRow or TodoRow.

`ObligationRow`

An obligation record's row in On me or On <agent> (served_state.queues).

Field	Type	Required	Description
`kind`	`"widget"` \| `"approval"` \| `"update"`	yes	The record's `source.kind`.
`id`	string	yes	The obligation, whose record is the view's `obligations` entry.
`owner`	`"user"` \| `"agent"`	yes	The list the row stands on.
`subject`	Subject	yes
`thread`	string or null	yes	The thread it stands in, or null.
`live`	boolean	yes	Whether the agent has it in hand now: an update it is at work on whose work has not gone quiet or stopped.

`TodoRow`

A to-do's row in On me or On <agent> (served_state.queues).

Field	Type	Required	Description
`kind`	`"todo"`	yes
`id`	string	yes	The to-do, whose record is the page's `todos` entry.
`owner`	`"agent"` \| `"user"`	yes	The list the row stands on.
`subject`	Subject	yes
`thread`	string or null	yes	The thread it stands in, or null.
`live`	boolean	yes	Whether a start holds the to-do now.

`DoneRow`

A row that left its list, in the Done of the list owner names: how it ended (state), when (ended, null going last), and the outcome's detail.

Type: ObligationRow or TodoRow.

Field	Type	Required
`state`	`"done"` \| `"failed"` \| `"dropped"`	yes
`ended`	string or null	yes
`detail`	string or null	yes

`Anchor`

Where a thread stands on the page, as a comment, reply or reanchor names it, or null.

Type: comment's anchor or reply's anchor or reanchor's anchor.

`Message`

A message as a served thread holds it.

Type: comment or reply or object.

Field	Type	Required	Description
variant 1. A logged comment or reply, with its current content version (`read_state.content_version`), which the browser marks read once its words have been shown. An agent's message carries the name it is shown under as `agent` (`schema.agent_name`). An input's first answer carries `key`, the name a provisional reply and the answer that retires it share.
`agent`	string
`key`	string
`content_version`	string	yes
`edited`	object		The user's latest rewrite, and the words it replaced.
`edited.id`	string	yes
`edited.seq`	integer	yes
`edited.ts`	string	yes
`edited.was`	string	yes
when `provisional` is `true` and `kind` is `"reply"` and `addressable` is `false` and `author` is `"agent"`. A provisional reply streaming under a delivery attempt, which joins its thread once it has words (`served_state.thread.browser_thread`).
`id`	string	yes
`content_version`	string	yes
`attempt`	string	yes
`key`	string	yes
`provisional`	`true`	yes
`kind`	`"reply"`	yes
`addressable`	`false`	yes
`author`	`"agent"`	yes
`agent`	string or null	yes
`parent`	string	yes
`text`	string	yes
`ts`	string	yes
`pending`	boolean	yes

`ContentVersion`

One version of an agent message's content: the message, and its latest edit's id or else its own (read_state.content_version).

Field	Type	Required	Description
`message`	string	yes	The message's event id.
`version`	string	yes	The content version's id, which a `read` event names.

`Attention`

Whose turn a thread is (served_state.browser._thread_attention), read from the open obligation records in it: a widget's or an update's handed back on the user, else one on the agent, whose strongest serving workflow it names; or null for nobody's.

Type: object or null.

Field	Type	Required	Description
when `kind` is `"needs_user"` and `reason` is `"widget"` \| `"resend"`.
`kind`	`"needs_user"`	yes
`reason`	`"widget"` \| `"resend"`	yes
`workflow`	string or null	yes
when `kind` is `"waiting"` and `reason` is `"uncertain"` \| `"workflow"`.
`kind`	`"waiting"`	yes
`reason`	`"uncertain"` \| `"workflow"`	yes
`workflow`	string	yes
when `kind` is `"waiting"` and `reason` is `"todo"`.
`kind`	`"waiting"`	yes
`reason`	`"todo"`	yes
`workflow`	null	yes
`todo`	string	yes	The id of the to-do the thread waits on, whose record is the page's `todos` entry.

`Thread`

One thread, keyed by the comment that opened it (events.build_threads), as served_state.thread.browser_thread serves it.

Field	Type	Required	Description
`id`	string	yes
`root`	Message	yes
`title`	string or null	yes
`anchor`	Anchor	yes
`detached_from`	Anchor	yes
`rewritten_from`	Anchor	yes
`msgs`	array of Message	yes
`revisions`	array of `edit`	yes	The user's edits in log order, each with `was`, the words it replaced.
`revisions[].was`	string	yes
`resolved`	`resolve` or `action` or null	yes	What closed the thread, an agent's named by `agent` (`schema.agent_name`), or null while it is open.
`resolved.agent`	string
`bare_reaction`	boolean	yes
`seat`	string or null	yes	The widget whose thread seat the root stands in (`events.seat_root`), or null.
`summaries`	array of object	yes	The thread's current summaries (`events.active_summaries`); `protected` lists the covered messages a summary must not hide.
`summaries[].id`	string	yes
`summaries[].seq`	integer	yes
`summaries[].from`	string	yes
`summaries[].through`	string	yes
`summaries[].covers`	array of string	yes
`summaries[].text`	string	yes
`summaries[].label`	string	yes
`summaries[].trigger`	string
`summaries[].protected`	array of string	yes
`unread`	array of ContentVersion	yes	The content versions the user hasn't read (`read_state.unread_content`).
`attention`	Attention	yes

`Stage`

How far an update has reached the agent; answered is only ever a retained failed response.

`ViewAnswer`

The answer GET /api/view gives (served_state.service.PageStateService.page_browser_view): one revision's browser reading at an exact log boundary, which version comparison folds.

Field	Type	Required	Description
`browser`	Browser	yes

`EventAnswer`

The answer POST /api/event gives once its gates pass (event_endpoint).

Field	Type	Required	Description
when `ok` is `true`. Accepted, with the page's state, which holds the event's receipt.
`ok`	`true`	yes
`state`	served state	yes
when `ok` is `false` and `final` is `true`. Refused, and final: nothing was appended. `error` is the words the tab shows its user. A refusal admission made carries `state`, which restores the tab from current truth; a gate's refusal (`http.PageEndpoint._refuse`) carries none.
`ok`	`false`	yes
`final`	`true`	yes
`error`	string	yes
`findings`	array of Finding	yes
`attempt`	any		The posted `attempt`, echoed as it came.
`state`	served state
when `ok` is `false`. A fault that may have landed either side of the append, so the next identical request finds out (`event_endpoint.event_fault`).
`ok`	`false`	yes
`error`	string	yes
`attempt`	any		The posted `attempt`, echoed as it came.

`Finding`

What a refusal refused on (findings.Finding.json, less its words). The browser shows the refusal's error instead.

Field	Type	Required
`code`	string	yes
`severity`	`"error"` \| `"advice"`	yes
`at`	string
`values`	object

`SampleAnswer`

The answer POST /api/samples gives: the new live sample's address, and its interaction page (http.PageEndpoint._create_sample).

Field	Type	Required	Description
`url`	string	yes
`page`	string	yes

`MediaAnswer`

The answer POST /api/media gives: the stored image's page-relative path (media.store_uploaded_media).

Field	Type	Required	Description
`path`	string	yes

`FileSnapshot`

One bound file as GET and a successful POST /api/files/<binding> answer it (file_bindings): its name, its text with LF line endings, and the revision a save names.

Field	Type	Required
`label`	string	yes
`text`	string	yes
`revision`	string	yes

`StaleFile`

A save refused because the file changed since the revision it named, with the file as it is now.

Field	Type	Required	Description
`error`	string	yes
`current`	FileSnapshot	yes

`Refusal`

Any route's refusal of a request (http.PageEndpoint._refuse): the words the page shows.

Field	Type	Required	Description
`error`	string	yes

`LayerAnswer`

A write held because the tab speaks another layer (http.PageEndpoint._layer_gate): the generation it should speak, which the Leaf-Layer header also carries, so the tab reloads without reading this.

Field	Type	Required	Description
`layer`	string	yes

Events

Each line of a page's events.jsonl is one event, admitted whole against its kind's schema. The first table lists the fields every kind shares; each kind's table lists the rest.

Every event

Field	Type	Required
`attention`	boolean	yes
`id`	string	yes
`ts`	string	yes
`seq`	integer	yes

`comment`

What it means. The browser may post it to POST /api/event. A message kind.

Field	Type	Required
`author`	string	yes
`kind`	`"comment"`	yes
`revision`	integer	yes
`text`	string
`token`	string
`anchor`	object
`anchor.section`	string or null
`anchor.quote`	string
`anchor.datum`	string
`anchor.source`	string
`anchor.source_revision`	string
`anchor.identity`	string
`anchor.visual`	string
`anchor.prefix`	string
`anchor.suffix`	string
`anchor.detached`	`true`
`anchor.part`	string
`anchor` one of: requires `section`; requires `quote`; requires `datum`.
`drawing`	object
`drawing.strokes`	array of array of [number, number]	yes
`drawing.box`	[number, number]	yes
`drawing.frame`	object
`drawing.frame.root`	string	yes
`drawing.frame.path`	array of object	yes
`drawing.frame.path[].tag`	string	yes
`drawing.frame.path[].index`	integer	yes
`drawing.frame.path[].siblings`	integer	yes
`drawing.frame.path[].shadow`	boolean
`drawing.says`	string
`drawing.viewport`	[number, number]	yes
`drawing.scheme`	`"light"` \| `"dark"`	yes
`suggestion`	boolean
`about`	`"design"`
`title`	string
`agent`	string
`session`	string
`markup`	string
`attempt`	string
`holds`	string
one of: requires `text`; requires `token`; requires `drawing` and forbids `text`.

`reply`

What it means. The browser may post it to POST /api/event. A message kind.

Field	Type	Required
`author`	string	yes
`kind`	`"reply"`	yes
`parent`	string	yes
`revision`	integer
`publication`	string
`text`	string
`token`	string
`anchor`	object or null
`anchor.section`	string or null
`anchor.quote`	string
`anchor.datum`	string
`anchor.source`	string
`anchor.source_revision`	string
`anchor.identity`	string
`anchor.visual`	string
`anchor.prefix`	string
`anchor.suffix`	string
`anchor.detached`	`true`
`anchor.part`	string
`anchor` one of: requires `section`; requires `quote`; requires `datum`.
`title`	string
`agent`	string
`session`	string
`markup`	string
`todo`	string
`ephemeral`	`true`
`start`	object
`start.item`	string	yes
`start.turn`	string
`failure`	string
`responds`	string
`attempt`	string
one of: requires `text`; requires `token`.

`edit`

What it means. The browser may post it to POST /api/event.

Field	Type	Required
`author`	`"agent"` \| `"user"`	yes
`kind`	`"edit"`	yes
`attempt`	string
`message`	string	yes
`text`	string	yes
`base`	string
`agent`	string
`session`	string
when `author` is `"agent"`, requires `agent`, `session`.
when `author` is `"user"`, forbids `agent`, `session`.

`summary`

What it means.

Field	Type	Required
`author`	`"agent"`	yes
`kind`	`"summary"`	yes
`thread`	string	yes
`from`	string	yes
`through`	string	yes
`text`	string	yes
`label`	string
`agent`	string	yes
`session`	string	yes

`read`

What it means. The browser may post it to POST /api/event. A bookkeeping kind.

Field	Type	Required
`author`	`"user"`	yes
`kind`	`"read"`	yes
`messages`	array of object	yes
`messages[].message`	string	yes
`messages[].version`	string	yes
`attempt`	string

`thread_title`

What it means.

Field	Type	Required
`author`	`"agent"`	yes
`kind`	`"thread_title"`	yes
`thread`	string	yes
`title`	string	yes
`agent`	string	yes
`session`	string	yes

`todo`

What it means.

Field	Type	Required
`author`	`"agent"`	yes
`kind`	`"todo"`	yes
`owner`	`"agent"` \| `"user"`	yes
`subject`	object	yes
`subject` when `kind` is `"widget"` \| `"element"`.
`subject.kind`	`"widget"` \| `"element"`	yes
`subject.id`	string	yes
`subject` when `kind` is `"page"`.
`subject.kind`	`"page"`	yes
`revision`	integer
`title`	string	yes
`agent`	string
`session`	string

`start`

What it means.

Field	Type	Required
`author`	`"agent"`	yes
`kind`	`"start"`	yes
`item`	string	yes
`text`	string	yes
`turn`	string
`agent`	string
`session`	string

`status`

What it means.

Field	Type	Required
`author`	`"agent"`	yes
`kind`	`"status"`	yes
`state`	`"waiting"` \| `"idle"`	yes
`detail`	string	yes
`agent`	string
`session`	string

`plan`

What it means.

Field	Type	Required
`author`	`"agent"`	yes
`kind`	`"plan"`	yes
`steps`	array of object	yes
`steps[]` when `state` is `"open"` \| `"working"` \| `"done"` \| `"dropped"`.
`steps[].depth`	integer	yes
`steps[].title`	string	yes
`steps[].state`	`"open"` \| `"working"` \| `"done"` \| `"dropped"`	yes
`steps[]` variant 2.
`steps[].depth`	integer	yes
`steps[].item`	string	yes
`agent`	string
`session`	string

`todo_end`

What it means. The browser may post it to POST /api/event. A undoable kind.

Field	Type	Required
`author`	`"agent"` \| `"user"`	yes
`kind`	`"todo_end"`	yes
`todo`	string	yes
`outcome`	`"done"` \| `"failed"` \| `"dropped"`	yes
`attempt`	string
`detail`	string
`agent`	string
`session`	string

`reanchor`

What it means. A bookkeeping kind.

Field	Type	Required
`author`	`"page"`	yes
`publication`	string
`kind`	`"reanchor"`	yes
`thread`	string	yes
`revision`	integer	yes
`anchor`	object or null	yes
`anchor.section`	string	yes

`resolve`

What it means. The browser may post it to POST /api/event. A undoable kind.

Field	Type	Required
`author`	string	yes
`kind`	`"resolve"`	yes
`parent`	string	yes
`agent`	string
`session`	string
`attempt`	string

`unresolve`

What it means. The browser may post it to POST /api/event. A undoable kind.

Field	Type	Required
`author`	string	yes
`kind`	`"unresolve"`	yes
`parent`	string	yes
`attempt`	string

`done`

What it means. The browser may post it to POST /api/event. A undoable kind.

Field	Type	Required
`author`	string	yes
`kind`	`"done"`	yes
`version`	integer	yes
`attempt`	string

`action`

What it means. The browser may post it to POST /api/event. A undoable kind. Carries an x-state verb the user writes.

Field	Type	Required
`author`	string	yes
`kind`	`"action"`	yes
`widget`	string	yes
`action`	string	yes
`detail`	object	yes
`meaning`	object	yes
`meaning.scope`	`"page"` \| `"thread"`	yes
`meaning.unit`	string	yes
`meaning.depends`	array of string	yes
`meaning.answer`	string or null
`meaning.creates`	string
`meaning.among`	array of string
`meaning.state`	object
`meaning.state.origin`	string	yes
`meaning.state.unit`	string	yes
`meaning.state.record`	object or null	yes
`meaning.state.creates`	object or null	yes
`meaning.state.detail`	object or boolean	yes
`revision`	integer	yes
`attempt`	string

`pickup`

What it means.

Field	Type	Required
`author`	`"page"`	yes
`kind`	`"pickup"`	yes
`events`	array of string	yes
`phase`	`"queued"` \| `"opened"` \| `"failed"`	yes
`session`	string or null	yes
`turn`	string or null	yes
`failure`	string
`refs`	map of object
`refs.*.ref`	string	yes
`refs.*.claim`	string or null	yes
when `phase` is `"failed"`, requires `failure`.
otherwise, forbids `failure`.

`receipt`

What it means.

Field	Type	Required
`author`	`"page"`	yes
`kind`	`"receipt"`	yes
`through`	integer	yes

`undo`

What it means. The browser may post it to POST /api/event.

Field	Type	Required
`author`	string	yes
`kind`	`"undo"`	yes
`undoes`	string	yes
`attempt`	string

`report`

What it means. Carries an x-state verb the agent writes.

Field	Type	Required
`author`	string	yes
`kind`	`"report"`	yes
`widget`	string	yes
`action`	string	yes
`detail`	object	yes
`meaning`	object	yes
`meaning.scope`	`"page"` \| `"thread"`	yes
`meaning.unit`	string	yes
`meaning.depends`	array of string	yes
`meaning.state`	object
`meaning.state.origin`	string	yes
`meaning.state.unit`	string	yes
`meaning.state.record`	object or null	yes
`meaning.state.creates`	object or null	yes
`meaning.state.detail`	object or boolean	yes
`revision`	integer	yes
`agent`	string
`session`	string

`note`

What it means.

Field	Type	Required
`author`	string	yes
`kind`	`"note"`	yes
`version`	integer	yes
`revision`	integer	yes
`publication`	string
`text`	string	yes
`restated`	array of string
`settles`	array of object
`settles[].kind`	`"report"` \| `"todo"`	yes
`settles[].id`	string	yes
`agent`	string
`session`	string

`error`

What it means. The browser may post it to POST /api/event.

Field	Type	Required
`author`	string	yes
`kind`	`"error"`	yes
`revision`	integer
`text`	string	yes

Records

Leaf keeps these JSON files outside a page's log and document, in the page directory, the machine's state home, or the browser's storage. Each carries a format naming the protocol at which its shape last changed. delivery is the envelope an agent reads with leaf delivery read.

`access`

The key every page this machine serves is read with (host_key), in the state home's access.json.

Stored with format leaf-access/13.

Field	Type	Required	Description
`token`	string	yes

`bridge`

Where an installed tree's running bridge listens, in the state home's bridge/<key>.json.

Stored with format leaf-bridge/13.

Field	Type	Required	Description
`port`	integer	yes	The loopback port it listens on.
`token`	string	yes	The token a request carries.
`pid`	integer	yes	The bridge's process.

`bridge-session`

A session the bridge serves, in the state home's bridge/<key>.sessions/<digest>.json, with the fields of the lifetime it lives by (Harness.lifetime) beside its id.

Stored with format leaf-bridge-session/13.

Field	Type	Required	Description
`id`	string	yes	The harness's session id.

`claim`

The session that receives a page's updates, in the state home's claims/<page key>.json (claim_path).

Stored with format leaf-claim/13.

Field	Type	Required	Description
`page`	string	yes	The page directory.
`ts`	string (date-time)	yes	When the claim was published.
`id`	string	yes	The claimant session (`state.SESSION`).
`generation`	string	yes	The generation of the session this claim names.
`acquisition`	string	yes	This publication's own identity (`same_claim`).
`harness`	string	yes	The claimant's `Harness.name`.
`agent`	string	yes	The name the claimant shows.
`cwd`	string	yes	The claimant's working directory.
`messaged_ending`	string		The turn ending after which input last messaged the session (`note_messaged`).

`codex-adapter`

A Codex task's running delivery adapter, written into the lease it holds at the state home's sessions/<digest>.adapter. A session can select a replacement runtime while this lease remains held (_running_adapter).

Stored with format leaf-codex-adapter/13.

Field	Type	Required	Description
`app_server`	string or null	yes	The Codex App Server the adapter delivers through, or null for the task's queue.
`launcher`	string		The immutable runtime running the adapter.

`codex-delivery`

One delivery a Codex task is handing to its agent (DeliveryRecord), in the state home's sessions/<digest>.deliveries/<id>.json and, once nothing is owed on it, that directory's history/. A record at another format is ignored, and the events its page has not acknowledged are captured afresh.

Stored with format leaf-codex-delivery/14.

Field	Type	Required	Description
`state`	`"collecting"` \| `"offering"` \| `"hook"` \| `"starting"` \| `"queued"` \| `"opened"` \| `"abandoned"`	yes	How far the handoff has gone (`RECORD_VARIANTS`).
`created_at`	number	yes	When it was captured, in seconds since the epoch.
`batches`	array of object	yes	One per page.
`batches[].page`	string	yes	The page directory.
`batches[].session`	string	yes
`batches[].events`	array of object	yes	The captured events, by id and `seq`.
`batches[].events[].id`	string	yes
`batches[].events[].seq`	integer	yes
when `state` is `"collecting"`.
`batches[].through_seq`	integer	yes
`batches[].threads`	array of object	yes
`batches[].threads[].id`	string	yes
`batches[].threads[].title`	string or null	yes
`batches[].events[].kind`	string	yes
`batches[].events[].threads`	array of string	yes
`batches[].events[].answer`	object
`batches[].events[].answer.kind`	`"reply"` \| `"markup"`	yes
`batches[].events[].answer` when `kind` is `"reply"`.
`batches[].events[].answer.parent`	string	yes
`batches[].events[].answer.responds`	string	yes
`batches[].events[].answer` when `kind` is `"markup"`.
`batches[].events[].answer.action`	string	yes
when `state` is `"queued"` \| `"opened"` \| `"abandoned"`.
`pending`	array of integer	yes
when `state` is `"hook"` \| `"opened"`.
`turn`	string	yes

`data-source`

One source's publication, in the page directory's data/<source>.json, which leaf data set writes whole.

Stored with format leaf-data-source/16.

Field	Type	Required	Description
`contract`	string	yes	The data contract the value was validated against at the write.
`run`	string	yes	An opaque receipt naming the write, a rerun with the same value included.
`updated`	string (date-time)	yes	When the value was written.
`value`	any	yes	The source's complete value.

`delivery`

The immutable envelope leaf delivery read prints (references/event-batches.md), in the state home's deliveries/<id>.json: the updates that need the agent's attention, one batch per page. Registry when clauses read its events, with an event's thread digest as thread (registry.contract.event_clauses).

Stored with format leaf-delivery/15.

Field	Type	Required	Description
`id`	string	yes	The delivery id, eight hex characters, which the agent's pointer names.
`created_at`	number	yes	When it was first collected, in seconds since the epoch.
`acknowledge`	string or null	yes	How the reader confirms receipt, or null where the harness did.
`batches`	array of object	yes	One per page.
`batches[].page`	string	yes	The page directory.
`batches[].claim`	string or null	yes	The session that owned the page at capture.
`batches[].through_seq`	integer	yes	The log position the batch was captured through; a correction keeps its original batch's.
`batches[].threads`	array of object	yes	The threads the batch's events land in, each with its messages other than the batch's own (`thread_context.batch_threads`). A `when` clause reads an event's as its `thread`.
`batches[].threads[].id`	string	yes	The thread's id, which the batch's events name.
`batches[].threads[].title`	string or null	yes	Null until the thread is named.
`batches[].threads[].anchor`	`comment`'s `anchor` or `reply`'s `anchor` or `reanchor`'s `anchor`	yes	Where the thread stands on the page.
`batches[].threads[].detached_from`	`comment`'s `anchor` or `reply`'s `anchor` or `reanchor`'s `anchor`	yes	The anchor a detached thread last had, or null.
`batches[].threads[].resolved`	string or null	yes	Who closed the thread, or null while it is open.
`batches[].threads[].elided`	object	yes	How many messages and gestures a long thread leaves out of `messages` and `actions`.
`batches[].threads[].elided.messages`	integer	yes
`batches[].threads[].elided.actions`	integer	yes
`batches[].threads[].messages`	array of object	yes	Its earlier messages (`thread_context.MESSAGE_FIELDS`), less the batch's own events: the first and the latest of a long thread.
`batches[].threads[].messages[].id`	string	yes	The message's event id.
`batches[].threads[].messages[].seq`	integer	yes	Its event's place in the log.
`batches[].threads[].messages[].author`	string	yes
`batches[].threads[].messages[].agent`	string		The name an agent's message is shown under.
`batches[].threads[].messages[].text`	string
`batches[].threads[].messages[].ephemeral`	`true`		Marks a one-line progress reply, which answers nothing.
`batches[].threads[].messages[].token`	string		A reaction's word, in place of `text`.
`batches[].threads[].messages[].markup`	string		The HTML an agent's message holds, such as a widget it sent.
`batches[].threads[].messages[].drawing`	`comment`'s `drawing`
`batches[].threads[].messages[].suggestion`	boolean		True where the comment is a suggestion.
`batches[].threads[].messages[].edited`	object		The user's latest rewrite, and the words it replaced.
`batches[].threads[].messages[].edited.id`	string	yes
`batches[].threads[].messages[].edited.seq`	integer	yes
`batches[].threads[].messages[].edited.ts`	string	yes
`batches[].threads[].messages[].edited.was`	string	yes
`batches[].threads[].summaries`	array of object	yes	The thread's summaries in force (`events.active_summaries`).
`batches[].threads[].summaries[].id`	string	yes
`batches[].threads[].summaries[].seq`	integer	yes
`batches[].threads[].summaries[].from`	string	yes	The first message the summary folds.
`batches[].threads[].summaries[].through`	string	yes	The last message it folds.
`batches[].threads[].summaries[].covers`	array of string	yes	Every message it folds, in thread order.
`batches[].threads[].summaries[].text`	string	yes	The summary's Markdown, empty for a fold that only hides the messages.
`batches[].threads[].summaries[].label`	string	yes	What the folded run reads as in the thread.
`batches[].threads[].summaries[].trigger`	string		The agent reply whose arrival folded earlier progress messages.
`batches[].threads[].actions`	array of object	yes	Gestures in force on widgets sent in the thread, other than the batch's own (`thread_context.ACTION_FIELDS`).
`batches[].threads[].actions[].id`	string	yes
`batches[].threads[].actions[].seq`	integer	yes
`batches[].threads[].actions[].author`	string	yes
`batches[].threads[].actions[].widget`	string	yes
`batches[].threads[].actions[].action`	string	yes
`batches[].threads[].actions[].detail`	object	yes
`batches[].threads[].summary_hint`	object		An earlier run of messages worth summarizing, from its first message through its last.
`batches[].threads[].summary_hint.from`	string	yes
`batches[].threads[].summary_hint.through`	string	yes
`batches[].handling`	map of string	yes	Each clause's text once, by an id only this batch's events use.
`batches[].events`	array of event	yes	In log order, each the logged record less the browser's `attempt`, with what the delivery reads of it (`batch_data`, `handled`).
`batches[].events[].subject`	object	yes	What the event changes.
`batches[].events[].subject` when `kind` is `"thread"` \| `"widget"`.
`batches[].events[].subject.kind`	`"thread"` \| `"widget"`	yes
`batches[].events[].subject.id`	string	yes
`batches[].events[].subject` when `kind` is `"page"`.
`batches[].events[].subject.kind`	`"page"`	yes
`batches[].events[].threads`	array of string	yes	Every thread the event belongs to.
`batches[].events[].says`	map of string		The words of each element the gesture names, by id, as the page it was made on wrote them.
`batches[].events[].was`	string		On the user's rewrite of their own message, the words it replaced.
`batches[].events[].suggestion`	boolean		A comment's own flag; beside an edit's `was`, true where the rewritten message is a suggestion, so its new text is the exact replacement it proposes.
`batches[].events[].answer`	object		The response the event owed at capture (`obligations.response_address`); absent where it owes none.
`batches[].events[].answer` when `kind` is `"reply"` and `writer` is `"agent"` \| `"turn"`. A thread reply under `parent` answering the input `responds`, written by the agent or, for a Codex App Server turn, by the turn's final message.
`batches[].events[].answer.kind`	`"reply"`	yes
`batches[].events[].answer.parent`	string	yes
`batches[].events[].answer.responds`	string	yes
`batches[].events[].answer.ref`	string	yes	The answer's address, which `leaf response` takes.
`batches[].events[].answer.writer`	`"agent"` \| `"turn"`	yes	Who is to write the reply when the delivery was frozen: the agent, or the final message of the turn carrying it.
`batches[].events[].answer` when `kind` is `"markup"`. A stamped page revision recording the widget action `action`.
`batches[].events[].answer.kind`	`"markup"`	yes
`batches[].events[].answer.action`	string	yes
`batches[].events[].answer.ref`	string	yes	The answer's address, which `leaf response` takes.
`batches[].events[].handling`	array of string		Ids of the batch's `handling` clauses that apply, in reading order.
`correction`	object		Asks again for one answer whose Codex turn final Leaf refused to post (`codex.prepare_reply_correction`).
`correction.delivery`	string	yes	The delivery whose answer was refused.
`correction.turn`	string	yes	The turn whose final was refused.
`correction.claim`	object	yes	The claim the refused final was written under.
`correction.claim.id`	string	yes	The claimant session.
`correction.claim.generation`	string	yes	The session generation the claim named.
`correction.claim.acquisition`	string	yes	The claim's own identity.
`correction.diagnostic`	string	yes	Why Leaf refused it.
`correction.instruction`	string	yes	What the agent is to do: fix the failure and answer the same input again.

`draft`

The composer's draft of a comment, which each tab keeps in browser storage under the passage it is on (runtime/composing/selection.js): its words, the anchor and the revision it was captured on, whether it is a suggestion or about design, its drawing, and when it was last touched. A draft's drawing adds at, the matrix that stands it in its anchor's section, which the comment leaves out: here properties beside a leaf: reference add to the object it names, as the build writes it in for the protocol baseline (build/browser/contract-types.mjs). Its format, leaf-draft/<since>, names the protocol at which this shape last changed; a tab reading a draft at another format keeps its words and drops its drawing.

Stored with format leaf-draft/15.

Field	Type	Required
`format`	string	yes
`text`	string	yes
`anchor`	`comment`'s `anchor` or null	yes
`revision`	integer	yes
`suggest`	boolean	yes
`about`	`comment`'s `about` or null	yes
`drawing`	`comment`'s `drawing` or null	yes
`drawing.at`	array of number
`touched`	number	yes

`file-bindings`

The local text files a page may edit, in the page directory's files.json.

Stored with format leaf-file-bindings/13.

Field	Type	Required	Description
`bindings`	map of string	yes	Each binding id's file, by its canonical absolute path.

`preview`

What a developer preview shows in browser chrome, as leaf-dev preview writes it to the page directory's preview.json.

Stored with format leaf-preview/13.

Field	Type	Required	Description
`example`	string	yes	The name of the source file the preview serves, without its extension.
`checkout`	string	yes	The checkout whose Leaf serves it.
`interaction`	`"user"` \| `"author"`	yes	`user` for a `--user` preview, whose presses reach the session that claimed it; `author` for a plain one.
`started`	string	yes	When the preview started.
`input`	object	yes	The fixture publication the preview's watcher last applied.
`input.source`	string	yes
`input.authored`	string	yes

`reconnect`

The pages a session has been told to reconnect, one notice each per outage, in the state home's sessions/<digest>.reconnect.

Stored with format leaf-reconnect/13.

Field	Type	Required	Description
`pages`	array of string	yes	Each page directory the session was told about.

`row`

A serving page's row, which other pages show it by, in the state home's rows/<page key>.json.

Stored with format leaf-row/16.

Field	Type	Required	Description
`page`	string	yes	The page directory.
`page_key`	string	yes	The page's key (`state.page_key`).
`server_id`	string	yes	The server incarnation that published the row; a reader takes only the live service's own.
`row`	object	yes	What other pages show of it.
`row.title`	string	yes	The page's title.
`row.session_cwd`	string or null	yes	The claimant session's working directory, or null.
`row.activity`	object	yes	The page's activity, bounded to the fields a row shows (`compact_activity`).
`row.activity.counts`	object	yes
`row.on_user`	integer	yes	How many rows On me holds.
`row.threads`	object	yes	What the Leaf panel's Threads mark counts (`thread_counts`): the open threads, and those the user hasn't read.
`row.threads.open`	integer	yes
`row.threads.unread`	integer	yes

`service`

The page's desired service, in the page directory's service.json, which hosting.py writes.

Stored with format leaf-service/13.

Field	Type	Required	Description
`host`	string	yes	The address a URL names.
`bind`	string	yes	The address the server binds.
`port`	integer	yes	The port the server listens on.
`enabled`	boolean	yes	Whether the page should be served.
`lifetime`	`"session"` \| `"persistent"`	yes	Whether the server stops when no live session claims the page, or runs until `leaf server stop`.
`runtime`	object	yes	The Leaf that served it (`hosting.payload_provenance`).
`server_id`	string	yes	The serving incarnation the server lease names.
`restart`	string		The mark `page init` leaves while it holds a served page down to re-vendor it (`hosting.restarting_server`).

`session`

One harness session's lifecycle, in the state home's sessions/<digest>.lifecycle (session_file): the lifetime it lives by, whether it has ended, and its current turn.

Stored with format leaf-session/13.

Field	Type	Required	Description
`id`	string	yes	The harness's own session id.
`generation`	string	yes	Replaced when a claim made before can no longer name this lifetime.
`ended`	null or string (date-time)	yes	When the session ended, or null while it lives.
`turn`	string or null	yes	The id of the session's latest turn, or null before its first.
`turn_opened`	null or string (date-time)	yes	When the latest turn opened or was last renewed.
`turn_closed`	null or string (date-time)	yes	When the turn closed, or null while it is open.
`revision`	integer	yes	Incremented by every write (`write_session`).
`provider`	boolean	yes	Whether the harness, rather than Leaf, names the turn.
`lifetime`	object	yes	What keeps the session alive (`Harness.lifetime`).
`transcript_path`	string		The native chat a desktop Codex lifetime stands on (`chat_exists`).
`launcher`	string		The developer-selected delivery runtime (`session_runtime`).

`stream`

What the harness observes of the claimant's task as it runs, in the page directory's stream.json; no_stream while it observes nothing.

Stored with format leaf-stream/16.

Field	Type	Required	Description
`activity`	object or null	yes	What the task is doing now (`set_stream_activity`), or null.
`activity.session`	string	yes	The claimant session the harness observed.
`activity.turn`	string	yes	The turn it observed.
`activity.kind`	string	yes	The step observed; the page reads one of `activity.WORK_KINDS`.
`activity.ts`	string (date-time)	yes	When it was last observed.
`activity.after`	integer	yes	The log's last `seq` when it was observed.
`activity.detail`	string		What the step names.
`reply`	object or null	yes	The reply it is drafting (`set_stream_reply`), or null.
`reply.session`	string	yes	The claimant session the harness observed.
`reply.turn`	string	yes	The turn it observed.
`reply.attempt`	string	yes	The delivery attempt it is drafted under.
`reply.parent`	string	yes	The thread it replies in.
`reply.responds`	string	yes	The input it answers.
`reply.item`	string or null	yes	The harness's id for the message supplying the draft, or null while none is attached.
`reply.text`	string	yes	Its words so far.
`reply.state`	string	yes
`reply.settles`	boolean	yes
`reply.agent`	string	yes	The name the claimant shows.
`reply.ts`	string (date-time)	yes	When the draft began.
`reply.updated_at`	string (date-time)	yes	When the draft last changed.
`reply_reservations`	map of object	yes	Each open reply reservation, by the response address it holds (`thread.reserve_delivery_reply`).
`reply_reservations.*.session`	string	yes	The claimant session the harness observed.
`reply_reservations.*.turn`	string	yes	The turn it observed.
`reply_reservations.*.attempt`	string	yes

`user-views`

The user's browser views of a page, in the page directory's user-views.json.

Stored with format leaf-user-views/16.

Field	Type	Required	Description
`sessions`	map of object	yes	Each document's latest report, by its session id.
`sessions.*.session`	string	yes	The document's random session id.
`sessions.*.sequence`	integer	yes	The report's place among its session's reports.
`sessions.*.visible`	boolean	yes	Whether the document was visible.
`sessions.*.revision`	integer	yes	The revision the document shows.
`sessions.*.through_seq`	integer or null	yes	The log position the tab's latest server reading was taken through, or null before one arrives.
`sessions.*.viewport`	object	yes	The layout viewport, in CSS pixels.
`sessions.*.viewport.width`	number	yes
`sessions.*.viewport.height`	number	yes
`sessions.*.visual_viewport`	object	yes	The visual viewport, as `window.visualViewport` reports it.
`sessions.*.visual_viewport.width`	number	yes
`sessions.*.visual_viewport.height`	number	yes
`sessions.*.visual_viewport.offset_left`	number	yes
`sessions.*.visual_viewport.offset_top`	number	yes
`sessions.*.visual_viewport.scale`	number	yes
`sessions.*.shown_window`	object	yes
`sessions.*.shown_window.x`	number	yes
`sessions.*.shown_window.y`	number	yes
`sessions.*.shown_window.width`	number	yes
`sessions.*.shown_window.height`	number	yes
`sessions.*.color_scheme`	`"light"` \| `"dark"`	yes	The scheme the document is drawn in.
`sessions.*.reduced_motion`	boolean	yes	Whether the user prefers reduced motion.
`sessions.*.pointer`	`"coarse"` \| `"fine"`	yes	Whether the primary pointer is coarse, as a finger is, or fine.
`sessions.*.scroll`	object	yes	The document's scroll offset.
`sessions.*.scroll.x`	number	yes
`sessions.*.scroll.y`	number	yes
`sessions.*.visible_regions`	array of string	yes
`sessions.*.checks`	object or null	yes	The document's latest view checks, with the revision, log position, viewport and scheme they read, or null.
`sessions.*.checks.sequence`	integer	yes
`sessions.*.checks.revision`	integer	yes
`sessions.*.checks.through_seq`	integer or null	yes
`sessions.*.checks.viewport`	object	yes
`sessions.*.checks.viewport.width`	number	yes
`sessions.*.checks.viewport.height`	number	yes
`sessions.*.checks.visual_viewport`	object	yes
`sessions.*.checks.visual_viewport.width`	number	yes
`sessions.*.checks.visual_viewport.height`	number	yes
`sessions.*.checks.visual_viewport.offset_left`	number	yes
`sessions.*.checks.visual_viewport.offset_top`	number	yes
`sessions.*.checks.visual_viewport.scale`	number	yes
`sessions.*.checks.shown_window`	object	yes
`sessions.*.checks.shown_window.x`	number	yes
`sessions.*.checks.shown_window.y`	number	yes
`sessions.*.checks.shown_window.width`	number	yes
`sessions.*.checks.shown_window.height`	number	yes
`sessions.*.checks.color_scheme`	`"light"` \| `"dark"`	yes
`sessions.*.checks.reading`	object	yes
`sessions.*.checks.checked_at`	string (date-time)	yes	When the server first received these checks.
`sessions.*.received_at`	string (date-time)	yes	When the server received the report.
`viewed`	number		When a report last said a document was visible, in POSIX seconds (`viewed_at`).

`website-publication`

What leaf.page's container last published of a page, in its state home's website-publications/<page key>.json, so an unchanged page is not published again.

Stored with format leaf-website-publication/13.

Field	Type	Required	Description
`fingerprint`	string	yes	The page reading the publication was made from (`record_reading`).

Interaction batch

The browser posts what it observed of the user's session, such as DOM events, to the page's diagnostic trace, observations.jsonl. Nothing in the page's state is read from it.

`POST /api/interaction`

A batch of browser interaction observations as both doors admit it: the local server's /api/interaction (interaction_log.admit_batch) and leaf.page's Worker, whose zod schema (interactionBatch in worker/src/interactions.ts) worker/test/interactions.test.ts holds to this one. A batch that fails is refused whole. An entry's other fields stay open: the local server keeps them as the browser sent them (runtime/interaction-log.js), and the Worker keeps only the structural fields its projection declares.

Field	Type	Required	Description
`session`	string	yes	The tab's diagnostic session, the runtime's one random identifier (`runtime/ids.js`).
`entries`	array of object	yes	The observations, each numbered by `sequence`.
`entries[].observed_at`	string	yes	The tab's wall clock, as `Date.prototype.toISOString` writes it.
`entries[].monotonic_ms`	number	yes	The document's monotonic clock (`performance.now`).
`entries[].sequence`	integer	yes	The observation's place in its session, from 1.
`entries[].visibility`	`"visible"` \| `"hidden"`	yes	The document's `visibilityState` when it observed the entry.
`entries[].type`	string	yes	What was observed, such as a DOM event's type.