@north-light/api 0.3.580 → 0.3.588

package/dist/core/graph/watches.d.ts

@@ -0,0 +1,66 @@
+/** Watches and their subscriptions, message-subscription ending, tree walks and fork copies.
+ *  `watches.in_tree` is written only here: it is 1 while any subscription of the watch
+ *  started from spawn, job-start or ask. */
+import type { ListenConfig, ObjectRow, Reader, WatchStart } from './types.js';
+import type { CanvasDb } from '../canvas/db.js';
+export interface Subscription {
+    subscription_id: string;
+    pattern: string;
+    filter: unknown;
+    config: ListenConfig | null;
+    started_by: WatchStart;
+    ends_on: string | null;
+    created_at: string;
+}
+export interface Watch {
+    watch_id: string;
+    watcher: ObjectRow;
+    object: ObjectRow;
+    in_tree: boolean;
+    read_heads_key: string | null;
+    created_at: string;
+    subscriptions: Subscription[];
+}
+export interface RecordWatchOpts {
+    patterns?: string[];
+    config?: ListenConfig;
+    filter?: unknown;
+    /** message subscriptions only: 'final' (the default) or 'result:<request message_id>' */
+    endsOn?: string;
+    readHeadsKey?: string;
+    /** The app that made this watch through `link`: `publish` then delivers the watched object's events past the watcher's read gate (see `linkDelivers` in events.ts). */
+    linkApp?: ObjectRow;
+}
+export declare function configToJson(config: ListenConfig): string;
+export declare function configFromJson(json: string): ListenConfig;
+/** Record (or extend) watcher's watch on object. Adds only the subscriptions the watch lacks:
+ *  a pattern already held without an end covers any new one, except that a tree start
+ *  still adds its own subscription when only non-tree ones hold the pattern. */
+export declare function recordWatch(db: CanvasDb, watcher: ObjectRow, object: ObjectRow, start: WatchStart, opts?: RecordWatchOpts): Promise<void>;
+/** Mark the existing watch of `object` by `watcher` as made through `link` by `app`, changing nothing else about it. */
+export declare function markLinkWatch(db: CanvasDb, watcher: ObjectRow, object: ObjectRow, app: ObjectRow): Promise<void>;
+/** Remove the whole watch, the subscriptions with one pattern, or (tree-only form) the
+ *  subscriptions one start made. A watch left with no subscription is deleted. */
+export declare function unwatch(db: CanvasDb, watcher: ObjectRow, object: ObjectRow, which?: string | {
+    startedBy: WatchStart;
+}): Promise<void>;
+/** Change the listening configuration of the watcher's subscriptions with `pattern`; null = the watcher's default. */
+export declare function setSubscriptionConfig(db: CanvasDb, watcher: ObjectRow, object: ObjectRow, pattern: string, config: ListenConfig | null): Promise<void>;
+/** End the message subscriptions on `object` (a node): 'final' and 'done' end all of them;
+ *  `{result}` ends those waiting for that request's answer. */
+export declare function endMessageSubscriptions(db: CanvasDb, object: ObjectRow, cause: 'final' | 'done' | {
+    result: string;
+}): Promise<void>;
+/** The watches `watcher` holds that the reader may see (both ends readable). */
+export declare function watchesOf(db: CanvasDb, reader: Reader, watcher: ObjectRow): Promise<Watch[]>;
+/** The watches held on `object` that the reader may see (both ends readable). */
+export declare function watchersOf(db: CanvasDb, reader: Reader, object: ObjectRow): Promise<Watch[]>;
+/** The ids of every object that watches `object`, whatever started the watch. */
+export declare function watcherIdsOf(db: CanvasDb, object: ObjectRow): Promise<string[]>;
+/** Every node above `leaf` in the tree (in-tree watches, object → watcher), each once. */
+export declare function ancestors(db: CanvasDb, leaf: ObjectRow): Promise<ObjectRow[]>;
+/** The objects whose in-tree watch covers `object` (its spawner, job starter, explicit watchers). */
+export declare function treeWatchersOf(db: CanvasDb, object: ObjectRow): Promise<ObjectRow[]>;
+/** Give `fork` a copy of every watch `source` holds, with the same subscriptions, configurations
+ *  and read base; each copied subscription records `fork`, so no copy is in the tree. */
+export declare function copyWatchesForFork(db: CanvasDb, source: ObjectRow, fork: ObjectRow): Promise<void>;

