@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/process-global.js

@@ -0,0 +1,28 @@
+/**
+ * Process-global singletons shared across module instances.
+ *
+ * A host that loads a library's modules more than once per process
+ * (pi loads each extension as its own module instance) does not get
+ * one registry from a module-level `const registry = new Map()`: each
+ * loader that imports the module gets its own. Anything one caller
+ * writes and another reads (a recorder sink, a prompt contributor, an
+ * LSP backend, the shared browser) must therefore live on
+ * `globalThis` under a shared key rather than in a module variable.
+ * `Symbol.for` gives every module instance the same key, and
+ * `globalThis` is shared across them, so the value is genuinely one
+ * per process.
+ */
+/**
+ * Get the process-global value for `key`, creating it once with
+ * `create` on first access. Every caller in the process, in any
+ * module instance, receives the same value.
+ */
+export function processGlobal(key, create) {
+    const symbol = Symbol.for(key);
+    const store = globalThis;
+    // Test presence with `in`, not truthiness, so a value that is
+    // legitimately undefined or falsy is still created only once.
+    if (!(symbol in store))
+        store[symbol] = create();
+    return store[symbol];
+}

package/dist/internal/quest/alias-index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Reverse index from alias `type:value` keys to quest ids.
+ *
+ * Built once from a `QuestIndex` (the discovery walk's
+ * output). The `quest create` action uses this to detect
+ * "this URL is already attached to an existing quest" and
+ * propose loading instead of creating a duplicate.
+ */
+import type { QuestAlias } from "../../quest/types.js";
+import type { QuestIndex } from "./discovery.js";
+/**
+ * Format a `{type, value}` alias as a flat lookup key. The type is
+ * lowercased so case variants of the same registered type (GitHub-PR
+ * and github-pr) resolve to one key; the value is kept verbatim,
+ * since paths and refs are case-sensitive.
+ */
+export declare function aliasKey(alias: QuestAlias): string;
+export interface AliasIndex {
+    /**
+     * Map from `type:value` to the quest id it appears in.
+     * When the same key appears on more than one quest, the
+     * key is also in `collisions` and `byKey` holds the
+     * lexicographically-first id (a stable choice the
+     * consumer can name in the error message).
+     */
+    byKey: Map<string, string>;
+    /**
+     * Every alias key that appears on more than one quest,
+     * with the full set of quest ids that share it. Consumers
+     * should refuse the operation when the alias they care
+     * about is in this map, since silently routing to the
+     * first-write-wins quest would mis-attribute work.
+     */
+    collisions: Map<string, string[]>;
+}
+/** Build a reverse index across every quest in the index. */
+export declare function buildAliasIndex(index: QuestIndex): AliasIndex;
+/**
+ * Find the quest id holding this alias, if any.
+ *
+ * Returns `undefined` when the alias is unknown OR when it
+ * is shared across multiple quests. Use `lookupAliasDetail`
+ * (below) when you need to distinguish those cases and
+ * surface the collision to the user.
+ */
+export declare function lookupAlias(index: AliasIndex, alias: QuestAlias): string | undefined;
+export type AliasLookup = {
+    kind: "miss";
+} | {
+    kind: "hit";
+    questId: string;
+} | {
+    kind: "collision";
+    questIds: string[];
+};
+/**
+ * Look up an alias and surface duplicates explicitly so the
+ * caller can refuse with a clear "alias X points at quests
+ * A and B" message rather than silently routing to one.
+ */
+export declare function lookupAliasDetail(index: AliasIndex, alias: QuestAlias): AliasLookup;

package/dist/internal/quest/alias-index.js

