@north-light/api 0.3.580 → 0.3.587

package/dist/core/graph/custom.js

@@ -0,0 +1,298 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { CrtrError, usage } from '../errors.js';
+import { ExitCode } from '../../types.js';
+import { createObject, liveDocumentNamed } from './objects.js';
+import { invalidateCustomKind } from './kinds/registry.js';
+import { publish, HOP_LIMIT, HopLimitError } from './events.js';
+import { checkoutsForCwd } from './repo-sync/repos.js';
+import { onQueueSignal, signalQueue } from './receivers.js';
+import { receiverEndpoint, isPublicReceiverAddress } from './receiver-url.js';
+import { isIP } from 'node:net';
+import { KIND, LOCAL, MAX_KIND_EVENTS, RESERVED_KIND_ROOTS, eventCatalogReasons } from '../plugin-objects-manifest.js';
+import { check } from '../permissions/evaluator.js';
+import { userOf } from '../permissions/evaluator.js';
+import { nodePlace } from '../permissions/ceiling.js';
+import { PermissionError } from '../permissions/errors.js';
+import { writeActsFor } from '../permissions/facts.js';
+/** Whether this reader may register, publish or watch as an object owned by `owner`. */
+export async function mayActAs(db, reader, owner) {
+    // An app (a root shared by every account) carries no `acts_for`, so no user holds `edit` on it; its own server and runs act as it.
+    if (reader.class !== 'person' && reader.app.id === owner.id)
+        return true;
+    return await check(db, reader, 'edit', owner.id);
+}
+/** Whether the reader reaches the custom object: it may read it. */
+export async function customReachable(db, reader, object) {
+    return await check(db, reader, 'read', object.id);
+}
+export { onQueueSignal };
+const PRIVACY = ['public', 'private'];
+function conflict(code, message) { throw new CrtrError(code, message, ExitCode.GENERAL); }
+function hash(token) { return createHash('sha256').update(token).digest('hex'); }
+function issueToken() { return `crtr_pub_${randomBytes(32).toString('base64url')}`; }
+function receiverJson(receiver) {
+    if (receiver == null)
+        return null;
+    if (receiver === 'queue')
+        return JSON.stringify(receiver);
+    if (typeof receiver !== 'object' || Array.isArray(receiver))
+        throw usage('invalid custom receiver; expected queue, an https url, or argv and absolute cwd');
+    if ('url' in receiver && typeof receiver.url === 'string') {
+        try {
+            const url = receiverEndpoint(receiver.url);
+            const literal = url.hostname.replace(/^\[|\]$/g, '');
+            if (isIP(literal) && !isPublicReceiverAddress(literal))
+                throw new Error('non-public IP address');
+            return JSON.stringify({ url: receiver.url });
+        }
+        catch (error) {
+            throw usage(`invalid custom receiver: ${String(error)}`);
+        }
+    }
+    if ('argv' in receiver && Array.isArray(receiver.argv) && receiver.argv.length > 0 &&
+        receiver.argv.every((arg) => typeof arg === 'string') && typeof receiver.cwd === 'string' && receiver.cwd.startsWith('/'))
+        return JSON.stringify(receiver);
+    throw usage('invalid custom receiver; url must be https and argv requires a command and absolute cwd');
+}
+/** Whether the reader is a node of an isolated run, or an app call or stub reader carrying an isolated run place. */
+async function inIsolatedRun(db, reader) {
+    if (reader.class === 'node')
+        return (await nodePlace(db, reader.node.id))?.isolated === true;
+    if (reader.class === 'app' || reader.class === 'object')
+        return reader.place?.isolated === true;
+    return false;
+}
+/** Register a kind and a named instance in the caller's write transaction. */
+export async function registerCustomObject(db, reader, input) {
+    const { kind, name, owner, description, events, receiver, rotateToken, privacy } = input;
+    if (privacy !== undefined && !PRIVACY.includes(privacy))
+        throw usage(`invalid privacy ${JSON.stringify(privacy)}`);
+    if (!await mayActAs(db, reader, owner))
+        conflict('forbidden', `cannot act as ${owner.id}`);
+    if (await inIsolatedRun(db, reader))
+        throw new PermissionError(403, 'isolated_run', 'a custom object cannot be registered from an isolated run');
+    if (!KIND.test(kind) || RESERVED_KIND_ROOTS.includes(kind.split('.')[0]))
+        throw usage(`invalid or reserved kind ${kind}`);
+    if (!name.trim() || name !== name.trim() || name.includes('\0'))
+        throw usage(`invalid object name ${JSON.stringify(name)}`);
+    const json = receiverJson(receiver);
+    if (receiver !== 'queue' && receiver !== null && receiver !== undefined && 'argv' in receiver && reader.class !== 'person' && reader.class !== 'node')
+        conflict('argv_forbidden', 'argv receiver requires a person or node principal');
+    if (events === undefined) {
+        const declared = await db.prepare('SELECT source FROM object_kinds WHERE name = ?').get(kind);
+        if (declared?.source !== 'manifest' && declared?.source !== 'peer')
+            throw usage('events is required unless the kind is declared by an installed plugin');
+    }
+    else if (Object.keys(events).length > MAX_KIND_EVENTS || Object.entries(events).some(([local, spec]) => !LOCAL.test(local) || !Number.isInteger(spec?.level) || spec.level < 1 || spec.level > 10 ||
+        (spec.supersedes !== undefined && typeof spec.supersedes !== 'boolean') ||
+        (spec.ends_wait !== undefined && typeof spec.ends_wait !== 'boolean')))
+        throw usage('invalid custom event catalog');
+    const holder = await liveDocumentNamed(db, owner.id, name);
+    if (holder && !await customReachable(db, reader, holder))
+        conflict('forbidden', `cannot act as ${owner.id}`);
+    if (holder && reader.class !== 'person' && reader.class !== 'node') {
+        const prior = (await db.prepare('SELECT receiver_json FROM custom_objects WHERE object = ?').get(holder.id))?.receiver_json;
+        if (prior && typeof JSON.parse(prior) === 'object' && 'argv' in JSON.parse(prior))
+            conflict('argv_forbidden', 'argv receiver requires a person or node principal');
+    }
+    if (holder && holder.type !== kind)
+        conflict('name_taken', `${owner.name}/${name} is already held by ${holder.id}`);
+    const upserted = events === undefined ? null : await upsertKind(db, { name: kind, owner, description, events, read: null, source: 'register' });
+    if (!holder) {
+        const object = await createObject(db, { type: kind, kind: null, owner: owner.id, privacy: privacy ?? 'public', name, preview: '' });
+        if (owner.type === 'app')
+            await writeActsFor(db, object.id, await userOf(db, reader));
+        const token = issueToken();
+        await db.prepare(`INSERT INTO custom_objects (object, description, receiver_json, token_hash)
+      VALUES (?, ?, ?, ?)`).run(object.id, description, json, hash(token));
+        // A custom object a node registers reads from that node's run (Silas, 2026-09-30).
+        if (reader.class === 'node')
+            await db.prepare('UPDATE custom_objects SET registered_by = ? WHERE object = ?').run(reader.node.id, object.id);
+        if (json !== null)
+            await db.prepare('UPDATE objects SET reception = 2 WHERE id = ?').run(object.id);
+        await publish(db, { event: 'created', object, actor: reader.class === 'object' ? reader.object : reader.class === 'person' ? reader.person : reader.class === 'app' ? reader.app : reader.node, attrs: {} }, async (cwd) => await checkoutsForCwd(db, cwd));
+        return { object, token, created: true, changed: [] };
+    }
+    const current = await db.prepare('SELECT description, receiver_json FROM custom_objects WHERE object = ?').get(holder.id);
+    if (!current)
+        conflict('name_taken', `${owner.name}/${name} is not a custom object`);
+    const changed = [];
+    if (current.description !== description)
+        changed.push('description');
+    if (current.receiver_json !== json)
+        changed.push('receiver');
+    if (upserted?.changed.includes('events'))
+        changed.push('events');
+    if (upserted?.changed.includes('description') && !changed.includes('description'))
+        changed.push('description');
+    if (privacy !== undefined && holder.privacy !== privacy)
+        changed.push('privacy');
+    if (rotateToken)
+        changed.push('token');
+    if (changed.length === 0)
+        return { object: holder, created: false, changed };
+    const token = rotateToken ? issueToken() : undefined;
+    const object = changed.includes('privacy') ? { ...holder, privacy: privacy } : holder;
+    if (object !== holder)
+        await db.prepare('UPDATE objects SET privacy = ? WHERE id = ?').run(privacy, holder.id);
+    await db.prepare('UPDATE custom_objects SET description = ?, receiver_json = ?, token_hash = COALESCE(?, token_hash) WHERE object = ?')
+        .run(description, json, token === undefined ? null : hash(token), holder.id);
+    await db.prepare('UPDATE objects SET reception = ? WHERE id = ?').run(json === null ? 0 : 2, holder.id);
+    if (current.receiver_json !== json) {
+        const nowMs = Date.now();
+        if (json === null) {
+            const canceled = await db.prepare(`UPDATE deliveries SET canceled_at = ?, updated_at = ?
+        WHERE destination_id = ? AND state = 'pending' AND canceled_at IS NULL`).run(nowMs, nowMs, holder.id);
+            await db.prepare('UPDATE custom_objects SET dropped = dropped + ? WHERE object = ?').run(canceled.changes, holder.id);
+        }
+        else {
+            await db.prepare(`UPDATE deliveries SET next_attempt_at = ?, updated_at = ?
+        WHERE destination_id = ? AND state = 'pending' AND canceled_at IS NULL`)
+                .run(json === '"queue"' ? null : nowMs, nowMs, holder.id);
+        }
+        signalQueue(holder.id);
+    }
+    if (rotateToken)
+        signalQueue(holder.id);
+    await publish(db, { event: 'configured', object, actor: reader.class === 'object' ? reader.object : reader.class === 'person' ? reader.person : reader.class === 'app' ? reader.app : reader.node, attrs: { changed: changed.join(',') } }, async (cwd) => await checkoutsForCwd(db, cwd));
+    return { object, ...(token === undefined ? {} : { token }), created: false, changed };
+}
+/**
+ * The only writer of `object_kinds`. `source` says who is writing: an app's `register` call, an installed plugin's
+ * manifest, or a declaration that crossed from another machine (`peer`). Precedence: `manifest` and `register` rows
+ * are never overwritten by `peer`; a `manifest` write takes over a row it already owns and replaces a `peer` row;
+ * a `register` write leaves a `manifest` row alone (`skipped`) and replaces a `peer` row; another owner's
+ * `manifest` or `register` row is `kind_owned`. `read_json` is written only by `manifest`. A catalog is replaced,
+ * never merged. Runs in the caller's write transaction.
+ */
+export async function upsertKind(db, input) {
+    const { name, owner, description, events, read, source } = input;
+    if (!KIND.test(name))
+        throw usage(`invalid kind ${name}`);
+    if (eventCatalogReasons(events, name).length > 0)
+        throw usage('invalid custom event catalog');
+    // Concurrent writers of one new kind take turns: the later waits for the earlier commit, then updates instead of failing on the primary key.
+    await db.prepare('SELECT pg_advisory_xact_lock(hashtext(?))').get(`kind:${name}`);
+    const existing = await db.prepare('SELECT owner, description, events_json, read_json, source, declared FROM object_kinds WHERE name = ?').get(name);
+    const catalog = canonicalEvents(events);
+    const readJson = source === 'manifest' && read !== null ? JSON.stringify({ command: read.command }) : null;
+    const now = new Date().toISOString();
+    if (!existing) {
+        await db.prepare(`INSERT INTO object_kinds (name, owner, description, events_json, created_at, updated_at, read_json, source, declared)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1)`).run(name, owner.id, description, catalog, now, now, readJson, source);
+        invalidateCustomKind(db, name);
+        return { outcome: 'inserted', changed: [] };
+    }
+    const sameOwner = existing.owner === owner.id;
+    if (source === 'peer') {
+        if (existing.source !== 'peer')
+            return { outcome: 'skipped', changed: [] };
+    }
+    else if (existing.source !== 'peer') {
+        if (!sameOwner)
+            conflict('kind_owned', `${name} belongs to another owner`);
+        if (source === 'register' && existing.source === 'manifest')
+            return { outcome: 'skipped', changed: [] };
+    }
+    const changed = [];
+    if (canonicalEvents(JSON.parse(existing.events_json)) !== catalog)
+        changed.push('events');
+    if (existing.description !== description)
+        changed.push('description');
+    if ((existing.read_json ?? null) !== readJson)
+        changed.push('read');
+    if (changed.length === 0 && sameOwner && existing.source === source && existing.declared === 1)
+        return { outcome: 'unchanged', changed };
+    await db.prepare('UPDATE object_kinds SET owner = ?, description = ?, events_json = ?, read_json = ?, source = ?, declared = 1, updated_at = ? WHERE name = ?')
+        .run(owner.id, description, catalog, readJson, source, now, name);
+    invalidateCustomKind(db, name);
+    return { outcome: 'updated', changed };
+}
+export async function publishCustom(db, object, actor, input) {
+    const kind = await db.prepare('SELECT events_json FROM object_kinds WHERE name = ?').get(object.type);
+    if (!kind || object.deleted_at !== null)
+        throw usage(`${object.id} is not a live custom object`);
+    const declared = JSON.parse(kind.events_json);
+    if (!LOCAL.test(input.event) || !Object.hasOwn(declared, input.event))
+        throw new CrtrError('unknown_event', `${object.type} declares ${Object.keys(declared).join(', ')}, not ${input.event}`, ExitCode.USAGE, { declared: Object.keys(declared), event: input.event });
+    if (typeof input.summary !== 'string')
+        throw usage('summary must be text');
+    const state = input.state === undefined ? null : JSON.stringify(input.state);
+    if (input.state !== undefined && state === undefined)
+        throw usage('state must be JSON-serializable');
+    if (Buffer.byteLength(JSON.stringify({ summary: input.summary, ...(input.state === undefined ? {} : { state: input.state }) })) > 64 * 1024)
+        throw new CrtrError('body_too_large', 'custom event summary and state exceed 64 KiB', ExitCode.USAGE);
+    if (state !== null && Buffer.byteLength(state) > 64 * 1024)
+        throw usage('state exceeds 64 KiB');
+    // Validate cause/hop before mutating the object's current value. Only a named cause carries depth.
+    const cause = input.cause ?? null;
+    const parent = cause === null ? null : await db.prepare(`SELECT depth FROM messages WHERE message_id = ?
+    UNION ALL SELECT depth FROM message_causes WHERE message_id = ? LIMIT 1`).get(cause, cause);
+    if (cause !== null && parent === undefined)
+        throw new CrtrError('unknown_cause', `no message ${cause}`, ExitCode.USAGE);
+    if (parent && parent.depth >= HOP_LIMIT)
+        throw new HopLimitError(parent.depth + 1);
+    const now = new Date().toISOString();
+    await db.prepare('UPDATE custom_objects SET summary = ?, state_json = ?, published_at = ? WHERE object = ?').run(input.summary, state, now, object.id);
+    await db.prepare('UPDATE objects SET preview = ? WHERE id = ?').run(input.summary.split('\n')[0], object.id);
+    return await publish(db, { event: `${object.type}.${input.event}`, object, actor, attrs: {}, messageBody: { summary: input.summary, ...(input.state === undefined ? {} : { state: input.state }) }, ...(input.cause === undefined ? {} : { cause: input.cause }) }, async (cwd) => await checkoutsForCwd(db, cwd));
+}
+export async function unregisterCustomObject(db, object, actor) {
+    if (object.deleted_at !== null)
+        return;
+    await publish(db, { event: 'deleted', object, actor, attrs: {} }, async (cwd) => await checkoutsForCwd(db, cwd));
+    const now = new Date().toISOString();
+    await db.prepare('UPDATE objects SET deleted_at = ?, reception = 0 WHERE id = ?').run(now, object.id);
+    await db.prepare("UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE destination_id = ? AND state = 'pending' AND canceled_at IS NULL")
+        .run(Date.now(), Date.now(), object.id);
+    signalQueue(object.id);
+}
+function canonicalEvents(events) {
+    return JSON.stringify(Object.fromEntries(Object.entries(events).sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, spec]) => [name, { level: spec.level, ...(spec.supersedes === undefined ? {} : { supersedes: spec.supersedes }), ...(spec.ends_wait === undefined ? {} : { ends_wait: spec.ends_wait }) }])));
+}
+export async function pendingFor(db, object, afterSeq = 0) {
+    return await queueLines(db, object.id, afterSeq, 'pending');
+}
+/** A claimed push delivery has the identical document as a pending queue delivery. */
+export async function pushLineFor(db, deliveryId) {
+    const row = await db.prepare('SELECT destination_id FROM deliveries WHERE delivery_id = ?').get(deliveryId);
+    if (!row)
+        return null;
+    return (await queueLines(db, row.destination_id, -1, 'handed_off')).find((line) => line.delivery_id === deliveryId) ?? null;
+}
+async function queueLines(db, destinationId, afterSeq, state) {
+    const rows = await db.prepare(`SELECT d.delivery_id, m.message_id, m.seq, m.event, m.level, m.object_id, m.actor_id, m.body_json, m.body_ref, m.depth, m.created_at,
+    o.type, o.name, owner.id AS owner_id
+    FROM deliveries d JOIN messages m ON m.message_id = d.message_id JOIN objects o ON o.id = m.object_id
+    LEFT JOIN objects owner ON owner.id = o.owner
+    WHERE d.destination_id = ? AND d.state = ? AND d.canceled_at IS NULL AND m.seq > ? ORDER BY m.seq`).all(destinationId, state, afterSeq);
+    return rows.map((row) => {
+        const body = row.body_json ? JSON.parse(row.body_json) : {};
+        return { delivery_id: row.delivery_id, message_id: row.message_id, seq: row.seq, event: row.event, level: row.level,
+            object: { id: row.object_id, type: row.type, name: row.name, owner: row.owner_id }, actor: row.actor_id,
+            attrs: body.push?.attrs ?? {}, ...(body.summary === undefined ? {} : { summary: body.summary }),
+            ...(body.state === undefined ? {} : { state: body.state }), ...(body.push?.pointer === undefined ? {} : { pointer: body.push.pointer }),
+            depth: row.depth, created_at: row.created_at };
+    });
+}
+export async function acknowledge(db, object, deliveryIds) {
+    const now = Date.now();
+    const unknown = [];
+    let acknowledged = 0;
+    for (const id of deliveryIds) {
+        const changed = await db.prepare(`UPDATE deliveries SET state = 'acknowledged', acknowledged_at = ?, updated_at = ?
+      WHERE delivery_id = ? AND destination_id = ? AND state = 'pending' AND canceled_at IS NULL`).run(now, now, id, object.id);
+        if (Number(changed.changes))
+            acknowledged++;
+        else
+            unknown.push(id);
+    }
+    return { acknowledged, ...(unknown.length ? { unknown } : {}) };
+}
+export async function verifyPublishToken(db, object, token) {
+    const row = await db.prepare('SELECT token_hash FROM custom_objects WHERE object = ?').get(object.id);
+    const expected = Buffer.from(row?.token_hash ?? ''.padEnd(64, '0'), 'hex');
+    const actual = Buffer.from(hash(token), 'hex');
+    return token.startsWith('crtr_pub_') && object.deleted_at === null && expected.length === actual.length && timingSafeEqual(expected, actual) && row?.token_hash != null;
+}

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

