@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,41 @@
+/** `acted-on` and `links-to` edges. An edge is visible only to a reader who may read both ends. */
+import type { ObjectRow, Reader } from './types.js';
+import type { CanvasDb } from '../canvas/db.js';
+export type EdgeType = 'acted-on' | 'links-to';
+export interface Edge {
+    type: EdgeType;
+    src: ObjectRow;
+    dst: ObjectRow;
+    written_as: string | null;
+    created_at: string;
+}
+/** One row per actor and object however many times the actor acts. */
+export declare function recordActedOn(db: CanvasDb, actor: ObjectRow, object: ObjectRow): Promise<void>;
+/** Replace the document's `links-to` edges with the links of its current revision. Answers the
+ *  ids it no longer links to, so the caller can collect a kept document that lost its last link. */
+export declare function setLinks(db: CanvasDb, doc: ObjectRow, links: ReadonlyArray<{
+    written_as: string;
+    dst: ObjectRow;
+}>): Promise<string[]>;
+/** Replace the names the document's current revision links that resolved to nothing or to several objects.
+ *  Kept so that when a document with such a name comes into being, the link can gain its edge. */
+export declare function setUnresolved(db: CanvasDb, doc: ObjectRow, names: readonly string[]): Promise<void>;
+/** Forget `names` among the document's remembered unresolved links: they have gained an edge. */
+export declare function dropUnresolved(db: CanvasDb, doc: ObjectRow, names: Iterable<string>): Promise<void>;
+/** The unresolved links, as `{src, name}`, whose written name is the document's id or `name`, or ends in `/<name>`: every
+ *  link that could name a document called `name`, bare or qualified by its owner. */
+export declare function unresolvedLinksCouldName(db: CanvasDb, name: string, id: string): Promise<Array<{
+    src: string;
+    name: string;
+}>>;
+/** The document's current `links-to` edges as the links they were written from. */
+export declare function linksOf(db: CanvasDb, doc: ObjectRow): Promise<Array<{
+    written_as: string;
+    dst: ObjectRow;
+}>>;
+/** Documents whose body links to `object`. */
+export declare function backlinks(db: CanvasDb, reader: Reader, object: ObjectRow): Promise<Edge[]>;
+export declare function edgesOf(db: CanvasDb, reader: Reader, object: ObjectRow, opts?: {
+    type?: EdgeType;
+    direction?: 'out' | 'in' | 'both';
+}): Promise<Edge[]>;

package/dist/core/graph/edges.js

