@heuresis/mcp 1.0.0-rc.1

package/dist/operators/triz.js

@@ -0,0 +1,23 @@
+// TRIZ family catalog — verbatim duplicate of `src/operators/triz.ts` so the
+// MCP package builds without reaching into the main app's source tree. Derives
+// 40 OperatorDefinitions from the principles table in `triz-matrix.ts`.
+import { TRIZ_PRINCIPLES } from './triz-matrix.js';
+function buildPromptFragment(p) {
+    const examples = p.examples && p.examples.length > 0
+        ? ` Reference examples from the canonical literature: ${p.examples.join('; ')}.`
+        : '';
+    return `Apply TRIZ Inventive Principle #${p.num} — ${p.name}. Doctrine: ${p.doctrine}${examples} Propose 3–5 concrete partitions of the current concept that each embody this principle. For every partition, name precisely what is being transformed (subject), how the principle reshapes it (mechanism), and what new behavior or affordance results (consequence). Avoid vague restatements; every partition must be implementable.`;
+}
+export const TRIZ_OPERATORS = TRIZ_PRINCIPLES.map((p) => ({
+    family: 'TRIZ',
+    key: `principle_${String(p.num).padStart(2, '0')}_${p.key}`,
+    name: p.name,
+    glyph: String(p.num).padStart(2, '0'),
+    oneLiner: p.oneLiner,
+    doctrine: p.doctrine,
+    promptFragment: buildPromptFragment(p),
+}));
+export const TRIZ_KEYS_BY_NUMBER = TRIZ_PRINCIPLES.reduce((acc, p, i) => {
+    acc[p.num] = TRIZ_OPERATORS[i].key;
+    return acc;
+}, {});

package/dist/operators/types.js

@@ -0,0 +1,10 @@
+// Operator type — narrow copy of `src/types/operators.ts` so the MCP package
+// builds with no reach into the main app's source tree. The shape is
+// intentionally identical; if the webapp's OperatorDefinition gains fields,
+// keep this in sync by hand.
+//
+// `family` is the same string union the webapp uses. We keep it loose (string)
+// here so a future operator family added to the webapp doesn't break the MCP
+// build — the runtime catalog is the source of truth for which families are
+// actually wired up.
+export {};

package/dist/prompt/compose.js

