@hienlh/ppm 0.23.13 → 0.23.15

package/src/services/db-ai-tools/db-approval-broker.ts

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { DB_EXECUTE_APPROVAL, type DbApprovalAnswer, type DbExecuteApprovalInput } from "../../shared/db-ai-tools.ts";
+import { checkPpmPassword, ppmPasswordRequired } from "../ppm-password.ts";
+
+/**
+ * The server half of `db_execute`'s approval. The call waits here while the chat shows the user
+ * what would run (`ws/chat.ts` holds it as the session's pending approval, so a device that
+ * connects later sees it too, and sends the "Waiting for approval" notification), and the user
+ * answers over HTTP (`POST /api/db/ai-approvals/:requestId`, behind PPM's auth) with PPM's
+ * password typed again. A wrong password leaves the approval pending; a decline, the user
+ * sending a message or stopping the chat, or nobody answering in time settles it as declined.
+ *
+ * One approval per session at a time, and a session is known by the id it goes by now: Codex
+ * renames a new chat during its first turn, which can be while the approval waits.
+ */
+
+export type DbApprovalEvent = { type: "approval_request"; requestId: string; tool: typeof DB_EXECUTE_APPROVAL; input: DbExecuteApprovalInput };
+
+export interface DbApprovalChat {
+  /** Show the approval in the session's chat; false when this server has no chat for the session. */
+  announce(sessionId: string, event: DbApprovalEvent): boolean;
+  /** The approval was answered, or given up on: take it off the session's devices. */
+  resolved(sessionId: string, requestId: string, approved: boolean): void;
+}
+
+export type DbApprovalOutcome =
+  | { approved: true }
+  | { approved: false; reason: "declined" | "timeout" | "cancelled" | "no-chat" | "busy"; message: string };
+
+export type DbApprovalAnswerResult =
+  | { ok: true; approved: boolean }
+  | { ok: false; status: 400 | 403 | 404; error: string };
+
+/** How long the user has to answer. */
+export const DB_APPROVAL_WAIT_MS = 10 * 60_000;
+
+interface Pending {
+  sessionId: string;
+  event: DbApprovalEvent;
+  settle: (outcome: DbApprovalOutcome) => void;
+}
+
+export function createDbApprovalBroker(opts: {
+  chat: () => DbApprovalChat | null;
+  /** The id a session goes by now, following a provider's rename; the id itself by default. */
+  canonical?: (sessionId: string) => string;
+  passwordRequired?: () => boolean;
+  checkPassword?: (typed: unknown) => boolean;
+}) {
+  const canonical = opts.canonical ?? ((sessionId: string) => sessionId);
+  const passwordRequired = opts.passwordRequired ?? ppmPasswordRequired;
+  const checkPassword = opts.checkPassword ?? checkPpmPassword;
+  const pending = new Map<string, Pending>();
+
+  function pendingOf(sessionId: string): [string, Pending] | null {
+    const id = canonical(sessionId);
+    for (const entry of pending) if (canonical(entry[1].sessionId) === id) return entry;
+    return null;
+  }
+
+  /**
+   * Asks the user to approve `input` and waits for the answer. `signal` is the tool call's own
+   * request: a provider that gave up on the call (the user stopped the turn) settles it.
+   */
+  function request(asked: string, input: Omit<DbExecuteApprovalInput, "passwordRequired">, waitMs = DB_APPROVAL_WAIT_MS, signal?: AbortSignal): Promise<DbApprovalOutcome> {
+    const sessionId = canonical(asked);
+    if (signal?.aborted) return Promise.resolve({ approved: false, reason: "cancelled", message: "The call was cancelled before the user was asked, so nothing ran." });
+    if (pendingOf(sessionId)) {
+      return Promise.resolve({ approved: false, reason: "busy", message: "Another change is already waiting for the user's approval in this chat; wait for its answer, then call again." });
+    }
+    const requestId = randomUUID();
+    const event: DbApprovalEvent = { type: "approval_request", requestId, tool: DB_EXECUTE_APPROVAL, input: { ...input, passwordRequired: passwordRequired() } };
+    return new Promise<DbApprovalOutcome>((done) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const onAbort = () => settle({ approved: false, reason: "cancelled", message: "The call was cancelled before the user answered, so nothing ran." });
+      const settle = (outcome: DbApprovalOutcome): void => {
+        const entry = pending.get(requestId);
+        if (!entry) return;
+        pending.delete(requestId);
+        if (timer) clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        try {
+          opts.chat()?.resolved(canonical(entry.sessionId), requestId, outcome.approved);
+        } catch (e) {
+          console.warn(`[db-tools] clearing approval ${requestId} failed: ${(e as Error).message}`);
+        }
+        done(outcome);
+      };
+      pending.set(requestId, { sessionId, event, settle });
+      signal?.addEventListener("abort", onAbort, { once: true });
+      let shown = false;
+      try {
+        shown = opts.chat()?.announce(sessionId, event) ?? false;
+      } catch (e) {
+        console.warn(`[db-tools] announcing approval failed for session=${sessionId}: ${(e as Error).message}`);
+      }
+      if (!shown) {
+        settle({
+          approved: false, reason: "no-chat",
+          message: "This chat is not open in PPM's web UI, so the user cannot be asked to approve the change. Nothing ran; give the user the SQL to run themselves.",
+        });
+        return;
+      }
+      timer = setTimeout(() => settle({
+        approved: false, reason: "timeout",
+        message: `The user did not answer within ${Math.round(waitMs / 60_000)} minutes, so nothing ran.`,
+      }), waitMs);
+    });
+  }
+
+  /** The user's answer, from the approval card. A wrong password leaves the approval pending. */
+  function answer(requestId: string, body: Partial<DbApprovalAnswer> | null): DbApprovalAnswerResult {
+    const entry = pending.get(requestId);
+    if (!entry) return { ok: false, status: 404, error: "This approval is no longer waiting: it was answered, cancelled or timed out." };
+    if (!body || typeof body.approved !== "boolean") return { ok: false, status: 400, error: "approved must be true or false" };
+    if (!body.approved) {
+      entry.settle({ approved: false, reason: "declined", message: "The user declined the change, so nothing ran." });
+      return { ok: true, approved: false };
+    }
+    if (!checkPassword(body.password)) return { ok: false, status: 403, error: "Wrong password" };
+    entry.settle({ approved: true });
+    return { ok: true, approved: true };
+  }
+
+  /** Declines the session's pending approval, if it has one; true when it had. */
+  function cancelSession(sessionId: string, message: string): boolean {
+    const found = pendingOf(sessionId);
+    if (!found) return false;
+    found[1].settle({ approved: false, reason: "cancelled", message });
+    return true;
+  }
+
+  return {
+    request,
+    answer,
+    cancelSession,
+    /** Whether `requestId` is one of these approvals, still pending. */
+    has: (requestId: string) => pending.has(requestId),
+    /** The session's pending approval as the chat shows it, or null. */
+    pendingEvent: (sessionId: string): DbApprovalEvent | null => pendingOf(sessionId)?.[1].event ?? null,
+    pendingCount: () => pending.size,
+  };
+}
+
+let chat: DbApprovalChat | null = null;
+let resolveSession: (sessionId: string) => string = (sessionId) => sessionId;
+
+/** `ws/chat.ts` owns the chats; it registers how to show an approval and how to follow a renamed session. */
+export function setDbApprovalChat(fn: DbApprovalChat | null, canonical?: (sessionId: string) => string): void {
+  chat = fn;
+  resolveSession = canonical ?? ((sessionId) => sessionId);
+}
+
+export const dbApprovalBroker = createDbApprovalBroker({
+  chat: () => chat,
+  canonical: (sessionId) => resolveSession(sessionId),
+});

