reference

Data structures

Leaf uses JSON for the state the server sends to the browser, the events in a page's log, and the records stored 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 describe JSON responses to POST requests. The user-view and interaction endpoints return no response body. leaf page state prints selected fields from the same state.

`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; a request naming a reading the tab holds may be answered with a Tail instead. 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). It is not part of the page protocol: the runtime that reads it comes from the Leaf that serves it (runtime_selection.py), so a change needs no bump. 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
`layer`	object	yes	The identity of the layer the shown revision was read under, or the page's before a revision exists (`layer-registry.md`): its generation and selection, and the fingerprint and producer of the layer the serving Leaf composes for it (`served_state.page.served_layer_identity`).
`layer.generation`	string	yes
`layer.fingerprint`	string	yes
`layer.packages`	array of string
`layer.theme`	object or null
`layer.theme.name`	string	yes
`layer.theme.source`	`"explicit"` \| `"default"`	yes
`layer.producer`	Provenance
`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
`others[].activity.kind`	Activity's `kind`	yes
`others[].activity.held`	Activity's `held`	yes
`others[].activity.dropped`	Activity's `dropped`	yes
`others[].activity.detail`	Activity's `detail`	yes
`others[].activity.observed`	Activity's `observed`	yes
`others[].activity.observed_kind`	Activity's `observed_kind`	yes
`others[].activity.awaiting`	Activity's `awaiting`	yes
`others[].activity.counts`	Activity's `counts`	yes
`others[].activity.ts`	Activity's `ts`	yes
`others[].activity.next_transition_at`	Activity's `next_transition_at`	yes
`reading`	string	yes	The news token of the facts this answer read (`served_state.reading`), which the tab's freshness reads compare.
`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 the layer it serves under, its neighbors and token. Before the page has an active revision, active and browser are null.

Field	Type	Required	Description
`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`).
`seen`	Revision or null	yes	The newest revision a tab showed the user while they were there, posted as they left (`read_state.seen_revision`), from which the browser counts what changed since (since-seen.js). Null before any, and on a hosted copy, whose reader is not the page's user.
`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	yes
`data.sources.*.run`	string	yes
`data.sources.*.updated`	string	yes
`data.sources.*.value`	any
`data.sources.*.error`	string
`data.sources.*` one of: requires `value` and forbids `error`; requires `error` and forbids `value`.
`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.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.
`forked`	array of string	yes	The user's waiting messages a fork of the claimant's conversation has taken on (`forks.forked`).
`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.
`session_name`	string or null	yes	What the claimant's harness calls its session now (`Harness.session_name`), or null where it names none.
`turn`	string or null	yes	The claimant's current turn, which an opened delivery names, or null. It and the two stamps after it are the claim's turn under the session record's names, which `state.turn_open` and `state.turn_closed` read.
`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`).
`input_wakes`	boolean	yes	Whether the nudge the claimant's next input gets would start a turn of its session's (`Harness.input_wakes`).
`fork_lane`	number or null	yes	When the claimant's fork lane came up, in seconds since the epoch, or null while none runs (`forks.lane_since`).
`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. An export's reading is folded from less of it (`exporting._page_log`).
`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.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

`WorkflowLine`

A workflow's last explicit work line comes from a start record, so its text and log position arrive together (workflows.workflow); a failed delivery has neither.

Field	Type	Required	Description
variant 1.
`detail`	string
`detail_seq`	integer
variant 2.
`detail`	null
`detail_seq`	null

`Workflow`

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

Type: WorkflowLine.

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, whatever its condition: at `working` or `replying`, or a fork of its conversation has taken its input on (`forks.forked`).
`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.
variant 1.
`subject.kind`	`"widget"`	yes
`subject.id`	string	yes
variant 2.
`subject.kind`	`"thread"`	yes
`subject.id`	string	yes

`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
`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

`Gesture`

What an action did, in its record form's terms and its own document's words (gesture_words.GestureWords.gesture).

Field	Type	Required
`form`	`"choice"` \| `"move"` \| `"edit"` \| `"add"` \| `"verb"`	yes
`chosen`	array of string
`unit`	string
`to`	string
`words`	string
`verb`	string
when `form` is `"choice"`, requires `chosen`.
when `form` is `"move"`, requires `unit`, `to`.
when `form` is `"add"`, requires `words`.
when `form` is `"verb"`, requires `verb`.

`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"`	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`	Gesture
`value`	any
`version`	integer
when `kind` is `"comment"`, requires `anchor`, `about`.
when `kind` is `"reply"`, requires `thread`.
when `kind` is `"edit"`, requires `thread`.
when `kind` is `"resolve"`, requires `thread`.
when `kind` is `"unresolve"`, requires `thread`.
when `kind` is `"action"`, requires `widget`, `gesture`.
when `kind` is `"report"`, requires `widget`, `value`, `excerpt`.
when `kind` is `"note"`, requires `version`, `excerpt`.

