@descryy/mcp 0.11.5 → 0.11.6

package/dist/tools/runtime-journey-drive.js

@@ -0,0 +1,247 @@
+/**
+ * RG-4 — both halves in the MCP layer, and RG-6's MCP half (video).
+ *
+ * `runInstrumentedExecution`'s `onReady` fires after every declared service's
+ * readiness has succeeded and before the observation window's sleep — the one
+ * moment in a run when the application is provably up and still alive. The
+ * desktop already composes exactly this way (`descry-desktop/packages/session/
+ * src/pipeline/browser-drive.ts`, invoked from `runtime-execution.ts`'s own
+ * `onReady`), so that browser evidence lands in the **same `EvidenceStore`
+ * under the same `executionId`** as the backend's. `observe_runtime` here
+ * never did: it passed no `onReady` and never drove a browser, so an MCP
+ * client got two calls with two lifetimes and nothing to prove they were the
+ * same run.
+ *
+ * This module is the MCP equivalent of the desktop's `browser-drive.ts` —
+ * same collectors, same package, same "never fabricate a step" discipline —
+ * built as its own file because `packages/mcp/src/browser/driver.ts` and
+ * `playwright-driver.ts` are lane identity's (a session-scoped, interactive
+ * `BrowserDriver` port for the `browser_*` tools' own lifetime) and this is a
+ * different lifetime entirely: one drive, bound to one execution's readiness
+ * window, torn down before that execution's observation window even starts.
+ * Composing through the identity lane's port would mean threading a whole
+ * interactive session through a callback that must complete before
+ * `onReady` returns — the wrong shape for what is, structurally, a single
+ * batch replay. `@descryy/runtime-browser`'s own collectors compose directly
+ * instead, the same way the desktop does it.
+ *
+ * ## The journey comes from the caller, projected by the ONE shared format
+ *
+ * `DEC-NEXT-runtime-journey-is-one-declared-format` (Q1) settled this: a
+ * saved `Scenario` and a driveable step list are two views of one format,
+ * and lane journey built the single projection both directions go through —
+ * `../scenarios/browser-run-plan-projection.ts`'s `projectScenarioToRunPlan`.
+ * This module calls that function and nothing else invents a second
+ * translation of the same scenario. Its own header explains exactly what
+ * projects and what refuses (seven shared verbs; `fill`, whole-page
+ * assertions and anything outside those seven are refused by name, never
+ * silently narrowed), and secret references are resolved inside it before
+ * this module ever sees a step — see that module's own doc.
+ *
+ * A `Scenario` with no steps drives to `startUrl` and observes, same as an
+ * empty step list does anywhere else in this codebase. No step is ever
+ * synthesized here.
+ *
+ * `@descryy/runtime-browser`'s `BrowserActionCollector` happens to support
+ * more than the shared projection's seven verbs (`assertVisible`/`assertText`
+ * included) — this module drives every one of the seven the projection
+ * can produce, which is a strict superset of what the desktop's narrower
+ * `BrowserStep` union can act on. `fill` is not among them: the shared
+ * projection refuses it because `BrowserStep` (the format's other consumer)
+ * has no counterpart for it, a decision this module does not own and does
+ * not work around — see the projection's own header for why collapsing it
+ * into `type` would be exactly the kind of silent narrowing rule 2 forbids.
+ */
+import { createBrowserActionCollector, createBrowserConsoleCollector, createBrowserNetworkCollector, launchBrowserSession, } from "@descryy/runtime-browser";
+import { projectScenarioToRunPlan } from "../scenarios/browser-run-plan-projection.js";
+export { projectScenarioToRunPlan };
+const DEFAULT_SETTLE_FOR_MS = 1_000;
+export function createRuntimeJourneyDrive(plan) {
+    const launch = plan.launchSession ?? launchBrowserSession;
+    const steps = plan.steps ?? [];
+    return async (input) => {
+        const harnessError = (detail) => {
+            input.store.write({
+                executionId: input.executionId,
+                timestamp: new Date().toISOString(),
+                source: "harness",
+                service: plan.service ?? null,
+                process: null,
+                eventType: "COLLECTOR_ERROR",
+                payload: { raw: detail, error: detail, collectorId: "runtime-journey-drive" },
+                traceId: null,
+                requestId: null,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                confidence: 1,
+                collectorVersion: RUNTIME_JOURNEY_DRIVE_VERSION,
+            });
+        };
+        let session;
+        try {
+            session = await launch({
+                headless: plan.headless ?? true,
+                ...(plan.recordVideo === true ? { recordVideo: true } : {}),
+            });
+        }
+        catch (error) {
+            const cause = describe(error);
+            const disclosure = `No browser was driven for this run: the browser session could not be launched (${cause}). ` +
+                `Backend evidence is unaffected — this drive runs inside the readiness window and never blocks it.`;
+            harnessError(disclosure);
+            return { ran: false, startUrl: plan.startUrl, stepsCompleted: 0, stepsRefused: [], videoBytes: null, disclosure };
+        }
+        const actions = createBrowserActionCollector({ session, ...(plan.service === undefined ? {} : { service: plan.service }) });
+        const consoleCollector = createBrowserConsoleCollector({
+            session,
+            ...(plan.service === undefined ? {} : { service: plan.service }),
+            ...(input.stackTraceParser === undefined ? {} : { stackTraceParser: input.stackTraceParser }),
+        });
+        const networkCollector = createBrowserNetworkCollector({
+            session,
+            ...(plan.service === undefined ? {} : { service: plan.service }),
+            ...(input.stackTraceParser === undefined ? {} : { stackTraceParser: input.stackTraceParser }),
+        });
+        const context = {
+            executionId: input.executionId,
+            configuration: input.configuration,
+            emit: (evidence) => {
+                input.store.write({ ...evidence, executionId: input.executionId });
+            },
+            ...(input.resolveSourceRoot === undefined ? {} : { resolveSourceRoot: input.resolveSourceRoot }),
+        };
+        const refusals = [];
+        const unavailable = [];
+        let completed = 0;
+        let videoBytes = null;
+        try {
+            for (const [name, collector] of [
+                ["browser-console", consoleCollector],
+                ["browser-network", networkCollector],
+                ["browser-action", actions],
+            ]) {
+                try {
+                    const started = await collector.start(context);
+                    if (!started.available)
+                        unavailable.push(`${name} (${started.reason ?? "no reason given"})`);
+                }
+                catch (error) {
+                    unavailable.push(`${name} (start() threw: ${describe(error)})`);
+                    harnessError(`browser collector "${name}" threw during start(): ${describe(error)}`);
+                }
+            }
+            await actions.navigate(plan.startUrl);
+            for (const [index, step] of steps.entries()) {
+                try {
+                    await runStep(actions, step);
+                    completed += 1;
+                }
+                catch (error) {
+                    const reason = describe(error);
+                    refusals.push({ index, kind: step.kind, reason });
+                    harnessError(`journey step ${String(index + 1)} (${step.kind}) could not be performed: ${reason}`);
+                }
+            }
+            await sleep(plan.settleForMs ?? DEFAULT_SETTLE_FOR_MS);
+        }
+        catch (error) {
+            const cause = describe(error);
+            harnessError(`the journey drive stopped early: ${cause}`);
+            refusals.push({ index: completed, kind: "navigate", reason: cause });
+        }
+        // Same ordering constraint as the desktop's browser-drive.ts: captureVideo() must run
+        // after session.close() (Playwright only finalizes recordVideo once the context closes)
+        // and before actions.stop() (which clears the emit channel it writes into).
+        videoBytes = await finish(consoleCollector, networkCollector, actions, session, input, harnessError);
+        const disclosure = describeShortfall(unavailable, refusals, plan);
+        return { ran: true, startUrl: plan.startUrl, stepsCompleted: completed, stepsRefused: refusals, videoBytes, disclosure };
+    };
+}
+async function finish(consoleCollector, networkCollector, actions, session, input, harnessError) {
+    const before = countVideoBytes(input);
+    for (const [name, stop] of [
+        ["browser-console", () => consoleCollector.stop()],
+        ["browser-network", () => networkCollector.stop()],
+        ["browser-session", () => session.close()],
+        ["browser-video", () => actions.captureVideo()],
+        ["browser-action", () => actions.stop()],
+    ]) {
+        try {
+            await stop();
+        }
+        catch (error) {
+            harnessError(`journey drive teardown step "${name}" failed: ${describe(error)}`);
+        }
+    }
+    const after = countVideoBytes(input);
+    return after === before ? null : after;
+}
+function countVideoBytes(input) {
+    for (const evidence of input.store.getByExecution(input.executionId)) {
+        if (evidence.eventType !== "VIDEO")
+            continue;
+        const payload = evidence.payload;
+        if (typeof payload?.videoBase64 !== "string")
+            continue;
+        return Buffer.from(payload.videoBase64, "base64").length;
+    }
+    return null;
+}
+/** Never throws on a step this module cannot resolve to an action — that would surface as a
+ *  bare refusal with a useless reason; a `ProjectedStep` naming no target/text for a kind that
+ *  needs one is a defect in the projection this module trusts rather than something to re-check
+ *  here, so those are stated plainly rather than re-validated. */
+async function runStep(actions, step) {
+    switch (step.kind) {
+        case "navigate":
+            if (step.url === null)
+                throw new Error(`"navigate" step carries no url`);
+            return actions.navigate(step.url);
+        case "click":
+            return actions.click(requireSelector(step));
+        case "type":
+            return actions.type(requireSelector(step), requireText(step));
+        case "select":
+            return actions.select(requireSelector(step), requireText(step));
+        case "submit":
+            return actions.submit(requireSelector(step));
+        case "assertVisible":
+            return actions.assertVisible(requireSelector(step));
+        case "assertText":
+            return actions.assertText(requireSelector(step), requireText(step));
+    }
+}
+function requireSelector(step) {
+    if (step.target === null)
+        throw new Error(`"${step.kind}" step carries no target`);
+    return step.target.selector;
+}
+function requireText(step) {
+    if (step.text === null)
+        throw new Error(`"${step.kind}" step carries no text`);
+    return step.text;
+}
+function describeShortfall(unavailable, refusals, plan) {
+    const parts = [];
+    if (unavailable.length > 0) {
+        parts.push(`These browser collectors reported themselves unavailable and observed nothing: ${unavailable.join("; ")}.`);
+    }
+    if (refusals.length > 0) {
+        parts.push(`${String(refusals.length)} of ${String((plan.steps ?? []).length)} declared journey step(s) could not be performed: ` +
+            refusals.map((r) => `step ${String(r.index + 1)} (${r.kind}): ${r.reason}`).join("; ") +
+            ".");
+    }
+    return parts.length === 0 ? null : parts.join(" ");
+}
+function describe(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** This module's own collector version, distinct from `@descryy/runtime-browser`'s — these rows
+ *  are the composition lane's own harness reports about driving, not the browser package's. */
+export const RUNTIME_JOURNEY_DRIVE_VERSION = "descry-mcp-runtime-journey-drive@1";
+//# sourceMappingURL=runtime-journey-drive.js.map

package/dist/tools/runtime-journey-drive.js.map

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

package/dist/tools/scope.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `scope` — §12.5 diff scoping: what else does this change touch? Expansion stops
+ * on score, not hop count — a payment gateway 4 hops out matters, a logging import
+ * 1 hop out doesn't. A file the graph never heard of has two causes (not analysable,
+ * or stale graph) — both disclosed, never reported as "0 affected" (§20.2's collapse). */
+import { type ScopeTier } from "@descryy/core";
+import type { EdgeType } from "@descryy/ir";
+import { type BriefNode, type ToolDefinition } from "./kit.ts";
+/** A node in the scope, with why it is in it. */
+export interface ScopedNodeReport extends BriefNode {
+    readonly score: number;
+    readonly tier: ScopeTier;
+    readonly depth: number;
+    /** The edge type this node was reached through. Absent for a seed. */
+    readonly via?: EdgeType;
+}
+/** Tier 1 is the changed set itself; 2-4 are the scoring bands beneath it. */
+export interface ScopeTierCount {
+    readonly tier: number;
+    readonly count: number;
+}
+export interface ScopeReport {
+    /** Capped by `limit`; `changedTotal` is the uncapped count. Every seed is
+     *  traversed either way — the cap shortens the listing, not the analysis. */
+    readonly changed: readonly ScopedNodeReport[];
+    readonly changedTotal: number;
+    /** Capped by `limit`; `affectedTotal` is the uncapped count. */
+    readonly affected: readonly ScopedNodeReport[];
+    readonly affectedTotal: number;
+    readonly droppedForBudget: number;
+    readonly budget: number;
+    readonly budgetUsed: number;
+    readonly byTier: readonly ScopeTierCount[];
+}
+/** Nothing named resolved into the graph, so the traversal never ran — a different
+ *  shape, not a zeroed `ScopeReport`: no `budget`/`affectedTotal` because nothing ran.
+ *  Narrow on `"seeds" in data`. */
+export interface ScopeNotSeeded {
+    readonly changed: readonly ScopedNodeReport[];
+    readonly affected: readonly ScopedNodeReport[];
+    readonly seeds: number;
+}
+export type ScopeData = ScopeReport | ScopeNotSeeded;
+export declare const scopeTool: ToolDefinition;
+//# sourceMappingURL=scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/tools/scope.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAE1F,OAAO,EAA8C,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAOL,KAAK,SAAS,EAEd,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAIlB,iDAAiD;AACjD,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B;iFAC6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;CAC5C;AAED;;mCAEmC;AACnC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,cAAc,CAAC;AA8OrD,eAAO,MAAM,SAAS,EAAE,cAavB,CAAC"}

package/dist/tools/scope.js

@@ -0,0 +1,217 @@
+/**
+ * `scope` — §12.5 diff scoping: what else does this change touch? Expansion stops
+ * on score, not hop count — a payment gateway 4 hops out matters, a logging import
+ * 1 hop out doesn't. A file the graph never heard of has two causes (not analysable,
+ * or stale graph) — both disclosed, never reported as "0 affected" (§20.2's collapse). */
+import { nodesInFiles, scopeChange } from "@descryy/core";
+import { answer, briefNode, optionalEnum, optionalInteger, optionalStringArray, ToolInputError, } from "./kit.js";
+import { capBySize, capped, sizeCapNote } from "../capped.js";
+const TRIGGERS = ["pre-push", "pr", "nightly"];
+const SCHEMA = {
+    type: "object",
+    properties: {
+        files: {
+            type: "array",
+            items: { type: "string" },
+            description: "Repository-relative paths that are changing. Every symbol declared in them seeds the " +
+                "blast radius.",
+        },
+        nodeIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Graph node ids to seed with directly, instead of or as well as files.",
+        },
+        trigger: {
+            type: "string",
+            enum: [...TRIGGERS],
+            description: "Which node budget to use: pre-push 200, pr 1000, nightly 5000. Default pr.",
+        },
+        budget: {
+            type: "integer",
+            minimum: 1,
+            description: "Override the trigger's node budget.",
+        },
+        limit: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap how many nodes come back in the reply — applied to the changed list and the affected " +
+                "list alike. Default 25 (MK-9 — the same walk-cost reduction impact.ts applies, for the " +
+                "same reason). Capping the changed list shortens only the listing: every changed symbol " +
+                "still seeds the traversal, and changedTotal reports how many there were. A capped reply " +
+                "always discloses shown/total; raise this explicitly when the full set is needed.",
+        },
+    },
+    additionalProperties: false,
+};
+/**
+ * `fitToBudget` for `ScopeReport` — a scaffold of scalars plus two lists,
+ * `changed` and `affected`, already cut once by `limit`. Neither row carries
+ * a droppable payload, so shrinking further means only dropping trailing
+ * rows from each, `changed` first: every seed still seeded the traversal
+ * either way, but it is the caller's own named files, the more load-bearing
+ * of the two lists to keep whole.
+ */
+function fitScope(rest, shapedChanged, shapedAffected, totalRows, budgetBytes) {
+    const scaffoldBytes = Buffer.byteLength(JSON.stringify({ ...rest, changed: [], affected: [] }), "utf8");
+    const changedFit = capBySize(shapedChanged, budgetBytes, scaffoldBytes);
+    const spentOnChanged = Buffer.byteLength(JSON.stringify(changedFit.shown), "utf8");
+    const affectedFit = capBySize(shapedAffected, Math.max(budgetBytes - scaffoldBytes - spentOnChanged, 0), 0);
+    const notes = [];
+    if (changedFit.droppedForSize > 0) {
+        notes.push(sizeCapNote("changed symbol", changedFit.shown.length, shapedChanged.length, changedFit.droppedForSize));
+    }
+    if (affectedFit.droppedForSize > 0) {
+        notes.push(sizeCapNote("affected node", affectedFit.shown.length, shapedAffected.length, affectedFit.droppedForSize));
+    }
+    const droppedNow = changedFit.droppedForSize + affectedFit.droppedForSize;
+    return {
+        data: { ...rest, changed: changedFit.shown, affected: affectedFit.shown },
+        notes,
+        ...(droppedNow === 0
+            ? {}
+            : { truncatedDetail: { shown: changedFit.shown.length + affectedFit.shown.length, total: totalRows, more: null } }),
+    };
+}
+function shape(entry) {
+    return {
+        ...briefNode(entry.node),
+        score: Number(entry.score.toFixed(4)),
+        tier: entry.tier,
+        depth: entry.depth,
+        ...(entry.via === null ? {} : { via: entry.via.type }),
+    };
+}
+async function run(args, ctx) {
+    const files = optionalStringArray(args, "files") ?? [];
+    const seedIds = [...(optionalStringArray(args, "nodeIds") ?? [])];
+    const trigger = optionalEnum(args, "trigger", TRIGGERS) ?? "pr";
+    const budget = optionalInteger(args, "budget", 1);
+    const limit = optionalInteger(args, "limit", 1) ?? 25;
+    if (files.length === 0 && seedIds.length === 0) {
+        throw new ToolInputError('give at least one of "files" or "nodeIds"');
+    }
+    const notes = [];
+    const session = ctx.session;
+    if (files.length > 0) {
+        ctx.progress(`Resolving ${files.length} path(s) to graph nodes`);
+        const absolute = files.filter((f) => f.startsWith("/"));
+        if (absolute.length > 0) {
+            notes.push(`${absolute.length} path(s) were absolute. The graph stores repository-relative paths, so ` +
+                "these matched nothing. Pass paths relative to the repository root.");
+        }
+        const { nodes, missing } = nodesInFiles(session.store().driver, files);
+        for (const node of nodes)
+            seedIds.push(node.id);
+        if (missing.length > 0) {
+            notes.push(`${missing.length} of ${files.length} path(s) have no node in the graph ` +
+                `(${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ", …" : ""}). Either no ` +
+                "configured adapter reads them or the graph predates them — run analyze. Their impact " +
+                "is not in this answer and they are not reported as having none.");
+        }
+    }
+    if (seedIds.length === 0) {
+        const base = session.provider().baseStamp();
+        return answer({
+            headline: "Nothing in the graph matches what you named, so no blast radius could be computed.",
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes: [
+                ...notes,
+                "This is not a result of zero impact. No seed node was found, so the traversal never ran.",
+            ],
+            data: { changed: [], affected: [], seeds: 0 },
+        });
+    }
+    ctx.progress(`Expanding from ${seedIds.length} changed symbol(s)`);
+    const scoped = scopeChange(session.provider(), [...new Set(seedIds)], {
+        trigger,
+        ...(budget === undefined ? {} : { budget }),
+    });
+    const affected = scoped.data.affected;
+    // `capped()` produces the slice and its shown/total detail together, so this reply
+    // can't cap without carrying what it capped — previously hand-sliced with only the
+    // prose note updated, so `truncated`/`truncatedDetail` stayed unset on the wire.
+    const cap = capped(affected, limit);
+    if (cap.detail !== null) {
+        notes.push(`${cap.detail.total - cap.detail.shown} lower-scoring affected node(s) are in the scope but not ` +
+            `listed here — the reply is capped at ${limit}. Raise "limit" to see them; they were ` +
+            "analysed either way.");
+    }
+    // P6-B5. `limit` used to bound `affected` alone, and `changed` — one entry per
+    // symbol declared in the named files — went out whole. That is unbounded by
+    // anything the caller controls: it is the size of the files they named, not of
+    // the answer they asked for. One generated file produced 638 entries and 162k
+    // characters, past the client's token limit, and the invariant sweep in
+    // `truncation-invariant.test.ts` could not catch it because an uncapped list
+    // emits no capping prose to scan for. The seeds are still all *analysed* — the
+    // traversal runs over every one of them, and `changedTotal` reports how many
+    // there were, so a capped list can never read as a smaller change than it was.
+    const changedCap = capped(scoped.data.changed, limit);
+    if (changedCap.detail !== null) {
+        notes.push(`${changedCap.detail.total - changedCap.detail.shown} of ${changedCap.detail.total} changed ` +
+            `symbol(s) are not listed here — the reply is capped at ${limit}. All ${changedCap.detail.total} ` +
+            'seeded the traversal; only the listing is shortened. Raise "limit" to see them.');
+    }
+    const byTier = [1, 2, 3, 4].map((tier) => ({
+        tier,
+        count: tier === 1
+            ? scoped.data.changed.length
+            : affected.filter((node) => node.tier === tier).length,
+    }));
+    // One `truncatedDetail` for a reply that now caps two lists: the rows carried
+    // versus the rows there were. Summing is the only reading of "the primary
+    // collection" that stays true when either list is cut — reporting `affected`'s
+    // pair alone would say nothing was withheld on a reply that withheld 290 seeds.
+    const shownRows = changedCap.shown.length + cap.shown.length;
+    const totalRows = scoped.data.changed.length + affected.length;
+    const truncatedDetail = changedCap.detail === null && cap.detail === null
+        ? null
+        : { shown: shownRows, total: totalRows, more: null };
+    const shapedChanged = changedCap.shown.map(shape);
+    const shapedAffected = cap.shown.map(shape);
+    const restOfData = {
+        changedTotal: scoped.data.changed.length,
+        affectedTotal: affected.length,
+        droppedForBudget: scoped.data.dropped.length,
+        budget: scoped.data.budget,
+        budgetUsed: scoped.data.budgetUsed,
+        byTier,
+    };
+    return {
+        result: {
+            ...scoped,
+            data: { ...restOfData, changed: shapedChanged, affected: shapedAffected },
+            // Deliberately not `scoped.truncated` (the node *budget*'s own drop flag,
+            // disclosed separately via `droppedForBudget`) — this `truncated` means "this
+            // reply is shorter than the scope computed," a different fact from that.
+            truncated: truncatedDetail !== null,
+            notes: [...scoped.notes, ...notes],
+        },
+        ...(truncatedDetail === null ? {} : { truncatedDetail }),
+        ...(affected.length === 0 ? { state: "empty" } : {}),
+        nameLevel: true,
+        headline: `${scoped.data.changed.length} changed symbol(s) reach ${affected.length} other node(s) ` +
+            `above the impact threshold, under the ${trigger} budget of ${scoped.data.budget}.`,
+        fitToBudget: (budgetBytes) => fitScope(restOfData, shapedChanged, shapedAffected, totalRows, budgetBytes),
+    };
+}
+export const scopeTool = {
+    name: "scope",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Blast radius of a change",
+    description: "Given the files or symbols you are changing, return what else is affected, ranked by impact " +
+        "score and grouped into tiers 1-4. Expansion stops on score rather than hop count, so a " +
+        "distant high-impact dependency is kept and a nearby trivial one is dropped. Names the paths " +
+        "it could not find in the graph rather than reporting them as unaffected.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=scope.js.map

package/dist/tools/scope.js.map

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

package/dist/tools/similar-incidents.d.ts

@@ -0,0 +1,43 @@
+/** `similar_incidents` ranks existing `INCIDENT` nodes against a failure with no graph node yet,
+ *  deterministically (file/token Jaccard, no vector store). DEC-274 found zero `INCIDENT` nodes
+ *  across three repos (734/459/203 commits): recall is 0/0, not 0% — an empty result never means
+ *  "no similar incident exists" (DEC-279). §1.3a: a zero-incident graph is `refused`, never `empty`
+ *  — the same split `contracts` and `propagation` apply to their own zero-population case. */
+import { type SimilarIncidentSignalKind } from "@descryy/core";
+import { type BriefNode, type ToolDefinition } from "./kit.ts";
+/** One signal that fired for a candidate — the "why", never a bare score. */
+export interface SimilarIncidentSignalReport {
+    readonly kind: SimilarIncidentSignalKind;
+    /** Jaccard similarity for this signal alone, 0..1. */
+    readonly score: number;
+}
+export interface SimilarIncidentReport {
+    readonly incident: BriefNode;
+    /** The `FIX_PATTERN` this incident resolved to, when a `FIXED_BY` edge exists. */
+    readonly fix: BriefNode | null;
+    /** How this incident was detected (`attrs.detectedVia`) — reported per match since the
+     *  mechanisms differ: revert, `Fixes #123`, a process dying at runtime, or `developer-confirmed`
+     *  testimony (capped at reliability B, DEC-223). `null` for incidents minted before this field. */
+    readonly detectedVia: string | null;
+    readonly signals: readonly SimilarIncidentSignalReport[];
+    /** Weighted combination of every signal the query attempted, 0..1. */
+    readonly score: number;
+}
+/** One shape, both branches: `analysed: false` with `incidentsInGraph: 0` is the zero-denominator
+ *  case, `state: "refused"`. Counts live in the payload, not just prose, so a caller can read the
+ *  denominator without parsing a sentence. */
+export interface SimilarIncidentsData {
+    readonly query: {
+        readonly touchedFiles: readonly string[];
+        readonly errorMessage: string | null;
+    };
+    readonly matches: readonly SimilarIncidentReport[];
+    /** Count before `limit` — honest about what was capped. */
+    readonly matchesTotal: number;
+    /** How many `INCIDENT` nodes were available to compare against. Zero is the headline fact. */
+    readonly incidentsInGraph: number;
+    /** False when the graph holds no `INCIDENT` node at all: nothing was compared. */
+    readonly analysed: boolean;
+}
+export declare const similarIncidentsTool: ToolDefinition;
+//# sourceMappingURL=similar-incidents.d.ts.map

package/dist/tools/similar-incidents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similar-incidents.d.ts","sourceRoot":"","sources":["../../src/tools/similar-incidents.ts"],"names":[],"mappings":"AAAA;;;;8FAI8F;AAE9F,OAAO,EAAoB,KAAK,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAOL,KAAK,SAAS,EAEd,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AA2BlB,6EAA6E;AAC7E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B;;uGAEmG;IACnG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;8CAE8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;QACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAwLD,eAAO,MAAM,oBAAoB,EAAE,cAYlC,CAAC"}