@@ -0,0 +1,16 @@
+import type { ObjectRow, Reader } from './types.js';
+import { type CanvasDb } from '../canvas/db.js';
+/** Mark the node and everything it owns deleted except kept documents, which stay owned by the
+ *  deleted node; drop the node's watches (both ends) and its `nodes` row. One savepoint, so it runs as one
+ *  transaction or inside the caller's. Refuses a node whose managed worktree is unreconciled. */
+export declare function deleteNodeWithOwned(db: CanvasDb, node: ObjectRow): Promise<void>;
+/** Delete a profile object with what it owns, in the same flow as the profile's own deletion
+ *  (`crtr profile delete`): its documents follow the node rule — deleted, except one a live document
+ *  outside the deletion links to, which stays owned by the deleted profile until its last link goes.
+ *  The object row stays with `deleted_at` (kept documents still name it); its handle is released so
+ *  a new profile can take the name, and its identity row stays so a kept document's permission
+ *  string still names the profile id. Returns whether a profile object existed for `profileId`. */
+export declare function deleteProfileWithOwned(db: CanvasDb, profileId: string): Promise<boolean>;
+/** The owner's undelete, inside the 30 days before the purge pass may take the row (`core/storage/purge.ts`). Only a document comes back:
+ *  a deleted node has lost its `nodes` row and everything that cascaded from it, and a deleted profile has lost its handle. */
+export declare function undeleteObject(db: CanvasDb, reader: Reader | null, object: ObjectRow): Promise<ObjectRow>;

