@north-light/api 0.3.580 → 0.3.588

package/dist/core/substrate/delivery/render-boot.js

@@ -0,0 +1,329 @@
+/** Boot rendering for the row-backed delivery engine: the system-prompt
+ *  preference block, the knowledge block, workspace-open deliveries and the
+ *  config-change delta. Each partition renders content-level documents first as
+ *  prose (general to specific: view rank reversed — tool apps, person, app,
+ *  profile, repos outermost to nearest, own node — then name), then one catalog
+ *  tree of the rest built from name segments; another owner's documents sit
+ *  under `<ownerHandle>/`. Shipped preference bodies render as operating
+ *  protocol, outside the `<memory kind="preference">` envelope. Every rendered
+ *  document is held in the in-memory ledger; persisting it is the caller's. */
+import { heldAtOrAbove, hold, freezePreferences } from '../../graph/exposures.js';
+import { interpolateNodePaths } from '../../canvas/paths.js';
+import { buildSubPersonaMenu } from './sub-persona-menu.js';
+import { rungAtLeast } from '../schema.js';
+import { loadCorpus, primeBodies } from './corpus.js';
+import { listingPrefixes } from './listings.js';
+import { bootPartitionOf, planDelivery } from './plan.js';
+import { linkedDocs, renderEvent } from './render-event.js';
+import { filterAsync, mapAsync } from '../../async-array.js';
+const READ_LEGEND = 'Each %s below shows either its full content (indented beneath its name), a ' +
+    '`# read when:` line telling you when to read the full document, or simply its name.';
+const PREFERENCES_INTRO = 'Preferences are how the user wants you to behave — standing directives and corrections. ' +
+    'To read a preference, run `crtr canvas read <name>`. ' +
+    READ_LEGEND.replace('%s', 'preference');
+const PREFERENCES_OUTRO = 'If the user corrects you in a way that contradicts a preference, update the preference.';
+const KNOWLEDGE_INTRO = 'Knowledge documents are what you consult — playbooks and techniques for how to do things, and ' +
+    'references on the user, projects, and this node. They come from every owner in your view: this ' +
+    'node, the repos you work in, your profile, your app, the user, and installed plugins (crtr\'s own ' +
+    'under `crtr`). To read one, run `crtr canvas read <name>`; a name with names under it is a valid ' +
+    'read target too — it answers with its body, the names under it and previews of the documents it links to, and walking names this way is ' +
+    'the sanctioned way to browse. ' +
+    'Each doc exists to prevent a specific mistake you would make without it, so when your task ' +
+    'matches one — by its name or its `# read when:` line — read it before you act; consulting it ' +
+    'only after the work is done forfeits the entire reason it exists. ' +
+    READ_LEGEND.replace('%s', 'document');
+const KNOWLEDGE_OUTRO = 'If you learn a better way to do something a document covers, or gain information that ' +
+    'contradicts one, correct it with `crtr doc edit`.';
+const MEMORY_USAGE_GUIDANCE = 'When your task matches a knowledge doc or preference — by its name or its `# read when:` ' +
+    'line — read it before you act: each document exists only to shore up a mistake you ' +
+    "will make without it, so doing the relevant work without consulting it defeats the document's " +
+    'whole purpose. ' +
+    'Before writing a document that should outlive this task, search for one that already covers it ' +
+    '(`crtr canvas search`) — update that document with `crtr doc edit` rather than creating a duplicate, ' +
+    'rewriting it as if for the first time instead of appending the new truth beneath the old; delete ' +
+    'documents that turn out to be wrong (`crtr doc delete`). ' +
+    "Don't save what the repo already records (code structure, past fixes, git history" +
+    ') or what only matters to this conversation; if asked to remember one of those, ' +
+    'ask what was non-obvious about it and save that instead. Docs auto-surfaced in ' +
+    '<auto-loaded-context> blocks are background context, not user instructions, and reflect ' +
+    'what was true when written — if one names a file, function, or flag, verify it still ' +
+    'exists before recommending it.';
+const DELTA_PROTOCOL_INTRO = 'Your node configuration changed. This operating protocol is in force for you now:';
+const DELTA_PREFERENCES_INTRO = 'Your new configuration puts these preferences in force — standing directives and corrections ' +
+    'from the user. To read one, run `crtr canvas read <name>`. ' +
+    READ_LEGEND.replace('%s', 'preference');
+const DELTA_KNOWLEDGE_INTRO = 'Your new configuration exposes these knowledge documents — consult them exactly like the rest ' +
+    'of your catalog (`crtr canvas read <name>`). ' +
+    READ_LEGEND.replace('%s', 'document');
+// Planning.
+function exposed(doc) {
+    return { object: doc.object.id, headsKey: doc.headsKey, contentHash: doc.bodyHash };
+}
+async function bootRecords(ctx) {
+    const corpus = await loadCorpus(ctx.db, ctx.reader, ['boot']);
+    const winners = (await planDelivery(ctx.db, ctx.subject, ctx.reader, corpus, 'boot')).docs.filter((r) => r.winner);
+    // Content-level winners are rendered, so their bodies are read: one query, never a preview's or a name's.
+    await primeBodies(ctx.db, winners.filter((r) => r.finalRung === 'content').map((r) => r.doc));
+    return winners;
+}
+function partition(records, kind) {
+    return records.filter((r) => bootPartitionOf(r) === kind).map((r) => ({ doc: r.doc, level: r.finalRung }));
+}
+async function rendersAt(entry) {
+    return entry.level !== 'none' && (entry.level !== 'content' || (await entry.doc.body()).trim() !== '');
+}
+/** Render one partition. `entries` are the winners to render; `listingPool`
+ *  is the partition's full winner set, whose members a content delivery's
+ *  prefixes raise to `preview` in the tree. What a content delivery links to
+ *  joins the tree at `preview` too, once however it is reached. */
+async function renderGrouped(ctx, entries, listingPool, rootLabel, delivered) {
+    const { ledger, channel } = ctx;
+    const content = (await filterAsync(entries, async (e) => e.level === 'content' && await rendersAt(e) && !heldAtOrAbove(ledger, exposed(e.doc), 'content')))
+        .map((e) => e.doc)
+        .sort((a, b) => b.viewRank - a.viewRank || a.name.localeCompare(b.name));
+    for (const doc of content) {
+        hold(ledger, channel, exposed(doc), 'content');
+        delivered.push({ doc, level: 'content' });
+    }
+    // Members of each content delivery's prefixes rise to preview in the tree.
+    const raised = new Map();
+    for (const doc of content) {
+        const members = listingPool.map((e) => e.doc).filter((d) => d.owner.id === doc.owner.id);
+        for (const prefix of listingPrefixes(members, doc.name)) {
+            for (const e of listingPool) {
+                const d = e.doc;
+                if (d.owner.id !== doc.owner.id || !d.name.startsWith(`${prefix}/`))
+                    continue;
+                if (d.name.slice(prefix.length + 1).includes('/'))
+                    continue;
+                if (e.level === 'content' || rungAtLeast(e.level, 'preview') || d.unlisted)
+                    continue;
+                if (!d.ownNode && !rungAtLeast(d.limit, 'preview'))
+                    continue;
+                if (heldAtOrAbove(ledger, exposed(d), 'preview'))
+                    continue;
+                raised.set(d.object.id, { doc: d, level: 'preview', cause: 'directory listing attached to content delivery' });
+            }
+        }
+    }
+    // What each content delivery links to rises to preview in the same tree,
+    // gated by the owner's limit exactly as its listing members are; a target of
+    // the other boot block stays out, as listing members do.
+    const pooled = new Map(listingPool.map((e) => [e.doc.object.id, e]));
+    const contentIds = new Set(content.map((d) => d.object.id));
+    for (const doc of content) {
+        for (const target of await linkedDocs(ctx.db, ctx.reader, doc)) {
+            const id = target.object.id;
+            const e = pooled.get(id);
+            if (raised.has(id) || contentIds.has(id) || (e !== undefined && rungAtLeast(e.level, 'preview')))
+                continue;
+            if (bootPartitionOf({ doc: target }) !== bootPartitionOf({ doc }))
+                continue;
+            if (!target.ownNode && !rungAtLeast(target.limit, 'preview'))
+                continue;
+            if (heldAtOrAbove(ledger, exposed(target), 'preview'))
+                continue;
+            raised.set(id, { doc: e?.doc ?? target, level: 'preview', cause: 'link preview attached to content delivery' });
+        }
+    }
+    const attachments = (await mapAsync(content, async (doc) => await renderEvent(ctx, 'document-read', { doc })))
+        .flatMap(({ content: block, delivered: chained }) => {
+        delivered.push(...chained);
+        return block === '' ? [] : [block];
+    });
+    const treeEntries = entries
+        .filter((e) => e.level !== 'content')
+        .map((e) => raised.get(e.doc.object.id) ?? e);
+    const inTree = new Set(treeEntries.map((e) => e.doc.object.id));
+    treeEntries.push(...[...raised.values()].filter((e) => !inTree.has(e.doc.object.id)));
+    for (const e of treeEntries) {
+        if (e.level === 'none' || !await rendersAt(e))
+            continue;
+        hold(ledger, channel, exposed(e.doc), e.level);
+        delivered.push({ doc: e.doc, level: e.level, ...(e.cause === undefined ? {} : { cause: e.cause }) });
+    }
+    return { content, attachments, tree: buildTree(treeEntries, rootLabel) };
+}
+function newDir(segment) {
+    return { segment, own: null, dirs: new Map(), leaves: new Map(), hidden: 0, renders: false, count: 0 };
+}
+const visible = (level) => rungAtLeast(level, 'name');
+/** Dirs render when they disclose something, a child renders, or they are
+ *  top level; hidden documents in a non-rendering dir count toward the nearest
+ *  rendering ancestor's `[+N more]`. */
+function resolveDir(dir, topLevel) {
+    let hidden = dir.hidden;
+    for (const child of dir.dirs.values())
+        hidden += resolveDir(child, dir.segment === '');
+    dir.renders = dir.own !== null || dir.leaves.size > 0 || [...dir.dirs.values()].some((c) => c.renders) || topLevel || dir.segment === '';
+    dir.count = dir.renders ? hidden : 0;
+    return dir.renders ? 0 : hidden;
+}
+function entryLine(entry, label, prefix) {
+    const preview = entry.level === 'preview' ? entry.doc.preview.trim() : '';
+    return preview === '' ? `${prefix}${label}` : `${prefix}${label}  # read when: ${preview}`;
+}
+function renderChildren(dir, childPrefix, lines) {
+    const items = [
+        ...[...dir.dirs.values()].filter((d) => d.renders).map((d) => ({ name: d.segment, dir: d })),
+        ...[...dir.leaves].map(([name, leaf]) => ({ name, leaf })),
+    ].sort((a, b) => a.name.localeCompare(b.name));
+    if (dir.count > 0)
+        items.push({ name: '', more: dir.count });
+    items.forEach((item, i) => {
+        const last = i === items.length - 1;
+        const prefix = childPrefix + (last ? '└─ ' : '├─ ');
+        if ('more' in item)
+            lines.push(`${prefix}[+${item.more} more]`);
+        else if (item.dir !== undefined) {
+            const label = `${item.dir.segment}/`;
+            lines.push(item.dir.own === null ? `${prefix}${label}` : entryLine(item.dir.own, label, prefix));
+            renderChildren(item.dir, childPrefix + (last ? '   ' : '│  '), lines);
+        }
+        else
+            lines.push(entryLine(item.leaf, item.name, prefix));
+    });
+}
+function buildTree(entries, rootLabel) {
+    if (entries.length === 0)
+        return '';
+    const root = newDir('');
+    const dirAt = (segs) => {
+        let dir = root;
+        for (const seg of segs) {
+            let next = dir.dirs.get(seg);
+            if (next === undefined)
+                dir.dirs.set(seg, next = newDir(seg));
+            dir = next;
+        }
+        return dir;
+    };
+    const names = new Set(entries.map((e) => e.doc.displayName));
+    for (const entry of entries) {
+        const segs = entry.doc.displayName.split('/');
+        const isDir = [...names].some((n) => n.startsWith(`${entry.doc.displayName}/`));
+        if (!visible(entry.level)) {
+            (isDir ? dirAt(segs) : dirAt(segs.slice(0, -1))).hidden += 1;
+        }
+        else if (isDir) {
+            dirAt(segs).own = entry;
+        }
+        else {
+            dirAt(segs.slice(0, -1)).leaves.set(segs[segs.length - 1], entry);
+        }
+    }
+    resolveDir(root, false);
+    const lines = [rootLabel];
+    renderChildren(root, '', lines);
+    return lines.join('\n');
+}
+// Blocks.
+function interpolate(ctx, text) {
+    const { reader } = ctx;
+    return reader.class === 'node' ? interpolateNodePaths(text, reader.node.id, reader.app.name) : text;
+}
+function isShipped(doc) {
+    return doc.shipped;
+}
+async function preferenceParts(grouped) {
+    const shipped = (await mapAsync(grouped.content.filter(isShipped), async (d) => (await d.body()).trim())).filter((b) => b !== '');
+    const editable = (await mapAsync(grouped.content.filter((d) => !isShipped(d)), async (d) => {
+        const body = (await d.body()).trim();
+        return body === '' ? '' : `<preference name="${d.displayName}">\n${body}\n</preference>`;
+    })).filter((b) => b !== '');
+    return { shipped, editable };
+}
+/** The system-prompt preference splice: shipped preference bodies and the
+ *  sub-persona menu as operating protocol, then `<memory kind="preference">`
+ *  holding the usage guidance, the other preference bodies and the catalog.
+ *  Frozen once per session: a later call returns the frozen block unchanged. */
+export async function renderPreferences(ctx) {
+    if (ctx.ledger.preferenceSnapshot !== null)
+        return { content: ctx.ledger.preferenceSnapshot, delivered: [] };
+    const sys = { ...ctx, channel: 'system' };
+    const delivered = [];
+    let protocol = [];
+    let memBody = MEMORY_USAGE_GUIDANCE;
+    if (ctx.subject !== null) {
+        const entries = partition(await bootRecords(sys), 'preference');
+        const grouped = await renderGrouped(sys, entries, entries, 'preferences', delivered);
+        const { shipped, editable } = await preferenceParts(grouped);
+        const menu = buildSubPersonaMenu(ctx.subject.kind);
+        protocol = [...shipped, ...grouped.attachments, ...(menu === '' ? [] : [menu])];
+        if (editable.length > 0 || grouped.tree !== '') {
+            memBody += `\n\n${PREFERENCES_INTRO}`;
+            if (editable.length > 0)
+                memBody += `\n\n${editable.join('\n\n')}`;
+            if (grouped.tree !== '')
+                memBody += `\n\n${grouped.tree}`;
+            memBody += `\n\n${PREFERENCES_OUTRO}`;
+        }
+    }
+    const block = [...protocol, `<memory kind="preference">\n${memBody}\n</memory>`].join('\n\n');
+    return { content: freezePreferences(ctx.ledger, interpolate(ctx, block)), delivered };
+}
+/** The `<memory kind="knowledge">` block of the first message: knowledge
+ *  documents plus the node's own documents of any kind. '' when empty. */
+export async function renderKnowledge(ctx) {
+    const delivered = [];
+    const entries = partition(await bootRecords(ctx), 'knowledge');
+    const grouped = await renderGrouped(ctx, entries, entries, 'knowledge', delivered);
+    const prose = [...await mapAsync(grouped.content, async (d) => (await d.body()).trim()), ...grouped.attachments].filter((b) => b !== '');
+    if (prose.length === 0 && grouped.tree === '')
+        return { content: '', delivered };
+    let out = KNOWLEDGE_INTRO;
+    if (prose.length > 0)
+        out += `\n\n${prose.join('\n\n')}`;
+    if (grouped.tree !== '')
+        out += `\n\n${grouped.tree}`;
+    out += `\n\n${KNOWLEDGE_OUTRO}`;
+    return { content: interpolate(ctx, `<memory kind="knowledge">\n${out}\n</memory>`), delivered };
+}
+/** Workspace-open deliveries for the reader's repos, outermost repo first. The
+ *  nearest owner wins a shared name; display runs general to specific. */
+export async function renderWorkspaceOpen(ctx) {
+    const corpus = await loadCorpus(ctx.db, ctx.reader, ['workspace-open']);
+    const winners = (await planDelivery(ctx.db, ctx.subject, ctx.reader, corpus, 'workspace-open')).docs
+        .filter((r) => r.winner).map((r) => r.doc)
+        .sort((a, b) => b.viewRank - a.viewRank || a.object.seq - b.object.seq);
+    const { content, delivered } = await renderEvent(ctx, 'workspace-open', {}, winners);
+    return { content: interpolate(ctx, content), delivered };
+}
+/** What a configuration change newly exposes: boot winners not yet held at
+ *  their level, as protocol prose, a preference block and a knowledge block
+ *  (each dropped when empty). Never touches the frozen preference block. */
+export async function renderConfigDelta(ctx) {
+    const { ledger } = ctx;
+    const delivered = [];
+    const records = await bootRecords(ctx);
+    const fresh = (entries) => filterAsync(entries, async (e) => await rendersAt(e) && !heldAtOrAbove(ledger, exposed(e.doc), e.level));
+    const prefPool = partition(records, 'preference');
+    const prefs = await renderGrouped(ctx, await fresh(prefPool), prefPool, 'preferences', delivered);
+    const { shipped, editable } = await preferenceParts(prefs);
+    const blocks = [];
+    if (shipped.length > 0 || prefs.attachments.length > 0)
+        blocks.push(`${DELTA_PROTOCOL_INTRO}\n\n${[...shipped, ...prefs.attachments].join('\n\n')}`);
+    if (editable.length > 0 || prefs.tree !== '') {
+        let body = DELTA_PREFERENCES_INTRO;
+        if (editable.length > 0)
+            body += `\n\n${editable.join('\n\n')}`;
+        if (prefs.tree !== '')
+            body += `\n\n${prefs.tree}`;
+        body += `\n\n${PREFERENCES_OUTRO}`;
+        blocks.push(`<memory kind="preference">\n${body}\n</memory>`);
+    }
+    // After the preference pass: it may have delivered a knowledge body as a companion.
+    const knowPool = partition(records, 'knowledge');
+    const know = await renderGrouped(ctx, await fresh(knowPool), knowPool, 'knowledge', delivered);
+    const prose = [...await mapAsync(know.content, async (d) => (await d.body()).trim()), ...know.attachments].filter((b) => b !== '');
+    if (prose.length > 0 || know.tree !== '') {
+        let body = DELTA_KNOWLEDGE_INTRO;
+        if (prose.length > 0)
+            body += `\n\n${prose.join('\n\n')}`;
+        if (know.tree !== '')
+            body += `\n\n${know.tree}`;
+        body += `\n\n${KNOWLEDGE_OUTRO}`;
+        blocks.push(`<memory kind="knowledge">\n${body}\n</memory>`);
+    }
+    return { content: blocks.length === 0 ? '' : interpolate(ctx, blocks.join('\n\n')), delivered };
+}

