@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/review/document.js

@@ -0,0 +1,138 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { documentLines } from '../document-lines.js';
+import { COMMENT_QUOTE_MAX, ReviewOperationError, } from './types.js';
+const REVIEW_SOURCE_MAX_BYTES = 2 * 1024 * 1024;
+function sourceUnreadable(file, phase, reason) {
+    throw new ReviewOperationError('source_unreadable', 'review source is unreadable', { phase, reason, file });
+}
+/** Read the reviewed document once, preserving the exact bytes used for its digest. */
+export function readReviewSource(file, phase = 'submit') {
+    let size;
+    try {
+        const stat = statSync(file);
+        if (!stat.isFile())
+            return sourceUnreadable(file, phase, 'unreadable');
+        size = stat.size;
+    }
+    catch (error) {
+        return sourceUnreadable(file, phase, error.code === 'ENOENT' ? 'missing' : 'unreadable');
+    }
+    if (size > REVIEW_SOURCE_MAX_BYTES)
+        return sourceUnreadable(file, phase, 'too_large');
+    let bytes;
+    try {
+        bytes = readFileSync(file);
+    }
+    catch (error) {
+        return sourceUnreadable(file, phase, error.code === 'ENOENT' ? 'missing' : 'unreadable');
+    }
+    if (bytes.length > REVIEW_SOURCE_MAX_BYTES)
+        return sourceUnreadable(file, phase, 'too_large');
+    if (bytes.includes(0))
+        return sourceUnreadable(file, phase, 'binary');
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return sourceUnreadable(file, phase, 'binary');
+    }
+    return {
+        bytes,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+        lines: documentLines(text),
+    };
+}
+function requireDocumentSource(review, expected_doc_hash) {
+    const source = readReviewSource(review.file, 'comment');
+    if (source.sha256 !== expected_doc_hash) {
+        throw new ReviewOperationError('stale_document', 'review document changed since it was rendered', {
+            reason: 'document_changed',
+            expected_sha256: expected_doc_hash,
+            actual_sha256: source.sha256,
+        });
+    }
+    if (source.sha256 !== review.anchor_base_sha256) {
+        throw new ReviewOperationError('stale_document', 'review comment ranges have not been remapped to the current document', {
+            reason: 'anchor_base_stale',
+            expected_sha256: review.anchor_base_sha256,
+            actual_sha256: source.sha256,
+        });
+    }
+    return source;
+}
+/** Require both the caller's rendered source and the persisted range coordinate base to be current. */
+export function requireCurrentDocument(review, expected_doc_hash) {
+    return requireDocumentSource(review, expected_doc_hash);
+}
+/** Verify a create-time source precondition from the review row held by the caller's canvas write transaction. */
+export function requireCurrentDocumentLocked(db, review_id, expected_doc_hash) {
+    const review = db.prepare('SELECT file, anchor_base_sha256 FROM reviews WHERE review_id = ?').get(review_id);
+    if (review === undefined) {
+        throw new ReviewOperationError('unknown_review', 'review was not found', { received: review_id });
+    }
+    return requireDocumentSource(review, expected_doc_hash);
+}
+/** Reject malformed ranges rather than normalizing them into a different anchor. */
+export function validateAnchorShape(anchor) {
+    const violations = [];
+    const hasStart = anchor.col_start !== undefined;
+    const hasEnd = anchor.col_end !== undefined;
+    if (!Number.isSafeInteger(anchor.line) || anchor.line < 1)
+        violations.push('line must be a positive integer');
+    if (!Number.isSafeInteger(anchor.end_line) || anchor.end_line < 1)
+        violations.push('end_line must be a positive integer');
+    if (Number.isSafeInteger(anchor.line) && Number.isSafeInteger(anchor.end_line) && anchor.end_line < anchor.line) {
+        violations.push('end_line must be greater than or equal to line');
+    }
+    if (hasStart !== hasEnd)
+        violations.push('col_start and col_end must be provided together');
+    if (hasStart && (!Number.isSafeInteger(anchor.col_start) || anchor.col_start < 0))
+        violations.push('col_start must be a non-negative integer');
+    if (hasEnd && (!Number.isSafeInteger(anchor.col_end) || anchor.col_end < 0))
+        violations.push('col_end must be a non-negative integer');
+    if (hasStart
+        && hasEnd
+        && anchor.line === anchor.end_line
+        && Number.isSafeInteger(anchor.col_start)
+        && Number.isSafeInteger(anchor.col_end)
+        && anchor.col_end <= anchor.col_start) {
+        violations.push('col_end must be greater than col_start for a single-line anchor');
+    }
+    if (anchor.quote !== undefined && typeof anchor.quote !== 'string')
+        violations.push('quote must be a string');
+    if (typeof anchor.quote === 'string' && Buffer.byteLength(anchor.quote, 'utf8') > COMMENT_QUOTE_MAX) {
+        violations.push(`quote exceeds ${COMMENT_QUOTE_MAX} bytes`);
+    }
+    if (violations.length > 0) {
+        throw new ReviewOperationError('invalid_anchor', 'comment anchor is invalid', { violations });
+    }
+}
+function isUtf8Boundary(bytes, offset) {
+    return offset === bytes.length || (bytes[offset] & 0xc0) !== 0x80;
+}
+/** Capture the full source range used to render an anchor, without silently clamping it. */
+export function captureAnchorText(lines, anchor) {
+    validateAnchorShape(anchor);
+    if (anchor.line > lines.length || anchor.end_line > lines.length) {
+        throw new ReviewOperationError('anchor_out_of_range', 'comment anchor exceeds the reviewed document', {
+            line_count: lines.length,
+            requested: { line: anchor.line, end_line: anchor.end_line },
+        });
+    }
+    if (anchor.col_start !== undefined && anchor.col_end !== undefined) {
+        const startLine = Buffer.from(lines[anchor.line - 1], 'utf8');
+        const endLine = Buffer.from(lines[anchor.end_line - 1], 'utf8');
+        if (anchor.col_start > startLine.length
+            || anchor.col_end > endLine.length
+            || !isUtf8Boundary(startLine, anchor.col_start)
+            || !isUtf8Boundary(endLine, anchor.col_end)) {
+            throw new ReviewOperationError('anchor_out_of_range', 'comment anchor columns exceed the reviewed document', {
+                line_count: lines.length,
+                requested: { line: anchor.line, end_line: anchor.end_line },
+            });
+        }
+    }
+    return lines.slice(anchor.line - 1, anchor.end_line).join('\n');
+}

