@north-light/crouter 0.3.170 → 0.3.172

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

@@ -0,0 +1,69 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type CommentAnchor, type CommentAuthorKind, type CommentStatus, type ReviewComment, type ReviewCommentEvent } from './types.js';
+interface Actor {
+    kind: CommentAuthorKind;
+    node_id: string | null;
+}
+interface CommentMutationArgs {
+    actor: Actor;
+    operation_id: string;
+    if_revision?: number;
+}
+export declare function createComment(args: {
+    review_id: string;
+    text: string;
+    anchor: CommentAnchor;
+    line_text: string;
+    doc_hash: string;
+    actor: Actor;
+    operation_id: string;
+}): {
+    comment: ReviewComment;
+    changed: true;
+};
+export declare function editComment(commentIdValue: string, args: {
+    text: string;
+    actor: Actor;
+    operation_id: string;
+    if_revision?: number;
+}): {
+    comment: ReviewComment;
+    changed: boolean;
+};
+export declare function resolveComment(commentIdValue: string, args: CommentMutationArgs): {
+    comment: ReviewComment;
+    changed: boolean;
+};
+export declare function reopenComment(commentIdValue: string, args: CommentMutationArgs): {
+    comment: ReviewComment;
+    changed: boolean;
+};
+export declare function deleteComment(commentIdValue: string, args: CommentMutationArgs): {
+    comment: ReviewComment;
+    changed: boolean;
+};
+export declare function listComments(reviewId: string, opts?: {
+    status?: CommentStatus | 'all';
+}): ReviewComment[];
+export declare function getComment(commentIdValue: string): ReviewComment | null;
+export declare function listCommentEvents(commentIdValue: string): ReviewCommentEvent[];
+export declare function listReviewEvents(reviewId: string, opts: {
+    since_seq?: number;
+    limit?: number;
+}): {
+    events: ReviewCommentEvent[];
+    next_since_seq: number;
+};
+export declare function snapshotCommentsLocked(db: DatabaseSync, reviewId: string): {
+    comments: import('../human/types.js').FeedbackComment[];
+    total: number;
+    unresolved: number;
+};
+export declare function appendDeliveryEvent(args: {
+    review_id: string;
+    comment_id: string;
+    kind: 'notified' | 'notify_failed';
+    payload: unknown;
+    operation_id: string;
+}): void;
+export {};

package/dist/core/review/comments.js