@@ -0,0 +1,69 @@
+/**
+ * Reverse index from alias `type:value` keys to quest ids.
+ *
+ * Built once from a `QuestIndex` (the discovery walk's
+ * output). The `quest create` action uses this to detect
+ * "this URL is already attached to an existing quest" and
+ * propose loading instead of creating a duplicate.
+ */
+/**
+ * Format a `{type, value}` alias as a flat lookup key. The type is
+ * lowercased so case variants of the same registered type (GitHub-PR
+ * and github-pr) resolve to one key; the value is kept verbatim,
+ * since paths and refs are case-sensitive.
+ */
+export function aliasKey(alias) {
+    return `${alias.type.toLowerCase()}:${alias.value}`;
+}
+/** Build a reverse index across every quest in the index. */
+export function buildAliasIndex(index) {
+    const occurrences = new Map();
+    for (const entry of index.quests.values()) {
+        for (const alias of entry.doc.frontMatter.aliases) {
+            const key = aliasKey(alias);
+            const list = occurrences.get(key) ?? [];
+            if (!list.includes(entry.doc.frontMatter.id)) {
+                list.push(entry.doc.frontMatter.id);
+            }
+            occurrences.set(key, list);
+        }
+    }
+    const byKey = new Map();
+    const collisions = new Map();
+    for (const [key, ids] of occurrences) {
+        const sorted = [...ids].sort();
+        byKey.set(key, sorted[0]);
+        if (sorted.length > 1)
+            collisions.set(key, sorted);
+    }
+    return { byKey, collisions };
+}
+/**
+ * Find the quest id holding this alias, if any.
+ *
+ * Returns `undefined` when the alias is unknown OR when it
+ * is shared across multiple quests. Use `lookupAliasDetail`
+ * (below) when you need to distinguish those cases and
+ * surface the collision to the user.
+ */
+export function lookupAlias(index, alias) {
+    const key = aliasKey(alias);
+    if (index.collisions.has(key))
+        return undefined;
+    return index.byKey.get(key);
+}
+/**
+ * Look up an alias and surface duplicates explicitly so the
+ * caller can refuse with a clear "alias X points at quests
+ * A and B" message rather than silently routing to one.
+ */
+export function lookupAliasDetail(index, alias) {
+    const key = aliasKey(alias);
+    const collisionIds = index.collisions.get(key);
+    if (collisionIds)
+        return { kind: "collision", questIds: collisionIds };
+    const questId = index.byKey.get(key);
+    if (questId)
+        return { kind: "hit", questId };
+    return { kind: "miss" };
+}

package/dist/internal/quest/append-journey.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Append a Journey bullet to a quest README at a known
+ * path. Pure file operation, no extension state involved.
+ * The extension's `appendJourneyEntry` wraps this for the
+ * loaded-quest case; a caller holding a path uses this
+ * directly so it can write to any quest the alias index
+ * points it at. That caller used to be named here as the
+ * PR-sidequest bridge, which no longer exists.
+ */
+/**
+ * Append a Journey bullet to `<questDir>/README.md`. When
+ * the Journey section is missing, append the whole section
+ * with the bullet inside. `now` is injected so tests can
+ * pin the date stamp.
+ *
+ * Returns `true` on success, `false` when the README is
+ * missing or unreadable so callers can log instead of
+ * silently dropping the journal entry.
+ */
+export declare function appendJourneyByPath(questDir: string, prose: string, opts?: {
+    now?: () => Date;
+}): boolean;

package/dist/internal/quest/append-journey.js

@@ -0,0 +1,63 @@
+/**
+ * Append a Journey bullet to a quest README at a known
+ * path. Pure file operation, no extension state involved.
+ * The extension's `appendJourneyEntry` wraps this for the
+ * loaded-quest case; a caller holding a path uses this
+ * directly so it can write to any quest the alias index
+ * points it at. That caller used to be named here as the
+ * PR-sidequest bridge, which no longer exists.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { nowYmd } from "./dates.js";
+import { atomicWriteFile, withQuestLock } from "./io.js";
+/**
+ * Append a Journey bullet to `<questDir>/README.md`. When
+ * the Journey section is missing, append the whole section
+ * with the bullet inside. `now` is injected so tests can
+ * pin the date stamp.
+ *
+ * Returns `true` on success, `false` when the README is
+ * missing or unreadable so callers can log instead of
+ * silently dropping the journal entry.
+ */
+export function appendJourneyByPath(questDir, prose, opts) {
+    const path = join(questDir, "README.md");
+    return withQuestLock(questDir, () => {
+        let text;
+        try {
+            text = readFileSync(path, "utf8");
+        }
+        catch {
+            return false;
+        }
+        const date = nowYmd(opts?.now);
+        const bullet = `- **${date}**: ${prose.trim()}`;
+        const journeyHeading = /^##\s+(?:[\u{1F300}-\u{1FFFF}]\s+)?Journey\s*$/mu;
+        const match = journeyHeading.exec(text);
+        let newText;
+        if (match) {
+            const lines = text.split("\n");
+            let lineIdx = 0;
+            let charCount = 0;
+            for (let i = 0; i < lines.length; i++) {
+                if (charCount + lines[i].length + 1 > match.index) {
+                    lineIdx = i;
+                    break;
+                }
+                charCount += lines[i].length + 1;
+            }
+            let insertAt = lineIdx + 1;
+            while (insertAt < lines.length && lines[insertAt].trim() === "") {
+                insertAt++;
+            }
+            lines.splice(insertAt, 0, bullet);
+            newText = lines.join("\n");
+        }
+        else {
+            newText = `${text.replace(/\n*$/, "\n")}\n## 🌄 Journey\n\n${bullet}\n`;
+        }
+        atomicWriteFile(path, newText);
+        return true;
+    });
+}