package/dist/core/review/project.d.ts

@@ -0,0 +1,13 @@
+import type { FeedbackComment } from '../human/types.js';
+import type { ReviewRecord, ReviewResult } from './types.js';
+export interface ReviewCommentSnapshot {
+    comments: FeedbackComment[];
+    total: number;
+    unresolved: number;
+}
+/** Build the immutable approval result from the review row and one comment snapshot. */
+export declare function buildReviewResult(review: ReviewRecord, snapshot: ReviewCommentSnapshot, approvedSha256: string, at: string): ReviewResult;
+/** Project one immutable result to ticket/output or inline result surfaces. */
+export declare function projectReviewResult(review: ReviewRecord, result: ReviewResult): {
+    destinations: string[];
+};

package/dist/core/review/project.js

@@ -0,0 +1,58 @@
+import { join } from 'node:path';
+import { atomicWriteJson, publishJsonExclusive, responsePath } from '../human/convention.js';
+import { ticketDir } from '../human/root.js';
+import { reviewResultPath } from '../canvas/paths.js';
+/** Build the immutable approval result from the review row and one comment snapshot. */
+export function buildReviewResult(review, snapshot, approvedSha256, at) {
+    return {
+        schema: 'humanloop.review-response/v1',
+        review_id: review.review_id,
+        file: review.file,
+        submitted: true,
+        approved: true,
+        changed: approvedSha256 !== review.baseline_sha256,
+        baseline_sha256: review.baseline_sha256,
+        approved_sha256: approvedSha256,
+        companion_node_id: review.companion_node_id,
+        comments_total: snapshot.total,
+        comments_unresolved: snapshot.unresolved,
+        comments: snapshot.comments,
+        submittedAt: at,
+        savedAt: at,
+    };
+}
+/** Project one immutable result to ticket/output or inline result surfaces. */
+export function projectReviewResult(review, result) {
+    const destinations = [];
+    if (review.origin_kind === 'ticket') {
+        if (review.bridge_node_id === null)
+            throw new Error(`ticket review has no bridge node: ${review.review_id}`);
+        const dir = ticketDir(review.bridge_node_id);
+        const feedback = {
+            file: result.file,
+            submitted: result.submitted,
+            approved: result.approved,
+            comments: result.comments,
+            submittedAt: result.submittedAt,
+            savedAt: result.savedAt,
+            reviewId: result.review_id,
+            changed: result.changed,
+            baselineSha256: result.baseline_sha256,
+            approvedSha256: result.approved_sha256,
+            companionNodeId: result.companion_node_id,
+            commentsTotal: result.comments_total,
+            commentsUnresolved: result.comments_unresolved,
+        };
+        const response = responsePath(dir);
+        publishJsonExclusive(response, { schema: 'humanloop.review-response/v1', kind: 'review', result: feedback, completedAt: result.submittedAt });
+        destinations.push(response);
+        const output = review.output_path ?? join(dir, 'feedback.json');
+        atomicWriteJson(output, feedback);
+        destinations.push(output);
+        return { destinations };
+    }
+    const output = reviewResultPath(review.review_id);
+    atomicWriteJson(output, result);
+    destinations.push(output);
+    return { destinations };
+}