package/dist/core/graph/deletion.js

@@ -0,0 +1,104 @@
+/** Deleting a node with what it owns (spec §6 "Deletion follows the owner", A9). Rows are kept
+ *  with `deleted_at` so every pointer resolves to "deleted" with the last preview. A document a
+ *  live document outside the deletion links to is kept: it stays owned by the deleted node, under
+ *  its name and rules, and is collected when its last link goes (`collectUnlinked`). */
+import { hasUnreconciledWorktree } from '../canvas/worktrees.js';
+import { usage } from '../errors.js';
+import { deleteDocument, undeleteDocument } from './documents.js';
+import { publish } from './events.js';
+import { getById } from './objects.js';
+import { writeActsFor } from '../permissions/facts.js';
+import { rememberDeletedIsolated } from '../permissions/ceiling.js';
+import { withCanvasWrite } from '../canvas/db.js';
+/** Mark the node and everything it owns deleted except kept documents, which stay owned by the
+ *  deleted node; drop the node's watches (both ends) and its `nodes` row. One savepoint, so it runs as one
+ *  transaction or inside the caller's. Refuses a node whose managed worktree is unreconciled. */
+export async function deleteNodeWithOwned(db, node) {
+    if (node.type !== 'node')
+        throw new Error(`deleteNodeWithOwned: ${node.id} is a ${node.type}, not a node`);
+    if (await hasUnreconciledWorktree(node.id))
+        throw new Error(`refusing to delete node ${node.id}: its managed worktree is not reconciled`);
+    await withCanvasWrite(async () => await deleteInside(db, node), { savepoint: true });
+}
+/** Delete a profile object with what it owns, in the same flow as the profile's own deletion
+ *  (`crtr profile delete`): its documents follow the node rule — deleted, except one a live document
+ *  outside the deletion links to, which stays owned by the deleted profile until its last link goes.
+ *  The object row stays with `deleted_at` (kept documents still name it); its handle is released so
+ *  a new profile can take the name, and its identity row stays so a kept document's permission
+ *  string still names the profile id. Returns whether a profile object existed for `profileId`. */
+export async function deleteProfileWithOwned(db, profileId) {
+    const profile = await db.prepare(`SELECT o.* FROM identities i JOIN objects o ON o.id = i.object
+    WHERE i.scheme = 'profile' AND i.external_id = ? AND o.type = 'profile' AND o.deleted_at IS NULL`)
+        .get(profileId);
+    if (!profile)
+        return false;
+    await withCanvasWrite(async () => {
+        // Nodes under the profile are never deleted with it: each goes back under its app, readable by the person it ran for.
+        const moved = await db.prepare(`UPDATE objects o SET owner = n.app FROM nodes n WHERE n.node_id = o.id AND o.owner = ? AND n.app IS NOT NULL
+      RETURNING o.id, n.sub`).all(profile.id);
+        for (const { id, sub } of moved)
+            if (sub)
+                await writeActsFor(db, id, sub);
+        await deleteOwned(db, profile);
+        await db.prepare('UPDATE objects SET deleted_at = ?, name = ? WHERE id = ?')
+            .run(new Date().toISOString(), `${profile.name}.deleted-${profile.id}`, profile.id);
+        await publish(db, { event: 'deleted', object: (await getById(db, profile.id)), actor: null, attrs: {} });
+        await db.prepare('DELETE FROM watches WHERE object = ? OR watcher = ?').run(profile.id, profile.id);
+    }, { savepoint: true });
+    return true;
+}
+/** The owner's undelete, inside the 30 days before the purge pass may take the row (`core/storage/purge.ts`). Only a document comes back:
+ *  a deleted node has lost its `nodes` row and everything that cascaded from it, and a deleted profile has lost its handle. */
+export async function undeleteObject(db, reader, object) {
+    if (object.type !== 'document')
+        throw usage(`${object.type} ${object.name} cannot be undeleted; only documents can`, { id: object.id });
+    return await undeleteDocument(db, reader, object);
+}
+async function deleteInside(db, node) {
+    const now = await deleteOwned(db, node);
+    await db.prepare('UPDATE objects SET deleted_at = ? WHERE id = ?').run(now, node.id);
+    await publish(db, { event: 'deleted', object: (await getById(db, node.id)), actor: null, attrs: {} });
+    await db.prepare('DELETE FROM watches WHERE object = ? OR watcher = ?').run(node.id, node.id);
+    // The run of a node of an isolated run outlives its row, so what it keeps stays confined (Silas, 2026-09-30).
+    await rememberDeletedIsolated(node.id, db);
+    // A surviving member of a run whose root goes joins no run: a `run_id` naming no row fails every event append
+    // for it. A member of an isolated run keeps its `run_id`, which confinement resolves through the tombstones above.
+    await db.prepare('UPDATE nodes SET run_id = NULL WHERE run_id = ? AND node_id != ? AND isolated = 0').run(node.id, node.id);
+    await db.prepare('DELETE FROM nodes WHERE node_id = ?').run(node.id);
+}
+/** Delete everything `owner` owns except kept documents; returns the deletion timestamp. */
+async function deleteOwned(db, node) {
+    const owned = await db.prepare(`WITH RECURSIVE sub(id) AS (
+      SELECT id FROM objects WHERE owner = ?
+      UNION SELECT o.id FROM objects o JOIN sub ON o.owner = sub.id)
+    SELECT o.* FROM objects o JOIN sub ON sub.id = o.id WHERE o.deleted_at IS NULL`)
+        .all(node.id);
+    const deleting = new Set(owned.map((o) => o.id));
+    // A document a kept document links to is kept; keeping it can keep what it links to.
+    const linkers = db.prepare(`SELECT e.src FROM edges e JOIN objects s ON s.id = e.src
+    WHERE e.type = 'links-to' AND e.dst = ? AND s.deleted_at IS NULL`);
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const o of owned) {
+            if (o.type !== 'document' || !deleting.has(o.id))
+                continue;
+            if ((await linkers.all(o.id)).some(({ src }) => !deleting.has(src))) {
+                deleting.delete(o.id);
+                changed = true;
+            }
+        }
+    }
+    const now = new Date().toISOString();
+    for (const o of owned) {
+        if (!deleting.has(o.id))
+            continue;
+        if (o.type === 'document') {
+            await deleteDocument(db, null, o);
+            continue;
+        }
+        await db.prepare('UPDATE objects SET deleted_at = ? WHERE id = ?').run(now, o.id);
+        await publish(db, { event: 'deleted', object: (await getById(db, o.id)), actor: null, attrs: {} });
+        await db.prepare('DELETE FROM watches WHERE object = ? OR watcher = ?').run(o.id, o.id);
+    }
+    return now;
+}

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

