@agentshouse/mdruntime 0.1.0-c454894e67f74 → 0.1.0-c52c32704e1a1

package/AGENTS.md

@@ -1,302 +1,304 @@
 # Instructions for the App Creator's agent
 
-These instructions address an agent in an environment with Git. Obtain the App
-Repository, change it, build, and push. They are documentation, not enforcement.
+These instructions address an agent in an environment with Git: obtain the App Repository,
+change it, build, and push. They are documentation, not enforcement.
 
 ## The MD Runtime API
 
-App code reaches the MD Runtime through the remote client. The surfaces are Rooms,
-Query, Search, Observe, Types, Room Draft, Save, History, the binary file reads, Call,
+App code reaches the MD Runtime through the remote client. The surfaces are Rooms, Query,
+Search, Observe, Types, Room Draft, Save, History, Resolve, the binary file reads, Call,
 Reached, Log, the reported persistence answer, reauthorization, conversation, the chat
 draft, and Presentation State. Sync Status, readiness, the Service Mode, the storage-loss
 statement, the deployment facts and the signed-in member are observations only.
 
 The host attaches each port with its reach, and every member and observation answers
 within it: a Room outside it answers as one the replica does not hold, Rooms lists only
-the Rooms reached whole, a Room reached for single Documents shows only those Documents
-and the Types of the models that govern them, and without conversations the conversation
-members, the chat draft and the conversation observation hold none. A change of the
-reach reaches every open observation as its new value, a query keeping unchanged
-Documents the same objects.
+the Rooms reached whole, a Room reached for single Documents shows only them and their
+models' Types, and without conversations the conversation members, chat draft and
+observation hold none. A changed reach reaches every open observation as its new value.
 