@@ -0,0 +1,295 @@
+import { randomBytes } from 'node:crypto';
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { nowIso } from '../fs-utils.js';
+import { signalReviewActivity } from './signal.js';
+import { COMMENT_EVENTS_PAGE_DEFAULT, COMMENT_EVENTS_PAGE_MAX, COMMENT_LINE_TEXT_MAX, COMMENT_TEXT_MAX, LIVE_COMMENTS_MAX, ReviewOperationError, } from './types.js';
+function commentFromRow(row) {
+    return {
+        comment_id: row.comment_id,
+        review_id: row.review_id,
+        status: row.status,
+        revision: row.revision,
+        text: row.text,
+        anchor: {
+            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 }),
+        },
+        anchor_state: row.anchor_state,
+        anchor_line_text: row.anchor_line_text,
+        anchor_doc_hash: row.anchor_doc_hash,
+        author: { kind: row.author_kind, node_id: row.author_node_id },
+        updated_by: { kind: row.updated_by_kind, node_id: row.updated_by_node_id },
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        resolved_at: row.resolved_at,
+        deleted_at: row.deleted_at,
+        created_seq: row.created_seq,
+    };
+}
+function eventFromRow(row) {
+    return {
+        seq: row.seq,
+        review_id: row.review_id,
+        comment_id: row.comment_id,
+        kind: row.kind,
+        state_change: row.state_change === 0 ? 0 : 1,
+        revision_after: row.revision_after,
+        actor: { kind: row.actor_kind, node_id: row.actor_node_id },
+        at: row.at,
+        operation_id: row.operation_id,
+        ...(row.payload === null ? {} : { payload: JSON.parse(row.payload) }),
+    };
+}
+function json(value) {
+    return JSON.stringify(value);
+}
+function commentId() {
+    let id;
+    do
+        id = randomBytes(16).toString('hex');
+    while (/^0+$/.test(id));
+    return id;
+}
+function trimText(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        throw new Error('comment text must not be empty');
+    const received = Buffer.byteLength(trimmed, 'utf8');
+    if (received > COMMENT_TEXT_MAX) {
+        throw new ReviewOperationError('text_too_long', 'comment text exceeds the maximum length', {
+            limit: COMMENT_TEXT_MAX,
+            received,
+        });
+    }
+    return trimmed;
+}
+function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text, 'utf8') <= maxBytes)
+        return text;
+    const marker = '… [truncated]';
+    const markerBytes = Buffer.byteLength(marker, 'utf8');
+    const bytes = Buffer.from(text, 'utf8');
+    let end = Math.max(0, maxBytes - markerBytes);
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return `${bytes.subarray(0, end).toString('utf8')}${marker}`;
+}
+function getStoredComment(db, commentIdValue) {
+    return db.prepare('SELECT * FROM review_comments WHERE comment_id = ?').get(commentIdValue) ?? null;
+}
+function requireStoredComment(db, commentIdValue) {
+    const row = getStoredComment(db, commentIdValue);
+    if (row === null) {
+        throw new ReviewOperationError('unknown_comment', 'comment was not found', { received: commentIdValue });
+    }
+    return row;
+}
+function assertReviewExists(db, reviewId) {
+    const row = db.prepare('SELECT review_id FROM reviews WHERE review_id = ?').get(reviewId);
+    if (row === undefined) {
+        throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
+    }
+}
+function assertRevision(row, expected) {
+    if (expected !== undefined && expected !== row.revision) {
+        throw new ReviewOperationError('stale_comment', 'comment revision is stale', {
+            revision: row.revision,
+            text: row.text,
+        });
+    }
+}
+function appendStateEvent(db, args) {
+    const result = 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)
+    VALUES (?, ?, ?, 1, ?, ?, ?, ?, ?, ?)
+  `).run(args.row.review_id, args.row.comment_id, args.kind, args.row.revision, args.actor.kind, args.actor.node_id, args.at, args.operation_id, json(args.payload));
+    return Number(result.lastInsertRowid);
+}
+function updateComment(db, row, fields, actor, at) {
+    const revision = row.revision + 1;
+    db.prepare(`
+    UPDATE review_comments
+    SET status = ?, revision = ?, text = ?, updated_by_kind = ?, updated_by_node_id = ?,
+        updated_at = ?, resolved_at = ?, deleted_at = ?
+    WHERE comment_id = ?
+  `).run(fields.status ?? row.status, revision, fields.text ?? row.text, actor.kind, actor.node_id, at, fields.resolved_at === undefined ? row.resolved_at : fields.resolved_at, fields.deleted_at === undefined ? row.deleted_at : fields.deleted_at, row.comment_id);
+    return { ...row, ...fields, revision, updated_by_kind: actor.kind, updated_by_node_id: actor.node_id, updated_at: at };
+}
+function completeMutation(result) {
+    if (result.changed)
+        signalReviewActivity();
+    return result;
+}
+export function createComment(args) {
+    const result = withCanvasWrite((db) => {
+        assertReviewExists(db, args.review_id);
+        const live = db.prepare("SELECT COUNT(*) AS count FROM review_comments WHERE review_id = ? AND status != 'deleted'").get(args.review_id);
+        if (Number(live.count) >= LIVE_COMMENTS_MAX) {
+            throw new ReviewOperationError('comment_limit_reached', 'review comment limit reached', {
+                limit: LIVE_COMMENTS_MAX,
+                live: Number(live.count),
+            });
+        }
+        const text = trimText(args.text);
+        const lineText = truncateUtf8(args.line_text, COMMENT_LINE_TEXT_MAX);
+        const at = nowIso();
+        let id = commentId();
+        while (getStoredComment(db, id) !== null)
+            id = commentId();
+        const inserted = db.prepare(`
+      INSERT INTO review_comments
+        (comment_id, review_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,
+         author_kind, author_node_id, updated_by_kind, updated_by_node_id, created_at,
+         updated_at, resolved_at, deleted_at, created_seq)
+      VALUES (?, ?, 'open', 1, ?, ?, ?, ?, ?, ?, ?, ?, 'live', ?, ?, ?, ?, ?, ?, NULL, NULL, 0)
+    `).run(id, args.review_id, text, args.anchor.line, args.anchor.end_line, args.anchor.col_start ?? null, args.anchor.col_end ?? null, args.anchor.quote ?? null, lineText, args.doc_hash, args.actor.kind, args.actor.node_id, args.actor.kind, args.actor.node_id, at, at);
+        if (inserted.changes !== 1)
+            throw new Error('failed to insert review comment');
+        const row = getStoredComment(db, id);
+        const seq = appendStateEvent(db, {
+            row,
+            kind: 'created',
+            actor: args.actor,
+            operation_id: args.operation_id,
+            at,
+            payload: { text, anchor: args.anchor, line_text: lineText, doc_hash: args.doc_hash },
+        });
+        db.prepare('UPDATE review_comments SET created_seq = ? WHERE comment_id = ?').run(seq, id);
+        return { comment: commentFromRow({ ...row, created_seq: seq }), changed: true };
+    });
+    signalReviewActivity();
+    return result;
+}
+export function editComment(commentIdValue, args) {
+    const result = withCanvasWrite((db) => {
+        const row = requireStoredComment(db, commentIdValue);
+        if (row.status === 'deleted')
+            throw new ReviewOperationError('comment_deleted', 'comment is a deleted tombstone', { comment_id: row.comment_id, deleted_at: row.deleted_at });
+        const text = trimText(args.text);
+        if (row.text === text)
+            return { comment: commentFromRow(row), changed: false };
+        assertRevision(row, args.if_revision);
+        const at = nowIso();
+        const previousAnchor = commentFromRow(row).anchor;
+        const updated = updateComment(db, row, { text }, args.actor, at);
+        appendStateEvent(db, {
+            row: updated,
+            kind: 'edited',
+            actor: args.actor,
+            operation_id: args.operation_id,
+            at,
+            payload: {
+                previous_text: row.text,
+                text,
+                previous_anchor: previousAnchor,
+                anchor: commentFromRow(updated).anchor,
+            },
+        });
+        return { comment: commentFromRow(updated), changed: true };
+    });
+    return completeMutation(result);
+}
+function transitionComment(commentIdValue, args, target, kind) {
+    const result = withCanvasWrite((db) => {
+        const row = requireStoredComment(db, commentIdValue);
+        if (row.status === 'deleted') {
+            if (target === 'deleted')
+                return { comment: commentFromRow(row), changed: false };
+            throw new ReviewOperationError('comment_deleted', 'comment is a deleted tombstone', { comment_id: row.comment_id, deleted_at: row.deleted_at });
+        }
+        if (row.status === target)
+            return { comment: commentFromRow(row), changed: false };
+        assertRevision(row, args.if_revision);
+        const at = nowIso();
+        const updated = updateComment(db, row, {
+            status: target,
+            resolved_at: target === 'resolved' ? at : target === 'open' ? null : undefined,
+            deleted_at: target === 'deleted' ? at : undefined,
+        }, args.actor, at);
+        appendStateEvent(db, {
+            row: updated,
+            kind,
+            actor: args.actor,
+            operation_id: args.operation_id,
+            at,
+            payload: {
+                previous_status: row.status,
+                status: target,
+                previous_text: row.text,
+                text: updated.text,
+                previous_anchor: commentFromRow(row).anchor,
+                anchor: commentFromRow(updated).anchor,
+            },
+        });
+        return { comment: commentFromRow(updated), changed: true };
+    });
+    return completeMutation(result);
+}
+export function resolveComment(commentIdValue, args) {
+    return transitionComment(commentIdValue, args, 'resolved', 'resolved');
+}
+export function reopenComment(commentIdValue, args) {
+    return transitionComment(commentIdValue, args, 'open', 'reopened');
+}
+export function deleteComment(commentIdValue, args) {
+    return transitionComment(commentIdValue, args, 'deleted', 'deleted');
+}
+export function listComments(reviewId, opts) {
+    const db = openDb();
+    const status = opts?.status;
+    const rows = status === undefined
+        ? db.prepare("SELECT * FROM review_comments WHERE review_id = ? AND status != 'deleted' ORDER BY anchor_line, created_seq").all(reviewId)
+        : status === 'all'
+            ? db.prepare('SELECT * FROM review_comments WHERE review_id = ? ORDER BY anchor_line, created_seq').all(reviewId)
+            : db.prepare('SELECT * FROM review_comments WHERE review_id = ? AND status = ? ORDER BY anchor_line, created_seq').all(reviewId, status);
+    return rows.map(commentFromRow);
+}
+export function getComment(commentIdValue) {
+    const row = getStoredComment(openDb(), commentIdValue);
+    return row === null ? null : commentFromRow(row);
+}
+export function listCommentEvents(commentIdValue) {
+    const rows = openDb().prepare('SELECT * FROM review_comment_events WHERE comment_id = ? ORDER BY seq').all(commentIdValue);
+    return rows.map(eventFromRow);
+}
+export function listReviewEvents(reviewId, opts) {
+    const since = opts.since_seq ?? 0;
+    const limit = Math.min(Math.max(opts.limit ?? COMMENT_EVENTS_PAGE_DEFAULT, 1), COMMENT_EVENTS_PAGE_MAX);
+    const rows = openDb().prepare('SELECT * FROM review_comment_events WHERE review_id = ? AND seq > ? ORDER BY seq LIMIT ?').all(reviewId, since, limit);
+    const events = rows.map(eventFromRow);
+    return { events, next_since_seq: events.length === 0 ? since : events[events.length - 1].seq };
+}
+export function snapshotCommentsLocked(db, reviewId) {
+    const rows = db.prepare("SELECT * FROM review_comments WHERE review_id = ? AND status != 'deleted' ORDER BY anchor_line, created_seq").all(reviewId);
+    const comments = rows.map((row) => ({
+        id: row.comment_id,
+        line: row.anchor_line,
+        endLine: row.anchor_end_line,
+        ...(row.anchor_quote === null ? {} : { quote: row.anchor_quote }),
+        ...(row.anchor_col_start === null ? {} : { colStart: row.anchor_col_start }),
+        ...(row.anchor_col_end === null ? {} : { colEnd: row.anchor_col_end }),
+        lineText: row.anchor_line_text,
+        comment: row.text,
+        createdAt: row.created_at,
+    }));
+    return { comments, total: rows.length, unresolved: rows.filter((row) => row.status === 'open').length };
+}
+export function appendDeliveryEvent(args) {
+    withCanvasWrite((db) => {
+        assertReviewExists(db, args.review_id);
+        const row = requireStoredComment(db, args.comment_id);
+        if (row.review_id !== args.review_id)
+            throw new ReviewOperationError('unknown_comment', 'comment was not found', { received: args.comment_id });
+        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)
+      VALUES (?, ?, ?, 0, NULL, 'system', NULL, ?, ?, ?)
+    `).run(args.review_id, args.comment_id, args.kind, nowIso(), args.operation_id, json(args.payload));
+    });
+    signalReviewActivity();
+}

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

