@dev.fast/whiteboard 0.2.4 → 0.2.5-preview.20261013.109

package/src/ask/thread.ts

@@ -74,6 +74,17 @@ const piGreetingSchema = z.object({
 
 const cursorTodosSchema = z.object({ todos: z.unknown() }).loose();
 
+/** The steering extension Claude's adapter takes: a follow-up joins the
+ * turn under way rather than waiting for it to end. */
+const STEER_METHOD = "_session/steering";
+
+/** How an agent says, in its `initialize` response, that it takes steering. */
+const steeringSchema = z.object({
+  steering: z.object({ supported: z.literal(true) }),
+});
+
+const steerOutcomeSchema = z.object({ outcome: z.string() });
+
 /** MCP servers the reviewer's own agent may bring whose tools only read,
  * so their calls run without asking, like the agent reading files. */
 const READ_ONLY_MCP_SERVERS = new Set([
@@ -203,6 +214,10 @@ export class AskThread {
   /** What Pi greets a new session with, its version and skills, which is no
    * part of the answer. */
   private greeting?: string;
+  /** The agent takes follow-ups into the turn under way. */
+  private steerable = false;
+  /** Follow-ups waiting for the turn under way to end, oldest first. */
+  private queue: { id: string; question: AskQuestion }[] = [];
 
   constructor(
     private readonly launch: AskAgentLauncher,
@@ -283,20 +298,29 @@ export class AskThread {
   askRefusal(): string | undefined {
     switch (this.state.status) {
       case "idle":
+      case "running":
+      case "waiting":
         return undefined;
       case "failed":
         return `${this.state.agentName} stopped. Try again first.`;
       default:
-        return "The agent is still answering.";
+        return `${this.state.agentName} is still starting.`;
     }
   }
 
-  /** Asks a follow-up, starting the agent again if it has stopped since. */
+  /** Asks a follow-up, starting the agent again if it has stopped since.
+   * While the agent answers, it joins that turn or waits for it to end. */
   async ask(question: AskQuestion) {
     const refusal = this.askRefusal();
 
     if (refusal) throw new Error(refusal);
 
+    if (this.state.status !== "idle") {
+      await this.steer(question);
+
+      return;
+    }
+
     this.asking = { id: this.addUser(question), question };
     await this.attempt(async () => {
       await this.reconnect();
@@ -340,6 +364,60 @@ export class AskThread {
     });
   }
 
+  /** Gives the turn under way a follow-up when the agent takes one, else
+   * keeps it for when the turn ends. */
+  private async steer(question: AskQuestion) {
+    const { connection, sessionId } = this;
+
+    if (this.steerable && connection && sessionId) {
+      const id = this.addUser(question);
+
+      const outcome = await connection.agent
+        .request(STEER_METHOD, {
+          sessionId,
+          prompt: [
+            { type: "text", text: question.text },
+            ...this.attachments(question),
+          ],
+          // A turn that ended meanwhile leaves the follow-up to Whiteboard,
+          // rather than the agent starting a turn Whiteboard does not see end.
+          _meta: { steering: { idleBehavior: "promptRequired" } },
+        })
+        .then(
+          (response) => steerOutcomeSchema.safeParse(response).data?.outcome,
+        )
+        .catch(() => undefined);
+
+      if (outcome === "injected") return;
+      this.emit({ type: "remove", ids: [id] });
+    }
+
+    this.queue.push({ id: randomUUID(), question });
+    this.showQueue();
+    // The turn may have ended while the agent was asked.
+    this.askQueued();
+  }
+
+  /** Asks the oldest waiting follow-up, once no turn is under way. */
+  private askQueued() {
+    if (this.closed || this.state.status !== "idle") return;
+    const next = this.queue.shift();
+
+    if (!next) return;
+    this.showQueue();
+    void this.ask(next.question);
+  }
+
+  private showQueue() {
+    this.emit({
+      type: "set",
+      queued: this.queue.map(({ id, question }) => ({
+        id,
+        text: question.text,
+      })),
+    });
+  }
+
   decide(permissionId: string, optionId: string) {
     const resolve = this.decisions.get(permissionId);
 
@@ -352,6 +430,12 @@ export class AskThread {
   /** Stops the turn, or the start, in progress. A turn the agent does not
    * end soon after is ended by stopping the agent. */
   async cancel() {
+    // Stop drops the follow-ups waiting on the turn as well.
+    if (this.queue.length) {
+      this.queue = [];
+      this.showQueue();
+    }
+
     // ACP: the Client answers every pending permission request as cancelled.
     for (const resolve of this.decisions.values())
       resolve({ outcome: { outcome: "cancelled" } });
@@ -379,31 +463,33 @@ export class AskThread {
         .catch(() => {});
   }
 
-  close() {
+  close(save = true) {
     if (this.closed) return;
     this.closed = true;
 
-    // A conversation still starting may be half replayed, and one that
-    // failed has nothing new; neither replaces what was saved.
-    if (
-      this.sessionId &&
-      this.state.status !== "starting" &&
-      this.state.status !== "failed"
-    )
-      this.start.onSave?.(settled(this.state.entries));
-
-    for (const resolve of this.decisions.values())
-      resolve({ outcome: { outcome: "cancelled" } });
+    try {
+      // Starting and failed conversations must not replace saved history.
+      if (
+        save &&
+        this.sessionId &&
+        this.state.status !== "starting" &&
+        this.state.status !== "failed"
+      )
+        this.start.onSave?.(settled(this.state.entries));
+    } finally {
+      for (const resolve of this.decisions.values())
+        resolve({ outcome: { outcome: "cancelled" } });
 
-    if (this.connection && this.sessionId)
-      void this.connection.agent
-        .notify(methods.agent.session.cancel, { sessionId: this.sessionId })
-        .catch(() => {});
-    this.disconnect();
-    this.listeners.clear();
+      if (this.connection && this.sessionId)
+        void this.connection.agent
+          .notify(methods.agent.session.cancel, { sessionId: this.sessionId })
+          .catch(() => {});
+      this.disconnect();
+      this.listeners.clear();
 
-    for (const closed of this.closers) closed();
-    this.closers.clear();
+      for (const closed of this.closers) closed();
+      this.closers.clear();
+    }
   }
 
   /** Runs when the thread closes, at once if it already has. */
@@ -556,6 +642,9 @@ export class AskThread {
       clientInfo: { name: "whiteboard", title: "Whiteboard", version: "1" },
     });
 
+    this.steerable =
+      askAgents[this.start.agent].steers === true &&
+      steeringSchema.safeParse(initialized._meta).success;
     this.emit({
       type: "set",
       accepts: {
@@ -793,6 +882,8 @@ export class AskThread {
         _meta: this.sessionMeta(),
       });
 
+      if (this.closed) throw new Error("This conversation has ended.");
+
       this.sessionId = response.sessionId;
       start.onSession?.(response.sessionId);
 
@@ -895,6 +986,8 @@ export class AskThread {
       clearTimeout(this.stopTimer);
     }
 
+    if (this.closed) return;
+
     if (withSelection) this.needsContext = false;
 
     if (withPermission) this.permitted = false;
@@ -936,6 +1029,7 @@ export class AskThread {
     });
     this.start.onTurn?.();
     this.start.onSave?.(this.state.entries);
+    this.askQueued();
   }
 
   private async requestPermission(

package/src/ask/threads.ts

@@ -265,10 +265,16 @@ export class AskThreads {
     return offer;
   }
 
-  close(id: string) {
-    this.threads.get(id)?.close();
+  close(id: string, save = true) {
+    const thread = this.threads.get(id);
     this.threads.delete(id);
     this.unwatchedSince.delete(id);
+    thread?.close(save);
+  }
+
+  closeDeletedReviews(isDeleted: (reviewId: string) => boolean) {
+    for (const [id, thread] of this.threads)
+      if (isDeleted(thread.reviewId)) this.close(id, false);
   }
 
   closeAll() {

package/src/error-telemetry.ts

@@ -95,17 +95,21 @@ export function deriveErrorTelemetryProperties(
     const message = jsonString(cause.message);
 
     if (message !== undefined && message.length > 0) {
+      const cleaned = cleanTelemetryText(message, NO_DELETED_DIRECTORIES);
+
       // The digest goes on every report, cleaned message or not. It is what
       // groups the reports whose message does not survive the checks below.
-      derived.message_hash = hashErrorMessage(message);
-
-      if (!SCHEMA_ERROR_NAMES.has(derived.error_name ?? "")) {
-        const cleaned = cleanTelemetryText(message, NO_DELETED_DIRECTORIES);
-
-        // Ask the allowlist's own check before sending. Failing here rather
-        // than there keeps a message that the cleaner could not finish out of
-        // the payload entirely, instead of relying on the later gate.
-        if (isReportableCleanedMessage(cleaned)) derived.message = cleaned;
+      // Cleaned, so an error that names a file has one digest for all files.
+      derived.message_hash = hashErrorMessage(cleaned);
+
+      // Ask the allowlist's own check before sending. Failing here rather
+      // than there keeps a message that the cleaner could not finish out of
+      // the payload entirely, instead of relying on the later gate.
+      if (
+        !SCHEMA_ERROR_NAMES.has(derived.error_name ?? "") &&
+        isReportableCleanedMessage(cleaned)
+      ) {
+        derived.message = cleaned;
       }
     }
 

package/src/fixtures/blocks/tutorial.json

@@ -4,48 +4,11 @@
     "kind": "keymap",
     "id": "block-1"
   },
-  {
-    "type": "tutorial",
-    "kind": "conversation",
-    "conversation": {
-      "version": 1,
-      "title": "How an agent authors a review",
-      "messages": [
-        {
-          "role": "user",
-          "body": "Explain this change."
-        },
-        {
-          "role": "assistant",
-          "body": "Here is a review."
-        }
-      ]
-    },
-    "id": "block-2"
-  },
   {
     "type": "tutorial",
     "kind": "view",
-    "view": "commits",
-    "label": "Explore commits",
-    "id": "block-3"
-  },
-  {
-    "type": "tutorial",
-    "kind": "feature",
-    "feature": "softwareMap",
-    "children": [
-      {
-        "type": "markdown",
-        "markdown": "Explore the map.",
-        "id": "block-5"
-      },
-      {
-        "id": "block-6",
-        "type": "software_map",
-        "mapVersionId": "33333333-3333-4333-8333-333333333333"
-      }
-    ],
-    "id": "block-4"
+    "view": "diff",
+    "label": "Open the diff",
+    "id": "block-2"
   }
 ]

package/src/review-api/README.md

@@ -16,7 +16,7 @@ catalog. Tests inject the native store and source-data provider.
 - `authoring_presences`: one row per agent working on a review (focus, color slot, where it last wrote, expiry).
 - `repositories`: server-only local paths; clients receive an ID and display name.
 - `resources`: immutable image, trace and software-map bytes, scoped to a repository.
-- `review_attention`: viewed/dismissed timestamps, separate from document history.
+- `review_attention`: viewed/trashed timestamps, separate from document history.
 
 One host-owned store serializes writes, including asynchronous validation.
 Presences show who is working across database connections and never block a
@@ -96,12 +96,15 @@ Commands: `create {title,target,pullRequestUrl?,reuseExisting?}` or `create {pul
 Agents name the checkout by `repositoryPath` in a target, or on a create from a PR alone; `/commands` registers the path and passes the store its id. Retargeting preserves content and component IDs. Restore restores title, target, PR identity, and content. Live targets still read the current checkout.
 PR URLs must be canonical `https://github.com/owner/repository/pull/123` URLs. The PR number is derived from the URL; identity is metadata alongside immutable pins, not a moving source reference. A `create` with a target keeps that target and treats the URL as identity only. A `create` with the URL and no target resolves the PR when accepted: it reads the PR with `gh pr view` (falling back to the public GitHub API), picks the registered checkout named by `repositoryId`, else the checkout of the PR's existing review, else the first registered checkout with a remote whose configured URL is `github.com/owner/repository`, and fetches `refs/pull/N/head` and the base branch from that remote into `refs/review/github/owner/repository/pull/N/*`, never moving branches or bookmarks (a jj repository indexes the commits through a transient tag). It pins that head and its merge base with the base branch; for a PR absorbed by a merge commit it uses the merge base with GitHub's frozen base commit instead. The title defaults to the PR title. A repeat resolves the PR again, so `headMoved` compares the existing review with the PR's current head. `set_target` preserves the document and component IDs, including when source commits change. Its response reports retained source ranges to verify, those in files the new commits changed, and resources that no longer match the pins; agents repair these with `edit`. Existing versions keep their original pins and content. It preserves omitted PR identity within one repository, clears it when switching repositories, and accepts an explicit URL or null.
 
-`attention {reviewId,action:"view"|"dismiss"|"restore"}` records viewing or
-reversible dismissal without creating a document version. Home summaries include
-the repository name and attention timestamps.
-The list stream is separate from document streams. Dismissal closes
-the native tab and can be undone from Home. Dismissed API reviews stay saved;
-`delete {reviewId}` permanently removes their versions. Old command
+`attention {reviewId,action:"view"}` records viewing without changing lifecycle or document history.
+`lifecycle {reviewId,state:"active"|"trash"}` moves a whiteboard to Trash or restores it.
+Trash retains whiteboards for 30 days; repeated moves to Trash keep the original deadline.
+`delete {reviewId}` permanently removes a whiteboard and its history, but only from Trash.
+The agent tools are `session_attention`, `session_lifecycle`, and `session_delete`.
+`session_restore_version` restores saved content; it does not move a whiteboard out of Trash.
+Home summaries include the repository name, `viewedAt`, and `trashedAt`.
+The list stream is separate from document streams; moving to Trash closes the native tab.
+Old command
 inputs are erased but their IDs remain, so delayed retries cannot resurrect content.
 Repository resources remain shared. Home and the canvas open a pinned, read-only
 source tree. Each source tab names its review version; files opened from it use

package/src/review-api/ask-history.ts

@@ -11,6 +11,8 @@ import {
 } from "@review/ask/thread-state.js";
 import { z } from "zod";
 
+import { ReviewInputError } from "./document.js";
+
 /** A saved Ask conversation: its history entry, and how to reopen it. */
 export const askRecordSchema = askHistoryEntrySchema.extend({
   reviewId: z.string(),
@@ -64,6 +66,10 @@ const rowSchema = z
 /** Saved Ask conversations, per review. Shared reviews are not in
  * `reviews`, so there is no foreign key; deleting a review deletes its rows. */
 export class AskHistory {
+  private externalWriteGuard?: (reviewId: string) => void;
+  setExternalWriteGuard(guard: (reviewId: string) => void) {
+    this.externalWriteGuard = guard;
+  }
   constructor(private readonly db: DatabaseSync) {
     db.exec(`CREATE TABLE IF NOT EXISTS ask_conversations(
       id TEXT PRIMARY KEY,
@@ -104,7 +110,26 @@ export class AskHistory {
     );
   }
 
+  private assertWritable(reviewId: string) {
+    if (reviewId.startsWith("shared-")) this.externalWriteGuard?.(reviewId);
+
+    const row = this.db
+      .prepare("SELECT deleted_at FROM review_attention WHERE review_id=?")
+      .get(reviewId);
+
+    if (row?.deleted_at)
+      throw new ReviewInputError(
+        `This whiteboard was moved to Trash on ${new Date(String(row.deleted_at)).toLocaleDateString("en-US", { month: "short", day: "numeric" })}. Restore it with session_lifecycle({"sessionId":"${reviewId}","state":"active"}) to continue.`,
+        409,
+      );
+  }
+  private assertThreadWritable(id: string) {
+    const record = this.get(id);
+
+    if (record) this.assertWritable(record.reviewId);
+  }
   save(record: AskRecord) {
+    this.assertWritable(record.reviewId);
     this.db
       .prepare(
         `INSERT OR REPLACE INTO ask_conversations(id,review_id,agent,session_id,version,head,cwd,selection,title,created_at,updated_at,bypass)
@@ -128,6 +153,7 @@ export class AskHistory {
 
   /** Whether reopening the conversation bypasses permissions. */
   setBypass(id: string, bypass: boolean) {
+    this.assertThreadWritable(id);
     this.db
       .prepare("UPDATE ask_conversations SET bypass=? WHERE id=?")
       .run(bypass ? 1 : 0, id);
@@ -136,6 +162,7 @@ export class AskHistory {
   /** Points a conversation at a new session, when its agent could not
    * reopen the one it had. */
   updateSession(id: string, sessionId: string) {
+    this.assertThreadWritable(id);
     this.db
       .prepare("UPDATE ask_conversations SET session_id=? WHERE id=?")
       .run(sessionId, id);
@@ -143,6 +170,7 @@ export class AskHistory {
 
   /** Keeps what the panel shows, so a reopen need not wait on the agent. */
   saveEntries(id: string, entries: AskEntry[]) {
+    this.assertThreadWritable(id);
     this.db
       .prepare("UPDATE ask_conversations SET entries=? WHERE id=?")
       .run(JSON.stringify(entries), id);
@@ -150,6 +178,7 @@ export class AskHistory {
 
   /** The agent's name for the conversation, which the list shows. */
   rename(id: string, title: string) {
+    this.assertThreadWritable(id);
     this.db
       .prepare("UPDATE ask_conversations SET title=? WHERE id=?")
       .run(title.slice(0, 200), id);
@@ -197,6 +226,7 @@ export class AskHistory {
   }
 
   touch(id: string, at = new Date().toISOString()) {
+    this.assertThreadWritable(id);
     this.db
       .prepare("UPDATE ask_conversations SET updated_at=? WHERE id=?")
       .run(at, id);
@@ -236,7 +266,14 @@ export class AskHistory {
     return row ? rowSchema.parse(row) : undefined;
   }
 
+  removeReview(reviewId: string) {
+    this.db
+      .prepare("DELETE FROM ask_conversations WHERE review_id=?")
+      .run(reviewId);
+  }
+
   delete(id: string) {
+    this.assertThreadWritable(id);
     this.db.prepare("DELETE FROM ask_conversations WHERE id=?").run(id);
   }
 }

package/src/review-api/authoring-tools.ts

@@ -36,7 +36,7 @@ export function authoringTools(
 
   const descriptions = {
     create:
-      'Create a review of saved working files, immutable commits or a GitHub PR. Revisions are resolved on acceptance. A worktree target reviews the saved files in its checkout, uncommitted ones included and untracked ones left out (git add -N a new file to include it), against base: the branch to compare against, by default the default branch of the repository. The diff starts at the merge base of base and HEAD, which follows rebases. Omitted commits base means source at head with no diff; supply the parent to review introduced changes. For a GitHub PR, pullRequestUrl alone is enough: target and title become optional, and the host fetches the PR into a registered checkout of its repository and pins the current PR head and GitHub diff base, titled from the PR. When a review for that PR exists, it is returned instead, reporting whether its head moved and whether an agent is working on it; update it in place, move its target with review_set_target, or create a separate review with reuseExisting. kind:"scratchpad" names the one scratchpad, which the host creates itself. The result carries review, the review as review_list shows it: its target with resolved commits, origin (its PR), repositoryName and repositoryPath, so no follow-up read is needed before diffing. When Desktop is available the review opens there and the result reports opened, softwareMapEnabled and environmentIssues, as review_open does; set open:false to author in the background without taking over Desktop.',
+      'Create a review of saved working files, immutable commits or a GitHub PR. Revisions are resolved on acceptance. A worktree target reviews the saved files in its checkout, uncommitted ones included and untracked ones left out (git add -N a new file to include it), against base: the branch to compare against, by default the default branch of the repository. The diff starts at the merge base of base and HEAD, which follows rebases. Omitted commits base means source at head with no diff; supply the parent to review introduced changes. For a GitHub PR, pullRequestUrl alone is enough: target and title become optional, and the host fetches the PR into a registered checkout of its repository and pins the current PR head and GitHub diff base, titled from the PR. When the existing review for that PR is in Trash, creation reports its ID; restore it with review_lifecycle state:"active" before continuing. When an active review for that PR exists, it is returned instead, reporting whether its head moved and whether an agent is working on it; update it in place, move its target with review_set_target, or create a separate review with reuseExisting. kind:"scratchpad" names the one scratchpad, which the host creates itself. The result carries review, the review as review_list shows it: its target with resolved commits, origin (its PR), repositoryName and repositoryPath, so no follow-up read is needed before diffing. When Desktop is available the review opens there and the result reports opened, softwareMapEnabled and environmentIssues, as review_open does; set open:false to author in the background without taking over Desktop.',
     set_target:
       "Move the review to a new target, such as the commits after a rebase or amend, preserving the document and component IDs. Revisions are resolved on acceptance. Returns warnings for retained source ranges in files the new commits changed, to verify, and resources that no longer match; fix them with review_edit. Earlier versions keep their source. Omitted pullRequestUrl keeps the PR within the same repository; changing repositories clears it. Supply a URL to replace it or null to detach.",
     edit: [
@@ -52,8 +52,11 @@ export function authoringTools(
     restore:
       "Restore title, source pins, PR identity and content from a saved version.",
     attention:
-      "Mark a review viewed, dismissed or restored without changing its content.",
-    delete: "Permanently delete this review and its history.",
+      "Mark an active review viewed without changing its content or lifecycle. Restore a review from Trash before marking it viewed.",
+    lifecycle:
+      "Move a review between active and trash. Trash retains the review for 30 days before automatic deletion. Moving it back to active restores it; moving it to trash again does not restart that period.",
+    delete:
+      "Permanently delete a review and its history. The review must be in Trash. This cannot be undone.",
   };
 
   const tool = (
@@ -64,7 +67,7 @@ export function authoringTools(
     path: string,
     commandType?: string,
   ) => ({
-    name: `review_${name}`,
+    name: `review_${name === "restore" ? "restore_version" : name}`,
     description,
     inputSchema: {
       ...z.toJSONSchema(schema, { io: "input" }),
@@ -174,7 +177,7 @@ export function authoringTools(
     ),
     tool(
       "open",
-      "Show an existing review immediately and prepare current pinned checkouts in the background. Returns softwareMapEnabled and any already-recorded environmentIssues. Missing optional setup is not an issue; use review_environment to recheck.",
+      "Show an active review immediately; restore it from Trash before opening it. Prepare current pinned checkouts in the background. Returns softwareMapEnabled and any already-recorded environmentIssues. Missing optional setup is not an issue; use review_environment to recheck.",
       z.strictObject(review),
       "POST",
       "/:reviewId/open",

package/src/review-api/blocks/database_lens.ts

@@ -57,6 +57,11 @@ export const storeSchema = z.strictObject({
       label,
       key: label.optional(),
       fields: z.record(text, fieldSchema),
+      source: anchorSchema
+        .optional()
+        .describe(
+          "Where the table or collection is declared, such as its schema definition. Its use cases' tours start here.",
+        ),
     }),
   ),
 });

package/src/review-api/blocks/tutorial.ts

@@ -1,36 +1,20 @@
-import {
-  type TutorialAuthoringConversation,
-  tutorialAuthoringConversationSchema,
-} from "@review/tutorial-conversation.js";
 import { z } from "zod";
 
 import { type BlockDefinition, defineBlock } from "./definition.js";
-import { type Block, blockSchema } from "./index.js";
 
 type TutorialContent =
   | { kind: "keymap" }
-  | { kind: "conversation"; conversation: TutorialAuthoringConversation }
-  | { kind: "view"; view: "review" | "commits" | "diff" | "map"; label: string }
-  | { kind: "feature"; feature: "softwareMap"; children: Block[] };
+  | { kind: "view"; view: "diff"; label: string };
 
 export type TutorialBlock = { id?: string; type: "tutorial" } & TutorialContent;
 
 export const tutorialSchema = z.discriminatedUnion("kind", [
   defineBlock("tutorial", { kind: z.literal("keymap") }),
-  defineBlock("tutorial", {
-    kind: z.literal("conversation"),
-    conversation: tutorialAuthoringConversationSchema,
-  }),
   defineBlock("tutorial", {
     kind: z.literal("view"),
-    view: z.enum(["review", "commits", "diff", "map"]),
+    view: z.literal("diff"),
     label: z.string(),
   }),
-  defineBlock("tutorial", {
-    kind: z.literal("feature"),
-    feature: z.literal("softwareMap"),
-    children: z.array(z.lazy((): z.ZodType<Block> => blockSchema)),
-  }),
 ]);
 
 export const tutorial: BlockDefinition<TutorialBlock> = {

package/src/review-api/comparison-coverage.ts

@@ -151,11 +151,14 @@ export async function comparisonCoverage(
 
   if (mode === "textual") return coverage;
 
-  // Keep Git's totals and file identities while structural results add folding.
-  const publishCurrent = () =>
-    publish?.({ ...coverage, files: [...coverage.files] });
+  const unsupported = new Set<string>();
 
-  publishCurrent();
+  const current = () => ({
+    ...coverage,
+    files: coverage.files.filter((file) => !unsupported.has(file.path)),
+  });
+
+  publish?.(current());
 
   const baseFiles = new Map(
     coverage.files.map((file, index) => [
@@ -195,12 +198,18 @@ export async function comparisonCoverage(
     if (!remaining.delete(path))
       throw new Error(`Unexpected structural result: ${path}`);
 
+    const baseIndex = event.file.lhs && baseFiles.get(event.file.lhs.path);
+    const headIndex = event.file.rhs && headFiles.get(event.file.rhs.path);
+
     if (event.error) {
       if (
         event.error.code !== "unsupported_file_type" &&
         event.error.code !== "not_utf8"
       )
         throw new Error(`Cannot count ${path}: ${event.error.message}`);
+
+      for (const index of [baseIndex, headIndex])
+        if (index !== undefined) unsupported.add(coverage.files[index].path);
     } else if (event.diff.type === "text") {
       const diff = event.diff;
       const folded = foldedChanges(diff);
@@ -229,8 +238,6 @@ export async function comparisonCoverage(
         };
       }
 
-      const baseIndex = event.file.lhs && baseFiles.get(event.file.lhs.path);
-      const headIndex = event.file.rhs && headFiles.get(event.file.rhs.path);
       const index = headIndex ?? baseIndex;
 
       if (index !== undefined) {
@@ -249,16 +256,16 @@ export async function comparisonCoverage(
             structuralRows(diff),
           );
       }
-
-      publishCurrent();
     }
 
+    publish?.(current());
+
     if (!remaining.size) break;
   }
 
   if (remaining.size) throw new Error("Structural coverage is incomplete.");
 
-  return coverage;
+  return current();
 }
 
 /**

package/src/review-api/component-reference.ts

@@ -22,7 +22,7 @@ export const COMPONENT_REFERENCE = [
   "- call_stack_diff {title, base: frame[], head: frame[], pins?}; either side may be empty",
   "- frame {source: anchor, label?, key?, parentKey? (an earlier frame on that side), callSite?: anchor, contextSources?: anchor[], via?: {kind: call|queue|callback|rpc, reason}, pins?}",
   "- database_lens {title, actors: {key: label}, stores: {key: store}, useCases: useCase[] (1 or more), pins?}",
-  "- store {label, storage: relational|document, collections: {key: {label, fields: {key: field}}}, dataStoreKind?: database|objectStore|bucket|artifactStore|fileStore}",
+  "- store {label, storage: relational|document, collections: {key: {label, fields: {key: field}, source?: anchor of its schema declaration}}, dataStoreKind?: database|objectStore|bucket|artifactStore|fileStore}",
   "- field {label, dataType, nullable?, primaryKey?, references?: {store, collection, field}, fields?: {key: field}}",
   "- useCase {label, summary?, operations: operation[] (1 or more)}; operation {kind: read|write, actor, store, collection, label, source: anchor, field?, detail?, pins?}, naming declared keys",
   "",