-Every `observe` resolves, once its first value has arrived, to a handle: `current()` is
-the latest complete value, `subscribe(listener)` hears each later value whole and returns
-its unsubscribe, and `close()` ends the observation. Closing the port ends every handle
-and rejects every pending call and observation; a client that reconnects observes again.
+Every `observe` resolves, once its first value arrived, to a handle: `current()` is the
+latest complete value, `subscribe(listener)` hears each later value whole and returns its
+unsubscribe, and `close()` ends it. Closing the port ends every handle and rejects every
+pending call and observation; a reconnected client observes again.
 
 `observe('agents')` answers every Agent a new conversation can go to, each `{ identity,
-name }`, whether or not it has a conversation yet. Each conversation the Provider's
-conversation list names is held complete in the browser. `conversation.list()` and
-`observe('conversations')` answer each with its Agent's identity and name, its name,
-created and finished times, last outcome and live `state`: `asking` while a question
-waits, `working` while a turn runs, else `idle`, and `started`, when the running turn
-began, or `null`. Observe one with `observe('conversation', id, { limit })`: the view
-holds a window of its latest `limit` messages, or all of them, oldest first, its chat
-draft, and what the Provider streams for it whether or not anything views it: the
-running `turn` with its message parts and its context in use and window, the open
-questions, the process state, and the CLI's commands and options. These live only in
-memory: the message accepted under the turn's id replaces the running turn, and none of
-them is stored or searchable. `chatDraft.write` and `chatDraft.discard` keep what the
-App Creator composes; sending it is a Provider Action that needs the Provider reachable
-and is never queued. A new conversation's chat draft is the one keyed `new:<Agent
+name }`, with a conversation yet or not. Each conversation the Provider lists is held
+complete in the browser. `conversation.list()` and `observe('conversations')` answer each
+with its Agent's identity and name, its name, created and finished times, last outcome,
+live `state` (`asking` while a question waits, `working` while a turn runs, else `idle`)
+and `started`, when the running turn began, or `null`. `observe('conversation', id, {
+limit, total: true })` holds its latest `limit` messages, at most 1,000, oldest first,
+`total` their count, and `next` while older ones exist, which `after` takes, there or in
+`conversation.read(id, { limit, after })`, for the window before; its chat draft; and,
+only in memory, what the Provider streams whether or not anything views it: the running
+`turn` with its parts and its context in use and window, which the message accepted under
+the turn's id replaces, the open questions, the process state, and the CLI's commands and
+options, none stored or searchable. `chatDraft.write` and `chatDraft.discard` keep what
+the App Creator composes, and `chatDraft.prepend(conversation, draft)` puts a returned
+message ahead of it as it stands. Sending it is a Provider Action that needs the Provider
+reachable and is never queued. A new conversation's chat draft is keyed `new:<Agent
 identity>`: no conversation list removes it, a retired Agent's goes, and the first answer
 to `conversation.create({ agent_id, operation_id })` moves it to the created conversation,
 where `conversation.send(conversation)` sends it; a replay of that create moves nothing.
 
-A binary file at a Path is a binary Path entry. Query lists it by `path`, and History
-each of its revisions, with its `binaryFile` record and never its bytes: `{ state:
-'accepted', revision, path, fileRef, byteLength, mediaType, sha256 }`, or, from a Save
-until the Provider accepts it, `{ state: 'pending', localId, path, byteLength,
-mediaType, sha256 }`. Write one with a Room Draft whose only part is `file: { blob }`,
-the `Blob`'s `type` its media type: Save keeps the bytes in its Pending Change, offline
-too, and acceptance gives the record the Provider's revision. Move or remove one as a
-Document, a pending one before or after Save too, its bytes following; once its Pending
-Change has gone to the Provider, Save refuses that as `unknown-revision` until it is
-accepted. `binaryFile.read(room, path, revision?)` answers a pending record's saved
-bytes, or asks the Provider again on every read of an accepted one or of a History
-revision, a removed file's last included, keeping nothing. Text, a Record attachment or
-a conversation message may name a file by its `fileRef`; read it with
-`binaryFile.readReference({ fileRef, referrer })`, the referrer being the `referrer` the
-Provider gave beside it, or `{ room, path }` of the document whose text names it. Both
-answer `{ kind: 'binary', blob }` or a refusal or failure.
+Presentation State is one value per App, kept in the browser and shared by its tabs:
+`presentation.read()` answers it, `null` before anything is kept,
+`observe('presentation')` hears it whole, `presentation.write(value)` replaces it whole,
+and `presentation.edit(members)` sets each member named, or removes one named `null`, in
+the state as it stands, so tabs changing different members never lose each other's change:
+never write back a value read before. Each rejects when the browser does not keep the
+change, and no tab sees it then.
+
+A binary file at a Path is a binary Path entry. Query lists it by `path`, and History each
+of its revisions, with its `binaryFile` record and never its bytes: `{ state: 'accepted',
+revision, path, fileRef, byteLength, mediaType, sha256 }`, or, from a Save until the
+Provider accepts it, `{ state: 'pending', localId, path, byteLength, mediaType, sha256 }`.
+Write one with a Room Draft whose only part is `file: { blob }`, the `Blob`'s `type` its
+media type: Save keeps the bytes in its Pending Change, offline too, and acceptance gives
+the record the Provider's revision. Move or remove one as a Document, a pending one too,
+its bytes following; once its Pending Change has gone to the Provider, Save refuses that
+as `unknown-revision` until it is accepted. `binaryFile.read(room, path, revision?)`
+answers a pending record's saved bytes, or asks the Provider on every read of an accepted
+one or a History revision, a removed file's last included, keeping nothing. Text, a Record
+attachment or a conversation message may name a file by its `fileRef`; read it with
+`binaryFile.readReference({ fileRef, referrer })`, the `referrer` the Provider gave beside
+it, or `{ room, path }` of the document whose text names it. Both answer
+`{ kind: 'binary', blob }` or a refusal or failure.
 
 Rooms, Query, Search, Observe, Types, Room Draft, Save, and Reached never touch the
-network. History, the binary file reads and Call go to the Provider through the Adapter.
-Call takes the Action names the Adapter declares; any other name answers `undeclared`
-without reaching the Provider. A Call result whose effect the Provider places in a Room
-carries `at`, that Room and Room Version; `reached(room, roomVersion)` answers whether
-the Room's confirmed state has reached it, and the MD Runtime keeps refreshing that Room
-until it has; `reached(room, roomVersion, path)` answers whether the held confirmed copy
-of that document was written at a later Room Version. Each History revision names its
-author, `{ kind: 'user', id }` or `{ kind: 'site', id, name }`. History of a Path no
-current document holds answers the removed document's revisions with `deleted: true`,
-newest first; that revision is what a link to the Path opens. Every member of the client
-is asynchronous. Results are detached snapshots. Nothing in this surface returns the
-authorization, performs a request the App's code composes, or exposes the browser store.
+network; History, the binary file reads and Call go to the Provider through the Adapter.
+Call takes the Action names the Adapter declares, any other answering `undeclared`. A Call
+result whose effect the Provider places in a Room carries `at`, that Room and Room
+Version: `reached(room, roomVersion)` answers whether the Room's confirmed state has
+reached it, refreshing the Room until it has, and `reached(room, roomVersion, path)`
+whether the held copy of that document was written later. A History revision names its
+author, `{ kind: 'user', id }` or `{ kind: 'site', id, name }`; History of a Path no
+document holds answers the removed document's revisions, newest first, with `deleted:
+true`, which a link to the Path opens. Every member is asynchronous and every result a
+detached snapshot; nothing returns the authorization, performs a request the App's code
+composes, or exposes the browser store. A Room `rooms` names `locked` shows only online.
 
 Every refusal and failure carries `code` and `retryable`: each Call and History answer
-other than its result, a refused Save or Room Draft write, a returned Room Draft's
-reason, a Room's refusal and the Connection Refusal, and every error a member rejects
-with, beside its message. A Provider refusal carries the Provider's own `retryable`.
-Every code and every value the API answers is open: handle one you do not know by its
-`code` and `retryable`. Only a tag telling which fields a value carries, such as an
-answer's `kind`, is closed so it narrows: keep a branch for a tag you do not know. A
-model with no usable types answers `types: null`, whatever its `status`.
+other than its result, a refused Save or Room Draft write, a returned Room Draft's reason,
+a Room's refusal, the Connection Refusal and every error a member rejects with, beside its
+message, a Provider refusal with the Provider's own `retryable`. Every code and value is
+open: handle one you do not know by its `code` and `retryable`. Only a tag telling which
+fields a value carries, such as `kind`, is closed: keep a branch for one you do not know.
+A model with no usable types answers `types: null`.
 
 Read the deployment facts with `observe('deployment-facts')`, an opaque value the host's
-contract interprets. `observe('member')` answers who uses the App: the User the Provider
-signed in, `{ kind: 'user', id, name }` in the shape of a change's `author`, so a
-Document whose `change.author.id` equals its `id` is that User's own. It is `null` until
-the Provider first names one, and where it names none, such as a Site. The MD Runtime
-keeps it with the Local Replicas, so it answers offline once known, and every port hears
-the next member the Provider names; signing out answers `null`, then ends the
-observation with the authorization. It is the only way App code learns who uses it.
+contract interprets. `observe('member')` answers who uses the App, the only way App code
+learns it: the User the Provider signed in, `{ kind: 'user', id, name }` like a change's
+`author`, so a Document whose `change.author.id` is its `id` is that User's own; `null`
+until the Provider first names one, and where it names none, such as a Site. It is kept
+with the Local Replicas, answers offline once known, and every port hears the next member
+named; signing out answers `null`, then ends the observation with the authorization.
 
 ## Local Query rules
 
-`query(q)` answers once from local state; `observe('query', q)` holds the whole result
-and hears it again only when it changes, keeping every unchanged Document the same
-object, so a component can tell what changed by identity. An answer is complete or
-pending: `{ documents, coverage }` or `{ groups, coverage }` is complete for the Rooms
-its `coverage` names, and `{ pending }` names each Room not yet acquired or prepared,
-`[{ room, awaits }]`. Never read a pending answer as empty: draw it as loading, and
-observe the query to hear the complete one. A query is data:
+`query(q)` answers once from local state; `observe('query', q)` holds the whole result and
+hears it again only when it changes, keeping every unchanged Document the same object, so
+a component can tell what changed by identity. `{ documents, coverage }` or `{ groups,
+coverage }` is complete for the Rooms its `coverage` names, and `{ pending }` names each
+Room not yet acquired, prepared or unlocked, `[{ room, awaits }]`: never read it as empty,
+draw it as loading and observe the query to hear the complete answer. A query is data:
 
 - **Filter.** `rooms` names Room locators and defaults to every Room. `types` names MD
-  Types, and `any` names untyped Markdown Documents. `pathPrefix` is a directory:
-  `notes` keeps `notes/a.md` and not `notes2/a.md`.
+  Types, and `any` names untyped Markdown Documents. `pathPrefix` is a directory: `notes`
+  keeps `notes/a.md` and not `notes2/a.md`; `folder` keeps only what lies directly in it.
+  `paths` keeps only the Paths it names: read named Documents so, never from a list.
 - **Fields.** Every frontmatter value is named by JSON Pointer: `/status`,
   `/shipping/city`, `~1` for a `/` and `~0` for a `~` in a key. A segment that meets a
   list applies to every item and a number names one item. `where` names pointers, ANDs
-  them, and nests `$and` and `$or`; a pointer through a list holds when any item
-  satisfies it. A bare value is equality; the operators are `$eq`, `$ne`, `$in`, `$nin`,
-  `$gt`, `$gte`, `$lt`, `$lte`, `$all`, `$size` and `$exists`. Equality on a list asks
-  whether it contains the value. Missing, null and empty differ: `$exists: false` keeps
-  a missing field, `null` an explicit null, `''` empty text and `$size: 0` an empty
-  list. A date compares in calendar order and never with a date-time. A reference
-  compares by the Room Path it resolves to. Untyped frontmatter, and a value under
-  `oneOf` or a conditional, is plain values. There is no text containment or regular
-  expression.
-- **Relations.** `hop: { field, types, where, pathPrefix }` keeps Documents whose
-  reference at pointer `field`, at any depth, points to a matching Document of the same
-  Room. `backlinks: { field, types, where, pathPrefix }` keeps Documents that a matching
-  Document of the same Room references. Each keeps a Document once.
+  them, and nests `$and` and `$or`; a pointer through a list holds if any item satisfies
+  it. A bare value is equality; the operators are `$eq`, `$ne`, `$in`, `$nin`, `$gt`,
+  `$gte`, `$lt`, `$lte`, `$all`, `$size` and `$exists`. Equality on a list asks if it
+  contains the value. Missing, null and empty differ: `$exists: false` keeps a missing
+  field, `null` an explicit null, `''` empty text and `$size: 0` an empty list. A date
+  compares in calendar order and never with a date-time. A reference compares by the
+  Room Path it resolves to. Untyped frontmatter, and a value under `oneOf` or a
+  conditional, is plain values. There is no text containment or regular expression.
+- **Relations.** Within one Room, `hop: { field, types, where, pathPrefix }` keeps Documents
+  whose reference at pointer `field`, at any depth, points to a matching Document, and
+  `backlinks` with the same keys those a matching Document references, each once. A body
+  link, or a reference declaring `cross_room`, may name another Room's
+  `/rooms/<handle>/<path>`: `resolve(room, path, destination)` answers its `document`, the
+  `deleted` one's last `revision`, or `unreadable` where the App does not bind it or it is
+  locked.
 - **Parts.** A Document query must `select`: `'all'`, or `fields`, `sections`,
-  `preamble`, `markdown`, `backlinks` and `change`, where `fields` is `'all'` or a list
-  of pointers and `sections` `'all'` or a list of names. Selected pointers return the
-  frontmatter holding only them, nested as written. A backlink names the referring Path,
-  MD Type and the pointer it came from as `field`. Room and Path always return; a
-  Markdown Document also returns its MD Type. A non-Markdown Document returns only Room
-  and Path, and a binary Path entry Room, Path and its `binaryFile` record, whatever is
-  selected. An unselected part is absent. Select only what a screen shows: a list that
-  selects the Markdown hears every edit of it.
-- **Change.** `change` is `{ author, time }` of the Document's head revision as the
-  Provider last delivered it: `author` is `{ kind: 'user' | 'site', id, name }` or `null`
-  for a write the Provider made itself, and `time` is the Provider's ISO 8601 change
-  time. It is `null` where the Provider delivered no time, as at a Site. An unsent edit
-  or move keeps it, an unsent creation has none, and a saved write takes the Provider's
-  own once it is Accepted. A Room's last change is its Document with the latest `time`.
-- **Order and groups.** `orderBy` sorts by `room`, `path`, `type` or `{ field }` with
-  TanStack DB's own options, and ties end with Room, then Path. `groupBy` by `room`,
-  `type` or `{ field }` answers `{ groups: [{ key, count }] }`, counted over every match
-  and ordered by `count` or a key. A sort or group takes only a pointer that holds one
-  value. `limit` bounds the Documents or the groups.
-- **Results and errors.** A result carries no Room Version: read freshness from Rooms
-  and Sync Status. `coverage` names each Room read as `{ room, generation, current }`,
-  `current` false while a newer copy of that Room is being fetched, and the queued
-  changes it includes as `overlay`; a Save in a Room changes the `overlay` of every
-  query over it. An invalid query fails with the `code` `invalid-query`, `unknown-type`,
-  `unknown-field` or `wrong-kind`, naming where, and never answers an empty result in
-  its place.
+  `preamble`, `markdown`, `backlinks`, `change` and `fileId`, where `fields` is `'all'`
+  or a list of pointers and `sections` `'all'` or a list of names. Selected pointers
+  return the frontmatter holding only them, nested as written. A backlink names the
+  referring Path, MD Type and the pointer it came from as `field`. Room and Path always
+  return; a Markdown Document also returns its MD Type, and at most its first 1,000
+  backlinks: a query on the referring field reads the rest. A non-Markdown Document
+  returns only Room, Path and a selected `fileId`, and a binary Path entry its
+  `binaryFile` record too. An unselected part is absent. Select only what a screen shows:
+  a list that selects the Markdown hears every edit of it.
+- **Change and file ID.** `change` is `{ author, time }` of the Document's head revision
+  as the Provider last delivered it: `author` is `{ kind: 'user' | 'site', id, name }`, or
+  `null` for a write the Provider made itself, and `time` its ISO 8601 change time, or the
+  whole change `null` where it delivered no time, as at a Site. `fileId` is the Provider's
+  Stable File ID of the file at the Path, or `null`. An unsent edit keeps both, an unsent
+  move keeps the change and carries the file ID to the new Path, so a file ID that leaves
+  one Path for another is the same file moved, and an unsent creation has neither until it
+  is Accepted. A Room's last change is its Document with the latest `time`.
+- **Order and groups.** `orderBy` sorts by `room`, `path`, `type`, `folder` or `{ field }`
+  with TanStack DB's own options; ties end with Room, then Path. `groupBy` by `room`,
+  `type`, `folder` or `{ field }` answers `{ groups: [{ key, count }] }`, counted over every
+  match and ordered by `count` or a key. A sort or group takes only a single-value pointer.
+  `limit`, at most 1,000 whatever a query names, bounds the Documents or the groups, and a
+  result it cuts short names `next`: the same query with it as `after` reads the next
+  window, in the same order, ties included. `total: true` adds `total`, every match's
+  count. An observed window hears rows entering, leaving or changing, and `next`, `total`.
+- **Results and errors.** A result carries no Room Version: read freshness from Rooms and
+  Sync Status. `coverage` names each Room read as `{ room, generation, current }`,
+  `current` false while a newer copy of that Room is being fetched, and the queued changes
+  it includes as `overlay`, which a Save in the Room changes. An invalid query fails with
+  `invalid-query`, `unknown-type`, `unknown-field` or `wrong-kind`, never an empty answer.
 
 ## Local Search rules
 
-`search({ text, documents, conversations, limit })` answers once, by words, from local
-state, with MiniSearch's defaults. There is no observed search.
-
-- **What is found.** A Document by its field values, its sections' headings and text,
-  its preamble and its Path; a message by its text. Frontmatter keys, Room Drafts, chat
-  drafts and a running turn's parts are never found. There are no phrases, word forms,
-  typo tolerance or prefix matching.
-- **Narrowing.** `documents` is a Local Query filter: `rooms`, `types`, `where`,
-  `pathPrefix`, `hop` and `backlinks`. `conversations` names conversations. Both apply
-  before `limit`, which bounds each list; without it every hit returns.
-- **Results.** `{ documents, messages, coverage }`, or `{ pending }` naming each Room or
-  conversation the search waits for while its index is prepared: ask again, and never
+`search({ text, documents, collection, conversations, limit, after, total })` answers
+once, by words, from local state, with MiniSearch's defaults. There is no observed search.
+
+- **Declaration.** Only an App whose release declares Local Search searches, its first
+  readiness waiting for its index; any other App's `search` answers the never retryable
+  `undeclared` refusal `search-undeclared`, its `fields` naming `local_search`.
+- **What is found.** A Document by its field values, its sections' headings and text, its
+  preamble and its Path, and a message by its text, never a frontmatter key, a Room Draft,
+  a chat draft or a running turn's parts, with no phrases, word forms, typo tolerance or
+  prefix matching.
+- **Narrowing.** `documents` is a Local Query filter, and `collection: true` leaves out
+  what each Room's `typedSelection` roots hold; `conversations` names conversations. All
+  apply before `limit`, which bounds each list, at most 1,000 whatever a search names. A
+  complete answer it cuts short names `next`, which `after` takes for the next window of
+  both lists. `total: true` adds `total`, each list's count.
+- **Results.** `{ documents, messages, coverage }`, or the same with `pending` naming each
+  Room or conversation the search still waits for: show its hits, ask again, and never
   read pending as no hits. `coverage` names the Rooms and conversations searched. Each
-  list is ranked by `score`, which compares hits of one list of one search. A Document
-  hit names its `room`, `path` and `type`, a message hit its `conversation` and
-  `identity`, and `matches` maps each matched word to the parts it matched in: `fields`,
-  `sections`, `preamble` or `path`, or `text`. A hit carries no position; mark the words
-  in the text you show. An invalid filter fails with its Local Query error.
+  list is ranked by `score`, comparable only within it; ties come by `room`, then `path`,
+  or by `conversation`, then `identity`. A Document hit names its `room`, `path` and
+  `type`, a message hit its `conversation` and `identity`; `matches` maps each matched
+  word to the parts it matched in: `fields`, `sections`, `preamble`, `path` or `text`. A
+  hit carries no position: mark the words you show. A bad filter fails as a query does.
 
 ## Room Draft, Save, and outcome rules
 
-The MD Runtime owns one Room Draft per Room and Path, shared by every App and tab. It is
-durable: it survives reload and navigation. A Room that Discovery stops listing takes its
-Room Drafts and its queue with it. Write a Room Draft with `roomDraft.write(room, path,
-revision, parts)`, naming the revision you read, or `null` when there was none, and every
-part it should now change: fields, sections and the preamble, or the whole Markdown, a
-creation, a move, or a removal. A part new to the Room Draft names its base, the value
-you showed when it was opened; the MD Runtime keeps a part's first base; a binary Path
-entry's move or removal takes `null` as its base. A write or a discard from an older
-revision is refused as `stale` with the current Room Draft; read it and write again.
+The MD Runtime owns one durable Room Draft per Room and Path, shared by every App and tab
+across reloads; a Room the Provider reports lost takes its Room Drafts and queue with it.
+Write one with `roomDraft.write(room, path, revision, parts)`, naming the revision you read
+or `null`, and every part it now changes: fields, sections and the preamble, or the whole
+Markdown, a creation, a move, into another Room when it names `room`, or a removal. A new
+part names its base, the value you showed when it was opened, a field's as `{ value }` or
+`null` for no such field, and keeps its first base; a binary Path entry's move or removal
+takes `null`. A write or discard from an older revision is refused as `stale` with the
+current Room Draft.
 
 Save takes one Room and the Room Drafts of it to save, each with its revision, validates
-locally, and on success appends one Change Batch to that Room's queue and removes those
-Room Drafts. It is refused with the `code` `stale`, `changed-underneath` naming each
-part whose base no longer matches the visible state, or a local validation rule, and
-then creates nothing and leaves every Room Draft in place. A directory move or removal
-is a move or removal part on each Document and binary Path entry beneath it, saved
-together.
-
-Outcomes follow the Provider's answer. An Accepted Change Batch stays in the queue,
-drawn over the confirmed layer, until the confirmed layer reaches the Room Version it
-was accepted at, and then leaves it. Conflicted and Rejected, an expired operation, and
-a change that no longer applies over the Room each leave the queue and return as Room
-Drafts on the Documents they changed, marked with why: the Provider's structured refusal
-code and fields as returned, not known to have applied, or withdrawn locally. The rest
-of the queue keeps synchronizing, and Sync Status requires attention until each returned
-Room Draft is saved again or discarded. A Change Batch keeps no outcome once it leaves
-the queue; `observe('queue', room)` shows each Pending one, and a returned Room Draft
-says why it returned. Transport failure and Provider unavailability keep work Pending
-and do not infer a rejection. A refusal the Provider marks retryable stays Pending until
-the reset it names; the MD Runtime retries the same Change Batch identity and payload
-and never infers an outcome from transport uncertainty. The MD Runtime never combines,
-reorders, or rebases.
-
-On a Site, every Save stays in the visitor's browser. Write grants and revisions do not
+locally, and on success appends one Change Batch to that Room's queue and removes those Room
+Drafts. Refused as `stale`, `changed-underneath` naming each part whose base no longer
+matches the visible state, or a local validation rule, it creates nothing and leaves every
+Room Draft. A directory move or removal is that part on each Document and binary Path entry
+beneath it, saved together; moves into another Room, saved alone, are one Change Batch in
+both Rooms' queues. `saveParts(room, [{ path, parts }])` saves parts, each Path once and
+each new part with its base, the same way but writes no Room Draft: one held at a saved Path
+stays, one at a moved Path moves with it to a destination that holds none. Never save by
+writing back a Room Draft read before.
+
+Outcomes follow the Provider's answer. An Accepted Change Batch stays in the queue, drawn
+over the confirmed layer, until that layer reaches the Room Version it was accepted at.
+Conflicted and Rejected, an expired operation, and a change that no longer applies each
+leave the queue and return as Room Drafts on their Documents, marked with why: the
+Provider's structured refusal code and fields as returned, not known to have applied, or
+withdrawn locally. The rest of the queue keeps synchronizing, and Sync Status requires
+attention until each returned Room Draft is saved or discarded. `observe('queue', room)`
+shows each Pending Change Batch, which keeps no outcome once it leaves. Transport failure,
+Provider unavailability and a refusal marked retryable, until the reset it names, keep
+work Pending; the MD Runtime retries the same Change Batch identity and payload, never
+infers an outcome from transport uncertainty, and never combines, reorders, or rebases.
+
+On a Site, every Save stays in the visitor's browser: write grants and revisions do not
 refuse it, and its Pending Change shows in every query and across reloads until the
-browser's storage is cleared. It is never sent: `observe('queue', room)` shows it
-`local`, and Sync Status never waits on it. Once the Room changes so that it no longer
-applies, it leaves the queue and returns no Room Draft.
+browser's storage is cleared. It is never sent: `observe('queue', room)` shows it `local`,
+Sync Status never waits on it, and once the Room no longer lets it apply it leaves the
+queue and returns no Room Draft.
 
 `observe('service-mode')` answers the Provider's Service Mode, `open` or `write-halted`.
-While writes are halted, Save still succeeds, its Change Batch waits unsent, and the
-queue is submitted in order once the Provider reopens writes. An Action is never held: a
-write the Provider refuses for the halt returns that refusal to its caller. Show the
-Provider as read-only instead of retrying.
-
+While writes are halted, Save succeeds, its Change Batch waits unsent and the queue is
+submitted in order once writes reopen; an Action is never held, and one the halt refuses
+returns that refusal: show the Provider as read-only instead of retrying.
 `observe('readiness')` tells whether the App's code and bound Rooms are held locally
 (`ready`), each Room's state, each refused Room's file and rule, the persistence answer
 and a paused preparation's `capacity` cause; `retry()` resumes a paused preparation.
 
-## The neutrality rule
-
-No module outside an Adapter package imports, names, or special-cases a Provider. MD UI
-and every App reach data only through the client entry.
-
-## Content-safety rules
+## Content safety and launch promises
 
-The Provider authorization belongs to the Runtime host and is never readable by the
-App's code. The App's code reaches the network only at the external origins its manifest
-declares, empty by default, and the Provider enforces that set. Every request to the
-Provider itself goes through the MD Runtime. Rendered Markdown never executes scripts,
-renders raw HTML only for the details and summary elements, and loads images and other
-resources only from origins the Provider's policy allows.
-
-## Launch promises MD UI keeps
+The Provider authorization belongs to the Runtime host and is never readable by the App's
+code. The App's code reaches the network only at the external origins its manifest
+declares, empty by default, and the Provider enforces that set. Rendered Markdown never
+executes scripts, renders raw HTML only for the details and summary elements, and loads
+images and other resources only from origins the Provider's policy allows. An agent must
+never read the authorization, load code from a Room, call the Provider directly, or rebase
+a refused Change Batch.
 
 MD UI uses semantic HTML, is fully operable from a keyboard with visible focus and
 labelled controls, and lays out from a 360 pixel wide viewport to a desktop. Its strings
 are English only, dates and numbers follow the browser locale, and content is never
-translated. Light and dark themes come from CSS custom properties with the browser's
-preference as the default and an App's override respected. What an App Creator's agent
-adds carries none of these promises by itself. Reading, querying and searching never
-wait for the network. Data lives only in the App Creator's browser and with the
-Provider.
+translated. Light and dark themes come from CSS custom properties, defaulting to the
+browser's preference and respecting an App's override. What an agent adds carries none of
+these promises by itself. Data lives only in the App Creator's browser and the Provider.
 
 ## App code takes the client its host hands it and never constructs a Runtime
 
-App code takes the client its host hands it: in House, `houseBridge().runtime` from
-`@agentshouse/app-bridge` resolves to the client House built into the page. It imports
-only types from `@agentshouse/mdruntime/client`, never calls `connectMdRuntime` or
-`serveMdRuntime`, and never imports the package main, the host entry or the Adapter
-package, which hosts and tests use. The in-memory Adapter at
-`@agentshouse/mdruntime/memory` is for tests and ships in no bundle. A Site's page fills
-its Entry Data Contract's `{"$param": name}` arguments with `boundQuery` from
-`@agentshouse/mdruntime/entry`, as House did for its HTML.
-
-A React App may observe and save through `@agentshouse/mdruntime/react`, which names
-React as a peer dependency. `useObserve(client, topic, ...input)` takes the arguments of
-`observe` and returns `{ state: 'loading' }` until the topic's first value arrives, then
-`{ state: 'ready', value }`, re-rendering on each change; a `null` client observes
-nothing and stays loading. `useSave(client)` returns `busy`, the last `outcome` or
-`failure`, and `save(room, roomDrafts)`, which writes each Path's parts onto the Room
-Draft already there, keeping the bases its parts have, or onto a new one, and saves them
-together. A refused Save leaves the Room Drafts for the App to save again or discard; a
-failure is recorded and rejects. `saveRoomDrafts(client, room, roomDrafts)` is that save
-outside a component. A react-admin or Refine App reads and writes its Rooms through the
-data providers of `@agentshouse/mdruntime-families`.
+No module outside an Adapter package imports, names, or special-cases a Provider, and
+every App and MD UI reach data only through the client entry. In House,
+`houseBridge().runtime` from `@agentshouse/app-bridge` resolves to the client House built
+into the page. App code imports only types from `@agentshouse/mdruntime/client`, never
+calls `connectMdRuntime` or `serveMdRuntime`, and never imports the package main, the host
+entry or the Adapter package; the in-memory Adapter at `@agentshouse/mdruntime/memory` is
+for tests and ships in no bundle. A Site's page fills its Entry Data Contract's
+`{"$param": name}` arguments with `boundQuery` from `@agentshouse/mdruntime/entry`, as
+House did for its HTML. While the Site prepares, a query a route's `interaction` names
+answers from the entry's result when the page observes that descriptor, and every other
+stays pending. House replaces its HTML with the page once its document changed after those
+answers, or readiness is `ready`, and then held still for two animation frames, unless the
+visitor uses the HTML: draw the route at once, never behind a placeholder. Before
+readiness is `ready`, `push` loads a new page.
+
+A React App may observe and save through `@agentshouse/mdruntime/react`, with React as a
+peer dependency. `useObserve(client, topic, ...input)` takes the arguments of `observe`
+and returns `{ state: 'loading' }` until the topic's first value arrives, then `{ state:
+'ready', value }`, re-rendering on each change; a `null` client stays loading.
+`useSave(client)` returns `busy`, the last `outcome` or `failure`, and `save(room,
+parts)`, which saves through `saveParts` and rejects with a recorded failure.
+`saveWritten(room, roomDrafts)` saves Room Drafts the App wrote, each named with the
+revision its last write returned: one another tab wrote since is refused as `stale`, and
+nothing is saved. React-admin and Refine Apps use `@agentshouse/mdruntime-families`.
 
 ## The Chat
 
-`@agentshouse/mdruntime/chat` holds the Chat, one data layer for every App; add React as
-a dependency in any App, with React DOM and `@assistant-ui/react`.
-
-Place the ready chat with `<Chat client={runtime} conversation={id} agent={agent}
-width="1/3" showChats />`: `conversation` opens one, `null` for a new chat, `agent` is
-the Agent a new chat goes to, `onOpen` hears each one it opens, and `width` is `full`
-(the place you give it), or `3/4`, `1/2` or `1/3` of the window docked at its right
-edge, whole on a narrow window. `showChats` adds its conversation list; or draw your own
-inside a `ChatProvider` around a `<Chat />` with no `client`. It carries its own styles;
-theme it with CSS custom properties on it or an ancestor: `--chat-background`,
-`--chat-surface`, `--chat-text`, `--chat-text-muted`, `--chat-accent`, `--chat-line`,
-`--chat-attention`, `--chat-danger`, `--chat-font`, `--chat-font-mono`,
-`--chat-font-size`, `--chat-radius` and `--chat-density` (a factor for spacing); an
-unset one keeps House's light or dark look. `mountChat(element, { client })` places it
-outside React and returns `update(props)` and `unmount()`.
+`@agentshouse/mdruntime/chat` holds the Chat, one data layer for every App; add React as a
+dependency in any App, with React DOM and `@assistant-ui/react`. Place the ready chat with
+`<Chat client={runtime} conversation={id} agent={agent} width="1/3" showChats />`:
+`conversation` opens one, `null` for a new chat, `agent` is the Agent a new chat goes to,
+`onOpen` hears each one it opens, and `width` is `full` (the place you give it), or `3/4`,
+`1/2` or `1/3` of the window docked at its right edge, whole on a narrow window.
+`showChats` adds its conversation list; or draw your own inside a `ChatProvider` around a
+`<Chat />` with no `client`. Theme its own styles with CSS custom properties on it or an
+ancestor: `--chat-background`, `--chat-surface`, `--chat-text`, `--chat-text-muted`,
+`--chat-accent`, `--chat-line`, `--chat-attention`, `--chat-danger`, `--chat-font`,
+`--chat-font-mono`, `--chat-font-size`, `--chat-radius` and `--chat-density` (a factor for
+spacing); an unset one keeps House's light or dark look. `mountChat(element, { client })`
+places it outside React, with `update(props)` and `unmount()`.
 
 Mix `ChatMessageList` (`components` takes your `UserMessage` and `AssistantMessage`),
 `ChatInput` and `ChatQuestionCard` with your own design inside a `ChatProvider`, or
-compose assistant-ui's primitives there; `useChat()` gives `send`, the conversations,
-the Agents, questions to `answer`, `options` to `choose`, `commands`, the queue to
-`edit` or `unqueue`, `stop`, `kill` and outcomes; never replace its messages, sending or
-store. A secret question is never answered here; typed answers live in Presentation
-State's `typed` key: keep it, and change Presentation State only inside `inTurn(client,
-work)` from `@agentshouse/mdruntime/client`. `Markdown` draws Markdown safely.
-
-## What an agent must never do
-
-An agent must never read the authorization, load code from a Room, call the Provider
-directly, or rebase a refused Change Batch.
+compose assistant-ui's primitives there; `useChat()` gives `send`, the conversations, the
+Agents, questions to `answer`, `options` to `choose`, `commands`, the queue to `edit` or
+`unqueue`, `stop`, `kill` and outcomes; never replace its messages, sending or store. It
+shows a conversation's latest 50 messages, and assistant-ui's `loadEarlier()` the 50
+before, which `ChatMessageList` calls as the reader scrolls back. A secret question is
+never answered here; typed answers live in the Presentation State members named `typed:…`:
+leave them. `Markdown` draws Markdown safely.