@north-light/api 0.3.580 → 0.3.588

package/dist/core/substrate/delivery/deliver.d.ts

@@ -0,0 +1,71 @@
+import { type ReposFn } from '../../graph/reader.js';
+import type { ObjectRow, Reader } from '../../graph/types.js';
+import type { DeliveryActivity, DeliveryCommandDTO } from '../../../api/dto/delivery.js';
+import type { RefMeta } from '../../runtime/broker-protocol.js';
+import type { NodeConfigSubject } from '../subject-fields.js';
+import { type DeliveryPlan } from './plan.js';
+import { type DeliveredDoc } from './render-event.js';
+import type { CanvasDb } from '../../canvas/db.js';
+export interface DeliveryRequestInput {
+    activity: DeliveryActivity;
+    subject?: string;
+    inherited?: boolean;
+}
+export interface DeliveryResult {
+    content: string;
+    inherited?: boolean;
+    commands?: DeliveryCommandDTO[];
+    blocks?: string[];
+    execution_body?: string;
+    refs?: RefMeta[];
+    names?: string[];
+}
+/** Record the content deliveries: a `deliver` watch at the delivered heads, a `read` event each,
+ *  and a `loaded` row in the analytics memory log (a full body that entered the context). */
+export declare function recordContentDelivery(db: CanvasDb, reader: Reader, delivered: readonly DeliveredDoc[], reposFn?: ReposFn): Promise<void>;
+/** Activities only a dry run performs: a live node's workspace-open arrives
+ *  inside its boot, and a document read goes through the read route. */
+export declare const DRY_RUN_ONLY: readonly DeliveryActivity[];
+/** One delivery for a live node. Call inside `withCanvasWrite`. */
+export declare function deliver(db: CanvasDb, reader: Reader, req: DeliveryRequestInput): Promise<DeliveryResult>;
+/** A node that does not exist, described by what delivery reads of one:
+ *  the directory it would work in, its profile and app, and the fields rule
+ *  `if` conditions see. Every field but `cwd` has a default. */
+export interface HypotheticalNode {
+    cwd: string;
+    /** Profile id or name; defaults to the profile pinned to `cwd`. */
+    profile?: string | null;
+    /** Defaults to `app:terminal`. */
+    grantee?: string;
+    kind?: string;
+    mode?: NodeConfigSubject['mode'];
+    lifecycle?: NodeConfigSubject['lifecycle'];
+    hasManager?: boolean;
+    depth?: number;
+}
+/** Fill a hypothetical node's unset fields from a live node, so `--node` with
+ *  `--cwd` or `--profile` starts from that node and dials away from it. */
+export declare function hypotheticalFrom(nodeId: string, h: Partial<HypotheticalNode>): Promise<HypotheticalNode>;
+/** The reader and gate subject of a node that does not exist. Resolving its
+ *  app, profile and repos may create their owner objects, so call it only
+ *  inside a transaction that rolls back. */
+export declare function hypotheticalReader(db: CanvasDb, h: HypotheticalNode): Promise<{
+    reader: Extract<Reader, {
+        class: 'node';
+    }>;
+    subject: NodeConfigSubject;
+}>;
+/** A dry run for inspection: render against an empty ledger and record nothing.
+ *  `subjectOverride` replaces fields of the gate subject — the node's own, or
+ *  `baseSubject` for a hypothetical reader. */
+export declare function inspect(db: CanvasDb, reader: Reader, req: DeliveryRequestInput, subjectOverride?: Partial<NodeConfigSubject>, baseSubject?: NodeConfigSubject): Promise<{
+    result: DeliveryResult;
+    plan: DeliveryPlan | null;
+}>;
+/** Watched documents with a revision created after `since` that the node did not author (D8). */
+export declare function changedWhileDone(db: CanvasDb, node: ObjectRow, since: string): Promise<Array<{
+    doc: ObjectRow;
+    from: number | null;
+    to: number;
+    authors: string[];
+}>>;

package/dist/core/substrate/delivery/deliver.js