`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, and, in an answer a page server sent, `key`, the reading's name, a digest of its content, which a request sends back in `Leaf-Held-Basis` to be answered with only what changed since (`Tail`).
`basis.through_seq`	integer	yes
`basis.key`	string
`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.
`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
`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`	ViewDocument	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 names 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`), or in an answer with `since` those new or changed since; `newest` marks the user's newest gesture, and `gesture` says what that one did when it is an action.
`undo[].event`	Event	yes
`undo[].coordinate`	array of string
`undo[].newest`	`true`
`undo[].gesture`	Gesture
`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

`Projection`

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

Field	Type	Required	Description
`entries`	array of object	yes	Each widget event this projection classifies, in log order, or in an answer with `since` those new or changed since.
`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

`ObligationAnswer`

Field	Type	Required	Description
`value`	any	yes
`event`	EventReference or null	yes

`WidgetObligationSource`

Field	Type	Required	Description
`kind`	`"widget"`	yes
`id`	string	yes
`tag`	string	yes
`unit`	string		A data record within the owning widget; its projected datum and action unit share this key.

`UpdateObligationSource`

An update the user handed over: id is the input's event, subject the thread or widget it stands on.

Field	Type	Required
`kind`	`"update"`	yes
`id`	string	yes
`subject`	Subject	yes

`MessageObligationSource`

Field	Type	Required	Description
`kind`	`"message"`	yes
`id`	string	yes

`ObligationPrompt`

Field	Type	Required	Description
`text`	string or null	yes
`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 a message, whose thread supplies navigation.

`Obligation`

One request and its contained answer (obligations.py, which owns the statuses): what a message or widget waits on the user for, or what a user update 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`	WidgetObligationSource or UpdateObligationSource or MessageObligationSource	yes
`thread`	string or null	yes
`message`	string or null	yes
`prompt`	ObligationPrompt	yes
`answer`	ObligationAnswer 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
variant 1.
`answer.value`	any	yes
variant 1.
variant 2.
variant 2.
`answer.value`	null	yes
variant 3.
`answer.value`	object	yes
`answer.value.text`	string
`answer.value.token`	string

`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 record in 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"` \| `"update"` \| `"message"`	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.
`also`	array of string	yes	The other obligations the user answers at the same place, each a view's `obligations` entry: the further records a thread's reply answers, and on an obligation's row those of a thread about it.
`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 <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"`	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.

`MessageEdited`

The user's latest rewrite of a message, and the words it replaced (events.rewritten).

Field	Type	Required
`id`	string	yes
`seq`	integer	yes
`ts`	string	yes
`was`	string	yes

`MessageWithdrawn`

The undo that took a message back while something still stood on it, and what it said; the message keeps its place with no words and no mark (events.message_reading).

Field	Type	Required
`id`	string	yes
`ts`	string	yes
`was`	string	yes

`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 latest edit's words, and 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
`completed_by`	string		The ordinary or provisional reply that supersedes this progress message. Hide it only while that reply is presented.
`edited`	MessageEdited
`withdrawn`	MessageWithdrawn
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 `"obligation"` \| `"resend"`.
`kind`	`"needs_user"`	yes
`reason`	`"obligation"` \| `"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[].protected`	array of string	yes
`unread`	map of string	yes	The content version of each message the user hasn't read, by the message's id, in log order (`read_state.unread_content`).
`attention`	Attention	yes

`Stage`

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

`ViewDocument`

A revision's document as a view serves it: its widget state's projection under the registry it captured (served_state.document.browser_document).

Field	Type	Required	Description
`revision`	integer	yes
`projection`	Projection	yes

`ViewAnswer`

The answer GET /api/view gives (served_state.service.PageStateService.page_comparison): what a version comparison folds of one revision at an exact log boundary.

