agentic-documents 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.2.0
+
+### Breaking changes
+
+- **Worker deployments from the repo template.** `wrangler.jsonc` now sets `main` to
+  `src/live-worker.ts`. To host live rooms, add the `SYNC_ROOM` Durable Object binding and the `v1`
+  migration (`new_sqlite_classes`). Without the binding, the room routes fail with `MISCONFIGURED`.
+  The published package does not include `wrangler.jsonc`.
+- **Token table.** An `AGENTIC_DOCS_TOKENS` entry in object form may now carry a `role`. A `role` that
+  is not `editor` or `viewer` refuses the whole token table, so a typo never leaves a token live with
+  the wrong role. Entries with no `role` stay editors, as before.
+- **Dependencies.** `agentic-identity` moves from `^0.2.0` to `^0.3.0`.
+
+### Added
+
+- Live rooms. Several people and agents edit one document at the same time. Import `LiveDoc` from
+  `agentic-documents/live`. Deploy `agentic-documents/live-worker` to host the rooms.
+- The `agentic-realtime` dependency (`^0.1.0`, the version on npm) for the live rooms.
+- `--live <url>` on the CLI and the MCP server, or `AGENTIC_DOCS_LIVE_URL`. Set `AGENTIC_DOCS_TOKEN`
+  to join a room. The server sets the author kind and the role from the token.
+- With `--live`, the CLI refuses `--as`, `--scopes`, and `--dir`, and exits 2. The server sets these
+  from the token.
+- A `viewer` role. A viewer reads and cannot write, over HTTP or in a live room. The default role is
+  `editor`.
+- Worker routes for live rooms: `GET /api/v1/me`, `GET /api/v1/docs/:id/room`,
+  `GET /api/v1/docs/:id/ws`, `GET /api/v1/docs/:id/state`, and `POST /api/v1/docs/:id/checkpoint`.
+- Live rooms save through the shared `Store` and `Blobs` ports. A stored document too big for a room
+  fails the join with a clear error.
+- `npm pack` and `npm publish` build `dist/` first (`prepack`).
+
+## 0.1.0
+
+- First release. The document model, the Markdown and ODT export, the text operations, the CLI, the
+  MCP server, and the Worker HTTP API.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pooria Arab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# agentic-documents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/agentic-documents)](https://www.npmjs.com/package/agentic-documents)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/license/mit)
+
+[Package](https://www.npmjs.com/package/agentic-documents) · [Source](https://github.com/pooriaarab/agentic-documents) · [Support](https://github.com/pooriaarab/agentic-documents/issues)
+
+Write documents with people and agents in real time.
+
+> Status: early, version 0.2.0. The document model, the text operations, the CLI, the MCP server,
+> the Worker API, and live editing in a room work. The web UI is not built yet.
+
+## Install
+
+```sh
+npm install agentic-documents
+```
+
+## Quick start
+
+```ts
+import { AgenticDoc, Suggestions, Threads } from "agentic-documents";
+
+const agent = { kind: "agent_of_human", name: "scribe" } as const;
+
+const doc = AgenticDoc.fromMarkdown("# Plan\n\nShip on Friday.", agent);
+const [plan] = doc.outline();
+
+doc.replace({ text: "Friday" }, "Monday", agent);
+doc.insert({ section: plan.id, at: "end" }, "- [ ] Write notes", agent);
+
+console.log(doc.toMarkdown());
+console.log(doc.edits()); // each edit keeps the author kind and name
+
+const person = { kind: "human", name: "Ada" } as const;
+const suggestions = new Suggestions(doc);
+const id = suggestions.add({ text: "Monday" }, "Tuesday", agent);
+suggestions.accept(id, person); // the text changes now
+new Threads(doc).add({ text: "Tuesday" }, "Is this date firm?", agent);
+```
+
+## CLI
+
+Every change needs an author: `--as <kind>:<name>` or `AGENTIC_DOCS_AS`. An agent that may accept
+suggestions also needs `--scopes docs:accept` (or `AGENTIC_DOCS_SCOPES`). Documents live in
+`--dir` (or `AGENTIC_DOCS_DIR`, default `.agentic-documents`) as Yjs update files.
+
+```sh
+export AGENTIC_DOCS_AS=agent_of_human:scribe
+printf '# Plan\n\nShip on Friday.\n' > plan.md
+npx agentic-documents new plan --file plan.md
+npx agentic-documents outline plan
+npx agentic-documents replace plan --text Friday --content Monday
+npx agentic-documents suggest plan --text Monday --replacement Tuesday
+npx agentic-documents comment plan --text Monday --body "Is this date firm?"
+npx agentic-documents export plan --format md --out plan.md
+npx agentic-documents export plan --format odt --out plan.odt   # OpenDocument text
+```
+
+Run `npx agentic-documents --help` for every command.
+
+## MCP
+
+`npx agentic-documents mcp --as agent_of_human:claude` starts a stdio server. It has one tool
+per command, named `doc_<command>` (`doc_read`, `doc_replace`, `doc_suggest`, and so on). The
+author is fixed when the server starts. A tool call cannot pick another author.
+
+## HTTP API
+
+A Cloudflare Worker (Hono) mirrors the CLI one to one under `/api/v1/docs`. A read command is a
+`GET` (flags are query parameters). A write command is a `POST` (flags are the JSON body).
+
+```sh
+curl -X POST $URL/api/v1/docs -H "authorization: Bearer $TOKEN" -d '{"id":"plan","markdown":"# Plan"}'
+curl "$URL/api/v1/docs/plan/outline" -H "authorization: Bearer $TOKEN"
+curl -X POST $URL/api/v1/docs/plan/replace -H "authorization: Bearer $TOKEN" -d '{"text":"Plan","content":"Roadmap"}'
+curl "$URL/api/v1/docs/plan/export?format=html" -H "authorization: Bearer $TOKEN"
+# add &remoteImages=true to keep web images; the default shows only images stored inside the document
+```
+
+- Each token stands for one author. Set `AGENTIC_DOCS_TOKENS` as a secret:
+  `wrangler secret put AGENTIC_DOCS_TOKENS`. The value is a JSON object from token to author:
+  `{"<32 or more random bytes>":"agent_of_human:scribe"}`. To give an agent the right to accept
+  suggestions, use `{"as":"agent_of_human:approver","scopes":["docs:accept"]}` as the value.
+  Make a token with `openssl rand -hex 32`.
+- A token under 32 bytes, a value that is not a valid author, or a value that is not a JSON
+  object makes the Worker refuse every request (401). It logs the reason once, never the token.
+  A body cannot name its own author. With no tokens the API refuses every request.
+- Errors are `{ "error": { "code", "message", "matches" } }`. Status: 400 bad input, 401 no
+  valid token, 403 `FORBIDDEN` (for example an agent without `docs:accept` that accepts), 404 not
+  found, 409 a conflict (ambiguous match, stale anchor, already decided), 503 `LOCKED`.
+- `GET /health` needs no token. It reveals nothing else.
+- Create an R2 bucket with `wrangler r2 bucket create agentic-documents-data --jurisdiction eu` and a D1
+  database with `wrangler d1 create agentic-documents --jurisdiction eu`. Put the database id in
+  `wrangler.jsonc`. Set `AGENTIC_DOCS_REGION` to `eu` or `us`. It is a claim that you make: it has no
+  default, and the Worker answers 500 `MISCONFIGURED` without it. Local D1 reports no region, so under
+  `wrangler dev` only, add `--var AGENTIC_DOCS_REGION:unknown --var AGENTIC_DOCS_UNSAFE_REGION:1`. That turns the
+  residency check off.
+- Run it locally with `npx wrangler dev`. Set `WRANGLER_SEND_METRICS=false` to turn off wrangler telemetry.
+
+## Features
+
+- A Yjs document that a Tiptap editor can open. It uses the y-prosemirror layout.
+- Headings, paragraphs, lists, task lists, tables, code, images, links, and marks.
+- Markdown in and out.
+- An outline. Each section has an id that stays the same when people edit around it. Blocks before the
+  first heading are the `preamble` section (level 0). It is listed when they exist, and it is always a
+  valid target. A replace or delete on it has no heading to keep.
+- Insert, replace, and delete by section id or by exact text. Append to the end.
+- Text anchors that follow their text when other replicas edit.
+- Clear errors: `NO_MATCH`, `AMBIGUOUS_MATCH`, `STALE_ANCHOR`, `NO_SECTION`, `FORBIDDEN`.
+- Comment threads on text, with replies and resolve. A thread follows its text.
+- Suggested edits (insert, replace, delete). Nothing changes until a person accepts.
+  An accepted edit is logged with the accepter as editor and the suggester as origin.
+- Who may decide: a `human` or a `user_token` who is not the suggester. An agent cannot accept
+  unless its principal carries the `docs:accept` scope. Nobody accepts their own suggestion.
+  A person can withdraw their own suggestion. An agent can never accept or reject its own. Other
+  deciders get `FORBIDDEN`. Accepting an accepted
+  suggestion changes nothing. Editor roles come with `agentic-identity`.
+- Two replicas can accept one suggestion before they meet. After the merge every replica keeps
+  one application and undoes the other, so the text and the edit log hold it once. An accept
+  beats a reject made at the same moment.
+- Export to ODT (OpenDocument text): headings, paragraphs, bold, italic, strike, code, links, lists,
+  quotes, rules, tables, and images as embedded files. The package follows ODF 1.3 with the mimetype
+  stored first. The CLI and the API send the file bytes. LibreOffice opens it, lists keep their
+  numbers, and its own re-save reads back to the same Markdown (checked by hand with LibreOffice 24.8
+  in the PR that added it).
+- Export to Markdown and to self-contained HTML. The HTML loads nothing from other hosts. An image
+  stored in the document as a `data:` URI (PNG, JPEG, GIF, or WebP) shows. Any other image becomes
+  its alt text, because a remote image tells its host who opened the file. `remoteImages` turns
+  that back on.
+- Every edit, message, and suggestion needs an author. The edit log keeps the kind and the name, so
+  agent work stays labeled. The log holds no content. Over the CLI, MCP, and HTTP the server or
+  the operator sets the author. In a live room a client writes its own log entries, suggestion decisions, and
+  threads. A save merges them into the stored document. So after a live client saves, treat all three
+  as advisory. The room's own record of who sent updates in the room is at `GET /api/v1/docs/:id/room`. It does not cover
+  text written over HTTP, the CLI, or MCP before the room opened: the client that seeds the room appears there.
+
+## Live editing
+
+A person and an agent can edit one document at the same time. Each sees the other's changes. The Worker
+hosts one room per document, on a Durable Object, through [agentic-realtime](https://www.npmjs.com/package/agentic-realtime).
+Deploy `agentic-documents/live-worker`. The sample `wrangler.jsonc` binds `SYNC_ROOM` and sets the migration.
+
+```ts
+import { LiveDoc } from "agentic-documents/live";
+
+const live = await LiveDoc.join({ server: "https://docs.example.com", id: "plan", token });
+await live.edit((doc, author) => doc.append("Ship on Friday.", author));
+console.log(live.peers); // the other people and agents. `machine` is true for an agent.
+await live.save(); // write the room state to the stored document
+await live.leave();
+```
+
+The CLI and the MCP server join rooms too. Every command then runs in the room and saves:
+
+```sh
+export AGENTIC_DOCS_TOKEN=...   # a bearer token. The server sets the author kind and the role.
+export AGENTIC_DOCS_LIVE_URL=https://docs.example.com   # or pass --live <url>
+npx agentic-documents append plan --content "Ship on Friday." --live https://docs.example.com
+npx agentic-documents mcp --live https://docs.example.com
+```
+
+- The server reads your author kind and role from the token (`GET /api/v1/me`). An agent token writes
+  agent edits. `--as`, `--scopes`, and `--dir` do not apply with `--live`: the CLI refuses them and exits 2. This
+  holds when `AGENTIC_DOCS_LIVE_URL` is set too, so unset it for a local call.
+- A room starts from the stored document. `save` merges the room back into the stored document, so
+  `read`, `export`, and the other commands see live edits. A save also creates a document that has none.
+  The CLI and MCP server save after each change. If a save fails, the room keeps the change and the error says so: do not repeat it. `new` makes the document in the store, and a room picks it up on the next join. A document over 1,000,000 bytes cannot open in a room or be saved from one. A save refuses an update with a wrong
+  kind of content or a malformed thread, suggestion, or log entry. HTTP edits reach an open room only when a client joins and seeds it.
+- A `viewer` token joins and reads. The room drops its updates, and `edit` and `save` fail with `FORBIDDEN`.
+  Set a role in `AGENTIC_DOCS_TOKENS` with `{ "as": "human:Vic", "role": "viewer" }`. A token with no role is an editor.
+- `GET /api/v1/docs/:id/room` lists who sent updates in the room, and whether each is machine-made.
+- Pass `reconnect: {}` to `join` to keep trying after a drop. Edits made offline merge on return.
+  A room that restarts recovers its state from the Durable Object.
+
+Limits of live editing:
+
+- The edit log, the suggestion decisions, and the threads live in the document, and a client writes them.
+  A modified client can write a log entry with another author, or accept its own suggestion. The room's
+  list at `/room` is the record to trust for who sent updates. It does not cover text written before the
+  room opened.
+- Until a client saves, a command over HTTP reads the stored copy, not the room.
+- After the room refuses an edit, the local copy of `LiveDoc` still holds it. Join again.
+- Durable Objects have no US jurisdiction. With the region `us` a room sits near the first client that opens it.
+  With `eu` it stays in the EU. The local `wrangler dev` cannot place rooms.
+
+## Rules for text matching
+
+- A match is exact and case sensitive.
+- A match stays inside one block. It cannot cross a paragraph, a cell, or a hard break.
+- More than one match is an error, and matches may overlap: `ana` matches twice in `banana`. Pass `occurrence` (1 is the first start) to choose.
+- A replacement takes the marks of the first matched character.
+
+## Limits
+
+- No web UI yet.
+- The Worker keeps each document in R2 and a catalog (who made it, and when) in D1. Both come from the
+  shared `agentic-identity` ports. A save is conditional on the version it read, so two writers cannot
+  overwrite each other. The CLI and MCP server keep the same data in local files.
+- The CLI and MCP server keep files under `<dir>/blobs` and `<dir>/store`. Files from an older release that sit
+  directly in `<dir>` are not read.
+- Token auth is a stopgap until the `Auth` port exists. A token has one role for the whole server: `editor` (the default) or `viewer`. A viewer cannot call a write command or write in a live room. There is no per-document sharing yet.
+- A save is a compare-and-set. The file store takes a lock file, checks the version, and renames a
+  uniquely named temp file into place. A writer that loses loads the document again and runs
+  its change again. A lock older than 10 seconds counts as dead and is taken over. A lock that
+  cannot be read, or that is dated in the future, counts as live. A writer that waits more than
+  5 seconds fails with `LOCKED`. A writer that loses 64 times in a row fails with `CONFLICT`. The lock
+  is for one machine. Two machines on a network file system need a store with its own
+  conditional write.
+- `--as` and `AGENTIC_DOCS_AS` are self-declared labels. The CLI does not prove who runs it, so
+  `--as human:Ada` labels work as human on any machine that can run the command. Only the HTTP API
+  (tokens) and an MCP server that a trusted host starts fix the author for the caller.
+- Suggestions work on text, not on whole sections.
+- A scope on a principal is trusted as given. Nothing here proves who a caller is.
+- Export covers Markdown, HTML, and ODT. DOCX export, and ODT and DOCX import, are planned.
+- ODT export: comments and suggestions are not written. A code block loses its language. A table
+  cell span is not written (the model has none yet). A task list becomes a bullet list that starts each
+  item with `☐` or `☑`. A remote image is not linked, because an office program would ask its host
+  for it when the file opens. It becomes its alt text.
+- Markdown with footnotes, or any syntax the model has no place for, is refused with
+  `INVALID_INPUT`. Nothing is stored. Reference links and image references are resolved to
+  their URL. An unused reference definition is dropped.
+- Markdown import drops link titles, table column alignment, and the part of a code fence
+  line after the language.
+- Markdown output trims whitespace at the edge of a block and skips empty paragraphs. A text
+  target that includes a trailing space can match in the document and not in `read` output.
+
+## Develop
+
+```sh
+npm ci
+npm run ci:local
+```
+
+## License
+
+MIT.

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security policy
+
+## Report a vulnerability
+
+Do not open a public issue for a security problem. Report it in private with
+GitHub security advisories:
+https://github.com/pooriaarab/agentic-documents/security/advisories/new
+
+Include the version (`npm ls agentic-documents`), the steps to reproduce, and the
+impact you expect. We aim to reply within 7 days.
+
+## Supported versions
+
+Only the latest published version gets fixes.
+
+## Scope
+
+In scope: the package code (the SDK, CLI, MCP server, and Worker API) and the
+export formats it writes.
+
+Out of scope: a deployment that sets its own tokens or region without following
+the README, and a self-declared `--as` label on the CLI. The README says that
+label is not proof of identity.

package/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: agentic-documents
+description: Read and edit rich-text documents by section or exact text, as Markdown, with every edit labeled by author. Keywords: documents,editor,rich-text,tiptap,yjs,agents.
+---
+
+# agentic-documents
+
+Write documents with people and agents in real time.
+
+## Use the SDK
+
+```ts
+import { AgenticDoc } from "agentic-documents";
+
+const me = { kind: "agent_of_human", name: "scribe" } as const;
+const doc = AgenticDoc.fromMarkdown("# Plan\n\nShip on Friday.", me);
+doc.replace({ text: "Friday" }, "Monday", me);
+doc.toMarkdown();
+```
+
+## Use the CLI or MCP
+
+```sh
+agentic-documents outline plan --as agent_of_human:scribe
+agentic-documents mcp --as agent_of_human:scribe
+```
+
+Tools are named `doc_<command>`: `doc_read`, `doc_outline`, `doc_replace`, `doc_suggest`.
+
+## Rules
+
+- Pass your author kind and name on every change.
+- Read the outline, then the section, before you edit.
+- On an ambiguous match, pass `occurrence`.
+- Report errors as failures.

package/dist/chunk-5Y66UCTE.js

@@ -0,0 +1,7 @@
+// src/version.ts
+import { createRequire } from "module";
+var VERSION = createRequire(import.meta.url)("../package.json").version;
+
+export {
+  VERSION
+};

package/dist/chunk-FZA5LQV3.js

@@ -0,0 +1,150 @@
+import {
+  AgenticDoc,
+  DocError,
+  PRINCIPAL_KINDS,
+  Suggestions,
+  Threads
+} from "./chunk-YBBQNCMC.js";
+
+// src/service.ts
+import * as Y from "yjs";
+var ATTEMPTS = 64;
+var ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var CATALOG = "documents";
+var MAX_LIVE_BYTES = 1e6;
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isString = (v) => typeof v === "string";
+var isWho = (v) => isObject(v) && PRINCIPAL_KINDS.includes(v.kind) && isString(v.name) && v.name !== "";
+var isAnchor = (v) => isObject(v) && isString(v.text) && isObject(v.start) && isObject(v.end);
+var ROOTS = /* @__PURE__ */ new Set(["default", "edits", "suggestions", "threads", "applied"]);
+var DocsService = class {
+  constructor(ports, options = {}) {
+    this.options = options;
+    this.blobs = ports.blobs;
+    this.store = ports.store;
+  }
+  options;
+  blobs;
+  store;
+  key(id) {
+    if (!ID.test(id)) throw new DocError("INVALID_INPUT", `invalid document id "${id}": use 1 to 64 of a-z, 0-9, "-" and "_"`);
+    return `${id}.ydoc`;
+  }
+  async create(id, markdown, author) {
+    const key = this.key(id);
+    const created = await this.blobs.put(key, AgenticDoc.fromMarkdown(markdown, author, this.options).encode(), { ifNoneMatch: "*" });
+    if (!created) throw new DocError("DOCUMENT_EXISTS", `document "${id}" already exists`);
+    await this.catalog(id, author);
+  }
+  /** The stored document as a Yjs update. A live client seeds its room from it. */
+  async state(id) {
+    const found = await this.blobs.get(this.key(id));
+    if (!found) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+    return found.data;
+  }
+  /**
+   * Merge a Yjs update from a live room into the stored document, and create the document when it
+   * has none. A merge is safe to repeat and to run in any order. The save is conditional, so two
+   * checkpoints at once both land.
+   */
+  async checkpoint(id, update, author) {
+    const key = this.key(id);
+    const scratch = new Y.Doc();
+    try {
+      Y.applyUpdate(scratch, update);
+    } catch {
+      throw new DocError("INVALID_INPUT", "the update is not a Yjs update");
+    }
+    if (scratch.store.clients.size === 0 || scratch.store.pendingStructs || scratch.store.pendingDs) {
+      throw new DocError("INVALID_INPUT", "the update is empty or lacks the changes it depends on");
+    }
+    for (const root of scratch.share.keys()) if (!ROOTS.has(root)) throw new DocError("INVALID_INPUT", `the update holds a part this package does not use: "${root}"`);
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const found = await this.blobs.get(key);
+      if (!found) {
+        const created = AgenticDoc.fromUpdate(update, this.options);
+        const fresh = this.checked(id, created);
+        this.fits(id, fresh);
+        if (!await this.blobs.put(key, fresh, { ifNoneMatch: "*" })) continue;
+        await this.catalog(id, author);
+        return;
+      }
+      const doc = AgenticDoc.fromUpdate(found.data, this.options);
+      doc.applyUpdate(update);
+      const merged = this.checked(id, doc);
+      this.fits(id, merged);
+      if (await this.blobs.put(key, merged, { ifMatch: found.version })) return;
+    }
+    throw new DocError("CONFLICT", `document "${id}" kept changing; try again`);
+  }
+  /**
+   * The encoded document, once it reads back and every stored entry has the shape the commands rely on. Yjs does not
+   * check types, so an update can put text where the editor expects blocks, or a thread with no messages, and then a
+   * command fails on every later call.
+   */
+  checked(id, doc) {
+    const refuse = (what) => new DocError("INVALID_INPUT", `the update would leave document "${id}" unreadable: ${what}`);
+    try {
+      doc.toMarkdown();
+      if (!doc.edits().every((e) => isObject(e) && isWho(e.author) && isString(e.at) && isString(e.op))) throw refuse("an edit log entry is malformed");
+      for (const [, t] of doc.ydoc.getMap("threads")) {
+        const messages = t instanceof Y.Map ? t.get("messages") : void 0;
+        const ok = t instanceof Y.Map && isAnchor(t.get("anchor")) && ["open", "resolved"].includes(t.get("status")) && messages instanceof Y.Array && messages.length > 0 && messages.toArray().every((m) => isObject(m) && isString(m.id) && isString(m.at) && isString(m.body) && isWho(m.author));
+        if (!ok) throw refuse("a thread is malformed");
+      }
+      for (const [, f] of doc.ydoc.getMap("suggestions")) {
+        const ok = f instanceof Y.Map && ["insert", "replace", "delete"].includes(f.get("kind")) && ["pending", "accepted", "rejected"].includes(f.get("status")) && isAnchor(f.get("anchor")) && isString(f.get("replacement")) && isString(f.get("createdAt")) && isWho(f.get("author"));
+        if (!ok) throw refuse("a suggestion is malformed");
+      }
+      new Suggestions(doc).list();
+      new Threads(doc).list();
+    } catch (error) {
+      throw error instanceof DocError ? error : refuse("a part holds the wrong kind of content");
+    }
+    return doc.encode();
+  }
+  fits(id, state) {
+    if (state.length > MAX_LIVE_BYTES) throw new DocError("INVALID_INPUT", `document "${id}" would pass ${MAX_LIVE_BYTES} bytes, the most a live room takes`);
+  }
+  async catalog(id, author) {
+    await this.store.transaction(async (tx) => {
+      if (await tx.get(CATALOG, id) === null) await tx.put(CATALOG, id, { createdBy: { kind: author.kind, name: author.name }, createdAt: Date.now() });
+    });
+  }
+  /** Who created the document and when, or null when it has no catalog entry (made before the catalog, or a failed catalog write). */
+  async info(id) {
+    this.key(id);
+    const entry = await this.store.get(CATALOG, id);
+    if (entry === null) return null;
+    const { createdBy, createdAt } = entry;
+    if (!createdBy || !PRINCIPAL_KINDS.includes(createdBy.kind) || typeof createdBy.name !== "string" || typeof createdAt !== "number") {
+      throw new DocError("INVALID_INPUT", `the catalog entry for "${id}" is damaged`);
+    }
+    return { createdBy, createdAt };
+  }
+  async read(id, run) {
+    const found = await this.blobs.get(this.key(id));
+    if (!found) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+    return run(AgenticDoc.fromUpdate(found.data, this.options));
+  }
+  /**
+   * Load, run the change, and save only if nobody saved in between. When someone did, load again and
+   * run the change again, so a check such as "is it still pending" sees the new state.
+   */
+  async write(id, run) {
+    const key = this.key(id);
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const found = await this.blobs.get(key);
+      if (!found) throw new DocError("NO_DOCUMENT", `no document with id "${id}"`);
+      const doc = AgenticDoc.fromUpdate(found.data, this.options);
+      const result = run(doc);
+      if (await this.blobs.put(key, doc.encode(), { ifMatch: found.version })) return result;
+    }
+    throw new DocError("CONFLICT", `document "${id}" kept changing; try again`);
+  }
+};
+
+export {
+  MAX_LIVE_BYTES,
+  DocsService
+};