snapback2 0.0.1

package/dist/guide/families.json

@@ -0,0 +1,446 @@
+[
+  {
+    "family": "bound",
+    "code": "E_BOUND_TAKE_REQUIRED",
+    "wrong": "db.scan(todos.byOwner, [ctx.viewer])",
+    "right": "db.scan(todos.byOwner, [ctx.viewer], { take: 50 })"
+  },
+  {
+    "family": "opaque",
+    "code": "E_PROVENANCE_AMBIGUOUS",
+    "wrong": "let key = args.id; key = args.otherId; db.scan(items.byKey, [key], { take: 50 })",
+    "right": "db.scan(items.byKey, [args.id], { take: 50 })"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_TABLE_UNKNOWN",
+    "wrong": "db.get(missing, args.id)",
+    "right": "db.get(todos, args.id)"
+  },
+  {
+    "family": "rule",
+    "code": "E_RULE",
+    "wrong": "insert: rule.deny()",
+    "right": "insert: rule.viewerIs(\"ownerId\")"
+  },
+  {
+    "family": "auth",
+    "code": "E_AUTH_REQUIRED",
+    "wrong": "client.query(api.todos.list, {})",
+    "right": "createClient({ url, as: \"alice\" }).query(api.todos.list, {})"
+  },
+  {
+    "family": "args",
+    "code": "E_ARGS_TYPE",
+    "wrong": "client.query(api.messages.thread, { conversationId: 1 })",
+    "right": "client.query(api.messages.thread, { conversationId: \"conversation-1\", c: null })"
+  },
+  {
+    "family": "op",
+    "code": "E_OP_UNKNOWN",
+    "wrong": "client.query(api.messages.threads, {})",
+    "right": "client.query(api.messages.thread, { conversationId: \"conversation-1\", c: null })"
+  },
+  {
+    "family": "successor",
+    "code": "E_SUCCESSOR_DESTRUCTIVE",
+    "wrong": "remove a populated column and save",
+    "right": "apply the emitted .snapback/migration-<generation>.json plan"
+  },
+  {
+    "family": "effect",
+    "code": "E_EFFECT_GRANT",
+    "wrong": "grants: [] // then fetch an external origin",
+    "right": "grants: [\"https://api.example.com\"]"
+  },
+  {
+    "family": "input",
+    "code": "E_INPUT_TRACE_UNKNOWN",
+    "wrong": "snapback2 trace 999999",
+    "right": "snapback2 trace latest"
+  },
+  {
+    "family": "owner",
+    "code": "E_OWNER_NOT_RUNNING",
+    "wrong": "snapback2 why todos.list --as alice",
+    "right": "snapback2 dev && snapback2 why todos.list --as alice"
+  },
+  {
+    "family": "bound",
+    "code": "E_UNBOUND_SCAN",
+    "wrong": "db.scan(todos.byOwner, [ctx.viewer])",
+    "right": "db.scan(todos.byOwner, [ctx.viewer], { take: 50 })"
+  },
+  {
+    "family": "bound",
+    "code": "E_UNBOUND_LOOP",
+    "wrong": "for (const item of unboundedItems) visit(item)",
+    "right": "for (const item of args.items) visit(item) // args.items declares max"
+  },
+  {
+    "family": "bound",
+    "code": "E_UNBOUND_COUNT",
+    "wrong": "db.scan(todos.byOwner, [ctx.viewer], { take: 50 }).count()",
+    "right": "db.scan(todos.byOwner, [ctx.viewer], { take: 50 }).countCapped()"
+  },
+  {
+    "family": "bound",
+    "code": "E_STRUCTURAL_COUNT",
+    "wrong": "return hiddenRows.countCapped()",
+    "right": "return maintainedVisibleCount"
+  },
+  {
+    "family": "opaque",
+    "code": "E_AMBIENT_TIME",
+    "wrong": "const now = Date.now()",
+    "right": "const now = ctx.now()"
+  },
+  {
+    "family": "opaque",
+    "code": "E_OPAQUE",
+    "wrong": "return unknownLibraryCall(args.id)",
+    "right": "return db.get(todos, args.id)"
+  },
+  {
+    "family": "bound",
+    "code": "E_BOUND",
+    "wrong": "return a program whose certified work exceeds the ceiling",
+    "right": "reduce take/max values until the program fits the certified ceiling"
+  },
+  {
+    "family": "args",
+    "code": "E_ARGS_SPREAD",
+    "wrong": "query({ ...makeArgs() }, handler)",
+    "right": "query({ id: t.id() }, handler)"
+  },
+  {
+    "family": "args",
+    "code": "E_ARGS_DESCRIPTOR",
+    "wrong": "query({ id: String }, handler)",
+    "right": "query({ id: t.id() }, handler)"
+  },
+  {
+    "family": "op",
+    "code": "E_OP_INVALID",
+    "wrong": "export const broken = query({}, () => missingName)",
+    "right": "export const valid = query({}, () => null)"
+  },
+  {
+    "family": "op",
+    "code": "E_OP_NONE",
+    "wrong": "const helper = () => null",
+    "right": "export const operation = query({}, () => null)"
+  },
+  {
+    "family": "op",
+    "code": "E_OP_RESERVED",
+    "wrong": "export const then = query({}, () => null)",
+    "right": "export const next = query({}, () => null)"
+  },
+  {
+    "family": "op",
+    "code": "E_OP_MODULE_BASENAME",
+    "wrong": "snapback/activity.ts and snapback/admin/activity.ts",
+    "right": "snapback/activity.ts and snapback/admin-activity.ts"
+  },
+  {
+    "family": "opaque",
+    "code": "E_DIAG_TRUNCATED",
+    "wrong": "leave more refusals than one check can report",
+    "right": "fix the reported refusals and run snapback2 check again"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_RESERVED",
+    "wrong": "export const _meta = table({ columns: {} })",
+    "right": "export const metadata = table({ columns: {} })"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_ID_RESERVED",
+    "wrong": "table({ columns: { id: t.id() } })",
+    "right": "table({ columns: {} }) // id is implicit"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_UNKNOWN_TABLE",
+    "wrong": "schema({ tables: { missing } })",
+    "right": "schema({ tables: { todos } })"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_INDEX_COLUMN",
+    "wrong": "indexes: { byMissing: { columns: [\"missing\"] } }",
+    "right": "indexes: { byTitle: { columns: [\"title\"] } }"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_INDEX_OPTION",
+    "wrong": "indexes: { byTitle: { columns: [\"title\"], unknown: true } }",
+    "right": "indexes: { byTitle: { columns: [\"title\"], unique: true } }"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_CONSTRAINT",
+    "wrong": "constraints: [{ unique: \"missing\" }]",
+    "right": "constraints: [{ unique: \"byTitle\" }]"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_MAINTAIN",
+    "wrong": "maintains: [{ count: \"missing\", by: [\"ownerId\"], into: \"counts\" }]",
+    "right": "maintains: [{ count: \"todos\", by: [\"ownerId\"], into: \"counts\" }]"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_ASSET_MAINTAIN",
+    "wrong": "maintains: [{ count: \"posts\", by: [\"photo\"], into: \"counts\" }]",
+    "right": "maintains: [{ count: \"posts\", by: [\"ownerId\"], into: \"counts\" }]"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_ASSET_SEED",
+    "wrong": "rows: { profiles: [{ id: \"profile-alice\", avatar: { id: \"asset-1\", width: 100, height: 100 } }] }",
+    "right": "rows: { profiles: [{ id: \"profile-alice\", avatar: null }] }"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_DEFAULT_EXPORT",
+    "wrong": "export const app = schema({ tables: {} })",
+    "right": "export default schema({ tables: {} })"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_COLUMN",
+    "wrong": "columns: { title: t.text() }",
+    "right": "columns: { title: t.text(100) }"
+  },
+  {
+    "family": "schema",
+    "code": "E_SCHEMA_INVALID",
+    "wrong": "export default schema(makeSchema())",
+    "right": "export default schema({ tables: { todos } })"
+  },
+  {
+    "family": "rule",
+    "code": "E_RULE_INVALID",
+    "wrong": "read: customRule()",
+    "right": "read: rule.viewerIs(\"ownerId\")"
+  },
+  {
+    "family": "args",
+    "code": "E_DECIMAL_SCALE",
+    "wrong": "```q\nmutation add():\n  insert prices { amount: 1.234 }\n```",
+    "right": "```q\nmutation add():\n  insert prices { amount: 1.23 }\n```"
+  },
+  {
+    "family": "args",
+    "code": "E_ENUM_VARIANT",
+    "wrong": "status: \"unknown\"",
+    "right": "status: \"open\""
+  },
+  {
+    "family": "input",
+    "code": "E_SEED_INVALID",
+    "wrong": "export default makeSeed()",
+    "right": "export default seed({ personas: [], rows: {} })"
+  },
+  {
+    "family": "input",
+    "code": "E_SEED_PERSONA",
+    "wrong": "personas: [1]",
+    "right": "personas: [\"alice\"]"
+  },
+  {
+    "family": "input",
+    "code": "E_SEED_TABLE",
+    "wrong": "rows: { missing: [] }",
+    "right": "rows: { todos: [] }"
+  },
+  {
+    "family": "input",
+    "code": "E_SEED_ROW",
+    "wrong": "rows: { todos: [null] }",
+    "right": "rows: { todos: [{ id: \"todo-1\", title: \"Ship\" }] }"
+  },
+  {
+    "family": "input",
+    "code": "E_SEED_SHAPE",
+    "wrong": "rows: { todos: [{ id: \"todo-1\" }] }",
+    "right": "rows: { todos: [{ id: \"todo-1\", title: \"Ship\" }] }"
+  },
+  {
+    "family": "input",
+    "code": "E_SEED_VALUE",
+    "wrong": "rows: { todos: [{ id: \"todo-1\", title: 7 }] }",
+    "right": "rows: { todos: [{ id: \"todo-1\", title: \"Ship\" }] }"
+  },
+  {
+    "family": "effect",
+    "code": "E_EFFECT_CLOSURE",
+    "wrong": "const token = secret; effect({ run: () => token })",
+    "right": "effect({ run: (payload) => payload })"
+  },
+  {
+    "family": "effect",
+    "code": "E_EFFECT_TYPE",
+    "wrong": "effect({ grants: [], run: 1 })",
+    "right": "effect({ grants: [], run: async () => null })"
+  },
+  {
+    "family": "effect",
+    "code": "E_EFFECT_IMPORT",
+    "wrong": "import helper from \"unapproved-runtime\"",
+    "right": "use the payload and granted effect tools"
+  },
+  {
+    "family": "effect",
+    "code": "E_EFFECT_THEN_ARGS",
+    "wrong": "then: mutation({ id: t.id() }, handler)",
+    "right": "then: mutation({ outboxId: t.id(), effect: t.text(100), result: t.json(4096) }, handler)"
+  },
+  {
+    "family": "effect",
+    "code": "E_EFFECT_UNKNOWN",
+    "wrong": "emit(missingEffect, payload)",
+    "right": "emit(declaredEffect, payload)"
+  },
+  {
+    "family": "effect",
+    "code": "E_EMIT_IN_QUERY",
+    "wrong": "query({}, () => { emit(notify, null); return null })",
+    "right": "mutation({}, () => { emit(notify, null); return null })"
+  },
+  {
+    "family": "quarry",
+    "code": "E_QUARRY_SYNTAX",
+    "wrong": "```q\ntable items\n  name text <=100\n```",
+    "right": "```q\ntable items:\n  name: text <=100\n  public\n```"
+  },
+  {
+    "family": "quarry",
+    "code": "E_QUARRY_UNKNOWN",
+    "wrong": "```q\nquery one(id: items):\n  return missing[id]\n```",
+    "right": "```q\nquery one(id: items):\n  return items[id]\n```"
+  },
+  {
+    "family": "quarry",
+    "code": "E_QUARRY_AMBIGUOUS",
+    "wrong": "```q\nquery recent(owner: principal):\n  return posts[owner] first 20\n```",
+    "right": "```q\nquery recent(owner: principal):\n  return posts[owner] first 20 by byAuthorTime\n```"
+  },
+  {
+    "family": "quarry",
+    "code": "E_QUARRY_UNSUPPORTED",
+    "wrong": "```q\nquery visible(author: principal):\n  return posts[author] first 20 by byAuthorAt where .visible = true\n```",
+    "right": "```q\n-- schema.q: by byAuthorVisibleAt: author, visible, at, id\nquery visible(author: principal):\n  return posts[author, true] first 20 by byAuthorVisibleAt\n```"
+  },
+  {
+    "family": "quarry",
+    "code": "E_QUARRY_PLACEMENT",
+    "wrong": "```q\n-- snapback/items.q\ntable items:\n  name: text <=100\n```",
+    "right": "```q\n-- snapback/schema.q\ntable items:\n  name: text <=100\n  public\n```"
+  },
+  {
+    "family": "quarry",
+    "code": "E_QUARRY_TYPE",
+    "wrong": "```q\nquery present(x: time ?):\n  if x:\n    return true\n  return false\n```",
+    "right": "```q\nquery present(x: time ?):\n  return x != null\n```"
+  },
+  {
+    "family": "quarry",
+    "code": "E_QUARRY_RETAIN",
+    "wrong": "```q\ntable messages:\n  body: text <=4000\n  retain forever\n```",
+    "right": "```q\ntable messages:\n  body: text <=4000\n  retain delivered-history\n```"
+  },
+  {
+    "family": "quarry",
+    "code": "E_QUARRY_ONLY",
+    "wrong": "```ts\nexport const list = query({}, () => null);\n```",
+    "right": "```q\nquery list():\n  return null\n```"
+  },
+  {
+    "family": "args",
+    "code": "E_ARGS_CURSOR_INDEX",
+    "wrong": "indexes: { byConvTime: { columns: [\"conversationId\", \"at\"] } }",
+    "right": "indexes: { byConvTime: { columns: [\"conversationId\", \"at\", \"id\"] } }"
+  },
+  {
+    "family": "input",
+    "code": "E_INPUT",
+    "wrong": "pass a cursor minted for another index or order",
+    "right": "pass the previous page's next token back as the cursor argument"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_CARRIER",
+    "wrong": "createClient({ offline: { store: unavailableCarrier } })",
+    "right": "configure the IndexedDB web carrier or Node file test carrier"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_LOCK",
+    "wrong": "open the same account in two writing browser tabs",
+    "right": "close the other tab before opening this account"
+  },
+  {
+    "family": "args",
+    "code": "E_ARGS_ID_SCALAR",
+    "wrong": "db.insert(todos, { id: \"\", title })",
+    "right": "db.insert(todos, { id: ctx.newId(), title })"
+  },
+  {
+    "family": "args",
+    "code": "E_ARGS_ID_TEXT",
+    "wrong": "const pair = leftId + \":\" + rightId",
+    "right": "db.get(dmPairs.byPair, [leftId, rightId])"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_RESET",
+    "wrong": "client.resume({ generation: heldGeneration }) // after the program changed",
+    "right": "on 409 drop held coverage, keep the outbox, fetch /api/program?generation=<returned>, cold-drain"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_RESUME",
+    "wrong": "client.resume({ mounted: fortyQueries })",
+    "right": "client.resume({ mounted: first32 }) // re-subscribe the rest as ordinary reads"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_INTENT_EXPIRED",
+    "wrong": "replay: { grant: thirtyOneDayOldGrant, offset: 0, count: 2, intent }",
+    "right": "resume first; replay under the grant it returns"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_INTENT_REUSE",
+    "wrong": "replay: { intent: settledIntent, ... } // with different args",
+    "right": "new bytes take a new slice and a new intent; retry only the original bytes"
+  },
+  {
+    "family": "offline",
+    "code": "E_ASSET_VIEWED",
+    "wrong": "client.assetBlob(url) // for a view-once row this device already viewed",
+    "right": "render a view-once row once; a viewed row answers null offline and fetches nothing"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_ID_BLOCK",
+    "wrong": "replay: { grant, offset: 8191, count: 2, intent: `${grant}:8191` }",
+    "right": "replay: { grant, offset: unusedOffset, count: 1 + maxNewIds, intent: `${grant}:${unusedOffset}` }"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_AUTHORITY",
+    "wrong": "client.query(api.messages.thread, args) // a delivery for dev:bob while dev:alice's partition is open",
+    "right": "keep the held coverage: open the store as the delivery's principal (sign in as it) before committing it; never a reset"
+  },
+  {
+    "family": "offline",
+    "code": "E_OFFLINE_CONFLICT",
+    "wrong": "replay a queued edit whose traced row moved and read the refusal as a session error",
+    "right": "the intent settles rejected with reason: \"conflict\" and site; read the current row and send a new intent"
+  }
+]