Field	Type	Required	Description
`document`	ViewDocument	yes
`saved_after`	array of object or null	yes	Where the request names `shown`, the user's messages that waited while the version at that revision was saved, compared with this one, in the order they were sent (`provenance.saved_after`); null where it names none, or where nothing can be said.
`saved_after[].thread`	string	yes
`saved_after[].message`	`comment` or `reply`	yes	The message as its thread held it at the latest of the version's revisions it waited at (`event_facts.EventFacts.message_at`), which the browser reads as a thread reads a message (`thread/messages.js`, `messageWords`): its words then, `edited` by the rewrite then standing.
`saved_after[].message.edited`	MessageEdited
`saved_after[].message.withdrawn`	MessageWithdrawn

`Tail`

What a page server sends a tab in place of a reading when the tab's request names, in Leaf-Held-Basis, the browser.basis.key of a reading it holds and the server still remembers that reading (served_state.tail). The browser applies patch to the reading since names and completes the whole answer from it (completeState in layer-client.js).

Field	Type	Required	Description
`since`	object	yes	The reading the changes start from.
`since.key`	string	yes
`patch`	array of Change	yes	The changes from that reading to this one, in order. They leave out `events` and `data`.
`events`	array of Event	yes	The events logged after that reading's `through_seq`.
`data`	Reading's `data`	yes

`Change`

One change a Tail makes to the reading it starts from, at at, a path of keys through its objects from the root of what it changes: the reading, or for a change inside a list's item, that item (served_state.tail).

Field	Type	Required
variant 1. The value at `at` is now `value`, whole.
`at`	array of string	yes
`value`	any	yes
variant 2. The object holding the last key of `at` no longer holds it.
`at`	array of string	yes
when `by` is `"id"` \| `"event"` \| `"self"`. The list at `at`, whose items are each named by its `id` (`by` `id`), its event's `id` (`event`) or itself, a string (`self`), changed: `items` holds its new items whole, `changed` pairs the name of each item it held that is now otherwise with the changes from that item to what it is now, `dropped` names those it no longer holds, and `after` pairs each item that is new or moved, in the list's order, with the name of the item now before it, or null for the first. Every other item keeps its place.
`at`	array of string	yes
`by`	`"id"` \| `"event"` \| `"self"`	yes
`items`	array of any
`changed`	array of [string, array of Change]
`dropped`	array of string
`after`	array of [string, string or null]

`EventAnswer`

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

Field	Type	Required	Description
when `ok` is `true`. Accepted, with the event the log holds for it and the page's state, which holds the event's receipt (`event_endpoint.with_state`).
`ok`	`true`	yes
`event`	Event	yes
`needs_reply`	boolean	yes	Whether the event owes the agent an answer: its update stands among those the agent owes (`obligations.update_obligation`).
`state`	served state or Tail	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 or Tail
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, validated against the schema for its kind before it is appended. 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. A undoable 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
`obligation`	`true`
`viewing`	array of 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. A undoable 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
`obligation`	`true` or array of string
one of: requires `text`; requires `token`.

`edit`

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

Field	Type	Required	Description
`author`	`"agent"` \| `"user"`	yes
`kind`	`"edit"`	yes
`attempt`	string
`message`	string	yes
`text`	string	yes	The message's new words. None deletes it: readings keep it in its place with no words (events.md, "Messages").
`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

`seen`

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

Field	Type	Required
`author`	`"user"`	yes
`kind`	`"seen"`	yes
`revision`	integer	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
`subject`	object	yes
`subject` when `kind` is `"widget"` \| `"element"` \| `"thread"`.
`subject.kind`	`"widget"` \| `"element"` \| `"thread"`	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
`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.

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

`activation`

What it means. A bookkeeping kind.

Field	Type	Required
`author`	`"page"`	yes
`kind`	`"activation"`	yes
`revision`	integer	yes
`publication`	string	yes

`reanchor`

What it means. A bookkeeping kind.

Field	Type	Required
`author`	`"page"`	yes
`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

`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.decides`	boolean	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.decides`	boolean	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`).

`clerk`

The lines Leaf queued for a session's next step, in the state home's sessions/<digest>.clerk (state.session_file): one for each record the clerk wrote and each finding it passes on (clerk), and one for each reply a fork of the conversation posted (forks).

Stored with format leaf-clerk/36.

Field	Type	Required	Description
`lines`	array of string	yes

`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 launcher 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	The indexes into `batches` whose page receipts are still to be written.
when `state` is `"hook"` \| `"opened"`.
`turn`	string	yes	The Codex turn that carries the delivery: the one its hook ran in, or the one its App Server delivery entered.

