@agentshouse/mdruntime 0.1.0-c104334047dfe → 0.1.0-c12088a8282f7

package/AGENTS.md

@@ -5,8 +5,8 @@ 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.
@@ -35,9 +35,8 @@ only in memory, what the Provider streams whether or not anything views it: the
 `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 message that
-came back ahead of the chat draft as it stands, its text on a line before and its files
-first, so what another tab typed meanwhile stays: never write back a draft read before; sending it is a Provider Action that needs the Provider
+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,
@@ -53,32 +52,34 @@ 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
+revision, path, 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.
+answers a pending record's saved bytes, or an accepted one's or a History revision's, a
+removed file's last included: the first read asks the Provider and the browser keeps the
+bytes, and every later read of that revision, offline too, answers them from the browser.
+Text names a file only by a link to its Path. A read answers
+`{ kind: 'binary', stream, byteLength, mediaType }`, the bytes a `ReadableStream`
+of parts of at most a mebibyte, or a refusal or failure; read the stream to its end, or
+take it whole with `new Response(stream).blob()` where a screen needs one `Blob`.
 
 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.
+network; History, a binary file read the browser does not keep yet 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
+author, `{ kind: 'user', id }` or `{ kind: 'site' | 'inbox', 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.
+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,
@@ -102,8 +103,8 @@ named; signing out answers `null`, then ends the observation with the authorizat
 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 or prepared, `[{ room, awaits }]`: never read it as empty, draw it
-as loading and observe the query to hear the complete answer. A query is data:
+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`
@@ -120,36 +121,41 @@ as loading and observe the query to hear the complete answer. A query is data:
   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.
+- **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 `cross_room` reference 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`, `change` and `fileId`, where `fields` is `'all'`
+  `preamble`, `markdown`, `backlinks`, `change`, `fileId` and `revision`, 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
+  returns only Room, Path and a selected `fileId` and `revision`, a binary Path entry its `binaryFile`
+  record too, and a YAML file under `settings/` its text as a selected `markdown`, kept
+  out of Search. An unselected part is absent. Select only what a screen shows: a list
+  that selects the Markdown hears every edit of it.
+- **Change, file ID and revision.** `change` is `{ author, time }` of the Document's head revision
+  as the Provider last delivered it: `author` is `{ kind: 'user' | 'site' | 'inbox', 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`.
+  is Accepted. `revision` is the Provider's head revision, `null` for an unsent creation or edit,
+  and moves with an unsent move. A Room's last change is its Document with the latest `time`.
+- **Order and groups.** `orderBy` sorts by `room`, `path`, `type`, `folder` or `{ field }`: missing
+  and null first, last with `nulls: 'last'`, then numbers and booleans, then text by `locale` or
+  code point with `stringSort: 'lexical'`, then lists item by item; 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
@@ -159,50 +165,59 @@ as loading and observe the query to hear the complete answer. A query is data:
 ## Local Search rules
 
 `search({ text, documents, collection, conversations, limit, after, total })` answers
-once, by words, from local state, with MiniSearch's defaults. There is no observed search.
+once, by words, from the full-text index the browser keeps with its local state, so it
+answers at once after a reload. 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`.
+- **Declaration.** Only an App whose release declares Local Search searches; 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.
+  a chat draft or a running turn's parts. Any word found ranks a hit, more found rank it
+  higher, and adjacent words higher still; case and the marks of Latin, Greek and
+  Cyrillic letters fold, English word forms stem, the last word also matches as the start
+  of a word unless the text ends with a space, and Chinese, Japanese, Korean and Thai text
+  matches by character pairs. There is no typo tolerance and no operator syntax.
 - **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.
+  both lists. `total: true` adds `total`, each list's count. A word in very many Documents
+  ranks among a bounded set of them, the Documents of a rarer word of the search always
+  among them.
 - **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`, 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 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`, 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 word of the search
+  to the parts it was found in: `fields`, `sections`, `preamble`, `path` or `text`. A hit
+  whose words were found carries `snippet: { part, text, at }`: the part's text around
+  the first word found, at most 80 characters on either side, and `at` that word's start
+  and end in `text`. Mark the words you show. A bad filter fails as a query does.
 
 ## Room Draft, Save, and outcome rules
 
 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 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.
+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. 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. `saveParts(room, [{ path, parts }])` saves
-parts, each Path once and each new part with its base, the same way without any Room
-Draft: one held at a saved Path stays as it is, and one held at a Path it moves moves with
-it to a destination that holds none. Save a change that is not a Room Draft with it, never
-by reading the Room Draft at that Path and writing it back.
+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.
@@ -212,24 +227,23 @@ Provider's structured refusal code and fields as returned, not known to have app
 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 the Provider marks 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`,
-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 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.
+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`, 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 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 code and bound Rooms are held
+locally (`ready`), each Room's state, each refused Room's file and rule, the persistence answer, `space`
+(`full` once the device's storage refused a write, Save and messages refusing as `durable-write` until
+`retry()` or a later test write finds space, or once the origin refused a newer release), and the
+`installation`'s Rooms, parts, bytes, `received`, `step` and `paused`.
 
 ## Content safety and launch promises
 
@@ -270,13 +284,10 @@ peer dependency. `useObserve(client, topic, ...input)` takes the arguments of `o
 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 each Path's parts, each new part naming its base, through
-`saveParts(room, [{ path, parts }])`: it writes no Room Draft, so one another tab holds
-at that Path stays as it is and one at a Path it moves moves with it, a refused Save
-changes nothing, and a failure is recorded and rejects. `saveWritten(room, roomDrafts)`
-saves Room Drafts the App wrote itself, each named with the revision its last write returned: one another tab wrote since
-is refused as `stale`, and nothing is saved. A react-admin or Refine App uses the data
-providers of `@agentshouse/mdruntime-families`.
+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
 
@@ -298,8 +309,9 @@ Mix `ChatMessageList` (`components` takes your `UserMessage` and `AssistantMessa
 `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. 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.
+`unqueue`, `stop`, `kill`, `renew`, which starts a new chat with the same Agent in place
+of a conversation whose session could not resume, 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.

package/README.md

@@ -12,14 +12,15 @@ npm install @agentshouse/mdruntime
 
 ## Entries
 
-| Entry                           | For                                                         |
-| ------------------------------- | ----------------------------------------------------------- |
-| `@agentshouse/mdruntime/client` | The host's client: `connectMdRuntime(port)`                 |
-| `@agentshouse/mdruntime/host`   | The host that serves a Runtime: `serveMdRuntime`            |
-| `@agentshouse/mdruntime`        | Shared types                                                |
-| `@agentshouse/mdruntime/memory` | Tests: `createMemoryAdapter`, an in-memory Adapter          |
-| `@agentshouse/mdruntime/react`  | React over the client: `useObserve`, `useSave`              |
-| `@agentshouse/mdruntime/chat`   | The Chat: `Chat`, `mountChat`, its parts and `ChatProvider` |
+| Entry                           | For                                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------------------- |
+| `@agentshouse/mdruntime/client` | The host's client: `connectMdRuntime(port)`                                         |
+| `@agentshouse/mdruntime/host`   | The host that serves a Runtime: `serveMdRuntime`                                    |
+| `@agentshouse/mdruntime`        | Shared types                                                                        |
+| `@agentshouse/mdruntime/memory` | Tests: `createMemoryAdapter`, an in-memory Adapter                                  |
+| `@agentshouse/mdruntime/tables` | The host's database: the Authored store's and opened files' tables, `answerRuntime` |
+| `@agentshouse/mdruntime/react`  | React over the client: `useObserve`, `useSave`                                      |
+| `@agentshouse/mdruntime/chat`   | The Chat: `Chat`, `mountChat`, its parts and `ChatProvider`                         |
 
 ## Usage
 

package/dist/adapter.d.ts

@@ -10,14 +10,13 @@ export type TypedSelection = {
     roots: readonly string[];
 };
 export type OperationScopes = {
-    read: readonly string[];
-    sync: readonly string[];
     write: readonly string[];
     delete: readonly string[];
 };
 export type ReplicaAdmission = {
     selection: string;
     admission: Open<'admitted' | 'unavailable'>;
+    offline: Open<'locked' | 'open'>;
 };
 export type DiscoveredRoom = {
     name: string;
@@ -49,8 +48,9 @@ export type ListedConversation = {
     created: string;
     finished: string | null;
     outcome: string | null;
+    waiting: boolean;
 };
-export type ConversationAction = 'conversation.create' | 'conversation.send' | 'conversation.answer' | 'conversation.interrupt' | 'conversation.kill' | 'conversation.cancel' | 'conversation.delete' | 'conversation.history';
+export type ConversationAction = 'conversation.create' | 'conversation.send' | 'conversation.attach' | 'conversation.answer' | 'conversation.interrupt' | 'conversation.kill' | 'conversation.cancel' | 'conversation.delete' | 'conversation.history';
 export type ConversationMessage = {
     identity: string;
     turn: string;
@@ -162,6 +162,18 @@ export type ConversationEvent = {
     kind: 'options';
     conversation: string;
     options: readonly SessionOption[];
+} | {
+    kind: 'starting';
+    conversation: string;
+    step: string | null;
+} | {
+    kind: 'link';
+    conversation: string;
+    connected: boolean;
+} | {
+    kind: 'deliveries';
+    conversation: string;
+    unknown: readonly string[];
 } | {
     kind: 'accepted-message';
     conversation: string;
@@ -187,6 +199,7 @@ export type ActionDeclaration = {
     name: string;
     inputShape: unknown;
     resultKind: unknown;
+    room?: string;
 };
 export type ProviderLimit = {
     name: string;
@@ -233,7 +246,7 @@ export type ProviderRefusal = {
 export type ScopedRefusal = ProviderRefusal & {
     kind: 'scoped-refusal';
     locator: string;
-    scope: Open<'content' | 'sync' | 'model' | 'operation' | 'undisclosed'>;
+    scope: Open<'content' | 'model' | 'operation' | 'undisclosed'>;
 };
 export type AdapterFailure = TransportUncertainty | RoomNotReadable | RevokedAuthorization | ScopedRefusal;
 export type ContractUnavailable = ProviderRefusal & {
@@ -242,7 +255,7 @@ export type ContractUnavailable = ProviderRefusal & {
 export type DiscoverResult = Discovery | TransportUncertainty | RevokedAuthorization | ContractUnavailable;
 export type PageToken = string;
 export type ChangeAuthor = {
-    kind: Open<'user' | 'site'>;
+    kind: Open<'user' | 'site' | 'inbox'>;
     id: string;
     name: string;
 };
@@ -256,20 +269,32 @@ export type HeadChange = {
     time: string;
 };
 export type BinaryFile = {
-    fileRef: string;
     byteLength: number;
     mediaType: string;
     sha256: string;
 };
+export type HeldFile = {
+    readonly path: string;
+    readonly revision: string;
+};
 export type HeldContent = {
-    documents: Readonly<Record<string, string>>;
-    revisions: Readonly<Record<string, string>>;
+    files(after: string | null, limit: number): Promise<readonly HeldFile[]>;
+    contents(paths: readonly string[]): Promise<ReadonlyMap<string, {
+        readonly content: string;
+        readonly revision: string;
+    }>>;
 };
 export type BootstrapRequest = {
     locator: string;
     selection: string;
     pageToken?: PageToken;
     held?: HeldContent;
+    received?: Uint8Array;
+    arriving?: (bytes: number) => void;
+};
+export type BootstrapInventory = {
+    readonly parts: number;
+    readonly bytes: number;
 };
 export type RoomModels = {
     collection?: ModelResult;
@@ -284,7 +309,10 @@ export type BootstrapPage = {
     fileIds?: Readonly<Record<string, string>>;
     changes: Readonly<Record<string, HeadChange>>;
     binaryFiles: Readonly<Record<string, BinaryFile>>;
+    folders?: readonly string[];
     pageToken?: PageToken;
+    inventory?: BootstrapInventory;
+    received?: Uint8Array;
 };
 export type BootstrapResult = BootstrapPage | {
     kind: 'beyond-horizon';
@@ -305,6 +333,8 @@ export type RefreshPage = {
     changes: Readonly<Record<string, HeadChange>>;
     binaryFiles: Readonly<Record<string, BinaryFile>>;
     removals: readonly string[];
+    folders?: readonly string[];
+    folderRemovals?: readonly string[];
     pageToken?: PageToken;
 };
 export type RefreshResult = {
@@ -315,6 +345,7 @@ export type RefreshResult = {
 export type MutationRequest = {
     locator: string;
     changeBatch: ChangeBatch;
+    file(localId: string): Promise<Blob>;
     upload?: unknown;
 };
 export type RetryableRefusal = ProviderRefusal & {
@@ -325,8 +356,7 @@ export type ServiceMode = Open<'open' | 'write-halted'>;
 export type ServiceModeSignal = {
     observe(notify: (mode: ServiceMode) => void): () => void;
 };
-export type MutationResult = {
-    kind: 'accepted';
+export type AcceptedRoom = {
     roomVersion: string;
     documents: Readonly<Record<string, string>>;
     revisions: Readonly<Record<string, string>>;
@@ -334,9 +364,13 @@ export type MutationResult = {
     changes: Readonly<Record<string, HeadChange>>;
     removals: readonly string[];
     binaryFiles?: Readonly<Record<string, BinaryFile>>;
+};
+export type MutationResult = (AcceptedRoom & {
+    kind: 'accepted';
     author?: string;
     time?: string;
-} | (ProviderRefusal & {
+    destination?: AcceptedRoom;
+}) | (ProviderRefusal & {
     kind: 'conflicted';
     roomVersion?: string;
     affected: Readonly<Record<string, string>>;
@@ -353,7 +387,7 @@ export type HistoryAuthor = {
     kind: 'user';
     id: string;
 } | {
-    kind: 'site';
+    kind: 'site' | 'inbox';
     id: string;
     name: string;
 };
@@ -385,22 +419,12 @@ export type BinaryRequest = {
     locator: string;
     path: string;
     revision: string;
-    fileRef?: string;
-} | {
-    kind: 'reference';
-    fileRef: string;
-    referrer: unknown;
-};
-export type ReferrerScope = {
-    kind: 'room';
-    locator: string;
-    path?: string;
-} | {
-    kind: 'conversations';
 };
 export type BinaryResult = {
     kind: 'binary';
-    blob: Blob;
+    body: ReadableStream<Uint8Array>;
+    mediaType: string;
+    sha256?: string;
 } | (ProviderRefusal & {
     kind: 'rejected';
 }) | AdapterFailure;
@@ -429,9 +453,8 @@ export type ActionResult = {
 export type HeldRoom = {
     locator: string;
     roomVersion: string;
-    documents: Readonly<Record<string, string>>;
-    revisions: Readonly<Record<string, string>>;
 };
+export type HeldRevisions = (locator: string, paths: readonly string[]) => Promise<ReadonlyMap<string, string>>;
 export type RoomStreamEvent = {
     kind: 'opened';
 } | {
@@ -462,19 +485,16 @@ export type StreamReceipts = {
     }): Promise<void>;
     drop(keys: readonly string[]): Promise<void>;
 };
-export type AcquiredDemand = {
-    rooms: readonly string[];
-    conversations: boolean;
-};
 export type RoomStream = {
-    hold(rooms: readonly HeldRoom[], demand: AcquiredDemand | null): void;
+    hold(rooms: readonly HeldRoom[]): void;
     reopen(): void;
     published(locator: string, roomVersion: string): void;
-    observe(notify: (event: RoomStreamEvent) => void, receipts: StreamReceipts): () => void;
+    observe(notify: (event: RoomStreamEvent) => void, receipts: StreamReceipts, revisions: HeldRevisions): () => void;
 };
 export type Adapter = {
     readonly localSaves?: true;
     readonly exhaustiveDiscovery?: true;
+    readonly roomTypes?: string;
     authorize(): Promise<Authorization>;
     discover(authorization: Authorization, scope?: DiscoveryScope): Promise<DiscoverResult>;
     bootstrap(authorization: Authorization, request: BootstrapRequest): Promise<BootstrapResult>;
@@ -482,10 +502,7 @@ export type Adapter = {
     mutate(authorization: Authorization, request: MutationRequest, keep: (upload: unknown) => Promise<void>): Promise<MutationResult>;
     history(authorization: Authorization, request: HistoryRequest): Promise<HistoryResult>;
     binary(authorization: Authorization, request: BinaryRequest): Promise<BinaryResult>;
-    link(authorization: Authorization, request: Extract<BinaryRequest, {
-        kind: 'path';
-    }>): Promise<BinaryLinkResult>;
-    referrerScope(referrer: unknown): ReferrerScope | null;
+    link(authorization: Authorization, request: BinaryRequest): Promise<BinaryLinkResult>;
     action(authorization: Authorization, request: ActionRequest): Promise<ActionResult>;
     reached(locator: string, roomVersion: string, target: string): boolean;
     follows(locator: string, roomVersion: string, next: string): boolean;