package/dist/core/review/realize.d.ts

@@ -0,0 +1,19 @@
+import type { NodeStatus } from '../canvas/types.js';
+import { type ReviewRecord } from './types.js';
+/**
+ * Finish a committed binding without ever recapturing its origin. Each step is
+ * safe to repeat after a crash; review.json is the final visibility switch.
+ */
+export declare function realizeReview(reviewId: string): Promise<ReviewRecord>;
+/**
+ * Reopen one already-open companion when needed. The surface only attaches to
+ * the returned node; it never owns a second revive path.
+ */
+export declare function openExistingReview(reviewId: string): Promise<{
+    review: ReviewRecord;
+    disposition: 'terminal';
+} | {
+    review: ReviewRecord;
+    companion_status: NodeStatus;
+    disposition: 'open';
+}>;

package/dist/core/review/realize.js

@@ -0,0 +1,217 @@
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { getNode, subscribersOf, subscribe } from '../canvas/index.js';
+import { withCanvasWrite } from '../canvas/db.js';
+import { atomicWriteJson } from '../human/convention.js';
+import { ticketDir } from '../human/root.js';
+import { submitReview } from '../human/tickets.js';
+import { isBrokerLive } from '../runtime/model-swap.js';
+import { NodeIdConflictError, spawnNode } from '../runtime/nodes.js';
+import { transition } from '../runtime/lifecycle.js';
+import { reviveNode } from '../runtime/revive.js';
+import { awaitCompanionBind, spawnReviewCompanion } from './companion.js';
+import { signalReviewActivity } from './signal.js';
+import { bindBridgeNode, getReview, openReviewRow } from './store.js';
+import { COMPANION_BIND_DEADLINE_MS, ReviewOperationError } from './types.js';
+function unknownReview(reviewId) {
+    return new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
+}
+function originMissing(originNodeId) {
+    return new ReviewOperationError('review_origin_missing', 'review origin was not found', {
+        origin_node_id: originNodeId,
+        reason: 'origin_missing',
+    });
+}
+function companionUnbound(reviewId, waitedMs) {
+    return new ReviewOperationError('review_companion_unbound', 'review companion did not bind in time', {
+        review_id: reviewId,
+        waited_ms: waitedMs,
+    });
+}
+function bridgeUnsubscribed(review, bridgeNodeId) {
+    return new ReviewOperationError('review_bridge_unsubscribed', 'review bridge is not subscribed to its origin', {
+        review_id: review.review_id,
+        bridge_node_id: bridgeNodeId,
+        origin_node_id: review.origin_node_id,
+    });
+}
+/** Cancel only a binding whose immutable branch has disappeared. No later pass may recapture it. */
+function cancelLostBinding(review) {
+    const canceled = withCanvasWrite((db) => db.prepare(`
+    UPDATE reviews
+    SET state = 'canceled', canceled_at = ?, cancel_reason = 'branch_lost', cancel_actor = NULL
+    WHERE review_id = ? AND state = 'binding'
+  `).run(new Date().toISOString(), review.review_id).changes > 0);
+    if (canceled)
+        signalReviewActivity();
+}
+function requireReview(reviewId) {
+    const review = getReview(reviewId);
+    if (review === null)
+        throw unknownReview(reviewId);
+    return review;
+}
+function requireOrigin(review) {
+    const origin = getNode(review.origin_node_id);
+    if (origin === null)
+        throw originMissing(review.origin_node_id);
+    return origin;
+}
+function spawnCompanion(review) {
+    if (getNode(review.companion_node_id) !== null)
+        return;
+    const origin = requireOrigin(review);
+    try {
+        spawnReviewCompanion({
+            nodeId: review.companion_node_id,
+            reviewId: review.review_id,
+            originNodeId: review.origin_node_id,
+            branchFile: review.branch_file,
+            targetFile: review.file,
+            modelSpec: review.model_spec,
+            cwd: origin.cwd,
+            profileId: origin.profile_id ?? null,
+        });
+    }
+    catch (error) {
+        if (!(error instanceof NodeIdConflictError))
+            throw error;
+    }
+}
+function cancelInvisibleBridge(nodeId) {
+    // A bridge which lost bindBridgeNode() was never exposed, so canceling it
+    // cannot produce a final report or notify the origin.
+    const node = getNode(nodeId);
+    if (node !== null && node.status !== 'done' && node.status !== 'canceled')
+        transition(nodeId, 'cancel');
+}
+/** Assert the only route a bridge has back to its origin before ticket exposure. */
+function ensureBridgeSubscription(review, bridgeNodeId) {
+    const hasActiveOrigin = () => subscribersOf(bridgeNodeId).some((subscriber) => subscriber.node_id === review.origin_node_id && subscriber.active);
+    if (!hasActiveOrigin())
+        subscribe(review.origin_node_id, bridgeNodeId, true);
+    if (!hasActiveOrigin())
+        throw bridgeUnsubscribed(review, bridgeNodeId);
+}
+/** R2: create/bind the ticket bridge and prove its active origin subscription. */
+function realizeBridge(review) {
+    if (review.origin_kind !== 'ticket')
+        return review;
+    let current = review;
+    if (current.bridge_node_id === null) {
+        const origin = requireOrigin(current);
+        const bridge = spawnNode({
+            kind: 'human',
+            lifecycle: 'terminal',
+            parent: current.origin_node_id,
+            cwd: origin.cwd,
+            profile_id: origin.profile_id ?? null,
+            name: 'human-review',
+        });
+        atomicWriteJson(join(ticketDir(bridge.node_id), 'run.json'), { mode: 'review' });
+        if (!bindBridgeNode(current.review_id, bridge.node_id)) {
+            cancelInvisibleBridge(bridge.node_id);
+            current = requireReview(current.review_id);
+        }
+        else {
+            current = requireReview(current.review_id);
+        }
+    }
+    if (current.bridge_node_id === null)
+        throw bridgeUnsubscribed(current, '');
+    ensureBridgeSubscription(current, current.bridge_node_id);
+    return current;
+}
+async function awaitAttachableCompanion(nodeId, deadlineMs) {
+    const deadline = Date.now() + deadlineMs;
+    for (;;) {
+        const companion = getNode(nodeId);
+        if (companion !== null && isBrokerLive(companion))
+            return true;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        await new Promise((resolveWait) => setTimeout(resolveWait, Math.min(100, remaining)));
+    }
+}
+function publishTicket(review) {
+    if (review.bridge_node_id === null)
+        throw bridgeUnsubscribed(review, '');
+    if (review.subtitle === null)
+        throw new Error(`ticket review has no subtitle: ${review.review_id}`);
+    submitReview({
+        dir: ticketDir(review.bridge_node_id),
+        review: {
+            file: review.file,
+            ...(review.output_path !== null ? { output: review.output_path } : {}),
+            title: basename(review.file),
+            subtitle: review.subtitle,
+            source: { nodeId: review.origin_node_id },
+            blockedSince: review.created,
+        },
+    });
+}
+/**
+ * Finish a committed binding without ever recapturing its origin. Each step is
+ * safe to repeat after a crash; review.json is the final visibility switch.
+ */
+export async function realizeReview(reviewId) {
+    let review = requireReview(reviewId);
+    if (review.state !== 'binding')
+        return review;
+    if (!existsSync(review.branch_file)) {
+        cancelLostBinding(review);
+        throw new ReviewOperationError('branch_lost', 'review branch was lost before realization', { review_id: review.review_id });
+    }
+    // R1: creation consumes only the persisted coordinates and preallocated id.
+    spawnCompanion(review);
+    // R2: ticket bridge birth and route assertion precede all public exposure.
+    review = realizeBridge(requireReview(reviewId));
+    if (review.state !== 'binding')
+        return review;
+    // R3: only realization owns this initial launch/retry.
+    const companion = getNode(review.companion_node_id);
+    if (companion === null)
+        throw companionUnbound(review.review_id, 0);
+    if (companion.pi_session_id === null)
+        reviveNode(companion.node_id, { resume: false });
+    // R4: session_start is the durable bind boundary.
+    if (!await awaitCompanionBind(review.companion_node_id, COMPANION_BIND_DEADLINE_MS)) {
+        throw companionUnbound(review.review_id, COMPANION_BIND_DEADLINE_MS);
+    }
+    // R5: SQLite visibility commits before the ticket projection. A missing
+    // projection is deliberately under-exposed and recovered by the startup sweep.
+    if (openReviewRow(review.review_id, new Date().toISOString())) {
+        signalReviewActivity();
+        if (review.origin_kind === 'ticket')
+            publishTicket(review);
+    }
+    return requireReview(reviewId);
+}
+/**
+ * Reopen one already-open companion when needed. The surface only attaches to
+ * the returned node; it never owns a second revive path.
+ */
+export async function openExistingReview(reviewId) {
+    const review = requireReview(reviewId);
+    if (review.state === 'binding')
+        throw unknownReview(reviewId);
+    if (review.state !== 'open')
+        return { review, disposition: 'terminal' };
+    const companion = getNode(review.companion_node_id);
+    if (companion === null)
+        throw companionUnbound(review.review_id, 0);
+    if (!isBrokerLive(companion))
+        reviveNode(companion.node_id, { resume: true });
+    if (!await awaitAttachableCompanion(review.companion_node_id, COMPANION_BIND_DEADLINE_MS)) {
+        throw companionUnbound(review.review_id, COMPANION_BIND_DEADLINE_MS);
+    }
+    const attachable = getNode(review.companion_node_id);
+    if (attachable === null)
+        throw companionUnbound(review.review_id, 0);
+    return {
+        review: requireReview(reviewId),
+        companion_status: attachable.status,
+        disposition: 'open',
+    };
+}