@@ -0,0 +1,141 @@
+// Prompt composer — port of `src/prompt/compose.ts` adapted to read the MCP's
+// cloud row shapes (snake_case via supabase-js) instead of the webapp's
+// camelCase domain types. The instruction text, response template, and rule
+// list are kept verbatim so the parser's expectations line up.
+//
+// The webapp's composer also blends in a <context> graph-awareness block and
+// a <files> prefix. The MCP composes the bare minimum: brief, ancestry,
+// target, knowledge pool, operator, plus the operator-specific inputs block.
+// File-context retrieval is a separate tool (find_in_files) that ships in
+// Agent B's tool-parity wave; not folded in here.
+const RESPONSE_TEMPLATE = `{
+  "partitions": [
+    {
+      "label": "STANDALONE concept title — 2–5 words, ≤ 60 chars, NO parent prefix, no trailing period",
+      "description": "1–2 sentences, ≤ 280 chars",
+      "partitionAttribute": "≤ 5 words for the distinguishing attribute",
+      "rationale": "1–3 sentences citing the operator and any K used",
+      "kReferences": ["k_id_or_empty"],
+      "selfCritique": "main weakness or assumption",
+      "children": [
+        {
+          "label": "STANDALONE sub-concept title — same rules; do NOT prefix with this partition's label either",
+          "description": "1–2 sentences, ≤ 280 chars",
+          "partitionAttribute": "≤ 5 words",
+          "rationale": "1–3 sentences",
+          "kReferences": [],
+          "selfCritique": "main weakness or assumption"
+        }
+      ]
+    }
+  ],
+  "newKnowledgeProposed": [
+    { "title": "fact title", "body": "1–2 sentences", "tags": ["tag1"] }
+  ],
+  "operatorNotes": "one line on how the operator fit (optional)"
+}`;
+function pathBlock(path) {
+    return path
+        .map((n, i) => {
+        const indent = '  '.repeat(i);
+        const head = i === 0 ? 'ROOT' : `LVL ${i}`;
+        const attr = n.partition_attribute ? `  attribute: ${n.partition_attribute}` : '';
+        const desc = n.description ? `\n${indent}  description: ${n.description}` : '';
+        return `${indent}- [${head}] ${n.label}${attr}${desc}`;
+    })
+        .join('\n');
+}
+function knowledgeBlock(knowledge) {
+    if (knowledge.length === 0)
+        return '(no knowledge items pinned)';
+    return knowledge
+        .map((k) => `- id=${k.id} tags=[${(k.tags ?? []).join(', ')}] :: ${k.label}\n    ${k.description}`)
+        .join('\n');
+}
+function inputsBlock(inputs) {
+    return inputs
+        .map((n) => `  <input id="${n.id}">\n    <label>${n.label}</label>${n.description ? `\n    <description>${n.description}</description>` : ''}\n  </input>`)
+        .join('\n');
+}
+function branchBlock(branch) {
+    if (branch.existingChildren.length === 0) {
+        return `<branch parent="${branch.parentLabel}">\n  (no existing children — propose first partitions)\n</branch>`;
+    }
+    const children = branch.existingChildren
+        .map((c) => `  <child>\n    <label>${c.label}</label>${c.description ? `\n    <desc>${c.description}</desc>` : ''}\n  </child>`)
+        .join('\n');
+    return `<branch parent="${branch.parentLabel}">\n${children}\n</branch>`;
+}
+function contradictionBlock(c) {
+    const principles = c.principles
+        .map((p) => `  - #${p.num} ${p.name}: ${p.doctrine}`)
+        .join('\n');
+    return `<contradiction>
+  improving: ${c.improvingName}
+  worsening: ${c.worseningName}
+  matrix_principles:
+${principles}
+</contradiction>`;
+}
+export function composePrompt(input) {
+    const { project, ancestry, target, operator, knowledge, freeformAngle, combineInputs, branch, contradiction, } = input;
+    const angleBlock = freeformAngle &&
+        (operator.family === 'FREEFORM' ||
+            operator.family === 'COMBINE' ||
+            operator.family === 'EXPLORE')
+        ? `\n<angle>\n${freeformAngle}\n</angle>\n`
+        : '';
+    const inputsXml = operator.family === 'COMBINE' && combineInputs && combineInputs.length > 0
+        ? `\n<inputs>\n${inputsBlock(combineInputs)}\n</inputs>\n`
+        : '';
+    const branchXml = operator.family === 'EXPLORE' && branch ? `\n${branchBlock(branch)}\n` : '';
+    const contradictionXml = operator.family === 'CONTRADICTION' && contradiction
+        ? `\n${contradictionBlock(contradiction)}\n`
+        : '';
+    return `You are assisting an inventive design session structured by C-K theory. The user is growing a graph of concepts (C) drawing on a pool of validated knowledge (K). You will generate a set of new partitions of the TARGET concept by applying the requested operator from ASIT/TRIZ.
+
+<brief>
+${project.brief}
+</brief>
+
+<concept_path_root_to_target>
+${pathBlock(ancestry)}
+</concept_path_root_to_target>
+
+<target_concept>
+id: ${target.id}
+label: ${target.label}
+description: ${target.description || '(no description)'}
+notes: ${target.notes || '(none)'}
+</target_concept>
+
+<knowledge_pool>
+${knowledgeBlock(knowledge)}
+</knowledge_pool>
+
+<operator>
+family: ${operator.family}
+key: ${operator.key}
+name: ${operator.name}
+doctrine: ${operator.doctrine}
+</operator>
+${inputsXml}${branchXml}${contradictionXml}${angleBlock}
+<instructions>
+${operator.promptFragment}
+
+Rules:
+- Produce 3–5 partitions at the top level, each genuinely distinct, each adding a clear new attribute to the TARGET concept. (The optional \`children\` array below adds depth-2 nodes; it does NOT count toward the 3–5 top-level requirement.)
+- Labels MUST be STANDALONE concept titles. Do NOT prefix labels with the parent concept's label. For example, if the parent is "Test", do NOT write labels like "Test by destruction" or "Test for X" — just write "Destruction" or "X". The label should make sense on its own; the parent context is implicit from the graph structure. This rule applies to EVERY label in the response, including children (a child's label must not contain its immediate parent partition's label either).
+- Labels MUST be short: 2–5 words, ≤ 60 characters, no trailing punctuation. The label is a concept title, not a sentence. Put long-form prose in description/rationale, not in label.
+- Each partition MAY optionally include a \`children\` array of 1–4 sub-partitions, when the partition naturally decomposes further into a clearly distinct sub-axis. Children follow the same shape (label, description, partitionAttribute, rationale, kReferences, selfCritique). Do NOT nest beyond one level — a child must NEVER have its own \`children\` array. Omit \`children\` entirely when no useful sub-decomposition exists; do not pad.
+- Stay faithful to the operator's doctrine. If the operator forbids alien components (ASIT closed-world), do not introduce them.
+- For each partition, cite by id any knowledge item from <knowledge_pool> you actually used in kReferences. Empty array if none.
+- Use selfCritique to surface the strongest assumption or risk in that partition (do not flatter the idea).
+- If you needed a fact you did not have, propose it via newKnowledgeProposed (1–3 items max). Do NOT invent specific numbers as facts; phrase as questions to verify.
+- Output ONLY a single JSON object, matching this shape exactly. No prose before or after, no markdown fences.
+</instructions>
+
+<response_shape>
+${RESPONSE_TEMPLATE}
+</response_shape>`;
+}

