@sigrun/sigrun 0.1.5 → 0.2.0

package/dist/server/blocks/chat-surfaces.js

@@ -0,0 +1,393 @@
+/**
+ * The chat-surface handler (UI-blocks U5 Task 2, spec §8.2/§8.3): core
+ * applies a chat block's edits itself — there is no extension handler.
+ *
+ * - `move` applies a `DataOp.move` to the collection's bound array
+ *   (a cross-group move ALSO sets the item's `groupBy` field, spec
+ *   §8.3), with the destination resolved exactly like the channel's
+ *   optimistic overlay (useSurface.applyMoveOverlay), so the confirmed
+ *   result matches what the user saw while the action was in flight;
+ * - `edit` (a check) applies a `set` at the item's bound field;
+ * - a `turn: false` `submit` writes the form's values at its `bind`.
+ *
+ * Each applied edit appends one `ChangeRecord` (spec §8.3) whose
+ * `summary` comes from {@link summarizeAction} (labels the user saw),
+ * bumps the family's `rev`, and announces the change through the
+ * Task-1 seam (`chatSurfaceChanged` — the server binds it to the hub).
+ * More than {@link MAX_CHANGES} records with `notedThrough` past them
+ * are trimmed on the next append (Task 1's `trimChanges`).
+ *
+ * Ops apply inside ONE conversation commit (a failed batch unwinds
+ * before anything persists), and the commit returns only the new `rev`
+ * and the applied `ops` — plain JSON echoes the route answers, never a
+ * draft value (the chord settle hazard Task 1 documented).
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { applyOps, DataOpError } from "@sigrun/shared/blocks";
+import { BlocksEntry, } from "../../harness/blocks/entries.js";
+import { BlocksStateDoc, readBlocksState, trimChanges, } from "../../harness/blocks/state.js";
+import { chatSurfaceChanged, parseEntryId } from "../../harness/blocks/tools.js";
+import { summarizeAction } from "./summaries.js";
+/** A plain-record check (the tree walk's node shape). */
+function isRec(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Locate one chat block: its `sigrun.blocks` entry (visible through
+ * THIS conversation — `Conversation.entries` is fork-aware, so a fork
+ * sees only blocks whose entries are in its history) plus the state
+ * family's current member. `undefined` when the entry id names no
+ * block in this conversation.
+ */
+export async function readChatBlock(harness, conversationId, entryId) {
+    if (!/^\d+$/.test(entryId))
+        return undefined;
+    const conversation = await harness.conversation(conversationId, BACKGROUND_CONTEXT);
+    if (conversation === undefined)
+        return undefined;
+    const parsed = parseEntryId(entryId);
+    if (parsed === undefined)
+        return undefined;
+    const page = await conversation.entries({ minEntryId: parsed, maxEntryId: parsed }, 1, undefined, BACKGROUND_CONTEXT);
+    const found = page.items[0];
+    if (found === undefined || found.kind !== BlocksEntry.kind)
+        return undefined;
+    const payload = found.data;
+    const state = await readBlocksState(harness, conversationId, entryId, BACKGROUND_CONTEXT);
+    if (state === undefined)
+        return undefined;
+    return { title: payload.title, tree: payload.tree, state };
+}
+/**
+ * Resolve the tree's handler labels (spec §6.1: handler names are free
+ * labels in chat — no `handlers` set at validation) to the node each
+ * names: a collection's `onMove`/`onCheck`, a form's `onSubmit`. The
+ * LAST declaration wins (matching the channel's own scan direction).
+ */
+export function resolveChatHandlers(tree) {
+    const handlers = new Map();
+    const visit = (node) => {
+        if (node.type === "collection") {
+            if (typeof node.onMove === "string") {
+                handlers.set(node.onMove, { kind: "move", node });
+            }
+            if (typeof node.onCheck === "string") {
+                handlers.set(node.onCheck, { kind: "check", node });
+            }
+        }
+        else if (node.type === "form" && typeof node.onSubmit === "string") {
+            handlers.set(node.onSubmit, { kind: "submit", node });
+        }
+        const childLists = [
+            node.root,
+            node.children,
+            node.fields,
+            node.main,
+            node.sidebar,
+            node.detail,
+        ];
+        for (const list of childLists) {
+            if (Array.isArray(list)) {
+                for (const child of list) {
+                    if (!isRec(child))
+                        continue;
+                    if (isRec(child.block))
+                        visit(child.block);
+                    else
+                        visit(child);
+                }
+            }
+            else if (isRec(list)) {
+                visit(list);
+            }
+        }
+        if (isRec(node.item))
+            visit(node.item);
+    };
+    // SAFETY: the walk reads only the structural record fields (type,
+    // children, item, handler props) the wire Tree and the loose
+    // JsonObject view agree on; every read is typeof-guarded.
+    visit(tree.root);
+    return handlers;
+}
+/**
+ * Whether the handler `actionName` names starts a turn (spec §6.2/§8.4):
+ * a form's `submit` defaults to `turn: true` (an answer) and may set
+ * `turn: false` to stay an edit. ONLY submit handlers start turns: a
+ * move/check `turn` flag is never consulted (the collection node's
+ * `turn` is not part of the declared wire contract — shared
+ * CollectionBlock has none — so depending on it here would lean on an
+ * undeclared, unvalidated contract). Chat handler names are free
+ * labels, so this reads the RESOLVED node — the only place the default
+ * rule lives.
+ */
+export function chatActionStartsTurn(tree, actionName) {
+    const handler = resolveChatHandlers(tree).get(actionName);
+    if (handler === undefined)
+        return false;
+    if (handler.kind !== "submit")
+        return false;
+    return handler.node.turn !== false;
+}
+/** A `move`/`edit` payload endpoint ({group?, index}). */
+function readSpot(value) {
+    if (!isRec(value))
+        return undefined;
+    return {
+        ...(typeof value.group === "string" ? { group: value.group } : {}),
+        ...(typeof value.index === "number" ? { index: value.index } : {}),
+    };
+}
+/** Read the value at one data pointer (`/a/0/b`); undefined when absent. */
+function dataAt(data, pointer) {
+    if (pointer === "/" || pointer === "")
+        return data;
+    const tokens = pointer.replace(/^\//, "").split("/");
+    let node = data;
+    for (const token of tokens) {
+        if (Array.isArray(node)) {
+            if (!/^\d+$/.test(token))
+                return undefined;
+            const index = Number(token);
+            if (index >= node.length)
+                return undefined;
+            node = node[index];
+        }
+        else if (isRec(node)) {
+            const next = node[token];
+            if (next === undefined)
+                return undefined;
+            node = next;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return node;
+}
+/** The collection's bound-array pointer (`/cards`), when it binds one. */
+function itemsPointer(collection) {
+    const items = collection.items;
+    if (!isRec(items))
+        return undefined;
+    const pointer = items.$;
+    return typeof pointer === "string" ? pointer : undefined;
+}
+/** The index of one item id inside its collection's bound array. */
+function itemIndexAt(items, itemId) {
+    return items.findIndex((candidate) => isRec(candidate) && candidate.id === itemId);
+}
+/**
+ * The ABSOLUTE array index a group-relative drop lands at, mirroring
+ * the channel's overlay math (useSurface.applyMoveOverlay): the
+ * `index`-th member of `group` in the POST-REMOVAL array, or the
+ * array's end when the index is past the group's members (a lane-end
+ * drop). Grouped on `groupBy`; `undefined` when the group is unknown.
+ */
+function absoluteDropIndex(removed, groupBy, group, index) {
+    const members = removed
+        .map((entry, position) => ({ entry, position }))
+        .filter(({ entry }) => isRec(entry) && entry[groupBy] === group)
+        .map(({ position }) => position);
+    if (index < members.length)
+        return members[index] ?? removed.length;
+    return removed.length;
+}
+/** Compute one action's ops against the CURRENT data (spec §8.3). */
+function planAction(handlers, actionName, payload, data) {
+    const handler = handlers.get(actionName);
+    if (handler === undefined)
+        return undefined;
+    const record = isRec(payload) ? payload : {};
+    if (handler.kind === "move") {
+        const base = itemsPointer(handler.node);
+        if (base === undefined)
+            return undefined;
+        const itemId = record.itemId;
+        if (typeof itemId !== "string")
+            return undefined;
+        const items = dataAt(data, base);
+        if (!Array.isArray(items))
+            return undefined;
+        const fromIndex = itemIndexAt(items, itemId);
+        if (fromIndex < 0)
+            return undefined;
+        const to = readSpot(record.to);
+        if (to === undefined || to.index === undefined)
+            return undefined;
+        const groupBy = typeof handler.node.groupBy === "string" ? handler.node.groupBy : undefined;
+        // Post-removal resolution (DataOp.move resolves its destination
+        // against the post-removal array too, so the two agree).
+        const removed = items.filter((_, index) => index !== fromIndex);
+        const at = groupBy !== undefined && to.group !== undefined
+            ? absoluteDropIndex(removed, groupBy, to.group, to.index)
+            : to.index;
+        const ops = [];
+        // A cross-group move sets the groupBy field FIRST (spec §8.3) —
+        // the item arrives at the destination already grouped, and the
+        // set's index still addresses the pre-move array.
+        if (groupBy !== undefined && to.group !== undefined) {
+            const current = items[fromIndex];
+            if (isRec(current) &&
+                current[groupBy] !== to.group) {
+                ops.push({
+                    op: "set",
+                    path: `${base}/${fromIndex}/${groupBy}`,
+                    value: to.group,
+                });
+            }
+        }
+        ops.push({ op: "move", from: `${base}/${fromIndex}`, path: `${base}/${at}` });
+        return { ops, actionKind: "reorder" };
+    }
+    if (handler.kind === "check") {
+        const field = handler.node.checkable;
+        if (typeof field !== "string")
+            return undefined;
+        const base = itemsPointer(handler.node);
+        if (base === undefined)
+            return undefined;
+        const itemId = record.itemId;
+        if (typeof itemId !== "string")
+            return undefined;
+        const items = dataAt(data, base);
+        if (!Array.isArray(items))
+            return undefined;
+        const at = itemIndexAt(items, itemId);
+        if (at < 0)
+            return undefined;
+        const value = record.value === undefined ? true : record.value;
+        return {
+            ops: [{ op: "set", path: `${base}/${at}/${field}`, value }],
+            actionKind: "edit",
+        };
+    }
+    // submit (turn:false): write the form's values at its bind.
+    const bind = handler.node.bind;
+    if (typeof bind !== "string")
+        return undefined;
+    const values = record.values;
+    if (!isRec(values))
+        return undefined;
+    const root = bind === "/" || bind === "" ? "" : bind.replace(/\/$/, "");
+    const ops = [];
+    // The bind object itself is created when absent (`set` can create the
+    // FINAL member but not intermediate parents) — a form writing at a
+    // fresh bind is the normal first-submit case.
+    if (root !== "" && dataAt(data, root) === undefined) {
+        ops.push({ op: "set", path: root, value: {} });
+    }
+    for (const name of Object.keys(values)) {
+        ops.push({
+            op: "set",
+            path: `${root}/${name}`,
+            value: values[name],
+        });
+    }
+    return { ops, actionKind: "submit" };
+}
+/** The `Action` summarizeAction reads for one plan (kind + label). */
+function actionFor(actionKind, actionName) {
+    if (actionKind === "reorder")
+        return { type: "move", name: actionName };
+    if (actionKind === "edit")
+        return { type: "edit", name: actionName };
+    return { type: "submit", name: actionName };
+}
+/** The next change-record seq, monotonic per surface even right after a
+ *  trim emptied the array (notedThrough anchors the sequence). */
+function nextSeq(changes, notedThrough) {
+    return Math.max(changes[changes.length - 1]?.seq ?? 0, notedThrough) + 1;
+}
+/**
+ * Apply one user edit (the core handler, spec §8.3): read the entry
+ * (the tree is immutable, so its labels are always current), then —
+ * INSIDE ONE conversation commit — read the CURRENT draft state,
+ * compute the ops against it (planAction), and write ops + change
+ * record + `rev` bump. Planning inside the commit is what keeps an
+ * index-addressed op from relocating the WRONG row when a concurrent
+ * move (or an agent `update_blocks`) lands between the read and the
+ * write: `draft.data` at commit time IS the data the op addresses
+ * (Review Focus 3, spec §6.3 convergence), and the summary names the
+ * positions/labels the actor saw AT APPLY TIME (draft.data again,
+ * never a pre-commit snapshot). A failed op batch unwinds the commit
+ * (no partial write) and answers a reject naming the op index.
+ * `undefined` outcome means the entry id names no block in this
+ * conversation (the route answers 404).
+ */
+export async function applyChatAction(harness, conversationId, entryId, by, actionName, payload) {
+    const conversation = await harness.conversation(conversationId, BACKGROUND_CONTEXT);
+    if (conversation === undefined)
+        return undefined;
+    const block = await readChatBlock(harness, conversationId, entryId);
+    if (block === undefined)
+        return undefined;
+    const handlers = resolveChatHandlers(block.tree);
+    if (!handlers.has(actionName))
+        return undefined;
+    let applied;
+    try {
+        applied = await conversation.commit(async (tx) => {
+            const draft = await tx.doc(BlocksStateDoc, conversationId, entryId, entryId);
+            // The plan is derived from the DRAFT — the data as of the
+            // commit, not the pre-commit snapshot — so every index
+            // addresses the row the op is about to move.
+            const plan = planAction(handlers, actionName, payload, draft.data);
+            if (plan === undefined) {
+                // Signal out of the commit (a throw unwinds it); the
+                // caller answers the reject.
+                return { rev: -1, ops: [] };
+            }
+            // The summary reads the labels the user saw AT APPLY TIME — the
+            // draft's PRE-edit data (the payload's positions are the
+            // pre-move ones), so it is computed BEFORE the ops apply.
+            const summary = summarizeAction(block.tree, draft.data, actionFor(plan.actionKind, actionName), payload);
+            // applyOps throws DataOpError on a bad path — the throw unwinds
+            // the commit before anything persists.
+            draft.data = applyDataOps(draft.data, plan.ops);
+            draft.rev += 1;
+            draft.changes = [
+                ...draft.changes,
+                {
+                    seq: nextSeq(draft.changes, draft.notedThrough),
+                    at: Date.now(),
+                    by,
+                    action: plan.actionKind,
+                    summary,
+                },
+            ];
+            // The trim (spec §8.2): once more than MAX_CHANGES accumulate,
+            // records at or below notedThrough drop on THIS append.
+            trimChanges(draft);
+            // Only the rev + ops escape the commit — never a draft value
+            // (the chord settle hazard Task 1 documented); rev/ops are the
+            // values the route echoes back, plain JSON.
+            return { rev: draft.rev, ops: plan.ops };
+        }, BACKGROUND_CONTEXT);
+    }
+    catch (error) {
+        if (error instanceof DataOpError) {
+            return {
+                ok: false,
+                error: { message: `op ${error.opIndex} failed: ${error.message}` },
+            };
+        }
+        throw error;
+    }
+    if (applied.rev === -1) {
+        return { ok: false, error: { message: `unappliable action payload: ${actionName}` } };
+    }
+    chatSurfaceChanged({
+        type: "surface.changed",
+        conversationId,
+        entryId,
+        rev: applied.rev,
+    });
+    return { ok: true, rev: applied.rev, ops: applied.ops };
+}
+/** applyOps over a plan's ops. */
+function applyDataOps(data, ops) {
+    // SAFETY: planAction built every op as a literal DataOp; applyOps
+    // re-validates each path and throws DataOpError on anything else.
+    return applyOps(data, ops);
+}

package/dist/server/blocks/notes.js

@@ -0,0 +1,216 @@
+/**
+ * The §8.3 change note (UI-blocks U5 Task 3): before the agent's next
+ * turn, core writes ONE `sigrun.blocks.note` entry covering every
+ * surface with change records above `notedThrough`, then advances each
+ * surface's `notedThrough` in one commit.
+ *
+ * The note is a `type: "write"` submission whose entry carries the note
+ * as a `model` user message — when the conversation is idle pi-durable
+ * appends it at once; when busy, both the note and the input queue in
+ * `pi.inbox`, and pi-durable places every queued write before any queued
+ * user item at each boundary (`harness/inbox.js` applyBoundary), so the
+ * note always precedes its input, a steer included.
+ *
+ * Exactly once (§8.3): the write's `requestId` is
+ * `blocks-note:<conversationId>:<sha256 of the sorted (entryId,
+ * notedThrough) pairs BEFORE advancing>` — a key over the pre-advance
+ * positions only, never the carried changes, so new edits arriving after
+ * the note compute cannot change the key; a crash between the admission
+ * and the advance re-sends under the SAME key and pi-durable returns the
+ * existing submission (`submissionByRequest`).
+ */
+import { createHash } from "node:crypto";
+import { toText } from "@sigrun/shared/blocks";
+import { PROJECTION_LOCALE, PROJECTION_WIDTH, } from "../../harness/blocks/tools.js";
+import { BlocksEntry, BlocksNoteEntry, } from "../../harness/blocks/entries.js";
+import { BlocksStateDoc, } from "../../harness/blocks/state.js";
+/** The note's header line (spec §8.3, verbatim). */
+export const NOTE_HEADER = "Changes made to your UI since your last turn:";
+/** The per-surface change-line cap (spec §8.3): the oldest fold into "…and N earlier changes". */
+export const MAX_NOTE_CHANGE_LINES = 50;
+/**
+ * The test seam for the crash-recovery case: when armed, the NEXT
+ * `writePendingNote` throws right after the note's admission (before the
+ * `notedThrough` advance) — the durable record of the crash window the
+ * exactly-once key exists for. One-shot: the throw consumes the arm.
+ */
+let throwAfterNextAdmission = false;
+/** Arm the crash seam (see the field above). Test-only. */
+export function throwAfterNextNoteAdmissionForTesting() {
+    throwAfterNextAdmission = true;
+}
+/**
+ * Render one surface's note section (spec §8.3): the bullet line naming
+ * the surface and each editor (`• <title> (<user>): <summaries joined by
+ * "; ">` — one line per distinct author, in first-appearance order) then
+ * `Current state of <title>: <toText of the surface at its CURRENT data>`.
+ * Over {@link MAX_NOTE_CHANGE_LINES} change lines for a surface, the
+ * oldest fold into "…and N earlier changes".
+ */
+function renderSurface(surface) {
+    const lines = [];
+    // Group the pending records by author, first-appearance order.
+    const byAuthor = new Map();
+    for (const record of surface.pending) {
+        const list = byAuthor.get(record.by) ?? [];
+        list.push(record.summary);
+        byAuthor.set(record.by, list);
+    }
+    for (const [author, summaries] of byAuthor) {
+        if (summaries.length > MAX_NOTE_CHANGE_LINES) {
+            const earlier = summaries.length - MAX_NOTE_CHANGE_LINES;
+            const kept = summaries.slice(earlier);
+            lines.push(`• ${surface.title} (${author}): …and ${earlier} earlier changes; ${kept.join("; ")}`);
+        }
+        else {
+            lines.push(`• ${surface.title} (${author}): ${summaries.join("; ")}`);
+        }
+    }
+    const projection = toText(surface.tree, surface.state.data, {
+        width: PROJECTION_WIDTH,
+        locale: PROJECTION_LOCALE,
+    });
+    lines.push(`Current state of ${surface.title}: ${projection}`);
+    return lines.join("\n");
+}
+/**
+ * Compute the pending change note for one conversation (spec §8.3):
+ * every `sigrun.blocks` entry in the conversation whose state carries
+ * change records above `notedThrough`. `skipEntry` excludes ONE surface
+ * (the block answer folds its own surface's changes into the answer
+ * instead — §8.4). `undefined` when nothing is unnoted.
+ */
+export async function pendingNote(harness, conversationId, skipEntry, ctx) {
+    const conversation = await harness.conversation(conversationId, ctx);
+    if (conversation === undefined)
+        return undefined;
+    // Every block entry in the conversation (oldest first — the note
+    // lists surfaces in transcript order).
+    const page = await conversation.entries({}, 500, undefined, ctx);
+    const blocks = [];
+    for (const entry of [...page.items].reverse()) {
+        if (entry.kind !== BlocksEntry.kind)
+            continue;
+        blocks.push({
+            entryId: String(entry.id),
+            payload: entry.data,
+        });
+    }
+    const surfaces = [];
+    for (const block of blocks) {
+        if (block.entryId === skipEntry)
+            continue;
+        const state = await harness.snapshot(BlocksStateDoc, conversationId, block.entryId, ctx);
+        if (state === undefined)
+            continue;
+        const pending = state.changes.filter((record) => record.seq > state.notedThrough);
+        if (pending.length === 0)
+            continue;
+        surfaces.push({
+            entryId: block.entryId,
+            title: block.payload.title,
+            state,
+            pending,
+            tree: block.payload.tree,
+        });
+    }
+    if (surfaces.length === 0)
+        return undefined;
+    // The exactly-once key: the sorted (entryId, notedThrough) pairs as
+    // they stand BEFORE this note advances them (spec §8.3).
+    const pairs = surfaces
+        .map((surface) => [surface.entryId, String(surface.state.notedThrough)])
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const digest = createHash("sha256")
+        .update(JSON.stringify(pairs))
+        .digest("hex");
+    const text = [
+        NOTE_HEADER,
+        ...surfaces.map((surface) => renderSurface(surface)),
+    ].join("\n");
+    return {
+        text,
+        requestId: `blocks-note:${conversationId}:${digest}`,
+        advance: surfaces.map((surface) => ({
+            entryId: surface.entryId,
+            // The covered top seq: the newest pending record. New edits
+            // landing after this compute advance only as far as the note
+            // covers — they stay pending for the NEXT note.
+            through: surface.pending[surface.pending.length - 1].seq,
+        })),
+    };
+}
+/**
+ * Write the pending change note for one conversation, when there is one:
+ * compute it, admit the `sigrun.blocks.note` write (model-facing, so a
+ * busy conversation queues it ahead of the input the caller submits
+ * next), then advance each covered surface's `notedThrough` in ONE
+ * commit. `skipEntry` excludes one surface (the block-answer fold,
+ * §8.4).
+ *
+ * Order is the exactly-once contract (§8.3): admission FIRST (a crash
+ * after it re-sends under the same requestId — `pendingNote` computes
+ * the key from the pre-advance positions, which a crashed advance never
+ * moved — and pi-durable returns the existing submission), the advance
+ * SECOND. The caller submits the turn's input after this returns.
+ */
+export async function writePendingNote(harness, conversation, skipEntry, ctx) {
+    const note = await pendingNote(harness, conversation.id, skipEntry, ctx);
+    if (note === undefined)
+        return;
+    const message = {
+        role: "user",
+        content: note.text,
+        timestamp: Date.now(),
+    };
+    const submission = await conversation.submit({
+        type: "write",
+        entry: {
+            kind: BlocksNoteEntry.kind,
+            model: [message],
+            // The coverage rides the entry (the durable artifact): a
+            // deduped retry — pi-durable returns the EXISTING
+            // submission and discards this text+data — must advance
+            // only as far as the ADMITTED note named, never this
+            // attempt's freshly computed `advance`.
+            data: { advance: note.advance },
+        },
+        requestId: note.requestId,
+    }, ctx);
+    // The crash seam (test-only, see the field's docblock): admission
+    // landed, the advance never runs — the retry path's premise.
+    if (throwAfterNextAdmission) {
+        throwAfterNextAdmission = false;
+        throw new Error("injected crash after note admission");
+    }
+    // Read the ADMITTED note's coverage from its entry, not this
+    // compute's: a deduped submission's entry id names the entry the
+    // FIRST admission wrote. Entries are conversation-scoped (the
+    // submission's `entry` id is only meaningful inside its
+    // conversation), so the read goes through the conversation handle.
+    const status = await submission.status(ctx);
+    const admittedEntryId = status.type === "write" && status.status === "done"
+        ? status.entry
+        : undefined;
+    let advance = note.advance;
+    if (admittedEntryId !== undefined) {
+        const page = await conversation.entries({ minEntryId: admittedEntryId, maxEntryId: admittedEntryId }, 1, undefined, ctx);
+        const data = page.items[0]?.data;
+        if (data !== undefined && typeof data === "object" && !Array.isArray(data)) {
+            const admitted = data.advance;
+            if (Array.isArray(admitted))
+                advance = admitted;
+        }
+    }
+    // Advance `notedThrough` per covered surface in ONE commit (the note
+    // is durable; the advance just moves the watermark).
+    await conversation.commit(async (tx) => {
+        for (const { entryId, through } of advance) {
+            const draft = await tx.doc(BlocksStateDoc, conversation.id, entryId, entryId);
+            // Never move the watermark BACKWARD (a retried note after a
+            // newer advance is a no-op).
+            if (draft.notedThrough < through)
+                draft.notedThrough = through;
+        }
+    }, ctx);
+}