@north-light/crouter-api 0.3.171 → 0.3.173

package/dist/client.d.ts

@@ -11,7 +11,9 @@ import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js
 import type { EnsureProfileRequest, ProfileDTO } from './dto/profiles.js';
 import type { FilePeekDTO } from './dto/files.js';
 import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, ModelAuthListDTO } from './dto/modelauth.js';
-import type { CreateHumanBridgeRequest, HumanBridgeResultDTO, HumanConsultResultDTO, HumanDeliverResultDTO, HumanVisualResultDTO } from './dto/human.js';
+import type { CreateHumanBridgeRequest, HumanBridgeResultDTO, HumanCancelRequest, HumanCancelResultDTO, HumanResolveRequest, HumanResolveResultDTO } from './dto/human.js';
+import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewOpenResultDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
+import type { CreateReviewCommentRequest, EditReviewCommentRequest, ListReviewCommentsQuery, ReadReviewCommentEventsQuery, ReviewCommentActionRequest, ReviewCommentDetailDTO, ReviewCommentEventsDTO, ReviewCommentListDTO, ReviewCommentMutationDTO, ReviewCommentRangeBatchRequest, ReviewCommentRangeBatchResultDTO } from './dto/review-comments.js';
 import type { CancelInboxTicketRequest, CanceledTicketResultDTO, DeckTicketResultDTO, InboxDeckDTO, InboxListDTO, InboxTicketIdDTO, RespondInboxDeckRequest } from './dto/inbox.js';
 import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
 import type { CloseWorktreeResultDTO } from './dto/worktree.js';