package/dist/prompt/parse.js

@@ -0,0 +1,99 @@
+// JSON-extraction + schema-validation for LLM operator responses. Verbatim
+// duplicate of `src/prompt/parse.ts` so the MCP can validate provider output
+// without importing from the main app.
+//
+// The scanner tolerates ```json fences and stray prose because providers
+// (especially OpenRouter pass-throughs) sometimes wrap JSON even when
+// response_format=json_object is requested.
+import { llmResponseSchema } from './schema.js';
+const FENCE = /```(?:json)?\s*([\s\S]*?)```/i;
+function stripFence(input) {
+    const trimmed = input.trim();
+    const m = trimmed.match(FENCE);
+    if (m)
+        return m[1].trim();
+    return trimmed;
+}
+function findJsonObject(input) {
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escape = false;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === '\\') {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0 && start !== -1) {
+                return { text: input.slice(start, i + 1), truncated: false };
+            }
+        }
+    }
+    return { text: null, truncated: start !== -1 };
+}
+export function parseLlmResponse(rawInput) {
+    const cleaned = stripFence(rawInput);
+    let candidate;
+    let truncated = false;
+    if (cleaned.startsWith('{')) {
+        const scan = findJsonObject(cleaned);
+        candidate = scan.text;
+        truncated = scan.truncated;
+    }
+    else {
+        const scan = findJsonObject(cleaned);
+        candidate = scan.text;
+        truncated = scan.truncated;
+    }
+    if (!candidate) {
+        return {
+            ok: false,
+            error: truncated
+                ? 'Response was truncated mid-JSON — likely hit the max-tokens limit. Retry with a higher-tier model.'
+                : 'No JSON object found in the model response.',
+            raw: rawInput,
+        };
+    }
+    let json;
+    try {
+        json = JSON.parse(candidate);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: `JSON.parse failed: ${e.message}`,
+            raw: rawInput,
+        };
+    }
+    const result = llmResponseSchema.safeParse(json);
+    if (!result.success) {
+        return {
+            ok: false,
+            error: `Schema validation failed: ${result.error.issues
+                .map((i) => `${i.path.join('.')} — ${i.message}`)
+                .join('; ')}`,
+            raw: rawInput,
+        };
+    }
+    return { ok: true, data: result.data, raw: rawInput };
+}

package/dist/prompt/schema.js