@@ -0,0 +1,35 @@
+import { type InitialModelRegistryLike } from '../model-routes.js';
+export interface OriginCapture {
+    sourceFile: string;
+    sourceSessionId: string;
+    leafId: string;
+    modelSpec: string;
+}
+export interface ReviewCompanionSpec {
+    nodeId: string;
+    reviewId: string;
+    originNodeId: string;
+    branchFile: string;
+    targetFile: string;
+    modelSpec: string;
+    cwd: string;
+    profileId: string | null;
+}
+type ExactModel = {
+    provider: string;
+    id: string;
+};
+type ExactModelRegistry = InitialModelRegistryLike<ExactModel>;
+/** Capture an origin without launching it or acquiring its broker's writer role. */
+export declare function captureOrigin(originNodeId: string, deps?: {
+    registry?: ExactModelRegistry;
+}): Promise<OriginCapture>;
+/** Materialize the immutable review fork, reusing only an already-valid branch. */
+export declare function materializeReviewBranch(reviewId: string, capture: OriginCapture): string;
+/** Create the ordinary, promptless companion node. Realization owns its launch. */
+export declare function spawnReviewCompanion(spec: ReviewCompanionSpec): void;
+/** A companion is bound only when its session coordinates and visible boundary are durable. */
+export declare function isReviewCompanionBound(nodeId: string): boolean;
+/** Wait for the durable companion bind without owning companion liveness. */
+export declare function awaitCompanionBind(nodeId: string, deadlineMs: number): Promise<boolean>;
+export {};