@@ -146,16 +148,30 @@ export declare class CrtrClient {
      *  (`spawnNode` server-side). Distinct from `createNode` (which launches a
      *  broker) precisely because a human bridge must never have one. */
     createHumanBridge(req: CreateHumanBridgeRequest): Promise<HumanBridgeResultDTO>;
-    /** Run the registered humanloop completion handler server-side for one
-     *  `humanloop.completion/v1` event. crtrd re-verifies the full trust binding
-     *  before performing any canvas mutation. */
-    deliverHuman(event: unknown): Promise<HumanDeliverResultDTO>;
-    /** Run the registered follow-up handler server-side for one
-     *  `humanloop.followup-request/v1` event. */
-    consultHuman(event: unknown): Promise<HumanConsultResultDTO>;
-    /** Run the registered visual handler server-side for one
-     *  `humanloop.visual-request-event/v1` event. */
-    visualHuman(event: unknown): Promise<HumanVisualResultDTO>;
+    /** Resolve a deck ticket answer. crtrd claims the ticket (taking over a live
+     *  inbox claim where one exists), publishes the canonical result, delivers
+     *  to the asking node, and retires the bridge before this resolves. */
+    resolveHumanTicket(nodeId: string, body: HumanResolveRequest): Promise<HumanResolveResultDTO>;
+    /** Cancel a pending ticket: a terminal canceled result, the bridge retired,
+     *  every subscriber but the caller notified. */
+    cancelHumanTicket(nodeId: string, body: HumanCancelRequest): Promise<HumanCancelResultDTO>;
+    createReview(req: CreateReviewRequest): Promise<ReviewDTO>;
+    listReviews(query?: ListReviewsQuery): Promise<ReviewListDTO>;
+    getReview(reviewId: string): Promise<ReviewDTO>;
+    getReviewByBridge(bridgeNodeId: string): Promise<ReviewDTO>;
+    openReview(reviewId: string): Promise<ReviewOpenResultDTO>;
+    submitReview(reviewId: string): Promise<ReviewSubmitResultDTO>;
+    cancelReview(reviewId: string, req?: CancelReviewRequest): Promise<ReviewCancelResultDTO>;
+    getReviewDocumentBase(reviewId: string): Promise<ReviewDocumentBaseDTO>;
+    createReviewComment(reviewId: string | undefined, req: CreateReviewCommentRequest): Promise<ReviewCommentMutationDTO>;
+    listReviewComments(reviewId?: string, query?: ListReviewCommentsQuery): Promise<ReviewCommentListDTO>;
+    readReviewCommentEvents(reviewId: string, query?: ReadReviewCommentEventsQuery): Promise<ReviewCommentEventsDTO>;
+    updateReviewCommentRanges(reviewId: string, req: ReviewCommentRangeBatchRequest): Promise<ReviewCommentRangeBatchResultDTO>;
+    getReviewComment(commentId: string): Promise<ReviewCommentDetailDTO>;
+    editReviewComment(commentId: string, req: EditReviewCommentRequest): Promise<ReviewCommentMutationDTO>;
+    resolveReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
+    reopenReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
+    deleteReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
     /** Pending deck/review tickets across every available crouter-owned
      *  humanloop root. */
     listHumanInbox(): Promise<InboxListDTO>;
@@ -210,6 +226,16 @@ export declare class CrtrClient {
      *  precondition, distinct from `nodePath`'s `ApiError` because that one IS a
      *  request the server could plausibly receive and reject itself). */
     private ticketId;
+    /** Validate a review id before route construction (D-A6). Reviews are minted
+     *  and addressed like node ids, but arrive from agent argv, so a malformed
+     *  one is a plausible request the server would also reject — `ApiError`,
+     *  not `TypeError`, matching `nodePath`. */
+    private reviewPath;
+    /** Validate a comment id before route construction (D-A6). Comment ids are
+     *  daemon-minted 32-char lowercase hex, but — like `reviewPath` — arrive from
+     *  agent argv, so a bad one is a plausible request the server would also
+     *  reject, not a caller-bug `TypeError` like `ticketId`. */
+    private commentPath;
     private transport;
     private isColdSocketError;
     /** A connection torn down MID-request (Node's "socket hang up" / a broken

package/dist/client.js

@@ -268,21 +268,70 @@ export class CrtrClient {
     createHumanBridge(req) {
         return this.request('POST', routes.humanBridge(), req);
     }
-    /** Run the registered humanloop completion handler server-side for one
-     *  `humanloop.completion/v1` event. crtrd re-verifies the full trust binding
-     *  before performing any canvas mutation. */
-    deliverHuman(event) {
-        return this.request('POST', routes.humanDeliver(), event);
-    }
-    /** Run the registered follow-up handler server-side for one
-     *  `humanloop.followup-request/v1` event. */
-    consultHuman(event) {
-        return this.request('POST', routes.humanConsult(), event);
-    }
-    /** Run the registered visual handler server-side for one
-     *  `humanloop.visual-request-event/v1` event. */
-    visualHuman(event) {
-        return this.request('POST', routes.humanVisual(), event);
+    /** Resolve a deck ticket answer. crtrd claims the ticket (taking over a live
+     *  inbox claim where one exists), publishes the canonical result, delivers
+     *  to the asking node, and retires the bridge before this resolves. */
+    resolveHumanTicket(nodeId, body) {
+        return this.request('POST', routes.humanTicketResolve(this.nodePath(nodeId)), body);
+    }
+    /** Cancel a pending ticket: a terminal canceled result, the bridge retired,
+     *  every subscriber but the caller notified. */
+    cancelHumanTicket(nodeId, body) {
+        return this.request('POST', routes.humanTicketCancel(this.nodePath(nodeId)), body);
+    }
+    // ---- Daemon-owned document reviews and comments -----------------------
+    createReview(req) {
+        return this.request('POST', routes.humanReviews(), req);
+    }
+    listReviews(query) {
+        return this.request('GET', withQuery(routes.humanReviews(), query));
+    }
+    getReview(reviewId) {
+        return this.request('GET', routes.humanReview(this.reviewPath(reviewId)));
+    }
+    getReviewByBridge(bridgeNodeId) {
+        return this.request('GET', routes.humanReviewByBridge(this.nodePath(bridgeNodeId)));
+    }
+    openReview(reviewId) {
+        return this.request('POST', routes.humanReviewOpen(this.reviewPath(reviewId)), {});
+    }
+    submitReview(reviewId) {
+        return this.request('POST', routes.humanReviewSubmit(this.reviewPath(reviewId)), {});
+    }
+    cancelReview(reviewId, req = {}) {
+        return this.request('POST', routes.humanReviewCancel(this.reviewPath(reviewId)), req);
+    }
+    getReviewDocumentBase(reviewId) {
+        return this.request('GET', routes.humanReviewDocument(this.reviewPath(reviewId)));
+    }
+    createReviewComment(reviewId, req) {
+        const path = reviewId === undefined ? 'self' : this.reviewPath(reviewId);
+        return this.request('POST', routes.humanReviewComments(path), req);
+    }
+    listReviewComments(reviewId, query) {
+        const path = reviewId === undefined ? 'self' : this.reviewPath(reviewId);
+        return this.request('GET', withQuery(routes.humanReviewComments(path), query));
+    }
+    readReviewCommentEvents(reviewId, query) {
+        return this.request('GET', withQuery(routes.humanReviewCommentEvents(this.reviewPath(reviewId)), query));
+    }
+    updateReviewCommentRanges(reviewId, req) {
+        return this.request('POST', routes.humanReviewCommentRanges(this.reviewPath(reviewId)), req);
+    }
+    getReviewComment(commentId) {
+        return this.request('GET', routes.humanComment(this.commentPath(commentId)));
+    }
+    editReviewComment(commentId, req) {
+        return this.request('POST', routes.humanCommentEdit(this.commentPath(commentId)), req);
+    }
+    resolveReviewComment(commentId, req = {}) {
+        return this.request('POST', routes.humanCommentResolve(this.commentPath(commentId)), req);
+    }
+    reopenReviewComment(commentId, req = {}) {
+        return this.request('POST', routes.humanCommentReopen(this.commentPath(commentId)), req);
+    }
+    deleteReviewComment(commentId, req = {}) {
+        return this.request('POST', routes.humanCommentDelete(this.commentPath(commentId)), req);
     }
     // ---- Humanloop inbox (Northlight crouter-inbox v1, inbox-contract.md §A) --
     /** Pending deck/review tickets across every available crouter-owned
@@ -406,6 +455,26 @@ export class CrtrClient {
         }
         return id;
     }
+    /** Validate a review id before route construction (D-A6). Reviews are minted
+     *  and addressed like node ids, but arrive from agent argv, so a malformed
+     *  one is a plausible request the server would also reject — `ApiError`,
+     *  not `TypeError`, matching `nodePath`. */
+    reviewPath(id) {
+        if (!isSafeNodeId(id)) {
+            throw new ApiError(400, 'invalid_review_id', `invalid review id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /** Validate a comment id before route construction (D-A6). Comment ids are
+     *  daemon-minted 32-char lowercase hex, but — like `reviewPath` — arrive from
+     *  agent argv, so a bad one is a plausible request the server would also
+     *  reject, not a caller-bug `TypeError` like `ticketId`. */
+    commentPath(id) {
+        if (!/^[a-f0-9]{32}$/.test(id)) {
+            throw new ApiError(400, 'invalid_comment_id', `invalid comment id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
     transport(method, path, body) {
         const usingHttps = this.baseUrl?.protocol === 'https:';
         const doRequest = usingHttps ? httpsRequest : httpRequest;

package/dist/dto/human.d.ts

@@ -1,29 +1,59 @@
-import type { IsoTime, NodeIdDTO } from './common.js';
-export type ConsultKindDTO = 'follow_up' | 'visual';
-/** A consult-outbox entry (the canvas half of a human consult/visual request). */
-export interface ConsultOutboxEntryDTO {
-    request_id: string;
-    node_id: NodeIdDTO;
-    kind: ConsultKindDTO;
-    dir: string;
-    created: IsoTime;
+import type { NodeIdDTO } from './common.js';
+import type { InteractionResponseDTO } from './inbox.js';
+/** One anchored review comment, mirroring crouter's ticket-store shape as a
+ *  plain structural wire type (no store import). */
+export interface FeedbackCommentDTO {
+    id: string;
+    /** 1-based source line where the comment is anchored (start). */
+    line: number;
+    /** 1-based source line where the anchored range ends (== line for one line). */
+    endLine: number;
+    /** Exact selected substring when the human made a visual selection. */
+    quote?: string;
+    /** 0-based byte column where a partial (charwise) selection starts on `line`. */
+    colStart?: number;
+    /** 0-based exclusive byte column where the selection ends on `endLine`. */
+    colEnd?: number;
+    /** Full source text of the anchored line(s) — context for the agent. */
+    lineText: string;
+    comment: string;
+    createdAt: string;
 }
-/** `GET /v1/canvas/consults` result. */
-export interface ConsultOutboxDTO {
-    entries: ConsultOutboxEntryDTO[];
+/** Immutable daemon-projected approval result, mirroring crouter's canonical
+ *  review result as a plain structural wire type — `src/api/**` never imports
+ *  the store's own type. */
+export interface FeedbackResultDTO {
+    file: string;
+    submitted: true;
+    approved: true;
+    comments: FeedbackCommentDTO[];
+    submittedAt: string;
+    savedAt: string;
+    reviewId: string;
+    changed: boolean;
+    baselineSha256: string;
+    approvedSha256: string;
+    companionNodeId: string;
+    commentsTotal: number;
+    commentsUnresolved: number;
 }
-/** `POST /v1/canvas/consults` body. */
-export interface CreateConsultRequest {
-    node_id: NodeIdDTO;
-    kind: ConsultKindDTO;
-    request_id: string;
-    dir: string;
-    root: string;
+/** `POST /v1/human/tickets/{node_id}/resolve` body — a deck answer. */
+export interface HumanResolveRequest {
+    responses: InteractionResponseDTO[];
+}
+/** `POST /v1/human/tickets/{node_id}/cancel` body. */
+export interface HumanCancelRequest {
+    reason?: string;
+    actor?: string;
 }
-/** Result of enqueuing a consult. */
-export interface ConsultResultDTO {
-    request_id: string;
-    created: boolean;
+/** `POST /v1/human/tickets/{node_id}/resolve` result. */
+export interface HumanResolveResultDTO {
+    delivered: true;
+    kind: 'deck';
+}
+/** `POST /v1/human/tickets/{node_id}/cancel` result. */
+export interface HumanCancelResultDTO {
+    canceled: true;
 }
 /** `POST /v1/human/bridge` body — create a terminal `kind:'human'` bridge node
  *  via `spawnNode` (NO broker engine). Distinct from `POST /v1/nodes`, whose
@@ -39,19 +69,3 @@ export interface HumanBridgeResultDTO {
     node_id: NodeIdDTO;
     name: string;
 }
-/** `POST /v1/human/deliver` result — the registered humanloop completion
- *  handler run server-side. */
-export interface HumanDeliverResultDTO {
-    delivered: boolean;
-}
-/** `POST /v1/human/consult` result — the registered follow-up handler run
- *  server-side. `handled` communicates whether an action was taken (never a
- *  throw for a stale/superseded event). */
-export interface HumanConsultResultDTO {
-    handled: boolean;
-}
-/** `POST /v1/human/visual` result — the registered visual handler run
- *  server-side. */
-export interface HumanVisualResultDTO {
-    handled: boolean;
-}

package/dist/dto/human.js

@@ -1,4 +1,3 @@
-// Human-bridge DTOs — the CANVAS HALF ONLY (spec §6.5). The humanloop
-// ticket/deck store is an external package and stays local; these cover the
-// `consult_outbox` rows that route through crtrd.
+// Human-bridge and crouter ticket-store DTOs — the canvas-facing wire shapes
+// for bridge work and ticket resolution through crtrd.
 export {};

package/dist/dto/inbox.d.ts

@@ -9,7 +9,6 @@ export interface DeckSourceDTO {
     askedBy?: string;
     blockedSince?: IsoTime;
     nodeId?: string;
-    visual?: 'humanloop.visual/v1';
 }
 export interface DeckTicketSummaryDTO {
     ticket_id: InboxTicketIdDTO;

package/dist/dto/nodes.d.ts

@@ -82,6 +82,14 @@ export interface NodeWorktreeDTO {
     created: IsoTime;
     closed?: IsoTime;
 }
+/** Immutable review-companion provenance and fork coordinates. Present only on
+ *  a `review/companion` node spawned by the daemon for a human review. */
+export interface NodeReviewBindingDTO {
+    review_id: string;
+    origin_node_id: string;
+    branch_file: string;
+    target_file: string;
+}
 /** The full node view — summary ∪ identity extras ∪ edges ∪ paths. Returned by
  *  `GET /v1/nodes/{id}` and by the create/lifecycle actions that yield a node. */
 export interface NodeDetailDTO extends NodeSummaryDTO {
@@ -111,6 +119,10 @@ export interface NodeDetailDTO extends NodeSummaryDTO {
      *  crtr-owned transcript mirror). Consumed by `memory origin` to deref a doc
      *  back to the conversation that authored it. */
     pi_session_file?: string | null;
+    /** Immutable review-companion provenance — present only on nodes of kind
+     *  `review/companion`. Four fields capture the invocation-time fork
+     *  coordinates without duplicating the full review record. */
+    review_binding?: NodeReviewBindingDTO | null;
     edges: NodeEdgesDTO;
     paths: NodePathsDTO;
     worktree?: NodeWorktreeDTO | null;

package/dist/dto/review-comments.d.ts

@@ -0,0 +1,137 @@
+import type { IsoTime, NodeIdDTO } from './common.js';
+export type ReviewCommentStatusDTO = 'open' | 'resolved' | 'deleted';
+export type ReviewCommentDeliverDTO = 'wake' | 'quiet';
+export type ReviewCommentAnchorStateDTO = 'live' | 'detached';
+/** Caller-supplied source location for a comment or range remap. */
+export interface ReviewCommentAnchorDTO {
+    line: number;
+    end_line: number;
+    col_start?: number;
+    col_end?: number;
+    quote?: string;
+}
+/** Daemon-derived current comment projection. */
+export interface ReviewCommentDTO {
+    comment_id: string;
+    review_id: string;
+    status: ReviewCommentStatusDTO;
+    revision: number;
+    text: string;
+    anchor: ReviewCommentAnchorDTO;
+    anchor_state: ReviewCommentAnchorStateDTO;
+    anchor_line_text: string;
+    anchor_doc_hash: string;
+    author: {
+        kind: 'human' | 'node';
+        node_id?: NodeIdDTO;
+    };
+    updated_by: {
+        kind: 'human' | 'node';
+        node_id?: NodeIdDTO;
+    };
+    created_at: IsoTime;
+    updated_at: IsoTime;
+    resolved_at?: IsoTime;
+    deleted_at?: IsoTime;
+    created_seq: number;
+}
+/** Caller-supplied body for comment creation. `doc_hash` is supplied by a rendered terminal surface; agent CLI creation omits it and the daemon verifies its current coordinate base instead. */
+export interface CreateReviewCommentRequest {
+    text: string;
+    anchor: ReviewCommentAnchorDTO;
+    doc_hash?: string;
+    actor_node_id?: NodeIdDTO | null;
+    deliver?: ReviewCommentDeliverDTO;
+}
+/** Caller-supplied body for comment text changes. */
+export interface EditReviewCommentRequest {
+    text: string;
+    actor_node_id?: NodeIdDTO | null;
+    deliver?: ReviewCommentDeliverDTO;
+    if_revision?: number;
+}
+/** Caller-supplied body for comment state changes. */
+export interface ReviewCommentActionRequest {
+    actor_node_id?: NodeIdDTO | null;
+    deliver?: ReviewCommentDeliverDTO;
+    if_revision?: number;
+}
+/** Daemon-derived best-effort companion-notification result. */
+export interface ReviewCommentDeliveryDTO {
+    attempted: boolean;
+    target_node_id?: NodeIdDTO;
+    status: 'delivered' | 'skipped' | 'failed';
+    via?: 'engine' | 'inbox';
+    woke: boolean;
+    error?: string;
+}
+/** Daemon-derived result of one comment mutation. */
+export interface ReviewCommentMutationDTO {
+    comment: ReviewCommentDTO;
+    changed: boolean;
+    delivery?: ReviewCommentDeliveryDTO;
+}
+/** Caller-supplied filter for a review's comment projection. */
+export interface ListReviewCommentsQuery {
+    status?: ReviewCommentStatusDTO | 'all';
+    actor_node_id?: NodeIdDTO | null;
+}
+/** Daemon-derived comment list. */
+export interface ReviewCommentListDTO {
+    review_id: string;
+    comments: ReviewCommentDTO[];
+}
+/** Daemon-derived one-comment projection and audit history. */
+export interface ReviewCommentDetailDTO {
+    comment: ReviewCommentDTO;
+    events: ReviewCommentEventDTO[];
+}
+/** Caller-supplied cursor/limit for the append-only review audit. */
+export interface ReadReviewCommentEventsQuery {
+    since_seq?: number;
+    limit?: number;
+}
+/** Daemon-derived page of append-only review comment events. */
+export interface ReviewCommentEventsDTO {
+    review_id: string;
+    events: ReviewCommentEventDTO[];
+    next_since_seq: number | null;
+}
+/** Daemon-derived append-only comment audit event. */
+export interface ReviewCommentEventDTO {
+    seq: number;
+    review_id: string;
+    comment_id: string;
+    kind: 'created' | 'edited' | 'resolved' | 'reopened' | 'deleted' | 'reanchored' | 'notified' | 'notify_failed';
+    state_change: boolean;
+    revision_after: number | null;
+    actor: {
+        kind: 'human' | 'node' | 'system';
+        node_id?: NodeIdDTO;
+    };
+    at: IsoTime;
+    operation_id: string;
+    payload?: unknown;
+}
+/** Caller-supplied replacement location for one nondeleted comment. */
+export type ReviewCommentRangeEntryDTO = {
+    comment_id: string;
+    anchor: ReviewCommentAnchorDTO;
+} | {
+    comment_id: string;
+    detached: true;
+};
+/** Caller-supplied atomic full-set range remap body. */
+export interface ReviewCommentRangeBatchRequest {
+    from_doc_hash: string;
+    to_doc_hash: string;
+    entries: ReviewCommentRangeEntryDTO[];
+}
+/** Daemon-derived result of an atomic full-set range remap. */
+export interface ReviewCommentRangeBatchResultDTO {
+    review_id: string;
+    anchor_base_sha256: string;
+    updated: number;
+    detached: number;
+    unchanged: number;
+}

package/dist/dto/review-comments.js

@@ -0,0 +1,5 @@
+// Daemon-owned review comment DTOs. These are HTTP wire contracts only.
+//
+// PURITY: imports remain within `src/api/*`; daemon/store types do not cross
+// this boundary.
+export {};

package/dist/dto/reviews.d.ts

@@ -0,0 +1,109 @@
+import type { IsoTime, NodeIdDTO, NodeStatusDTO } from './common.js';
+import type { FeedbackResultDTO } from './human.js';
+export type ReviewOriginKindDTO = 'ticket' | 'inline';
+/** `binding` is intentionally never exposed over the API. */
+export type ReviewStateDTO = 'open' | 'approved' | 'canceled';
+/** Caller-supplied body for `POST /v1/human/reviews`. */
+export interface CreateReviewRequest {
+    /** Caller-selected review origin. */
+    origin_kind: ReviewOriginKindDTO;
+    /** Caller-selected node whose persisted session is forked. */
+    origin_node_id: NodeIdDTO;
+    /** Caller-selected absolute file path; the daemon canonicalizes and validates it. */
+    file: string;
+    /** Caller-minted invocation key; the daemon enforces its uniqueness. */
+    idempotency_key: string;
+    /** Caller-supplied ticket subtitle; required for ticket origins. */
+    subtitle?: string;
+    /** Caller-supplied ticket-only projection destination. */
+    output_path?: string;
+}
+/** Daemon-derived canonical review projection. */
+export interface ReviewDTO {
+    /** Daemon-minted opaque review identity. */
+    review_id: string;
+    /** Daemon-recorded origin kind. */
+    origin_kind: ReviewOriginKindDTO;
+    /** Daemon-recorded originating node. */
+    origin_node_id: NodeIdDTO;
+    /** Daemon-recorded ticket bridge, when this review came from a ticket. */
+    bridge_node_id: NodeIdDTO | null;
+    /** Daemon-preallocated companion node. */
+    companion_node_id: NodeIdDTO;
+    /** Daemon-canonicalized reviewed file path. */
+    file: string;
+    /** Daemon lifecycle state; never `binding`. */
+    state: ReviewStateDTO;
+    /** Daemon capture timestamp. */
+    created: IsoTime;
+    /** Daemon open timestamp, after the companion binds. */
+    opened_at?: IsoTime;
+    /** Daemon source-read status at projection time. */
+    source_missing: boolean;
+    /** Daemon-owned current comment-coordinate source digest. */
+    anchor_base_sha256: string;
+    /** Daemon approval timestamp. */
+    approved_at?: IsoTime;
+    /** Daemon comparison of approval bytes to the invocation baseline. */
+    changed?: boolean;
+    /** Daemon snapshot count at approval. */
+    comments_total?: number;
+    /** Daemon unresolved-comment count at approval. */
+    comments_unresolved?: number;
+    /** Daemon cancellation timestamp. */
+    canceled_at?: IsoTime;
+    /** Daemon-recorded caller cancellation reason. */
+    cancel_reason?: string;
+    /** Daemon-recorded cancellation actor. */
+    cancel_actor?: string;
+    /** Daemon-owned immutable result projection path. */
+    result_path?: string;
+    /** Daemon-recorded approval delivery error, when delivery failed after commit. */
+    delivery_error?: string;
+    /** Daemon-recorded result projection error, when publication failed after commit. */
+    projection_error?: string;
+}
+/** Caller-supplied optional filters for `GET /v1/human/reviews`. */
+export interface ListReviewsQuery {
+    state?: ReviewStateDTO;
+    origin_node_id?: NodeIdDTO;
+    file?: string;
+}
+/** Daemon-derived review list. */
+export interface ReviewListDTO {
+    reviews: ReviewDTO[];
+}
+/** Daemon-derived result of opening an active review or acknowledging a terminal one. */
+export type ReviewOpenResultDTO = {
+    review: ReviewDTO;
+    companion_node_id: NodeIdDTO;
+    companion_status: NodeStatusDTO;
+    disposition: 'open';
+} | {
+    review: ReviewDTO;
+    disposition: 'terminal';
+};
+/** Daemon-derived result of terminal review approval. */
+export interface ReviewSubmitResultDTO {
+    review: ReviewDTO;
+    /** Immutable approval result. */
+    result: FeedbackResultDTO;
+    outcome: 'settled' | 'already_settled';
+}
+/** Daemon-derived result of terminal review cancellation. */
+export interface ReviewCancelResultDTO {
+    review: ReviewDTO;
+    outcome: 'settled' | 'already_settled';
+}
+/** Caller-supplied optional cancellation context. */
+export interface CancelReviewRequest {
+    reason?: string;
+    actor?: string;
+}
+/** Daemon-derived coordinate base for the terminal review surface. */
+export interface ReviewDocumentBaseDTO {
+    review_id: string;
+    anchor_base_sha256: string;
+    anchor_base_text: string;
+    file: string;
+}

package/dist/dto/reviews.js

@@ -0,0 +1,5 @@
+// Canonical daemon-owned review DTOs. These are HTTP wire contracts only.
+//
+// PURITY: imports remain within `src/api/*`; daemon/store types do not cross
+// this boundary.
+export {};

package/dist/index.d.ts

@@ -22,3 +22,5 @@ export * from './dto/worktree.js';
 export * from './dto/human.js';
 export * from './dto/files.js';
 export * from './dto/inbox.js';
+export * from './dto/reviews.js';
+export * from './dto/review-comments.js';

package/dist/index.js

@@ -23,3 +23,5 @@ export * from './dto/worktree.js';
 export * from './dto/human.js';
 export * from './dto/files.js';
 export * from './dto/inbox.js';
+export * from './dto/reviews.js';
+export * from './dto/review-comments.js';

package/dist/routes.d.ts

@@ -48,11 +48,24 @@ export declare const routes: {
     readonly canvasRoster: () => string;
     readonly canvasPrune: () => string;
     readonly canvasRebuildIndex: () => string;
-    readonly canvasConsults: () => string;
     readonly humanBridge: () => string;
-    readonly humanDeliver: () => string;
-    readonly humanConsult: () => string;
-    readonly humanVisual: () => string;
+    readonly humanTicketResolve: (nodeId: string) => string;
+    readonly humanTicketCancel: (nodeId: string) => string;
+    readonly humanReviews: () => string;
+    readonly humanReview: (reviewId: string) => string;
+    readonly humanReviewByBridge: (bridgeNodeId: string) => string;
+    readonly humanReviewOpen: (reviewId: string) => string;
+    readonly humanReviewSubmit: (reviewId: string) => string;
+    readonly humanReviewCancel: (reviewId: string) => string;
+    readonly humanReviewDocument: (reviewId: string) => string;
+    readonly humanReviewComments: (reviewId: string) => string;
+    readonly humanReviewCommentEvents: (reviewId: string) => string;
+    readonly humanReviewCommentRanges: (reviewId: string) => string;
+    readonly humanComment: (commentId: string) => string;
+    readonly humanCommentEdit: (commentId: string) => string;
+    readonly humanCommentResolve: (commentId: string) => string;
+    readonly humanCommentReopen: (commentId: string) => string;
+    readonly humanCommentDelete: (commentId: string) => string;
     readonly humanInbox: () => string;
     readonly humanInboxTicket: (ticketId: string) => string;
     readonly humanInboxRespond: (ticketId: string) => string;

package/dist/routes.js

@@ -70,12 +70,28 @@ export const routes = {
     canvasRoster: () => `${V}/canvas/roster`,
     canvasPrune: () => `${V}/canvas/prune`,
     canvasRebuildIndex: () => `${V}/canvas/rebuild-index`,
-    canvasConsults: () => `${V}/canvas/consults`,
-    // Human bridge + completion-handler forwarding (spec §6.5)
+    // Human bridge creation + the pinned ticket route table (design §"The `/v1`
+    // surface") — every ticket route is addressed by node id only.
     humanBridge: () => `${V}/human/bridge`,
-    humanDeliver: () => `${V}/human/deliver`,
-    humanConsult: () => `${V}/human/consult`,
-    humanVisual: () => `${V}/human/visual`,
+    humanTicketResolve: (nodeId) => `${V}/human/tickets/${nodeId}/resolve`,
+    humanTicketCancel: (nodeId) => `${V}/human/tickets/${nodeId}/cancel`,
+    // Daemon-owned document reviews and comments. All interpolated ids are
+    // guarded by `CrtrClient` before they reach these pure builders.
+    humanReviews: () => `${V}/human/reviews`,
+    humanReview: (reviewId) => `${V}/human/reviews/${reviewId}`,
+    humanReviewByBridge: (bridgeNodeId) => `${V}/human/reviews/by-bridge/${bridgeNodeId}`,
+    humanReviewOpen: (reviewId) => `${V}/human/reviews/${reviewId}/open`,
+    humanReviewSubmit: (reviewId) => `${V}/human/reviews/${reviewId}/submit`,
+    humanReviewCancel: (reviewId) => `${V}/human/reviews/${reviewId}/cancel`,
+    humanReviewDocument: (reviewId) => `${V}/human/reviews/${reviewId}/document`,
+    humanReviewComments: (reviewId) => `${V}/human/reviews/${reviewId}/comments`,
+    humanReviewCommentEvents: (reviewId) => `${V}/human/reviews/${reviewId}/comment-events`,
+    humanReviewCommentRanges: (reviewId) => `${V}/human/reviews/${reviewId}/comment-ranges`,
+    humanComment: (commentId) => `${V}/human/comments/${commentId}`,
+    humanCommentEdit: (commentId) => `${V}/human/comments/${commentId}/edit`,
+    humanCommentResolve: (commentId) => `${V}/human/comments/${commentId}/resolve`,
+    humanCommentReopen: (commentId) => `${V}/human/comments/${commentId}/reopen`,
+    humanCommentDelete: (commentId) => `${V}/human/comments/${commentId}/delete`,
     // Humanloop inbox (Northlight crouter-inbox v1, inbox-contract.md §A)
     humanInbox: () => `${V}/human/inbox`,
     humanInboxTicket: (ticketId) => `${V}/human/inbox/${ticketId}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.171",
+  "version": "0.3.173",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/index.js",