@north-light/api 0.3.580 → 0.3.588

package/dist/core/graph/exposures.js

@@ -0,0 +1,152 @@
+const RANK = { name: 1, preview: 2, content: 3 };
+const CHANNELS = ['system', 'transcript'];
+/** What `loadLedger` read, so `saveLedger` writes only the difference. */
+const loaded = new WeakMap();
+function cloneLedger(l) {
+    return {
+        node: l.node, preferenceSnapshot: l.preferenceSnapshot,
+        objects: new Map([...l.objects].map(([k, v]) => [k, { ...v }])),
+        listed: new Map([...l.listed].map(([k, v]) => [k, { ...v }])),
+    };
+}
+function emptyLedger(node) {
+    return { node, preferenceSnapshot: null, objects: new Map(), listed: new Map() };
+}
+export async function loadLedger(db, node) {
+    const ledger = emptyLedger(node);
+    const session = await db.prepare('SELECT preference_snapshot, listed_json FROM context_sessions WHERE node = ?').get(node);
+    if (session !== undefined) {
+        ledger.preferenceSnapshot = session.preference_snapshot;
+        for (const [key, listed] of Object.entries(JSON.parse(session.listed_json)))
+            ledger.listed.set(key, listed);
+    }
+    const rows = await db.prepare('SELECT object, channel, level, heads_key, content_hash FROM exposures WHERE node = ?').all(node);
+    for (const row of rows) {
+        const held = ledger.objects.get(row.object) ?? { headsKey: row.heads_key, contentHash: row.content_hash };
+        held[row.channel] = row.level;
+        ledger.objects.set(row.object, held);
+    }
+    loaded.set(ledger, cloneLedger(ledger));
+    return ledger;
+}
+/** Write what changed since `loadLedger` (a ledger never loaded is written whole). */
+export async function saveLedger(db, ledger) {
+    const before = loaded.get(ledger) ?? emptyLedger(ledger.node);
+    const listedJson = JSON.stringify(Object.fromEntries(ledger.listed));
+    if (ledger.preferenceSnapshot !== before.preferenceSnapshot || listedJson !== JSON.stringify(Object.fromEntries(before.listed))) {
+        await db.prepare(`INSERT INTO context_sessions (node, preference_snapshot, listed_json) VALUES (?, ?, ?)
+      ON CONFLICT(node) DO UPDATE SET preference_snapshot = excluded.preference_snapshot, listed_json = excluded.listed_json`)
+            .run(ledger.node, ledger.preferenceSnapshot, listedJson);
+    }
+    const upsert = db.prepare(`INSERT INTO exposures (node, object, channel, level, heads_key, content_hash) VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(node, object, channel) DO UPDATE SET level = excluded.level, heads_key = excluded.heads_key, content_hash = excluded.content_hash`);
+    const remove = db.prepare('DELETE FROM exposures WHERE node = ? AND object = ? AND channel = ?');
+    const objects = new Set([...before.objects.keys(), ...ledger.objects.keys()]);
+    for (const object of objects) {
+        const now = ledger.objects.get(object);
+        const was = before.objects.get(object);
+        for (const channel of CHANNELS) {
+            const level = now?.[channel];
+            if (level === undefined) {
+                if (was?.[channel] !== undefined)
+                    await remove.run(ledger.node, object, channel);
+            }
+            else if (level !== was?.[channel] || now.headsKey !== was?.headsKey || now.contentHash !== was?.contentHash) {
+                await upsert.run(ledger.node, object, channel, level, now.headsKey, now.contentHash);
+            }
+        }
+    }
+    loaded.set(ledger, cloneLedger(ledger));
+}
+/** Whether the node has a ledger at all (a context session or any exposure). */
+export async function hasLedger(db, node) {
+    return await db.prepare('SELECT 1 FROM context_sessions WHERE node = ? UNION ALL SELECT 1 FROM exposures WHERE node = ? LIMIT 1').get(node, node) !== undefined;
+}
+/** End the node's context session: nothing is held any more. */
+export async function clearLedger(db, node) {
+    await db.prepare('DELETE FROM exposures WHERE node = ?').run(node);
+    await db.prepare('DELETE FROM context_sessions WHERE node = ?').run(node);
+}
+/** Seed a fork with what the source's transcript holds; the fork builds its own
+ *  system prompt, so system rows and the preference snapshot are not copied. */
+export async function forkLedger(db, source, fork) {
+    await clearLedger(db, fork);
+    await db.prepare(`INSERT INTO exposures (node, object, channel, level, heads_key, content_hash)
+    SELECT ?, object, channel, level, heads_key, content_hash FROM exposures WHERE node = ? AND channel = 'transcript'`).run(fork, source);
+    const session = await db.prepare('SELECT listed_json FROM context_sessions WHERE node = ?').get(source);
+    if (session === undefined)
+        return;
+    const listed = {};
+    for (const [key, entry] of Object.entries(JSON.parse(session.listed_json))) {
+        if (entry.transcript !== undefined)
+            listed[key] = { transcript: entry.transcript };
+    }
+    await db.prepare('INSERT INTO context_sessions (node, preference_snapshot, listed_json) VALUES (?, NULL, ?)').run(fork, JSON.stringify(listed));
+}
+function rankIn(entry, channel) {
+    if (entry === undefined)
+        return 0;
+    const of = (c) => (entry[c] !== undefined ? RANK[entry[c]] : 0);
+    return channel !== undefined ? of(channel) : Math.max(of('system'), of('transcript'));
+}
+/** Held at `level` or above: this object, or any held object with the same body
+ *  (content hash). The object itself counts at content level only for the same revision. */
+export function heldAtOrAbove(ledger, exposed, level, channel) {
+    const want = RANK[level];
+    const own = ledger.objects.get(exposed.object);
+    if (own !== undefined && rankIn(own, channel) >= want && (level !== 'content' || own.headsKey === exposed.headsKey))
+        return true;
+    if (exposed.contentHash === null)
+        return false;
+    for (const held of ledger.objects.values()) {
+        if (held.contentHash === exposed.contentHash && rankIn(held, channel) >= want)
+            return true;
+    }
+    return false;
+}
+/** Record that `channel` now holds the object at `level`; never lowers a level of the same revision. */
+export function hold(ledger, channel, exposed, level) {
+    const current = ledger.objects.get(exposed.object);
+    const sameRevision = current !== undefined && current.headsKey === exposed.headsKey && current.contentHash === exposed.contentHash;
+    // One revision per object: holding a new revision drops what the other channel held of the old one.
+    const next = sameRevision ? { ...current } : { headsKey: exposed.headsKey, contentHash: exposed.contentHash };
+    const prior = sameRevision ? current[channel] : undefined;
+    next[channel] = prior !== undefined && RANK[prior] >= RANK[level] ? prior : level;
+    ledger.objects.set(exposed.object, next);
+}
+export function listedAtOrAbove(ledger, key, level, channel) {
+    return rankIn(ledger.listed.get(key), channel) >= RANK[level];
+}
+export function holdListing(ledger, channel, key, level) {
+    const current = ledger.listed.get(key) ?? {};
+    const prior = current[channel];
+    if (prior !== undefined && RANK[prior] >= RANK[level])
+        return;
+    ledger.listed.set(key, { ...current, [channel]: level });
+}
+/** Forget the transcript's copy of the object and of every held object with the
+ *  same body (compaction dropped it); system holdings stay. */
+export function demoteTranscript(ledger, object) {
+    const target = ledger.objects.get(object);
+    if (target === undefined)
+        return;
+    for (const [key, held] of ledger.objects) {
+        if (key !== object && (target.contentHash === null || held.contentHash !== target.contentHash))
+            continue;
+        const { transcript: _dropped, ...rest } = held;
+        if (rest.system === undefined)
+            ledger.objects.delete(key);
+        else
+            ledger.objects.set(key, rest);
+    }
+}
+/** The byte-stable preference block: the first render is kept for the session. */
+export function freezePreferences(ledger, rendered) {
+    if (ledger.preferenceSnapshot === null)
+        ledger.preferenceSnapshot = rendered;
+    return ledger.preferenceSnapshot;
+}
+export function hasTranscript(ledger) {
+    return [...ledger.objects.values()].some((h) => h.transcript !== undefined)
+        || [...ledger.listed.values()].some((l) => l.transcript !== undefined);
+}

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