package/dist/internal/quest/bash-write.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Advisory classification of a bash command for the quest phase
+ * gate. The command is reduced to its executable skeleton first
+ * (heredoc bodies and quoted data removed) so a mutating verb that
+ * appears only as a literal argument, or inside a heredoc body,
+ * does not trip the gate. This is a nudge toward the right stage,
+ * not a security boundary.
+ */
+/** What kind of write, if any, a bash command performs. */
+export type BashWriteKind = "git-mutating" | "bash-write" | "read-only";
+/**
+ * Extract the destination paths a bash command writes to, so the
+ * gate can see where the write lands and allow scratch
+ * destinations. The command is reduced to the same data-stripped
+ * skeleton the classifier matches on, so a redirect that lived
+ * inside quoted data raises no phantom target. Three write shapes
+ * are read: redirect destinations (`>`, `>>`, excluding fd
+ * redirects such as `2>`), `tee` destinations, and the file
+ * argument of an in-place editor (sed -i, gsed -i, perl -i), whose
+ * quoted script has already been stripped, leaving the file as a
+ * trailing non-flag token.
+ *
+ * A target the command builds out of its own variables is expanded
+ * from the assignments in that same command, since `Q=...; echo >
+ * "$Q/f"` is one of the commonest ways to write to a directory whose
+ * path is long. A target still carrying a sigil after that is dropped
+ * rather than reported: the caller resolves what it is given against a
+ * working directory, so a literal `$UNKNOWN/f.txt` becomes a real path
+ * nobody wrote to, and judging the wrong file is worse than declining
+ * to judge this one.
+ *
+ * A quoted destination counts, which is the ordinary spelling and the
+ * spelling a variable almost always arrives in. Reading it does not cost
+ * the protection against a `>` inside a string, because the two are
+ * different questions: what makes a redirect real is its operator being
+ * unquoted, not its target being bare. The command model already draws
+ * that line, so the targets come from there and the patterns below stay
+ * as a second pass for the grammar it declines, such as a subshell or a
+ * loop. Both readings are kept because this gate wants recall: a missed
+ * target is an unjudged write, while a spurious one is inert unless it
+ * happens to name tracked code.
+ */
+export declare function bashWriteTargets(command: string): string[];
+/**
+ * Classify a bash command after stripping non-executable content,
+ * so quoted literals and heredoc bodies cannot raise a false
+ * positive.
+ */
+export declare function classifyBashWrite(command: string): BashWriteKind;

package/dist/internal/quest/bash-write.js