@@ -0,0 +1,30 @@
+// LLM response schema — duplicate of `src/prompt/schema.ts` so the MCP can
+// parse operator output without reaching into the main app. Keep in sync if
+// the webapp tightens limits (label ≤ 60, etc.) — the parser will accept
+// either; the webapp is the strict gate at write time.
+import { z } from 'zod';
+const partitionBaseShape = {
+    label: z.string().min(1).max(60),
+    description: z.string().min(1).max(600),
+    partitionAttribute: z.string().min(1).max(80),
+    rationale: z.string().min(1).max(800),
+    kReferences: z.array(z.string()).default([]),
+    selfCritique: z.string().max(600).optional().default(''),
+};
+// Leaf — depth-2 children. No further nesting.
+export const partitionLeafSchema = z.object(partitionBaseShape);
+// Root — depth-1 partitions. May optionally carry up to 4 children.
+export const partitionSchema = z.object({
+    ...partitionBaseShape,
+    children: z.array(partitionLeafSchema).max(4).optional(),
+});
+export const newKnowledgeSchema = z.object({
+    title: z.string().min(1).max(160),
+    body: z.string().min(1).max(800),
+    tags: z.array(z.string()).default([]),
+});
+export const llmResponseSchema = z.object({
+    partitions: z.array(partitionSchema).min(1).max(8),
+    newKnowledgeProposed: z.array(newKnowledgeSchema).default([]),
+    operatorNotes: z.string().max(400).optional().default(''),
+});

package/dist/realtime.js

