@north-light/api 0.3.580 → 0.3.588

package/dist/core/graph/repo-sync/sync.js

@@ -0,0 +1,322 @@
+/** The repo-sync engine in crtrd: per repo at most one sync running and one queued. No timer and
+ *  no retry loop — the next trigger is the retry. A failed sync keeps the local mirror commit and
+ *  every canvas.db revision; the next run sends them. Every outcome is written as an event. */
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { emitEvent as emitUnchecked } from '../../events/emit.js';
+import { exportRepo, importTree, pendingPaths } from './exchange.js';
+import { checkoutChain } from './identity.js';
+import { checkoutsForCwd, reposForCwd, warmCheckoutIdentities } from './repos.js';
+import { commitTree, fetchDocs, FIRST_FETCH_MARKER, isAncestor, mergeBase, openMirror, pushDocs, readTree, remoteDocsTip, resolveRef, setRef, } from './mirror.js';
+import { mergeTrees } from './ref-format.js';
+import { withCanvasWrite } from '../../canvas/db.js';
+import { filterAsync } from '../../async-array.js';
+export const FIRST_FETCH_WAIT_MS = 20_000;
+const PUSH_ATTEMPTS = 3;
+const REMOTE_URL_FILE = 'remote-url';
+const LOCAL = 'refs/crtr/docs';
+const REMOTE = 'refs/crtr/remote-docs';
+const IMPORTED = 'refs/crtr/imported';
+/** Every repo-sync outcome is an event, and writing one never fails a boot, a write or a run. */
+function emitEvent(input) {
+    try {
+        emitUnchecked(input);
+    }
+    catch { /* an unwritable event must not escape into the caller */ }
+}
+let engine = null;
+const states = new Map();
+/** Repos whose first fetch was attempted in this daemon's lifetime. */
+const attempted = new Set();
+/** Called once by crtrd. Until then triggers are refused loudly. */
+export async function startRepoSync(lifecycle, db) {
+    engine = { lifecycle, db };
+}
+async function gitScheme(db, repo) {
+    if (repo.type !== 'repo')
+        return false;
+    return await db.prepare(`SELECT 1 FROM identities WHERE object = ? AND scheme = 'git'`).get(repo.id) !== undefined;
+}
+/** Remembers the fetch URL of every syncing repo that encloses one of `dirs` (identities store only
+ *  the normalized id, so the URL comes from a checkout's `origin`). */
+async function recordRemoteUrls(repos, dirs) {
+    const byId = new Map();
+    for (const dir of dirs)
+        for (const id of await checkoutChain(dir))
+            if (id.ok && id.scheme === 'git')
+                byId.set(id.externalId, id.remoteUrl);
+    if (byId.size === 0)
+        return;
+    const db = await engine.db();
+    const ext = db.prepare(`SELECT external_id FROM identities WHERE object = ? AND scheme = 'git'`);
+    for (const repo of repos) {
+        const row = await ext.get(repo.id);
+        const url = row && byId.get(row.external_id);
+        if (!url)
+            continue;
+        const m = await openMirror(repo.id);
+        await writeFile(join(m.dir, REMOTE_URL_FILE), `${url}\n`);
+    }
+}
+/**
+ * A node starts working in `cwd`, enclosed by `repos`. For each syncing repo: when no fetch has
+ * ever succeeded on this machine and none was attempted in this daemon's lifetime, wait for its
+ * sync, at most FIRST_FETCH_WAIT_MS; otherwise schedule it and return at once.
+ */
+export async function noteNodeWorking(repos, cwd) {
+    const e = requireEngine();
+    const db = await e.db();
+    const syncing = (await filterAsync(repos, async (r) => await gitScheme(db, r)));
+    if (syncing.length === 0)
+        return;
+    await recordRemoteUrls(syncing, [cwd]);
+    const waits = [];
+    for (const repo of syncing) {
+        const firstHere = !attempted.has(repo.id) && !existsSync(join((await openMirror(repo.id)).dir, FIRST_FETCH_MARKER));
+        const run = schedule(repo);
+        if (firstHere && run)
+            waits.push(run);
+    }
+    if (waits.length === 0)
+        return;
+    let timer;
+    const bound = new Promise((resolve) => { timer = setTimeout(resolve, FIRST_FETCH_WAIT_MS); });
+    await Promise.race([Promise.all(waits), bound]);
+    clearTimeout(timer);
+}
+/**
+ * A node's boot delivery is about to render: it starts working in the repos enclosing its cwd.
+ * Sync them first (the first on this machine waits for the first fetch, bounded), so what the
+ * repo's collaborators wrote is on the canvas before its bearings. Never throws: a failed sync
+ * never fails a boot, and every failure is an event.
+ */
+export async function noteNodeBooting(nodeId) {
+    try {
+        const db = await requireEngine().db();
+        const row = await db.prepare('SELECT cwd FROM nodes WHERE node_id = ?').get(nodeId);
+        if (!row)
+            return;
+        await warmCheckoutIdentities(row.cwd);
+        const repos = await withCanvasWrite(async () => await reposForCwd(db, row.cwd));
+        if (repos.length > 0)
+            await noteNodeWorking(repos, row.cwd);
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'repo_sync.failed', outcome: 'failed', error, node_id: nodeId,
+            fields: { step: 'fetch', reason: `the boot trigger failed: ${error instanceof Error ? error.message : String(error)}` } });
+    }
+}
+/** A repo-owned document changed (write, edit, move at either end, delete). `dirs`, the caller's
+ *  cwd and the checkouts it reaches, record the fetch URL of any that is a checkout of the repo; the
+ *  sync itself never depends on where the writer runs. */
+export async function noteRepoDocumentsChanged(repo, dirs = []) {
+    const e = requireEngine();
+    if (!await gitScheme(await e.db(), repo))
+        return;
+    if (dirs.length === 0) {
+        void schedule(repo);
+        return;
+    }
+    const recorded = recordRemoteUrls([repo], dirs).then(() => { void schedule(repo); }, (error) => {
+        emitEvent({ level: 'error', event: 'repo_sync.failed', error, fields: { repo: repo.name, step: 'fetch', reason: 'recording the remote URL failed' } });
+    });
+    e.lifecycle.registerDetached(recorded);
+}
+function requireEngine() {
+    if (!engine)
+        throw new Error('repo sync is not started: crtrd must call startRepoSync first');
+    return engine;
+}
+/** Starts a run, or marks one queued behind the running one. Returns the promise of the run that
+ *  will cover this trigger, or null when the daemon is shutting down. */
+function schedule(repo) {
+    const e = requireEngine();
+    const state = states.get(repo.id) ?? { running: null, again: false };
+    states.set(repo.id, state);
+    if (state.running) {
+        state.again = true;
+        // The queued run starts when this one ends; its promise is that follow-up.
+        return state.running.then(() => states.get(repo.id)?.running ?? null).then((p) => p ?? { ok: true, pushed: false, imported: emptyImport() });
+    }
+    if (!e.lifecycle.acceptsDetachedWork())
+        return null;
+    attempted.add(repo.id);
+    const run = syncRepo(repo).then((outcome) => {
+        report(repo, outcome);
+        return outcome;
+    }, (error) => {
+        const outcome = { ok: false, step: 'export', reason: error instanceof Error ? error.message : String(error) };
+        report(repo, outcome);
+        return outcome;
+    }).finally(() => {
+        state.running = null;
+        if (state.again) {
+            state.again = false;
+            void schedule(repo);
+        }
+    });
+    state.running = run;
+    e.lifecycle.registerDetached(run.then(() => undefined));
+    return run;
+}
+function report(repo, outcome) {
+    if (outcome.ok) {
+        const i = outcome.imported;
+        emitEvent({ level: 'info', event: 'repo_sync.completed', outcome: 'succeeded', fields: {
+                repo: repo.name, pushed: outcome.pushed, created: i.created, revisions: i.revisions, deleted: i.deleted,
+                needs_merge: i.needsMerge, refused: i.refused,
+            } });
+    }
+    else {
+        emitEvent({ level: 'warn', event: 'repo_sync.failed', outcome: 'failed', fields: { repo: repo.name, step: outcome.step, reason: outcome.reason } });
+    }
+}
+function emptyImport() { return { created: 0, revisions: 0, deleted: 0, needsMerge: [], refused: [] }; }
+class StepError extends Error {
+    step;
+    constructor(step, reason) {
+        super(reason);
+        this.step = step;
+    }
+}
+async function step(name, body) {
+    try {
+        return await body();
+    }
+    catch (error) {
+        if (error instanceof StepError)
+            throw error;
+        throw new StepError(name, error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * One sync: export canvas.db to a local commit, fetch the remote ref, fast-forward or merge,
+ * import the merged tree into canvas.db, push (never forced). A rejected push fetches again,
+ * at most PUSH_ATTEMPTS times.
+ */
+export async function syncRepo(repo) {
+    const e = requireEngine();
+    try {
+        const m = await openMirror(repo.id);
+        const url = await readUrl(m);
+        if (url === null)
+            return { ok: false, step: 'fetch', reason: `no checkout of ${repo.name} with an origin remote has been seen by this runtime` };
+        let imported = emptyImport();
+        // (4) Import what LOCAL holds beyond the last import, so canvas.db matches LOCAL. Run first
+        // too: a run that failed after its merge must not export over the merged documents.
+        const importLocal = () => step('import', async () => {
+            const local = await resolveRef(m, LOCAL);
+            const importedSha = await resolveRef(m, IMPORTED);
+            if (local === null || importedSha === local)
+                return;
+            const before = importedSha ? (await readTree(m, IMPORTED)) : new Map();
+            const db = await e.db();
+            // Watchers of a repo document read it through the repos enclosing their cwd.
+            const localTree = (await readTree(m, LOCAL));
+            const r = await importTree(db, repo, before, localTree, async (cwd) => await checkoutsForCwd(db, cwd));
+            imported = { created: imported.created + r.created, revisions: imported.revisions + r.revisions,
+                deleted: imported.deleted + r.deleted, needsMerge: [...new Set([...imported.needsMerge, ...r.needsMerge])],
+                refused: [...imported.refused, ...r.refused] };
+            // A file that was refused has not landed: the baseline keeps its old text so the next run
+            // retries it, and the next export carries it forward instead of dropping it.
+            await advanceImported(m, local, localTree, before, new Set(r.refused.map((x) => x.path)), importedSha);
+        });
+        await importLocal();
+        // (1) Export against LOCAL, which canvas.db now holds; the new commit is imported by definition.
+        await step('export', async () => {
+            const tip = await resolveRef(m, LOCAL);
+            const previous = tip ? await readTree(m, LOCAL) : null;
+            const importedSha = await resolveRef(m, IMPORTED);
+            const importedTree = importedSha ? await readTree(m, IMPORTED) : null;
+            const tree = await exportRepo(await e.db(), repo, previous, importedTree);
+            if (tip ? sameTree(previous, tree) : tree.size === 0)
+                return; // nothing new; no empty first ref
+            const sha = await commitTree(m, tree, tip ? [tip] : [], `crtr: export ${repo.name}`);
+            await setRef(m, LOCAL, sha, tip);
+            await advanceImported(m, sha, tree, importedTree ?? new Map(), new Set(pendingPaths(previous, importedTree)), importedSha);
+        });
+        for (let attempt = 1;; attempt++) {
+            // (2) Remote tip.
+            const tip = await remoteDocsTip(m, url);
+            if (!tip.ok)
+                return { ok: false, step: 'fetch', reason: tip.reason };
+            let local = await resolveRef(m, LOCAL);
+            // (3) Fetch and fast-forward or merge.
+            if (tip.value !== null && !(local && await hasCommit(m, tip.value) && await isAncestor(m, tip.value, local))) {
+                const fetched = await fetchDocs(m, url);
+                if (!fetched.ok)
+                    return { ok: false, step: 'fetch', reason: fetched.reason };
+                const remote = fetched.value;
+                local = await step('merge', async () => {
+                    if (!local || await isAncestor(m, local, remote)) {
+                        await setRef(m, LOCAL, remote, local);
+                        return remote;
+                    }
+                    const base = await mergeBase(m, local, remote);
+                    const merged = mergeTrees(base ? (await readTree(m, base)) : new Map(), (await readTree(m, LOCAL)), (await readTree(m, REMOTE)));
+                    for (const r of merged.refused)
+                        imported.refused.push(r);
+                    const sha = await commitTree(m, merged.tree, [local, remote], `crtr: merge ${repo.name}`);
+                    await setRef(m, LOCAL, sha, local);
+                    return sha;
+                });
+            }
+            await importLocal();
+            // (5) Push when the remote lacks the local tip.
+            if (local === null || local === tip.value)
+                return { ok: true, pushed: false, imported };
+            const pushed = await pushDocs(m, url, local);
+            if (pushed.ok)
+                return { ok: true, pushed: true, imported };
+            if (pushed.reason !== 'rejected')
+                return { ok: false, step: 'push', reason: pushed.reason };
+            if (attempt >= PUSH_ATTEMPTS)
+                return { ok: false, step: 'push', reason: `push rejected ${PUSH_ATTEMPTS} times` };
+        }
+    }
+    catch (error) {
+        if (error instanceof StepError)
+            return { ok: false, step: error.step, reason: error.message };
+        throw error;
+    }
+}
+/**
+ * Record that canvas.db now holds `tree` (the tree of commit `sha`) except the `pending` paths,
+ * which keep their previously imported text (or stay absent). With nothing pending the baseline
+ * is the commit itself; otherwise it is a parentless commit of the adjusted tree, left alone
+ * when it equals the baseline already there.
+ */
+async function advanceImported(m, sha, tree, previous, pending, expectOld) {
+    if (pending.size === 0) {
+        await setRef(m, IMPORTED, sha, expectOld);
+        return;
+    }
+    const baseline = new Map(tree);
+    for (const path of pending) {
+        if (previous.has(path))
+            baseline.set(path, previous.get(path));
+        else
+            baseline.delete(path);
+    }
+    if (expectOld !== null && sameTree(previous, baseline))
+        return;
+    await setRef(m, IMPORTED, await commitTree(m, baseline, [], 'crtr: imported baseline (some files pending)'), expectOld);
+}
+async function readUrl(m) {
+    const file = join(m.dir, REMOTE_URL_FILE);
+    if (!existsSync(file))
+        return null;
+    return (await readFile(file, 'utf8')).trim() || null;
+}
+async function hasCommit(m, sha) {
+    return (await resolveRef(m, sha)) !== null;
+}
+function sameTree(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [k, v] of a)
+        if (b.get(k) !== v)
+            return false;
+    return true;
+}

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

@@ -0,0 +1,27 @@
+/** A document's delivery rules as `rules` rows. `rules.owner` mirrors the
+ *  document's `objects.owner` so a rule is found by its document's owner; `replaceRules` and `setRulesOwner` are the only writers. */
+import type { ObjectRow, RuleOn, RuleSpec } from './types.js';
+import type { CanvasDb, CanvasValue } from '../canvas/db.js';
+export declare const RULE_ONS: readonly RuleOn[];
+export interface RuleRow extends RuleSpec {
+    object: string;
+    owner: string | null;
+    position: number;
+}
+/** Replace the document's rules; `position` is the array index, `owner` the document's owner. */
+export declare function replaceRules(db: CanvasDb, object: ObjectRow, specs: readonly RuleSpec[]): Promise<void>;
+/** Re-point the document's rule rows at its current owner (after a move). */
+export declare function setRulesOwner(db: CanvasDb, object: ObjectRow): Promise<void>;
+export declare function rulesOf(db: CanvasDb, object: ObjectRow): Promise<RuleRow[]>;
+/** Every rule on one of `on` whose document satisfies `permitted`: SQL over the document's `objects` row aliased `o` (the evaluator's `permits`). */
+export declare function rulesOn(db: CanvasDb, on: readonly RuleOn[], permitted: {
+    sql: string;
+    params: CanvasValue[];
+}): Promise<RuleRow[]>;
+/** The only converter from package/legacy frontmatter (`surfaces`, `gate`,
+ *  `slash`) to rules. Tolerant like the runtime parser it replaces: invalid
+ *  entries are dropped; `lintRules` is the strict check. A document-level
+ *  `gate` is ANDed into every rule's `if`. */
+export declare function rulesFromFrontmatter(fm: Record<string, unknown>): RuleSpec[];
+/** Strict validation of a rule list; null when valid. */
+export declare function lintRules(value: unknown): string | null;

package/dist/core/graph/rules.js

@@ -0,0 +1,134 @@
+import { forEachAsync } from '../async-array.js';
+export const RULE_ONS = ['boot', 'workspace-open', 'file-read', 'document-read', 'command', 'pre-command', 'slash-command'];
+const DELIVER_LEVELS = ['name', 'preview', 'content'];
+/** Events whose rule selects by `match` (or, for file-read, `matchFrontmatter`). */
+const MATCHED_ONS = ['file-read', 'document-read', 'command', 'pre-command'];
+const RULE_KEYS = ['on', 'match', 'matchFrontmatter', 'if', 'deliver'];
+function fromRaw(raw) {
+    return {
+        object: raw.object, owner: raw.owner, position: raw.position, on: raw.on_event, deliver: raw.deliver,
+        ...(raw.match_json !== null ? { match: JSON.parse(raw.match_json) } : {}),
+        ...(raw.match_frontmatter_json !== null ? { matchFrontmatter: JSON.parse(raw.match_frontmatter_json) } : {}),
+        ...(raw.if_json !== null ? { if: JSON.parse(raw.if_json) } : {}),
+    };
+}
+/** Replace the document's rules; `position` is the array index, `owner` the document's owner. */
+export async function replaceRules(db, object, specs) {
+    const problem = lintRules(specs);
+    if (problem !== null)
+        throw new Error(`replaceRules(${object.id}): ${problem}`);
+    await db.prepare('DELETE FROM rules WHERE object = ?').run(object.id);
+    const insert = db.prepare(`INSERT INTO rules (object, owner, position, on_event, match_json, match_frontmatter_json, if_json, deliver)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    (await forEachAsync(specs, async (spec, position) => {
+        await insert.run(object.id, object.owner, position, spec.on, spec.match !== undefined ? JSON.stringify(spec.match) : null, spec.matchFrontmatter !== undefined ? JSON.stringify(spec.matchFrontmatter) : null, spec.if !== undefined ? JSON.stringify(spec.if) : null, spec.deliver);
+    }));
+}
+/** Re-point the document's rule rows at its current owner (after a move). */
+export async function setRulesOwner(db, object) {
+    const row = await db.prepare('SELECT owner FROM objects WHERE id = ?').get(object.id);
+    if (row === undefined)
+        throw new Error(`setRulesOwner: object ${object.id} does not exist`);
+    await db.prepare('UPDATE rules SET owner = ? WHERE object = ?').run(row.owner, object.id);
+}
+export async function rulesOf(db, object) {
+    return (await db.prepare('SELECT * FROM rules WHERE object = ? ORDER BY position').all(object.id)).map(fromRaw);
+}
+/** Every rule on one of `on` whose document satisfies `permitted`: SQL over the document's `objects` row aliased `o` (the evaluator's `permits`). */
+export async function rulesOn(db, on, permitted) {
+    if (on.length === 0)
+        return [];
+    const sql = `SELECT r.* FROM rules r JOIN objects o ON o.id = r.object WHERE r.on_event IN (${on.map(() => '?').join(',')})
+    AND o.deleted_at IS NULL AND ${permitted.sql} ORDER BY r.object, r.position`;
+    return (await db.prepareUncached(sql).all(...on, ...permitted.params)).map(fromRaw);
+}
+// ── frontmatter → rules ────────────────────────────────────────────────────
+const FRONTMATTER_ON = {
+    boot: 'boot', 'workspace-open': 'workspace-open', read: 'file-read', 'memory-read': 'document-read', command: 'command', 'pre-command': 'pre-command',
+};
+function predicate(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+}
+function globs(v) {
+    if (typeof v === 'string')
+        return v.trim() === '' ? undefined : [v.trim()];
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v.filter((g) => typeof g === 'string' && g.trim() !== '').map((g) => g.trim());
+    return out.length > 0 ? out : undefined;
+}
+/** The only converter from package/legacy frontmatter (`surfaces`, `gate`,
+ *  `slash`) to rules. Tolerant like the runtime parser it replaces: invalid
+ *  entries are dropped; `lintRules` is the strict check. A document-level
+ *  `gate` is ANDed into every rule's `if`. */
+export function rulesFromFrontmatter(fm) {
+    const docGate = predicate(fm['gate']);
+    const withGate = (entryGate) => docGate !== undefined && entryGate !== undefined ? { all: [docGate, entryGate] } : docGate ?? entryGate;
+    const out = [];
+    const surfaces = Array.isArray(fm['surfaces']) ? fm['surfaces'] : [];
+    for (const raw of surfaces) {
+        const rec = predicate(raw);
+        if (rec === undefined)
+            continue;
+        const on = typeof rec['on'] === 'string' ? FRONTMATTER_ON[rec['on']] : undefined;
+        const deliver = rec['at'];
+        if (on === undefined || typeof deliver !== 'string' || !DELIVER_LEVELS.includes(deliver))
+            continue;
+        const match = globs(rec['match']);
+        const matchFrontmatter = on === 'file-read' ? predicate(rec['match-frontmatter']) : undefined;
+        if (MATCHED_ONS.includes(on) && match === undefined && matchFrontmatter === undefined)
+            continue;
+        const cond = withGate(predicate(rec['gate']));
+        out.push({
+            on, deliver: deliver,
+            ...(match !== undefined && on !== 'boot' && on !== 'workspace-open' ? { match } : {}),
+            ...(matchFrontmatter !== undefined ? { matchFrontmatter } : {}),
+            ...(cond !== undefined ? { if: cond } : {}),
+        });
+    }
+    if (fm['slash'] === true)
+        out.push({ on: 'slash-command', deliver: 'content', ...(docGate !== undefined ? { if: docGate } : {}) });
+    return out;
+}
+/** Strict validation of a rule list; null when valid. */
+export function lintRules(value) {
+    if (!Array.isArray(value))
+        return `invalid rules: ${JSON.stringify(value)} (expected a list of {on, deliver, match?, matchFrontmatter?, if?} entries)`;
+    for (const raw of value) {
+        const rule = predicate(raw);
+        if (rule === undefined)
+            return `invalid rule: ${JSON.stringify(raw)} (expected an {on, deliver, match?, matchFrontmatter?, if?} object)`;
+        for (const key of Object.keys(rule)) {
+            if (!RULE_KEYS.includes(key))
+                return `invalid rule: unknown key \`${key}\` (a rule carries only ${RULE_KEYS.join(', ')})`;
+        }
+        const on = rule['on'];
+        if (typeof on !== 'string' || !RULE_ONS.includes(on))
+            return `invalid rule \`on\`: ${JSON.stringify(on)} (expected ${RULE_ONS.join('|')})`;
+        const deliver = rule['deliver'];
+        if (typeof deliver !== 'string' || !DELIVER_LEVELS.includes(deliver)) {
+            return `invalid rule \`deliver\`: ${JSON.stringify(deliver)} (expected ${DELIVER_LEVELS.join('|')})`;
+        }
+        const match = rule['match'];
+        if (match !== undefined) {
+            if (on === 'boot' || on === 'workspace-open' || on === 'slash-command')
+                return `invalid rule: \`match\` is meaningless on \`${on}\`; drop it`;
+            if (!Array.isArray(match) || match.length === 0 || match.some((g) => typeof g !== 'string' || g.trim() === '')) {
+                return `invalid rule \`match\`: ${JSON.stringify(match)} (expected a non-empty list of non-empty globs)`;
+            }
+        }
+        const matchFrontmatter = rule['matchFrontmatter'];
+        if (matchFrontmatter !== undefined) {
+            if (on !== 'file-read')
+                return 'invalid rule: `matchFrontmatter` applies to `file-read` rules only';
+            if (predicate(matchFrontmatter) === undefined)
+                return `invalid rule \`matchFrontmatter\`: ${JSON.stringify(matchFrontmatter)} (expected a field→matcher object)`;
+        }
+        if (MATCHED_ONS.includes(on) && match === undefined && matchFrontmatter === undefined) {
+            return `invalid rule: a \`${on}\` rule requires \`match\`${on === 'file-read' ? ' or `matchFrontmatter`' : ''}`;
+        }
+        if (rule['if'] !== undefined && predicate(rule['if']) === undefined)
+            return `invalid rule \`if\`: ${JSON.stringify(rule['if'])} (expected a predicate object)`;
+    }
+    return null;
+}

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

@@ -0,0 +1,131 @@
+/** Shared types of the canvas graph: documents, nodes, jobs and their owners as rows of `objects`. */
+export type Privacy = 'public' | 'private';
+/** `friends` was a privacy level until cycle 3. Data from an old source (a peer on an older release, a plugin package, a
+ *  legacy canvas or frontmatter) that still says `friends` reads as `private`; a `/v1` write or CLI flag naming it stays refused. */
+export declare const readLegacyPrivacy: (value: unknown) => unknown;
+export interface ObjectRow {
+    id: string;
+    /** Insertion order: the identity column the object list pages by. */
+    seq: number;
+    /** The kind name (`node`, `document`, `job`, an owner kind); the kind registry validates it on create. */
+    type: string;
+    kind: string | null;
+    owner: string | null;
+    privacy: Privacy;
+    name: string;
+    preview: string;
+    created_at: string;
+    deleted_at: string | null;
+    /** Set on a stub (a remote object's local representative): the machine (`runtime:<id>`) that owns the real object. */
+    home_machine?: string | null;
+    /** A document's permission schema type (`firstlight/memory`); null for an ordinary object, evaluated as `crtr/object`. */
+    schema_type?: string | null;
+}
+export type Level = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+export type ListenDelivery = 'interrupt' | 'steer' | 'after-turn' | 'next-turn';
+/** Stored as `{"10":"interrupt",...}`. */
+export type ListenConfig = Array<{
+    threshold: Level;
+    delivery: ListenDelivery;
+}>;
+export declare const DEFAULT_LISTEN: ListenConfig;
+export type WatchStart = 'spawn' | 'job-start' | 'ask' | 'read' | 'write' | 'act' | 'message' | 'deliver' | 'fork';
+export interface CanvasEvent {
+    /** An event the object's kind declares; `publish` validates it against the registry. */
+    event: string;
+    object: ObjectRow;
+    actor: ObjectRow | null;
+    /** Omitted: the declared level. Supplied: must equal it or be one of the event's declared `levels`. */
+    level?: Level;
+    /** revision, rationale, exit-code, log-path, request id …; never content */
+    attrs: Record<string, string | number | boolean | null>;
+    /** the act's pointer (inbox entry id, report doc id, revision rev_id) */
+    pointer?: string;
+    /** ONLY for report.* and notice.*: the body today's report delivery carries */
+    messageBody?: unknown;
+    /** The message whose handling caused this publish, named by the publisher. Its depth + 1 is this
+     *  event's depth and is bounded by HOP_LIMIT; omitted, the event starts a new chain at depth 0. */
+    cause?: string;
+    /** Set by `peer.events` ingestion: each delivery this publish creates carries the unique key `<key>:<destination>`, so a replay adds nothing. */
+    idempotencyKey?: string;
+    /** Deliver only to these watchers (object ids): every other candidate is dropped before grouping, every other check applies unchanged. */
+    onlyWatchers?: readonly string[];
+}
+/** A repo and the directory it is checked out at. */
+export interface Checkout {
+    repo: ObjectRow;
+    root: string;
+}
+/** Who is asking. Mirrors the router's RequestPrincipal; brokers resolve to their node's object. */
+export type Reader = {
+    class: 'person';
+    person: ObjectRow;
+} | {
+    class: 'app';
+    app: ObjectRow;
+    scopes: readonly string[];
+    /** The person this call acts for: the `sub` of the member's call token. Absent for a runtime-owned call (cron, forwarded). */
+    sub?: string;
+    /** The launched `scopes` list exactly as given (null/absent = none was given). Unlike `scopes` it is not filtered through the grant, so it keeps the own-app memory strings a grant never holds; it alone narrows access to the app's own documents. */
+    launched?: readonly string[] | null;
+    /** A cron command's run place (its origin run, and whether that run is isolated): it reads its own app's nodes under run confinement, as a node of that run does. Absent for the app's server. */
+    place?: {
+        run: string;
+        isolated: boolean;
+    };
+} | {
+    class: 'node';
+    node: ObjectRow;
+    app: ObjectRow;
+    scopes: readonly string[] | null;
+    cwd: string;
+    /** The launched `scopes` list as given (see the app reader); null/absent = the run was launched with no list. */
+    launched?: readonly string[] | null;
+    /** The repos enclosing `cwd`, nearest first; `checkouts` pairs each with its checkout root. Only these are repos the node
+     *  "works in": `--owner repo` follows them; rule `if: {repo}` follows these plus `projectRepos`; read and write access
+     *  to a repo's documents follow `checkouts` plus `projectCheckouts`, each gated by the node's file permissions. */
+    repos: ObjectRow[];
+    checkouts: Checkout[];
+    /** The repos of the profile's project paths that do not enclose `cwd`, in manifest order: in the node's view, readable and, where its file permissions allow writing the checkout, changeable; not worked in. */
+    projectRepos: ObjectRow[];
+    projectCheckouts: Checkout[];
+    profile: ObjectRow | null;
+} | {
+    class: 'object';
+    object: ObjectRow; /** A stub reader's saved run place (from its envelope); run-confines it within its own app. */
+    place?: {
+        run: string;
+        isolated: boolean;
+    }; /** Identity alias for shared actor access; never a node principal. */
+    node: ObjectRow;
+    app: ObjectRow;
+    scopes: readonly string[] | null;
+    launched?: readonly string[] | null;
+    repos: ObjectRow[];
+    owner: ObjectRow;
+};
+export type RuleOn = 'boot' | 'workspace-open' | 'file-read' | 'document-read' | 'command' | 'pre-command' | 'slash-command';
+export interface RuleSpec {
+    on: RuleOn;
+    match?: string[];
+    matchFrontmatter?: Record<string, unknown>;
+    if?: unknown;
+    deliver: 'name' | 'preview' | 'content';
+}
+export interface Revision {
+    rev_id: string;
+    seq: number;
+    number: number;
+    body_hash: string;
+    /** the author object's id; null for revisions imported from another runtime */
+    author: string | null;
+    rationale: string | null;
+    verbatim: boolean;
+    created_at: string;
+    /** The app principal (`app:<x>`) that made the revision; null for a person's own revision and for imported ones. */
+    acting_app: string | null;
+    /** The person (`user:<id>`) the revision was made for; null for imported ones. */
+    acting_for: string | null;
+    /** parent rev_ids */
+    parents: string[];
+}

package/dist/core/graph/types.js

@@ -0,0 +1,10 @@
+/** Shared types of the canvas graph: documents, nodes, jobs and their owners as rows of `objects`. */
+/** `friends` was a privacy level until cycle 3. Data from an old source (a peer on an older release, a plugin package, a
+ *  legacy canvas or frontmatter) that still says `friends` reads as `private`; a `/v1` write or CLI flag naming it stays refused. */
+export const readLegacyPrivacy = (value) => (value === 'friends' ? 'private' : value);
+export const DEFAULT_LISTEN = [
+    { threshold: 10, delivery: 'interrupt' },
+    { threshold: 7, delivery: 'steer' },
+    { threshold: 5, delivery: 'after-turn' },
+    { threshold: 3, delivery: 'next-turn' },
+];