package/dist/guide/grammar.md

@@ -0,0 +1,52 @@
+# Quarry grammar
+
+Use `snapback/schema.q` and `snapback/<module>.q`. Seeds, tests, and effect
+bodies are TypeScript; effect `then` is Quarry.
+
+```q
+use identity
+
+table todos:
+  title: text <=200
+  done: bool
+  ownerId: principal
+  by ownerId
+  read <- .ownerId = viewer
+```
+
+Schema uses `use identity [password|guests]`, `table`, `maintain`, and `channel`.
+Tables hold columns, indexes, invariants, rules, `after insert <-
+exists`, and optionally `retain until-revoked` or `retain delivered-history`
+(default: the former). Absences, uniform-range holes, and tombstones evict under
+both. Only hidden rows differ: the default evicts; `delivered-history` keeps.
+Put the word on the table whose rows can hide. A per-recipient log with immutable
+`.recipient = viewer` never hides, so needs no word. `.` is the row. Maintains
+count/sum by fields. Channels declare `publish`, `subscribe`, and `ttl Ns`.
+
+Types: `principal`, `id`, table references, `int`, `time`, `bool`,
+`decimal <scale>`, `money <CUR> [scale]`, `text <=N`, `text M..N`, `json <=N`,
+`bytes <=N`, `image <=N`, `video <=N`, `enum(...)`, `[type] <=N`, and
+operation-only `cursor`. Text may add a format; `?` makes any type optional.
+
+```q
+query list():
+  return todos[viewer] first 50
+```
+
+Programs are `effect name from module`, `query`, or `mutation`.
+`shape name = { fields }` applies to a row/page/read or splices as `...name`.
+Statements include bindings, `return`, `require`, `if/else`, bounded `for`,
+`match`, and `emit`; expressions include
+objects, arrays, reads/shapes, `exists`, `#maintain[key]`, four word writes,
+`! [else CODE]`, `??`, `merge`, and bounded built-ins.
+
+Reads use `table[value, …]` or `table[column = value, …]` plus `[after cursor]
+first|last N [by index]`; point reads may use `by index`.
+`merge table [after cursor] first|last N by index:` has indented lanes. Declare
+`c: cursor ?`; absent starts page one. Pass opaque `next` back unchanged. A
+pageable merge index ends in `id`.
+Equality is total; ordered comparisons need nonoptional operands or direct
+`if x != null:` narrowing. `where` refuses with index/read rewrites. Upserts
+cannot spell `id`. Decimal/money seeds are
+whole units; wire arguments remain minor units. `sorted` is
+`(lo, hi) = sorted(a, b)`. `shape`, `fn`, and `cursor` are reserved bindings.

