@north-light/api 0.0.0 → 0.3.414

package/dist/api/dto/recovery.d.ts

@@ -0,0 +1,104 @@
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'daemon→node' | 'crtr→pi';
+export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
+export interface FaultRetry {
+    disposition: 'auto' | 'manual' | 'fatal';
+    by?: 'sdk' | 'daemon' | 'client';
+    attempt?: number;
+    max?: number;
+    nextAt?: string;
+}
+export interface FaultProviderError {
+    provider: string;
+    model: string;
+    status?: number;
+    code?: string | number;
+    errno?: string;
+    body?: string;
+    causes?: Array<{
+        message?: string;
+        status?: number;
+        code?: string | number;
+        errno?: string;
+        body?: string;
+    }>;
+    ratelimit?: {
+        scope?: string;
+        claim?: string;
+        account?: string;
+        model?: string;
+        headers: Record<string, string>;
+    };
+}
+export interface RecoveryFaultDTO {
+    fault_id: string;
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    since: string;
+    operation_id: string;
+    anchor_entry_id?: string;
+    provider_error?: FaultProviderError;
+}
+export interface ExecutionExitDiagnosticDTO {
+    schema: 'crtr.execution-exit-diagnostic/v1';
+    transport_poison: {
+        consecutive_passes: number;
+        routes: string[];
+    };
+}
+export interface BrokerTurnResultDTO {
+    applied: boolean;
+    fault_link: FaultLink | null;
+}
+export interface BrokerTurnRequest {
+    expected_execution_id: string;
+    event: 'started' | 'progress' | 'closed' | 'interrupted' | 'exit-diagnostic';
+    end_reason?: 'settled' | 'teardown-aborted';
+    exit_diagnostic?: ExecutionExitDiagnosticDTO;
+}
+export interface BrokerFaultInputDTO {
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    operation_id?: string;
+    since?: string;
+    anchor_entry_id?: string;
+    provider_error?: FaultProviderError;
+}
+export interface BrokerFaultResultDTO {
+    fault: RecoveryFaultDTO | null;
+}
+export interface BrokerFaultRequest {
+    expected_execution_id: string;
+    op: 'record' | 'clear';
+    link?: FaultLink;
+    preserve_episode?: boolean;
+    input?: BrokerFaultInputDTO;
+}
+export interface BrokerProviderRetryResultDTO {
+    applied: boolean;
+    episode: RecoveryStateDTO['episode'];
+}
+export interface BrokerProviderRetryRequest {
+    expected_execution_id: string;
+    op: 'record-pending' | 'admit' | 'reopen' | 'invalidate' | 'clear';
+    session_id: string;
+    fault_id?: string;
+    retry?: FaultRetry;
+    input?: BrokerFaultInputDTO;
+}
+export interface RecoveryStateDTO {
+    fault: RecoveryFaultDTO | null;
+    episode: {
+        state: 'pending' | 'admitted' | 'invalidated';
+        session_id: string | null;
+        fault: RecoveryFaultDTO;
+    } | null;
+}
+export interface NodeFaultClearResultDTO {
+    cleared: boolean;
+}

package/dist/api/dto/recovery.js

@@ -0,0 +1 @@
+export {};

package/dist/api/dto/reports.d.ts

