@north-light/crouter 0.3.312 → 0.3.313

package/dist/core/human/root.d.ts

@@ -1,10 +1,3 @@
-export declare function ticketsRoot(): string;
-/** The opaque id the `/v1/human/inbox` routes address a ticket by — a hash of
- * the canonical tickets root and the ticket directory basename. The daemon
- * derives the same value when it resolves a route id back to a directory. */
-export declare function opaqueInboxTicketId(ticketId: string): string;
-/** Ticket directories share the canvas node root. Reply-bearing tickets may use their bridge id; standalone pages use an independent ticket id. */
-export declare function ticketDir(ticketId: string): string;
 export declare function inboxActivityPath(): string;
 /** Signal one durable ticket mutation to every open inbox without watching every ticket directory. */
 export declare function signalInboxActivity(): void;

package/dist/core/human/root.js

@@ -1,21 +1,4 @@
-import { realpathSync } from 'node:fs';
-import { createHash } from 'node:crypto';
-import { nodeDir, nodesRoot } from '../canvas/paths.js';
 import { activityPath, signalActivity, watchActivity } from '../activity-signal.js';
-export function ticketsRoot() {
-    return nodesRoot();
-}
-/** The opaque id the `/v1/human/inbox` routes address a ticket by — a hash of
- * the canonical tickets root and the ticket directory basename. The daemon
- * derives the same value when it resolves a route id back to a directory. */
-export function opaqueInboxTicketId(ticketId) {
-    const canonicalRoot = realpathSync(ticketsRoot());
-    return createHash('sha256').update(`${canonicalRoot}\0${ticketId}`, 'utf8').digest('hex');
-}
-/** Ticket directories share the canvas node root. Reply-bearing tickets may use their bridge id; standalone pages use an independent ticket id. */
-export function ticketDir(ticketId) {
-    return nodeDir(ticketId);
-}
 export function inboxActivityPath() {
     return activityPath('inbox-activity');
 }

package/dist/core/human/scan.d.ts

@@ -1,11 +1,6 @@
 import type { PageTicketSummary, TicketSummary } from './types.js';
-/** Read all unresolved page/review tickets, newest first. Progress never affects visibility. */
+/** SQL-backed inbox discovery. Files in request_dir are presentation projections only. */
 export declare function scanInbox(): TicketSummary[];
 export type PageHistoryEntry = PageTicketSummary;
-/**
- * Every page ticket — pending, resolved or canceled — oldest first, optionally
- * narrowed to one raising node. This is the durable discovery seam for
- * transcript placement and for browsing settled tickets, so it is a separate
- * walk from the pending-only inbox scan and never filters on a terminal file.
- */
+/** SQL-backed page history, including terminal requests. */
 export declare function scanPageHistory(nodeId?: string): PageHistoryEntry[];

package/dist/core/human/scan.js

@@ -1,153 +1,69 @@
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { basename, join } from 'node:path';
-import { claimPath, isResolved, pageManifestPath, reviewPath } from './convention.js';
-import { readJsonOrNull } from '../fs-utils.js';
-import { validateReviewDescriptor } from './review-schema.js';
 import { pageAwaitsResponse, pageOverviewActions } from './page-schema.js';