@@ -0,0 +1,181 @@
+import { type ReposFn } from './reader.js';
+import type { ObjectRow, Privacy, Reader, Revision, RuleSpec } from './types.js';
+import { type CanvasDb } from '../canvas/db.js';
+export interface DocumentFields {
+    preview?: string;
+    summary?: string | null;
+    privacy?: Privacy;
+    rules?: readonly RuleSpec[];
+    whyItExists?: string | null;
+    unlisted?: boolean;
+    lintIgnore?: readonly string[] | null;
+    extensions?: Record<string, Record<string, unknown>> | null;
+}
+export interface WriteSpec extends DocumentFields {
+    owner: ObjectRow;
+    name: string;
+    kind: string;
+    preview: string;
+    privacy: Privacy;
+    /** The permission schema type the document is evaluated under (`firstlight/memory`); omitted = `crtr/object`. */
+    schemaType?: string;
+    /** Facts written on the new document in the same transaction (`{ relation: 'editor', subject: 'user:abc' }`); they need a `schemaType`. */
+    relations?: Array<{
+        relation: string;
+        subject: string;
+    }>;
+}
+export type DocumentChange = {
+    body: string;
+    verbatim?: boolean;
+} | {
+    replace: ReadonlyArray<{
+        old: string;
+        new: string;
+    }>;
+    verbatim?: boolean;
+};
+export interface DocumentRecord {
+    summary: string | null;
+    heads_key: string;
+    revision: number;
+    why_it_exists: string | null;
+    unlisted: boolean;
+    lint_ignore: string[] | null;
+    extensions: Record<string, Record<string, unknown>> | null;
+    source_path: string | null;
+}
+export interface Head extends Revision {
+    body: string;
+}
+export interface RenderedLink {
+    written_as: string;
+    object: ObjectRow;
+    deleted: boolean;
+}
+export interface DocumentRead {
+    object: ObjectRow;
+    record: DocumentRecord;
+    heads: Head[];
+    needsMerge: boolean;
+    links: RenderedLink[];
+}
+/** The object a reader acts as: its node, its app, or the person. */
+export declare function actorOf(reader: Reader): ObjectRow;
+/** Head revisions (no child), highest number first. More than one means the document needs a merge. */
+export declare function heads(db: CanvasDb, doc: ObjectRow): Promise<Revision[]>;
+export declare function documentRecord(db: CanvasDb, doc: ObjectRow): Promise<DocumentRecord>;
+/** The `[[name]]` links a body names, in order, each once. */
+export declare function linksIn(body: string): string[];
+/** Derive the document's `links-to` edges from `body`, resolving each name in the writer's
+ *  view. A name that resolves to nothing or to several objects stays text and is returned,
+ *  and remembered so {@link linkNewlyNamed} can link it when a document by that name appears;
+ *  one that may live on another runtime is neither linked nor reported. */
+export declare function setRevisionLinks(db: CanvasDb, reader: Reader, doc: ObjectRow, body: string): Promise<string[]>;
+/** `body` with each `[[link]]` the document's `links-to` edges resolved shown under its target's
+ *  current name, so a rename rewrites no stored body yet every read shows the new name (spec §4).
+ *  A link written as the target's id, or to a deleted target, stays as written. */
+export declare function withCurrentNames(db: CanvasDb, doc: ObjectRow, body: string): Promise<string>;
+/** Write the record fields that are present; `null` clears a nullable one. Rules are
+ *  replaced when given. Does not publish; callers publish the act the fields belong to. */
+export declare function applyDocumentFields(db: CanvasDb, doc: ObjectRow, fields: DocumentFields): Promise<ObjectRow>;
+/** Create a document with its first revision. The actor becomes a watcher whose read base is
+ *  the new revision; `created` is published. Returns the names that stayed text. */
+export declare function writeDocument(db: CanvasDb, reader: Reader, spec: WriteSpec, body: string, reposFn?: ReposFn): Promise<{
+    object: ObjectRow;
+    revision: number;
+    unresolved: string[];
+}>;
+/** The base of the reader's next edit: the heads it last read or wrote, or null when it never has. */
+export declare function readBase(db: CanvasDb, reader: Reader, doc: ObjectRow): Promise<string | null>;
+/** Apply exact-text replacements to one head's body; each `old` must occur exactly once. */
+export declare function applyReplacements(body: string, replace: ReadonlyArray<{
+    old: string;
+    new: string;
+}>): string;
+/**
+ * Commit a new revision made from `base` — the editor's read heads captured when it computed
+ * the change. No base → `read_first`. The commit is CAS on `documents.heads_key`: a base that is
+ * no longer current returns `{stale}` and writes nothing. The new revision's parents are every
+ * head, so an edit from a read that showed several heads merges them. `fields` are record
+ * changes applied with the edit.
+ */
+export declare function editDocument(db: CanvasDb, reader: Reader, doc: ObjectRow, change: DocumentChange, rationale: string, base: string | null, fields?: DocumentFields, reposFn?: ReposFn): Promise<{
+    revision: number;
+    heads_key: string;
+    unresolved: string[];
+} | {
+    stale: {
+        heads_key: string;
+        revision: number;
+    };
+}>;
+/** Change record fields (preview, summary, privacy, rules, …). A null reader is repo sync, which carries no reader, checks no access and
+ *  records no history. Any other caller's change is recorded as a revision with the current body, so `history` attributes it (author,
+ *  `acting_app`, `acting_for`) with the rationale. It descends from the highest head only, so a document that needs a merge still does. A caller
+ *  that held the heads before keeps holding them; one that had not read the body does not gain a read base it never earned. */
+export declare function setDocumentRecord(db: CanvasDb, reader: Reader | null, doc: ObjectRow, fields: DocumentFields, rationale?: string): Promise<ObjectRow>;
+/** Record that the reader holds the document's current heads: a `read` watch with that read
+ *  base, and a `read` push. Delivery's content load calls this without reading the body. */
+export declare function recordRead(db: CanvasDb, reader: Reader, doc: ObjectRow, reposFn?: ReposFn): Promise<void>;
+/** The document's record, each head with its body (several = needs merge) and its links under
+ *  their current names; records the read. */
+export declare function readDocument(db: CanvasDb, reader: Reader, doc: ObjectRow, reposFn?: ReposFn): Promise<DocumentRead>;
+/** Every revision, newest first, with authors, rationales and parents. Records nothing. */
+export declare function history(db: CanvasDb, reader: Reader, doc: ObjectRow): Promise<Revision[]>;
+/** Rename and/or re-own a document. Only `objects` changes: links point at the id, so no body is
+ *  rewritten. A null actor is repo sync, which carries no reader and checks no access. */
+export declare function moveDocument(db: CanvasDb, reader: Reader | null, doc: ObjectRow, to: {
+    name?: string;
+    owner?: ObjectRow;
+}, reposFn?: ReposFn): Promise<ObjectRow>;
+/** Mark the document deleted; the row stays with its last preview. Publishes `deleted`
+ *  (level 8), then ends the watches on it and drops its rules. A null actor is repo sync or
+ *  node deletion; `deletedAt` is the tombstone's own time when sync imports one. What it linked to is re-checked by {@link collectUnlinked}. */
+export declare function deleteDocument(db: CanvasDb, reader: Reader | null, doc: ObjectRow, reposFn?: ReposFn, deletedAt?: string): Promise<ObjectRow>;
+/** Repo sync: bring a deleted document back under `name` (checked free first). Revisions, record
+ *  and links are untouched; the watches and rules deletion dropped are not recreated here. */
+export declare function restoreDocument(db: CanvasDb, doc: ObjectRow, name: string, reposFn?: ReposFn): Promise<ObjectRow>;
+/** The owner's undelete: bring a deleted document back under its own name inside the 30-day window (past it the purge pass may take the
+ *  row). Its owner must be live. Revisions, record and links are untouched; the rules, watches and facts deletion dropped are not
+ *  recreated (as {@link restoreDocument}). */
+export declare function undeleteDocument(db: CanvasDb, reader: Reader | null, doc: ObjectRow, now?: number): Promise<ObjectRow>;
+/** Delete each of `targets` that is a kept document nothing links to any more: a live document
+ *  whose owner is deleted (node deletion kept it because a live document linked to it) and that
+ *  no other live document links to. Each one deleted re-checks what it linked to, so chains of
+ *  kept documents collapse; a cycle of kept documents keeps itself. Call it after a document
+ *  stops linking to `targets` — it was deleted, or an edit dropped the links. */
+export declare function collectUnlinked(db: CanvasDb, targets: Iterable<string>, reposFn?: ReposFn): Promise<void>;
+export interface ImportedRevision {
+    rev_id?: string;
+    body_hash: string;
+    author: ObjectRow | null;
+    rationale: string | null;
+    created_at: string;
+    verbatim?: boolean;
+}
+export interface ImportSpec extends WriteSpec {
+    id?: string;
+    revisions: readonly ImportedRevision[];
+}
+/** Migration: a document with its linear history (oldest first; bodies already in the body
+ *  store). Explicit authors and times; records no edge or watch and publishes nothing — the
+ *  caller adds links (`setRevisionLinks`), acted-on edges and watches. */
+export declare function importDocument(db: CanvasDb, spec: ImportSpec, reposFn?: ReposFn): Promise<ObjectRow>;
+export interface SyncedRevision {
+    rev_id: string;
+    parents: readonly string[];
+    body_hash: string;
+    rationale: string | null;
+    created_at: string;
+    verbatim?: boolean;
+}
+/** Repo sync: add revisions that arrived from another runtime, skipping known `rev_id`s. No
+ *  CAS, author NULL, publishes nothing; the caller publishes `edited` (with `needs_merge`
+ *  when `headCount > 1`) and re-derives links from the head it trusts. */
+export declare function insertImportedRevisions(db: CanvasDb, doc: ObjectRow, revs: readonly SyncedRevision[]): Promise<{
+    heads_key: string;
+    headCount: number;
+}>;
+/** Look up a live document by id (convenience for handlers and importers). */
+export declare function documentById(db: CanvasDb, id: string): Promise<ObjectRow>;