package/src/services/db.service.ts

@@ -14,7 +14,7 @@ const log = createLogger("db");
 const proxyLog = createLogger("proxy");
 // Must equal the last `PRAGMA user_version` below: the pre-migration snapshot is skipped for
 // any database already at this version, so a stale value silently drops that backup.
-export const CURRENT_SCHEMA_VERSION = 56;
+export const CURRENT_SCHEMA_VERSION = 57;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -1259,6 +1259,30 @@ export function runMigrations(database: Database): void {
     try { database.exec("ALTER TABLE connections ADD COLUMN ai_access INTEGER NOT NULL DEFAULT 1"); } catch { /* column exists */ }
     database.exec(`PRAGMA user_version = 56;`);
   }
+
+  if (current < 57) {
+    // Design share links. The code a reviewer holds is derived from a secret file and the
+    // link id, so only its hash is kept: a copied database or backup opens no link.
+    // `project_key` is the folded path the rows are looked up by (case-insensitive on Windows).
+    database.exec(`
+      CREATE TABLE IF NOT EXISTS design_share_links (
+        id TEXT PRIMARY KEY,
+        code_hash TEXT NOT NULL UNIQUE,
+        code_version INTEGER NOT NULL DEFAULT 1,
+        project_path TEXT NOT NULL,
+        project_key TEXT NOT NULL,
+        slug TEXT NOT NULL,
+        snapshot_id TEXT NOT NULL,
+        label TEXT NOT NULL DEFAULT '',
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        expires_at INTEGER,
+        revoked_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_design_share_links_design ON design_share_links(project_key, slug);
+    `);
+    database.exec(`PRAGMA user_version = 57;`);
+  }
 }
 
 /**

package/src/services/design/bridge/bridge-picker.ts

@@ -17,7 +17,8 @@ import type { BridgeApi } from "./bridge-core.ts";
  * The long-press is disarmed on `touchmove` past 10 px, on `touchend` and on `touchcancel`:
  * once the browser takes the gesture for a scroll it fires `touchcancel` and delivers no
  * further move or end, and a timer left armed would open the composer over a list the
- * finger is already scrolling.
+ * finger is already scrolling. A long-press that did fire cancels its `touchend`, so lifting
+ * the finger makes no click on the composer that opened under it.
  *
  * Shipped as source, so it may only use what it is handed in `ppm`.
  */