package/dist/core/review/remap.d.ts

@@ -0,0 +1,24 @@
+import { type CommentAnchor, type CommentAuthorKind } from './types.js';
+export interface RangeBatchEntry {
+    comment_id: string;
+    anchor?: CommentAnchor;
+    detached?: true;
+}
+interface Actor {
+    kind: CommentAuthorKind;
+    node_id: string | null;
+}
+/** Atomically replace every live review coordinate with ranges expressed against the current source. */
+export declare function applyRangeBatch(args: {
+    review_id: string;
+    from_doc_hash: string;
+    to_doc_hash: string;
+    entries: RangeBatchEntry[];
+    actor: Actor;
+    operation_id: string;
+}): {
+    updated: number;
+    detached: number;
+    anchor_base_sha256: string;
+};
+export {};

package/dist/core/review/remap.js

@@ -0,0 +1,156 @@
+import { withCanvasWrite } from '../canvas/db.js';
+import { nowIso } from '../fs-utils.js';
+import { signalReviewActivity } from './signal.js';
+import { replaceAnchorBaseLocked } from './store.js';
+import { ReviewOperationError, } from './types.js';
+import { captureAnchorText, readReviewSource, validateAnchorShape } from './document.js';
+function anchorFromRow(row) {
+    return {
+        line: row.anchor_line,
+        end_line: row.anchor_end_line,
+        ...(row.anchor_col_start === null ? {} : { col_start: row.anchor_col_start }),
+        ...(row.anchor_col_end === null ? {} : { col_end: row.anchor_col_end }),
+        ...(row.anchor_quote === null ? {} : { quote: row.anchor_quote }),
+    };
+}
+function rangeBatchStale(reason, expected, actual, comment_id) {
+    throw new ReviewOperationError('range_batch_stale', 'review comment ranges are stale', {
+        reason,
+        expected,
+        actual,
+        ...(comment_id === undefined ? {} : { comment_id }),
+    });
+}
+function validateEntry(entry) {
+    if (typeof entry.comment_id !== 'string' || entry.comment_id === '') {
+        throw new ReviewOperationError('invalid_anchor', 'comment anchor is invalid', {
+            violations: ['comment_id must be a non-empty string'],
+        });
+    }
+    const hasAnchor = entry.anchor !== undefined;
+    const detached = entry.detached === true;
+    if (hasAnchor === detached) {
+        throw new ReviewOperationError('invalid_anchor', 'comment anchor is invalid', {
+            violations: ['each range batch entry must provide exactly one of anchor or detached'],
+        });
+    }
+    if (hasAnchor)
+        validateAnchorShape(entry.anchor);
+}
+function appendReanchorEvent(db, args) {
+    db.prepare(`
+    INSERT INTO review_comment_events
+      (review_id, comment_id, kind, state_change, revision_after, actor_kind, actor_node_id, at, operation_id, payload)
+    SELECT review_id, ?, 'reanchored', 1, ?, ?, ?, ?, ?, ?
+    FROM review_comments WHERE comment_id = ?
+  `).run(args.row.comment_id, args.row.revision + 1, args.actor.kind, args.actor.node_id, args.at, args.operation_id, JSON.stringify({
+        previous_anchor: args.previous_anchor,
+        anchor: args.anchor,
+        previous_anchor_state: args.previous_anchor_state,
+        anchor_state: args.anchor_state,
+        previous_doc_hash: args.previous_doc_hash,
+        doc_hash: args.doc_hash,
+        line_text: args.line_text,
+    }), args.row.comment_id);
+}
+/** Atomically replace every live review coordinate with ranges expressed against the current source. */
+export function applyRangeBatch(args) {
+    const result = withCanvasWrite((db) => {
+        const review = db.prepare('SELECT file, anchor_base_sha256 FROM reviews WHERE review_id = ?').get(args.review_id);
+        if (review === undefined) {
+            throw new ReviewOperationError('unknown_review', 'review was not found', { received: args.review_id });
+        }
+        const source = readReviewSource(review.file, 'comment');
+        if (source.sha256 !== args.to_doc_hash)
+            rangeBatchStale('to_doc_hash', args.to_doc_hash, source.sha256);
+        if (review.anchor_base_sha256 !== args.from_doc_hash) {
+            rangeBatchStale('from_doc_hash', review.anchor_base_sha256, args.from_doc_hash);
+        }
+        const comments = db.prepare(`
+      SELECT comment_id, status, revision, text, anchor_line, anchor_end_line,
+             anchor_col_start, anchor_col_end, anchor_quote, anchor_line_text,
+             anchor_doc_hash, anchor_state
+      FROM review_comments
+      WHERE review_id = ? AND status != 'deleted'
+      ORDER BY created_seq
+    `).all(args.review_id);
+        for (const comment of comments) {
+            if (comment.anchor_doc_hash !== args.from_doc_hash) {
+                rangeBatchStale('comment_hash', args.from_doc_hash, comment.anchor_doc_hash, comment.comment_id);
+            }
+        }
+        const entries = new Map();
+        const extra = [];
+        for (const entry of args.entries) {
+            validateEntry(entry);
+            if (entries.has(entry.comment_id)) {
+                extra.push(entry.comment_id);
+            }
+            else {
+                entries.set(entry.comment_id, entry);
+            }
+        }
+        const commentIds = new Set(comments.map((comment) => comment.comment_id));
+        for (const commentId of entries.keys()) {
+            if (!commentIds.has(commentId))
+                extra.push(commentId);
+        }
+        const missing = comments.filter((comment) => !entries.has(comment.comment_id)).map((comment) => comment.comment_id);
+        if (missing.length > 0 || extra.length > 0) {
+            throw new ReviewOperationError('range_batch_incomplete', 'range batch must cover every non-deleted comment exactly once', {
+                missing,
+                extra,
+            });
+        }
+        let updated = 0;
+        let detached = 0;
+        const at = nowIso();
+        for (const comment of comments) {
+            const entry = entries.get(comment.comment_id);
+            const previousAnchor = anchorFromRow(comment);
+            const nextAnchor = entry.detached === true ? previousAnchor : entry.anchor;
+            const nextState = entry.detached === true ? 'detached' : 'live';
+            const nextLineText = entry.detached === true
+                ? comment.anchor_line_text
+                : captureAnchorText(source.lines, nextAnchor);
+            const changed = comment.anchor_state !== nextState
+                || comment.anchor_doc_hash !== source.sha256
+                || comment.anchor_line !== nextAnchor.line
+                || comment.anchor_end_line !== nextAnchor.end_line
+                || comment.anchor_col_start !== (nextAnchor.col_start ?? null)
+                || comment.anchor_col_end !== (nextAnchor.col_end ?? null)
+                || comment.anchor_quote !== (nextAnchor.quote ?? null)
+                || comment.anchor_line_text !== nextLineText;
+            if (!changed)
+                continue;
+            const revision = comment.revision + 1;
+            db.prepare(`
+        UPDATE review_comments
+        SET revision = ?, anchor_line = ?, anchor_end_line = ?, anchor_col_start = ?, anchor_col_end = ?,
+            anchor_quote = ?, anchor_line_text = ?, anchor_doc_hash = ?, anchor_state = ?,
+            updated_by_kind = ?, updated_by_node_id = ?, updated_at = ?
+        WHERE comment_id = ?
+      `).run(revision, nextAnchor.line, nextAnchor.end_line, nextAnchor.col_start ?? null, nextAnchor.col_end ?? null, nextAnchor.quote ?? null, nextLineText, source.sha256, nextState, args.actor.kind, args.actor.node_id, at, comment.comment_id);
+            appendReanchorEvent(db, {
+                row: comment,
+                actor: args.actor,
+                operation_id: args.operation_id,
+                at,
+                previous_anchor: previousAnchor,
+                anchor: nextAnchor,
+                previous_anchor_state: comment.anchor_state,
+                anchor_state: nextState,
+                previous_doc_hash: comment.anchor_doc_hash,
+                doc_hash: source.sha256,
+                line_text: nextLineText,
+            });
+            updated += 1;
+            if (nextState === 'detached')
+                detached += 1;
+        }
+        replaceAnchorBaseLocked(db, args.review_id, source.bytes, source.sha256);
+        return { updated, detached, anchor_base_sha256: source.sha256 };
+    });
+    signalReviewActivity();
+    return result;
+}