@@ -0,0 +1,333 @@
+/** The one-phase delivery transaction behind `POST /v1/nodes/:id/delivery`:
+ *  load the node's ledger, render the activity, record a `deliver` watch and a
+ *  `read` event for every document delivered at content, save the ledger. The
+ *  caller runs it inside one `withCanvasWrite`, so exposures, watches and
+ *  events land together or not at all. */
+import { dirname } from 'node:path';
+import { clearLedger, demoteTranscript, freezePreferences, loadLedger, saveLedger } from '../../graph/exposures.js';
+import { recordWatch } from '../../graph/watches.js';
+import { publish } from '../../graph/events.js';
+import { viewOf } from '../../graph/names.js';
+import { checkoutsForCwd } from '../../graph/repo-sync/repos.js';
+import { liveLookups, profileObject, viewRepos } from '../../graph/reader.js';
+import { ownerForGrantee } from '../../graph/objects.js';
+import { resolveName } from '../../graph/names.js';
+import { SCOPE_VOCABULARY } from '../../scopes.js';
+import { getNode } from '../../canvas/index.js';
+import { recordMemoryReadsIn } from '../../canvas/memory-reads.js';
+import { lookupProfile } from '../../profiles/manifest.js';
+import { getDefaultProfileId } from '../../profiles/default-binding.js';
+import { effectiveScopes, profileNameFor, scopeForCwd } from '../subject-fields.js';
+import { spineDepth } from '../subject.js';
+import { appForNode } from '../../canvas/node-agent-paths.js';
+import { interpolateNodePaths } from '../../canvas/paths.js';
+import { readableProjectForScopes } from '../../spaces/permissions.js';
+import { ApiError } from '../../../api/errors.js';
+import { buildContextBearings } from '../../runtime/bearings.js';
+import { deliveryDocOf, listingCorpus, loadCorpus, nodeSubject, primeBodies } from './corpus.js';
+import { listingPrefixes } from './listings.js';
+import { planDelivery } from './plan.js';
+import { renderEvent, renderExplicitRead } from './render-event.js';
+import { renderConfigDelta, renderKnowledge, renderPreferences, renderWorkspaceOpen } from './render-boot.js';
+import { mapAsync } from '../../async-array.js';
+function nodeOf(reader) {
+    if (reader.class !== 'node')
+        throw new Error(`delivery needs a node reader, got ${reader.class}`);
+    return reader;
+}
+/** The id a hypothetical reader's synthetic node carries: no `objects` row has it. */
+const HYPOTHETICAL_ID = 'hypothetical';
+function isHypothetical(reader) {
+    return reader.node.id === HYPOTHETICAL_ID;
+}
+/** The grantee of the reader's app: a live node's row, or the app identity of a hypothetical one. */
+async function granteeOf(db, reader) {
+    if (!isHypothetical(reader))
+        return await appForNode(reader.node.id);
+    const row = await db.prepare('SELECT external_id FROM identities WHERE object = ?').get(reader.app.id);
+    if (!row)
+        throw new Error(`app object ${reader.app.id} has no identity`);
+    return row.external_id;
+}
+/** Record the content deliveries: a `deliver` watch at the delivered heads, a `read` event each,
+ *  and a `loaded` row in the analytics memory log (a full body that entered the context). */
+export async function recordContentDelivery(db, reader, delivered, reposFn = async (cwd) => await checkoutsForCwd(db, cwd)) {
+    const node = nodeOf(reader).node;
+    const seen = new Set();
+    const at = new Date().toISOString();
+    const loaded = [];
+    for (const { doc, level } of delivered) {
+        if (level !== 'content' || seen.has(doc.object.id))
+            continue;
+        seen.add(doc.object.id);
+        await recordWatch(db, node, doc.object, 'deliver', { readHeadsKey: doc.headsKey });
+        await publish(db, { event: 'read', object: doc.object, actor: node, attrs: {} }, reposFn);
+        loaded.push({ name: doc.name, scope: doc.ownerHandle, at, type: 'loaded' });
+    }
+    if (!isHypothetical(nodeOf(reader)))
+        await recordMemoryReadsIn(db, node.id, loaded);
+}
+/** The file-read reader: the node's own view plus the repos enclosing the read file, so their rules apply. */
+async function fileReadReader(db, reader, file) {
+    const extra = (await checkoutsForCwd(db, dirname(file))).filter((c) => !reader.repos.some((own) => own.id === c.repo.id));
+    return extra.length === 0 ? reader
+        : { ...reader, repos: [...reader.repos, ...extra.map((c) => c.repo)], checkouts: [...reader.checkouts, ...extra] };
+}
+async function assertReadableFile(db, reader, file) {
+    const grantee = await granteeOf(db, reader);
+    const ok = file.startsWith('/') && ((process.platform !== 'linux' && grantee === 'app:terminal')
+        || readableProjectForScopes(file, grantee, reader.scopes ?? [], null));
+    if (!ok)
+        throw new ApiError(403, 'scope_missing', 'read file is outside the run mounts');
+}
+async function slashCommands(ctx) {
+    const reader = nodeOf(ctx.reader);
+    const node = reader.node;
+    const grantee = await granteeOf(ctx.db, reader);
+    const docs = await loadCorpus(ctx.db, ctx.reader, ['slash-command']);
+    await primeBodies(ctx.db, docs);
+    const commands = await mapAsync(docs, async (d) => {
+        const body = await d.body();
+        return { name: d.displayName, command_name: d.displayName, description: d.preview, canonical_body: body, execution_body: interpolateNodePaths(body, node.id, grantee) };
+    });
+    return { docs, commands };
+}
+function scopeOf(doc) {
+    if (doc.shipped)
+        return 'builtin';
+    switch (doc.owner.type) {
+        case 'node': return 'node';
+        case 'repo': return 'project';
+        case 'profile': return 'profile';
+        default: return 'user';
+    }
+}
+async function composerNames(db, reader) {
+    const refs = [];
+    const names = new Set();
+    for (const owner of await viewOf(db, reader)) {
+        const members = await listingCorpus(db, reader, owner);
+        for (const d of members) {
+            refs.push({ name: d.displayName, kind: d.kind, scope: scopeOf(d), shortForm: d.preview, gatewayVisible: !d.shipped });
+            names.add(d.displayName);
+            const prefixOwner = d.displayName === d.name ? '' : `${d.ownerHandle}/`;
+            for (const prefix of listingPrefixes(members, d.name))
+                names.add(`${prefixOwner}${prefix}`);
+        }
+    }
+    return { refs, names: [...names] };
+}
+/** Render one activity against `ctx.ledger` (mutating it); records nothing. */
+async function render(ctx, req) {
+    const reader = nodeOf(ctx.reader);
+    const { db, ledger } = ctx;
+    const requireSubject = () => {
+        if (typeof req.subject !== 'string' || req.subject === '')
+            throw new ApiError(400, 'usage', `delivery activity ${req.activity} requires a subject`);
+        return req.subject;
+    };
+    switch (req.activity) {
+        case 'boot': {
+            if (req.inherited === true) {
+                for (const [key, held] of ledger.objects) {
+                    if (held.transcript === undefined)
+                        ledger.objects.delete(key);
+                    else {
+                        const { system: _system, ...rest } = held;
+                        ledger.objects.set(key, rest);
+                    }
+                }
+                for (const [key, listed] of ledger.listed) {
+                    if (listed.transcript === undefined)
+                        ledger.listed.delete(key);
+                    else
+                        ledger.listed.set(key, { transcript: listed.transcript });
+                }
+                ledger.preferenceSnapshot = null;
+                return { result: { content: '', inherited: true }, delivered: [] };
+            }
+            const bearings = isHypothetical(reader) ? await hypotheticalBearings(ctx) : await buildContextBearings(reader.node.id, ctx);
+            const prefs = await renderPreferences({ ...ctx, channel: 'system' });
+            freezePreferences(ledger, prefs.content);
+            return { result: { content: bearings.content }, delivered: [...bearings.delivered, ...prefs.delivered] };
+        }
+        case 'system-prompt': {
+            if (ledger.preferenceSnapshot !== null)
+                return { result: { content: ledger.preferenceSnapshot }, delivered: [] };
+            const prefs = await renderPreferences({ ...ctx, channel: 'system' });
+            return { result: { content: freezePreferences(ledger, prefs.content) }, delivered: prefs.delivered };
+        }
+        case 'compact': {
+            for (const doc of await loadCorpus(db, reader, ['pre-command']))
+                demoteTranscript(ledger, doc.object.id);
+            return { result: { content: '' }, delivered: [] };
+        }
+        case 'persona': {
+            const r = await renderConfigDelta(ctx);
+            return { result: { content: r.content }, delivered: r.delivered };
+        }
+        case 'file-read': {
+            const file = requireSubject();
+            await assertReadableFile(db, reader, file);
+            const fileReader = await fileReadReader(db, reader, file);
+            const fileCtx = { ...ctx, reader: fileReader };
+            const r = await renderEvent(fileCtx, 'file-read', { absoluteFile: file }, await loadCorpus(db, fileReader, ['file-read']));
+            return { result: { content: r.content }, delivered: r.delivered };
+        }
+        case 'command':
+        case 'pre-command': {
+            const r = await renderEvent(ctx, req.activity, { command: requireSubject() });
+            return { result: { content: r.content }, delivered: r.delivered };
+        }
+        case 'slash-command': {
+            const { docs, commands } = await slashCommands(ctx);
+            if (req.subject === undefined || req.subject === '')
+                return { result: { content: '', commands }, delivered: [] };
+            const i = docs.findIndex((d) => d.displayName === req.subject || d.name === req.subject);
+            if (i < 0)
+                throw new ApiError(404, 'not_found', `no slash command named ${req.subject}`);
+            const doc = docs[i];
+            const read = await renderExplicitRead(ctx, doc, true);
+            return {
+                result: { content: '', execution_body: commands[i].execution_body, blocks: read.attachments === '' ? [] : [read.attachments] },
+                delivered: [{ doc, level: 'content' }, ...read.delivered],
+            };
+        }
+        case 'workspace-open': {
+            const r = await renderWorkspaceOpen(ctx);
+            return { result: { content: r.content }, delivered: r.delivered };
+        }
+        case 'document-read': {
+            const doc = await readDocument(db, reader, requireSubject());
+            const read = await renderExplicitRead(ctx, await deliveryDocOf(db, reader, doc), true);
+            return { result: { content: read.attachments }, delivered: read.delivered };
+        }
+        case 'names':
+            return { result: { content: '', ...await composerNames(db, reader) }, delivered: [] };
+        default:
+            throw new ApiError(400, 'usage', `unknown delivery activity ${String(req.activity)}`);
+    }
+}
+/** A hypothetical node has no bearings of its own: its boot content is the
+ *  knowledge catalog and the workspace-open documents. */
+async function hypotheticalBearings(ctx) {
+    const knowledge = await renderKnowledge(ctx);
+    const workspace = await renderWorkspaceOpen(ctx);
+    return { content: [knowledge.content, workspace.content].filter((s) => s !== '').join('\n'), delivered: [...knowledge.delivered, ...workspace.delivered] };
+}
+/** The document a `document-read` dry run reads, resolved as the reader names it. */
+async function readDocument(db, reader, raw) {
+    const hit = await resolveName(db, reader, raw);
+    if ('object' in hit && hit.object.type === 'document')
+        return hit.object;
+    if ('ambiguous' in hit)
+        throw new ApiError(409, 'ambiguous', `${raw} names ${hit.ambiguous.length} documents; name one as <type>:<owner>/<name>`);
+    throw new ApiError(404, 'not_found', `no document ${raw} the reader can read`);
+}
+/** Activities only a dry run performs: a live node's workspace-open arrives
+ *  inside its boot, and a document read goes through the read route. */
+export const DRY_RUN_ONLY = ['workspace-open', 'document-read'];
+/** One delivery for a live node. Call inside `withCanvasWrite`. */
+export async function deliver(db, reader, req) {
+    if (DRY_RUN_ONLY.includes(req.activity))
+        throw new ApiError(400, 'usage', `delivery activity ${req.activity} is available to a dry run only`);
+    const node = nodeOf(reader).node;
+    if (req.activity === 'boot' && req.inherited !== true)
+        await clearLedger(db, node.id);
+    const ledger = await loadLedger(db, node.id);
+    const ctx = { db, reader, subject: await nodeSubject(db, reader), ledger, channel: 'transcript' };
+    const { result, delivered } = await render(ctx, req);
+    await recordContentDelivery(db, reader, delivered);
+    await saveLedger(db, ledger);
+    return result;
+}
+const ACTIVITY_ON = {
+    boot: 'boot', 'workspace-open': 'workspace-open', 'file-read': 'file-read', 'document-read': 'document-read',
+    command: 'command', 'pre-command': 'pre-command', 'slash-command': 'slash-command',
+};
+/** Fill a hypothetical node's unset fields from a live node, so `--node` with
+ *  `--cwd` or `--profile` starts from that node and dials away from it. */
+export async function hypotheticalFrom(nodeId, h) {
+    const meta = await getNode(nodeId);
+    if (meta === null)
+        throw new ApiError(404, 'not_found', `no node ${nodeId}`);
+    return {
+        cwd: h.cwd ?? meta.cwd,
+        profile: h.profile !== undefined ? h.profile : meta.profile_id,
+        grantee: h.grantee ?? meta.grantee,
+        kind: h.kind ?? meta.kind,
+        mode: h.mode ?? meta.mode,
+        lifecycle: h.lifecycle ?? meta.lifecycle,
+        hasManager: h.hasManager ?? (meta.parent ?? null) !== null,
+        depth: h.depth ?? await spineDepth(nodeId),
+    };
+}
+function resolveProfileId(raw, cwd) {
+    if (raw === null)
+        return null;
+    if (raw === undefined || raw === '')
+        return getDefaultProfileId(cwd);
+    const hit = lookupProfile(raw);
+    if (hit.kind !== 'resolved') {
+        const message = `no profile ${raw}`;
+        throw new ApiError(404, 'not_found', message, { error: 'not_found', message, next: 'List profile ids and names with `crtr profile list`.' });
+    }
+    return hit.entry.profileId;
+}
+/** The reader and gate subject of a node that does not exist. Resolving its
+ *  app, profile and repos may create their owner objects, so call it only
+ *  inside a transaction that rolls back. */
+export async function hypotheticalReader(db, h) {
+    const app = await ownerForGrantee(db, h.grantee ?? 'app:terminal');
+    const profileId = resolveProfileId(h.profile, h.cwd);
+    const view = await viewRepos(h.cwd, profileId, async (cwd) => await checkoutsForCwd(db, cwd), liveLookups(db));
+    const { repos } = view;
+    const mode = h.mode ?? 'base';
+    const node = {
+        id: HYPOTHETICAL_ID, seq: 0, type: 'node', kind: h.kind ?? 'general', owner: app.id,
+        privacy: 'private', name: 'hypothetical', preview: '', created_at: new Date(0).toISOString(), deleted_at: null,
+    };
+    const reader = {
+        class: 'node', node, app, scopes: [...SCOPE_VOCABULARY], cwd: h.cwd, ...view,
+        profile: profileId === null ? null : await profileObject(db, profileId, app),
+    };
+    const subject = {
+        kind: h.kind ?? 'general', mode, lifecycle: h.lifecycle ?? (mode === 'orchestrator' ? 'resident' : 'terminal'),
+        hasManager: h.hasManager ?? true, cwd: h.cwd, scope: scopeForCwd(h.cwd), orchestration: { depth: h.depth ?? 0 },
+        profile: profileNameFor(profileId), app: h.grantee ?? 'app:terminal', scopes: effectiveScopes(null), repo: [...repos, ...view.projectRepos].map((r) => r.name),
+    };
+    return { reader, subject };
+}
+/** A dry run for inspection: render against an empty ledger and record nothing.
+ *  `subjectOverride` replaces fields of the gate subject — the node's own, or
+ *  `baseSubject` for a hypothetical reader. */
+export async function inspect(db, reader, req, subjectOverride, baseSubject) {
+    const node = nodeOf(reader).node;
+    const ledger = { node: node.id, preferenceSnapshot: null, objects: new Map(), listed: new Map() };
+    const subject = { ...(baseSubject ?? await nodeSubject(db, reader)), ...subjectOverride };
+    const ctx = { db, reader, subject, ledger, channel: 'transcript' };
+    const { result } = await render(ctx, req);
+    const on = ACTIVITY_ON[req.activity];
+    let plan = null;
+    if (on !== undefined) {
+        const payload = req.activity === 'file-read' ? { absoluteFile: req.subject }
+            : req.activity === 'command' || req.activity === 'pre-command' ? { command: req.subject }
+                : req.activity === 'document-read' && req.subject !== undefined ? { doc: await deliveryDocOf(db, reader, await readDocument(db, reader, req.subject)) }
+                    : {};
+        const planReader = req.activity === 'file-read' && req.subject !== undefined ? await fileReadReader(db, nodeOf(reader), req.subject) : reader;
+        plan = await planDelivery(db, subject, planReader, await loadCorpus(db, planReader, [on]), on, payload);
+    }
+    return { result, plan };
+}
+/** Watched documents with a revision created after `since` that the node did not author (D8). */
+export async function changedWhileDone(db, node, since) {
+    const rows = await db.prepare(`SELECT o.*, MAX(r.number) AS to_seq, string_agg(DISTINCT a.id, ',') AS authors
+    FROM watches w JOIN objects o ON o.id = w.object AND o.type = 'document' AND o.deleted_at IS NULL
+    JOIN revisions r ON r.document = o.id LEFT JOIN objects a ON a.id = r.author
+    WHERE w.watcher = ? AND r.created_at > ? AND (r.author IS NULL OR r.author != ?)
+    GROUP BY o.id ORDER BY o.seq`).all(node.id, since, node.id);
+    return (await mapAsync(rows, async ({ to_seq, authors, ...doc }) => {
+        const prior = await db.prepare('SELECT MAX(number) AS seq FROM revisions WHERE document = ? AND created_at <= ?').get(doc.id, since);
+        return { doc: doc, from: prior.seq, to: to_seq, authors: authors === null ? [] : authors.split(',') };
+    }));
+}

