@north-light/cli 0.0.0-stage → 0.3.413

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,21 @@
+var D=Object.defineProperty;var i=(e,t)=>D(e,"name",{value:t,configurable:!0});import{prepared as _}from"../sqlite-statements.js";import{randomBytes as F}from"node:crypto";import{openDb as l,withCanvasWrite as h}from"../canvas/db.js";import{nowIso as v}from"../fs-utils.js";import{signalReviewActivity as E}from"./signal.js";import{COMMENT_EVENTS_PAGE_DEFAULT as U,COMMENT_EVENTS_PAGE_MAX as W,COMMENT_LINE_TEXT_MAX as B,COMMENT_TEXT_MAX as k,LIVE_COMMENTS_MAX as N,ReviewOperationError as u}from"./types.js";function m(e){return{comment_id:e.comment_id,review_id:e.review_id,status:e.status,revision:e.revision,text:e.text,anchor:{line:e.anchor_line,end_line:e.anchor_end_line,...e.anchor_col_start===null?{}:{col_start:e.anchor_col_start},...e.anchor_col_end===null?{}:{col_end:e.anchor_col_end},...e.anchor_quote===null?{}:{quote:e.anchor_quote}},anchor_state:e.anchor_state,anchor_line_text:e.anchor_line_text,anchor_doc_hash:e.anchor_doc_hash,author:{kind:e.author_kind,node_id:e.author_node_id},updated_by:{kind:e.updated_by_kind,node_id:e.updated_by_node_id},created_at:e.created_at,updated_at:e.updated_at,resolved_at:e.resolved_at,deleted_at:e.deleted_at,created_seq:e.created_seq}}i(m,"commentFromRow");function q(e){return{seq:e.seq,review_id:e.review_id,comment_id:e.comment_id,kind:e.kind,state_change:e.state_change===0?0:1,revision_after:e.revision_after,actor:{kind:e.actor_kind,node_id:e.actor_node_id},at:e.at,operation_id:e.operation_id,...e.payload===null?{}:{payload:JSON.parse(e.payload)}}}i(q,"eventFromRow");function y(e){return JSON.stringify(e)}i(y,"json");function S(){let e;do e=F(16).toString("hex");while(/^0+$/.test(e));return e}i(S,"commentId");function C(e){const t=e.trim();if(t==="")throw new Error("comment text must not be empty");const n=Buffer.byteLength(t,"utf8");if(n>k)throw new u("text_too_long","comment text exceeds the maximum length",{limit:k,received:n});return t}i(C,"trimText");function H(e,t){if(Buffer.byteLength(e,"utf8")<=t)return e;const n="\u2026 [truncated]",r=Buffer.byteLength(n,"utf8"),o=Buffer.from(e,"utf8");let d=Math.max(0,t-r);for(;d>0&&(o[d]&192)===128;)d-=1;return`${o.subarray(0,d).toString("utf8")}${n}`}i(H,"truncateUtf8");function p(e,t){return _(e,"SELECT * FROM review_comments WHERE comment_id = ?").get(t)??null}i(p,"getStoredComment");function f(e,t){const n=p(e,t);if(n===null)throw new u("unknown_comment","comment was not found",{received:t});return n}i(f,"requireStoredComment");function L(e,t){if(_(e,"SELECT request_id FROM human_requests WHERE request_id = ? AND kind = 'review' AND state = 'open'").get(t)===void 0)throw new u("unknown_review","review was not found",{received:t})}i(L,"assertReviewExists");function M(e,t){if(t!==void 0&&t!==e.revision)throw new u("stale_comment","comment revision is stale",{revision:e.revision,text:e.text})}i(M,"assertRevision");function x(e,t){const n=_(e,`
+    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(t.row.review_id,t.row.comment_id,t.kind,t.row.revision,t.actor.kind,t.actor.node_id,t.at,t.operation_id,y(t.payload));return Number(n.lastInsertRowid)}i(x,"appendStateEvent");function O(e,t,n,r,o){const d=t.revision+1;return _(e,`
+    UPDATE review_comments
+    SET status = ?, revision = ?, text = ?, updated_by_kind = ?, updated_by_node_id = ?,
+        updated_at = ?, resolved_at = ?, deleted_at = ?
+    WHERE comment_id = ?
+  `).run(n.status??t.status,d,n.text??t.text,r.kind,r.node_id,o,n.resolved_at===void 0?t.resolved_at:n.resolved_at,n.deleted_at===void 0?t.deleted_at:n.deleted_at,t.comment_id),{...t,...n,revision:d,updated_by_kind:r.kind,updated_by_node_id:r.node_id,updated_at:o}}i(O,"updateComment");function A(e){return e.changed&&E(),e}i(A,"completeMutation");function G(e){const t=h(n=>{L(n,e.review_id);const r=_(n,"SELECT COUNT(*) AS count FROM review_comments WHERE review_id = ? AND status != 'deleted'").get(e.review_id);if(Number(r.count)>=N)throw new u("comment_limit_reached","review comment limit reached",{limit:N,live:Number(r.count)});const o=C(e.text),d=H(e.line_text,B),c=v();let a=S();for(;p(n,a)!==null;)a=S();if(_(n,`
+      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(a,e.review_id,o,e.anchor.line,e.anchor.end_line,e.anchor.col_start??null,e.anchor.col_end??null,e.anchor.quote??null,d,e.doc_hash,e.actor.kind,e.actor.node_id,e.actor.kind,e.actor.node_id,c,c).changes!==1)throw new Error("failed to insert review comment");const w=p(n,a),T=x(n,{row:w,kind:"created",actor:e.actor,operation_id:e.operation_id,at:c,payload:{text:o,anchor:e.anchor,line_text:d,doc_hash:e.doc_hash}});return _(n,"UPDATE review_comments SET created_seq = ? WHERE comment_id = ?").run(T,a),{comment:m({...w,created_seq:T}),changed:!0}});return E(),t}i(G,"createComment");function J(e,t){const n=h(r=>{const o=f(r,e);if(o.status==="deleted")throw new u("comment_deleted","comment is a deleted tombstone",{comment_id:o.comment_id,deleted_at:o.deleted_at});const d=C(t.text);if(o.text===d)return{comment:m(o),changed:!1};M(o,t.if_revision);const c=v(),a=m(o).anchor,s=O(r,o,{text:d},t.actor,c);return x(r,{row:s,kind:"edited",actor:t.actor,operation_id:t.operation_id,at:c,payload:{previous_text:o.text,text:d,previous_anchor:a,anchor:m(s).anchor}}),{comment:m(s),changed:!0}});return A(n)}i(J,"editComment");function R(e,t,n,r){const o=h(d=>{const c=f(d,e);if(c.status==="deleted"){if(n==="deleted")return{comment:m(c),changed:!1};throw new u("comment_deleted","comment is a deleted tombstone",{comment_id:c.comment_id,deleted_at:c.deleted_at})}if(c.status===n)return{comment:m(c),changed:!1};M(c,t.if_revision);const a=v(),s=O(d,c,{status:n,resolved_at:n==="resolved"?a:n==="open"?null:void 0,deleted_at:n==="deleted"?a:void 0},t.actor,a);return x(d,{row:s,kind:r,actor:t.actor,operation_id:t.operation_id,at:a,payload:{previous_status:c.status,status:n,previous_text:c.text,text:s.text,previous_anchor:m(c).anchor,anchor:m(s).anchor}}),{comment:m(s),changed:!0}});return A(o)}i(R,"transitionComment");function j(e,t){return R(e,t,"resolved","resolved")}i(j,"resolveComment");function z(e,t){return R(e,t,"open","reopened")}i(z,"reopenComment");function K(e,t){return R(e,t,"deleted","deleted")}i(K,"deleteComment");function Q(e,t){const n=l(),r=t?.status;return(r===void 0?_(n,"SELECT * FROM review_comments WHERE review_id = ? AND status != 'deleted' ORDER BY anchor_line, created_seq").all(e):r==="all"?_(n,"SELECT * FROM review_comments WHERE review_id = ? ORDER BY anchor_line, created_seq").all(e):_(n,"SELECT * FROM review_comments WHERE review_id = ? AND status = ? ORDER BY anchor_line, created_seq").all(e,r)).map(m)}i(Q,"listComments");function Z(e){const t=p(l(),e);return t===null?null:m(t)}i(Z,"getComment");function g(e){return _(l(),"SELECT * FROM review_comment_events WHERE comment_id = ? ORDER BY seq").all(e).map(q)}i(g,"listCommentEvents");function ee(e,t){const n=t.since_seq??0,r=Math.min(Math.max(t.limit??U,1),W),d=_(l(),"SELECT * FROM review_comment_events WHERE review_id = ? AND seq > ? ORDER BY seq LIMIT ?").all(e,n,r).map(q);return{events:d,next_since_seq:d.length===0?n:d[d.length-1].seq}}i(ee,"listReviewEvents");function te(e,t){const n=_(e,"SELECT * FROM review_comments WHERE review_id = ? AND status != 'deleted' ORDER BY anchor_line, created_seq").all(t);return{comments:n.map(o=>({id:o.comment_id,line:o.anchor_line,endLine:o.anchor_end_line,...o.anchor_quote===null?{}:{quote:o.anchor_quote},...o.anchor_col_start===null?{}:{colStart:o.anchor_col_start},...o.anchor_col_end===null?{}:{colEnd:o.anchor_col_end},lineText:o.anchor_line_text,comment:o.text,createdAt:o.created_at})),total:n.length,unresolved:n.filter(o=>o.status==="open").length}}i(te,"snapshotCommentsLocked");function ne(e){h(t=>{if(L(t,e.review_id),f(t,e.comment_id).review_id!==e.review_id)throw new u("unknown_comment","comment was not found",{received:e.comment_id});_(t,`
+      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(e.review_id,e.comment_id,e.kind,v(),e.operation_id,y(e.payload))}),E()}i(ne,"appendDeliveryEvent");export{ne as appendDeliveryEvent,G as createComment,K as deleteComment,J as editComment,Z as getComment,g as listCommentEvents,Q as listComments,ee as listReviewEvents,z as reopenComment,j as resolveComment,te as snapshotCommentsLocked};

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

@@ -0,0 +1,33 @@
+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>;
+/** Create the ordinary, promptless companion node. Realization owns its launch. */
+export declare function spawnReviewCompanion(spec: ReviewCompanionSpec): Promise<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 @@
+var y=Object.defineProperty;var s=(e,o)=>y(e,"name",{value:o,configurable:!0});import{randomUUID as v}from"node:crypto";import{conversationIdFromPath as u,conversationStore as w,ConversationNotFoundError as p}from"../conversation-store/index.js";import{basename as F,isAbsolute as c}from"node:path";import{BrokerClient as x}from"../broker-client/index.js";import{deleteNode as M,getNode as g}from"../canvas/index.js";import{expandModelCandidates as C,selectInitialModelRoute as E}from"../model-routes.js";import{buildLaunchSpec as L}from"../runtime/launch.js";import{openModelRegistry as B}from"../runtime/model-registry.js";import{isBrokerLive as O}from"../runtime/model-swap.js";import{spawnNode as R}from"../runtime/nodes.js";import{SessionManager as D}from"../runtime/broker-sdk.js";import{isReviewBoundary as P}from"../runtime/session-visibility.js";import{forkNodeLedger as $}from"../runtime/ledger.js";import{ReviewOperationError as b}from"./types.js";const I=/^[^/\s:]+\/[^/\s:]+:(?:off|minimal|low|medium|high|xhigh|max)$/,q=100;function N(e){return new b("review_origin_missing","review origin was not found",{origin_node_id:e})}s(N,"originMissing");function f(e,o,r={}){return new b("review_origin_unforkable","review origin has no forkable exact session",{origin_node_id:e,reason:o,...r})}s(f,"originUnforkable");async function k(e,o,r){const n=u(o.sourceFile);if(!c(o.sourceFile)||n===null||n!==o.sourceSessionId||o.leafId===null||o.leafId==="")throw f(e,"no_forkable_session");try{w().header(n)}catch(i){throw i instanceof p?f(e,"no_forkable_session"):i}if(o.modelSpec===null||!I.test(o.modelSpec))throw f(e,"model_unresolvable");const t=E({kind:"exact",spec:o.modelSpec},r??await B(),{cwd:o.cwd,profileId:o.profileId});if(t.selected===void 0)throw f(e,"model_unresolvable",{model_reason:t.rejected[0]?.reason});return{sourceFile:o.sourceFile,sourceSessionId:o.sourceSessionId,leafId:o.leafId,modelSpec:o.modelSpec}}s(k,"validateCapture");function U(e){return new Promise((o,r)=>{const n=new x(e);let t=!1;function i(d){t||(t=!0,n.close(),d())}s(i,"finish"),n.on("error",d=>i(()=>r(d))),n.on("close",()=>i(()=>r(new Error("origin broker closed before fork coordinates were read")))),n.on("connect",()=>{n.send({type:"hello",role:"observer",client_id:v()}),n.request({type:"get_human_fork_coordinates"}).then(d=>{if(d.kind!=="human_fork_coordinates"){i(()=>r(new Error("origin broker returned an unexpected fork-coordinate response")));return}i(()=>o(d))}).catch(d=>i(()=>r(d)))}),n.connect()})}s(U,"captureLiveOrigin");async function re(e,o={}){const r=g(e);if(r===null)throw N(e);if(O(r)){const a=await U(e);return k(e,{...a,cwd:r.cwd,profileId:r.profile_id},o.registry)}const n=typeof r.pi_session_file=="string"?r.pi_session_file:"";let t="",i=null,d=null;const h=u(n);if(c(n)&&h!==null)try{const a=w().read(h),m=D.inMemory(a.header.cwd,void 0,[a.header,...a.entries]);t=m.getSessionId(),i=m.getLeafId();const _=r.launch?.model,l=typeof _=="string"?C({kind:"exact",spec:_},r.cwd,r.profile_id)[0]:void 0;if(l!==void 0){const S=l.thinkingLevel??(m.buildSessionContext().thinkingLevel||"off");d=`${l.providerId}/${l.modelId}:${S}`}}catch(a){if(!(a instanceof p))throw a}return k(e,{sourceFile:n,sourceSessionId:t,leafId:i,modelSpec:d,cwd:r.cwd,profileId:r.profile_id},o.registry)}s(re,"captureOrigin");async function ne(e){if(!c(e.branchFile)||!c(e.targetFile))throw new Error("review companion requires absolute branch and target paths");if(!I.test(e.modelSpec))throw new Error("review companion requires an exact model spec");const{launch:o}=L("review/companion","base",{lifecycle:"resident",hasManager:!1,model:e.modelSpec,modelExact:!0,cwd:e.cwd,profileId:e.profileId}),r=await R({nodeId:e.nodeId,kind:"review/companion",mode:"base",lifecycle:"resident",cwd:e.cwd,profile_id:e.profileId,parent:e.originNodeId,creator:e.originNodeId,subscribe:!1,forkFrom:e.branchFile,forkSourceFile:e.branchFile,modelOverride:e.modelSpec,reviewBinding:{review_id:e.reviewId,origin_node_id:e.originNodeId,branch_file:e.branchFile,target_file:e.targetFile},name:`review ${F(e.targetFile)}`,launch:o});try{$(r.node_id,e.originNodeId)}catch(n){throw M(r.node_id),n}}s(ne,"spawnReviewCompanion");function A(e){const o=g(e),r=o?.review_binding,n=o?.pi_session_file,t=typeof n=="string"?u(n):null;if(r==null||o?.pi_session_id==null||t===null)return!1;try{return w().read(t).entries.some(i=>P(i,r.review_id))}catch(i){if(i instanceof p)return!1;throw i}}s(A,"isReviewCompanionBound");async function ie(e,o){const r=Date.now()+Math.max(0,o);for(;;){if(A(e))return!0;const n=r-Date.now();if(n<=0)return!1;await new Promise(t=>setTimeout(t,Math.min(q,n)))}}s(ie,"awaitCompanionBind");export{ie as awaitCompanionBind,re as captureOrigin,A as isReviewCompanionBound,ne as spawnReviewCompanion};

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 {};

package/dist/core/review/document.js

@@ -0,0 +1,2 @@
+var f=Object.defineProperty;var i=(e,t)=>f(e,"name",{value:t,configurable:!0});import{prepared as m}from"../sqlite-statements.js";import{createHash as g}from"node:crypto";import{readFileSync as b,statSync as p}from"node:fs";import{documentLines as w}from"../document-lines.js";import{COMMENT_QUOTE_MAX as a,ReviewOperationError as u}from"./types.js";const l=2*1024*1024;function o(e,t,n){throw new u("source_unreadable","review source is unreadable",{phase:t,reason:n,file:e})}i(o,"sourceUnreadable");function h(e,t="submit"){let n;try{const s=p(e);if(!s.isFile())return o(e,t,"unreadable");n=s.size}catch(s){return o(e,t,s.code==="ENOENT"?"missing":"unreadable")}if(n>l)return o(e,t,"too_large");let r;try{r=b(e)}catch(s){return o(e,t,s.code==="ENOENT"?"missing":"unreadable")}if(r.length>l)return o(e,t,"too_large");if(r.includes(0))return o(e,t,"binary");let d;try{d=new TextDecoder("utf-8",{fatal:!0}).decode(r)}catch{return o(e,t,"binary")}return{bytes:r,sha256:g("sha256").update(r).digest("hex"),lines:w(d)}}i(h,"readReviewSource");function c(e,t){const n=h(e.file,"comment");if(n.sha256!==t)throw new u("stale_document","review document changed since it was rendered",{reason:"document_changed",expected_sha256:t,actual_sha256:n.sha256});if(n.sha256!==e.anchor_base_sha256)throw new u("stale_document","review comment ranges have not been remapped to the current document",{reason:"anchor_base_stale",expected_sha256:e.anchor_base_sha256,actual_sha256:n.sha256});return n}i(c,"requireDocumentSource");function I(e,t){return c(e,t)}i(I,"requireCurrentDocument");function T(e,t,n){const r=m(e,"SELECT file, anchor_base_sha256 FROM human_requests WHERE request_id = ? AND kind = 'review' AND state = 'open'").get(t);if(r===void 0)throw new u("unknown_review","review was not found",{received:t});return c(r,n)}i(T,"requireCurrentDocumentLocked");function v(e){const t=[],n=e.col_start!==void 0,r=e.col_end!==void 0;if((!Number.isSafeInteger(e.line)||e.line<1)&&t.push("line must be a positive integer"),(!Number.isSafeInteger(e.end_line)||e.end_line<1)&&t.push("end_line must be a positive integer"),Number.isSafeInteger(e.line)&&Number.isSafeInteger(e.end_line)&&e.end_line<e.line&&t.push("end_line must be greater than or equal to line"),n!==r&&t.push("col_start and col_end must be provided together"),n&&(!Number.isSafeInteger(e.col_start)||e.col_start<0)&&t.push("col_start must be a non-negative integer"),r&&(!Number.isSafeInteger(e.col_end)||e.col_end<0)&&t.push("col_end must be a non-negative integer"),n&&r&&e.line===e.end_line&&Number.isSafeInteger(e.col_start)&&Number.isSafeInteger(e.col_end)&&e.col_end<=e.col_start&&t.push("col_end must be greater than col_start for a single-line anchor"),e.quote!==void 0&&typeof e.quote!="string"&&t.push("quote must be a string"),typeof e.quote=="string"&&Buffer.byteLength(e.quote,"utf8")>a&&t.push(`quote exceeds ${a} bytes`),t.length>0)throw new u("invalid_anchor","comment anchor is invalid",{violations:t})}i(v,"validateAnchorShape");function _(e,t){return t===e.length||(e[t]&192)!==128}i(_,"isUtf8Boundary");function O(e,t){if(v(t),t.line>e.length||t.end_line>e.length)throw new u("anchor_out_of_range","comment anchor exceeds the reviewed document",{line_count:e.length,requested:{line:t.line,end_line:t.end_line}});if(t.col_start!==void 0&&t.col_end!==void 0){const n=Buffer.from(e[t.line-1],"utf8"),r=Buffer.from(e[t.end_line-1],"utf8");if(t.col_start>n.length||t.col_end>r.length||!_(n,t.col_start)||!_(r,t.col_end))throw new u("anchor_out_of_range","comment anchor columns exceed the reviewed document",{line_count:e.length,requested:{line:t.line,end_line:t.end_line}})}return e.slice(t.line-1,t.end_line).join(`
+`)}i(O,"captureAnchorText");export{O as captureAnchorText,h as readReviewSource,I as requireCurrentDocument,T as requireCurrentDocumentLocked,v as validateAnchorShape};

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

@@ -0,0 +1,8 @@
+export interface ReviewForkResult {
+    /** The newborn fork. */
+    node_id: string;
+    /** Where the fork runs — the companion's cwd, which a viewer pane reuses. */
+    cwd: string;
+}
+/** Fork the review companion onto one comment. */
+export declare function forkReviewComment(commentId: string): Promise<ReviewForkResult>;

package/dist/core/review/fork.js

@@ -0,0 +1,5 @@
+var m=Object.defineProperty;var d=(o,n)=>m(o,"name",{value:n,configurable:!0});import{basename as c}from"node:path";import{getNode as s}from"../canvas/index.js";import{materializeSessionBranch as p}from"../runtime/session-branch.js";import{spawnChildPrepared as w}from"../runtime/spawn.js";import{getComment as l}from"./comments.js";import{captureOrigin as _}from"./companion.js";import{requireVisibleReview as f}from"./store.js";import{ReviewOperationError as a}from"./types.js";function h(o,n){const{line:e,end_line:i}=n.anchor,t=i>e?`lines ${e}-${i}`:`line ${e}`,r=n.anchor_line_text===""?"":`
+> ${n.anchor_line_text}
+`;return[`The person handed you this one comment on \`${o.file}\` so it can be worked in parallel. The review companion you were forked from keeps the rest of the document.`,`${t}:${r}`,n.text,`Address it by editing only the lines this comment is about \u2014 other forks may be editing the same file \u2014 then resolve it with \`crtr human review comment resolve ${n.comment_id}\`, and tell the companion what changed with \`crtr push update\`.`].join(`
+
+`)}d(h,"forkTask");async function R(o){const n=l(o);if(n===null)throw new a("unknown_comment","comment was not found",{received:o});if(n.status!=="open")throw new a("comment_deleted","only an open comment can be forked",{comment_id:o,status:n.status});const e=f(n.review_id);if(e.state!=="open")throw new a("review_terminal","review already has a terminal outcome",{state:e.state,requested:"fork",review:e});const i=s(e.companion_node_id);if(i===null)throw new a("review_companion_unbound","review companion is gone",{companion_node_id:e.companion_node_id});const t=await _(e.companion_node_id),r=p(t);return{node_id:(await w({kind:"review/companion",mode:"base",cwd:i.cwd,parent:e.companion_node_id,creator:e.companion_node_id,rootLifecycle:"resident",prompt:h(e,n),forkFrom:r,model:t.modelSpec,name:`comment on ${c(e.file)}`,reviewBinding:{review_id:e.review_id,origin_node_id:e.origin_node_id,branch_file:r,target_file:e.file}})).node.node_id,cwd:i.cwd}}d(R,"forkReviewComment");export{R as forkReviewComment};

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

@@ -0,0 +1,17 @@
+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 every terminal review from its SQL row; no ticket bridge participates. */
+export declare function projectReviewResult(review: ReviewRecord, result: ReviewResult): {
+    destinations: string[];
+};
+/** Cancellation has no review approval payload but still receives a durable projection. */
+export declare function projectReviewCancellation(review: ReviewRecord, result: unknown): {
+    destinations: string[];
+};

package/dist/core/review/project.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var i=(e,o)=>u(e,"name",{value:o,configurable:!0});import{join as s}from"node:path";import{atomicWriteJson as r}from"../human/convention.js";function m(e,o,t,n){return{schema:"humanloop.review-response/v1",review_id:e.review_id,file:e.file,submitted:!0,approved:!0,changed:t!==e.baseline_sha256,baseline_sha256:e.baseline_sha256,approved_sha256:t,companion_node_id:e.companion_node_id,comments_total:o.total,comments_unresolved:o.unresolved,comments:o.comments,submittedAt:n,savedAt:n}}i(m,"buildReviewResult");function l(e,o){const t=s(e.review_dir,"result.json");r(t,o);const n=e.output_path??s(e.review_dir,"feedback.json");return n!==t&&r(n,o),{destinations:n===t?[t]:[t,n]}}i(l,"projectReviewResult");function _(e,o){const t=s(e.review_dir,"result.json");return r(t,o),{destinations:[t]}}i(_,"projectReviewCancellation");export{m as buildReviewResult,_ as projectReviewCancellation,l as projectReviewResult};

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

@@ -0,0 +1,3 @@
+import { type HumanRequestRecord } from '../human/requests.js';
+/** Finish a committed binding without bridge creation or directory descriptor publication. */
+export declare function realizeReview(reviewId: string): Promise<HumanRequestRecord>;

package/dist/core/review/realize.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var r=(i,e)=>m(i,"name",{value:e,configurable:!0});import{conversationIdFromPath as v,conversationStore as h,ConversationNotFoundError as g}from"../conversation-store/index.js";import{getNode as s}from"../canvas/index.js";import{openRequest as q,cancelBindingRequest as b,getRequest as y}from"../human/requests.js";import{NodeIdConflictError as I}from"../runtime/nodes.js";import{reviveNode as N}from"../runtime/revive.js";import{awaitCompanionBind as E,spawnReviewCompanion as S}from"./companion.js";import{signalReviewActivity as l}from"./signal.js";import{COMPANION_BIND_DEADLINE_MS as f,ReviewOperationError as o}from"./types.js";function p(i){const e=y(i);if(e===null||e.kind!=="review")throw new o("unknown_review","review was not found",{received:i});return e}r(p,"requireBinding");function R(i){try{const e=JSON.parse(i.specification_json);if(typeof e!="object"||e===null)throw new Error("not an object");return e}catch(e){throw new Error(`corrupt review specification: ${i.request_id}`,{cause:e})}}r(R,"specification");async function k(i){let e=p(i);if(e.state!=="binding")return e;const w=R(e),t=w.branch_file,d=typeof t=="string"?v(t):null;let u=d===null;if(d!==null)try{h().header(d)}catch(n){if(!(n instanceof g))throw n;u=!0}if(u)throw b(e.request_id,new Date().toISOString(),"branch_lost")&&l(),new o("branch_lost","review branch was lost before realization",{review_id:e.request_id});if(e.file===null||e.requester_node_id===null||e.companion_node_id===null)throw new Error(`binding review has incomplete identity: ${e.request_id}`);const a=s(e.requester_node_id);if(a===null)throw new o("review_origin_missing","review origin was not found",{origin_node_id:e.requester_node_id});if(s(e.companion_node_id)===null){const n=w.model_spec;if(typeof n!="string")throw new Error(`binding review has no model spec: ${e.request_id}`);try{await S({nodeId:e.companion_node_id,reviewId:e.request_id,originNodeId:e.requester_node_id,branchFile:t,targetFile:e.file,modelSpec:n,cwd:a.cwd,profileId:a.profile_id??null})}catch(_){if(!(_ instanceof I))throw _}}const c=s(e.companion_node_id);if(c===null)throw new o("review_companion_unbound","review companion was not created",{review_id:e.request_id});if(c.pi_session_id===null&&await N(c.node_id,{resume:!1,capacity:"refuse"}),!await E(e.companion_node_id,f))throw new o("review_companion_unbound","review companion did not bind in time",{review_id:e.request_id,waited_ms:f});return q(e.request_id,new Date().toISOString())&&l(),e=p(i),e}r(k,"realizeReview");export{k as realizeReview};

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,19 @@
+var q=Object.defineProperty;var i=(e,n)=>q(e,"name",{value:n,configurable:!0});import{prepared as u}from"../sqlite-statements.js";import{withCanvasWrite as A}from"../canvas/db.js";import{nowIso as k}from"../fs-utils.js";import{signalReviewActivity as T}from"./signal.js";import{replaceAnchorBaseLocked as b}from"./store.js";import{ReviewOperationError as h}from"./types.js";import{captureAnchorText as O,readReviewSource as N,validateAnchorShape as D}from"./document.js";function I(e){return{line:e.anchor_line,end_line:e.anchor_end_line,...e.anchor_col_start===null?{}:{col_start:e.anchor_col_start},...e.anchor_col_end===null?{}:{col_end:e.anchor_col_end},...e.anchor_quote===null?{}:{quote:e.anchor_quote}}}i(I,"anchorFromRow");function f(e,n,c,_){throw new h("range_batch_stale","review comment ranges are stale",{reason:e,expected:n,actual:c,..._===void 0?{}:{comment_id:_}})}i(f,"rangeBatchStale");function L(e){if(typeof e.comment_id!="string"||e.comment_id==="")throw new h("invalid_anchor","comment anchor is invalid",{violations:["comment_id must be a non-empty string"]});const n=e.anchor!==void 0,c=e.detached===!0;if(n===c)throw new h("invalid_anchor","comment anchor is invalid",{violations:["each range batch entry must provide exactly one of anchor or detached"]});n&&D(e.anchor)}i(L,"validateEntry");function W(e,n){u(e,`
+    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(n.row.comment_id,n.row.revision+1,n.actor.kind,n.actor.node_id,n.at,n.operation_id,JSON.stringify({previous_anchor:n.previous_anchor,anchor:n.anchor,previous_anchor_state:n.previous_anchor_state,anchor_state:n.anchor_state,previous_doc_hash:n.previous_doc_hash,doc_hash:n.doc_hash,line_text:n.line_text}),n.row.comment_id)}i(W,"appendReanchorEvent");function j(e){const n=A(c=>{const _=u(c,"SELECT file, anchor_base_sha256 FROM human_requests WHERE request_id = ? AND kind = 'review' AND state = 'open'").get(e.review_id);if(_===void 0)throw new h("unknown_review","review was not found",{received:e.review_id});const a=N(_.file,"comment");a.sha256!==e.to_doc_hash&&f("to_doc_hash",e.to_doc_hash,a.sha256),_.anchor_base_sha256!==e.from_doc_hash&&f("from_doc_hash",_.anchor_base_sha256,e.from_doc_hash);const d=u(c,`
+      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(e.review_id);for(const o of d)o.anchor_doc_hash!==e.from_doc_hash&&f("comment_hash",e.from_doc_hash,o.anchor_doc_hash,o.comment_id);const r=new Map,s=[];for(const o of e.entries)L(o),r.has(o.comment_id)?s.push(o.comment_id):r.set(o.comment_id,o);const y=new Set(d.map(o=>o.comment_id));for(const o of r.keys())y.has(o)||s.push(o);const p=d.filter(o=>!r.has(o.comment_id)).map(o=>o.comment_id);if(p.length>0||s.length>0)throw new h("range_batch_incomplete","range batch must cover every non-deleted comment exactly once",{missing:p,extra:s});let w=0,E=0;const x=k();for(const o of d){const m=r.get(o.comment_id),R=I(o),t=m.detached===!0?R:m.anchor,l=m.detached===!0?"detached":"live",v=m.detached===!0?o.anchor_line_text:O(a.lines,t);if(!(o.anchor_state!==l||o.anchor_doc_hash!==a.sha256||o.anchor_line!==t.line||o.anchor_end_line!==t.end_line||o.anchor_col_start!==(t.col_start??null)||o.anchor_col_end!==(t.col_end??null)||o.anchor_quote!==(t.quote??null)||o.anchor_line_text!==v))continue;const S=o.revision+1;u(c,`
+        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(S,t.line,t.end_line,t.col_start??null,t.col_end??null,t.quote??null,v,a.sha256,l,e.actor.kind,e.actor.node_id,x,o.comment_id),W(c,{row:o,actor:e.actor,operation_id:e.operation_id,at:x,previous_anchor:R,anchor:t,previous_anchor_state:o.anchor_state,anchor_state:l,previous_doc_hash:o.anchor_doc_hash,doc_hash:a.sha256,line_text:v}),w+=1,l==="detached"&&(E+=1)}return b(c,e.review_id,a.bytes,a.sha256),{updated:w,detached:E,anchor_base_sha256:a.sha256}});return T(),n}i(j,"applyRangeBatch");export{j as applyRangeBatch};

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 @@
+var v=Object.defineProperty;var t=(i,e)=>v(i,"name",{value:e,configurable:!0});import{activityPath as c,signalActivity as r,watchActivity as a}from"../activity-signal.js";function o(){return c("review-activity")}t(o,"reviewActivityPath");function w(){r("review-activity")}t(w,"signalReviewActivity");function u(i){return a("review-activity",i)}t(u,"watchReviewActivity");export{o as reviewActivityPath,w as signalReviewActivity,u as watchReviewActivity};

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

@@ -0,0 +1,38 @@
+import { type HumanRequestRecord } from '../human/requests.js';
+import { type NewReviewRow, type ReviewOriginKind } from './types.js';
+/** The document a review is of: the head the origin read, snapshotted into the review dir. */
+export interface ReviewedDocument {
+    id: string;
+    /** `<owner>/<name>`. */
+    name: string;
+    /** The heads the snapshot was read from — the base of the save on submit. */
+    base: string;
+    body: string;
+}
+/** Exactly one of `file` (an inline review of a file) or `document`. */
+export interface StageReviewArgs {
+    origin_kind: ReviewOriginKind;
+    origin_node_id: string;
+    file?: string;
+    document?: ReviewedDocument;
+    idempotency_key: string;
+    subtitle?: string;
+    output_path?: string;
+}
+/** A persisted winner needs realization, while a new stage has unreferenced filesystem state to commit or discard. */
+export type StagedReview = {
+    existing: HumanRequestRecord;
+    row?: never;
+    review_dir?: never;
+} | {
+    existing?: never;
+    row: NewReviewRow;
+    review_dir: string;
+};
+/** Remove only review-directory state that was never committed to a review row. */
+export declare function discardStaging(reviewId: string, branchFile?: string): void;
+/**
+ * Capture an existing origin and write its immutable branch without creating a
+ * canvas node or review row. The caller alone commits or discards this stage.
+ */
+export declare function stageReview(args: StageReviewArgs): Promise<StagedReview>;

package/dist/core/review/stage.js

@@ -0,0 +1 @@
+var v=Object.defineProperty;var o=(e,n)=>v(e,"name",{value:n,configurable:!0});import{createHash as g}from"node:crypto";import{existsSync as y,readFileSync as b,realpathSync as S,rmSync as F,statSync as I,writeFileSync as k}from"node:fs";import{isAbsolute as x,join as R}from"node:path";import{getNode as O}from"../canvas/index.js";import{conversationIdFromPath as j,conversationStore as z,ConversationNotFoundError as D}from"../conversation-store/index.js";import{ensureReviewDir as E,reviewDir as l}from"../canvas/paths.js";import{checkReviewableFile as B}from"../human/visible-paths.js";import{newNodeId as w}from"../runtime/nodes.js";import{captureOrigin as N}from"./companion.js";import{materializeSessionBranch as q}from"../runtime/session-branch.js";import{getRequestByIdempotencyKey as A}from"../human/requests.js";import{ReviewOperationError as r}from"./types.js";function a(e,n){return new r("review_target_unreviewable","review target cannot be staged",{phase:"create",file:e,reason:n})}o(a,"targetError");function h(e){if(!x(e))throw a(e,"not_absolute");if(!y(e))throw a(e,"missing");try{if(!I(e).isFile())throw a(e,"not_a_file")}catch(i){throw i instanceof r?i:a(e,"missing")}const n=B(e);if(!n.ok){const i=n.reason==="file is not UTF-8 text"?"binary":n.reason==="file is too large to review (2 MB limit)"?"too_large":n.reason==="file is too long to review (5,000 line limit)"?"too_many_lines":"not_a_file";throw a(e,i)}try{return S(e)}catch{throw a(e,"missing")}}o(h,"validateReviewFile");function U(e){return new r("review_branch_unavailable","review branch could not be materialized",{reason:"materialize_failed",origin_node_id:e})}o(U,"branchUnavailable");async function C(e){try{return await N(e)}catch(n){throw n instanceof r&&n.code==="review_origin_missing"?new r("review_origin_missing","review origin was not found",{origin_node_id:e,reason:"origin_missing"}):n}}o(C,"captureStagedOrigin");function H(e,n){try{return q(n)}catch{throw U(e)}}o(H,"materialize");function K(e,n){if(n!==void 0){const i=j(n);if(i===null)throw new Error(`invalid staged conversation path: ${n}`);try{z().delete(i)}catch(c){if(!(c instanceof D))throw c}}try{F(l(e),{recursive:!0,force:!0})}catch{}}o(K,"discardStaging");async function ee(e){const n=A(e.idempotency_key);if(n!==null)return{existing:n};if(O(e.origin_node_id)===null)throw new r("review_origin_missing","review origin was not found",{origin_node_id:e.origin_node_id,reason:"origin_missing"});const i=w(),c=w();let d,s=e.document===void 0?h(e.file??""):"";try{if(E(i),e.document!==void 0){const m=R(l(i),"document.md");k(m,e.document.body),s=h(m)}const t=await C(e.origin_node_id),p=new Date().toISOString(),_=b(s),u=g("sha256").update(_).digest("hex");d=H(e.origin_node_id,t);const f=new Date().toISOString();return{row:{review_id:i,idempotency_key:e.idempotency_key,origin_kind:e.origin_kind,origin_node_id:e.origin_node_id,companion_node_id:c,review_dir:l(i),file:s,origin_session_file:t.sourceFile,origin_session_id:t.sourceSessionId,origin_leaf_id:t.leafId,model_spec:t.modelSpec,branch_file:d,baseline_sha256:u,baseline_bytes:_.length,anchor_base_sha256:u,anchor_base_bytes:_,state:"binding",created:f,captured_at:p,opened_at:null,submit_requested_at:null,output_path:e.output_path??null,document_id:e.document?.id??null,document_name:e.document?.name??null,document_base:e.document?.base??null,subtitle:e.subtitle??null,approved_at:null,approved_sha256:null,changed:null,comments_total:null,comments_unresolved:null,result_json:null,canceled_at:null,cancel_reason:null,cancel_actor:null,delivery_entry_id:null,delivered_at:null,delivery_error:null,projected_at:null,projection_error:null},review_dir:l(i)}}catch(t){throw K(i,d),t}}o(ee,"stageReview");export{K as discardStaging,ee as stageReview};

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

@@ -0,0 +1,44 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type ReviewRecord, type ReviewState } from './types.js';
+export interface ApproveReviewArgs {
+    review_id: string;
+    approved_at: string;
+    approved_sha256: string;
+    changed: boolean;
+    comments_total: number;
+    comments_unresolved: number;
+    result_json: string;
+}
+export declare function getReview(reviewId: string): ReviewRecord | null;
+export declare function requireVisibleReview(reviewId: string): ReviewRecord;
+export declare function getReviewByIdempotencyKey(key: string): ReviewRecord | null;
+export declare function getReviewByCompanion(nodeId: string): ReviewRecord | null;
+export declare function listReviews(filter: {
+    state?: ReviewState;
+    origin_node_id?: string;
+    file?: string;
+}): ReviewRecord[];
+export declare function reviewIdsByOriginNodes(nodeIds: readonly string[]): string[];
+export declare function deleteReviewsByOriginNodes(nodeIds: readonly string[]): string[];
+export declare function listBindingReviews(): ReviewRecord[];
+export declare function listSubmitRequestedReviews(): ReviewRecord[];
+export declare function listUnprojectedTerminalReviews(): ReviewRecord[];
+export declare function openReviewRow(reviewId: string, openedAt: string): boolean;
+/** Put a deferred submit back to not-requested, so the person sees the review open again. */
+export declare function clearReviewSubmit(reviewId: string): void;
+export declare function requestReviewSubmit(reviewId: string, at: string): boolean;
+export declare function approveReviewLocked(db: DatabaseSync, args: ApproveReviewArgs): boolean;
+export declare function cancelReviewRow(reviewId: string, args: {
+    at: string;
+    reason: string;
+    actor: string | null;
+}): boolean;
+export declare function markProjected(reviewId: string, at: string): void;
+export declare function markProjectionError(reviewId: string, error: string): void;
+export declare function markDelivered(_reviewId: string, _receipt: string | null, _at: string): void;
+export declare function markDeliveryError(_reviewId: string, _error: string): void;
+export declare function readAnchorBase(reviewId: string): {
+    bytes: Buffer;
+    sha256: string;
+} | null;
+export declare function replaceAnchorBaseLocked(db: DatabaseSync, reviewId: string, bytes: Buffer, sha256: string): void;

package/dist/core/review/store.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var t=(e,n)=>c(e,"name",{value:n,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{existsSync as d}from"node:fs";import{withCanvasWrite as s}from"../canvas/db.js";import{getRequest as l,getRequestByCompanion as _,getRequestByIdempotencyKey as p,listBindingRequests as m,listRequests as u,listSubmitRequestedRequests as v,listUnprojectedReviews as w,markProjected as f,markProjectionError as h,openRequest as R,readAnchorBase as E,replaceAnchorBaseLocked as y,requestSubmit as j}from"../human/requests.js";import{ReviewOperationError as k}from"./types.js";function b(e){try{const n=JSON.parse(e.specification_json);if(typeof n!="object"||n===null)throw new Error("not an object");return n}catch(n){throw new Error(`corrupt review specification: ${e.request_id}`,{cause:n})}}t(b,"specification");function g(e){return e.state!=="settled"?e.state:e.outcome==="approved"?"approved":"canceled"}t(g,"state");function i(e){if(e.kind!=="review")throw new Error(`human request is not a review: ${e.request_id}`);const n=b(e),r=g(e),o=e.settled_at;return{review_id:e.request_id,idempotency_key:e.idempotency_key??"",origin_kind:n.origin_kind??(e.inbox_listed?"ticket":"inline"),origin_node_id:e.requester_node_id??"",companion_node_id:e.companion_node_id??"",review_dir:e.request_dir,file:e.file??"",origin_session_file:n.origin_session_file,origin_session_id:n.origin_session_id,origin_leaf_id:n.origin_leaf_id,model_spec:n.model_spec,branch_file:n.branch_file,baseline_sha256:n.baseline_sha256,baseline_bytes:n.baseline_bytes,anchor_base_sha256:e.anchor_base_sha256??"",state:r,created:e.created_at,captured_at:n.captured_at,opened_at:e.opened_at,submit_requested_at:e.submit_requested_at,output_path:n.output_path??null,document_id:n.document_id??null,document_name:n.document_name??null,document_base:n.document_base??null,subtitle:e.subtitle,approved_at:r==="approved"?o:null,approved_sha256:r==="approved"?(()=>{try{return JSON.parse(e.result_json??"{}").approved_sha256??null}catch{return null}})():null,changed:r==="approved"?(()=>{try{return JSON.parse(e.result_json??"{}").changed??null}catch{return null}})():null,comments_total:r==="approved"?(()=>{try{return JSON.parse(e.result_json??"{}").comments_total??null}catch{return null}})():null,comments_unresolved:r==="approved"?(()=>{try{return JSON.parse(e.result_json??"{}").comments_unresolved??null}catch{return null}})():null,result_json:e.result_json,canceled_at:r==="canceled"?o:null,cancel_reason:r==="canceled"?(()=>{try{return JSON.parse(e.result_json??"{}").reason??null}catch{return null}})():null,cancel_actor:r==="canceled"?(()=>{try{return JSON.parse(e.result_json??"{}").actor??null}catch{return null}})():null,delivery_entry_id:e.settlement_delivery_id,delivered_at:e.settlement_delivery_id===null?null:o,delivery_error:null,projected_at:e.projected_at,projection_error:e.projection_error,source_missing:!d(e.file??"")}}t(i,"record");function x(e){const n=l(e);return n?.kind==="review"?n:null}t(x,"requestForReview");function N(e){const n=x(e);return n===null?null:i(n)}t(N,"getReview");function T(e){const n=N(e);if(n===null||n.state==="binding")throw new k("unknown_review","review was not found",{received:e});return n}t(T,"requireVisibleReview");function I(e){const n=p(e);return n?.kind==="review"?i(n):null}t(I,"getReviewByIdempotencyKey");function P(e){const n=_(e);return n?.kind==="review"?i(n):null}t(P,"getReviewByCompanion");function J(e){return u({kind:"review",...e.origin_node_id===void 0?{}:{requester_node_id:e.origin_node_id},...e.file===void 0?{}:{file:e.file}}).map(i).filter(n=>n.state!=="binding"&&(e.state===void 0||n.state===e.state))}t(J,"listReviews");function S(e){const n=new Set(e);return u({kind:"review"}).filter(r=>r.requester_node_id!==null&&n.has(r.requester_node_id)).map(r=>r.request_id)}t(S,"reviewIdsByOriginNodes");function U(e){const n=S(e);return n.length===0?[]:(s(r=>{const o=n.map(()=>"?").join(",");r.prepare(`DELETE FROM review_comment_events WHERE review_id IN (${o})`).run(...n),r.prepare(`DELETE FROM review_comments WHERE review_id IN (${o})`).run(...n),r.prepare(`DELETE FROM human_requests WHERE request_id IN (${o})`).run(...n)}),n)}t(U,"deleteReviewsByOriginNodes");function W(){return m().map(i)}t(W,"listBindingReviews");function H(){return v().map(i)}t(H,"listSubmitRequestedReviews");function $(){return w().map(i)}t($,"listUnprojectedTerminalReviews");function F(e,n){return R(e,n)}t(F,"openReviewRow");function C(e){s(n=>a(n,"UPDATE human_requests SET submit_requested_at = NULL, updated_at = ? WHERE request_id = ? AND kind = 'review' AND state = 'open'").run(new Date().toISOString(),e))}t(C,"clearReviewSubmit");function M(e,n){return j(e,n)}t(M,"requestReviewSubmit");function K(e,n){return a(e,"UPDATE human_requests SET state = 'settled', outcome = 'approved', result_json = ?, settled_at = ?, progress_json = NULL, updated_at = ? WHERE request_id = ? AND kind = 'review' AND state = 'open'").run(n.result_json,n.approved_at,n.approved_at,n.review_id).changes>0}t(K,"approveReviewLocked");function V(e,n){return s(r=>a(r,"UPDATE human_requests SET state = 'settled', outcome = 'canceled', result_json = ?, settled_at = ?, progress_json = NULL, updated_at = ? WHERE request_id = ? AND kind = 'review' AND state = 'open'").run(JSON.stringify({schema:"humanloop.cancel/v1",kind:"canceled",canceledAt:n.at,...n.reason===""?{}:{reason:n.reason},...n.actor===null?{}:{actor:n.actor}}),n.at,n.at,e).changes>0)}t(V,"cancelReviewRow");function z(e,n){f(e,n)}t(z,"markProjected");function G(e,n){h(e,n)}t(G,"markProjectionError");function Q(e,n,r){}t(Q,"markDelivered");function X(e,n){}t(X,"markDeliveryError");function Y(e){return E(e)}t(Y,"readAnchorBase");function Z(e,n,r,o){y(e,n,r,o)}t(Z,"replaceAnchorBaseLocked");export{K as approveReviewLocked,V as cancelReviewRow,C as clearReviewSubmit,U as deleteReviewsByOriginNodes,N as getReview,P as getReviewByCompanion,I as getReviewByIdempotencyKey,W as listBindingReviews,J as listReviews,H as listSubmitRequestedReviews,$ as listUnprojectedTerminalReviews,Q as markDelivered,X as markDeliveryError,z as markProjected,G as markProjectionError,F as openReviewRow,Y as readAnchorBase,Z as replaceAnchorBaseLocked,M as requestReviewSubmit,T as requireVisibleReview,S as reviewIdsByOriginNodes};

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

@@ -0,0 +1,139 @@
+/**
+ * Internal review/comment/error vocabulary and constants.
+ * Backs the daemon-owned review lifecycle and comment authority.
+ * This module declares no HTTP status, DTOs, or I/O.
+ */
+import type { FeedbackComment } from '../human/types.js';
+export type ReviewState = 'binding' | 'open' | 'approved' | 'canceled';
+export type ReviewOriginKind = 'ticket' | 'inline';
+export type CommentStatus = 'open' | 'resolved' | 'deleted';
+export type CommentAuthorKind = 'human' | 'node';
+export type CommentEventKind = 'created' | 'edited' | 'resolved' | 'reopened' | 'deleted' | 'reanchored' | 'notified' | 'notify_failed';
+export type ReviewErrorCode = 'review_origin_missing' | 'review_origin_unforkable' | 'review_branch_unavailable' | 'branch_lost' | 'review_companion_unbound' | 'review_bridge_unsubscribed' | 'review_target_unreviewable' | 'source_unreadable' | 'delivery_unroutable' | 'unknown_review' | 'review_terminal' | 'review_required' | 'stale_document' | 'stale_revision' | 'unknown_comment' | 'comment_deleted' | 'invalid_anchor' | 'anchor_out_of_range' | 'text_too_long' | 'comment_limit_reached' | 'stale_comment' | 'range_batch_incomplete' | 'range_batch_stale';
+/** Limits */
+export declare const COMMENT_TEXT_MAX = 8000;
+export declare const COMMENT_QUOTE_MAX = 4000;
+export declare const COMMENT_LINE_TEXT_MAX = 8000;
+export declare const LIVE_COMMENTS_MAX = 500;
+export declare const COMMENT_EVENTS_PAGE_DEFAULT = 200;
+export declare const COMMENT_EVENTS_PAGE_MAX = 1000;
+export declare const COMPANION_BIND_DEADLINE_MS = 90000;
+export interface CommentAnchor {
+    line: number;
+    end_line: number;
+    col_start?: number;
+    col_end?: number;
+    quote?: string;
+}
+export interface ReviewRow {
+    review_id: string;
+    idempotency_key: string;
+    origin_kind: ReviewOriginKind;
+    origin_node_id: string;
+    companion_node_id: string;
+    review_dir: string;
+    file: string;
+    origin_session_file: string;
+    origin_session_id: string;
+    origin_leaf_id: string;
+    model_spec: string;
+    branch_file: string;
+    baseline_sha256: string;
+    baseline_bytes: number;
+    anchor_base_sha256: string;
+    anchor_base_bytes: Buffer;
+    state: ReviewState;
+    created: string;
+    captured_at: string;
+    opened_at: string | null;
+    /** When the human pressed submit on a review whose companion was still
+     *  working. The review stays `open` — comments still land and still remap —
+     *  until the companion goes quiet and the daemon completes the approval. */
+    submit_requested_at: string | null;
+    output_path: string | null;
+    /** A document review: the document's object id, its `<owner>/<name>`, and the heads it was
+     *  snapshotted from — the base the reviewed text is saved against on submit. All null for a
+     *  file review. */
+    document_id: string | null;
+    document_name: string | null;
+    document_base: string | null;
+    subtitle: string | null;
+    approved_at: string | null;
+    approved_sha256: string | null;
+    changed: boolean | null;
+    comments_total: number | null;
+    comments_unresolved: number | null;
+    result_json: string | null;
+    canceled_at: string | null;
+    cancel_reason: string | null;
+    cancel_actor: string | null;
+    delivery_entry_id: string | null;
+    delivered_at: string | null;
+    delivery_error: string | null;
+    projected_at: string | null;
+    projection_error: string | null;
+}
+export interface ReviewRecord extends Omit<ReviewRow, 'anchor_base_bytes'> {
+    source_missing: boolean;
+}
+export interface ReviewComment {
+    comment_id: string;
+    review_id: string;
+    status: CommentStatus;
+    revision: number;
+    text: string;
+    anchor: CommentAnchor;
+    anchor_state: 'live' | 'detached';
+    anchor_line_text: string;
+    anchor_doc_hash: string;
+    author: {
+        kind: CommentAuthorKind;
+        node_id: string | null;
+    };
+    updated_by: {
+        kind: CommentAuthorKind;
+        node_id: string | null;
+    };
+    created_at: string;
+    updated_at: string;
+    resolved_at: string | null;
+    deleted_at: string | null;
+    created_seq: number;
+}
+export interface ReviewCommentEvent {
+    seq: number;
+    review_id: string;
+    comment_id: string;
+    kind: CommentEventKind;
+    state_change: 0 | 1;
+    revision_after: number | null;
+    actor: {
+        kind: CommentAuthorKind | 'system';
+        node_id: string | null;
+    };
+    at: string;
+    operation_id: string;
+    payload?: unknown;
+}
+export interface ReviewResult {
+    schema: 'humanloop.review-response/v1';
+    review_id: string;
+    file: string;
+    submitted: true;
+    approved: true;
+    changed: boolean;
+    baseline_sha256: string;
+    approved_sha256: string;
+    companion_node_id: string;
+    comments_total: number;
+    comments_unresolved: number;
+    comments: FeedbackComment[];
+    submittedAt: string;
+    savedAt: string;
+}
+export declare class ReviewOperationError extends Error {
+    code: ReviewErrorCode;
+    detail: Record<string, unknown>;
+    constructor(code: ReviewErrorCode, message: string, detail: Record<string, unknown>);
+}
+export type NewReviewRow = ReviewRow;

package/dist/core/review/types.js

@@ -0,0 +1 @@
+var r=Object.defineProperty;var E=(o,t)=>r(o,"name",{value:t,configurable:!0});const s=8e3,T=4e3,N=8e3,c=500,n=200,p=1e3,O=9e4;class A extends Error{static{E(this,"ReviewOperationError")}code;detail;constructor(t,_,e){super(_),this.code=t,this.detail=e,this.name="ReviewOperationError"}}export{n as COMMENT_EVENTS_PAGE_DEFAULT,p as COMMENT_EVENTS_PAGE_MAX,N as COMMENT_LINE_TEXT_MAX,T as COMMENT_QUOTE_MAX,s as COMMENT_TEXT_MAX,O as COMPANION_BIND_DEADLINE_MS,c as LIVE_COMMENTS_MAX,A as ReviewOperationError};

package/dist/core/runs/activity.d.ts

@@ -0,0 +1,11 @@
+import { type OpenAssistantBlock } from '../../daemon/runs/observer.js';
+import type { RunActivityDTO } from '../../api/dto/run-events.js';
+/** One line naming what a tool call acts on: a command's first line, else a path; null when neither is present. */
+export declare function toolCallSummary(args: unknown): string | null;
+/** `run.get` `activity`: what the run's root is doing now, for a running run.
+ *  The root's own turn and tool-call events say whether a turn is open and
+ *  which tool is executing; the run observer's open assistant message (the
+ *  state `run.trace` `in_progress_message` reads) says what the model is
+ *  streaming. Null unless the run is `running`. `streaming` is that open
+ *  message's newest block; a test passes it in place of a live broker. */
+export declare function runActivity(runId: string, status: string, streaming?: () => OpenAssistantBlock | null): RunActivityDTO | null;

package/dist/core/runs/activity.js

@@ -0,0 +1,6 @@
+var f=Object.defineProperty;var i=(e,t)=>f(e,"name",{value:t,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{openDb as b}from"../canvas/db.js";import{openAssistantBlock as y}from"../../daemon/runs/observer.js";import{SUBMIT_RESULT_TOOL as p}from"../runtime/structured-output.js";const _=120;function E(e){if(!e||typeof e!="object")return null;const t=e,s=[t.command,t.file_path,t.path].find(r=>typeof r=="string"&&r.trim()!=="");if(s===void 0)return null;const o=s.trim().split(`
+`)[0].trim();return o.length>_?`${o.slice(0,_-1)}\u2026`:o}i(E,"toolCallSummary");function D(e,t,s=()=>y(e)){if(t!=="running")return null;const o=b(),r=a(o,`SELECT type, sequence_number FROM run_events WHERE run_id = ? AND node_id = ?
+    AND type IN ('node.turn.started', 'node.turn.completed') ORDER BY sequence_number DESC LIMIT 1`).get(e,e);if(!r)return{phase:"starting"};if(r.type==="node.turn.completed")return{phase:"between_turns"};const l=s();if(l?.kind==="text")return{phase:"writing"};if(l?.kind==="tool_call")return l.name===p?{phase:"submitting_result"}:{phase:"tool",tool:{name:l.name,summary:null}};if(l===null){const c=a(o,`SELECT type, json_extract(body_json, '$.tool_call_id') AS id, sequence_number FROM run_events
+      WHERE run_id = ? AND node_id = ? AND type IN ('node.tool_call.started', 'node.tool_call.completed') AND sequence_number > ?
+      ORDER BY sequence_number`).all(e,e,r.sequence_number),d=new Set(c.filter(n=>n.type==="node.tool_call.completed").map(n=>n.id)),m=c.filter(n=>n.type==="node.tool_call.started"&&!d.has(n.id)).at(-1);if(m){const n=a(o,`SELECT json_extract(body_json, '$.name') AS name, json_extract(body_json, '$.arguments') AS args
+        FROM run_events WHERE run_id = ? AND sequence_number = ?`).get(e,m.sequence_number);if(n.name===p)return{phase:"submitting_result"};let u=null;try{u=n.args===null?null:JSON.parse(n.args)}catch{u=null}return{phase:"tool",tool:{name:n.name,summary:E(u)}}}}return{phase:"thinking"}}i(D,"runActivity");export{D as runActivity,E as toolCallSummary};

package/dist/core/runs/confinement.d.ts

@@ -0,0 +1,23 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** A node's run and whether that run is isolated (the node's own flag or its root's). */
+export interface RunPlace {
+    run: string;
+    isolated: boolean;
+}
+/** The run a node belongs to: its `run_id`, or the node itself when it has none.
+ *  A deleted node of an isolated run keeps its run through `deleted_isolated_nodes`,
+ *  so what it leaves behind stays confined; any other node without a row is null. */
+export declare function runPlace(nodeId: string, db?: DatabaseSync): RunPlace | null;
+/** Record, before a node's row is deleted, the run of a node of an isolated run. */
+export declare function rememberDeletedIsolated(nodeId: string, db?: DatabaseSync): void;
+/** The place of the node that registered a custom object, which is where that object
+ *  reads from; null when the person or the app's server registered it. */
+export declare function objectPlace(objectRowid: number, db?: DatabaseSync): RunPlace | null;
+/** The confinement predicate: two places see each other when they are the same
+ *  run, or when neither run is isolated. */
+export declare function runsSeeEachOther(a: RunPlace, b: RunPlace): boolean;
+/** Whether a node caller of `app` may reach `target` (a node id) under run confinement.
+ *  Confinement applies only within one app; cross-app reach stays with the scope rules. */
+export declare function nodeMayReach(callerNode: string, callerApp: string, targetNode: string, targetApp: string | null, db?: DatabaseSync): boolean;
+/** The node ids of one run (its root and every node carrying its `run_id`). */
+export declare function runNodeIds(run: string, db?: DatabaseSync): string[];