package/dist/core/review/signal.d.ts

@@ -0,0 +1,5 @@
+/** Signal one durable review mutation to every open viewer without watching every review directory. */
+export declare function reviewActivityPath(): string;
+/** Signal one review mutation (comment create/edit/resolve/delete/reanchor/delivery) to every open review surface. */
+export declare function signalReviewActivity(): void;
+export declare function watchReviewActivity(onChange: () => void): () => void;

package/dist/core/review/signal.js

@@ -0,0 +1,31 @@
+import { basename, dirname, join } from 'node:path';
+import { mkdirSync, watch, writeFileSync } from 'node:fs';
+import { crtrHome } from '../canvas/paths.js';
+/** Signal one durable review mutation to every open viewer without watching every review directory. */
+export function reviewActivityPath() {
+    return join(crtrHome(), 'signals', 'review-activity');
+}
+/** Signal one review mutation (comment create/edit/resolve/delete/reanchor/delivery) to every open review surface. */
+export function signalReviewActivity() {
+    try {
+        mkdirSync(dirname(reviewActivityPath()), { recursive: true, mode: 0o700 });
+        writeFileSync(reviewActivityPath(), `${Date.now()}\n`, { mode: 0o600 });
+    }
+    catch {
+        // A later review read is still authoritative.
+    }
+}
+export function watchReviewActivity(onChange) {
+    const activityPath = reviewActivityPath();
+    try {
+        mkdirSync(dirname(activityPath), { recursive: true, mode: 0o700 });
+        const watcher = watch(dirname(activityPath), (_event, filename) => {
+            if (String(filename) === basename(activityPath))
+                onChange();
+        });
+        return () => watcher.close();
+    }
+    catch {
+        return () => { };
+    }
+}