package/dist/core/review/companion.js

@@ -0,0 +1,205 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { basename, isAbsolute, resolve } from 'node:path';
+import { BrokerClient } from '../broker-client/index.js';
+import { getNode } from '../canvas/index.js';
+import { ensureReviewDir, reviewBranchPath } from '../canvas/paths.js';
+import { expandModelCandidates, selectInitialModelRoute } from '../model-routes.js';
+import { buildLaunchSpec } from '../runtime/launch.js';
+import { openModelRegistry } from '../runtime/model-registry.js';
+import { isBrokerLive } from '../runtime/model-swap.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { SessionManager } from '../runtime/broker-sdk.js';
+import { materializeSessionBranchAt } from '../runtime/session-branch.js';
+import { isReviewBoundary } from '../runtime/session-visibility.js';
+import { ReviewOperationError } from './types.js';
+const EXACT_MODEL_SPEC = /^[^/\s:]+\/[^/\s:]+:(?:off|minimal|low|medium|high|xhigh|max)$/;
+const BIND_POLL_MS = 100;
+function originMissing(originNodeId) {
+    return new ReviewOperationError('review_origin_missing', 'review origin was not found', { origin_node_id: originNodeId });
+}
+function originUnforkable(originNodeId, reason, detail = {}) {
+    return new ReviewOperationError('review_origin_unforkable', 'review origin has no forkable exact session', {
+        origin_node_id: originNodeId,
+        reason,
+        ...detail,
+    });
+}
+async function validateCapture(originNodeId, value, registry) {
+    if (!isAbsolute(value.sourceFile) || !existsSync(value.sourceFile) || value.sourceSessionId === '' || value.leafId === null || value.leafId === '') {
+        throw originUnforkable(originNodeId, 'no_forkable_session');
+    }
+    if (value.modelSpec === null || !EXACT_MODEL_SPEC.test(value.modelSpec)) {
+        throw originUnforkable(originNodeId, 'model_unresolvable');
+    }
+    const selection = selectInitialModelRoute({ kind: 'exact', spec: value.modelSpec }, registry ?? await openModelRegistry(), { cwd: value.cwd, profileId: value.profileId });
+    if (selection.selected === undefined) {
+        throw originUnforkable(originNodeId, 'model_unresolvable', {
+            model_reason: selection.rejected[0]?.reason,
+        });
+    }
+    return {
+        sourceFile: value.sourceFile,
+        sourceSessionId: value.sourceSessionId,
+        leafId: value.leafId,
+        modelSpec: value.modelSpec,
+    };
+}
+/** Read the broker's fork coordinate through its observer-only protocol path.
+ * This connection can inspect a streaming origin but has no writer authority. */
+function captureLiveOrigin(originNodeId) {
+    return new Promise((resolveCapture, reject) => {
+        const client = new BrokerClient(originNodeId);
+        let settled = false;
+        function finish(action) {
+            if (settled)
+                return;
+            settled = true;
+            client.close();
+            action();
+        }
+        client.on('error', (error) => finish(() => reject(error)));
+        client.on('close', () => finish(() => reject(new Error('origin broker closed before fork coordinates were read'))));
+        client.on('connect', () => {
+            client.send({ type: 'hello', role: 'observer', client_id: randomUUID() });
+            void client.request({ type: 'get_human_fork_coordinates' })
+                .then((frame) => {
+                if (frame.kind !== 'human_fork_coordinates') {
+                    finish(() => reject(new Error('origin broker returned an unexpected fork-coordinate response')));
+                    return;
+                }
+                finish(() => resolveCapture(frame));
+            })
+                .catch((error) => finish(() => reject(error)));
+        });
+        client.connect();
+    });
+}
+/** Capture an origin without launching it or acquiring its broker's writer role. */
+export async function captureOrigin(originNodeId, deps = {}) {
+    const node = getNode(originNodeId);
+    if (node === null)
+        throw originMissing(originNodeId);
+    if (isBrokerLive(node)) {
+        const coordinates = await captureLiveOrigin(originNodeId);
+        return validateCapture(originNodeId, {
+            ...coordinates,
+            cwd: node.cwd,
+            profileId: node.profile_id,
+        }, deps.registry);
+    }
+    const sourceFile = typeof node.pi_session_file === 'string' ? node.pi_session_file : '';
+    let sourceSessionId = '';
+    let leafId = null;
+    let modelSpec = null;
+    if (isAbsolute(sourceFile) && existsSync(sourceFile)) {
+        let session;
+        try {
+            session = SessionManager.open(sourceFile);
+        }
+        catch {
+            return validateCapture(originNodeId, {
+                sourceFile,
+                sourceSessionId,
+                leafId,
+                modelSpec,
+                cwd: node.cwd,
+                profileId: node.profile_id,
+            }, deps.registry);
+        }
+        sourceSessionId = session.getSessionId();
+        leafId = session.getLeafId();
+        const launchSpec = node.launch?.model;
+        const parsed = typeof launchSpec === 'string'
+            ? expandModelCandidates({ kind: 'exact', spec: launchSpec }, node.cwd, node.profile_id)[0]
+            : undefined;
+        if (parsed !== undefined) {
+            const thinking = parsed.thinkingLevel ?? (session.buildSessionContext().thinkingLevel || 'off');
+            modelSpec = `${parsed.providerId}/${parsed.modelId}:${thinking}`;
+        }
+    }
+    return validateCapture(originNodeId, {
+        sourceFile,
+        sourceSessionId,
+        leafId,
+        modelSpec,
+        cwd: node.cwd,
+        profileId: node.profile_id,
+    }, deps.registry);
+}
+/** Materialize the immutable review fork, reusing only an already-valid branch. */
+export function materializeReviewBranch(reviewId, capture) {
+    ensureReviewDir(reviewId);
+    const branchFile = reviewBranchPath(reviewId);
+    if (existsSync(branchFile)) {
+        const branch = SessionManager.open(branchFile);
+        if (branch.getSessionFile() === resolve(branchFile) && branch.getSessionId() !== '')
+            return branchFile;
+    }
+    materializeSessionBranchAt(capture, branchFile);
+    return branchFile;
+}
+/** Create the ordinary, promptless companion node. Realization owns its launch. */
+export function spawnReviewCompanion(spec) {
+    if (!isAbsolute(spec.branchFile) || !isAbsolute(spec.targetFile)) {
+        throw new Error('review companion requires absolute branch and target paths');
+    }
+    if (!EXACT_MODEL_SPEC.test(spec.modelSpec)) {
+        throw new Error('review companion requires an exact model spec');
+    }
+    const { launch } = buildLaunchSpec('review/companion', 'base', {
+        lifecycle: 'resident',
+        hasManager: false,
+        model: spec.modelSpec,
+        modelExact: true,
+        cwd: spec.cwd,
+        profileId: spec.profileId,
+    });
+    spawnNode({
+        nodeId: spec.nodeId,
+        kind: 'review/companion',
+        mode: 'base',
+        lifecycle: 'resident',
+        cwd: spec.cwd,
+        profile_id: spec.profileId,
+        parent: spec.originNodeId,
+        subscribe: false,
+        forkFrom: spec.branchFile,
+        modelOverride: spec.modelSpec,
+        reviewBinding: {
+            review_id: spec.reviewId,
+            origin_node_id: spec.originNodeId,
+            branch_file: spec.branchFile,
+            target_file: spec.targetFile,
+        },
+        name: `review ${basename(spec.targetFile)}`,
+        launch,
+    });
+}
+/** A companion is bound only when its session coordinates and visible boundary are durable. */
+export function isReviewCompanionBound(nodeId) {
+    const node = getNode(nodeId);
+    const binding = node?.review_binding;
+    const sessionFile = node?.pi_session_file;
+    if (binding == null || node?.pi_session_id == null || typeof sessionFile !== 'string' || !existsSync(sessionFile)) {
+        return false;
+    }
+    try {
+        return SessionManager.open(sessionFile).getEntries().some((entry) => isReviewBoundary(entry, binding.review_id));
+    }
+    catch {
+        return false;
+    }
+}
+/** Wait for the durable companion bind without owning companion liveness. */
+export async function awaitCompanionBind(nodeId, deadlineMs) {
+    const deadline = Date.now() + Math.max(0, deadlineMs);
+    for (;;) {
+        if (isReviewCompanionBound(nodeId))
+            return true;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        await new Promise((resolveWait) => setTimeout(resolveWait, Math.min(BIND_POLL_MS, remaining)));
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ReviewRecord } from './types.js';
+import { type CommentAnchor } from './types.js';
+type SourcePhase = 'submit' | 'comment';
+/** Read the reviewed document once, preserving the exact bytes used for its digest. */
+export declare function readReviewSource(file: string, phase?: SourcePhase): {
+    bytes: Buffer;
+    sha256: string;
+    lines: string[];
+};
+/** Require both the caller's rendered source and the persisted range coordinate base to be current. */
+export declare function requireCurrentDocument(review: ReviewRecord, expected_doc_hash: string): {
+    bytes: Buffer;
+    sha256: string;
+    lines: string[];
+};
+/** Verify a create-time source precondition from the review row held by the caller's canvas write transaction. */
+export declare function requireCurrentDocumentLocked(db: DatabaseSync, review_id: string, expected_doc_hash: string): {
+    bytes: Buffer;
+    sha256: string;
+    lines: string[];
+};
+/** Reject malformed ranges rather than normalizing them into a different anchor. */
+export declare function validateAnchorShape(anchor: CommentAnchor): void;
+/** Capture the full source range used to render an anchor, without silently clamping it. */
+export declare function captureAnchorText(lines: string[], anchor: CommentAnchor): string;
+export {};