@crouton-kit/crouter 0.3.11 → 0.3.13

package/dist/core/__tests__/argv-parser.test.js

@@ -101,6 +101,24 @@ describe('parseArgv: positional', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// parseArgv — stdin satisfied by a positional argument
+// ---------------------------------------------------------------------------
+describe('parseArgv: stdin-as-positional', () => {
+    const params = [
+        { kind: 'stdin', name: 'prompt', required: true, constraint: 'Task.' },
+        { kind: 'flag', name: 'agent', type: 'string', required: false, default: 'general', constraint: '' },
+    ];
+    test('a positional token satisfies a stdin param', async () => {
+        const result = await parseArgv(params, ['--agent', 'general', 'Say hi']);
+        assert.equal(result['prompt'], 'Say hi');
+        assert.equal(result['agent'], 'general');
+    });
+    test('positional-as-stdin works with the positional before flags', async () => {
+        const result = await parseArgv(params, ['Say hi', '--agent', 'general']);
+        assert.equal(result['prompt'], 'Say hi');
+    });
+});
+// ---------------------------------------------------------------------------
 // parseArgv — context-file
 // ---------------------------------------------------------------------------
 describe('parseArgv: context-file', () => {
@@ -167,7 +185,7 @@ describe('renderLeafArgv: help format', () => {
     });
     test('contains Output section', () => {
         const out = renderLeafArgv(help);
-        assert.ok(out.includes('Output (stdout, JSON)'));
+        assert.ok(out.includes('Output (fields carried in the rendered result)'));
     });
     test('contains Effects section', () => {
         const out = renderLeafArgv(help);

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -0,0 +1,100 @@
+// Tests for the canvas-node inbox watcher pi extension.
+//
+// Run with: node --import tsx/esm --test src/core/__tests__/canvas-inbox-watcher.test.ts
+//
+// Focus: a finished node (push final → InboxEntry kind 'final') must STEER a
+// mid-stream subscriber, not queue behind its current turn as a follow-up.
+import { test, describe, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
+import { appendInbox } from '../feed/inbox.js';
+// Mirror the watcher's internal cadence (TICK_MS=800, DEBOUNCE_MS=1000): allow a
+// resolve+seed tick, a read tick, and the debounce window before asserting.
+const TICK_MS = 800;
+const DEBOUNCE_MS = 1000;
+const SETTLE_MS = TICK_MS * 2 + DEBOUNCE_MS + 500;
+let origHome;
+let origNode;
+const homes = [];
+const disposers = [];
+/** Point CRTR_HOME at a fresh temp canvas root and bind CRTR_NODE_ID. */
+function freshNode(nodeId) {
+    const home = join(tmpdir(), `crtr-canvas-watcher-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(home, { recursive: true });
+    homes.push(home);
+    process.env['CRTR_HOME'] = home;
+    process.env['CRTR_NODE_ID'] = nodeId;
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+before(() => {
+    origHome = process.env['CRTR_HOME'];
+    origNode = process.env['CRTR_NODE_ID'];
+});
+afterEach(() => {
+    while (disposers.length > 0)
+        disposers.pop()();
+});
+after(() => {
+    if (origHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = origHome;
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+    for (const h of homes) {
+        try {
+            rmSync(h, { recursive: true, force: true });
+        }
+        catch { /* noop */ }
+    }
+});
+describe('canvas inbox watcher — finished-node delivery', () => {
+    test('mid-stream: a finished node (kind final) steers the subscriber', async () => {
+        freshNode('node-final');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // Subscriber is actively streaming when the worker finishes.
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-final', { from: 'child-1', tier: 'normal', kind: 'final', label: 'all done' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1, 'one coalesced injection');
+        assert.equal(pi.injected[0].deliverAs, 'steer', 'a finished node steers, not follows up');
+    });
+    test('mid-stream: a routine update still follows up', async () => {
+        freshNode('node-update');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-update', { from: 'child-2', tier: 'normal', kind: 'update', label: 'still working' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1);
+        assert.equal(pi.injected[0].deliverAs, 'followUp', 'a normal update is not urgent → followUp');
+    });
+    test('idle: a finished node triggers a fresh turn (no deliverAs)', async () => {
+        freshNode('node-idle');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // No agent_start fired → watcher treats the node as idle.
+        await wait(TICK_MS + 100);
+        appendInbox('node-idle', { from: 'child-3', tier: 'normal', kind: 'final', label: 'done while idle' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1);
+        assert.equal(pi.injected[0].deliverAs, undefined, 'idle → sendUserMessage triggers a turn, no deliverAs');
+    });
+});

package/dist/core/__tests__/canvas.test.js

@@ -0,0 +1,154 @@
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, getRow, updateNode, setStatus, listNodes, subscribe, unsubscribe, setSubscriptionActive, recordSpawn, subscribersOf, subscriptionsOf, view, hasActiveLiveSubscription, rebuildIndex, } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { contextDir, reportsDir, jobDir, nodeMetaPath, } from '../canvas/paths.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-canvas-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    // Fresh db + dirs per test for isolation.
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('createNode scaffolds dirs, writes meta, indexes the row', () => {
+    createNode(node('a'));
+    assert.ok(existsSync(contextDir('a')));
+    assert.ok(existsSync(reportsDir('a')));
+    assert.ok(existsSync(jobDir('a')));
+    assert.ok(existsSync(nodeMetaPath('a')));
+    const meta = getNode('a');
+    assert.equal(meta?.node_id, 'a');
+    assert.equal(meta?.kind, 'general');
+    const row = getRow('a');
+    assert.equal(row?.node_id, 'a');
+    assert.equal(row?.status, 'active');
+});
+test('meta.json is the source of truth on disk', () => {
+    createNode(node('a', { kind: 'developer' }));
+    const raw = JSON.parse(readFileSync(nodeMetaPath('a'), 'utf8'));
+    assert.equal(raw.kind, 'developer');
+});
+test('updateNode merges meta and re-indexes the row', () => {
+    createNode(node('a'));
+    updateNode('a', { mode: 'orchestrator', lifecycle: 'resident' });
+    assert.equal(getNode('a')?.mode, 'orchestrator');
+    assert.equal(getRow('a')?.lifecycle, 'resident');
+    // unspecified fields preserved
+    assert.equal(getNode('a')?.kind, 'general');
+});
+test('setStatus updates both meta and row', () => {
+    createNode(node('a'));
+    setStatus('a', 'done');
+    assert.equal(getNode('a')?.status, 'done');
+    assert.equal(getRow('a')?.status, 'done');
+});
+test('listNodes filters by status', () => {
+    createNode(node('a', { status: 'active' }));
+    createNode(node('b', { status: 'idle' }));
+    createNode(node('c', { status: 'done' }));
+    assert.equal(listNodes().length, 3);
+    assert.deepEqual(listNodes({ status: ['active', 'idle'] }).map((n) => n.node_id).sort(), ['a', 'b']);
+});
+test('subscription spine: subscribersOf / subscriptionsOf', () => {
+    createNode(node('mgr'));
+    createNode(node('w1'));
+    createNode(node('w2'));
+    // mgr subscribes to both workers (parent watches children)
+    subscribe('mgr', 'w1');
+    subscribe('mgr', 'w2', false);
+    // w1's subscribers = who a w1 push fans out to = mgr
+    assert.deepEqual(subscribersOf('w1').map((s) => s.node_id), ['mgr']);
+    // mgr's subscriptions = its reports = both workers
+    const subs = subscriptionsOf('mgr');
+    assert.deepEqual(subs.map((s) => s.node_id).sort(), ['w1', 'w2']);
+    assert.equal(subs.find((s) => s.node_id === 'w1')?.active, true);
+    assert.equal(subs.find((s) => s.node_id === 'w2')?.active, false);
+});
+test('subscribe is idempotent and flips active', () => {
+    createNode(node('a'));
+    createNode(node('b'));
+    subscribe('a', 'b', true);
+    subscribe('a', 'b', false); // re-subscribe updates the flag, no dup
+    const subs = subscriptionsOf('a');
+    assert.equal(subs.length, 1);
+    assert.equal(subs[0].active, false);
+    setSubscriptionActive('a', 'b', true);
+    assert.equal(subscriptionsOf('a')[0].active, true);
+    unsubscribe('a', 'b');
+    assert.equal(subscriptionsOf('a').length, 0);
+});
+test('view = transitive closure down the subscription spine', () => {
+    // root → mid → leaf, plus root → sib
+    for (const id of ['root', 'mid', 'leaf', 'sib'])
+        createNode(node(id));
+    subscribe('root', 'mid');
+    subscribe('root', 'sib');
+    subscribe('mid', 'leaf');
+    assert.deepEqual(view('root').sort(), ['leaf', 'mid', 'sib']);
+    assert.deepEqual(view('mid'), ['leaf']);
+});
+test('view is cycle-safe', () => {
+    createNode(node('a'));
+    createNode(node('b'));
+    subscribe('a', 'b');
+    subscribe('b', 'a');
+    assert.deepEqual(view('a'), ['b']);
+});
+test('hasActiveLiveSubscription: the stop-guard primitive', () => {
+    createNode(node('mgr'));
+    createNode(node('child', { status: 'active' }));
+    // no subscription yet
+    assert.equal(hasActiveLiveSubscription('mgr'), false);
+    subscribe('mgr', 'child', true);
+    assert.equal(hasActiveLiveSubscription('mgr'), true); // active sub to a live node
+    setStatus('child', 'done');
+    assert.equal(hasActiveLiveSubscription('mgr'), false); // child no longer live
+    setStatus('child', 'active');
+    setSubscriptionActive('mgr', 'child', false);
+    assert.equal(hasActiveLiveSubscription('mgr'), false); // passive sub doesn't count
+});
+test('recordSpawn writes the audit-only spawned_by edge', () => {
+    createNode(node('parent'));
+    createNode(node('child', { parent: 'parent' }));
+    recordSpawn('child', 'parent');
+    // spawned_by does not appear in the subscription spine
+    assert.equal(subscriptionsOf('child').length, 0);
+    assert.equal(subscribersOf('parent').length, 0);
+});
+test('rebuildIndex reconstructs node rows from on-disk metas', () => {
+    createNode(node('a', { parent: null }));
+    createNode(node('b', { parent: 'a' }));
+    // wipe just the db, keep the node dirs
+    closeDb();
+    rmSync(join(home, 'canvas.db'), { force: true });
+    rmSync(join(home, 'canvas.db-wal'), { force: true });
+    rmSync(join(home, 'canvas.db-shm'), { force: true });
+    assert.equal(getRow('a'), null); // gone from index
+    rebuildIndex();
+    assert.equal(getRow('a')?.node_id, 'a');
+    assert.equal(getRow('b')?.parent, 'a');
+});

package/dist/core/__tests__/reset.test.js

@@ -0,0 +1,105 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/reset.test.ts
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, subscribe, setStatus, subscriptionsOf, view, } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { reportsDir, inboxPath } from '../canvas/paths.js';
+import { roadmapPath } from '../runtime/roadmap.js';
+import { resetRoot } from '../runtime/reset.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-reset-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('resetRoot empties the root view, reaps descendants, and wipes working state', () => {
+    // root → child → grandchild (mirrors a parent that subscribes to its workers)
+    createNode(node('root', { parent: null, lifecycle: 'resident', mode: 'orchestrator', pi_session_id: 'old-sess' }));
+    createNode(node('child', { parent: 'root' }));
+    createNode(node('grand', { parent: 'child' }));
+    subscribe('root', 'child', true);
+    subscribe('child', 'grand', true);
+    // Root accumulated working state.
+    writeFileSync(roadmapPath('root'), '# Roadmap\nold goal\n');
+    writeFileSync(inboxPath('root'), '{"ts":"x","from":"child","tier":"normal","kind":"update","label":"hi"}\n');
+    writeFileSync(join(reportsDir('root'), '20260101T000000-update.md'), 'stale report');
+    assert.equal(view('root').length, 2, 'precondition: root sees 2 descendants');
+    const res = resetRoot('root', 'new-sess');
+    assert.equal(res.reset, true);
+    assert.deepEqual(res.detached, ['child'], 'root detaches its direct subscription');
+    assert.deepEqual(res.reaped.sort(), ['child', 'grand'], 'whole sub-DAG reaped');
+    // Graph is empty from the root's view.
+    assert.equal(view('root').length, 0, 'root view is empty after reset');
+    assert.equal(subscriptionsOf('root').length, 0, 'no outgoing edges remain');
+    // Descendants are dead (daemon will skip them).
+    assert.equal(getNode('child')?.status, 'dead');
+    assert.equal(getNode('grand')?.status, 'dead');
+    // Working state wiped.
+    assert.equal(existsSync(roadmapPath('root')), false, 'roadmap wiped');
+    assert.equal(existsSync(inboxPath('root')), false, 'inbox wiped');
+    // Root reset to a pristine base resident, rebound to the new session id.
+    const root = getNode('root');
+    assert.equal(root?.mode, 'base');
+    assert.equal(root?.lifecycle, 'resident');
+    assert.equal(root?.status, 'active');
+    assert.equal(root?.intent, null);
+    assert.equal(root?.pi_session_id, 'new-sess');
+    assert.ok(root?.launch, 'a fresh base launch spec was written');
+});
+test('resetRoot on a non-root only refreshes the session id (no reap)', () => {
+    createNode(node('root', { parent: null }));
+    createNode(node('child', { parent: 'root', pi_session_id: 'old' }));
+    subscribe('root', 'child', true);
+    subscribe('child', 'root', false); // contrived: ensure child has an outgoing edge
+    const res = resetRoot('child', 'fresh');
+    assert.equal(res.reset, false, 'a non-root is not a graph reset');
+    assert.deepEqual(res.reaped, []);
+    assert.deepEqual(res.detached, []);
+    assert.equal(getNode('child')?.pi_session_id, 'fresh', 'session id still refreshed');
+    assert.equal(getNode('child')?.status, 'active', 'child not reaped');
+    // The root that subscribes to the child is untouched.
+    assert.equal(getNode('root')?.status, 'active');
+});
+test('resetRoot is a no-op for an unknown node', () => {
+    const res = resetRoot('ghost', 'x');
+    assert.equal(res.reset, false);
+    assert.deepEqual(res.reaped, []);
+    assert.deepEqual(res.detached, []);
+});
+test('reaped descendants keep their meta on disk (orphaned, not deleted)', () => {
+    createNode(node('root', { parent: null }));
+    createNode(node('child', { parent: 'root' }));
+    subscribe('root', 'child', true);
+    setStatus('child', 'idle');
+    resetRoot('root', 'new');
+    // The node record persists (we detach + mark dead, we don't delete the node).
+    const child = getNode('child');
+    assert.ok(child, 'child meta still on disk');
+    assert.equal(child?.status, 'dead');
+    // It is just unreachable from the root.
+    assert.equal(view('root').length, 0);
+});

package/dist/core/canvas/attention.d.ts

@@ -0,0 +1,24 @@
+export interface AskEntry {
+    node_id: string;
+    name: string;
+    cwd: string;
+    count: number;
+}
+/**
+ * Count pending asks for the cwd of a single node.
+ * Returns 0 when the node is unknown or humanloop is unavailable.
+ */
+export declare function countAsks(nodeId: string): number;
+/**
+ * Pending asks for all nodes reachable in the subscription sub-DAG from
+ * `rootId` (including root itself). De-duped by cwd: when multiple nodes
+ * share a cwd the first one encountered claims the entry.
+ *
+ * Returns only entries with count > 0.
+ */
+export declare function pendingAsksForView(rootId: string): AskEntry[];
+/**
+ * Pending asks across the entire canvas — every distinct cwd among all known
+ * nodes. Returns only entries with count > 0.
+ */
+export declare function asksAcrossCanvas(): AskEntry[];

package/dist/core/canvas/attention.js

@@ -0,0 +1,94 @@
+// attention.ts — pending human-ask counters across the canvas.
+//
+// Human asks are stored per-cwd, not per-node (interactionsRoot is keyed by
+// the cwd the agent ran in, same pattern as humanloop's human list command).
+// A cwd can be shared by multiple nodes, so we de-dup on cwd before summing to
+// avoid counting the same pending ask N times.
+//
+// All public functions are best-effort: scanInbox failures return 0 / empty.
+// Callers are display code (dashboard, attention queue) that must not blow up
+// on a cold canvas or missing humanloop state.
+import { scanInbox } from '@crouton-kit/humanloop';
+import { interactionsRoot } from '../artifact.js';
+import { getNode, listNodes, view } from './canvas.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Count pending asks for a single cwd root. Never throws.
+ *
+ * When `nodeId` is given, count only asks raised by THAT node — humanloop
+ * stamps `deck.source.nodeId` with the originating CRTR_NODE_ID, so two nodes
+ * sharing a cwd no longer pollute each other's count. Asks with no stamp
+ * (legacy, or raised outside a canvas node) are not attributable to any node
+ * and are excluded from the per-node count. Read via a cast so this doesn't
+ * hard-depend on a humanloop type bump.
+ */
+function countForCwd(cwd, nodeId) {
+    try {
+        const items = scanInbox([interactionsRoot(cwd)]);
+        if (nodeId === undefined)
+            return items.length;
+        return items.filter((i) => i.source?.nodeId === nodeId).length;
+    }
+    catch {
+        // humanloop not installed, or interactions dir doesn't exist — both fine.
+        return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Count pending asks for the cwd of a single node.
+ * Returns 0 when the node is unknown or humanloop is unavailable.
+ */
+export function countAsks(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null)
+        return 0;
+    return countForCwd(node.cwd, nodeId);
+}
+/**
+ * Pending asks for all nodes reachable in the subscription sub-DAG from
+ * `rootId` (including root itself). De-duped by cwd: when multiple nodes
+ * share a cwd the first one encountered claims the entry.
+ *
+ * Returns only entries with count > 0.
+ */
+export function pendingAsksForView(rootId) {
+    // view() returns children only (excludes root), so prepend root.
+    const ids = [rootId, ...view(rootId)];
+    const seen = new Map(); // cwd → entry
+    for (const id of ids) {
+        const node = getNode(id);
+        if (node === null)
+            continue;
+        if (seen.has(node.cwd))
+            continue; // already counted this cwd
+        const count = countForCwd(node.cwd);
+        if (count === 0) {
+            // Still mark the cwd seen so later nodes with the same cwd are skipped.
+            seen.set(node.cwd, { node_id: id, name: node.name, cwd: node.cwd, count: 0 });
+        }
+        else {
+            seen.set(node.cwd, { node_id: id, name: node.name, cwd: node.cwd, count });
+        }
+    }
+    return Array.from(seen.values()).filter((e) => e.count > 0);
+}
+/**
+ * Pending asks across the entire canvas — every distinct cwd among all known
+ * nodes. Returns only entries with count > 0.
+ */
+export function asksAcrossCanvas() {
+    const rows = listNodes();
+    const seen = new Map(); // cwd → entry
+    for (const row of rows) {
+        if (seen.has(row.cwd))
+            continue;
+        const count = countForCwd(row.cwd);
+        seen.set(row.cwd, { node_id: row.node_id, name: row.name, cwd: row.cwd, count });
+    }
+    return Array.from(seen.values()).filter((e) => e.count > 0);
+}

package/dist/core/canvas/canvas.d.ts

@@ -0,0 +1,40 @@
+import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
+/** Create a node: scaffold its dirs, write meta.json, index the row. */
+export declare function createNode(meta: NodeMeta): NodeMeta;
+/** The canonical node record (from meta.json), or null if unknown. */
+export declare function getNode(nodeId: string): NodeMeta | null;
+/** The indexed row (from the db) — cheap for queries that don't need full meta. */
+export declare function getRow(nodeId: string): NodeRow | null;
+/** Merge a patch into a node's meta.json and re-index its row. */
+export declare function updateNode(nodeId: string, patch: Partial<NodeMeta>): NodeMeta;
+/** Convenience for the most common mutation. */
+export declare function setStatus(nodeId: string, status: NodeStatus): void;
+/** All rows, optionally filtered by status. */
+export declare function listNodes(filter?: {
+    status?: NodeStatus | NodeStatus[];
+}): NodeRow[];
+/** Record `A subscribes_to B` — A receives B's output. active=true wakes A on
+ *  emit; passive accumulates pointers without a wake. Mutable; callable by anyone. */
+export declare function subscribe(subscriber: string, publisher: string, active?: boolean): void;
+/** Drop a subscription edge. */
+export declare function unsubscribe(subscriber: string, publisher: string): void;
+/** Flip an existing subscription's wake behavior. */
+export declare function setSubscriptionActive(subscriber: string, publisher: string, active: boolean): void;
+/** Record the audit-only `child spawned_by parent` edge. */
+export declare function recordSpawn(child: string, parent: string): void;
+/** Who subscribes to `publisher` — the targets a push fans out to. */
+export declare function subscribersOf(publisher: string): SubscriptionRef[];
+/** Who `subscriber` subscribes to — its reports / the nodes feeding it. */
+export declare function subscriptionsOf(subscriber: string): SubscriptionRef[];
+/** A "view": every node whose output cascades up to `root` via subscriptions —
+ *  the subscription sub-DAG reachable downward (root → its reports → theirs …).
+ *  Returns ids excluding root, in BFS order. Cycle-safe. */
+export declare function view(root: string): string[];
+/** Stop-guard primitive: does this node hold an *active* subscription to a node
+ *  that's still live (active|idle) — i.e. something that can actually wake it?
+ *  If so, stopping is a legitimate await; if not, it must finish or escalate. */
+export declare function hasActiveLiveSubscription(nodeId: string): boolean;
+/** Rebuild node rows from on-disk metas (the db node table is a derived index).
+ *  Edges are left intact — subscribes_to is db-authoritative; spawned_by is
+ *  re-derived from each meta's `parent`. */
+export declare function rebuildIndex(): void;