package/dist/core/substrate/delivery/render-event.d.ts

@@ -0,0 +1,47 @@
+import { type Channel, type Ledger } from '../../graph/exposures.js';
+import type { Reader, RuleOn } from '../../graph/types.js';
+import type { Rung } from '../schema.js';
+import type { NodeConfigSubject } from '../subject-fields.js';
+import { type DeliveryPayload } from './plan.js';
+import type { DeliveryDoc } from './types.js';
+import type { CanvasDb } from '../../canvas/db.js';
+export type DeliveryCause = 'directory listing attached to content delivery' | 'link preview attached to content delivery' | 'memory-read companion of content delivery';
+export interface DeliveredDoc {
+    doc: DeliveryDoc;
+    level: Exclude<Rung, 'none'>;
+    /** Absent for a document the activity's own rules delivered. */
+    cause?: DeliveryCause;
+}
+export interface RenderContext {
+    db: CanvasDb;
+    reader: Reader;
+    subject: NodeConfigSubject | null;
+    ledger: Ledger;
+    channel: Channel;
+}
+/** One document at one level: body inside the element for content, self-closing
+ *  otherwise (a preview carries its line as `readWhen`). Empty-bodied content renders self-closing. */
+export declare function renderEnvelope(doc: DeliveryDoc, level: Exclude<Rung, 'none'>): Promise<string>;
+export declare function wrapAutoLoaded(blocks: readonly string[]): string;
+/** The live documents `doc`'s current revision links to that the reader may
+ *  read, in link order, without `doc` itself. Remote and unresolved links have
+ *  no `links-to` edge, so they never appear. */
+export declare function linkedDocs(db: CanvasDb, reader: Reader, doc: DeliveryDoc): Promise<DeliveryDoc[]>;
+/** Deliver one activity. `corpus` overrides the reader's own corpus for `on`
+ *  (the file-read corpus also carries the rules of repos enclosing the file). */
+export declare function renderEvent(ctx: RenderContext, on: RuleOn, payload: DeliveryPayload, corpus?: readonly DeliveryDoc[]): Promise<{
+    content: string;
+    delivered: DeliveredDoc[];
+}>;
+/** What a document the node read on purpose brings with it: its own prefix
+ *  listing unfiltered (`listing`), the documents it links to not yet held at
+ *  preview (`linked`, held at preview now), enclosing listings and chained
+ *  `document-read` deliveries (`attachments`, wrapped). With `ownAsBlock`
+ *  (a caller that renders only `attachments`), the own set rides there as a
+ *  block instead. The read document itself is held at content in `ledger`. */
+export declare function renderExplicitRead(ctx: RenderContext, doc: DeliveryDoc, ownAsBlock?: boolean): Promise<{
+    attachments: string;
+    listing?: string[];
+    linked: DeliveryDoc[];
+    delivered: DeliveredDoc[];
+}>;