package/dist/core/substrate/delivery/listings.d.ts

@@ -0,0 +1,30 @@
+/** Prefix listings for the row-backed delivery engine. Documents of one owner
+ *  form a name-segment tree: prefix `a/b` of `a/b/c` is a listing under that
+ *  owner. A listing renders one line per member — childless documents first,
+ *  then subtrees — and never recurses. Listing identity in the ledger is
+ *  `<owner object id>/<prefix>`. */
+import { type Channel, type Ledger } from '../../graph/exposures.js';
+import type { DeliveryDoc } from './types.js';
+export declare function listingKey(doc: Pick<DeliveryDoc, 'owner'>, prefix: string): string;
+/** Is `prefix` a listing among these names — does some name sit below it? */
+export declare function isPrefix(members: readonly DeliveryDoc[], prefix: string): boolean;
+/** The listings a content delivery of `name` shows, in render order: its own
+ *  prefix when it has members, then each enclosing prefix walking up. Only
+ *  prefixes with members among `members` are returned. */
+export declare function listingPrefixes(members: readonly DeliveryDoc[], name: string): string[];
+/** How the prefix is labelled: bare when the owner's names resolve bare for the reader, else `<ownerHandle>/<prefix>`. */
+export declare function listingLabel(sample: DeliveryDoc, prefix: string): string;
+export interface ListingLines {
+    lines: string[];
+    /** Members whose preview line rendered, now held at preview. */
+    previewed: DeliveryDoc[];
+}
+/** One prefix's lines: `[[name]]: <preview>` per member (bare `[[name]]` with
+ *  no preview). With `filterHeld`, a member the ledger already holds at preview
+ *  or above renders no line (a subtree keeps its bare row). Every preview that
+ *  renders is held in `ledger` on `channel`. */
+export declare function renderListing(members: readonly DeliveryDoc[], prefix: string, ledger: Ledger, channel: Channel, filterHeld: boolean): ListingLines;
+export declare function listingBlock(label: string, lines: readonly string[]): string;
+/** A content delivery's own set: the names under `label` (`dir`, when there
+ *  are any) and the documents it links to (`linked-from`), one line each. */
+export declare function ownSetBlock(label: string, underLines: readonly string[], linkLines: readonly string[]): string;