@@ -0,0 +1,107 @@
+import type { ObjectRow } from './types.js';
+import type { CanvasDb } from '../canvas/db.js';
+export type JobStatus = 'running' | 'exited' | 'killed';
+export interface JobRow {
+    object: string;
+    command: string;
+    status: JobStatus;
+    exit_code: number | null;
+    /** Blob key of the job's output (`jobs/<node>/<job>/output/<seq>`). */
+    output_key: string;
+    /** ISO time the node must claim the job by, or null for a job that runs to completion. */
+    deadline_at: string | null;
+    purpose: string | null;
+    quiet_ok: boolean;
+    pgid: number | null;
+    pgid_identity: string | null;
+    activity_last_ms: number | null;
+    activity_sampled_ms: number | null;
+    activity_files: string | null;
+    silence_activity_ms: number | null;
+    silence_threshold_ms: number | null;
+    exit_reported_at: string | null;
+}
+/** A live job as the node, the roster and the stop guard see it. */
+export interface RunningJob {
+    jobId: string;
+    command: string;
+    purpose: string | null;
+    startedAtMs: number;
+    outputKey: string;
+    deadlineAtMs: number | null;
+    pgid: number | null;
+    pgidIdentity: string | null;
+    quietOk: boolean;
+    activity: {
+        lastActivityMs: number;
+        sampledAtMs: number;
+        files: string[];
+    } | null;
+    silence: {
+        lastActivityMs: number;
+        thresholdMs: number;
+    } | null;
+}
+/** The blob prefix a job's output chunks are written under, one object per chunk (`<prefix>/<seq, 8 digits>`). */
+export declare function jobOutputKey(nodeId: string, jobId: string): string;
+/** What the broker's valve reports about a job it runs: any subset, applied together. */
+export interface JobReport {
+    pgid?: number;
+    pgidIdentity?: string;
+    exitCode?: number;
+    vanished?: boolean;
+    activity?: {
+        lastActivityMs: number;
+        sampledAtMs: number;
+        files: string[];
+    };
+}
+export declare function jobRow(db: CanvasDb, job: ObjectRow): Promise<JobRow | null>;
+/** Create the job object (`id` keeps the job id the runner already uses), its `running` row,
+ *  the node's acted-on edge and `job-start` watch, and publish `created`. */
+export declare function startJob(db: CanvasDb, node: ObjectRow, spec: {
+    id?: string;
+    command: string;
+    purpose?: string | null;
+    deadlineAtMs?: number | null;
+}): Promise<ObjectRow>;
+/** End a running job: `exited` with its exit code, or `killed` with the killer as actor (null
+ *  when the runtime killed it, e.g. at its deadline; `reason` then names why). The event carries
+ *  the exit code and output key, never output. A job already ended is left as is. */
+export declare function finishJob(db: CanvasDb, job: ObjectRow, end: {
+    exitCode: number;
+} | {
+    killedBy: ObjectRow | null;
+    reason?: string;
+}): Promise<ObjectRow>;
+/** Arm (epoch ms) or drop (null) a running job's cancel deadline. */
+export declare function setJobDeadline(db: CanvasDb, jobId: string, deadlineAtMs: number | null): Promise<void>;
+/** Declare a running job an expected wait: it gets no silence messages. */
+export declare function markJobQuietOk(db: CanvasDb, jobId: string): Promise<void>;
+/** Record the silence message last sent for a job. */
+export declare function recordJobSilence(db: CanvasDb, jobId: string, lastActivityMs: number, thresholdMs: number): Promise<void>;
+/** Apply a broker report to a running job's row: the process identity, the activity sample, and the exit
+ *  (`exit_reported_at` set; the reconciler's next pass ends the job through `finishJob`). */
+export declare function applyJobReport(db: CanvasDb, jobId: string, report: JobReport): Promise<void>;
+/** Every `running` job a node owns, oldest first. */
+export declare function runningJobs(db: CanvasDb, nodeId: string): Promise<RunningJob[]>;
+/** Every `running` job in the canvas, with its owner. */
+export declare function allRunningJobs(db: CanvasDb): Promise<Array<RunningJob & {
+    owner: string;
+}>>;
+/** Every `running` job in the canvas whose cancel deadline has passed, with its owner. */
+export declare function expiredJobs(db: CanvasDb, nowMs: number): Promise<Array<RunningJob & {
+    owner: string;
+}>>;
+/** Credit every armed deadline of a node's running jobs for an interval the node was not permitted to run. */
+export declare function shiftJobDeadlines(db: CanvasDb, nodeId: string, byMs: number): Promise<number>;
+/** End every running job whose exit the broker reported: `exited` with its code, or `killed` when the process
+ *  vanished without one. Returns how many ended. */
+export declare function endReportedJobs(db: CanvasDb): Promise<number>;
+/** True when the node's newest execution runs on a runner other than the process runner (a sandbox): its jobs run
+ *  there, so their pids, supervisor files and output are not on this host and only the broker's reports describe them. */
+export declare function ownerRunsRemotely(db: CanvasDb, nodeId: string): Promise<boolean>;
+/** End, as killed, every running job whose owner's newest execution is a sandbox execution that has exited: the
+ *  sandbox the job ran in is gone with its broker, so nothing is left to report an exit. Run after `endReportedJobs`,
+ *  so an exit the broker did report wins. Returns how many ended. */
+export declare function endJobsOfExitedSandboxes(db: CanvasDb): Promise<number>;