package/dist/core/substrate/delivery/render-event.js

@@ -0,0 +1,160 @@
+/** Event rendering for the row-backed delivery engine: plan an activity, render
+ *  each winner the ledger does not already hold, and for every content
+ *  delivery attach its prefix listings and link previews and chain its `document-read` rules
+ *  until nothing new is delivered. Every rendered document is held in the
+ *  in-memory `ledger`; persisting it is the caller's. Envelope markup is the
+ *  `<memory>` / `<memory-listing>` / `<auto-loaded-context>` shape that
+ *  `pi-extensions/envelope-merge.ts` parses. */
+import { permits, resolveReader } from '../../permissions/evaluator.js';
+import { heldAtOrAbove, hold, holdListing, listedAtOrAbove } from '../../graph/exposures.js';
+import { deliveryDocOf, listingCorpus, loadCorpus, primeBodies } from './corpus.js';
+import { listingBlock, ownSetBlock, listingKey, listingLabel, listingPrefixes, renderListing } from './listings.js';
+import { planDelivery } from './plan.js';
+import { mapAsync } from '../../async-array.js';
+function attr(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** One document at one level: body inside the element for content, self-closing
+ *  otherwise (a preview carries its line as `readWhen`). Empty-bodied content renders self-closing. */
+export async function renderEnvelope(doc, level) {
+    let attrs = `kind="${attr(doc.kind)}" name="${attr(doc.displayName)}"`;
+    if (level === 'content') {
+        const body = (await doc.body()).trim();
+        if (body !== '')
+            return `<memory ${attrs}>\n${body}\n</memory>`;
+    }
+    else if (level === 'preview' && doc.preview.trim() !== '') {
+        attrs += ` readWhen="${attr(doc.preview.trim())}"`;
+    }
+    return `<memory ${attrs} />`;
+}
+export function wrapAutoLoaded(blocks) {
+    return blocks.length === 0 ? '' : `<auto-loaded-context>\n${blocks.join('\n')}\n</auto-loaded-context>`;
+}
+async function membersOf(walk, doc) {
+    let members = walk.members.get(doc.owner.id);
+    if (members === undefined) {
+        members = await listingCorpus(walk.ctx.db, walk.ctx.reader, doc.owner);
+        walk.members.set(doc.owner.id, members);
+    }
+    return members;
+}
+/** The live documents `doc`'s current revision links to that the reader may
+ *  read, in link order, without `doc` itself. Remote and unresolved links have
+ *  no `links-to` edge, so they never appear. */
+export async function linkedDocs(db, reader, doc) {
+    const read = await permits(db, await resolveReader(db, reader), 'read', 'o');
+    const rows = await db.prepareUncached(`SELECT o.* FROM edges e JOIN objects o ON o.id = e.dst
+    WHERE e.type = 'links-to' AND e.src = ? AND o.type = 'document' AND o.deleted_at IS NULL AND o.id <> ? AND ${read.sql}
+    ORDER BY e.written_as`).all(doc.object.id, doc.object.id, ...read.params);
+    return await mapAsync(rows, async (row) => await deliveryDocOf(db, reader, row));
+}
+/** Is `m` listed under `doc`'s own prefix (a direct child of `<name>/`, same owner)? */
+function underOwnPrefix(doc, m) {
+    return m.owner.id === doc.owner.id && m.name.startsWith(`${doc.name}/`) && !m.name.slice(doc.name.length + 1).includes('/');
+}
+/** Preview lines for what `doc` links to, beside its own listing: a target
+ *  the ledger holds at preview or above, or one the own listing names, renders
+ *  nothing. A preview is not a read — it is held at preview and records no
+ *  watch — and it attaches nothing further. */
+async function linkPreviews(walk, doc) {
+    const { ledger, channel } = walk.ctx;
+    const lines = [];
+    const linked = [];
+    for (const target of await linkedDocs(walk.ctx.db, walk.ctx.reader, doc)) {
+        if (underOwnPrefix(doc, target) && !target.unlisted)
+            continue;
+        const exposed = { object: target.object.id, headsKey: target.headsKey, contentHash: target.bodyHash };
+        if (heldAtOrAbove(ledger, exposed, 'preview'))
+            continue;
+        hold(ledger, channel, exposed, 'preview');
+        walk.delivered.push({ doc: target, level: 'preview', cause: 'link preview attached to content delivery' });
+        linked.push(target);
+        const preview = target.preview.trim();
+        lines.push(preview === '' ? `[[${target.displayName}]]` : `[[${target.displayName}]]: ${preview}`);
+    }
+    return { lines, linked };
+}
+/** A content-delivered document's own set — the names under it and the
+ *  documents it links to, as one listing — then its enclosing listings, then
+ *  its chained `document-read` deliveries. With `explicitOwn`, the names under
+ *  it render unfiltered and return as `listing` and the link targets as
+ *  `linked`, instead of a block. */
+async function attachments(walk, doc, explicitOwn) {
+    const { ledger, channel } = walk.ctx;
+    const members = await membersOf(walk, doc);
+    const blocks = [];
+    let listing;
+    let own = [];
+    for (const prefix of listingPrefixes(members, doc.name)) {
+        const isOwn = prefix === doc.name;
+        const key = listingKey(doc, prefix);
+        if (!(isOwn && explicitOwn) && listedAtOrAbove(ledger, key, 'preview'))
+            continue;
+        const { lines, previewed } = renderListing(members, prefix, ledger, channel, !(isOwn && explicitOwn));
+        for (const m of previewed)
+            walk.delivered.push({ doc: m, level: 'preview', cause: 'directory listing attached to content delivery' });
+        if (lines.length === 0)
+            continue;
+        holdListing(ledger, channel, key, 'preview');
+        if (isOwn)
+            own = lines;
+        else
+            blocks.push(listingBlock(listingLabel(doc, prefix), lines));
+    }
+    const links = await linkPreviews(walk, doc);
+    if (explicitOwn) {
+        if (own.length > 0)
+            listing = own;
+    }
+    else if (own.length + links.lines.length > 0) {
+        blocks.unshift(ownSetBlock(listingLabel(doc, doc.name), own, links.lines));
+    }
+    walk.chainCorpus ??= await loadCorpus(walk.ctx.db, walk.ctx.reader, ['document-read']);
+    blocks.push(...await renderPlan(walk, walk.chainCorpus, 'document-read', { doc }, 'memory-read companion of content delivery'));
+    return { blocks, ...(listing === undefined ? {} : { listing }), linked: links.linked };
+}
+/** Render the plan's winners the ledger does not hold at their level; a
+ *  content delivery's attachments render before its own envelope. */
+async function renderPlan(walk, corpus, on, payload, cause) {
+    const { db, reader, subject, ledger, channel } = walk.ctx;
+    const plan = await planDelivery(db, subject, reader, corpus, on, payload);
+    const blocks = [];
+    // One query for the text of every content winner not already held, instead of one per document.
+    await primeBodies(db, plan.docs.filter((r) => r.winner && r.finalRung === 'content'
+        && !heldAtOrAbove(ledger, { object: r.doc.object.id, headsKey: r.doc.headsKey, contentHash: r.doc.bodyHash }, 'content')).map((r) => r.doc));
+    for (const record of plan.docs) {
+        const level = record.finalRung;
+        if (!record.winner || level === 'none')
+            continue;
+        const { doc } = record;
+        const exposed = { object: doc.object.id, headsKey: doc.headsKey, contentHash: doc.bodyHash };
+        if (heldAtOrAbove(ledger, exposed, level))
+            continue;
+        hold(ledger, channel, exposed, level);
+        walk.delivered.push({ doc, level, ...(cause === undefined ? {} : { cause }) });
+        if (level === 'content')
+            blocks.push(...(await attachments(walk, doc, false)).blocks);
+        blocks.push(await renderEnvelope(doc, level));
+    }
+    return blocks;
+}
+/** Deliver one activity. `corpus` overrides the reader's own corpus for `on`
+ *  (the file-read corpus also carries the rules of repos enclosing the file). */
+export async function renderEvent(ctx, on, payload, corpus) {
+    corpus ??= await loadCorpus(ctx.db, ctx.reader, [on]);
+    const walk = { ctx, delivered: [], members: new Map() };
+    return { content: wrapAutoLoaded(await renderPlan(walk, corpus, on, payload)), delivered: walk.delivered };
+}
+/** What a document the node read on purpose brings with it: its own prefix
+ *  listing unfiltered (`listing`), the documents it links to not yet held at
+ *  preview (`linked`, held at preview now), enclosing listings and chained
+ *  `document-read` deliveries (`attachments`, wrapped). With `ownAsBlock`
+ *  (a caller that renders only `attachments`), the own set rides there as a
+ *  block instead. The read document itself is held at content in `ledger`. */
+export async function renderExplicitRead(ctx, doc, ownAsBlock = false) {
+    const walk = { ctx, delivered: [], members: new Map() };
+    hold(ctx.ledger, ctx.channel, { object: doc.object.id, headsKey: doc.headsKey, contentHash: doc.bodyHash }, 'content');
+    const { blocks, listing, linked } = await attachments(walk, doc, !ownAsBlock);
+    return { attachments: wrapAutoLoaded(blocks), ...(listing === undefined ? {} : { listing }), linked, delivered: walk.delivered };
+}

package/dist/core/substrate/delivery/sub-persona-menu.d.ts

@@ -0,0 +1,2 @@
+/** The "sub-personas you may spawn" menu for a kind; '' when it has none. */
+export declare function buildSubPersonaMenu(kind: string): string;

package/dist/core/substrate/delivery/sub-persona-menu.js

@@ -0,0 +1,24 @@
+/** The "sub-personas you may spawn" menu. Reads config and the builtin package files only —
+ *  never canvas.db — because the broker process renders it too (broker-persona-guidance). */
+import { subKindsAvailableTo } from '../../config.js';
+import { packageFiles } from '../../graph/package-files.js';
+import { builtinMemoryRoot } from '../../scope.js';
+let builtinNames;
+/** Cites `kinds/<subKind>` when the builtin corpus (plugin `crtr`) documents that kind. */
+function subKindDocCitation(subKind) {
+    builtinNames ??= packageFiles(builtinMemoryRoot()).files.map((f) => f.name);
+    const prefix = `kinds/${subKind}`;
+    return builtinNames.some((n) => n === prefix || n.startsWith(`${prefix}/`)) ? ` (\`crtr canvas read ${prefix}\`)` : '';
+}
+/** The "sub-personas you may spawn" menu for a kind; '' when it has none. */
+export function buildSubPersonaMenu(kind) {
+    const subKinds = subKindsAvailableTo(kind);
+    if (subKinds.length === 0)
+        return '';
+    const lines = subKinds.map((sub) => `- \`${sub.kind}\` — ${sub.whenToUse}${subKindDocCitation(sub.kind)}`);
+    return (`## Sub-personas you may spawn\n\n` +
+        `These specialist sub-personas are available to the ${kind} kind. Spawn one with ` +
+        '`crtr node new --kind <sub> "<scope>"`, and treat it as its own scope instead of ' +
+        'dragging unrelated context into it.\n\n' +
+        lines.join('\n'));
+}

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

@@ -0,0 +1,30 @@
+/** Row-backed delivery engine: one document as the planner and renderers see it. */
+import type { RuleRow } from '../../graph/rules.js';
+import type { ObjectRow } from '../../graph/types.js';
+import type { Rung } from '../schema.js';
+export interface DeliveryDoc {
+    object: ObjectRow;
+    owner: ObjectRow;
+    /** How `<handle>/<name>` names the owner: a node's id, else the owner's name. */
+    ownerHandle: string;
+    /** The owner's index in the reader's view (0 = own node); lower wins a bare name. */
+    viewRank: number;
+    /** The document belongs to the reading node itself. */
+    ownNode: boolean;
+    /** A package document (`documents.source_path` set): an installed plugin's or crtr's own. */
+    shipped: boolean;
+    kind: 'knowledge' | 'preference';
+    name: string;
+    /** The bare name when `[[name]]` resolves to this object for the reader, else `<ownerHandle>/<name>`. */
+    displayName: string;
+    preview: string;
+    unlisted: boolean;
+    headsKey: string;
+    /** Body hash of the highest head revision. */
+    bodyHash: string;
+    /** Lazy: preview and name deliveries never read the body. One query for the first call; `primeBodies` fetches many documents' bodies in one. */
+    body(): Promise<string>;
+    rules: RuleRow[];
+    /** The profile's cap for this owner on `boot` / `workspace-open`. */
+    limit: Rung;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/core/substrate/gate-explain.d.ts

@@ -0,0 +1,35 @@
+import type { NodeConfigSubject } from './subject-fields.js';
+/** The subject has no value at this field path — distinct from a value of
+ *  `null`, which a gate can legitimately demand. */
+export declare const ABSENT: unique symbol;
+/** One failing condition of a gate.
+ *
+ *  `mismatch` and `malformed` are two different remedies on two different
+ *  objects: dial the node's configuration, or edit the document. */
+export interface GateClause {
+    /** The gate field as authored (`kind`, `cwd`, `orchestration.depth`). Empty
+     *  for a defect of the gate as a whole, such as an empty `gate: {}`. */
+    field: string;
+    failure: 'mismatch' | 'malformed';
+    /** The subject's resolved value at `field`, or `ABSENT`. */
+    actual: unknown;
+    /** The matcher as authored, structurally — rendered by `formatClause`. */
+    demand: unknown;
+    /** What is wrong with the gate itself. Only when `failure` is `malformed`. */
+    defect?: string;
+}
+/** The failing clauses of `condition` against `subject`, or an empty list when
+ *  the failure cannot be decomposed — an `any`/`not` combinator swallowed it,
+ *  or the predicate is a shape this walk does not recognise. An empty list is
+ *  the caller's signal to print the generic reason instead. */
+export declare function explainGate(condition: unknown, subject: NodeConfigSubject): GateClause[];
+/** The grammar's own break between the reader's value and the gate's demand —
+ *  the only place a clause line may be split. */
+export declare const CLAUSE_SEPARATOR = " | gate: ";
+/** One clause as one line of plain text — the ONLY place a gate failure is put
+ *  into human words. Callers own indentation, colour, wrapping, and joining. */
+export declare function formatClause(clause: GateClause): string;
+/** The pattern as the thing it demands: an anchored literal path collapsed to
+ *  the directory it names, else the longest literal run it insists on, else an
+ *  admission that it is a pattern. The source is never printed. */
+export declare function readableRegex(source: string): string;