@@ -0,0 +1,83 @@
+import { check, permits, resolveReader } from '../permissions/evaluator.js';
+import { getById } from './objects.js';
+import { mapAsync } from '../async-array.js';
+/** One row per actor and object however many times the actor acts. */
+export async function recordActedOn(db, actor, object) {
+    await db.prepare(`INSERT INTO edges (type, src, dst, written_as, created_at) VALUES ('acted-on', ?, ?, NULL, ?)
+    ON CONFLICT DO NOTHING`)
+        .run(actor.id, object.id, new Date().toISOString());
+}
+/** Replace the document's `links-to` edges with the links of its current revision. Answers the
+ *  ids it no longer links to, so the caller can collect a kept document that lost its last link. */
+export async function setLinks(db, doc, links) {
+    const before = (await db.prepare(`SELECT dst FROM edges WHERE type = 'links-to' AND src = ?`).all(doc.id))
+        .map(({ dst }) => dst);
+    await db.prepare(`DELETE FROM edges WHERE type = 'links-to' AND src = ?`).run(doc.id);
+    const insert = db.prepare(`INSERT INTO edges (type, src, dst, written_as, created_at) VALUES ('links-to', ?, ?, ?, ?)
+    ON CONFLICT DO NOTHING`);
+    const now = new Date().toISOString();
+    for (const link of links)
+        await insert.run(doc.id, link.dst.id, link.written_as, now);
+    const still = new Set(links.map((link) => link.dst.id));
+    return before.filter((dst) => !still.has(dst));
+}
+/** Replace the names the document's current revision links that resolved to nothing or to several objects.
+ *  Kept so that when a document with such a name comes into being, the link can gain its edge. */
+export async function setUnresolved(db, doc, names) {
+    await db.prepare('DELETE FROM unresolved_links WHERE src = ?').run(doc.id);
+    const insert = db.prepare('INSERT INTO unresolved_links (src, name) VALUES (?, ?) ON CONFLICT DO NOTHING');
+    for (const name of names)
+        await insert.run(doc.id, name);
+}
+/** Forget `names` among the document's remembered unresolved links: they have gained an edge. */
+export async function dropUnresolved(db, doc, names) {
+    const drop = db.prepare('DELETE FROM unresolved_links WHERE src = ? AND name = ?');
+    for (const name of names)
+        await drop.run(doc.id, name);
+}
+/** The unresolved links, as `{src, name}`, whose written name is the document's id or `name`, or ends in `/<name>`: every
+ *  link that could name a document called `name`, bare or qualified by its owner. */
+export async function unresolvedLinksCouldName(db, name, id) {
+    return await db.prepare(`SELECT src, name FROM unresolved_links WHERE name = ? OR name = ? OR right(name, length(CAST(? AS text)) + 1) = '/' || CAST(? AS text) ORDER BY src, name`)
+        .all(name, id, name, name);
+}
+/** The document's current `links-to` edges as the links they were written from. */
+export async function linksOf(db, doc) {
+    const rows = await db.prepare(`SELECT e.dst, e.written_as FROM edges e WHERE e.type = 'links-to' AND e.src = ? ORDER BY e.written_as`)
+        .all(doc.id);
+    return (await mapAsync(rows, async (r) => ({ written_as: r.written_as ?? '', dst: (await getById(db, r.dst)) })));
+}
+/** Documents whose body links to `object`. */
+export async function backlinks(db, reader, object) {
+    return await edgesOf(db, reader, object, { type: 'links-to', direction: 'in' });
+}
+export async function edgesOf(db, reader, object, opts = {}) {
+    const ev = await resolveReader(db, reader);
+    if (!await check(db, ev, 'read', object.id))
+        return [];
+    const direction = opts.direction ?? 'both';
+    const types = opts.type ? [opts.type] : ['acted-on', 'links-to'];
+    const other = await permits(db, ev, 'read', 'x');
+    const raws = [];
+    // The other end is joined to its objects row, so only edges whose other end the reader may read come back.
+    for (const type of types) {
+        if (direction !== 'in')
+            raws.push(...await db.prepareUncached(`SELECT e.* FROM edges e JOIN objects x ON x.id = e.dst WHERE e.type = ? AND e.src = ? AND ${other.sql}`).all(type, object.id, ...other.params));
+        if (direction !== 'out')
+            raws.push(...await db.prepareUncached(`SELECT e.* FROM edges e JOIN objects x ON x.id = e.src WHERE e.type = ? AND e.dst = ? AND ${other.sql}`).all(type, object.id, ...other.params));
+    }
+    const seen = new Set();
+    const out = [];
+    for (const raw of raws) {
+        const key = `${raw.type}|${raw.src}|${raw.dst}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const src = raw.src === object.id ? object : await getById(db, raw.src);
+        const dst = raw.dst === object.id ? object : await getById(db, raw.dst);
+        if (!src || !dst)
+            continue;
+        out.push({ type: raw.type, src, dst, written_as: raw.written_as, created_at: raw.created_at });
+    }
+    return out;
+}

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

@@ -0,0 +1,49 @@
+export declare function subscribeDocumentEvents(id: string, callback: (event: 'edited' | 'deleted') => void): Promise<() => void>;
+import { type ReposFn } from './reader.js';
+import { type Subscription } from './watches.js';
+import { CrtrError } from '../errors.js';
+import type { EventSpec } from './kinds/kind.js';
+import { type CanvasEvent, type Level, type ListenConfig, type ListenDelivery, type ObjectRow } from './types.js';
+import { type CanvasDb } from '../canvas/db.js';
+/** The level `ev` publishes at: the declared level when none is supplied; a supplied level
+ *  must equal it or be one of the event's declared `levels`. Throws `unknown_event` for an
+ *  event the object's kind does not declare, `invalid_level` for any other level. */
+export declare function resolveLevel(ev: Pick<CanvasEvent, 'event' | 'object' | 'level'>, spec: EventSpec): Level;
+/** NATS-style match over dot-separated event names: `*` is one part, `>` the rest (at least one part). */
+export declare function matchSubject(pattern: string, event: string): boolean;
+/** Per config, the delivery of the highest threshold the level reaches; across configs, the
+ *  strongest. Null when the level is below every threshold of every config. */
+export declare function resolveDelivery(configs: readonly ListenConfig[], level: Level): ListenDelivery | null;
+/** A subscription's own config, else the watcher's `objects.listen_json`, else the global default. */
+export declare function listenConfigFor(db: CanvasDb, subscription: Pick<Subscription, 'config'>, watcher: ObjectRow): Promise<ListenConfig>;
+/** Supersede (`spec.supersedes`): each destination's pending deliveries of the same
+ *  event on the same object are deleted. A receiver kind may fence its claimed delivery if
+ *  that in-flight execution is replaceable. The replacement carries `spec.merge(prior, ev)` —
+ *  prior being the attrs of the latest superseded message, null when there is none — or, with no
+ *  merge, the newer event's attrs. Destinations are grouped by the message they superseded, so
+ *  each group shares one replacement message. Messages left with no delivery are deleted.
+ *  The core selects matches by delivery destination and the message's event and object.
+ *  An event that does not supersede is one group with its own attrs. */
+export declare function supersede<D>(db: CanvasDb, ev: CanvasEvent, spec: EventSpec, destinations: readonly D[], idOf: (d: D) => string): Promise<Array<{
+    attrs: Record<string, unknown>;
+    destinations: D[];
+}>>;
+/**
+ * Validate the event against its object's kind (`resolveLevel`), then push it to every watcher of
+ * the object itself whose subscriptions receive it — a watch on an owner hears that owner's own
+ * events, not those of the objects it owns — inside the caller's write transaction. Candidates are
+ * the watchers whose `objects.reception` admits the event: a `durable` event reaches reception ≥ 1
+ * (a done node too), any other only reception 2. The actor is never pushed its own act, and access
+ * is re-checked per watcher. Writes one `messages` row, only when a delivery results, and hands
+ * each receiver (`receivers.ts`) its destinations. `reposFn` resolves a watcher's repos when the
+ * object lives in a repo space.
+ */
+export declare const HOP_LIMIT = 8;
+export declare class HopLimitError extends CrtrError {
+    constructor(depth: number);
+}
+export declare function publish(db: CanvasDb, input: CanvasEvent, reposFn?: ReposFn): Promise<{
+    delivered: number;
+    message_id: string | null;
+    depth: number;
+}>;

package/dist/core/graph/events.js

@@ -0,0 +1,315 @@
+/** The event catalog, subject matching, listening-config resolution and `publish`: the one
+ *  path by which an event on an object reaches its watchers' inboxes. */
+import { EventEmitter } from 'node:events';
+const documentEvents = new EventEmitter();
+documentEvents.setMaxListeners(0);
+export async function subscribeDocumentEvents(id, callback) {
+    const listener = (event) => callback(event);
+    documentEvents.on(id, listener);
+    return () => documentEvents.off(id, listener);
+}
+import { evalCondition } from '../predicate.js';
+import { finalizeNodeMail, insertMessage } from '../feed/messages.js';
+import { check, resolveReader } from '../permissions/evaluator.js';
+import { getById } from './objects.js';
+import { appScopesNow, publishLookups, readerForObject } from './reader.js';
+import { configFromJson } from './watches.js';
+import { CrtrError } from '../errors.js';
+import { ExitCode } from '../../types.js';
+import { eventSpec, kindOf } from './kinds/registry.js';
+import { machineNameOf } from '../peer/names.js';
+import { settleObjectWaits } from '../canvas/waits.js';
+import { RECEIVERS } from './receivers.js';
+import { DEFAULT_LISTEN } from './types.js';
+import { afterCommit } from '../canvas/db.js';
+/** The level `ev` publishes at: the declared level when none is supplied; a supplied level
+ *  must equal it or be one of the event's declared `levels`. Throws `unknown_event` for an
+ *  event the object's kind does not declare, `invalid_level` for any other level. */
+export function resolveLevel(ev, spec) {
+    if (ev.level === undefined || ev.level === spec.level || spec.levels?.includes(ev.level))
+        return ev.level ?? spec.level;
+    const allowed = [spec.level, ...(spec.levels ?? [])].filter((l, i, all) => all.indexOf(l) === i).sort((a, b) => a - b);
+    throw new CrtrError('invalid_level', `${ev.object.type} ${ev.event} publishes at level ${allowed.join(', ')}, not ${ev.level}`, ExitCode.USAGE, { kind: ev.object.type, event: ev.event, level: ev.level, allowed });
+}
+/** NATS-style match over dot-separated event names: `*` is one part, `>` the rest (at least one part). */
+export function matchSubject(pattern, event) {
+    const p = pattern.split('.');
+    const e = event.split('.');
+    for (let i = 0; i < p.length; i++) {
+        if (p[i] === '>')
+            return i === p.length - 1 && e.length > i;
+        if (i >= e.length)
+            return false;
+        if (p[i] !== '*' && p[i] !== e[i])
+            return false;
+    }
+    return p.length === e.length;
+}
+const STRENGTH = { 'next-turn': 1, 'after-turn': 2, steer: 3, interrupt: 4 };
+/** Per config, the delivery of the highest threshold the level reaches; across configs, the
+ *  strongest. Null when the level is below every threshold of every config. */
+export function resolveDelivery(configs, level) {
+    let best = null;
+    for (const config of configs) {
+        let hit = null;
+        for (const entry of config)
+            if (entry.threshold <= level && (!hit || entry.threshold > hit.threshold))
+                hit = entry;
+        if (hit && (!best || STRENGTH[hit.delivery] > STRENGTH[best]))
+            best = hit.delivery;
+    }
+    return best;
+}
+/** A subscription's own config, else the watcher's `objects.listen_json`, else the global default. */
+export async function listenConfigFor(db, subscription, watcher) {
+    if (subscription.config)
+        return subscription.config;
+    const row = await db.prepare('SELECT listen_json FROM objects WHERE id = ?').get(watcher.id);
+    return row?.listen_json ? configFromJson(row.listen_json) : DEFAULT_LISTEN;
+}
+function inboxKind(ev, spec) {
+    return spec.inboxKind ?? (ev.level >= 7 ? 'urgent' : 'update');
+}
+/** The handle `resolveName` reads an owner by: a node's id, else its name — typed
+ *  (`<type>:<name>`) when another owner type shares that name. */
+async function ownerHandleOf(db, owner) {
+    if (owner.type === 'node')
+        return owner.id;
+    const shared = await db.prepare(`SELECT 1 FROM objects WHERE type IN ('person','app','repo','profile')
+    AND name = ? AND id != ? LIMIT 1`).get(owner.name, owner.id);
+    return shared ? `${owner.type}:${owner.name}` : owner.name;
+}
+/** What a push carries: the object's identity, the actor, level, attributes and pointer — never content.
+ *  `owner` is the owner's object id; `owner_handle` is the readable handle notifications name it by. */
+async function pushFields(db, ev, attrs) {
+    const ownerRow = ev.object.owner === null ? null : await db.prepare('SELECT * FROM objects WHERE id = ?').get(ev.object.owner);
+    const owner = ownerRow?.id ?? null;
+    const owner_handle = ownerRow ? await ownerHandleOf(db, ownerRow) : null;
+    // A node's owner is its profile, so its app (`nodes.app`) travels beside it.
+    const appRow = ev.object.type === 'node'
+        ? await db.prepare(`SELECT i.external_id FROM nodes n JOIN identities i ON i.object = n.app AND i.scheme = 'app' WHERE n.node_id = ?`).get(ev.object.id)
+        : undefined;
+    return {
+        event: ev.event, level: ev.level,
+        object: { id: ev.object.id, type: ev.object.type, kind: ev.object.kind, owner, owner_handle, ...(appRow ? { app: appRow.external_id } : {}), name: ev.object.name,
+            ...(ev.object.home_machine ? { machine: machineNameOf(ev.object.home_machine), machine_id: ev.object.home_machine } : {}) },
+        actor: ev.actor?.id ?? null,
+        ...(ev.actor?.home_machine ? { actor_machine: machineNameOf(ev.actor.home_machine), actor_machine_id: ev.actor.home_machine } : {}), attrs, ...(ev.pointer === undefined ? {} : { pointer: ev.pointer }),
+    };
+}
+async function messageInput(db, ev, spec, attrs) {
+    const push = await pushFields(db, ev, attrs);
+    const carriesBody = ev.messageBody !== undefined && spec.carriesBody === true;
+    const bodyJson = carriesBody
+        ? (typeof ev.messageBody === 'object' && ev.messageBody !== null && !Array.isArray(ev.messageBody)
+            ? { ...ev.messageBody, push } : { body: ev.messageBody, push })
+        : { push };
+    // A report's body lives in its report document: the message points at it (`bodyRef`) instead of inlining it.
+    const body = carriesBody ? ev.messageBody : null;
+    const report = body?.bodyRef === undefined ? null : body;
+    return {
+        kind: inboxKind(ev, spec),
+        label: report?.label ?? (typeof body?.label === 'string' ? body.label : ev.object.type.includes('.') && typeof ev.messageBody?.summary === 'string'
+            ? ev.messageBody.summary.split('\n')[0] : `${ev.event} ${ev.object.type} ${ev.object.name}`),
+        ...(report?.bodyRef === undefined ? {} : { bodyRef: report.bodyRef }),
+        ...(report?.disposition === undefined ? {} : { disposition: report.disposition }),
+        senderNodeId: ev.actor?.type === 'node' ? ev.actor.id : null,
+        // A sender that is a stub lives on another machine: its name says which.
+        senderName: ev.actor === null || ev.actor === undefined ? null : ev.actor.home_machine ? `${ev.actor.name} on ${machineNameOf(ev.actor.home_machine)}` : ev.actor.name,
+        bodyJson,
+    };
+}
+/** Supersede (`spec.supersedes`): each destination's pending deliveries of the same
+ *  event on the same object are deleted. A receiver kind may fence its claimed delivery if
+ *  that in-flight execution is replaceable. The replacement carries `spec.merge(prior, ev)` —
+ *  prior being the attrs of the latest superseded message, null when there is none — or, with no
+ *  merge, the newer event's attrs. Destinations are grouped by the message they superseded, so
+ *  each group shares one replacement message. Messages left with no delivery are deleted.
+ *  The core selects matches by delivery destination and the message's event and object.
+ *  An event that does not supersede is one group with its own attrs. */
+export async function supersede(db, ev, spec, destinations, idOf) {
+    if (!spec.supersedes)
+        return [{ attrs: ev.attrs, destinations: [...destinations] }];
+    const pendingOf = db.prepare(`SELECT d.delivery_id, d.message_id, d.state, m.body_json FROM deliveries d
+    JOIN messages m ON m.message_id = d.message_id
+    WHERE d.destination_id = ? AND d.state IN ('pending', 'handed_off')
+      AND d.canceled_at IS NULL AND m.event = ? AND m.object_id = ?
+    ORDER BY m.seq`);
+    const deleteDelivery = db.prepare('DELETE FROM deliveries WHERE delivery_id = ?');
+    const destinationKind = db.prepare('SELECT * FROM objects WHERE id = ?');
+    const groups = new Map();
+    const priorMessages = new Set();
+    for (const destination of destinations) {
+        const id = idOf(destination);
+        const object = await destinationKind.get(id);
+        const kind = object === undefined ? undefined : await kindOf(db, object.type);
+        const pending = await pendingOf.all(id, ev.event, ev.object.id);
+        const replaced = new Set();
+        for (const p of pending) {
+            if (p.state === 'handed_off') {
+                if (await kind?.supersedeClaimed?.(db, p.delivery_id))
+                    replaced.add(p.delivery_id);
+            }
+            else {
+                await deleteDelivery.run(p.delivery_id);
+                priorMessages.add(p.message_id);
+            }
+        }
+        const latest = pending.filter((p) => p.state === 'pending' || replaced.has(p.delivery_id)).at(-1);
+        const key = latest?.message_id ?? null;
+        const group = groups.get(key) ?? {
+            prior: latest?.body_json ? JSON.parse(latest.body_json).push?.attrs ?? null : null,
+            destinations: [],
+        };
+        group.destinations.push(destination);
+        groups.set(key, group);
+    }
+    const orphan = db.prepare('DELETE FROM messages WHERE message_id = ? AND NOT EXISTS (SELECT 1 FROM deliveries WHERE message_id = ?)');
+    for (const id of priorMessages)
+        await orphan.run(id, id);
+    return [...groups.values()].map((g) => ({ attrs: spec.merge ? spec.merge(g.prior, ev) : ev.attrs, destinations: g.destinations }));
+}
+/** Whether the watch of `object` by `watcher` that app `linkApp` made through `link` still authorizes delivery: the app may edit the object's owner and, when its scopes are known, hold the link scope for the watcher. It grants delivery of this one object's events only; nothing about reading it. The scope is
+ *  rechecked against the app's current scopes, except for a stub of a remote object, whose home machine already checked it. */
+async function linkDelivers(db, object, watcher, linkApp, lookups) {
+    const app = await getById(db, linkApp);
+    if (app === null || app.type !== 'app')
+        return false;
+    const remote = await db.prepare('SELECT 1 FROM peer_stubs WHERE object = ?').get(object.id) !== undefined;
+    const scopes = remote ? null : await appScopesNow(db, app, lookups);
+    if (!remote && scopes === null)
+        return false;
+    if (object.owner === null)
+        return false;
+    const ev = await resolveReader(db, { class: 'app', app, scopes: scopes ?? [] });
+    return (object.owner === app.id || await check(db, ev, 'edit', object.owner)) && (scopes === null || await check(db, ev, 'read', watcher.id, { verb: 'link' }));
+}
+/** Whether the object lives in a repo space: the last owner on its chain is a repo. */
+async function inRepoSpace(db, object) {
+    const row = await db.prepare(`WITH RECURSIVE chain(id, depth) AS (
+      SELECT owner, 1 FROM objects WHERE id = ? AND owner IS NOT NULL
+      UNION ALL
+      SELECT o.owner, c.depth + 1 FROM objects o JOIN chain c ON o.id = c.id WHERE o.owner IS NOT NULL
+    ) SELECT o.type FROM chain c JOIN objects o ON o.id = c.id ORDER BY c.depth DESC LIMIT 1`).get(object.id);
+    return (row?.type ?? object.type) === 'repo';
+}
+/**
+ * Validate the event against its object's kind (`resolveLevel`), then push it to every watcher of
+ * the object itself whose subscriptions receive it — a watch on an owner hears that owner's own
+ * events, not those of the objects it owns — inside the caller's write transaction. Candidates are
+ * the watchers whose `objects.reception` admits the event: a `durable` event reaches reception ≥ 1
+ * (a done node too), any other only reception 2. The actor is never pushed its own act, and access
+ * is re-checked per watcher. Writes one `messages` row, only when a delivery results, and hands
+ * each receiver (`receivers.ts`) its destinations. `reposFn` resolves a watcher's repos when the
+ * object lives in a repo space.
+ */
+export const HOP_LIMIT = 8;
+export class HopLimitError extends CrtrError {
+    constructor(depth) { super('hop_limit', `event depth ${depth} exceeds ${HOP_LIMIT}`, ExitCode.GENERAL, { depth, limit: HOP_LIMIT }); }
+}
+export async function publish(db, input, reposFn = async () => []) {
+    const spec = await eventSpec(db, input.object.type, input.event);
+    const ev = { ...input, level: resolveLevel(input, spec) };
+    // The graph's publication is the single source for the local browser stream,
+    // including edits by nodes and package reconciliation (not just browser saves).
+    if (ev.object.type === 'document' && (ev.event === 'edited' || ev.event === 'deleted')) {
+        afterCommit(() => documentEvents.emit(ev.object.id, ev.event));
+    }
+    // Depth follows only a cause the publisher names (`--cause`, CRTR_CAUSE_EVENT in a receiver). A node's
+    // own command is a new decision, so it starts a fresh chain instead of inheriting its wake mail's 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, { cause });
+    const depth = parent === null ? 0 : parent.depth + 1;
+    if (depth > HOP_LIMIT)
+        throw new HopLimitError(depth);
+    // The event the kind declares as ending a wait settles every node's live wait on this object, delivered or not;
+    // so does deletion, since a deleted object publishes nothing more.
+    if (spec.endsWait === true || ev.event === 'deleted')
+        await settleObjectWaits(db, ev.object.id);
+    const columns = `w.watcher, o.id AS watcher_id, o.type AS watcher_type, o.reception, s.pattern, s.filter_json,
+    COALESCE(s.config_json, o.listen_json) AS config_json, w.link_app`;
+    // Durable node events must reach done watchers as pending wake=0 deliveries; reception,
+    // not terminal/finalized status, controls the node receiver's wake decision.
+    // Non-durable events start from fully receiving objects (partial index `objects_receiving`).
+    const rows = await db.prepareUncached(spec.durable
+        ? `SELECT ${columns} FROM watches w JOIN watch_subscriptions s ON s.watch = w.watch_id
+        JOIN objects o ON o.id = w.watcher WHERE w.object = ? AND w.watcher != ? AND o.reception >= 1`
+        : `SELECT ${columns} FROM objects o JOIN watches w ON w.watcher = o.id JOIN watch_subscriptions s ON s.watch = w.watch_id
+        WHERE o.reception = 2 AND w.object = ? AND w.watcher != ?`).all(ev.object.id, ev.actor?.id ?? '');
+    if (rows.length === 0)
+        return { delivered: 0, message_id: null, depth };
+    const subject = {
+        event: ev.event, level: ev.level, id: ev.object.id, type: ev.object.type, kind: ev.object.kind,
+        actor: ev.actor?.id ?? null, ...ev.attrs,
+    };
+    const byWatcher = new Map();
+    for (const row of rows) {
+        if (ev.onlyWatchers !== undefined && !ev.onlyWatchers.includes(row.watcher_id))
+            continue;
+        if (!matchSubject(row.pattern, ev.event))
+            continue;
+        if (row.filter_json !== null && !evalCondition(JSON.parse(row.filter_json), subject))
+            continue;
+        const entry = byWatcher.get(row.watcher) ?? { id: row.watcher_id, type: row.watcher_type, reception: row.reception, configs: [], configured: false, linkApp: row.link_app };
+        entry.configs.push(row.config_json ? configFromJson(row.config_json) : DEFAULT_LISTEN);
+        entry.configured ||= row.config_json !== null;
+        byWatcher.set(row.watcher, entry);
+    }
+    const inRepo = await inRepoSpace(db, ev.object);
+    const noRepos = async () => [];
+    // A stub is owned by the local object of its remote owner (`ensureStub`), so the same space rules answer for it as for a local
+    // object: this machine's CURRENT mirrored grant of the watcher must still hold the scope that reading that owner's objects needs
+    // (`crtr:objects:read:<app>` for a node of another app). The home machine authorized the event as well when it sent it.
+    const lookups = publishLookups(db);
+    const destinations = [];
+    for (const watcher of byWatcher.values()) {
+        const watcherObject = await db.prepare('SELECT * FROM objects WHERE id = ?').get(watcher.id);
+        const kind = await kindOf(db, watcherObject.type);
+        const receiver = kind.receiverFor ? await kind.receiverFor(db, watcherObject) : kind.receiver;
+        if (receiver === undefined)
+            continue;
+        // A stub of a node on another machine carries no listening config of its own (the node's lives on its home machine), so unless the watch
+        // set one, every level is forwarded and the home machine's ingest applies that node's config. The delivery is unused by the peer receiver.
+        const delivery = receiver === 'peer' && !watcher.configured ? 'next-turn' : resolveDelivery(watcher.configs, ev.level);
+        if (delivery === null)
+            continue;
+        const reader = await readerForObject(db, watcherObject, inRepo ? reposFn : noRepos, lookups);
+        // Revocation removes the node's grant, not its app/repo ownership. Do not
+        // let those ownership paths deliver events to a revoked node.
+        if (reader.scopes === null && (reader.class === 'node' || reader.owner.type !== 'person'))
+            continue;
+        // A watch an app made through `link` delivers its own object's events without giving the watcher any read access to the object.
+        const readable = await check(db, reader, 'read', ev.object.id);
+        const linked = watcher.linkApp !== null && !readable && await linkDelivers(db, ev.object, watcherObject, watcher.linkApp, lookups);
+        if (!linked && !readable)
+            continue;
+        destinations.push({ id: watcher.id, reception: watcher.reception, delivery, receiver, ...(linked ? { linked } : {}) });
+    }
+    if (destinations.length === 0)
+        return { delivered: 0, message_id: null, depth };
+    let firstMessageId = null;
+    for (const group of await supersede(db, ev, spec, destinations, (d) => d.id)) {
+        const byReceiver = new Map();
+        for (const d of group.destinations)
+            byReceiver.set(d.receiver, [...(byReceiver.get(d.receiver) ?? []), d]);
+        const input = await messageInput(db, ev, spec, group.attrs);
+        const bodyOwner = [...byReceiver].map(([name, ds]) => RECEIVERS[name].bodyOwner(ds)).find((o) => o !== null) ?? null;
+        const prepared = finalizeNodeMail({ ...input, urgency: 'normal' }, bodyOwner);
+        const messageId = await insertMessage(db, {
+            operationId: prepared.operationId, createdAt: prepared.createdAt,
+            senderNodeId: input.senderNodeId, senderName: input.senderName, kind: input.kind, label: input.label,
+            bodyRef: prepared.bodyRef, bodyJson: prepared.bodyJson, disposition: input.disposition ?? null,
+            event: { event: ev.event, objectId: ev.object.id, level: ev.level, actorId: ev.actor?.id ?? null },
+            causeMessageId: cause, depth,
+        });
+        firstMessageId ??= messageId;
+        for (const [name, ds] of byReceiver) {
+            await RECEIVERS[name].enqueue(db, { messageId, event: ev.event, level: ev.level, senderNodeId: input.senderNodeId, elevatesTier: spec.elevatesTier === true,
+                ...(ev.idempotencyKey === undefined ? {} : { idempotencyKey: ev.idempotencyKey }) }, ds);
+        }
+    }
+    return { delivered: destinations.length, message_id: firstMessageId, depth };
+}

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

@@ -0,0 +1,53 @@
+/** The exposure ledger: what each node's loaded context already holds, per
+ *  channel (`system` = rebuilt system prompt, `transcript` = conversation), in
+ *  `exposures` and `context_sessions`. Rows cascade with the node. Callers
+ *  load, mutate in memory, and `saveLedger` inside their own transaction. */
+import type { RuleSpec } from './types.js';
+import type { CanvasDb } from '../canvas/db.js';
+export type ExposureLevel = RuleSpec['deliver'];
+export type Channel = 'system' | 'transcript';
+export interface Held {
+    system?: ExposureLevel;
+    transcript?: ExposureLevel;
+    headsKey: string | null;
+    contentHash: string | null;
+}
+export type Listed = {
+    system?: ExposureLevel;
+    transcript?: ExposureLevel;
+};
+export interface Ledger {
+    node: string;
+    preferenceSnapshot: string | null;
+    objects: Map<string, Held>;
+    /** key = `<owner object id>/<prefix>` */
+    listed: Map<string, Listed>;
+}
+export interface Exposed {
+    object: string;
+    headsKey: string | null;
+    contentHash: string | null;
+}
+export declare function loadLedger(db: CanvasDb, node: string): Promise<Ledger>;
+/** Write what changed since `loadLedger` (a ledger never loaded is written whole). */
+export declare function saveLedger(db: CanvasDb, ledger: Ledger): Promise<void>;
+/** Whether the node has a ledger at all (a context session or any exposure). */
+export declare function hasLedger(db: CanvasDb, node: string): Promise<boolean>;
+/** End the node's context session: nothing is held any more. */
+export declare function clearLedger(db: CanvasDb, node: string): Promise<void>;
+/** 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 declare function forkLedger(db: CanvasDb, source: string, fork: string): Promise<void>;
+/** 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 declare function heldAtOrAbove(ledger: Ledger, exposed: Exposed, level: ExposureLevel, channel?: Channel): boolean;
+/** Record that `channel` now holds the object at `level`; never lowers a level of the same revision. */
+export declare function hold(ledger: Ledger, channel: Channel, exposed: Exposed, level: ExposureLevel): void;
+export declare function listedAtOrAbove(ledger: Ledger, key: string, level: ExposureLevel, channel?: Channel): boolean;
+export declare function holdListing(ledger: Ledger, channel: Channel, key: string, level: ExposureLevel): void;
+/** Forget the transcript's copy of the object and of every held object with the
+ *  same body (compaction dropped it); system holdings stay. */
+export declare function demoteTranscript(ledger: Ledger, object: string): void;
+/** The byte-stable preference block: the first render is kept for the session. */
+export declare function freezePreferences(ledger: Ledger, rendered: string): string;
+export declare function hasTranscript(ledger: Ledger): boolean;