@@ -0,0 +1,208 @@
+/**
+ * Advisory classification of a bash command for the quest phase
+ * gate. The command is reduced to its executable skeleton first
+ * (heredoc bodies and quoted data removed) so a mutating verb that
+ * appears only as a literal argument, or inside a heredoc body,
+ * does not trip the gate. This is a nudge toward the right stage,
+ * not a security boundary.
+ */
+import { tokenize } from "../../command/index.js";
+import { stripHeredocBodies, stripShellData, unquote, } from "../../shell/index.js";
+/** Git subcommands that change repository or working-tree state. */
+const GIT_MUTATING = /\bgit(?:\s+(?:-c\s+\S+|-C\s+\S+|--git-dir=\S+|--work-tree=\S+|--no-pager))*\s+(add|commit|push|pull|merge|rebase|reset|checkout|stash|cherry-pick|revert|tag|switch|restore|am|format-patch)\b/i;
+/** Shell patterns that write to the filesystem via redirection or in-place edit. */
+const BASH_WRITE_PATTERNS = [
+    /(^|\s|[;&|`])cat\s+[^|]*>>?\s/, // cat > foo, cat >> foo
+    /(^|\s|[;&|`])tee\s+(?:-[a-z]+\s+)*\S/, // tee foo, tee -a foo
+    /(^|\s|[;&|`])sed\s+(?:-[a-z]+\s+)*-i\b/, // sed -i
+    /(^|\s|[;&|`])gsed\s+(?:-[a-z]+\s+)*-i\b/, // homebrew sed
+    /(^|\s|[;&|`])perl\s+(?:-[a-z]+\s+)*-i\b/, // perl -i
+    /(^|\s|[;&|`])printf\s+.+>>?\s/, // printf > foo
+    /(^|\s|[;&|`])echo\s+.+>>?\s/, // echo > foo
+];
+/**
+ * Extract the destination paths a bash command writes to, so the
+ * gate can see where the write lands and allow scratch
+ * destinations. The command is reduced to the same data-stripped
+ * skeleton the classifier matches on, so a redirect that lived
+ * inside quoted data raises no phantom target. Three write shapes
+ * are read: redirect destinations (`>`, `>>`, excluding fd
+ * redirects such as `2>`), `tee` destinations, and the file
+ * argument of an in-place editor (sed -i, gsed -i, perl -i), whose
+ * quoted script has already been stripped, leaving the file as a
+ * trailing non-flag token.
+ *
+ * A target the command builds out of its own variables is expanded
+ * from the assignments in that same command, since `Q=...; echo >
+ * "$Q/f"` is one of the commonest ways to write to a directory whose
+ * path is long. A target still carrying a sigil after that is dropped
+ * rather than reported: the caller resolves what it is given against a
+ * working directory, so a literal `$UNKNOWN/f.txt` becomes a real path
+ * nobody wrote to, and judging the wrong file is worse than declining
+ * to judge this one.
+ *
+ * A quoted destination counts, which is the ordinary spelling and the
+ * spelling a variable almost always arrives in. Reading it does not cost
+ * the protection against a `>` inside a string, because the two are
+ * different questions: what makes a redirect real is its operator being
+ * unquoted, not its target being bare. The command model already draws
+ * that line, so the targets come from there and the patterns below stay
+ * as a second pass for the grammar it declines, such as a subshell or a
+ * loop. Both readings are kept because this gate wants recall: a missed
+ * target is an unjudged write, while a spurious one is inert unless it
+ * happens to name tracked code.
+ */
+export function bashWriteTargets(command) {
+    const skeleton = stripShellData(stripHeredocBodies(command));
+    const assigned = assignmentsIn(skeleton, command);
+    const targets = [];
+    const add = (token) => {
+        if (!token)
+            return;
+        const bare = token.replace(/^['"]/, "").replace(/['"]$/, "");
+        if (!bare)
+            return;
+        const value = expand(bare, assigned);
+        // Anything still holding a `$` was built from something this command
+        // does not say, so there is nothing honest to report.
+        if (value === undefined)
+            return;
+        targets.push(value);
+    };
+    // Redirect destinations: the token following > or >>. A leading
+    // digit or & marks an fd redirect (2>, &>), which routes a stream
+    // rather than naming a content target, so it is skipped.
+    // A closing paren is excluded from the target so `(echo x > f.ts)` does
+    // not report `f.ts)`, which names nothing and so is never judged. A real
+    // filename may hold a paren, but a subshell ending is far likelier, and
+    // this pass is the one reading commands the model would not.
+    for (const match of skeleton.matchAll(/(?<![0-9&])>>?\s*([^\s;&|<>()]+)/g)) {
+        add(match[1]);
+    }
+    // tee destinations: non-flag tokens following a tee invocation.
+    for (const match of skeleton.matchAll(/(?:^|[|;&]|\s)tee\s+((?:-[^\s]+\s+)*)(\S+)/g)) {
+        add(match[2]);
+    }
+    // In-place editor file arguments: every non-flag token after the
+    // editor invocation. An unquoted script token cannot resolve to
+    // a tracked path, so it is harmless to include.
+    for (const match of skeleton.matchAll(/(?:^|[|;&]|\s)(?:g?sed|perl)\s+([^|;&\n]*)/g)) {
+        const tokens = (match[1] ?? "").split(/\s+/).filter(Boolean);
+        if (!tokens.some((t) => t === "-i" || t.startsWith("-i")))
+            continue;
+        for (const token of tokens) {
+            if (token.startsWith("-"))
+                continue;
+            add(token);
+        }
+    }
+    for (const target of modelledTargets(command))
+        add(target);
+    return [...new Set(targets)];
+}
+/**
+ * Write destinations read from the command model, where quoting is
+ * already understood.
+ *
+ * Three shapes, the same three the patterns above look for: a redirect's
+ * target, `tee`'s file arguments, and the file arguments of an in-place
+ * editor. A file-descriptor redirect (`2>`, `&>`) is skipped, matching
+ * what the pattern pass does, since it routes a stream rather than naming
+ * a content target.
+ *
+ * An editor's script is reported alongside its file, because telling one
+ * from the other means knowing whether this `sed` is the BSD or the GNU
+ * one. A script cannot name tracked code, so including it costs nothing,
+ * whereas missing the file was the whole defect.
+ */
+function modelledTargets(command) {
+    const line = tokenize(command);
+    const found = [];
+    for (const simple of line.commands) {
+        for (const redirect of simple.redirects) {
+            if (!redirect.target)
+                continue;
+            if (/^[0-9&]/.test(redirect.operator))
+                continue;
+            found.push(unquote(redirect.target.text));
+        }
+        const argv = simple.argv.map((word) => unquote(word.text));
+        const name = argv[0];
+        if (!name)
+            continue;
+        const rest = argv.slice(1).filter((token) => !token.startsWith("-"));
+        if (name === "tee")
+            found.push(...rest);
+        if (/^(g?sed|perl)$/.test(name) && editsInPlace(simple.argv)) {
+            found.push(...rest);
+        }
+    }
+    return found;
+}
+/** Whether an editor invocation carries the in-place flag. */
+function editsInPlace(argv) {
+    return argv.some((word) => {
+        const text = unquote(word.text);
+        return text === "-i" || text.startsWith("-i");
+    });
+}
+/**
+ * The variables a command assigns to itself, last assignment winning.
+ *
+ * Only the literal `NAME=value` form, which is what a command writing to
+ * a long path actually uses. A value built from an earlier variable is
+ * expanded against what is known so far, so `A=/tmp; B=$A/x` resolves.
+ */
+function assignmentsIn(skeleton, command) {
+    const known = new Map();
+    const record = (name, raw) => {
+        if (!name)
+            return;
+        const value = expand(unquote(raw), known);
+        if (value !== undefined)
+            known.set(name, value);
+    };
+    // The model first, because it keeps a quoted value. `Q="/tmp/q"` reaches
+    // the skeleton as `Q=""`, so reading only that lost exactly the paths
+    // long enough to be worth a variable.
+    for (const simple of tokenize(command).commands) {
+        for (const word of simple.assignments) {
+            const at = word.text.indexOf("=");
+            if (at < 0)
+                continue;
+            record(word.text.slice(0, at), word.text.slice(at + 1));
+        }
+    }
+    for (const match of skeleton.matchAll(/(?:^|[;&|]|\s)([A-Za-z_][A-Za-z0-9_]*)=([^\s;&|<>]*)/g)) {
+        record(match[1], match[2] ?? "");
+    }
+    return known;
+}
+/**
+ * A token with its variables filled in, or undefined when one of them is
+ * not something this command said.
+ *
+ * Both spellings, `$NAME` and `${NAME}`. A command substitution is never
+ * expanded: what it produces is not knowable from the text.
+ */
+function expand(token, known) {
+    if (!token.includes("$"))
+        return token;
+    if (token.includes("$("))
+        return undefined;
+    const filled = token.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (whole, braced, bare) => known.get(braced ?? bare) ?? whole);
+    return filled.includes("$") ? undefined : filled;
+}
+/**
+ * Classify a bash command after stripping non-executable content,
+ * so quoted literals and heredoc bodies cannot raise a false
+ * positive.
+ */
+export function classifyBashWrite(command) {
+    const skeleton = stripShellData(stripHeredocBodies(command));
+    if (GIT_MUTATING.test(skeleton))
+        return "git-mutating";
+    if (BASH_WRITE_PATTERNS.some((rx) => rx.test(skeleton)))
+        return "bash-write";
+    return "read-only";
+}

package/dist/internal/quest/dates.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared date helpers for the quest workflow.
+ *
+ * Every quest write that stamps an `updated` field, every
+ * Journey bullet, every document's first scaffolded
+ * `updated` value asks the same question: what is today in
+ * YYYY-MM-DD form, using the local time zone? Put the
+ * answer here once.
+ *
+ * `now` is injectable so callers under test can pin the
+ * date stamp without monkey-patching `Date`.
+ */
+/** YYYY-MM-DD in the local time zone. */
+export declare function nowYmd(now?: () => Date): string;

package/dist/internal/quest/dates.js

@@ -0,0 +1,20 @@
+/**
+ * Shared date helpers for the quest workflow.
+ *
+ * Every quest write that stamps an `updated` field, every
+ * Journey bullet, every document's first scaffolded
+ * `updated` value asks the same question: what is today in
+ * YYYY-MM-DD form, using the local time zone? Put the
+ * answer here once.
+ *
+ * `now` is injectable so callers under test can pin the
+ * date stamp without monkey-patching `Date`.
+ */
+/** YYYY-MM-DD in the local time zone. */
+export function nowYmd(now = () => new Date()) {
+    const d = now();
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}

package/dist/internal/quest/discovery.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Quest discovery: walk a quest tree on disk and build an
+ * in-memory index.
+ *
+ * Canonical disk layout (within `questsRoot`):
+ *
+ *     QEST-20260603-AAA111/
+ *       README.md
+ *       plans/PLAN-20260603-BBB222.md
+ *       research/RSCH-20260605-CCC333.md
+ *       briefs/BRIF-20260606-EEE555.md
+ *       reports/RPRT-20260607-FFF666.md
+ *     QEST-20260610-DDD444/           (subquest of AAA111,
+ *       README.md                       parent: QEST-...-AAA111
+ *                                       lives flat at the
+ *                                       quests root, not
+ *                                       nested in its
+ *                                       parent's directory)
+ *
+ * All quests live as immediate children of `questsRoot`.
+ * Hierarchy is expressed by the `parent:` front-matter
+ * field on each quest's README, not by directory nesting.
+ * Documents (plans, research, briefs, reports) live inside
+ * their owning quest's kind subdirectory (`plans/`,
+ * `research/`, `briefs/`, `reports/`).
+ *
+ * Discovery enforces these invariants. Two drift patterns
+ * are surfaced as `DiscoveryError` and the offending entry
+ * is skipped:
+ *
+ * - a `QEST-*` directory found inside another quest
+ * - a `PLAN-/RSCH-/BRIF-/RPRT-*.md` file at a quest's root
+ *   instead of in its kind subdirectory
+ *
+ * Free-form subdirectories under a quest (`runs/`,
+ * `tools/`, `workloads/`, etc.) are not walked. They're
+ * surfaced only via the quest's own body references.
+ */
+import type { QuestDoc, QuestDocumentDoc } from "../../quest/types.js";
+/** A single quest entry in the index. */
+export interface QuestEntry {
+    dir: string;
+    doc: QuestDoc;
+    /** Documents inside this quest's directory (not its subquests). */
+    documents: QuestDocumentEntry[];
+}
+/** A document (plan/research/brief/report) under a quest. */
+export interface QuestDocumentEntry {
+    path: string;
+    doc: QuestDocumentDoc;
+}
+/** The whole tree. */
+export interface QuestIndex {
+    /** Every discovered quest by id. */
+    quests: Map<string, QuestEntry>;
+    /**
+     * Parent-to-children adjacency. The empty key `""`
+     * holds top-level quests (those whose `parent` is
+     * null).
+     */
+    children: Map<string, string[]>;
+}
+/**
+ * The ranks of every quest sharing a parent and priority bucket (a
+ * sibling set), optionally excluding one id. Callers pair this with
+ * `nextRank` to place a new or moved quest at the next free rank in
+ * its group rather than colliding at rank 1.
+ */
+export declare function siblingRanks(index: QuestIndex, parent: string | null, priority: string, excludeId?: string): number[];
+interface DiscoveryError {
+    path: string;
+    message: string;
+}
+/** Result of a discovery walk. */
+export interface DiscoveryResult {
+    index: QuestIndex;
+    errors: DiscoveryError[];
+}
+/**
+ * Drop the discovery memo. Tests call this between runs; write
+ * paths do not need it because the signature catches their
+ * changes on the next read.
+ */
+export declare function clearDiscoveryCache(): void;
+/**
+ * Walk `questsRoot` and build the index, memoized per root. The
+ * walk re-parses every README and document, which is the costly
+ * part; this caches the result behind a cheap mtime-and-size
+ * signature so repeated read verbs in a session do not re-parse
+ * an unchanged tree. The signature recomputes on every call (a
+ * directory traversal plus stats, no file reads), so any change
+ * to a README, a document, or the set of quests invalidates the
+ * cache on the next read.
+ */
+export declare function discoverQuests(questsRoot: string): DiscoveryResult;
+export {};