@@ -0,0 +1,192 @@
+// Heuresis MCP - Supabase Realtime CDC subscription (Phase 19.8).
+//
+// We subscribe to row-level changes on the four workspace tables that the
+// webapp also watches: nodes, edges, projects, ideas. When a change lands we
+// fire a single callback so the MCP server can notify its client (Claude
+// Desktop, Claude Code, Cursor, etc.) that the workspace state has moved.
+//
+// One channel per process, filtered by workspace_id. RLS still applies to
+// Realtime payloads, so even if a stray row leaks through the publication a
+// non-member of the workspace would not see it. The filter is belt-and-braces.
+//
+// Reconnect behavior:
+//   supabase-js auto-reconnects on transient socket drops. We hook the
+//   subscribe-status callback and re-emit a "resync" event on every
+//   SUBSCRIBED transition that follows a CLOSED / CHANNEL_ERROR / TIMED_OUT
+//   state, so the client knows it may have missed updates while offline and
+//   should refetch.
+//
+// CLI flag:
+//   The default is ON. Users can opt out with `--no-realtime` (one-shot for
+//   this process) or persistently by setting `{ realtime: false }` in
+//   ~/.heuresis/config.json. The CLI flag wins over the config file when both
+//   are present.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const TABLES = ['nodes', 'edges', 'projects', 'ideas'];
+// ---------------------------------------------------------------------------
+// Subscription
+// ---------------------------------------------------------------------------
+/**
+ * Subscribe to Postgres change events on the user's workspace and call
+ * `onChange` for every row change (INSERT / UPDATE / DELETE) and for every
+ * post-reconnect resync signal.
+ *
+ * Returns an `unsubscribe` function that tears down the channel. Safe to call
+ * more than once; subsequent calls are no-ops.
+ */
+export function startRealtimeSubscription(client, workspaceId, onChange) {
+    const channelName = `heuresis-mcp-ws-${workspaceId}`;
+    const channel = client.channel(channelName);
+    let everSubscribed = false;
+    let lastStatusWasBad = false;
+    for (const table of TABLES) {
+        channel.on(
+        // The supabase-js types for `channel.on('postgres_changes', ...)` are
+        // strictly typed against a string-literal overload. Casting through
+        // `any` keeps this file readable while still matching the runtime API.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        'postgres_changes', {
+            event: '*',
+            schema: 'public',
+            table,
+            filter: `workspace_id=eq.${workspaceId}`,
+        }, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (payload) => {
+            const newRow = payload && typeof payload.new === 'object' && payload.new
+                ? payload.new
+                : null;
+            const oldRow = payload && typeof payload.old === 'object' && payload.old
+                ? payload.old
+                : null;
+            const eventType = payload?.eventType === 'INSERT' || payload?.eventType === 'UPDATE' || payload?.eventType === 'DELETE'
+                ? payload.eventType
+                : 'UPDATE';
+            try {
+                onChange({ table, eventType, new: newRow, old: oldRow });
+            }
+            catch (err) {
+                console.error('[heuresis-mcp] realtime handler threw:', err);
+            }
+        });
+    }
+    channel.subscribe((status, err) => {
+        // status is one of SUBSCRIBED | TIMED_OUT | CLOSED | CHANNEL_ERROR.
+        if (status === 'SUBSCRIBED') {
+            if (everSubscribed && lastStatusWasBad) {
+                // Reconnect: tell the caller it may have missed events while the
+                // socket was down.
+                try {
+                    onChange({ table: null, eventType: 'RESYNC', new: null, old: null });
+                }
+                catch (handlerErr) {
+                    console.error('[heuresis-mcp] realtime resync handler threw:', handlerErr);
+                }
+                console.error(`[heuresis-mcp] realtime: reconnected to workspace ${workspaceId} (possible missed updates).`);
+            }
+            else {
+                console.error(`[heuresis-mcp] realtime: subscribed to workspace ${workspaceId} (tables: ${TABLES.join(', ')}).`);
+            }
+            everSubscribed = true;
+            lastStatusWasBad = false;
+        }
+        else if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT' || status === 'CLOSED') {
+            lastStatusWasBad = true;
+            const detail = err ? `: ${err.message}` : '';
+            console.error(`[heuresis-mcp] realtime: channel ${status}${detail}. supabase-js will retry.`);
+        }
+    });
+    let torn = false;
+    return () => {
+        if (torn)
+            return;
+        torn = true;
+        try {
+            void client.removeChannel(channel);
+        }
+        catch (err) {
+            console.error('[heuresis-mcp] realtime: removeChannel failed:', err);
+        }
+    };
+}
+/**
+ * Resolve the workspace the MCP session should subscribe to. Same single-
+ * workspace rule the cloud tools use: first workspace visible to the user,
+ * ordered by name. A future per-session override (workspace id in
+ * credentials.json or an env var) can replace this.
+ */
+export async function resolveSubscriptionWorkspaceId(client) {
+    const res = await client
+        .from('workspaces')
+        .select('id, name')
+        .order('name', { ascending: true })
+        .limit(1);
+    if (res.error) {
+        console.error(`[heuresis-mcp] realtime: failed to resolve workspace: ${res.error.message}`);
+        return null;
+    }
+    const rows = (res.data ?? []);
+    return rows.length > 0 ? rows[0].id : null;
+}
+export function configPath() {
+    return join(homedir(), '.heuresis', 'config.json');
+}
+export async function readConfig() {
+    const path = configPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        const text = await readFile(path, 'utf8');
+        const data = JSON.parse(text);
+        return data && typeof data === 'object' ? data : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function writeConfig(next) {
+    const path = configPath();
+    await mkdir(dirname(path), { recursive: true });
+    const current = await readConfig();
+    const merged = { ...current, ...next };
+    await writeFile(path, JSON.stringify(merged, null, 2), 'utf8');
+    return path;
+}
+/**
+ * Read the effective "should Realtime be on?" decision from (in order):
+ *   1. The CLI flag `--no-realtime` (or `--realtime` to force on).
+ *   2. The `realtime` field in ~/.heuresis/config.json.
+ *   3. Default: true.
+ *
+ * Also persists a CLI flag back to the config file so the preference sticks
+ * across runs (the user only has to pass `--no-realtime` once).
+ */
+export async function readRealtimeFlag(argv = process.argv) {
+    const hasOff = argv.includes('--no-realtime');
+    const hasOn = argv.includes('--realtime');
+    if (hasOff && hasOn) {
+        console.error('[heuresis-mcp] both --no-realtime and --realtime passed; --no-realtime wins.');
+    }
+    if (hasOff) {
+        await writeConfig({ realtime: false });
+        return false;
+    }
+    if (hasOn) {
+        await writeConfig({ realtime: true });
+        return true;
+    }
+    const cfg = await readConfig();
+    if (cfg.realtime === false)
+        return false;
+    return true;
+}
+/**
+ * Strip realtime-related flags from argv so the subcommand dispatch in
+ * index.ts does not mistake them for an unknown subcommand.
+ */
+export function stripRealtimeFlags(argv) {
+    return argv.filter((a) => a !== '--no-realtime' && a !== '--realtime');
+}

package/dist/store.js

@@ -0,0 +1,128 @@
+// In-memory Heuresis store backed by a JSON snapshot on disk.
+//
+// Re-reads the file at every tool call if its mtime has changed, so the
+// agent always sees the latest export without needing a server restart.
+// The file path is taken from $HEURESIS_SNAPSHOT (preferred) or, when
+// absent, the conventional location `~/.heuresis/snapshot.json`.
+//
+// Why this shape:
+//  • The web app stores everything in IndexedDB, which Node can't read.
+//  • The app's existing Export workspace action writes a JSON file in
+//    exactly this shape; the eventual Settings → MCP sync (next commit)
+//    will write the same file automatically to a fixed path.
+//  • This decouples the MCP server from the browser entirely. The MCP
+//    server runs in the agent's process (Claude Desktop, Cursor, …) and
+//    reads whatever the latest snapshot has — no IPC, no permission
+//    dance, no auth.
+import { readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export class HeuresisStore {
+    path;
+    lastMtimeMs = null;
+    cache = null;
+    constructor(opts = {}) {
+        this.path =
+            opts.path ??
+                process.env.HEURESIS_SNAPSHOT ??
+                join(homedir(), '.heuresis', 'snapshot.json');
+    }
+    getSnapshotPath() {
+        return this.path;
+    }
+    /**
+     * Lazy-load and cache the snapshot. Re-reads from disk if the file's
+     * mtime has advanced — the agent always sees the latest data without
+     * us having to manage file watches.
+     */
+    async load() {
+        if (!existsSync(this.path)) {
+            throw new Error(`Heuresis snapshot not found at ${this.path}. Export your workspace from Settings → Workspace → Export, then either set HEURESIS_SNAPSHOT to point at it, or place it at the default path.`);
+        }
+        const s = await stat(this.path);
+        if (this.cache && this.lastMtimeMs === s.mtimeMs) {
+            return this.cache;
+        }
+        const text = await readFile(this.path, 'utf8');
+        const data = JSON.parse(text);
+        if (!Array.isArray(data.nodes) || !Array.isArray(data.edges)) {
+            throw new Error(`Snapshot at ${this.path} is missing required nodes/edges arrays. Re-export from Settings.`);
+        }
+        this.cache = data;
+        this.lastMtimeMs = s.mtimeMs;
+        return data;
+    }
+    // ── Convenience accessors ────────────────────────────────────────────
+    async workspaces() {
+        return (await this.load()).workspaces;
+    }
+    async nodes() {
+        return (await this.load()).nodes;
+    }
+    async edges() {
+        return (await this.load()).edges;
+    }
+    async projects() {
+        return (await this.load()).projects;
+    }
+    async ideas() {
+        return (await this.load()).ideas;
+    }
+    async provenance() {
+        return (await this.load()).provenance ?? [];
+    }
+    async nodeById(id) {
+        return (await this.nodes()).find((n) => n.id === id);
+    }
+    async projectById(id) {
+        return (await this.projects()).find((p) => p.id === id);
+    }
+    /**
+     * Children of a node via partition edges + the canonical `parentId`
+     * field. We accept both because the app sometimes records parent
+     * relationships only on the node and sometimes only on the edge.
+     */
+    async childrenOf(id) {
+        const [nodes, edges] = await Promise.all([this.nodes(), this.edges()]);
+        const ids = new Set();
+        for (const e of edges) {
+            if (e.kind === 'partition' && e.fromId === id)
+                ids.add(e.toId);
+        }
+        for (const n of nodes) {
+            if (n.parentId === id)
+                ids.add(n.id);
+        }
+        return nodes.filter((n) => ids.has(n.id));
+    }
+    /**
+     * Walk descendants breadth-first up to `maxDepth`. Depth 0 = just the
+     * node itself, depth 1 = node + direct children, etc.
+     */
+    async descendantsOf(id, maxDepth) {
+        const out = [];
+        const seen = new Set();
+        let frontier = [id];
+        for (let d = 0; d <= maxDepth; d++) {
+            const next = [];
+            for (const cur of frontier) {
+                if (seen.has(cur))
+                    continue;
+                seen.add(cur);
+                const node = await this.nodeById(cur);
+                if (!node)
+                    continue;
+                out.push(node);
+                if (d < maxDepth) {
+                    const kids = await this.childrenOf(cur);
+                    for (const k of kids)
+                        if (!seen.has(k.id))
+                            next.push(k.id);
+                }
+            }
+            frontier = next;
+        }
+        return out;
+    }
+}