package/dist/core/substrate/delivery/listings.js

@@ -0,0 +1,75 @@
+/** Prefix listings for the row-backed delivery engine. Documents of one owner
+ *  form a name-segment tree: prefix `a/b` of `a/b/c` is a listing under that
+ *  owner. A listing renders one line per member — childless documents first,
+ *  then subtrees — and never recurses. Listing identity in the ledger is
+ *  `<owner object id>/<prefix>`. */
+import { heldAtOrAbove, hold } from '../../graph/exposures.js';
+function attr(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function listingKey(doc, prefix) {
+    return `${doc.owner.id}/${prefix}`;
+}
+/** Is `prefix` a listing among these names — does some name sit below it? */
+export function isPrefix(members, prefix) {
+    return prefix !== '' && members.some((m) => m.name.startsWith(`${prefix}/`));
+}
+/** The listings a content delivery of `name` shows, in render order: its own
+ *  prefix when it has members, then each enclosing prefix walking up. Only
+ *  prefixes with members among `members` are returned. */
+export function listingPrefixes(members, name) {
+    const segs = name.split('/');
+    const prefixes = segs.map((_, i) => segs.slice(0, segs.length - i).join('/'));
+    return prefixes.filter((p) => isPrefix(members, p));
+}
+/** How the prefix is labelled: bare when the owner's names resolve bare for the reader, else `<ownerHandle>/<prefix>`. */
+export function listingLabel(sample, prefix) {
+    return sample.displayName === sample.name ? prefix : `${sample.ownerHandle}/${prefix}`;
+}
+/** One prefix's lines: `[[name]]: <preview>` per member (bare `[[name]]` with
+ *  no preview). With `filterHeld`, a member the ledger already holds at preview
+ *  or above renders no line (a subtree keeps its bare row). Every preview that
+ *  renders is held in `ledger` on `channel`. */
+export function renderListing(members, prefix, ledger, channel, filterHeld) {
+    const byName = new Map(members.map((m) => [m.name, m]));
+    const children = [...new Set(members.filter((m) => m.name.startsWith(`${prefix}/`))
+            .map((m) => `${prefix}/${m.name.slice(prefix.length + 1).split('/')[0]}`))].sort();
+    const leaves = children.filter((c) => !isPrefix(members, c));
+    const subtrees = children.filter((c) => isPrefix(members, c));
+    const lines = [];
+    const previewed = [];
+    const suffix = (doc) => {
+        if (doc === undefined || doc.unlisted)
+            return null;
+        const exposed = { object: doc.object.id, headsKey: doc.headsKey, contentHash: doc.bodyHash };
+        if (filterHeld && heldAtOrAbove(ledger, exposed, 'preview'))
+            return null;
+        hold(ledger, channel, exposed, 'preview');
+        previewed.push(doc);
+        return doc.preview.trim();
+    };
+    const line = (label, s) => (s === null || s === '' ? `[[${label}]]` : `[[${label}]]: ${s}`);
+    for (const child of leaves) {
+        const doc = byName.get(child);
+        const s = suffix(doc);
+        if (s !== null)
+            lines.push(line(doc.displayName, s));
+    }
+    for (const child of subtrees) {
+        const doc = byName.get(child);
+        const sample = doc ?? members.find((m) => m.name.startsWith(`${child}/`));
+        lines.push(line(doc?.displayName ?? listingLabel(sample, child), suffix(doc)));
+    }
+    return { lines, previewed };
+}
+export function listingBlock(label, lines) {
+    return `<memory-listing dir="${attr(label)}">\n${lines.join('\n')}\n</memory-listing>`;
+}
+/** A content delivery's own set: the names under `label` (`dir`, when there
+ *  are any) and the documents it links to (`linked-from`), one line each. */
+export function ownSetBlock(label, underLines, linkLines) {
+    if (linkLines.length === 0)
+        return listingBlock(label, underLines);
+    const dir = underLines.length > 0 ? `dir="${attr(label)}" ` : '';
+    return `<memory-listing ${dir}linked-from="${attr(label)}">\n${[...underLines, ...linkLines].join('\n')}\n</memory-listing>`;
+}

package/dist/core/substrate/delivery/match.d.ts

@@ -0,0 +1,28 @@
+import type { RuleRow } from '../../graph/rules.js';
+import type { RuleOn } from '../../graph/types.js';
+import type { NodeConfigSubject } from '../subject-fields.js';
+import type { DeliveryDoc } from './types.js';
+/** What an activity exposes for matching. A field the activity needs and lacks matches nothing. */
+export interface MatchPayload {
+    /** `file-read`: the read file, realpathed. */
+    absoluteFile?: string;
+    /** `file-read`: the read file's own frontmatter (empty for a non-markdown file). */
+    readFrontmatter?: Record<string, unknown>;
+    /** `file-read`: checkout root of each repo object (by id) that encloses the read file. */
+    repoRoots?: ReadonlyMap<string, string>;
+    /** `document-read`: the document that was delivered or read. */
+    doc?: DeliveryDoc;
+    /** `command` / `pre-command`: the command string. */
+    command?: string;
+}
+export type GateOutcome = {
+    pass: true;
+} | {
+    pass: false;
+    reason: string;
+};
+/** A rule's `if` against the node's subject. A missing subject cannot satisfy
+ *  an `if`; a predicate that throws excludes only its own rule. */
+export declare function ruleGate(rule: RuleRow, subject: NodeConfigSubject | null): GateOutcome;
+/** Do the rule's constraints fit the activity, without its `if`? */
+export declare function ruleConstraintsFit(rule: RuleRow, carrier: DeliveryDoc, on: RuleOn, payload: MatchPayload): boolean;