package/dist/guide/live-query.md

@@ -0,0 +1,27 @@
+# Live query
+
+A query is live because its authoritative read trace intersects a commit, not
+because the author declares an invalidation list. Bound every scan:
+
+For paging, every cursor index ends in intrinsic `id`. Declare a `cursor ?`
+argument and pass it to Quarry's forward-only `after` clause; `null` means the
+first page.
+
+```ts
+export const thread = query({ conversationId: t.ref(conversations) }, ({ db, ctx, args }) => {
+  db.require(
+    db.exists(memberships.byConversationPrincipal, [args.conversationId, ctx.viewer]),
+    "MEMBERSHIP_REQUIRED",
+  );
+  return db.scan(messages.byConvTime, [args.conversationId], { order: "desc", take: 50 });
+});
+```
+
+`complete` and `capped` receipts carry `next: Cursor | null`. Pass that opaque
+token back as the cursor argument for the next page. It represents the last
+returned row, is bound to the table/index/order, and must not be inspected or
+constructed by application code.
+
+Subscribe through `client.subscribe(api.messages.thread, args, listener)`.
+Each SSE data frame is a query response or refusal. Connection `live`/`stale`
+facts belong to the client and never replace `complete`/`capped`/`denied`.

package/dist/guide/offline.md

@@ -0,0 +1,75 @@
+# Offline
+
+`offline.store`: IndexedDB or test files; `E_OFFLINE_CARRIER` if unavailable.
+Session expiry seals; sign-out or replacement wipes;
+one writer (`E_OFFLINE_LOCK`). `offline.fenceDays` (1..30) bounds trust, not
+reading: past it no predicting or replay until a resume succeeds; held
+answers read `stale`. `useQuery(op, args, { drain: true })` drains to `null`
+by its `Cursor`, then watches the tail. Offline `run()` resolves
+`{ state: "queued", intent, ids }`, replayed FIFO after resume.
+`useOutbox()` exposes `entries`, `dismiss`, `ready` (current grant or no partition),
+and `fence: "inside" | "past"`. `client.outbox.drain()` replays;
+it and `settled()` return `{ stopped: "fence" }` when resume is needed.
+The twin evaluates held rows: exact if covered, else `partial` with `reason`.
+Asset bytes share their row's lease, keyed `(assetId, width)`;
+`offline.maxAssetBytes` (256 MiB) caps an LRU. `offline.viewOnce(table, row)`
+marks an image at fetch, a clip at play (`assetCache.markViewed`): then the
+row reads `null`, `useAssetUrl` mints no URL, `assetBlob` refuses `E_ASSET_VIEWED`.
+
+Answers: `receipt: true` on `POST /api/query` or
+`receipt=1` on `/api/subscribe` returns `{ protocol: 1, generation,
+schemaHash, planHash, authority, state, data, next, seq, rows, receipt,
+validator }`; `rows` pools each row once, `data` and `receipt` cite
+`{ "$row": { table, id } }`, an equal `validator` gets `{ state: "unchanged",
+seq, validator }`. `GET /api/program?generation=`: IR, certificates, schema;
+`/api/manifest` has `tables[<name>].retain`.
+
+## Resume
+
+`POST /api/resume { protocol: 1, generation, schemaHash, authEpoch, remaining?,
+log?: { op, args, watermark, validator }, mounted: [{ op, args, validator }] }`
+is one owner action: the log tail (`{ unchanged: true }` or an envelope
+and `watermark`), then mounted queries, to 1 MiB (`more` past it).
+The log op pages ascending, `after c
+first <=50`; mounted caps at 32 (`E_OFFLINE_RESUME` 413, `which`). New
+program or schema: `E_OFFLINE_RESET` (409) with the live `{ generation,
+schemaHash }`; drop held coverage, keep the outbox, fetch `/api/program`,
+re-resume. Stale `authEpoch`: `E_AUTH_SESSION`. Another partition's delivery:
+`E_OFFLINE_AUTHORITY`, coverage kept.
+No facts: query for a receipt, then logless resume. No query:
+`E_OFFLINE_RESUME`; keep the queue.
+
+## Grants
+
+Login, guest, resume return `grant: { id, from, count: 8192, mintedAt,
+expiresAt }` (principal-bound, 30 days) if `remaining`, the client's unused
+ids, is absent or under 1024. `POST /api/mutation { op, args, replay: {
+grant, offset, count, intent: "<grant>:<offset>", trace } }` injects ids
+`from + offset …` as the `new` envelope. Refusals:
+`E_OFFLINE_INTENT_EXPIRED` (unknown, foreign, or expired grant),
+`E_OFFLINE_ID_BLOCK` (slice outside the grant or settled),
+`E_OFFLINE_INTENT_REUSE` (same intent, other bytes). Same bytes twice get the
+stored response; a 503 never double-sends.
+
+## Conflict
+
+`trace: { points: [{ table, index, key, digest }], verdicts: [{ ruleHash,
+inputsDigest, result }] }` is the read set at queue time: each point's row
+digest (SHA-256 of the canonical wire row, `null` if absent), each verdict's
+`inputsDigest` (SHA-256 of wire `[table, index, key]`). At commit the server
+executes on current rows and compares; a moved point or verdict rolls back:
+`{ state: "rejected", reason: "conflict", site, intent }`
+(`E_OFFLINE_CONFLICT`). Ranges re-execute unvalidated: a fan-out uses members
+at commit. Past-fence entries have `predicted: false, reason: "fence"` and
+an empty trace: only the program checks conflicts. The compare-and-set edit:
+
+```q
+mutation edit(messageId: messages, body: text <=4000, baseBody: text <=4000):
+  msg = messages[messageId] ! else NOT_FOUND
+  require msg.authorId = viewer else NOT_AUTHOR
+  require msg.body = baseBody else CONFLICT
+  update messages[msg] { body }
+  for m in memberships[msg.conversationId] first 50 by byConversationPrincipal:
+    insert deliveries { recipient: m.principal, conversationId: msg.conversationId, messageId, kind: 'edit', at: now }
+  return null
+```

package/dist/guide/personas.md

@@ -0,0 +1,15 @@
+# Personas
+
+Seed a small, named cast for development and tests:
+
+```ts
+  personas: ["alice", "bob", "charlie"],
+```
+
+Use `snapback2 run <op> '{}' --as alice`, `snapback2 why <query> --as alice`,
+or `createClient({ url, as: "alice" })`. Persona ids are stable (`dev:alice`)
+and remain distinct across clients. The loopback-only `--as`/header shortcut
+does not mint a stored session. `snapback2 persona create alice` instead
+issues a fresh, finite ordinary session for the same principal each time, so
+logout and expiry use the production session path. A `serve` owner refuses
+persona headers.