`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[].viewing`	`comment`'s `viewing`
`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[].messages[].withdrawn`	object		The user's undo of a message something still stood on, and what the message said; it keeps its place with nothing in it.
`batches[].threads[].messages[].withdrawn.id`	string	yes
`batches[].threads[].messages[].withdrawn.ts`	string	yes
`batches[].threads[].messages[].withdrawn.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[].names`	map of string		The name of each element in `says`, by id, in the gesture's own document: its declared name or leading title, else its words.
`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[].unsent`	array of object		On the user's message or edit about a widget, one their thread is anchored in or was sent in, the work they had made there without sending it (`$state.unsent`), as it stood when they wrote: what the widget showed them (`thread_context.unsent_at_messages`). Absent where none stood.
`batches[].events[].unsent[].id`	string	yes
`batches[].events[].unsent[].seq`	integer	yes
`batches[].events[].unsent[].author`	string	yes
`batches[].events[].unsent[].widget`	string	yes
`batches[].events[].unsent[].action`	string	yes
`batches[].events[].unsent[].detail`	object	yes
`batches[].events[].waiting`	array of object		The agent's questions the input may have answered though it answers them by no rule: on a widget action, those still waiting on the user's words in a thread about that widget's obligations (`obligations.waiting_about`); on the user's message in a thread, those still waiting on a pick on a widget frozen there (`obligations.waiting_in_thread`). Each is the obligation's `id` and the `text` that asked it.
`batches[].events[].waiting[].id`	string	yes
`batches[].events[].waiting[].text`	string or null	yes
`batches[].events[].settled`	array of object		On the user's message in a thread, the agent's questions in words it answered by rule, whatever it says, so they have left On Me (`obligations.settled_by_message`). Each is the obligation's `id` and the `text` that asked it.
`batches[].events[].settled[].id`	string	yes
`batches[].events[].settled[].text`	string	yes
`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 delivery reference identifying this answer.
`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 delivery reference identifying this answer.
`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 selection composer's submission payload, kept beside its words in the shared draft generation (runtime/drafts.js): 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 payload's shape last changed; the composer reads only its current format.

Stored with format leaf-draft/17.

Field	Type	Required
`format`	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.

`fork-lane-start`

The admission cutoff of a session's fork lane. Its live lease alone proves that lane is running (forks.take_lane).

Stored with format leaf-fork-lane-start/37.

Field	Type	Required	Description
`since`	number	yes

`forks`

The thread messages a fork of a Claude Code session's conversation handed to the session, in the state home's sessions/<digest>.forks (state.session_file): for each page, by state.page_key, the ids of the messages it handed over that the session hasn't yet received (forks).

Stored with format leaf-forks/37.

Field	Type	Required	Description
`handed`	map of array of string	yes

`http-connections`

Stored with format leaf-http-connections/19.

Field	Type	Required
`page`	string	yes
`connections`	map of object	yes
`connections.*.origin`	string	yes
`connections.*.credential`	string	yes
`connections.*.header`	string	yes
`connections.*.prefix`	string	yes
`connections.*.remaining`	integer	yes

`layer`

A page's layer selection, layer.json in its directory: the packages and theme every Leaf that reads the page composes, the generation an open document speaks, and the page protocol a Leaf last initialized it at.

Stored with format leaf-layer/36.

Field	Type	Required
`packages`	array of string	yes
`theme`	null or object	yes
`theme` when `source` is `"explicit"` \| `"default"`.
`theme.name`	string	yes
`theme.source`	`"explicit"` \| `"default"`	yes
`generation`	string	yes
`protocol`	integer	yes

`pointed`

The pages whose input a hook handed a session's turn by pointer, in the state home's sessions/<digest>.pointed (state.session_file).

Stored with format leaf-pointed/24.

Field	Type	Required	Description
`turn`	string	yes	The turn the pointers were handed to.
`opened`	string	yes	When that turn last opened (`turn_opened`): a prompt that opens it again hands the input over anew.
`pages`	map of integer	yes	Each page directory, with the last log position pointed at.

`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

`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 counts of the threads (`thread_counts`): the open threads, and of those the ones 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 (`layer.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 rewrite its layer record (`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/27.

Field	Type	Required	Description
`sessions`	map of object	yes	Each document's latest report, by its session id.
`sessions.*.identity`	object	yes	The rendering identity captured by this document.
`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.identity`	object	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.