@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/quest/git-signals.js

@@ -0,0 +1,192 @@
+/**
+ * Production git predicates for the write classifier. Each shells
+ * out to git from the directory enclosing the target, so a target
+ * in a different repository than the session cwd is judged against
+ * its own repository. Every call fails closed to the safe answer
+ * when git is absent, the path is outside a repository, or the
+ * subprocess errors: no tree root, not ignored, not tracked.
+ *
+ * The pure classifier takes these as injected predicates; this
+ * module is the real implementation it composes in production.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import * as path from "node:path";
+/**
+ * Wall-clock ceiling for a single git invocation. The classifier
+ * runs on the synchronous tool_call path, so a wedged git must not
+ * hang the event loop with no operator lever; a timeout throws,
+ * which every caller already treats as the safe answer.
+ */
+const GIT_TIMEOUT_MS = 5000;
+/** Run git in `cwd`, returning trimmed stdout, or null on any failure. */
+function git(cwd, args) {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: GIT_TIMEOUT_MS,
+        }).trim();
+    }
+    catch {
+        // git missing, non-zero exit (e.g. not a repo, not ignored,
+        // not tracked) or any spawn error: the caller's safe answer.
+        return null;
+    }
+}
+/**
+ * The canonical directory to run git from and the canonical target
+ * path, for a target that may not exist yet. Walks up to the
+ * nearest existing ancestor (so git runs from a real directory
+ * even when several leading path segments are missing) and
+ * realpath's it, so a /var versus /private/var spelling does not
+ * read as outside the repository. The missing tail is re-appended
+ * to form the full canonical target.
+ */
+function located(absPath) {
+    const resolved = path.resolve(absPath);
+    const tail = [];
+    let prefix = path.dirname(resolved);
+    tail.unshift(path.basename(resolved));
+    while (true) {
+        try {
+            const dir = realpathSync(prefix);
+            return { dir, target: path.join(dir, ...tail) };
+        }
+        catch {
+            // prefix does not exist; step up and try its parent.
+        }
+        const parent = path.dirname(prefix);
+        if (parent === prefix)
+            return { dir: prefix, target: resolved };
+        tail.unshift(path.basename(prefix));
+        prefix = parent;
+    }
+}
+/**
+ * The git working tree root containing the target, or null when the
+ * target is not inside any repository. Resolves through `.git` files
+ * (worktrees) natively via rev-parse.
+ *
+ * Accepts a directory as readily as a file. It did not always: it ran
+ * git from `located().dir`, which resolves an existing directory to
+ * its parent, and the parent of a repository root is outside the
+ * repository. So the one input a caller is most likely to hold, the
+ * root of the checkout they are standing in, answered null. Two
+ * callers knew and worked around it by appending a filename they
+ * invented; the third did not, and shipped a verb that refused in the
+ * only place it was meant to work.
+ */
+export function gitTreeRootOf(absPath) {
+    const root = git(fromInside(absPath), ["rev-parse", "--show-toplevel"]);
+    return root && root.length > 0 ? root : null;
+}
+/**
+ * The directory to run git from for a target: the target itself when
+ * it is a directory, and otherwise the nearest existing ancestor.
+ */
+function fromInside(absPath) {
+    try {
+        if (statSync(absPath).isDirectory())
+            return realpathSync(absPath);
+    }
+    catch {
+        // Does not exist, so it is a path a caller invented to probe with.
+        // located() walks up to the nearest real ancestor, which is what
+        // those callers were relying on and what still happens below.
+    }
+    return located(absPath).dir;
+}
+/**
+ * Whether the target sits in a repository's primary checkout, as
+ * opposed to a linked worktree. The main tree's git-dir equals its
+ * git-common-dir; a linked worktree's git-dir is under
+ * `.git/worktrees/`, so the two differ. False when git cannot answer
+ * or the path is outside any repository, so a doubtful case never
+ * reads as the shared main tree by accident.
+ */
+export function isMainWorkingTree(absPath) {
+    // Probe a child path so git runs from the directory itself, the
+    // same trick gitTreeRootOf uses; located() otherwise resolves to
+    // the parent of an existing directory.
+    const { dir } = located(path.join(absPath, ".quest-tree-probe"));
+    const gitDir = git(dir, ["rev-parse", "--path-format=absolute", "--git-dir"]);
+    const commonDir = git(dir, [
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-common-dir",
+    ]);
+    if (!gitDir || !commonDir)
+        return false;
+    return canonicalPath(gitDir) === canonicalPath(commonDir);
+}
+/** Whether the target is gitignored at its destination. */
+export function isGitignored(absPath) {
+    const { dir, target } = located(absPath);
+    try {
+        execFileSync("git", ["check-ignore", "-q", "--", target], {
+            cwd: dir,
+            stdio: "ignore",
+            timeout: GIT_TIMEOUT_MS,
+        });
+        return true;
+    }
+    catch {
+        // Exit 1 (not ignored) and 128 (not a repo) both land here as
+        // "not ignored," which is the safe answer for the classifier.
+        return false;
+    }
+}
+/**
+ * Canonicalize a path for comparison, tolerating a path that does
+ * not exist yet. Resolves the longest existing ancestor (which
+ * turns /var into /private/var on macOS) and re-appends the missing
+ * tail. The literal path survives a total failure.
+ */
+export function canonicalPath(p) {
+    const tail = [];
+    let prefix = p;
+    while (!existsSync(prefix)) {
+        const parent = path.dirname(prefix);
+        if (parent === prefix)
+            return p;
+        tail.unshift(path.basename(prefix));
+        prefix = parent;
+    }
+    try {
+        const real = realpathSync(prefix);
+        return tail.length > 0 ? path.join(real, ...tail) : real;
+    }
+    catch {
+        // realpath can fail on a broken symlink; the literal path is best.
+        return p;
+    }
+}
+/**
+ * Whether `child` is `parent` or lives beneath it, comparing
+ * canonicalized paths with a separator boundary so a /var versus
+ * /private/var spelling still matches and a sibling whose name
+ * merely shares a prefix (feature-2 against feat) does not.
+ */
+export function isWithin(child, parent) {
+    const c = canonicalPath(child);
+    const p = canonicalPath(parent);
+    return c === p || c.startsWith(p + path.sep);
+}
+/** Whether the target is tracked in its repository's index. */
+export function isTracked(absPath) {
+    const { dir, target } = located(absPath);
+    try {
+        execFileSync("git", ["ls-files", "--error-unmatch", "--", target], {
+            cwd: dir,
+            stdio: "ignore",
+            timeout: GIT_TIMEOUT_MS,
+        });
+        return true;
+    }
+    catch {
+        // Non-zero exit (untracked or not a repo): not tracked.
+        return false;
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Quest and document ID minting.
+ *
+ * IDs are deterministic in shape, random in suffix:
+ *
+ *     PREFIX-YYYYMMDD-XXXXXX
+ *
+ * `PREFIX` is one of the four-character codes for our
+ * document kinds. `YYYYMMDD` is the creation date in the
+ * local timezone (we never coordinate IDs across timezones,
+ * so local is what the user expects to see). `XXXXXX` is a
+ * six-character base-36 (upper) random suffix giving roughly
+ * 2.18 billion distinct IDs per kind per day.
+ */
+/** Recognised ID prefixes for the four document kinds plus quests. */
+export declare const ID_PREFIXES: readonly ["QEST", "PLAN", "RSCH", "BRIF", "RPRT"];
+export type IdPrefix = (typeof ID_PREFIXES)[number];
+/**
+ * Mint a fresh ID. The date defaults to `new Date()`; tests
+ * pass a fixed date for stable output.
+ */
+export declare function mintId(prefix: IdPrefix, date?: Date): string;
+/** Quick validation: is this string a valid ID? */
+export declare function isId(text: string): boolean;
+/** Extract the prefix from an ID, or `undefined` for an invalid ID. */
+export declare function prefixOf(id: string): IdPrefix | undefined;
+/** Extract the date portion (YYYYMMDD) from an ID, or `undefined`. */
+export declare function dateOf(id: string): string | undefined;
+/** Find every valid ID in a body of text. */
+export declare function findIds(text: string): string[];
+/**
+ * How an inline ID mention reads. A bare `QEST-...` reads
+ * as a `reference`. An id preceded by the `→` sigil
+ * (after optional whitespace) reads as `produced`: the
+ * containing document is the work that produced the
+ * mentioned id.
+ */
+export type IdMentionRelation = "produced" | "reference";
+export interface IdMention {
+    id: string;
+    relation: IdMentionRelation;
+}
+/**
+ * Find every ID in a body of text and classify each
+ * mention as a bare reference or a produced-by sigil hit.
+ * When the same id appears more than once, the strongest
+ * relation wins: a single `→ ID` anywhere upgrades the
+ * record from `reference` to `produced`.
+ */
+export declare function findIdsWithRelation(text: string): IdMention[];

package/dist/internal/quest/id.js

@@ -0,0 +1,116 @@
+/**
+ * Quest and document ID minting.
+ *
+ * IDs are deterministic in shape, random in suffix:
+ *
+ *     PREFIX-YYYYMMDD-XXXXXX
+ *
+ * `PREFIX` is one of the four-character codes for our
+ * document kinds. `YYYYMMDD` is the creation date in the
+ * local timezone (we never coordinate IDs across timezones,
+ * so local is what the user expects to see). `XXXXXX` is a
+ * six-character base-36 (upper) random suffix giving roughly
+ * 2.18 billion distinct IDs per kind per day.
+ */
+import { randomBytes } from "node:crypto";
+/** Recognised ID prefixes for the four document kinds plus quests. */
+export const ID_PREFIXES = ["QEST", "PLAN", "RSCH", "BRIF", "RPRT"];
+// YYYY: 1900-2999. MM: 01-12. DD: 01-31. This is a
+// shape check, not a perfect calendar validator: it
+// rejects the obvious garbage (00000000, 20261345) the
+// old `\d{8}` accepted while staying cheap.
+const DATE_PATTERN = "(?:19|2[0-9])\\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])";
+const ID_REGEX = new RegExp(`^(${ID_PREFIXES.join("|")})-(${DATE_PATTERN})-([0-9A-Z]{6})$`);
+const ID_REGEX_BODY = `(${ID_PREFIXES.join("|")})-(${DATE_PATTERN})-([0-9A-Z]{6})`;
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+function ymd(date) {
+    return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`;
+}
+/** Build a six-character base-36 uppercase random suffix. */
+function randomSuffix() {
+    const bytes = randomBytes(6);
+    const out = [];
+    for (let i = 0; i < 6; i++) {
+        out.push((bytes[i] % 36).toString(36).toUpperCase());
+    }
+    return out.join("");
+}
+/**
+ * Mint a fresh ID. The date defaults to `new Date()`; tests
+ * pass a fixed date for stable output.
+ */
+export function mintId(prefix, date = new Date()) {
+    return `${prefix}-${ymd(date)}-${randomSuffix()}`;
+}
+/** Quick validation: is this string a valid ID? */
+export function isId(text) {
+    return ID_REGEX.test(text);
+}
+/** Extract the prefix from an ID, or `undefined` for an invalid ID. */
+export function prefixOf(id) {
+    const match = ID_REGEX.exec(id);
+    return match ? match[1] : undefined;
+}
+/** Extract the date portion (YYYYMMDD) from an ID, or `undefined`. */
+export function dateOf(id) {
+    const match = ID_REGEX.exec(id);
+    return match ? match[2] : undefined;
+}
+/** Find every valid ID in a body of text. */
+export function findIds(text) {
+    // We need a no-anchor flavour of the regex so it can
+    // scan the middle of a string. The `\b` boundary keeps
+    // us from matching IDs embedded inside longer tokens.
+    const scan = new RegExp(`\\b${ID_REGEX_BODY}\\b`, "g");
+    const out = [];
+    const seen = new Set();
+    for (const m of text.matchAll(scan)) {
+        if (!seen.has(m[0])) {
+            seen.add(m[0]);
+            out.push(m[0]);
+        }
+    }
+    return out;
+}
+/**
+ * Find every ID in a body of text and classify each
+ * mention as a bare reference or a produced-by sigil hit.
+ * When the same id appears more than once, the strongest
+ * relation wins: a single `→ ID` anywhere upgrades the
+ * record from `reference` to `produced`.
+ */
+export function findIdsWithRelation(text) {
+    const scan = new RegExp(`\\b${ID_REGEX_BODY}\\b`, "g");
+    const seen = new Map();
+    const order = [];
+    for (const m of text.matchAll(scan)) {
+        const id = m[0];
+        const start = m.index ?? 0;
+        const relation = sigilBefore(text, start) ? "produced" : "reference";
+        const prev = seen.get(id);
+        if (prev === undefined) {
+            order.push(id);
+            seen.set(id, relation);
+            continue;
+        }
+        if (prev === "reference" && relation === "produced") {
+            seen.set(id, relation);
+        }
+    }
+    return order.map((id) => ({
+        id,
+        relation: seen.get(id) ?? "reference",
+    }));
+}
+function sigilBefore(text, idStart) {
+    // Walk backwards past whitespace; if we hit a → with
+    // nothing but whitespace in between, the id reads as
+    // `produced`. Anything else (text, punctuation, line
+    // boundary) means bare reference.
+    let i = idStart - 1;
+    while (i >= 0 && /\s/.test(text[i]))
+        i--;
+    return i >= 0 && text[i] === "\u2192";
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Atomic file IO and per-quest advisory locks.
+ *
+ * Quest READMEs are read-modify-write at every action,
+ * potentially from two pi sessions attached to the same
+ * quest at the same time. Two concerns:
+ *
+ * 1. Torn reads. The "read text, parse, mutate, write
+ *    text" sequence is not atomic against a concurrent
+ *    reader; on a slow disk a reader sees half a file.
+ *    We write to a sibling temp file, fsync, then rename
+ *    over the target so observers always see the old or
+ *    new file in full.
+ *
+ * 2. Lost updates. Two pi sessions running in parallel
+ *    both load the README, both mutate frontmatter
+ *    in-memory, both write back: the second overwrites
+ *    the first. We take a coarse per-quest lock around
+ *    the read-modify-write so the second waits.
+ *
+ * The lock is file-creation with `O_EXCL`. A short retry
+ * loop covers the normal contention case; a stale-lock
+ * sweep kicks in when the lock is older than
+ * `STALE_LOCK_MS` so a crashed pi cannot wedge the quest
+ * for the rest of time. The lock is advisory: a process
+ * that bypasses it can still write through. We rely on
+ * every README write going through `withQuestLock`.
+ */
+/**
+ * Write `data` to `path` atomically: write to a sibling
+ * temp file in the same directory, fsync, then rename
+ * over the target. The rename is atomic on POSIX
+ * filesystems for files on the same volume.
+ */
+export declare function atomicWriteFile(path: string, data: string): void;
+/**
+ * Run `fn` under an advisory lock on the given quest dir.
+ * Acquires `<questDir>/.quest.lock`, runs fn, releases.
+ * Steals locks older than `STALE_LOCK_MS` whose owner is
+ * no longer alive.
+ */
+export declare function withQuestLock<T>(questDir: string, fn: () => T): T;
+/**
+ * Convenience helper: lock the quest, write the README
+ * atomically, release. Most call sites use this directly.
+ */
+export declare function writeQuestReadmeAtomic(questDir: string, contents: string): void;
+/** Fallback when we have a path but no enclosing quest dir. */
+export declare function atomicWriteUnderLock(questDir: string, path: string, contents: string): void;
+/** Synchronous sleep used in tests when emulating contention. */
+export declare const __testing: {
+    LOCK_TIMEOUT_MS: number;
+    STALE_LOCK_MS: number;
+};

package/dist/internal/quest/io.js

@@ -0,0 +1,233 @@
+/**
+ * Atomic file IO and per-quest advisory locks.
+ *
+ * Quest READMEs are read-modify-write at every action,
+ * potentially from two pi sessions attached to the same
+ * quest at the same time. Two concerns:
+ *
+ * 1. Torn reads. The "read text, parse, mutate, write
+ *    text" sequence is not atomic against a concurrent
+ *    reader; on a slow disk a reader sees half a file.
+ *    We write to a sibling temp file, fsync, then rename
+ *    over the target so observers always see the old or
+ *    new file in full.
+ *
+ * 2. Lost updates. Two pi sessions running in parallel
+ *    both load the README, both mutate frontmatter
+ *    in-memory, both write back: the second overwrites
+ *    the first. We take a coarse per-quest lock around
+ *    the read-modify-write so the second waits.
+ *
+ * The lock is file-creation with `O_EXCL`. A short retry
+ * loop covers the normal contention case; a stale-lock
+ * sweep kicks in when the lock is older than
+ * `STALE_LOCK_MS` so a crashed pi cannot wedge the quest
+ * for the rest of time. The lock is advisory: a process
+ * that bypasses it can still write through. We rely on
+ * every README write going through `withQuestLock`.
+ */
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { dirname, join } from "node:path";
+/** Lock-acquire retry budget per call. */
+const LOCK_TIMEOUT_MS = 5000;
+/** Sleep between retries. */
+const LOCK_RETRY_MS = 25;
+/** A lock older than this is considered stale and stolen. */
+const STALE_LOCK_MS = 30_000;
+const LOCK_NAME = ".quest.lock";
+/**
+ * Write `data` to `path` atomically: write to a sibling
+ * temp file in the same directory, fsync, then rename
+ * over the target. The rename is atomic on POSIX
+ * filesystems for files on the same volume.
+ */
+export function atomicWriteFile(path, data) {
+    const dir = dirname(path);
+    const tmp = join(dir, `.${path.split("/").pop()}.tmp-${process.pid}-${Math.random()
+        .toString(36)
+        .slice(2, 10)}`);
+    const fd = openSync(tmp, "w");
+    try {
+        writeSync(fd, data);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // Best-effort cleanup; the temp's leftover state is
+            // safe to leave in place and is not user-visible.
+        }
+        throw err;
+    }
+}
+function readLockRecord(lockPath) {
+    try {
+        const text = readFileSync(lockPath, "utf8");
+        const parsed = JSON.parse(text);
+        const pid = typeof parsed.pid === "number" && Number.isFinite(parsed.pid)
+            ? parsed.pid
+            : undefined;
+        const startedAt = typeof parsed.startedAt === "number" && Number.isFinite(parsed.startedAt)
+            ? parsed.startedAt
+            : undefined;
+        if (pid === undefined || startedAt === undefined)
+            return undefined;
+        return { pid, startedAt };
+    }
+    catch {
+        // Lock file is malformed or unreadable. Treat as stale
+        // so the steal loop can recover instead of wedging.
+        return undefined;
+    }
+}
+function isProcessAlive(pid) {
+    if (pid <= 0 || pid === process.pid)
+        return false;
+    try {
+        // kill(pid, 0) probes whether the pid exists; throws
+        // ESRCH when it doesn't and EPERM when it does but we
+        // can't signal it. Either non-throw is "alive enough".
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function tryStealStaleLock(lockPath, now) {
+    const record = readLockRecord(lockPath);
+    if (!record) {
+        // Malformed lock file; remove and retry.
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            // Another process beat us to the cleanup; that's fine.
+        }
+        return true;
+    }
+    const age = now - record.startedAt;
+    if (age < STALE_LOCK_MS && isProcessAlive(record.pid))
+        return false;
+    try {
+        unlinkSync(lockPath);
+        return true;
+    }
+    catch {
+        // Another process beat us to the cleanup; let the
+        // next loop iteration retry the acquire.
+        return false;
+    }
+}
+function acquireLock(lockPath) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let lastStealCheck = 0;
+    while (true) {
+        try {
+            const fd = openSync(lockPath, "wx");
+            const payload = {
+                pid: process.pid,
+                startedAt: Date.now(),
+            };
+            writeSync(fd, JSON.stringify(payload));
+            fsyncSync(fd);
+            return fd;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+        }
+        const now = Date.now();
+        if (now >= deadline) {
+            throw new Error(`Timed out acquiring quest lock at ${lockPath} after ${LOCK_TIMEOUT_MS}ms.`);
+        }
+        // Probe for staleness every couple of retries so a
+        // crashed holder doesn't keep us spinning.
+        if (now - lastStealCheck > LOCK_RETRY_MS * 4) {
+            tryStealStaleLock(lockPath, now);
+            lastStealCheck = now;
+        }
+        // Busy-wait inside the retry budget. Node has no
+        // blocking sleep without async, and the caller is
+        // already running a synchronous read-modify-write.
+        const sleepUntil = Date.now() + LOCK_RETRY_MS;
+        while (Date.now() < sleepUntil) {
+            // spin
+        }
+    }
+}
+function releaseLock(lockPath, fd) {
+    try {
+        closeSync(fd);
+    }
+    catch {
+        // Already closed; cleanup of the path below still runs.
+    }
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Lock file was stolen out from under us or never
+        // committed; nothing more we can do.
+    }
+}
+/**
+ * Run `fn` under an advisory lock on the given quest dir.
+ * Acquires `<questDir>/.quest.lock`, runs fn, releases.
+ * Steals locks older than `STALE_LOCK_MS` whose owner is
+ * no longer alive.
+ */
+export function withQuestLock(questDir, fn) {
+    if (!existsSync(questDir)) {
+        throw new Error(`Quest directory ${questDir} does not exist.`);
+    }
+    const lockPath = join(questDir, LOCK_NAME);
+    // Probe once before the loop so we don't wait the full
+    // retry budget on a clearly-stale lock.
+    if (existsSync(lockPath)) {
+        try {
+            const age = Date.now() - statSync(lockPath).mtimeMs;
+            if (age > STALE_LOCK_MS)
+                tryStealStaleLock(lockPath, Date.now());
+        }
+        catch {
+            // Stat failed; the acquire loop handles it.
+        }
+    }
+    const fd = acquireLock(lockPath);
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock(lockPath, fd);
+    }
+}
+/**
+ * Convenience helper: lock the quest, write the README
+ * atomically, release. Most call sites use this directly.
+ */
+export function writeQuestReadmeAtomic(questDir, contents) {
+    withQuestLock(questDir, () => {
+        atomicWriteFile(join(questDir, "README.md"), contents);
+    });
+}
+/** Fallback when we have a path but no enclosing quest dir. */
+export function atomicWriteUnderLock(questDir, path, contents) {
+    withQuestLock(questDir, () => {
+        atomicWriteFile(path, contents);
+    });
+}
+/** Synchronous sleep used in tests when emulating contention. */
+export const __testing = {
+    LOCK_TIMEOUT_MS,
+    STALE_LOCK_MS,
+};

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

@@ -0,0 +1,45 @@
+/**
+ * Reverse-mention index: for each quest in the index, find
+ * every other quest whose body or documents mention it.
+ *
+ * Two kinds of mentions:
+ *
+ * - Bare IDs in prose: `QEST-...`, `PLAN-...`, etc.
+ * - Refs: anything the registered ref types extract.
+ *
+ * For Echoes rendering on `quest show`, we care about
+ * inbound mentions: "who has mentioned QEST-X". The reverse
+ * map is keyed by the target id (or ref canonical) and
+ * values are the source quests.
+ */
+import type { QuestIndex } from "./discovery.js";
+import type { IdMentionRelation } from "./id.js";
+/** One inbound mention. */
+export interface MentionEdge {
+    /** The quest the mention came from. */
+    from: string;
+    /** Short snippet of context around the mention. */
+    snippet: string;
+    /**
+     * How the source document referred to this id. `produced`
+     * when the mention was preceded by the → sigil; a bare
+     * reference otherwise. Refs carry `reference` since the
+     * sigil applies to ids only.
+     */
+    relation: IdMentionRelation;
+}
+/** Snapshot of mentions for the whole index. */
+export interface MentionIndex {
+    /** Inbound mentions keyed by target quest/document id. */
+    byId: Map<string, MentionEdge[]>;
+    /** Inbound mentions keyed by `${type}:${value}` for refs. */
+    byRef: Map<string, MentionEdge[]>;
+}
+/**
+ * Build a reverse-mention index over every quest in the
+ * input. Each quest contributes both its README body and
+ * its documents' bodies to the mention pool.
+ */
+export declare function buildMentionIndex(index: QuestIndex): MentionIndex;
+/** Convenience: lookup inbound mentions for one target quest id. */
+export declare function mentionsOf(index: MentionIndex, targetId: string): MentionEdge[];