package/dist/core/graph/jobs.js

@@ -0,0 +1,184 @@
+/** Jobs: a backgrounded bash command as an object the node that started it owns, with its
+ *  `jobs` row and the events of its start and end. Runs in the caller's transaction. */
+import { recordActedOn } from './edges.js';
+import { publish } from './events.js';
+import { createObject, getById } from './objects.js';
+import { recordWatch } from './watches.js';
+/** The blob prefix a job's output chunks are written under, one object per chunk (`<prefix>/<seq, 8 digits>`). */
+export function jobOutputKey(nodeId, jobId) {
+    return `jobs/${nodeId}/${jobId}/output`;
+}
+function firstLine(command) {
+    return command.split('\n', 1)[0].trim();
+}
+function previewOf(command, status) {
+    return `${firstLine(command)} (${status})`;
+}
+export async function jobRow(db, job) {
+    return await db.prepare('SELECT * FROM jobs WHERE object = ?').get(job.id) ?? null;
+}
+/** Create the job object (`id` keeps the job id the runner already uses), its `running` row,
+ *  the node's acted-on edge and `job-start` watch, and publish `created`. */
+export async function startJob(db, node, spec) {
+    if (node.type !== 'node')
+        throw new Error(`startJob: ${node.id} is a ${node.type}, not a node`);
+    const job = await createObject(db, {
+        ...(spec.id === undefined ? {} : { id: spec.id }),
+        type: 'job', kind: 'bash', owner: node.id, privacy: 'public',
+        name: firstLine(spec.command) || 'bash', preview: previewOf(spec.command, 'running'),
+    });
+    await db.prepare(`INSERT INTO jobs (object, command, status, exit_code, output_key, deadline_at, purpose)
+    VALUES (?, ?, 'running', NULL, ?, ?, ?)`)
+        .run(job.id, spec.command, jobOutputKey(node.id, job.id), spec.deadlineAtMs == null ? null : new Date(spec.deadlineAtMs).toISOString(), spec.purpose ?? null);
+    await recordActedOn(db, node, job);
+    await recordWatch(db, node, job, 'job-start');
+    await publish(db, { event: 'created', object: job, actor: node, attrs: {} });
+    return job;
+}
+/** End a running job: `exited` with its exit code, or `killed` with the killer as actor (null
+ *  when the runtime killed it, e.g. at its deadline; `reason` then names why). The event carries
+ *  the exit code and output key, never output. A job already ended is left as is. */
+export async function finishJob(db, job, end) {
+    const row = await jobRow(db, job);
+    if (row === null)
+        throw new Error(`finishJob: ${job.id} has no jobs row`);
+    if (row.status !== 'running')
+        return job;
+    const killed = 'killedBy' in end;
+    const status = killed ? 'killed' : 'exited';
+    const exitCode = killed ? null : end.exitCode;
+    await db.prepare('UPDATE jobs SET status = ?, exit_code = ? WHERE object = ?').run(status, exitCode, job.id);
+    const label = killed ? 'killed' : `exited ${exitCode}`;
+    await db.prepare('UPDATE objects SET preview = ? WHERE id = ?').run(previewOf(row.command, label), job.id);
+    const updated = (await getById(db, job.id));
+    if (killed && end.killedBy !== null)
+        await recordActedOn(db, end.killedBy, updated);
+    await publish(db, {
+        event: status, object: updated, actor: killed ? end.killedBy : null,
+        attrs: killed
+            ? { 'output-key': row.output_key, ...(end.reason === undefined ? {} : { reason: end.reason }) }
+            : { 'exit-code': exitCode, 'output-key': row.output_key },
+    });
+    return updated;
+}
+/** Arm (epoch ms) or drop (null) a running job's cancel deadline. */
+export async function setJobDeadline(db, jobId, deadlineAtMs) {
+    await db.prepare(`UPDATE jobs SET deadline_at = ? WHERE object = ? AND status = 'running'`)
+        .run(deadlineAtMs === null ? null : new Date(deadlineAtMs).toISOString(), jobId);
+}
+/** Declare a running job an expected wait: it gets no silence messages. */
+export async function markJobQuietOk(db, jobId) {
+    await db.prepare(`UPDATE jobs SET quiet_ok = true WHERE object = ?`).run(jobId);
+}
+/** Record the silence message last sent for a job. */
+export async function recordJobSilence(db, jobId, lastActivityMs, thresholdMs) {
+    await db.prepare(`UPDATE jobs SET silence_activity_ms = ?, silence_threshold_ms = ? WHERE object = ?`)
+        .run(Math.trunc(lastActivityMs), Math.trunc(thresholdMs), jobId);
+}
+/** Apply a broker report to a running job's row: the process identity, the activity sample, and the exit
+ *  (`exit_reported_at` set; the reconciler's next pass ends the job through `finishJob`). */
+export async function applyJobReport(db, jobId, report) {
+    const sets = [];
+    const args = [];
+    if (report.pgid !== undefined) {
+        sets.push('pgid = ?');
+        args.push(report.pgid);
+    }
+    if (report.pgidIdentity !== undefined) {
+        sets.push('pgid_identity = ?');
+        args.push(report.pgidIdentity);
+    }
+    if (report.activity !== undefined) {
+        sets.push('activity_last_ms = ?', 'activity_sampled_ms = ?', 'activity_files = ?');
+        args.push(Math.trunc(report.activity.lastActivityMs), Math.trunc(report.activity.sampledAtMs), report.activity.files.join('\n'));
+    }
+    if (report.exitCode !== undefined) {
+        sets.push('exit_code = ?', 'exit_reported_at = ?');
+        args.push(report.exitCode, new Date().toISOString());
+    }
+    else if (report.vanished === true) {
+        sets.push('exit_reported_at = ?');
+        args.push(new Date().toISOString());
+    }
+    if (sets.length === 0)
+        return;
+    await db.prepare(`UPDATE jobs SET ${sets.join(', ')} WHERE object = ? AND status = 'running'`).run(...args, jobId);
+}
+function startedAtMs(jobId) {
+    const n = Number(jobId.slice(0, Math.max(0, jobId.indexOf('-'))));
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+function toRunning(row) {
+    return {
+        jobId: row.object, command: row.command, purpose: row.purpose, startedAtMs: startedAtMs(row.object),
+        outputKey: row.output_key, deadlineAtMs: row.deadline_at === null ? null : Date.parse(row.deadline_at),
+        pgid: row.pgid, pgidIdentity: row.pgid_identity, quietOk: row.quiet_ok,
+        activity: row.activity_last_ms === null || row.activity_sampled_ms === null ? null
+            : { lastActivityMs: row.activity_last_ms, sampledAtMs: row.activity_sampled_ms, files: (row.activity_files ?? '').split('\n').filter((f) => f !== '') },
+        silence: row.silence_activity_ms === null || row.silence_threshold_ms === null ? null
+            : { lastActivityMs: row.silence_activity_ms, thresholdMs: row.silence_threshold_ms },
+    };
+}
+/** Every `running` job a node owns, oldest first. */
+export async function runningJobs(db, nodeId) {
+    const rows = await db.prepare(`SELECT j.* FROM jobs j JOIN objects o ON o.id = j.object
+    WHERE o.owner = ? AND o.deleted_at IS NULL AND j.status = 'running'`).all(nodeId);
+    return rows.map(toRunning).sort((a, b) => a.startedAtMs - b.startedAtMs);
+}
+/** Every `running` job in the canvas, with its owner. */
+export async function allRunningJobs(db) {
+    const rows = await db.prepare(`SELECT j.*, o.owner AS owner FROM jobs j JOIN objects o ON o.id = j.object
+    WHERE o.deleted_at IS NULL AND j.status = 'running'`).all();
+    return rows.map((row) => ({ ...toRunning(row), owner: row.owner }));
+}
+/** Every `running` job in the canvas whose cancel deadline has passed, with its owner. */
+export async function expiredJobs(db, nowMs) {
+    const rows = await db.prepare(`SELECT j.*, o.owner AS owner FROM jobs j JOIN objects o ON o.id = j.object
+    WHERE o.deleted_at IS NULL AND j.status = 'running' AND j.deadline_at IS NOT NULL AND j.deadline_at <= ?`)
+        .all(new Date(nowMs).toISOString());
+    return rows.map((row) => ({ ...toRunning(row), owner: row.owner }));
+}
+/** Credit every armed deadline of a node's running jobs for an interval the node was not permitted to run. */
+export async function shiftJobDeadlines(db, nodeId, byMs) {
+    if (!Number.isFinite(byMs) || byMs <= 0)
+        return 0;
+    let shifted = 0;
+    for (const job of await runningJobs(db, nodeId)) {
+        if (job.deadlineAtMs === null)
+            continue;
+        await setJobDeadline(db, job.jobId, job.deadlineAtMs + byMs);
+        shifted += 1;
+    }
+    return shifted;
+}
+/** End every running job whose exit the broker reported: `exited` with its code, or `killed` when the process
+ *  vanished without one. Returns how many ended. */
+export async function endReportedJobs(db) {
+    const rows = await db.prepare(`SELECT j.object, j.exit_code FROM jobs j JOIN objects o ON o.id = j.object
+    WHERE o.deleted_at IS NULL AND j.status = 'running' AND j.exit_reported_at IS NOT NULL`).all();
+    for (const { object, exit_code } of rows) {
+        const job = (await getById(db, object));
+        await finishJob(db, job, exit_code === null ? { killedBy: null, reason: 'process disappeared without an exit record' } : { exitCode: exit_code });
+    }
+    return rows.length;
+}
+/** True when the node's newest execution runs on a runner other than the process runner (a sandbox): its jobs run
+ *  there, so their pids, supervisor files and output are not on this host and only the broker's reports describe them. */
+export async function ownerRunsRemotely(db, nodeId) {
+    const row = await db.prepare('SELECT runner FROM executions WHERE node_id = ? ORDER BY started_at DESC, attempt DESC LIMIT 1')
+        .get(nodeId);
+    return row !== undefined && row.runner !== 'process';
+}
+/** End, as killed, every running job whose owner's newest execution is a sandbox execution that has exited: the
+ *  sandbox the job ran in is gone with its broker, so nothing is left to report an exit. Run after `endReportedJobs`,
+ *  so an exit the broker did report wins. Returns how many ended. */
+export async function endJobsOfExitedSandboxes(db) {
+    const rows = await db.prepare(`SELECT j.object FROM jobs j JOIN objects o ON o.id = j.object
+    WHERE o.deleted_at IS NULL AND j.status = 'running'
+      AND (SELECT e.runner || ':' || e.state FROM executions e WHERE e.node_id = o.owner ORDER BY e.started_at DESC, e.attempt DESC LIMIT 1) IN ('blaxel:exited')`)
+        .all();
+    for (const { object } of rows) {
+        await finishJob(db, (await getById(db, object)), { killedBy: null, reason: 'the sandbox running the job ended with its broker' });
+    }
+    return rows.length;
+}

package/dist/core/graph/kinds/action.d.ts

@@ -0,0 +1,3 @@
+import type { ObjectKind } from './kind.js';
+/** An action is a receiver, not a publisher. Its source is the node it watches. */
+export declare const actionKind: ObjectKind;

package/dist/core/graph/kinds/action.js

@@ -0,0 +1,20 @@
+import { receiverForObject } from '../receivers.js';
+import { withBase } from './kind.js';
+import { header } from './render.js';
+import { objectDTO } from './dto.js';
+/** An action is a receiver, not a publisher. Its source is the node it watches. */
+export const actionKind = {
+    name: 'action', addressable: 'id', events: withBase({}),
+    receiverFor: receiverForObject,
+    // An action process already running cannot be retracted. Cancel its claim, then let the
+    // receiver's claim fence hold its successor until this attempt settles.
+    async supersedeClaimed(db, deliveryId) {
+        const now = Date.now();
+        return Number((await db.prepareUncached("UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE delivery_id = ? AND state = 'handed_off' AND canceled_at IS NULL")
+            .run(now, now, deliveryId)).changes) === 1;
+    },
+    async read(db, _reader, object) {
+        const data = { object: await objectDTO(db, object) };
+        return { data, text: header('object', data.object) };
+    },
+};

package/dist/core/graph/kinds/custom.d.ts

@@ -0,0 +1,8 @@
+import type { ObjectKind } from './kind.js';
+import type { Level } from '../types.js';
+/** A catalog is frozen into the kind; receiver choice belongs to each object. */
+export declare function customKind(name: string, declared: Record<string, {
+    level: Level;
+    supersedes?: boolean;
+    ends_wait?: boolean;
+}>): ObjectKind;

package/dist/core/graph/kinds/custom.js

@@ -0,0 +1,25 @@
+import { recordLiveRead } from './live-read.js';
+import { header } from './render.js';
+import { objectDTO } from './dto.js';
+import { receiverForObject } from '../receivers.js';
+/** A catalog is frozen into the kind; receiver choice belongs to each object. */
+export function customKind(name, declared) {
+    const events = Object.fromEntries(Object.entries(declared).map(([local, { ends_wait, ...spec }]) => [`${name}.${local}`, { ...spec, carriesBody: true, ...(ends_wait === undefined ? {} : { endsWait: ends_wait }) }]));
+    return {
+        name, events: {
+            created: { level: 4 }, read: { level: 1 }, watched: { level: 1 },
+            deleted: { level: 5 }, configured: { level: 1 }, ...events,
+        }, addressable: 'name', receiverFor: receiverForObject,
+        async read(db, reader, object, opts) {
+            await recordLiveRead(db, reader, object, opts.reposFn);
+            const row = await db.prepare('SELECT description, summary, state_json, published_at, receiver_json, dropped FROM custom_objects WHERE object = ?')
+                .get(object.id);
+            const receiver = row?.receiver_json == null ? null : JSON.parse(row.receiver_json);
+            const data = { object: await objectDTO(db, object), description: row?.description ?? '', summary: row?.summary ?? null,
+                state: row?.state_json == null ? null : JSON.parse(row.state_json), published_at: row?.published_at ?? null,
+                receiver: typeof receiver === 'string' ? receiver : receiver && typeof receiver === 'object' ? Object.keys(receiver)[0] : null,
+                dropped: row?.dropped ?? 0 };
+            return { data, text: `${header('object', data.object)}\nDescription: ${data.description}\nSummary: ${data.summary ?? ''}\nState: ${JSON.stringify(data.state)}\nPublished: ${data.published_at ?? 'never'}\nReceiver: ${data.receiver ?? 'none'}\nDropped: ${data.dropped}` };
+        },
+    };
+}

package/dist/core/graph/kinds/document.d.ts

@@ -0,0 +1,20 @@
+/** The document kind: markdown with revisions — its catalog (edits supersede and merge), its list fields and its render. */
+import type { DocFieldsDTO, ObjectDTO } from '../../../api/dto/objects.js';
+import { type ObjectKind } from './kind.js';
+export interface DocumentReadData {
+    summary: string | null;
+    revision: number;
+    heads: Array<{
+        rev_id: string;
+        number: number;
+        author_id: string | null;
+        created_at: string;
+    }>;
+    /** One body per head, in `heads` order. */
+    bodies: string[];
+    needs_merge: boolean;
+    listing?: ObjectDTO[];
+    attachments?: string;
+    fields?: DocFieldsDTO;
+}
+export declare const documentKind: ObjectKind;

package/dist/core/graph/kinds/document.js

@@ -0,0 +1,133 @@
+import { recordMemoryReadsIn } from '../../canvas/memory-reads.js';
+import { deliveryDocOf, nodeSubject, ownerHandle } from '../../substrate/delivery/corpus.js';
+import { recordContentDelivery } from '../../substrate/delivery/deliver.js';
+import { renderExplicitRead } from '../../substrate/delivery/render-event.js';
+import { permits, resolveReader } from '../../permissions/evaluator.js';
+import { documentRecord, readDocument } from '../documents.js';
+import { loadLedger, saveLedger } from '../exposures.js';
+import { getById } from '../objects.js';
+import { rulesOf } from '../rules.js';
+import { objectDTO } from './dto.js';
+import { withBase } from './kind.js';
+import { attr, header, section } from './render.js';
+import { mapAsync } from '../../async-array.js';
+/** Readable documents named directly under `<name>/` with the same owner; the
+ *  read's link previews join them as one listing. */
+async function listingOf(db, reader, doc) {
+    const prefix = `${doc.name}/`;
+    const read = await permits(db, await resolveReader(db, reader), 'read', 'o');
+    const rows = await db.prepareUncached(`SELECT o.* FROM objects o WHERE o.type = 'document' AND o.deleted_at IS NULL AND o.home_machine IS NULL AND o.owner IS NOT DISTINCT FROM ?
+    AND substr(o.name, 1, ?) = ? AND strpos(substr(o.name, ? + 1), '/') = 0 AND ${read.sql} ORDER BY o.name`).all(doc.owner, prefix.length, prefix, prefix.length, ...read.params);
+    return await mapAsync(rows, async (o) => await objectDTO(db, o));
+}
+/** Fire the document-read rules matching `doc` and preview what it links to.
+ *  A node holds `doc` and what it delivered in its ledger, so neither is
+ *  delivered again this context; a person has no ledger and gets every
+ *  attachment on each read. A link preview is not a read: no watch, no event. */
+async function explicitReadAttachments(db, reader, doc) {
+    const isNode = reader.class === 'node';
+    const ledger = isNode ? await loadLedger(db, reader.node.id) : { node: '', preferenceSnapshot: null, objects: new Map(), listed: new Map() };
+    const ctx = { db, reader, subject: isNode ? await nodeSubject(db, reader) : null, ledger, channel: 'transcript' };
+    const read = await renderExplicitRead(ctx, await deliveryDocOf(db, reader, doc));
+    if (isNode) {
+        await recordContentDelivery(db, reader, read.delivered);
+        await saveLedger(db, ledger);
+    }
+    return { attachments: read.attachments, linked: read.linked.map((d) => d.object) };
+}
+/** A node's explicit read of a knowledge or preference document is the analytics memory log's
+ *  `read` event; its companions are `loaded` rows, written by `recordContentDelivery`. */
+async function recordExplicitMemoryRead(db, reader, doc) {
+    if (reader.class !== 'node' || (doc.kind !== 'knowledge' && doc.kind !== 'preference') || doc.owner === null)
+        return;
+    const owner = await getById(db, doc.owner);
+    if (owner === null)
+        return;
+    await recordMemoryReadsIn(db, reader.node.id, [{ name: doc.name, scope: ownerHandle(owner), at: new Date().toISOString(), type: 'read' }]);
+}
+function render(o, d) {
+    const lines = [];
+    if (d.attachments)
+        lines.push(d.attachments, '');
+    lines.push(header('object', o, attr('privacy', o.privacy) + attr('revision', d.revision)));
+    lines.push(`Preview: ${o.preview}`);
+    if (d.summary)
+        lines.push(`Summary: ${d.summary}`);
+    if (d.fields !== undefined)
+        lines.push(`<fields>\n${JSON.stringify(d.fields, null, 2)}\n</fields>`);
+    if (d.needs_merge) {
+        d.heads.forEach((h, i) => {
+            lines.push(`<head${attr('rev', h.rev_id)}${attr('number', h.number)}${attr('author', h.author_id)}>`, d.bodies[i] ?? '', '</head>');
+        });
+        lines.push(`This document has ${d.heads.length} heads. Your next \`crtr doc edit\` writes the merged body and joins them into one revision.`);
+    }
+    else {
+        lines.push('', d.bodies[0] ?? '');
+    }
+    if (d.listing && d.listing.length > 0) {
+        const under = d.listing.some((l) => l.owner?.id === o.owner?.id && l.name.startsWith(`${o.name}/`));
+        const linked = d.listing.some((l) => l.owner?.id !== o.owner?.id || !l.name.startsWith(`${o.name}/`));
+        const title = under && linked ? `Names under ${o.name}/ and documents it links to`
+            : under ? `Names under ${o.name}/` : 'Documents it links to';
+        lines.push('', ...section(title, d.listing));
+    }
+    return lines.join('\n');
+}
+/** One edit's attrs in the mergeable shape: its revision range, authors and rationales. */
+function editAttrs(ev) {
+    const revision = ev.attrs['revision'];
+    const from = ev.attrs['from_revision'] ?? (typeof revision === 'number' ? revision - 1 : null);
+    const rationale = ev.attrs['rationale'];
+    return {
+        ...ev.attrs, from_revision: from, revision,
+        authors: ev.actor ? [ev.actor.id] : [],
+        rationales: typeof rationale === 'string' ? [rationale] : [],
+    };
+}
+/** A superseded edit folds into the new one: the range starts at the older edit's base, authors
+ *  are the union in first-edit order, rationales accumulate. */
+const mergeEdits = (prior, ev) => {
+    const newer = editAttrs(ev);
+    if (prior === null)
+        return newer;
+    const priorAuthors = prior['authors'] ?? [];
+    return {
+        ...newer, from_revision: prior['from_revision'] ?? null,
+        authors: [...priorAuthors, ...newer['authors'].filter((a) => !priorAuthors.includes(a))],
+        rationales: [...(prior['rationales'] ?? []), ...newer['rationales']],
+    };
+};
+export const documentKind = {
+    name: 'document',
+    addressable: 'name',
+    events: withBase({ edited: { level: 8, supersedes: true, merge: mergeEdits }, deleted: { level: 8 } }),
+    async listItem(db, doc) {
+        return { summary: (await documentRecord(db, doc)).summary ?? null, rules: (await rulesOf(db, doc)).length };
+    },
+    async read(db, reader, doc, opts) {
+        const read = await readDocument(db, reader, doc, opts.reposFn); // records the read watch at the current heads and publishes `read`
+        await recordExplicitMemoryRead(db, reader, doc);
+        const rec = read.record;
+        const under = await listingOf(db, reader, doc);
+        const { attachments, linked } = await explicitReadAttachments(db, reader, doc);
+        const listed = new Set(under.map((o) => o.id));
+        const listing = [...under, ...(await mapAsync(linked.filter((o) => !listed.has(o.id)), async (o) => await objectDTO(db, o)))];
+        const data = {
+            summary: rec.summary ?? null, revision: rec.revision,
+            heads: read.heads.map((h) => ({ rev_id: h.rev_id, number: h.number, author_id: h.author, created_at: h.created_at })),
+            bodies: read.heads.map((h) => h.body), needs_merge: read.needsMerge,
+            ...(listing.length > 0 ? { listing } : {}),
+            ...(attachments === '' ? {} : { attachments }),
+        };
+        if (opts.fields) {
+            data.fields = {
+                why_it_exists: rec.why_it_exists ?? null, unlisted: rec.unlisted, lint_ignore: rec.lint_ignore ?? [],
+                extensions: rec.extensions ?? {},
+                rules: (await rulesOf(db, doc)).map(({ matchFrontmatter, ...r }) => ({
+                    ...r, ...(matchFrontmatter === undefined ? {} : { match_frontmatter: matchFrontmatter }),
+                })),
+            };
+        }
+        return { data: data, text: render(await objectDTO(db, doc), data) };
+    },
+};