@@ -141,12 +142,21 @@ export function installPicker(ppm: BridgeApi): void {
     if (!press || !t) return;
     if (Math.abs(t.clientX - press.x) > MOVE_TOLERANCE || Math.abs(t.clientY - press.y) > MOVE_TOLERANCE) disarm();
   }, { capture: true, passive: true });
-  win.addEventListener("touchend", () => {
+  // Not passive: a completed long-press has to cancel its touchend.
+  win.addEventListener("touchend", (event: TouchEvent) => {
     lastTouchAt = Date.now();
-    // The click that follows a completed long-press is not a tap.
-    if (press && press.fired) swallowClicksUntil = lastTouchAt + TOUCH_WINDOW_MS;
+    if (press && press.fired) {
+      // Lifting the finger after a long-press is no tap, but a browser whose own long-press
+      // takes longer than ours (1 s in desktop Chromium) still reads it as one. The composer
+      // has opened under the finger by then, and where the browser hit-tests that tap when it
+      // ends rather than where it began, the click lands on the composer's backdrop and closes
+      // it the moment it opened. A cancelled touchend makes no click at all; a browser that
+      // sends one anyway sends it here, where it is swallowed.
+      if (event.cancelable) event.preventDefault();
+      swallowClicksUntil = lastTouchAt + TOUCH_WINDOW_MS;
+    }
     disarm();
-  }, { capture: true, passive: true });
+  }, { capture: true, passive: false });
   win.addEventListener("touchcancel", disarm, { capture: true, passive: true });
 
   win.addEventListener("keydown", (event: KeyboardEvent) => {

package/src/services/design/bridge/guest-bridge.ts

@@ -0,0 +1,19 @@
+import { assembleBridge, assertInlineScript } from "./bridge-script.ts";
+import { installNavGuard } from "./bridge-nav-guard.ts";
+import { installPicker } from "./bridge-picker.ts";
+import { installPins } from "./bridge-pins.ts";
+import { anchorOf, cssPathOf, describeElement, domTreeAccess, elementQuote } from "./bridge-element-info.ts";
+import { diceSimilarity, resolveAnchor } from "./bridge-anchor-resolve.ts";
+import { createPickerOverlay } from "./bridge-picker-overlay.ts";
+
+/**
+ * The bridge a reviewer's view of a shared design gets: the core, the element picker, the
+ * comment pins and the navigation guard. Nothing that moves, resizes, tweaks or undoes —
+ * those features are what propose a write to the design, and a reviewer's frame has no
+ * write to propose. The lib carries exactly the helpers these three features call.
+ */
+export const GUEST_BRIDGE_JS = assembleBridge([installPicker, installPins, installNavGuard], {
+  anchorOf, describeElement, diceSimilarity, resolveAnchor, createPickerOverlay, cssPathOf, elementQuote, domTreeAccess,
+});
+
+assertInlineScript(GUEST_BRIDGE_JS, "guest design bridge");

package/src/services/design/comments/design-comment-element-context.ts

@@ -1,7 +1,7 @@
 import {
   COMMENT_LIMITS, stripHtmlComments, type CommentAnchor, type CommentQuote,
 } from "../../../shared/design-comment-types.ts";
-import { resolveScopedPath } from "../preview/design-preview-scope.ts";
+import { resolveScopedPath, resolveSnapshotScopedPath } from "../preview/design-preview-scope.ts";
 import { readDesignSource, type DesignSource } from "../source/design-source-file.ts";
 import { elementSourceRange } from "../source/element-source-range.ts";
 import { diceSimilarity, resolveAnchor } from "../bridge/bridge-anchor-resolve.ts";
@@ -25,12 +25,27 @@ export interface ElementContext {
   quote: CommentQuote;
 }
 
-/** The HTML file a comment is on: inside the design, no dot-directories, `.html`/`.htm`. */
-export async function resolveCommentFile(projectPath: string, slug: string, file: string): Promise<string> {
+/** Which copy of the design an element is read from: the live folder unless a snapshot is named. */
+export interface ElementSourceOptions {
+  snapshotId?: string;
+}
+
+/**
+ * The HTML file a comment is on: inside the design, no dot-directories, `.html`/`.htm`. With
+ * a `snapshotId`, the file inside that snapshot instead, which is what a reviewer was shown.
+ */
+export async function resolveCommentFile(
+  projectPath: string, slug: string, file: string, opts: ElementSourceOptions = {},
+): Promise<string> {
   if (!/\.html?$/i.test(file) || file.startsWith("/") || file.split("/").includes("..")) {
     throw new DesignError(400, "EBADFILE", "A comment must be on an HTML file of the design");
   }
-  return (await resolveScopedPath({ projectPath, slug }, `${slug}/${file}`)).abs;
+  const design = { projectPath, slug };
+  const path = `${slug}/${file}`;
+  const asset = opts.snapshotId === undefined
+    ? await resolveScopedPath(design, path)
+    : await resolveSnapshotScopedPath(design, opts.snapshotId, path);
+  return asset.abs;
 }
 
 export function capSnippet(markup: string): string {
@@ -49,8 +64,15 @@ async function readSource(abs: string): Promise<DesignSource | null> {
   }
 }
 
-export async function elementContext(projectPath: string, slug: string, anchor: CommentAnchor): Promise<ElementContext> {
-  const abs = await resolveCommentFile(projectPath, slug, anchor.file);
+/**
+ * A non-null `snippet` means the anchor's `ppmId` and `gen` were confirmed against the file
+ * read — the live one, or the named snapshot's. Re-anchoring ({@link validateReanchor}) is
+ * always against the live file.
+ */
+export async function elementContext(
+  projectPath: string, slug: string, anchor: CommentAnchor, opts: ElementSourceOptions = {},
+): Promise<ElementContext> {
+  const abs = await resolveCommentFile(projectPath, slug, anchor.file, opts);
   const source = await readSource(abs);
   if (!source || anchor.ppmId === null || anchor.gen !== source.gen) return { snippet: null, quote: anchor.quote };
   const range = elementSourceRange(source.text, anchor.ppmId);

package/src/services/design/comments/design-comment-input.ts

@@ -0,0 +1,47 @@
+import { COMMENT_LIMITS } from "../../../shared/design-comment-types.ts";
+import {
+  GUEST_KEY_HASH_RE, parseGuestName, SHARE_LINK_ID_RE, type StoredCommentAuthor, type StoredGuestAuthor,
+} from "../../../shared/design-comment-thread-types.ts";
+import { emitDesignEvent } from "../design-events.ts";
+import { DesignError } from "../design-error.ts";
+import { bumpCommentsRevision } from "./design-comments-revision.ts";
+import type { CommentActor, GuestIdentity } from "./design-comment-views.ts";
+
+/** Input checks and refusals shared by the root-comment and reply services. */
+
+export type Raw = Record<string, unknown>;
+export const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
+export const badRequest = (message: string): DesignError => new DesignError(400, "EBADCOMMENT", message);
+export const notFound = (): DesignError => new DesignError(404, "ENOENT", "Comment not found");
+export const tooMany = (message: string): DesignError => new DesignError(409, "ETOOMANY", message);
+export const notYours = (): DesignError => new DesignError(403, "ENOTYOURS", "You can only change your own comments");
+export const guestTextIsTheirs = (): DesignError => new DesignError(403, "ENOTYOURS", "A reviewer's text can only be edited by them");
+
+export function parseBody(v: unknown, required: boolean): string | undefined {
+  if (v === undefined && !required) return undefined;
+  if (typeof v !== "string" || !v.trim()) throw badRequest("A comment needs some text");
+  if (v.length > COMMENT_LIMITS.body) throw badRequest(`A comment is at most ${COMMENT_LIMITS.body} characters`);
+  return v.trim();
+}
+
+export function commentsChanged(projectPath: string, slug: string): void {
+  bumpCommentsRevision(projectPath, slug);
+  emitDesignEvent("comments_changed", { projectPath, slug });
+}
+
+/** The guest identity of an actor (checked), or null for the owner. */
+export function guestOf(actor: CommentActor | undefined): GuestIdentity | null {
+  if (!actor || actor.kind === "owner") return null;
+  if (!SHARE_LINK_ID_RE.test(actor.linkId) || !GUEST_KEY_HASH_RE.test(actor.keyHash)) throw badRequest("Invalid reviewer");
+  return { linkId: actor.linkId, keyHash: actor.keyHash };
+}
+
+/** The author a new entry is stored with; a guest needs a valid name. */
+export function newAuthor(actor: CommentActor | undefined): StoredCommentAuthor {
+  if (!actor || actor.kind === "owner") return { kind: "owner" };
+  const who = guestOf(actor)!;
+  const name = parseGuestName(actor.name);
+  if (!name.ok) throw badRequest(name.error);
+  const author: StoredGuestAuthor = { kind: "guest", name: name.name, linkId: who.linkId, keyHash: who.keyHash };
+  return author;
+}

package/src/services/design/comments/design-comment-views.ts

@@ -0,0 +1,146 @@
+import { COMMENT_LIMITS, type CommentAuthor } from "../../../shared/design-comment-types.ts";
+import {
+  REMOVED_LINK_LABEL,
+  type DesignCommentGuestView, type DesignCommentOwnerView, type OwnerViewAuthor,
+  type StoredCommentAuthor, type StoredCommentReply, type StoredDesignComment,
+} from "../../../shared/design-comment-thread-types.ts";
+
+/**
+ * Who may see and change which comment, how many each party may write, and what each side
+ * is shown. Pure: the service applies these under the design lock, to the list it just read.
+ *
+ * A guest's key hash never appears in either view. The owner sees which link a reviewer came
+ * through; a reviewer sees names and whether an entry is their own, nothing more.
+ */
+
+/** A reviewer, as the guest routes identify one: their link and the hash of their key. */
+export interface GuestIdentity {
+  linkId: string;
+  keyHash: string;
+}
+
+/** Who is making a change. A guest's `name` is needed only to write something new. */
+export type CommentActor = { kind: "owner" } | ({ kind: "guest"; name?: string } & GuestIdentity);
+
+type Authored = { author?: StoredCommentAuthor };
+
+export function isOwnerEntry(entry: Authored): boolean {
+  return !entry.author || entry.author.kind === "owner";
+}
+
+export function isMine(entry: Authored, who: GuestIdentity): boolean {
+  const a = entry.author;
+  return a?.kind === "guest" && a.linkId === who.linkId && a.keyHash === who.keyHash;
+}
+
+/**
+ * A reviewer sees a thread only when a reviewer on the same link started it. Links are
+ * isolated from one another, and the owner's own notes are never shown to anyone.
+ */
+export function visibleToLink(root: Authored, linkId: string): boolean {
+  return root.author?.kind === "guest" && root.author.linkId === linkId;
+}
+
+/** A guest may delete their own root only while nobody has replied; after that it is edit-only. */
+export function guestMayDeleteRoot(root: StoredDesignComment, who: GuestIdentity): boolean {
+  return isMine(root, who) && !root.replies?.length;
+}
+
+/** Guest entries (roots and replies) in the list, all of them or one link's. */
+export function countGuestEntries(comments: readonly StoredDesignComment[], linkId?: string): number {
+  const counts = (a: StoredCommentAuthor | undefined) => a?.kind === "guest" && (linkId === undefined || a.linkId === linkId);
+  let n = 0;
+  for (const c of comments) {
+    if (counts(c.author)) n++;
+    for (const r of c.replies ?? []) if (counts(r.author)) n++;
+  }
+  return n;
+}
+
+export function countOwnerRoots(comments: readonly StoredDesignComment[]): number {
+  return comments.filter(isOwnerEntry).length;
+}
+
+/**
+ * Why `author` may not add a root (no `thread`) or a reply to `thread`, or null when it may.
+ * The owner's roots have a cap of their own, so reviewers filling theirs never lock the owner
+ * out; the owner's replies in a reviewer's thread count against no reviewer cap.
+ */
+export function quotaRefusal(
+  comments: readonly StoredDesignComment[],
+  author: StoredCommentAuthor | undefined,
+  thread?: StoredDesignComment,
+): string | null {
+  if (thread && (thread.replies?.length ?? 0) >= COMMENT_LIMITS.maxReplies) {
+    return `A thread holds at most ${COMMENT_LIMITS.maxReplies} replies`;
+  }
+  if (author?.kind === "guest") {
+    if (countGuestEntries(comments, author.linkId) >= COMMENT_LIMITS.maxGuestEntriesPerLink) {
+      return `A share link holds at most ${COMMENT_LIMITS.maxGuestEntriesPerLink} comments and replies`;
+    }
+    if (countGuestEntries(comments) >= COMMENT_LIMITS.maxGuestEntries) {
+      return `A design holds at most ${COMMENT_LIMITS.maxGuestEntries} reviewer comments and replies`;
+    }
+    return null;
+  }
+  if (!thread && countOwnerRoots(comments) >= COMMENT_LIMITS.maxComments) {
+    return `A design holds at most ${COMMENT_LIMITS.maxComments} comments; delete resolved ones first`;
+  }
+  return null;
+}
+
+function ownerAuthor(a: StoredCommentAuthor | undefined, labels: ReadonlyMap<string, string>): OwnerViewAuthor {
+  if (!a || a.kind === "owner") return { kind: "owner" };
+  return { kind: "guest", name: a.name, linkId: a.linkId, linkLabel: labels.get(a.linkId) ?? REMOVED_LINK_LABEL };
+}
+
+function guestAuthor(a: StoredCommentAuthor | undefined): CommentAuthor {
+  return !a || a.kind === "owner" ? { kind: "owner" } : { kind: "guest", name: a.name };
+}
+
+/** The owner's view: every field but the key hash, and each guest's link by its label. */
+export function toOwnerView(c: StoredDesignComment, linkLabels: ReadonlyMap<string, string>): DesignCommentOwnerView {
+  const { author, replies, ...rest } = c;
+  return {
+    ...rest,
+    author: ownerAuthor(author, linkLabels),
+    replies: (replies ?? []).map((r: StoredCommentReply) => ({
+      id: r.id, body: r.body, author: ownerAuthor(r.author, linkLabels), createdAt: r.createdAt, updatedAt: r.updatedAt,
+    })),
+  };
+}
+
+/**
+ * A reviewer's view of one thread on `link`. Built field by field, so nothing added to the
+ * stored shape later reaches a reviewer by accident. The anchor's `ppmId`/`gen` come from
+ * the pinned anchor only, and only while the link still shows the snapshot it was made on:
+ * the stored ones follow the owner's live file and mean nothing in the snapshot.
+ */
+export function toGuestView(
+  c: StoredDesignComment, link: { id: string; snapshotId: string }, keyHash: string,
+): DesignCommentGuestView {
+  const who = { linkId: link.id, keyHash };
+  const pinned = c.pinnedAnchor?.snapshotId === link.snapshotId ? c.pinnedAnchor : null;
+  const view: DesignCommentGuestView = {
+    id: c.id,
+    file: c.file,
+    anchor: { ...c.anchor, ppmId: pinned?.ppmId ?? null, gen: pinned?.gen ?? null },
+    body: c.body,
+    createdAt: c.createdAt,
+    updatedAt: c.updatedAt,
+    author: guestAuthor(c.author),
+    mine: isMine(c, who),
+    replies: (c.replies ?? []).map((r) => ({
+      id: r.id, body: r.body, author: guestAuthor(r.author), createdAt: r.createdAt, updatedAt: r.updatedAt, mine: isMine(r, who),
+    })),
+  };
+  if (c.resolvedAt) view.resolvedAt = c.resolvedAt;
+  return view;
+}
+
+/** Every thread a reviewer on `link` may see, in their view. */
+export function guestThreads(
+  comments: readonly StoredDesignComment[], link: { id: string; snapshotId: string }, keyHash: string,
+): DesignCommentGuestView[] {
+  return comments.filter((c) => visibleToLink(c, link.id)).map((c) => toGuestView(c, link, keyHash));
+}

package/src/services/design/comments/design-comments-revision.ts

@@ -0,0 +1,19 @@
+import { designLockKey } from "../design-lock.ts";
+
+/**
+ * A per-design counter, bumped every time a comment change is announced. It lets a poll be
+ * answered "unchanged" from memory and one `stat`, without reading `comments.json`. It is
+ * lost on restart, which is why a reader pairs it with a per-boot id and the file's own
+ * mtime and size rather than trusting it alone.
+ */
+
+const revisions = new Map<string, number>();
+
+export function bumpCommentsRevision(projectPath: string, slug: string): void {
+  const key = designLockKey(projectPath, slug);
+  revisions.set(key, (revisions.get(key) ?? 0) + 1);
+}
+
+export function commentsRevision(projectPath: string, slug: string): number {
+  return revisions.get(designLockKey(projectPath, slug)) ?? 0;
+}