-import { parsePage } from './page.js';
-import { pageTicketState, readTicketResult } from './tickets.js';
-import { ticketsRoot } from './root.js';
-import { emitEvent } from '../events/emit.js';
-function errorText(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function claimSummary(dir) {
-    const claim = readJsonOrNull(claimPath(dir));
-    if (claim === null || typeof claim.host !== 'string' || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string')
-        return undefined;
-    return { owner: claim.host, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt };
-}
-function reviewSummary(dir, id) {
-    const raw = readJsonOrNull(reviewPath(dir));
-    if (raw === null)
-        return null;
-    let review;
+import { listRequests } from './requests.js';
+function specification(request) {
     try {
-        review = validateReviewDescriptor(raw);
+        const value = JSON.parse(request.specification_json);
+        if (typeof value !== 'object' || value === null)
+            throw new Error('not an object');
+        return value;
     }
-    catch {
-        return null;
+    catch (error) {
+        throw new Error(`corrupt human request specification: ${request.request_id}`, { cause: error });
     }
-    return { dir, id, kind: 'review', title: review.title, subtitle: review.subtitle, file: review.file, output: review.output, source: review.source, blockedSince: review.blockedSince, claim: claimSummary(dir) };
 }
-function pageSummary(dir, id) {
-    // The tickets root IS the canvas node root, so all but a handful of these
-    // directories hold no page at all. Gate on the manifest's presence with one
-    // stat instead of letting `parsePage` throw: a thrown ENOENT carries a V8
-    // stack capture, which over thousands of node directories is the whole cost
-    // of a scan.
-    if (!existsSync(pageManifestPath(dir)))
-        return null;
-    let manifest;
-    try {
-        manifest = parsePage(dir);
-    }
-    catch {
-        return null;
-    }
-    let emittedAt = manifest.source?.emittedAt;
-    if (emittedAt === undefined) {
-        try {
-            emittedAt = statSync(pageManifestPath(dir)).mtime.toISOString();
-        }
-        catch {
-            return null;
-        }
-    }
-    const state = pageTicketState(dir);
+function pageSummary(request) {
+    const manifest = specification(request);
     const { recommendedOptions, fastAction } = pageOverviewActions(manifest);
+    const result = request.result_json === null ? null : JSON.parse(request.result_json);
+    const state = request.state !== 'settled' ? (request.settleable ? 'pending' : 'passive') : request.outcome === 'canceled' || request.outcome === 'dismissed' ? 'canceled' : 'resolved';
     return {
-        dir,
-        id,
+        dir: request.request_dir,
+        id: request.request_id,
+        inboxTicketId: request.inbox_ticket_id,
         kind: 'page',
-        title: manifest.title,
-        subtitle: manifest.subtitle ?? '',
+        title: request.title,
+        subtitle: request.subtitle ?? '',
         dialect: manifest.dialect,
         placement: manifest.delivery.placement,
-        inbox: manifest.delivery.inbox,
+        inbox: request.inbox_listed,
         steps: manifest.steps,
         slotKinds: manifest.slots.map((slot) => slot.kind),
         awaitsResponse: pageAwaitsResponse(manifest),
         source: manifest.source ?? {},
-        emittedAt,
-        state,
+        emittedAt: typeof manifest.source?.emittedAt === 'string' ? manifest.source.emittedAt : request.created_at,
         recommendedOptions,
-        // A settled ticket has nothing left to publish, so only a pending one offers the keypress.
-        ...(fastAction !== undefined && state === 'pending' ? { fastAction } : {}),
-        claim: claimSummary(dir),
+        ...(fastAction === undefined || state !== 'pending' ? {} : { fastAction }),
+        state,
+        ...(result?.kind === 'page' ? { answerDigest: result.summary.replace(/\s+/g, ' ').trim() } : {}),
     };
 }
-/** Read all unresolved page/review tickets, newest first. Progress never affects visibility. */
+function reviewSummary(request) {
+    const spec = specification(request);
+    const source = { nodeId: request.requester_node_id ?? undefined };
+    return {
+        dir: request.request_dir,
+        id: request.request_id,
+        inboxTicketId: request.inbox_ticket_id,
+        kind: 'review',
+        title: request.title,
+        subtitle: request.subtitle ?? '',
+        file: request.file ?? '',
+        output: typeof spec['output_path'] === 'string' ? spec['output_path'] : `${request.request_dir}/result.json`,
+        source,
+        blockedSince: request.created_at,
+    };
+}
+/** SQL-backed inbox discovery. Files in request_dir are presentation projections only. */
 export function scanInbox() {
-    let entries;
-    try {
-        entries = readdirSync(ticketsRoot());
-    }
-    catch {
-        return [];
-    }
-    const items = [];
-    for (const entry of entries) {
-        const dir = join(ticketsRoot(), entry);
-        try {
-            if (!statSync(dir).isDirectory())
-                continue;
-        }
-        catch {
-            continue;
-        }
-        if (isResolved(dir))
-            continue;
-        let item;
-        try {
-            item = reviewSummary(dir, basename(dir)) ?? pageSummary(dir, basename(dir));
-        }
-        catch (error) {
-            emitEvent({ level: 'warn', event: 'human.scan.ticket_unreadable', fields: { ticket_id: basename(dir), error: errorText(error) } });
-            continue;
-        }
-        if (item !== null && (item.kind !== 'page' || item.inbox))
-            items.push(item);
-    }
-    return items.sort((a, b) => (b.kind === 'page' ? b.emittedAt : b.blockedSince).localeCompare(a.kind === 'page' ? a.emittedAt : a.blockedSince) || a.id.localeCompare(b.id));
+    return listRequests({ state: 'open' })
+        .filter((request) => request.inbox_listed)
+        .map((request) => request.kind === 'page' ? pageSummary(request) : reviewSummary(request))
+        .sort((a, b) => (b.kind === 'page' ? b.emittedAt : b.blockedSince).localeCompare(a.kind === 'page' ? a.emittedAt : a.blockedSince) || a.id.localeCompare(b.id));
 }
-/**
- * Every page ticket — pending, resolved or canceled — oldest first, optionally
- * narrowed to one raising node. This is the durable discovery seam for
- * transcript placement and for browsing settled tickets, so it is a separate
- * walk from the pending-only inbox scan and never filters on a terminal file.
- */
+/** SQL-backed page history, including terminal requests. */
 export function scanPageHistory(nodeId) {
-    let entries;
-    try {
-        entries = readdirSync(ticketsRoot());
-    }
-    catch {
-        return [];
-    }
-    const items = [];
-    for (const entry of entries) {
-        const dir = join(ticketsRoot(), entry);
-        try {
-            if (!statSync(dir).isDirectory())
-                continue;
-        }
-        catch {
-            continue;
-        }
-        try {
-            const summary = pageSummary(dir, basename(dir));
-            if (summary === null)
-                continue;
-            if (nodeId !== undefined && summary.source.nodeId !== nodeId)
-                continue;
-            const result = summary.state === 'resolved' ? readTicketResult(dir) : null;
-            items.push({ ...summary, ...(result?.kind === 'page' ? { answerDigest: result.summary.replace(/\s+/g, ' ').trim() } : {}) });
-        }
-        catch (error) {
-            emitEvent({ level: 'warn', event: 'human.scan.ticket_unreadable', fields: { ticket_id: basename(dir), error: errorText(error) } });
-            continue;
-        }
-    }
-    return items.sort((a, b) => Date.parse(a.emittedAt) - Date.parse(b.emittedAt) || a.id.localeCompare(b.id));
+    return listRequests({ kind: 'page' })
+        .map(pageSummary)
+        .filter((page) => nodeId === undefined || page.source.nodeId === nodeId)
+        .sort((a, b) => Date.parse(a.emittedAt) - Date.parse(b.emittedAt) || a.id.localeCompare(b.id));
 }

package/dist/core/human/summary.d.ts

@@ -1,3 +1,3 @@
 import type { PageManifest, PageResponses } from './page-schema.js';
-/** The stable one-line digest stored in response.json. */
+/** The stable one-line digest stored in the terminal request result. */
 export declare function buildPageSummary(manifest: PageManifest, responses: PageResponses): string;

package/dist/core/human/summary.js

@@ -1,5 +1,5 @@
 import { describePageAnswer } from './answer.js';
-/** The stable one-line digest stored in response.json. */
+/** The stable one-line digest stored in the terminal request result. */
 export function buildPageSummary(manifest, responses) {
     return describePageAnswer(manifest, responses, { completedAt: '' }).digest;
 }

package/dist/core/human/tickets.d.ts

@@ -1,86 +1,28 @@
-import type { ReviewDescriptor, TicketResult } from './types.js';
-import type { ProductPageComponents } from '../../types.js';
-import { type PageDelivery, type PageManifest, type PageResponses, type PageSource } from './page-schema.js';
-/** Strict decoder for the only canonical final marker. Only a missing file reads
- *  as absent — a corrupt (unparseable) response is a real anomaly and throws,
- *  since silently treating it as "no result yet" would mask data loss instead
- *  of surfacing it to whichever caller owns the failure boundary. */
+import type { TicketResult } from './types.js';
+import type { PreparedPage } from './page-authoring.js';
+import { type PageManifest, type PageResponses } from './page-schema.js';
+/** Strict decoder for the canonical SQL terminal result. A corrupt result throws
+ *  rather than being treated as absent, because that would hide data loss from
+ *  the caller that owns the failure boundary. */
 export declare function readTicketResult(dir: string): TicketResult | null;
-export interface SubmitPageOptions {
-    dir: string;
-    /** The authored page source; copied into the ticket directory as its `document`. */
-    sourceFile: string;
-    source?: PageSource;
-    productKinds?: ProductPageComponents;
-    delivery?: PageDelivery;
-}
-/** One validated page, ready to publish into a ticket directory. */
-export interface PreparedPage {
-    /** The authored source, verbatim, as the ticket's `document`. */
-    document: string;
-    /** The compiled CommonJS module the Gateway evaluates for JSX pages. */
-    module?: string;
-    manifest: PageManifest;
-}
-export interface PreparePageSourceOptions {
-    /** `jsx` carries .tsx semantics; `html` is a complete document. */
-    dialect: 'jsx' | 'html';
-    /** The complete authored page text, inline. */
-    document: string;
-    source?: PageSource;
-    productKinds?: ProductPageComponents;
-    delivery?: PageDelivery;
-}
-/** Validate one authored page document into publishable form. The single
- *  validation path: `preparePage` reads a file and lands here, and a
- *  programmatic request supplies the same text inline. */
-export declare function preparePageSource(opts: PreparePageSourceOptions): PreparedPage;
-/** Validate one authored page source file into publishable form. Reads only: a
- *  page that fails authoring leaves nothing behind, so a caller that must create
- *  a bridge node prepares first and creates it only once the page is known good.
- *  The source is read exactly once, so the published document is the same bytes
- *  the manifest was derived from even if the file changes underneath. */
-export declare function preparePage(opts: Omit<SubmitPageOptions, 'dir'>): PreparedPage;
-/** Publish one prepared page ticket: the authored source plus its manifest.
- * These writes are overwrites. A ticket's REQUEST is whatever page the agent
- * currently wants on screen, and `crtr human send --replace` revises it in
- * place while the human watches; only the ANSWER is write-once, which
- * `publishJsonExclusive` still guarantees for response.json alone. The manifest
- * switches after all new generation files exist, then stale media is removed. */
+/** Publish an immutable revision, then atomically select it with its matching specification. */
 export declare function publishPage(dir: string, prepared: PreparedPage): {
     id: string;
     dir: string;
     kind: 'page';
     manifest: PageManifest;
 };
-/** Validate and publish one page ticket in a single step, for callers that own
- *  the ticket directory before they have a page. */
-export declare function submitPage(opts: SubmitPageOptions): {
-    id: string;
-    dir: string;
-    kind: 'page';
-    manifest: PageManifest;
-};
-export interface SubmitReviewOptions {
-    dir: string;
-    review: Omit<ReviewDescriptor, 'schema' | 'file' | 'output' | 'blockedSince'> & {
-        file: string;
-        output?: string;
-        blockedSince?: string;
-    };
-}
-export declare function submitReview(opts: SubmitReviewOptions): {
-    id: string;
-    dir: string;
-    kind: 'review';
-};
-/** Validate a page resolution against its canonical ticket before claim takeover. */
+/** Resolve a stable request directory to the SQL-selected immutable page revision. */
+export declare function selectedPageDir(dir: string): string;
+/** Validate a final page response against its ticket's reply contract. */
+export declare function validateFinalPageResponses(manifest: PageManifest, responses: unknown): PageResponses;
+/** Validate a page resolution against its SQL-selected immutable revision. */
 export declare function validatePageTicketResponses(dir: string, responses: unknown): PageResponses;
-/** The three terminal states of a page ticket, derived from its published result. */
+/** Page state is derived from the SQL request row. */
 export declare function pageTicketState(dir: string): 'pending' | 'resolved' | 'canceled' | 'passive';
 /** Autosave partial page work. Every supplied response is validated; omitted components are permitted. */
 export declare function writePageProgress(dir: string, responses: unknown): PageResponses;
-/** Saved partial work, or null when none exists. Malformed progress is an error, never silently discarded. */
+/** Saved partial work from the request row, or null when none exists. */
 export declare function readPageProgress(dir: string): PageResponses | null;
 export interface PageTicket {
     dir: string;
@@ -97,32 +39,30 @@ export interface PageTicket {
 export declare function readPageTicket(dir: string): PageTicket;
 export interface CompletePageOptions {
     completedAt?: string;
-    /** Recorded when an authorized programmatic writer answered instead of a person. */
     actor?: string;
 }
-export declare function completePage(dir: string, responses: unknown, claimToken: string, opts?: CompletePageOptions): {
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function completePage(_dir: string, _responses: unknown, _claimToken: string, _opts?: CompletePageOptions): {
     won: boolean;
     result: TicketResult;
 };
-/** Atomically take a page ticket's claim over, complete it, and release the takeover claim. */
-export declare function takeoverAndCompletePage(dir: string, responses: unknown, owner: {
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function takeoverAndCompletePage(_dir: string, _responses: unknown, _owner: {
     host: string;
     pid: number;
-}, opts?: CompletePageOptions): {
+}, _opts?: CompletePageOptions): {
     won: boolean;
     result: TicketResult;
 };
 export interface CancelTicketOptions {
     reason?: string;
     actor?: string;
-    /** The recipient closing it writes `dismissed`; the requester withdrawing it
-     * writes `canceled`. Omitted where the caller is neither. */
     disposition?: 'canceled' | 'dismissed';
 }
-/** Cancellation races finalization but never requires or removes another claim. */
-export declare function cancelTicket(dir: string, opts?: CancelTicketOptions): {
+/** Page settlement must go through daemon/human/finish, which records its SQL result and direct obligations together. */
+export declare function cancelTicket(_dir: string, _opts?: CancelTicketOptions): {
     status: 'canceled' | 'already_resolved';
     result: TicketResult;
 };
-/** Write the validated review output once its review result is published. */
-export declare function projectReviewOutput(dir: string): 'projected' | 'not_a_review' | 'no_result';
+/** Review projection is performed by daemon/review/finish after its SQL terminal transition. */
+export declare function projectReviewOutput(_dir: string): 'projected' | 'not_a_review' | 'no_result';