@descryy/mcp 0.1.0

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,164 @@
+/**
+ * One repository, one graph, one process.
+ *
+ * The session owns everything with a lifetime: the SQLite handle, the resolved
+ * configuration, the loaded sources. Tools receive it and own nothing, which is
+ * what lets the whole tool layer be tested against an in-memory graph.
+ *
+ * ## Configuration is read once and reported, not read repeatedly and assumed
+ *
+ * `.descry/config.json` is optional. Everything in it has a default that makes
+ * local mode work unconfigured, per the architecture's local-first guarantee —
+ * except the source list, which cannot have one: this repository must not name
+ * an adapter (see `registry.ts`). So an unconfigured session can query a graph
+ * and cannot build one, and `analyze` says exactly that rather than reporting a
+ * successful run over zero sources.
+ *
+ * ## The graph is opened lazily
+ *
+ * A server that opened the database at startup would fail to start on a repo
+ * that has never been analysed — the worst possible first experience for the
+ * primary UX. Opening on first use means `tools/list` works everywhere, and a
+ * query against a missing graph fails as a *tool* result the agent can read and
+ * act on ("run analyze first"), not as a crash before the handshake.
+ */
+import type { ConfirmedFact, RepoRoot } from "@descryy/ir";
+import { type AdjacencyProvider, type Store } from "@descryy/core";
+import { type SourceSpec } from "./registry.ts";
+export interface DescryConfig {
+    /** Identity scope for repo-scoped nodes. Never a path — see DEC-004. */
+    readonly repo: string;
+    /**
+     * The contract boundary (DEC-054). Must be byte-identical in every repository
+     * of the workspace; a mismatch produces a graph that joins nothing silently.
+     */
+    readonly workspace?: string | undefined;
+    /** Graph file, relative to the repository root unless absolute. */
+    readonly graph: string;
+    readonly sources: readonly SourceSpec[];
+    /**
+     * DEC-223 §4's storage decision: human-confirmed answers to refusal-ledger
+     * rows, in the same small, field-additive, human-inspectable file as
+     * `repo`/`workspace` rather than a new store table — recommended there on
+     * measured population (a handful of facts per repository, not thousands;
+     * see DEC-223 for the number this rests on). Revisit if that stops holding.
+     */
+    readonly confirmedFacts: readonly ConfirmedFact[];
+    /** Where the settings came from, so a surprising run can be explained. */
+    readonly configPath: string | null;
+}
+export declare const CONFIG_RELATIVE_PATH: string;
+export declare const DEFAULT_GRAPH_RELATIVE_PATH: string;
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function loadConfig(repoPath: string): Promise<DescryConfig>;
+export interface ConfigPatch {
+    readonly repo: string;
+    /** Omit to leave a previously-set workspace untouched; there is no way to clear one here. */
+    readonly workspace?: string | undefined;
+}
+/**
+ * `.descry/config.json`'s writer, the counterpart to `loadConfig`.
+ *
+ * One writer for one file, used by both front doors that set the workspace
+ * id — `descry init` (`@descryhq-wq/cli`) and the `link_workspace` MCP tool — so
+ * the two can never drift into writing two different shapes of the same
+ * file. Fields this function does not know about (`graph`, `sources`, or
+ * anything a future version adds) survive a re-run untouched: this patches
+ * `repo` and `workspace`, it does not own the whole file.
+ */
+export declare function writeConfig(repoPath: string, patch: ConfigPatch): Promise<{
+    readonly path: string;
+    readonly previousWorkspace: string | undefined;
+}>;
+/**
+ * `confirmedFacts`'s writer — separate from `writeConfig` on purpose.
+ *
+ * `writeConfig`'s own doc is explicit that it "patches `repo` and
+ * `workspace`, it does not own the whole file" — a second, narrow writer for
+ * a second, narrow field keeps that boundary rather than growing one
+ * function into "the file's owner." Both read-modify-write the same JSON
+ * file the same way, so a future field gets a third writer, not a branch in
+ * this one.
+ *
+ * Keyed on exact `(repo, blockedBy, environment)` — DEC-223 §3 and
+ * `ConfirmedFact`'s own doc; `environment` is `undefined` for an unscoped
+ * answer, which is its own distinct key value, not a wildcard that a later
+ * environment-scoped answer would collide with. A second call with the same
+ * key **replaces** the first rather than appending a duplicate: a
+ * re-confirmation (the value changed, or the same value is being
+ * re-asserted after §7's staleness note) updates in place, and a caller can
+ * always find out what was overwritten from the return value rather than
+ * having to read the file first. A second call with a *different*
+ * environment for the same `blockedBy` adds a second fact rather than
+ * replacing the first — a repository can genuinely need one value per
+ * environment.
+ */
+export declare function writeConfirmedFact(repoPath: string, fact: ConfirmedFact): Promise<{
+    readonly path: string;
+    readonly replaced: ConfirmedFact | null;
+}>;
+/**
+ * `sources`' writer — MK-3, the third narrow field-writer beside `writeConfig`
+ * (`repo`/`workspace`) and `writeConfirmedFact` (`confirmedFacts`), for the
+ * same reason those two stayed separate: a shared file gets one writer per
+ * field it owns, not one function that grows a branch per field.
+ *
+ * Unconditional: the caller (`descry init`) decides whether writing is
+ * appropriate — reading `loadConfig(repoPath).sources` first and skipping
+ * this call when it is already non-empty — because "should this overwrite
+ * what's there" is a policy question `writeConfig`'s own precedent leaves to
+ * the caller, not to the file-writing primitive.
+ */
+export declare function writeSources(repoPath: string, sources: readonly string[]): Promise<{
+    readonly path: string;
+}>;
+export interface SessionOptions {
+    readonly repoPath: string;
+    /** Swap the store — the reason tools can be tested with no file on disk. */
+    readonly openGraph?: (path: string) => Store;
+    readonly config?: DescryConfig;
+}
+export declare class Session {
+    #private;
+    readonly repoPath: string;
+    readonly config: DescryConfig;
+    constructor(repoPath: string, config: DescryConfig, openGraph?: (path: string) => Store);
+    static open(options: SessionOptions): Promise<Session>;
+    get graphPath(): string;
+    /** Open on first use; reuse thereafter. */
+    store(): Store;
+    /**
+     * MK-4 — `analyze`'s own repair path, and the only caller entitled to one.
+     *
+     * Every other tool goes through `store()`/`provider()` and keeps refusing a
+     * version mismatch per DEC-017 (`SchemaVersionError`'s own message names
+     * this method's caller as the fix). `analyze` is different: it is about to
+     * rebuild the graph from source regardless, so there is nothing lost by
+     * repairing the derived tables first instead of stopping.
+     *
+     * Opens a short-lived `NodeSqliteDriver` directly rather than going through
+     * `this.#openGraph` — the injected-store path a test fixture uses bypasses
+     * a real file on disk entirely, and a `SchemaVersionError` from `migrate()`
+     * only exists for a real one. A no-op here on that path (nothing found to
+     * repair, `rebuilt: false`) is correct: an injected in-memory fixture store
+     * is never stale by construction, and `store()` right after this still
+     * goes through the real, checked path either way — this only ever removes
+     * a refusal that check would otherwise have hit first.
+     */
+    repairStaleGraph(): {
+        readonly rebuilt: boolean;
+    };
+    provider(): AdjacencyProvider;
+    /**
+     * The repo root for an analysis run.
+     *
+     * The commit sha is read from git and **is not defaulted** when git is absent:
+     * every node and edge is stamped with it, and a placeholder would make the
+     * staleness stamp a lie that nothing downstream could detect.
+     */
+    root(): Promise<RepoRoot>;
+    close(): void;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -0,0 +1,302 @@
+/**
+ * One repository, one graph, one process.
+ *
+ * The session owns everything with a lifetime: the SQLite handle, the resolved
+ * configuration, the loaded sources. Tools receive it and own nothing, which is
+ * what lets the whole tool layer be tested against an in-memory graph.
+ *
+ * ## Configuration is read once and reported, not read repeatedly and assumed
+ *
+ * `.descry/config.json` is optional. Everything in it has a default that makes
+ * local mode work unconfigured, per the architecture's local-first guarantee —
+ * except the source list, which cannot have one: this repository must not name
+ * an adapter (see `registry.ts`). So an unconfigured session can query a graph
+ * and cannot build one, and `analyze` says exactly that rather than reporting a
+ * successful run over zero sources.
+ *
+ * ## The graph is opened lazily
+ *
+ * A server that opened the database at startup would fail to start on a repo
+ * that has never been analysed — the worst possible first experience for the
+ * primary UX. Opening on first use means `tools/list` works everywhere, and a
+ * query against a missing graph fails as a *tool* result the agent can read and
+ * act on ("run analyze first"), not as a crash before the handshake.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import { createStoreProvider, gitHead, isGitRepository, NodeSqliteDriver, openStore, rebuildStaleGraph, } from "@descryy/core";
+import { normaliseSpec } from "./registry.js";
+export const CONFIG_RELATIVE_PATH = join(".descry", "config.json");
+export const DEFAULT_GRAPH_RELATIVE_PATH = join(".descry", "graph.db");
+function parseConfirmedFacts(raw, configPath) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new ConfigError(`${configPath}: "confirmedFacts" must be an array`);
+    }
+    return raw.map((entry, index) => {
+        const e = entry;
+        for (const key of ["repo", "blockedBy", "value", "confirmedBy", "confirmedAt"]) {
+            if (typeof e[key] !== "string" || e[key] === "") {
+                throw new ConfigError(`${configPath}: confirmedFacts[${index}].${key} must be a non-empty string`);
+            }
+        }
+        if (e["environment"] !== undefined && (typeof e["environment"] !== "string" || e["environment"] === "")) {
+            throw new ConfigError(`${configPath}: confirmedFacts[${index}].environment must be a non-empty string when present`);
+        }
+        return {
+            repo: e["repo"],
+            blockedBy: e["blockedBy"],
+            value: e["value"],
+            ...(e["environment"] === undefined ? {} : { environment: e["environment"] }),
+            confirmedBy: e["confirmedBy"],
+            confirmedAt: e["confirmedAt"],
+        };
+    });
+}
+/** `(repo, blockedBy, environment)` — `undefined` environment is its own value, never a wildcard. */
+function sameFactKey(a, b) {
+    return a.repo === b.repo && a.blockedBy === b.blockedBy && a.environment === b.environment;
+}
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+export async function loadConfig(repoPath) {
+    const configPath = join(repoPath, CONFIG_RELATIVE_PATH);
+    let raw = {};
+    let found = null;
+    try {
+        raw = JSON.parse(await readFile(configPath, "utf8"));
+        found = configPath;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT") {
+            // A config that exists and cannot be parsed is refused rather than
+            // defaulted past. Silently falling back would run the whole session under
+            // settings the user believes they overrode.
+            throw new ConfigError(`${configPath} exists but could not be read: ${error.message}`);
+        }
+    }
+    if (raw.sources !== undefined && !Array.isArray(raw.sources)) {
+        throw new ConfigError(`${configPath}: "sources" must be an array`);
+    }
+    const sources = (raw.sources ?? []).map((entry, index) => {
+        if (typeof entry === "string")
+            return normaliseSpec(entry);
+        if (typeof entry === "object" && entry !== null && typeof entry.module === "string") {
+            return entry;
+        }
+        throw new ConfigError(`${configPath}: sources[${index}] must be a module specifier or an object with a "module" field`);
+    });
+    return {
+        // The directory name is a defensible default and a poor identity: it changes
+        // when someone clones into a different folder, and every repo-scoped node id
+        // changes with it. Stated in the analyze disclosures rather than left to be
+        // discovered when two machines produce different graphs.
+        repo: typeof raw.repo === "string" && raw.repo !== "" ? raw.repo : basename(resolve(repoPath)),
+        workspace: typeof raw.workspace === "string" && raw.workspace !== "" ? raw.workspace : undefined,
+        graph: typeof raw.graph === "string" && raw.graph !== "" ? raw.graph : DEFAULT_GRAPH_RELATIVE_PATH,
+        sources,
+        confirmedFacts: parseConfirmedFacts(raw.confirmedFacts, configPath),
+        configPath: found,
+    };
+}
+/**
+ * `.descry/config.json`'s writer, the counterpart to `loadConfig`.
+ *
+ * One writer for one file, used by both front doors that set the workspace
+ * id — `descry init` (`@descryhq-wq/cli`) and the `link_workspace` MCP tool — so
+ * the two can never drift into writing two different shapes of the same
+ * file. Fields this function does not know about (`graph`, `sources`, or
+ * anything a future version adds) survive a re-run untouched: this patches
+ * `repo` and `workspace`, it does not own the whole file.
+ */
+export async function writeConfig(repoPath, patch) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        // A config that cannot be parsed is what a write here is entitled to fix
+        // — proceed from an empty base rather than refusing, unlike `loadConfig`,
+        // whose job is to run a session rather than repair one. Genuinely absent
+        // (ENOENT) takes the same path; both mean "start from nothing".
+        void error;
+        existing = {};
+    }
+    const previousWorkspace = typeof existing.workspace === "string" ? existing.workspace : undefined;
+    const next = { ...existing, repo: patch.repo };
+    if (patch.workspace !== undefined)
+        next.workspace = patch.workspace;
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { path, previousWorkspace };
+}
+/**
+ * `confirmedFacts`'s writer — separate from `writeConfig` on purpose.
+ *
+ * `writeConfig`'s own doc is explicit that it "patches `repo` and
+ * `workspace`, it does not own the whole file" — a second, narrow writer for
+ * a second, narrow field keeps that boundary rather than growing one
+ * function into "the file's owner." Both read-modify-write the same JSON
+ * file the same way, so a future field gets a third writer, not a branch in
+ * this one.
+ *
+ * Keyed on exact `(repo, blockedBy, environment)` — DEC-223 §3 and
+ * `ConfirmedFact`'s own doc; `environment` is `undefined` for an unscoped
+ * answer, which is its own distinct key value, not a wildcard that a later
+ * environment-scoped answer would collide with. A second call with the same
+ * key **replaces** the first rather than appending a duplicate: a
+ * re-confirmation (the value changed, or the same value is being
+ * re-asserted after §7's staleness note) updates in place, and a caller can
+ * always find out what was overwritten from the return value rather than
+ * having to read the file first. A second call with a *different*
+ * environment for the same `blockedBy` adds a second fact rather than
+ * replacing the first — a repository can genuinely need one value per
+ * environment.
+ */
+export async function writeConfirmedFact(repoPath, fact) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        void error;
+        existing = {};
+    }
+    const priorRaw = Array.isArray(existing["confirmedFacts"]) ? existing["confirmedFacts"] : [];
+    const prior = parseConfirmedFacts(priorRaw, path);
+    const replaced = prior.find((f) => sameFactKey(f, fact)) ?? null;
+    const rest = prior.filter((f) => !sameFactKey(f, fact));
+    const next = { ...existing, confirmedFacts: [...rest, fact] };
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { path, replaced };
+}
+/**
+ * `sources`' writer — MK-3, the third narrow field-writer beside `writeConfig`
+ * (`repo`/`workspace`) and `writeConfirmedFact` (`confirmedFacts`), for the
+ * same reason those two stayed separate: a shared file gets one writer per
+ * field it owns, not one function that grows a branch per field.
+ *
+ * Unconditional: the caller (`descry init`) decides whether writing is
+ * appropriate — reading `loadConfig(repoPath).sources` first and skipping
+ * this call when it is already non-empty — because "should this overwrite
+ * what's there" is a policy question `writeConfig`'s own precedent leaves to
+ * the caller, not to the file-writing primitive.
+ */
+export async function writeSources(repoPath, sources) {
+    const path = join(repoPath, CONFIG_RELATIVE_PATH);
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        void error;
+        existing = {};
+    }
+    const next = { ...existing, sources: [...sources] };
+    await mkdir(join(repoPath, ".descry"), { recursive: true });
+    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { path };
+}
+export class Session {
+    repoPath;
+    config;
+    #store = null;
+    #provider = null;
+    #openGraph;
+    constructor(repoPath, config, openGraph) {
+        this.repoPath = repoPath;
+        this.config = config;
+        this.#openGraph = openGraph ?? ((path) => openStore(path));
+    }
+    static async open(options) {
+        const repoPath = resolve(options.repoPath);
+        const config = options.config ?? (await loadConfig(repoPath));
+        return new Session(repoPath, config, options.openGraph);
+    }
+    get graphPath() {
+        return isAbsolute(this.config.graph)
+            ? this.config.graph
+            : join(this.repoPath, this.config.graph);
+    }
+    /** Open on first use; reuse thereafter. */
+    store() {
+        if (this.#store === null)
+            this.#store = this.#openGraph(this.graphPath);
+        return this.#store;
+    }
+    /**
+     * MK-4 — `analyze`'s own repair path, and the only caller entitled to one.
+     *
+     * Every other tool goes through `store()`/`provider()` and keeps refusing a
+     * version mismatch per DEC-017 (`SchemaVersionError`'s own message names
+     * this method's caller as the fix). `analyze` is different: it is about to
+     * rebuild the graph from source regardless, so there is nothing lost by
+     * repairing the derived tables first instead of stopping.
+     *
+     * Opens a short-lived `NodeSqliteDriver` directly rather than going through
+     * `this.#openGraph` — the injected-store path a test fixture uses bypasses
+     * a real file on disk entirely, and a `SchemaVersionError` from `migrate()`
+     * only exists for a real one. A no-op here on that path (nothing found to
+     * repair, `rebuilt: false`) is correct: an injected in-memory fixture store
+     * is never stale by construction, and `store()` right after this still
+     * goes through the real, checked path either way — this only ever removes
+     * a refusal that check would otherwise have hit first.
+     */
+    repairStaleGraph() {
+        if (this.#store !== null)
+            return { rebuilt: false };
+        const driver = new NodeSqliteDriver();
+        try {
+            driver.open(this.graphPath);
+            return rebuildStaleGraph(driver);
+        }
+        catch {
+            // Anything from opening — a missing directory, a genuinely corrupt file
+            // — is not this method's job to diagnose. `store()` right after this
+            // hits the same path through its own, already-disclosed error handling.
+            return { rebuilt: false };
+        }
+        finally {
+            driver.close();
+        }
+    }
+    provider() {
+        if (this.#provider === null)
+            this.#provider = createStoreProvider(this.store().driver);
+        return this.#provider;
+    }
+    /**
+     * The repo root for an analysis run.
+     *
+     * The commit sha is read from git and **is not defaulted** when git is absent:
+     * every node and edge is stamped with it, and a placeholder would make the
+     * staleness stamp a lie that nothing downstream could detect.
+     */
+    async root() {
+        if (!(await isGitRepository(this.repoPath))) {
+            throw new ConfigError(`${this.repoPath} is not a git repository. Every node is stamped with the commit it was ` +
+                "read at, so there is nothing honest to record for a directory with no history.");
+        }
+        return {
+            repo: this.config.repo,
+            ...(this.config.workspace === undefined ? {} : { workspace: this.config.workspace }),
+            absolutePath: this.repoPath,
+            commitSha: await gitHead(this.repoPath),
+        };
+    }
+    close() {
+        this.#store?.close();
+        this.#store = null;
+        this.#provider = null;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/tools/analyze.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `analyze` — read the repository into the graph.
+ *
+ * The only tool that writes. Everything else queries what this produced, so its
+ * disclosures are the ones that matter most: a query cannot report a gap it was
+ * never told about, and this is where the gaps become known.
+ *
+ * ## What is disclosed, and why each one earns its line
+ *
+ * - **Sources that would not load.** "No problem found in your Python service"
+ *   and "your Python adapter did not import" are different statements (§20.2).
+ * - **Sources that loaded and did not claim the repository.** The same
+ *   distinction, one level up: an unanalysed language is *not analysable*, not
+ *   clean.
+ * - **The resolution each source reached.** A run that degraded to R0 because a
+ *   virtualenv was missing produces a graph that looks identical to a healthy
+ *   one until you read this number. Principle 3 then caps everything above it.
+ * - **Identity collisions.** Two things arrived under one id. There is no
+ *   correct merge, so the builder reports rather than picks (DEC-024).
+ * - **Evicted files.** Rows a previous run owned and this one did not re-supply.
+ *   They are gone from the graph; a query over them will now find nothing, and
+ *   nothing would otherwise say why.
+ * - **The workspace join.** Zero cross-repo joins looks exactly like success.
+ *
+ * ## The repo identity warning
+ *
+ * With no `.descry/config.json`, `repo` defaults to the directory name — and
+ * every repo-scoped node id is a hash over it. Clone into a differently-named
+ * folder and every id changes, which silently destroys incident links and
+ * `CHANGES_WITH` weights. That is DEC-004's failure arriving through the one
+ * field a default cannot get right, so it is stated on every unconfigured run.
+ */
+import type { UnresolvedRef } from "@descryy/ir";
+import type { BuildResult, StoreCounts } from "@descryy/core";
+import { type ToolDefinition } from "./kit.ts";
+/**
+ * What one source read, and how well.
+ *
+ * `reachedResolution` is the number principle 3 caps everything above it by. A
+ * run that degraded to R0 because a dependency was missing produces a graph
+ * that looks identical to a healthy one until this field is read.
+ */
+export interface SourceRun {
+    readonly source: string;
+    readonly files: number;
+    readonly nodes: number;
+    readonly edges: number;
+    /** Refusal-ledger rows: gaps this source disclosed rather than guessed at. */
+    readonly unresolved: number;
+    /**
+     * Files this source attempted but could not parse — absent from the graph
+     * entirely, not confirmed clean. Never counted in `files`; see
+     * `IRBatch.skippedFiles`.
+     */
+    readonly skippedFiles: number;
+    readonly reachedResolution: number;
+    /** Wall-clock time this source took, including the git-history reader. */
+    readonly ms: number;
+}
+export interface AnalyzeData {
+    readonly repo: string;
+    readonly workspace: string | null;
+    readonly commitSha: string;
+    readonly graphPath: string;
+    /** One entry per source that ran. An empty array is the not-analysable case. */
+    readonly sources: readonly SourceRun[];
+    /** Configured sources whose module would not import. Not clean — unread. */
+    readonly sourcesFailed: readonly {
+        readonly module: string;
+        readonly reason: string;
+    }[];
+    /** Sources that loaded and did not claim this repository, with why. */
+    readonly sourcesSkipped: readonly {
+        readonly source: string;
+        readonly reason: string;
+    }[];
+    /** Row counts in the store after this run. */
+    readonly stored: StoreCounts;
+    readonly merge: {
+        /** Node ids more than one source supplied — this is the cross-language join, not an error. */
+        readonly mergedNodes: number;
+        readonly mergedEdges: number;
+        /** Two different things under one id. There is no correct merge, so they are reported (DEC-024). */
+        readonly collisions: number;
+        /** Edges dropped because an endpoint resolved to nothing. Never stubbed. */
+        readonly droppedEdges: number;
+        readonly rejections: number;
+    };
+    /** Per workspace-scoped node type: how many exist and how many two repositories both supplied. */
+    readonly joins: BuildResult["joins"];
+    readonly written: {
+        readonly nodes: number;
+        readonly edges: number;
+        readonly unresolved: number;
+        readonly orphanedEdges: number;
+        /** Files a previous run owned and this one did not re-supply. Their rows are gone. */
+        readonly evictedFiles: number;
+    };
+    /** Edges minted from human-confirmed answers, capped at reliability class B by DEC-223. */
+    readonly minted: {
+        readonly edges: number;
+        readonly orphaned: number;
+        readonly unjoinable: number;
+        readonly evictedFiles: number;
+    };
+}
+/**
+ * §5.4's `refusals` field, for this run only — never the graph's whole
+ * stored ledger (`refusal_fetch`'s job). `built.unresolved` is what the
+ * sources this call just read could not resolve, so it is a fresh
+ * population every run rather than accumulated history, and honestly
+ * scoped to "what this call found" the way the field's own contract asks.
+ *
+ * `undefined` on zero rows — the envelope's `refusals` stays `null` rather
+ * than carrying a summary with no exemplar or handle to show (matching
+ * `summariseRefusals`'s own `count === 0` shape one level up).
+ */
+export declare function refusalSummaryField(unresolved: readonly UnresolvedRef[]): {
+    readonly count: number;
+    readonly exemplar: string;
+    readonly handle: string;
+} | undefined;
+export declare const analyzeTool: ToolDefinition;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/tools/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/tools/analyze.ts"],"names":[],"mappings":"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"}