package/dist/core/graph/watches.js

@@ -0,0 +1,177 @@
+import { permits, resolveReader } from '../permissions/evaluator.js';
+import { receiverForObject } from './receivers.js';
+import { getById } from './objects.js';
+import { randomUUID } from 'node:crypto';
+import { mapAsync } from '../async-array.js';
+const TREE_STARTS = ['spawn', 'job-start', 'ask'];
+const MESSAGE_PATTERNS = ['report.final', 'report.result', 'notice.>'];
+export function configToJson(config) {
+    return JSON.stringify(Object.fromEntries(config.map((c) => [String(c.threshold), c.delivery])));
+}
+export function configFromJson(json) {
+    const raw = JSON.parse(json);
+    return Object.entries(raw).map(([t, delivery]) => ({ threshold: Number(t), delivery }))
+        .sort((a, b) => b.threshold - a.threshold);
+}
+async function watchRow(db, watcher, object) {
+    return await db.prepare('SELECT * FROM watches WHERE watcher = ? AND object = ?').get(watcher.id, object.id);
+}
+async function subsOf(db, watch) {
+    return await db.prepare('SELECT * FROM watch_subscriptions WHERE watch = ? ORDER BY seq').all(watch);
+}
+/** Recompute `in_tree`, and delete the watch when no subscription is left. */
+async function settle(db, watch) {
+    const subs = await subsOf(db, watch);
+    if (subs.length === 0) {
+        await db.prepare('DELETE FROM watches WHERE watch_id = ?').run(watch);
+        return;
+    }
+    const inTree = subs.some((s) => TREE_STARTS.includes(s.started_by)) ? 1 : 0;
+    await db.prepare('UPDATE watches SET in_tree = ? WHERE watch_id = ? AND in_tree != ?').run(inTree, watch, inTree);
+}
+function defaultPatterns(start, opts) {
+    if (start === 'message')
+        return MESSAGE_PATTERNS;
+    if (opts.patterns?.length)
+        return opts.patterns;
+    return ['>'];
+}
+/** Record (or extend) watcher's watch on object. Adds only the subscriptions the watch lacks:
+ *  a pattern already held without an end covers any new one, except that a tree start
+ *  still adds its own subscription when only non-tree ones hold the pattern. */
+export async function recordWatch(db, watcher, object, start, opts = {}) {
+    if (start === 'fork')
+        throw new Error('recordWatch: fork watches are made by copyWatchesForFork');
+    if (watcher.type.includes('.') && !await receiverForObject(db, watcher))
+        throw new Error(`custom object ${watcher.id} has no receiver`);
+    const now = new Date().toISOString();
+    await db.prepare(`INSERT INTO watches (watch_id, watcher, object, in_tree, read_heads_key, created_at, link_app) VALUES (?, ?, ?, 0, ?, ?, ?)
+    ON CONFLICT (watcher, object) DO UPDATE SET read_heads_key = COALESCE(excluded.read_heads_key, watches.read_heads_key),
+      link_app = COALESCE(excluded.link_app, watches.link_app)`)
+        .run(randomUUID(), watcher.id, object.id, opts.readHeadsKey ?? null, now, opts.linkApp?.id ?? null);
+    const watch = (await watchRow(db, watcher, object));
+    const endsOn = start === 'message' ? (opts.endsOn ?? 'final') : null;
+    const isTree = TREE_STARTS.includes(start);
+    const existing = await subsOf(db, watch.watch_id);
+    const insert = db.prepare(`INSERT INTO watch_subscriptions (subscription_id, watch, pattern, filter_json, config_json, started_by, ends_on, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    for (const pattern of defaultPatterns(start, opts)) {
+        const covered = existing.some((s) => s.pattern === pattern
+            && (s.ends_on === null || s.ends_on === endsOn)
+            && (!isTree || TREE_STARTS.includes(s.started_by)));
+        if (covered)
+            continue;
+        await insert.run(randomUUID(), watch.watch_id, pattern, opts.filter === undefined ? null : JSON.stringify(opts.filter), opts.config ? configToJson(opts.config) : null, start, endsOn, now);
+    }
+    await settle(db, watch.watch_id);
+}
+/** Mark the existing watch of `object` by `watcher` as made through `link` by `app`, changing nothing else about it. */
+export async function markLinkWatch(db, watcher, object, app) {
+    await db.prepare('UPDATE watches SET link_app = ? WHERE watcher = ? AND object = ?').run(app.id, watcher.id, object.id);
+}
+/** Remove the whole watch, the subscriptions with one pattern, or (tree-only form) the
+ *  subscriptions one start made. A watch left with no subscription is deleted. */
+export async function unwatch(db, watcher, object, which) {
+    const watch = await watchRow(db, watcher, object);
+    if (!watch)
+        return;
+    if (which === undefined)
+        await db.prepare('DELETE FROM watch_subscriptions WHERE watch = ?').run(watch.watch_id);
+    else if (typeof which === 'string')
+        await db.prepare('DELETE FROM watch_subscriptions WHERE watch = ? AND pattern = ?').run(watch.watch_id, which);
+    else
+        await db.prepare('DELETE FROM watch_subscriptions WHERE watch = ? AND started_by = ?').run(watch.watch_id, which.startedBy);
+    await settle(db, watch.watch_id);
+}
+/** Change the listening configuration of the watcher's subscriptions with `pattern`; null = the watcher's default. */
+export async function setSubscriptionConfig(db, watcher, object, pattern, config) {
+    const watch = await watchRow(db, watcher, object);
+    const changed = watch
+        ? (await db.prepare('UPDATE watch_subscriptions SET config_json = ? WHERE watch = ? AND pattern = ?')
+            .run(config ? configToJson(config) : null, watch.watch_id, pattern)).changes
+        : 0;
+    if (Number(changed) === 0)
+        throw new Error(`${watcher.id} has no subscription ${pattern} on ${object.id}`);
+}
+/** End the message subscriptions on `object` (a node): 'final' and 'done' end all of them;
+ *  `{result}` ends those waiting for that request's answer. */
+export async function endMessageSubscriptions(db, object, cause) {
+    const ended = (typeof cause === 'string'
+        ? await db.prepare(`DELETE FROM watch_subscriptions WHERE started_by = 'message'
+        AND watch IN (SELECT watch_id FROM watches WHERE object = ?) RETURNING watch`).all(object.id)
+        : await db.prepare(`DELETE FROM watch_subscriptions WHERE started_by = 'message' AND ends_on = ?
+        AND watch IN (SELECT watch_id FROM watches WHERE object = ?) RETURNING watch`).all(`result:${cause.result}`, object.id));
+    for (const watch of new Set(ended.map((r) => r.watch)))
+        await settle(db, watch);
+}
+async function hydrate(db, raw) {
+    const watcher = await getById(db, raw.watcher);
+    const object = await getById(db, raw.object);
+    if (!watcher || !object)
+        return null;
+    return {
+        watch_id: raw.watch_id, watcher, object, in_tree: raw.in_tree === 1, read_heads_key: raw.read_heads_key, created_at: raw.created_at,
+        subscriptions: (await subsOf(db, raw.watch_id)).map((s) => ({
+            subscription_id: s.subscription_id, pattern: s.pattern, started_by: s.started_by, ends_on: s.ends_on, created_at: s.created_at,
+            filter: s.filter_json === null ? null : JSON.parse(s.filter_json),
+            config: s.config_json === null ? null : configFromJson(s.config_json),
+        })),
+    };
+}
+/** The watches matching `where` whose watcher and watched object the reader may both read. */
+async function visible(db, reader, where, id) {
+    const ev = await resolveReader(db, reader);
+    const wer = await permits(db, ev, 'read', 'wr');
+    const obj = await permits(db, ev, 'read', 'ob');
+    const raws = await db.prepareUncached(`SELECT w.* FROM watches w JOIN objects wr ON wr.id = w.watcher JOIN objects ob ON ob.id = w.object
+    WHERE w.${where} = ? AND ${wer.sql} AND ${obj.sql} ORDER BY w.seq`).all(id, ...wer.params, ...obj.params);
+    return (await mapAsync(raws, async (r) => await hydrate(db, r))).filter((w) => w !== null);
+}
+/** The watches `watcher` holds that the reader may see (both ends readable). */
+export async function watchesOf(db, reader, watcher) {
+    return await visible(db, reader, 'watcher', watcher.id);
+}
+/** The watches held on `object` that the reader may see (both ends readable). */
+export async function watchersOf(db, reader, object) {
+    return await visible(db, reader, 'object', object.id);
+}
+/** The ids of every object that watches `object`, whatever started the watch. */
+export async function watcherIdsOf(db, object) {
+    return (await db.prepare('SELECT o.id FROM watches w JOIN objects o ON o.id = w.watcher WHERE w.object = ? ORDER BY w.seq').all(object.id)).map((r) => r.id);
+}
+/** Every node above `leaf` in the tree (in-tree watches, object → watcher), each once. */
+export async function ancestors(db, leaf) {
+    return await db.prepare(`WITH RECURSIVE walk(id) AS (
+      SELECT CAST(? AS text)
+      UNION
+      SELECT w.watcher FROM walk JOIN watches w ON w.object = walk.id AND w.in_tree = 1
+    ) SELECT o.* FROM walk JOIN objects o ON o.id = walk.id
+      WHERE o.type = 'node' AND o.id != ?`).all(leaf.id, leaf.id);
+}
+/** The objects whose in-tree watch covers `object` (its spawner, job starter, explicit watchers). */
+export async function treeWatchersOf(db, object) {
+    return await db.prepare(`SELECT o.* FROM watches w JOIN objects o ON o.id = w.watcher
+    WHERE w.object = ? AND w.in_tree = 1 ORDER BY w.seq`).all(object.id);
+}
+/** Give `fork` a copy of every watch `source` holds, with the same subscriptions, configurations
+ *  and read base; each copied subscription records `fork`, so no copy is in the tree. */
+export async function copyWatchesForFork(db, source, fork) {
+    const now = new Date().toISOString();
+    const watches = await db.prepare('SELECT * FROM watches WHERE watcher = ?').all(source.id);
+    const insertSub = db.prepare(`INSERT INTO watch_subscriptions (subscription_id, watch, pattern, filter_json, config_json, started_by, ends_on, created_at)
+    VALUES (?, ?, ?, ?, ?, 'fork', ?, ?)`);
+    for (const w of watches) {
+        if (w.object === fork.id)
+            continue;
+        await db.prepare(`INSERT INTO watches (watch_id, watcher, object, in_tree, read_heads_key, created_at) VALUES (?, ?, ?, 0, ?, ?)
+      ON CONFLICT (watcher, object) DO NOTHING`).run(randomUUID(), fork.id, w.object, w.read_heads_key, now);
+        const copy = (await watchRow(db, fork, { id: w.object }));
+        const have = await subsOf(db, copy.watch_id);
+        for (const s of await subsOf(db, w.watch_id)) {
+            if (have.some((h) => h.pattern === s.pattern && h.ends_on === s.ends_on))
+                continue;
+            await insertSub.run(randomUUID(), copy.watch_id, s.pattern, s.filter_json, s.config_json, s.ends_on, now);
+        }
+        await settle(db, copy.watch_id);
+    }
+}

package/dist/core/human/action-binding.d.ts

@@ -0,0 +1,23 @@
+export declare const HUMAN_ACTION_NAME_PATTERN: RegExp;
+export interface TicketActionBinding {
+    schema: 'crtr.human-action-binding/v1';
+    /** Declared action name, matching HUMAN_ACTION_NAME_PATTERN. */
+    name: string;
+    /** Frozen creation payload; opaque JSON, never inspected. */
+    payload: unknown;
+    /** The creator's absolute cwd, captured verbatim. */
+    creatorCwd: string;
+    /** Absolute path of the config file that won resolution. */
+    configOrigin: string;
+    /** Fully resolved argv; argv[0] is an absolute executable path. */
+    argv: string[];
+    /** Fully resolved absolute working directory. */
+    cwd: string;
+    /** Originating app, retained when its node is later deleted. */
+    app?: string;
+}
+/** Publish the binding before the page exists, so a visible request is never
+ * unbound. A second write is a caller bug, not a race to tolerate. */
+export declare function publishTicketActionBinding(dir: string, binding: TicketActionBinding): void;
+/** The frozen binding, or null for a request with no completion action. */
+export declare function readTicketActionBinding(dir: string): TicketActionBinding | null;

package/dist/core/human/action-binding.js

@@ -0,0 +1,41 @@
+// The optional completion-action binding of a durable human request. Written
+// once at creation and never again: `replace` revises the page, so the approved
+// effect must not be reachable from any later write.
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { actionBindingPath, publishJsonExclusive } from './convention.js';
+export const HUMAN_ACTION_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const bindingSchema = z.object({
+    schema: z.literal('crtr.human-action-binding/v1'),
+    name: z.string().regex(HUMAN_ACTION_NAME_PATTERN),
+    payload: z.unknown(),
+    creatorCwd: z.string().min(1),
+    configOrigin: z.string().min(1),
+    argv: z.array(z.string().min(1)).min(1),
+    cwd: z.string().min(1),
+    app: z.string().min(1).optional(),
+}).strict();
+/** Publish the binding before the page exists, so a visible request is never
+ * unbound. A second write is a caller bug, not a race to tolerate. */
+export function publishTicketActionBinding(dir, binding) {
+    if (!publishJsonExclusive(actionBindingPath(dir), binding)) {
+        throw new Error(`action binding already exists: ${actionBindingPath(dir)}`);
+    }
+}
+/** The frozen binding, or null for a request with no completion action. */
+export function readTicketActionBinding(dir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(actionBindingPath(dir), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const parsed = bindingSchema.parse(raw);
+    // `payload` is optional-by-absence in JSON but required in the type; z.unknown()
+    // accepts a missing key, so restore it explicitly as the JSON null the
+    // completion document must carry.
+    return { ...parsed, payload: raw.payload ?? null };
+}

package/dist/core/human/answer-text.d.ts

@@ -0,0 +1,5 @@
+import type { PageAnswer } from './answer.js';
+/** Render a PageAnswer as the deterministic Markdown report delivered to its asking agent.
+ *  The person sees this same prose in their own chat surface, so it carries the answer
+ *  itself and nothing addressed only to the agent. */
+export declare function renderAnswerText(answer: PageAnswer): string;

package/dist/core/human/answer-text.js

@@ -0,0 +1,100 @@
+function inline(value) {
+    return `“${value}”`;
+}
+function verbatim(prefix, value) {
+    if (value === '')
+        return [`${prefix}(left empty)`];
+    if (!value.includes('\n'))
+        return [`${prefix}${inline(value)}`];
+    return [...(prefix === '' ? [] : [prefix.trimEnd()]), ...value.split('\n').map((line) => `> ${line}`)];
+}
+function code(value) {
+    const fence = '`'.repeat(Math.max(0, ...(value.match(/`+/g)?.map((run) => run.length) ?? [0])) + 1);
+    return `${fence}${value}${fence}`;
+}
+function item(item) {
+    return `${item.label} (${code(item.id)})`;
+}
+function groupName(group) {
+    if (group.group === 'option')
+        return 'Chose';
+    if (group.group === 'card')
+        return 'Cards';
+    return group.group === 'row' ? 'Rows' : 'Columns';
+}
+function groupLines(group) {
+    return [`${groupName(group)}: ${group.picked.length === 0 ? 'none' : group.picked.map(item).join(', ')}`];
+}
+function commentLines(comment) {
+    const prefix = comment.anchor.kind === 'whole' ? 'Comment: ' : `Comment on ${inline(comment.anchorLabel)}: `;
+    return verbatim(prefix, comment.text);
+}
+function shape(slot) {
+    if (slot.kind === 'options')
+        return `options, ${slot.groups[0]?.mode === 'single' ? 'pick one' : 'pick any'}`;
+    if (slot.kind === 'text') {
+        if (slot.text?.singleLine === true)
+            return `one-line text, ${slot.text.edited ? 'edited' : 'unchanged'}`;
+        return `text, ${slot.text?.edited === true ? 'edited' : 'accepted as written'}`;
+    }
+    if (slot.kind === 'table') {
+        const group = slot.groups.find((candidate) => candidate.group === 'row') ?? slot.groups.find((candidate) => candidate.group === 'column');
+        return `table, ${group === undefined ? 'no selection' : group.total > 0 ? `${group.picked.length} of ${group.total} ${group.group}s` : `${group.picked.length} ${group.group}${group.picked.length === 1 ? '' : 's'}`}`;
+    }
+    if (slot.kind === 'cards') {
+        const cards = slot.groups[0];
+        return `cards, ${cards?.total && cards.total > 0 ? `${cards.picked.length} of ${cards.total} cards` : `${cards?.picked.length ?? 0} cards`}`;
+    }
+    return slot.kind;
+}
+function slotHeading(slot, totalSlots) {
+    if (slot.label !== undefined && slot.label !== '')
+        return `**${slot.label}** — ${shape(slot)}`;
+    if (totalSlots === 1)
+        return undefined;
+    return `${code(slot.id)} — ${shape(slot)}`;
+}
+function slotLines(slot, totalSlots) {
+    const lines = [];
+    const heading = slotHeading(slot, totalSlots);
+    if (heading !== undefined)
+        lines.push(heading);
+    if (slot.raw !== undefined) {
+        lines.push(`Custom component (${code(slot.kind)}) response: ${JSON.stringify(slot.raw)}`);
+    }
+    else if (slot.text !== undefined) {
+        // A one-line field always shows its value inline — quoted, or "(left empty)" — because the
+        // whole answer is that one string; the heading already carries whether it was edited.
+        if (slot.text.singleLine === true || slot.text.edited)
+            lines.push(...verbatim('', slot.text.value));
+        else
+            lines.push('Accepted as written, unchanged');
+    }
+    else {
+        for (const group of slot.groups)
+            lines.push(...groupLines(group));
+        if (slot.freetext !== undefined)
+            lines.push(...verbatim('Other: ', slot.freetext));
+    }
+    for (const comment of slot.comments)
+        lines.push(...commentLines(comment));
+    return lines;
+}
+/** Render a PageAnswer as the deterministic Markdown report delivered to its asking agent.
+ *  The person sees this same prose in their own chat surface, so it carries the answer
+ *  itself and nothing addressed only to the agent. */
+export function renderAnswerText(answer) {
+    if (answer.kind === 'acknowledgement') {
+        return [
+            `The user saw **${answer.title}** and dismissed it. The page asked for nothing, so the acknowledgement is the whole answer.`,
+            '',
+            `Acknowledged ${answer.completedAt}.`,
+        ].join('\n');
+    }
+    const answered = answer.slots.filter((slot) => slot.state === 'answered');
+    const lines = [`The user answered **${answer.title}**.`];
+    for (const slot of answered)
+        lines.push('', ...slotLines(slot, answer.slots.length));
+    lines.push('', `Answered ${answer.completedAt}.`);
+    return lines.join('\n');
+}

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

@@ -0,0 +1,53 @@
+import { type PageCommentAnchor, type PageResponses, type PageSlot } from './page-schema.js';
+export type PageAnswer = {
+    title: string;
+    subtitle?: string;
+    completedAt: string;
+    kind: 'answer' | 'acknowledgement';
+    digest: string;
+    slots: PageAnswerSlot[];
+};
+export type PageAnswerSlot = {
+    id: string;
+    kind: string;
+    label?: string;
+    state: 'answered' | 'unanswered';
+    blank: boolean;
+    groups: PageAnswerGroup[];
+    freetext?: string;
+    /** `singleLine` marks a one-line input, whose value is worth echoing even when unchanged. */
+    text?: {
+        value: string;
+        edited: boolean;
+        singleLine?: boolean;
+    };
+    comments: PageAnswerComment[];
+    raw?: Record<string, unknown>;
+};
+export type PageAnswerGroup = {
+    group: 'option' | 'card' | 'row' | 'column';
+    mode: 'single' | 'multi';
+    total: number;
+    picked: {
+        id: string;
+        label: string;
+    }[];
+};
+/** Stored responses predating the `whole` anchor's removal still carry it; answers keep rendering them. */
+export type LegacyCommentAnchor = PageCommentAnchor | {
+    kind: 'whole';
+};
+export type PageAnswerComment = {
+    anchor: LegacyCommentAnchor;
+    anchorLabel: string;
+    text: string;
+};
+export interface DescribePageAnswerOptions {
+    completedAt: string;
+}
+export declare function answerCommentAnchorLabel(slot: PageSlot, anchor: LegacyCommentAnchor): string;
+/** Derive the one shared answer model from the immutable page manifest and a response map. */
+/** `manifest` is unknown deliberately: this boundary validates persisted JSON before deriving. */
+export declare function describePageAnswer(manifest: unknown, responses: PageResponses, opts: DescribePageAnswerOptions): PageAnswer;
+/** The stable one-line digest stored in the terminal request result and shown in history. */
+export declare function buildAnswerDigest(slots: PageAnswerSlot[]): string;

package/dist/core/human/answer.js

@@ -0,0 +1,119 @@
+import { isResponseBearingSlot, validatePageManifest, } from './page-schema.js';
+function hasOwn(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+function responseRecord(response) {
+    return response !== null && typeof response === 'object' ? response : {};
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function comments(value) {
+    return Array.isArray(value) ? value.filter((item) => item !== null && typeof item === 'object' && 'anchor' in item && 'text' in item) : [];
+}
+function picked(ids, items) {
+    const labels = new Map(items.map((item) => [item.id, item.label]));
+    return ids.map((id) => ({ id, label: labels.get(id) ?? id }));
+}
+function rowLabel(config, id) {
+    const row = config.rows?.find((candidate) => candidate.id === id);
+    const firstColumn = config.columns[0];
+    if (row === undefined || firstColumn === undefined || !hasOwn(row.cells, firstColumn.id))
+        return id;
+    return String(row.cells[firstColumn.id]);
+}
+function slotLabel(slot) {
+    const label = slot.config.label;
+    return typeof label === 'string' && label !== '' ? label : slot.id ?? slot.kind;
+}
+export function answerCommentAnchorLabel(slot, anchor) {
+    if (anchor.kind === 'whole')
+        return slotLabel(slot); // legacy stored data only; new anchors are option/row
+    if (anchor.kind === 'option')
+        return slot.config.options.find((option) => option.id === anchor.optionId)?.label ?? anchor.optionId;
+    return rowLabel(slot.config, anchor.rowId);
+}
+function describeComments(slot, response) {
+    return comments(response.comments).map((comment) => ({ anchor: comment.anchor, anchorLabel: answerCommentAnchorLabel(slot, comment.anchor), text: comment.text }));
+}
+function describeSlot(slot, response) {
+    const state = response === undefined ? 'unanswered' : 'answered';
+    const value = responseRecord(response);
+    const configLabel = slot.config.label;
+    const base = {
+        id: slot.id,
+        kind: slot.kind,
+        ...(typeof configLabel === 'string' && configLabel !== '' ? { label: configLabel } : {}),
+        state,
+    };
+    if (slot.unvalidated === true) {
+        return { ...base, blank: response === undefined, groups: [], comments: [], ...(response === undefined ? {} : { raw: value }) };
+    }
+    if (slot.kind === 'options') {
+        const config = slot.config;
+        const freetext = typeof value.freetext === 'string' && value.freetext !== '' ? value.freetext : undefined;
+        const group = { group: 'option', mode: config.mode, total: config.options.length, picked: picked(strings(value.selectedOptionIds), config.options) };
+        return { ...base, blank: group.picked.length === 0 && freetext === undefined, groups: [group], ...(freetext === undefined ? {} : { freetext }), comments: describeComments(slot, value) };
+    }
+    if (slot.kind === 'text') {
+        const text = value;
+        const written = typeof text.text === 'string' ? text.text : '';
+        const singleLine = slot.config.singleLine === true;
+        return { ...base, blank: singleLine && written === '', groups: [], text: { value: written, edited: text.edited === true, ...(singleLine ? { singleLine: true } : {}) }, comments: [] };
+    }
+    if (slot.kind === 'table') {
+        const config = slot.config;
+        const groups = [];
+        if (config.rowSelect === 'single' || config.rowSelect === 'multi')
+            groups.push({ group: 'row', mode: config.rowSelect, total: config.rows?.length ?? 0, picked: strings(value.selectedRowIds).map((id) => ({ id, label: rowLabel(config, id) })) });
+        if (config.columnSelect === 'single' || config.columnSelect === 'multi')
+            groups.push({ group: 'column', mode: config.columnSelect, total: config.columns.length, picked: picked(strings(value.selectedColumnIds), config.columns) });
+        return { ...base, blank: groups.every((group) => group.picked.length === 0), groups, comments: describeComments(slot, value) };
+    }
+    if (slot.kind === 'cards') {
+        const config = slot.config;
+        const cards = (config.cards ?? []).map((card) => ({ id: card.id, label: card.title }));
+        const group = { group: 'card', mode: config.mode, total: cards.length, picked: picked(strings(value.selectedCardIds), cards) };
+        return { ...base, blank: group.picked.length === 0, groups: [group], comments: [] };
+    }
+    throw new Error(`slot "${slot.id}" kind "${slot.kind}" does not accept a response`);
+}
+/** Derive the one shared answer model from the immutable page manifest and a response map. */
+/** `manifest` is unknown deliberately: this boundary validates persisted JSON before deriving. */
+export function describePageAnswer(manifest, responses, opts) {
+    const page = validatePageManifest(manifest);
+    const slots = page.slots.filter(isResponseBearingSlot).map((slot) => describeSlot(slot, hasOwn(responses, slot.id) ? responses[slot.id] : undefined));
+    const answered = slots.filter((slot) => slot.state === 'answered');
+    return {
+        title: page.title,
+        ...(page.subtitle === undefined ? {} : { subtitle: page.subtitle }),
+        completedAt: opts.completedAt,
+        kind: slots.length === 0 ? 'acknowledgement' : 'answer',
+        digest: buildAnswerDigest(answered),
+        slots,
+    };
+}
+function groupDigest(group) {
+    if (group.picked.length === 0)
+        return 'no selection';
+    if (group.group === 'option' || group.group === 'card')
+        return group.picked.map((item) => item.label).join(', ');
+    return group.total > 0 ? `${group.picked.length} of ${group.total} ${group.group}s` : `${group.picked.length} ${group.group}${group.picked.length === 1 ? '' : 's'}`;
+}
+/** The stable one-line digest stored in the terminal request result and shown in history. */
+export function buildAnswerDigest(slots) {
+    return slots.map((slot) => {
+        if (slot.raw !== undefined)
+            return `${slot.kind} response`;
+        // A one-line answer IS its value; "edited" would say nothing about what was typed.
+        if (slot.text !== undefined) {
+            if (slot.text.singleLine === true)
+                return slot.text.value === '' ? 'empty' : slot.text.value;
+            return slot.text.edited ? 'edited' : 'unchanged';
+        }
+        const groups = slot.groups.map(groupDigest);
+        if (slot.freetext !== undefined)
+            groups.push(slot.freetext);
+        return groups.join(', ') || 'no selection';
+    }).join(' · ');
+}

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

@@ -0,0 +1,23 @@
+export interface TicketClaim {
+    token: string;
+    host: string;
+    pid: number;
+    claimedAt: string;
+    heartbeatAt: string;
+    tmuxClient?: string;
+}
+export interface ClaimOptions {
+    host?: string;
+    pid?: number;
+    tmuxClient?: string;
+    now?: Date;
+}
+export declare function readTicketClaim(dir: string): TicketClaim | null;
+export declare function isStaleClaim(claim: TicketClaim, now?: number, localHost?: string): boolean;
+/** Exclude another live presenter; the daemon owns whether the request can settle. */
+export declare function claimTicket(dir: string, opts?: ClaimOptions): TicketClaim | null;
+export declare function heartbeatClaim(dir: string, token: string, now?: Date): boolean;
+export declare function releaseClaimLocked(dir: string, token: string): boolean;
+export declare function releaseClaim(dir: string, token: string): boolean;
+export declare function claimExists(dir: string): boolean;
+export declare function withTicketLock<T>(dir: string, operation: () => T): T;