@@ -0,0 +1,95 @@
+import type { IsoTime, NodeIdDTO } from './common.js';
+/** Report kind — `crtr push {update,final}`; legacy `urgent` rows remain readable. */
+export type ReportTierDTO = 'update' | 'urgent' | 'final';
+/** Delivery urgency for an update report's subscriber fan-out. */
+export type ReportDeliveryTierDTO = 'deferred' | 'normal' | 'urgent';
+/** `POST /v1/nodes/{id}/reports` body ({id} = the reporting node).
+ * `tier` is the stored report kind; `delivery_tier` is the optional inbox
+ * delivery urgency for an update's subscriber fan-out. */
+export interface PushReportRequest {
+    tier: ReportTierDTO;
+    delivery_tier?: ReportDeliveryTierDTO;
+    body: string;
+}
+/** Result of a push. `transitioned` is present only for `final`, which drives a
+ *  server-side lifecycle transition. */
+export interface PushReportResultDTO {
+    /** The written report document's ref, `<node-id>/reports/<name>`. */
+    report: string;
+    /** Subscriber node ids that received an inbox entry. */
+    notified: NodeIdDTO[];
+    transitioned?: {
+        from: string;
+        to: string;
+    };
+    /** Present (and true) only for a `final` push that closes the reporting
+     *  node's managed-worktree record without `node worktree close`. An existing
+     *  checkout must be clean with its tip contained in the local base and stays
+     *  pending cleanup; a missing checkout must be proven delivered. Work not
+     *  proven delivered blocks with an `open_managed_worktree` error. */
+    worktree_auto_dropped?: boolean;
+    /** Present only alongside `worktree_auto_dropped`: the closed managed-worktree path; an existing checkout remains until pending cleanup. */
+    worktree_auto_dropped_path?: string;
+}
+/** Why a node declined a structured result. `reason` is one plain sentence
+ *  for a reader; `code` is an opaque token the requester classifies on and
+ *  validates itself — crouter only carries it; `retryable` is the node's
+ *  claim that the same request could succeed later. */
+export interface DeclinedResultDTO {
+    reason: string;
+    code: string;
+    retryable: boolean;
+}
+/** `POST /v1/nodes/{id}/result` body ({id} = the submitting node). `request_id`
+ *  identifies the pending structured request. Either `value` is validated
+ *  against that request's schema — any JSON value (including null) is legal
+ *  input — or a decline carries the reason sentence, requester-classified
+ *  code, and retry claim. A decline records a `failure` outcome with reason
+ *  `declined` carrying all three and clears the request without validating
+ *  anything. */
+export type SubmitResultRequest = {
+    request_id: string;
+} & ({
+    value: unknown;
+} | {
+    decline: string;
+    code: string;
+    retryable: boolean;
+});
+/** Result of a structured-result submission (`crtr push result`). Terminal
+ *  mode reuses the final-push machinery, so `transitioned` and the managed-worktree
+ *  closure fields carry the same meaning as on PushReportResultDTO. */
+export interface SubmitResultDTO {
+    /** Which request this answered: `terminal` finished the node; `oneoff` left it working. */
+    mode: 'terminal' | 'oneoff';
+    /** Absolute path of the recorded artifact: context/result.json for an
+     *  answered request, context/declined.json for a declined one. */
+    result_path: string;
+    /** Present only when the request was declined. */
+    declined?: DeclinedResultDTO;
+    /** Ref of the report document pushed alongside the result, `<node-id>/reports/<name>`. */
+    report: string;
+    /** Subscriber node ids that received an inbox entry. */
+    notified: NodeIdDTO[];
+    transitioned?: {
+        from: string;
+        to: string;
+    };
+    worktree_auto_dropped?: boolean;
+    worktree_auto_dropped_path?: string;
+}
+/** `GET /v1/nodes/{id}/reports` query filters. */
+export interface ReportsQuery {
+    tier?: ReportTierDTO;
+    limit?: number;
+}
+/** A single stored report document. */
+export interface ReportDTO {
+    /** Document name under the node, `reports/<compact-ts>-<uuid8>-<kind>`. */
+    name: string;
+    /** Document object id. */
+    id: string;
+    tier: ReportTierDTO;
+    body: string;
+    created: IsoTime;
+}

package/dist/api/dto/reports.js

@@ -0,0 +1,2 @@
+// Push / report DTOs (spec §7.4).
+export {};

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

@@ -0,0 +1,146 @@
+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;
+    reason?: 'capacity_frozen';
+    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;
+}
+/** Daemon-derived result of forking the review companion onto one comment. */
+export interface ReviewCommentForkDTO {
+    comment_id: string;
+    /** The newborn fork of the review companion. */
+    node_id: NodeIdDTO;
+    /** Where the fork runs, so a caller can place a viewer for it. */
+    cwd: string;
+}

package/dist/api/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/api/dto/reviews.d.ts

@@ -0,0 +1,113 @@
+import type { IsoTime, NodeIdDTO } 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;
+    /** The document to review, as a canvas ref (`[[ ]]` optional) — required for ticket reviews,
+     *  and the alternative to `file` for inline ones. The daemon reads it as the caller, snapshots
+     *  its head to `<review_dir>/document.md`, and on submit saves the reviewed text as a new
+     *  revision (refused as `stale_revision` if it moved). */
+    document?: string;
+    /** Inline reviews of a file: an absolute path; the daemon canonicalizes and validates it.
+     *  An inline review takes exactly one of `file` or `document`. */
+    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-owned directory containing the review branch and terminal result. */
+    review_dir: string;
+    /** Daemon-preallocated companion node. */
+    companion_node_id: NodeIdDTO;
+    /** Daemon-canonicalized reviewed file path (for a document review, its `document.md` snapshot). */
+    file: string;
+    /** The reviewed document's `<owner>/<name>`, for a document review. */
+    document?: string;
+    /** Daemon lifecycle state; never `binding`. */
+    state: ReviewStateDTO;
+    /** Daemon capture timestamp. */
+    created: IsoTime;
+    /** Daemon open timestamp, after the companion binds. */
+    opened_at?: IsoTime;
+    /** When the human submitted a review whose companion was still working. The
+     *  review remains `open` until the companion goes quiet. */
+    submit_requested_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 review approval, which may still be waiting on the
+ *  review's companion. */
+export interface ReviewSubmitResultDTO {
+    review: ReviewDTO;
+    /** Immutable approval result; absent while the approval awaits the companion. */
+    result?: FeedbackResultDTO;
+    outcome: 'settled' | 'already_settled' | 'awaiting_companion';
+}
+/** 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;
+    /** Recipient surfaces send `dismissed`; a requester withdrawal defaults to `canceled`. */
+    disposition?: 'canceled' | 'dismissed';
+}
+/** 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/api/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 {};