@descryy/mcp 0.1.2 → 0.3.0

package/dist/tools/link-workspace.js

@@ -38,7 +38,7 @@
  */
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import { writeConfig } from "../session.js";
+import { writeConfig, writeWorkspaceRepos } from "../session.js";
 import { answer, requiredString, ToolInputError } from "./kit.js";
 const SCHEMA = {
     type: "object",
@@ -113,6 +113,17 @@ async function run(args, ctx) {
             notes.push(`${entry.repo}: replaced previous workspace "${result.previousWorkspace}" with "${workspace}".`);
         }
     }
+    // The membership list, written into every repository that took the workspace
+    // id — and only after the loop, so it names the repositories the link
+    // actually reached rather than the ones it was asked about. A workspace name
+    // alone tells a session nothing about where its siblings live on disk, and a
+    // workspace-scoped confirmed fact lives in whichever repository recorded it
+    // (DEC-NEXT-workspace-scoped-confirmed-facts). Still nothing inferred: this
+    // is the caller's own list, resolved to absolute paths and written back.
+    const members = written.map((w) => ({ path: w.path, repo: w.repo }));
+    for (const member of members) {
+        await writeWorkspaceRepos(member.path, members);
+    }
     if (written.length < repos.length) {
         notes.push(`${repos.length - written.length} of ${repos.length} repositories were skipped. The workspace ` +
             "id is only byte-identical where it was actually written — re-run for the skipped paths " +
@@ -134,6 +145,7 @@ async function run(args, ctx) {
         commitSha: null,
         graphBuiltAt: null,
         irSchemaVersion: ctx.session.provider().baseStamp().irSchemaVersion,
+        commitSpread: ctx.session.provider().baseStamp().commitSpread,
         notes,
         data: { workspace, written, requested: repos.length },
     });

package/dist/tools/link-workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"link-workspace.js","sourceRoot":"","sources":["../../src/tools/link-workspace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"link-workspace.js","sourceRoot":"","sources":["../../src/tools/link-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,cAAc,EAAyC,MAAM,UAAU,CAAC;AA+BzG,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,qFAAqF;gBACrF,kFAAkF;SACrF;QACD,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,CAAC;YACX,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0CAA0C,EAAE;oBACjF,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,uEAAuE;qBACrF;iBACF;gBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;gBAC1B,oBAAoB,EAAE,KAAK;aAC5B;YACD,WAAW,EACT,4FAA4F;gBAC5F,2FAA2F;gBAC3F,2FAA2F;gBAC3F,wFAAwF;gBACxF,yCAAyC;SAC5C;KACF;IACD,QAAQ,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC;IAChC,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,cAAc,CACtB,qFAAqF;YACnF,mEAAmE,CACtE,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,cAAc,CAAC,SAAS,KAAK,qBAAqB,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,IAAI,GAAG,cAAc,CAAC,KAAgC,EAAE,MAAM,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,cAAc,CAAC,KAAgC,EAAE,MAAM,CAAC,CAAC;QACtE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,IAA6B,EAAE,GAAgB;IAChE,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAExC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,cAAc,CAAC,IAAI,KAAK,CAAC,IAAI,4BAA4B,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC;IAED,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YAC/D,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,qEAAqE,CAAC,CAAC;YAChG,SAAS;QACX,CAAC;QACD,GAAG,CAAC,QAAQ,CAAC,kCAAkC,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5E,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5E,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACrF,KAAK,CAAC,IAAI,CACR,GAAG,KAAK,CAAC,IAAI,kCAAkC,MAAM,CAAC,iBAAiB,WAAW,SAAS,IAAI,CAChG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,sEAAsE;IACtE,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACrE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,mBAAmB,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CACR,GAAG,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,4CAA4C;YAC7F,yFAAyF;YACzF,wBAAwB,CAC3B,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI,CACR,oFAAoF,SAAS,IAAI;QAC/F,uEAAuE,CAC1E,CAAC;IAEF,OAAO,MAAM,CAAoB;QAC/B,QAAQ,EACN,OAAO,CAAC,MAAM,KAAK,CAAC;YAClB,CAAC,CAAC,qEAAqE;YACvE,CAAC,CAAC,UAAU,OAAO,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,aAAa,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG;gBAC3F,iBAAiB,SAAS,IAAI;QACpC,KAAK,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;QAC9C,SAAS,EAAE,IAAI;QACf,mEAAmE;QACnE,qEAAqE;QACrE,0DAA0D;QAC1D,eAAe,EAAE,CAAC;QAClB,SAAS,EAAE,IAAI;QACf,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,eAAe;QACnE,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,YAAY;QAC7D,KAAK;QACL,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE;KACtD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAmB;IAC/C,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,eAAe;IACtB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,8CAA8C;IACrD,WAAW,EACT,0FAA0F;QAC1F,2FAA2F;QAC3F,8FAA8F;QAC9F,wFAAwF;QACxF,oFAAoF;QACpF,8BAA8B;IAChC,WAAW,EAAE,MAA4C;IACzD,GAAG;CACJ,CAAC"}

package/dist/tools/mark-incident.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `mark_incident` — "that was a bug, and I just fixed it."
+ *
+ * The mechanism that lets an incident corpus grow during ordinary work, and the
+ * only one with precision 1.0 by construction: a person is asserting it.
+ *
+ * ## Why this exists
+ *
+ * `similar_incidents` is built, tested and correct, and starved. Until now one
+ * thing in the whole system minted an `INCIDENT` — a commit body carrying
+ * `This reverts commit <sha>` — which produced **zero** incidents across three
+ * measured repositories and two in a real product repository. Widening the
+ * automatic detection helps (`incidents.ts` now reads manual reverts and
+ * `Fixes #123` too), but every automatic mechanism can only read what somebody
+ * already wrote down. Most bugs are fixed forward with a commit message that
+ * says what the code now does, not what it used to do wrong.
+ *
+ * The heuristic that would close that gap was built and measured and refused:
+ * `bench/incident-fix-forward.mjs` scored **25%** against a 90% threshold
+ * declared before it ran. So the remaining route is to ask, once, cheaply, at
+ * the moment the developer already knows the answer.
+ *
+ * ## Where the record lives, and why not in the graph
+ *
+ * `.descry/config.json`, beside `confirmedFacts` — DEC-223's storage decision
+ * for exactly this class of data. A store is derived data (DEC-017) and every
+ * derived table is dropped on a schema bump; a fact a person asserted, which
+ * exists nowhere else, must not be. The graph holds a *projection*
+ * (`createConfirmedIncidentSource`), re-derived by every `analyze`, and this
+ * tool writes both so the incident is visible in the same conversation that
+ * recorded it rather than after the next rebuild.
+ *
+ * ## Reliability
+ *
+ * DEC-223's rule, unchanged: an edge resting on testimony is capped at class B
+ * however much structure surrounds it. One unaudited assertion is one unaudited
+ * assertion. This tool asserts a defect existed; it asserts nothing about why,
+ * and nothing here may promote it.
+ *
+ * ## Class
+ *
+ * `action` — DEC-278's test is *"can this call's effect change a later finding
+ * without the developer having said so"*, and an `INCIDENT_CORRELATED` edge
+ * biases diff-scoping traversal toward the files it names on every later run.
+ * Gated by the same two-call `confirmToken` handshake `questions` uses.
+ *
+ * See `DEC-NEXT-incident-minting-beyond-explicit-reverts`.
+ */
+import type { ConfirmedIncident } from "@descryy/ir";
+import { type ToolDefinition } from "./kit.ts";
+export interface MarkIncidentData {
+    /** The record as written. Read it back to see exactly what was stored. */
+    readonly recorded: ConfirmedIncident;
+    /** The `INCIDENT` node id, so a caller can query it immediately. */
+    readonly incidentNodeId: string;
+    /** Where the durable record lives — a file a person can read and correct. */
+    readonly configPath: string;
+    /** How many confirmed incidents this repository now has on record. */
+    readonly totalConfirmed: number;
+    /**
+     * Paths named that the graph has no node for.
+     *
+     * The incident is still recorded and still correlated — a developer naming a
+     * file Descry cannot read is a gap in Descry, not a mistake by the developer.
+     */
+    readonly filesNotInGraph: readonly string[];
+}
+export declare const markIncidentTool: ToolDefinition;
+//# sourceMappingURL=mark-incident.d.ts.map

package/dist/tools/mark-incident.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mark-incident.d.ts","sourceRoot":"","sources":["../../src/tools/mark-incident.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AASH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAGlB,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AA0KD,eAAO,MAAM,gBAAgB,EAAE,cAkB9B,CAAC"}

package/dist/tools/mark-incident.js

@@ -0,0 +1,212 @@
+/**
+ * `mark_incident` — "that was a bug, and I just fixed it."
+ *
+ * The mechanism that lets an incident corpus grow during ordinary work, and the
+ * only one with precision 1.0 by construction: a person is asserting it.
+ *
+ * ## Why this exists
+ *
+ * `similar_incidents` is built, tested and correct, and starved. Until now one
+ * thing in the whole system minted an `INCIDENT` — a commit body carrying
+ * `This reverts commit <sha>` — which produced **zero** incidents across three
+ * measured repositories and two in a real product repository. Widening the
+ * automatic detection helps (`incidents.ts` now reads manual reverts and
+ * `Fixes #123` too), but every automatic mechanism can only read what somebody
+ * already wrote down. Most bugs are fixed forward with a commit message that
+ * says what the code now does, not what it used to do wrong.
+ *
+ * The heuristic that would close that gap was built and measured and refused:
+ * `bench/incident-fix-forward.mjs` scored **25%** against a 90% threshold
+ * declared before it ran. So the remaining route is to ask, once, cheaply, at
+ * the moment the developer already knows the answer.
+ *
+ * ## Where the record lives, and why not in the graph
+ *
+ * `.descry/config.json`, beside `confirmedFacts` — DEC-223's storage decision
+ * for exactly this class of data. A store is derived data (DEC-017) and every
+ * derived table is dropped on a schema bump; a fact a person asserted, which
+ * exists nowhere else, must not be. The graph holds a *projection*
+ * (`createConfirmedIncidentSource`), re-derived by every `analyze`, and this
+ * tool writes both so the incident is visible in the same conversation that
+ * recorded it rather than after the next rebuild.
+ *
+ * ## Reliability
+ *
+ * DEC-223's rule, unchanged: an edge resting on testimony is capped at class B
+ * however much structure surrounds it. One unaudited assertion is one unaudited
+ * assertion. This tool asserts a defect existed; it asserts nothing about why,
+ * and nothing here may promote it.
+ *
+ * ## Class
+ *
+ * `action` — DEC-278's test is *"can this call's effect change a later finding
+ * without the developer having said so"*, and an `INCIDENT_CORRELATED` edge
+ * biases diff-scoping traversal toward the files it names on every later run.
+ * Gated by the same two-call `confirmToken` handshake `questions` uses.
+ *
+ * See `DEC-NEXT-incident-minting-beyond-explicit-reverts`.
+ */
+import { buildGraph, confirmedIncidentId, createConfirmedIncidentSource, nodesInFiles, persistGraph, } from "@descryy/core";
+import { writeConfirmedIncident } from "../session.js";
+import { answer, optionalString, optionalStringArray, requiredString, ToolInputError, } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        summary: {
+            type: "string",
+            description: "What broke, in your own words — one sentence. This becomes the incident's name and is " +
+                "matched against future failures, so describe the symptom rather than the fix " +
+                "(\"invoice totals doubled for multi-currency orders\", not \"corrected the rate lookup\").",
+        },
+        files: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            description: "Repo-relative paths the defect lived in. At least one. These are what make the incident " +
+                "findable later and what biases future blast radii toward this area, so name where the " +
+                "bug was, not every file the fix happened to touch.",
+        },
+        errorText: {
+            type: "string",
+            description: "The error or exception text as you saw it, if there was one. Optional, and worth giving: " +
+                "matching a future failure against real error text is what this corpus is for, and a " +
+                "commit subject line is a thin substitute.",
+        },
+        fixedAtCommit: {
+            type: "string",
+            description: "The commit that fixed it, if it is already committed. Optional — omit it rather than " +
+                "guessing, since recording a commit that did not fix this claims something you did not.",
+        },
+        confirmedBy: {
+            type: "string",
+            description: "Free text — who is asserting this. Defaults to \"user\".",
+        },
+        confirmToken: {
+            type: "string",
+            description: "The token returned by a previous call. Recording an incident takes two calls: the first " +
+                "returns a token and writes nothing, the second redeems it. A token is single-use, " +
+                "expires, and is only valid for this tool.",
+        },
+    },
+    required: ["summary", "files"],
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const { session } = ctx;
+    const summary = requiredString(args, "summary");
+    const files = optionalStringArray(args, "files");
+    if (files === undefined || files.length === 0) {
+        throw new ToolInputError('"files" must name at least one repo-relative path — an incident naming no file has nothing ' +
+            "to attach it to, and would be invisible to every query that looks for one");
+    }
+    const errorText = optionalString(args, "errorText");
+    const fixedAtCommit = optionalString(args, "fixedAtCommit");
+    const confirmedBy = optionalString(args, "confirmedBy") ?? "user";
+    const root = await session.root();
+    const recorded = {
+        repo: session.config.repo,
+        summary,
+        files: [...new Set(files)].sort(),
+        ...(errorText === undefined ? {} : { errorText }),
+        ...(fixedAtCommit === undefined ? {} : { fixedAtCommit }),
+        confirmedBy,
+        confirmedAt: new Date().toISOString(),
+    };
+    const driver = session.store().driver;
+    // Measured **before** the projection runs. The projection mints a `FILE` node
+    // for every path the record names — the same thing the git source does for a
+    // reverted commit's files — so asking afterwards would always answer "all of
+    // them are in the graph" and the disclosure would be a tautology.
+    const { missing: filesNotInGraph } = nodesInFiles(driver, recorded.files);
+    ctx.progress(`Recording an incident in ${session.config.repo}`);
+    const written = await writeConfirmedIncident(session.repoPath, recorded);
+    // Projected into the store now, not at the next `analyze`, so the incident is
+    // visible in the conversation that recorded it — the same reason `questions`
+    // merges its just-written fact into the response it is about to return.
+    ctx.progress("Projecting it into the graph");
+    const batch = await createConfirmedIncidentSource({
+        repo: session.config.repo,
+        // Every record, not just this one: the projection is of the whole file, and
+        // a batch carrying only the newest would invalidate the rest of them.
+        incidents: [...(session.config.confirmedIncidents ?? []), recorded],
+    }).emit({ root });
+    const built = buildGraph([batch], { nodeExists: (id) => session.provider().node(id) !== undefined });
+    persistGraph(driver, [batch], built);
+    const stamp = session.provider().baseStamp();
+    const notes = [
+        "Recorded as testimony, not as a reading of the repository. An edge resting on it is capped at " +
+            "reliability class B (DEC-223) however much structure surrounds it — one unaudited assertion " +
+            "is one unaudited assertion.",
+        `The durable record is ${written.path}, which is a file you can read and correct. The graph ` +
+            "holds a projection of it, re-derived by every analyze, so a rebuild never loses it.",
+    ];
+    if (fixedAtCommit === undefined) {
+        notes.push("No fixing commit was named, so no FIX_PATTERN was minted and no FIXED_BY edge exists. " +
+            '"A defect existed" and "this commit fixed it" are separate claims and only the second ' +
+            "licenses that edge.");
+    }
+    if (filesNotInGraph.length > 0) {
+        notes.push(`${filesNotInGraph.length} of the named path(s) have no node in the graph ` +
+            `(${filesNotInGraph.slice(0, 5).join(", ")}). The incident is recorded and correlated to ` +
+            "them anyway — a developer naming a file Descry cannot read is a gap in Descry, not a " +
+            "mistake to discard. Run analyze if the graph predates them.");
+    }
+    return answer({
+        headline: `Recorded an incident in ${session.config.repo}, correlated to ${recorded.files.length} file(s). ` +
+            `${written.total} confirmed incident(s) now on record.`,
+        // A name-level fact: this defect existed and touched these paths. It makes
+        // no claim about program shape.
+        nameLevel: true,
+        // R0, and honestly so. Testimony is not a point on the R0-R4 ladder at all —
+        // that ladder measures how much tooling ran — so the honest floor is the
+        // bottom of it, with the real ceiling expressed by `humanAsserted` where a
+        // finding is actually classified.
+        resolutionFloor: 0,
+        commitSha: stamp.commitSha,
+        graphBuiltAt: stamp.graphBuiltAt,
+        irSchemaVersion: stamp.irSchemaVersion,
+        commitSpread: stamp.commitSpread,
+        notes,
+        data: {
+            recorded,
+            incidentNodeId: confirmedIncidentId({ repo: session.config.repo, ...(root.workspace === undefined ? {} : { workspace: root.workspace }) }, recorded),
+            configPath: written.path,
+            totalConfirmed: written.total,
+            filesNotInGraph,
+        },
+    });
+}
+/**
+ * Always returns a sentence: unlike `questions`, whose unconfirmed shape is a
+ * genuine read of the open-question queue, there is no argument to this tool
+ * that makes it not write.
+ */
+function describeAction(args) {
+    const summary = args["summary"];
+    const files = args["files"];
+    if (typeof summary !== "string" || !Array.isArray(files) || files.length === 0)
+        return undefined;
+    return (`record a confirmed incident — "${summary}" — correlated to ${files.length} file(s) ` +
+        `(${files.slice(0, 3).join(", ")}${files.length > 3 ? ", …" : ""}). It is written to ` +
+        ".descry/config.json and projected into the graph, where it will bias future blast radii " +
+        "toward those files and can be matched against future failures. Capped at reliability class B.");
+}
+export const markIncidentTool = {
+    name: "mark_incident",
+    class: "action",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Record a bug you just fixed, so a future failure can match against it",
+    description: "Record that a defect existed in this repository and which files it lived in, so " +
+        "\"similar_incidents\" can match a future failure against it. This is the mechanism that lets " +
+        "an incident corpus grow during ordinary work: git history only yields an incident when " +
+        "somebody wrote a revert or a \"Fixes #123\", and most bugs are fixed forward with a message " +
+        "that says what the code now does rather than what it did wrong. Recorded as testimony — an " +
+        "edge resting on it is capped at reliability class B regardless of anything else about it " +
+        "(DEC-223). Takes a two-call confirmation: the first call performs nothing and returns a " +
+        "token; call again with \"confirmToken\" to actually record it.",
+    inputSchema: SCHEMA,
+    run,
+    describeAction,
+};
+//# sourceMappingURL=mark-incident.js.map

package/dist/tools/mark-incident.js.map

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

package/dist/tools/observe-runtime.d.ts

@@ -0,0 +1,292 @@
+/**
+ * `observe_runtime` — boot or attach to a real application, watch it, and write
+ * what was witnessed into the graph as R4 facts.
+ *
+ * **The second tool that writes, and the first that writes something no
+ * re-index can reproduce.** `analyze` re-derives the graph from source already
+ * on disk, so nothing it writes is a new claim about the world. This one runs
+ * a real process and records what it saw happen, which is the one accuracy
+ * source architecture §11B.3 calls *"the core technical moat"* and the one a
+ * purely static tool is structurally unable to reach: *"a purely static
+ * code-graph tool is capped at R3 permanently. It has no runtime."*
+ *
+ * ## What this composes, and what it invents
+ *
+ * It invents no mechanism. Every stage already existed, gate-verified, in
+ * `descry-runtime`, and every one of them was dormant — the whole point of
+ * `DEC-NEXT-mcp-runtime-dependency-boundary-for-r4-evidence`, which measured
+ * that `applyRuntimeObservations` had **zero production callers anywhere**,
+ * not in `descry-desktop` and not in `descry-runtime`'s own pipeline. Four
+ * shipped components in a row, and this tool is the wire between them:
+ *
+ * 1. `runInstrumentedExecution` (`@descryy/runtime-orchestrator`) spawns or
+ *    attaches the declared services, starts the adapter's collectors, drains
+ *    them for a stated window, and writes every item through `EvidenceStore`.
+ * 2. `correlateExecution` (`@descryy/runtime-evidence-correlation`) resolves
+ *    each evidence item to the graph node it is *about* — the resolve-then-
+ *    attribute pass. This answers identity, not edges.
+ * 3. `confirmObservedFrontendCaller` (`@descryy/runtime-graph-correlator`)
+ *    turns a captured call-site stack plus a resolved endpoint into a
+ *    `RuntimeEdgeObservation`, and
+ * 4. calls `applyRuntimeObservations` (`@descryy/core`) with it, which
+ *    promotes, mints or contradicts the edge and writes the EARNED ledger.
+ *
+ * ## Why stage 3 exists rather than deriving edges from stage 2 directly
+ *
+ * `uat-phase-1-bug-fixes.md` Phase 2 describes step 2 as producing
+ * `RuntimeEdgeObservation[]`. It does not, and the difference is load-bearing
+ * rather than pedantic: `correlateExecution` returns
+ * `CorrelationAttribution`s — *(evidenceId, graphNodeId)* pairs saying which
+ * single node an observation is about. An edge needs **two** endpoints and a
+ * witnessed relationship between them, and manufacturing one by pairing up
+ * attributions that happen to co-occur in the same run would mint edges from
+ * temporal coincidence. That is precisely the wrong-direction failure rule 2
+ * exists to prevent, arriving through the one mechanism built to make the
+ * graph *more* trustworthy.
+ *
+ * So the observation comes from the one shipped producer that can honestly
+ * make one: a captured stack naming the caller, against an endpoint the same
+ * observation named. Both endpoints come from the observation itself. Every
+ * other correlated item is reported in the counts and produces no edge, which
+ * is a disclosed gap rather than a silent one.
+ *
+ * ## What this closure can actually witness today — measured, not assumed
+ *
+ * The wire is complete, and what it can carry changed when the runtime packages
+ * were published at 0.1.0 and pinned here — so this paragraph is the record of
+ * a limit that was real and is now lifted, kept rather than deleted because the
+ * shape of it recurs.
+ *
+ * **It used to be that no producer of the required pair — HTTP evidence
+ * carrying a call-site stack — was in this server's closure.** The browser
+ * network collector never has been. The outbound-fetch instrumentation in
+ * `@descryy/runtime-external-service-observation` existed, was proven in
+ * `descry-runtime`, and was not installed here at all. So a run resolved both
+ * kinds of node and wrote no edge, and `STANDING_NOTES` said so on every call
+ * because "no edge was written" and "nothing here could have written one" are
+ * different statements.
+ *
+ * **That second producer is now in the closure**, transitively through
+ * `@descryy/runtime-orchestrator`, which applies the adapter's
+ * `outboundHttpLaunch()` between the interpreter and the script so the client
+ * is patched before any application code can capture an unpatched one. Measured
+ * end to end in `observe-runtime-outbound.conformance.test.ts`: two real
+ * processes, 17 `EXTERNAL_REQUEST` items alongside 18 `BACKEND_LOG`, one
+ * `USES_API` edge minted at R4, and the first `strongly supported` reply this
+ * server has produced.
+ *
+ * **Two limits remain, and they are stated rather than inferred from a zero.**
+ * An *attached* service is not launched by Descry, so the instrumentation
+ * cannot be installed into it and its outbound calls carry no stack. And
+ * browser-side traffic still needs `@descryy/runtime-browser`, which is not
+ * here. Both are in `STANDING_NOTES`.
+ *
+ * The rule that outlives all of it: a disclosure about the closure is a fact
+ * about *this build*, not about what `descry-runtime` can do. The two came
+ * apart once already, when the cross-boundary lane landed and this file still
+ * claimed the capability was absent. Re-check it against the installed tree
+ * when the pins move, not against the source repository.
+ * Descry.
+ *
+ * ## Why no denial is ever emitted
+ *
+ * `applyRuntimeObservations` accepts `held: false`. Nothing here ever sends
+ * one, and `confirmObservedFrontendCaller`'s own header explains why: a run
+ * establishes that a call *happened*; it cannot establish that one did not,
+ * because a run exercises the paths it happens to take. Demoting a correct
+ * edge on the strength of a route this run did not visit would be worse than
+ * never running.
+ *
+ * ## Class and tier
+ *
+ * `action` — DEC-278's own test is *"can this call's effect change a later
+ * finding without the developer having said so"*, and this one spawns
+ * processes and writes R4 edges that cap every later reliability class
+ * differently. It is gated by the same two-call `confirmToken` handshake
+ * `questions` uses, and additionally by the environment profile's declared
+ * `safetyLevel` (DEC-270): booting a service is a **write** against the
+ * target, so a `readOnly` profile refuses. An all-attach run is genuinely
+ * read-only — `ServiceConfiguration.attach`'s own contract is that Descry
+ * never executes code in, or applies limits to, a process it did not spawn —
+ * so it is allowed under `readOnly`, and that distinction is stated in the
+ * disclosures rather than inferred silently.
+ *
+ * `evidence` — it reports what was witnessed and what was written. It draws no
+ * conclusion about the user's code; nothing here reads or writes a finding, a
+ * hypothesis or a category (RT-027).
+ *
+ * ## No new query tools
+ *
+ * None are needed and none are added. `impact`, `propagation` and the rest
+ * already read the `resolution` field, so an edge this tool promotes to R4
+ * becomes visible through every one of them on the next call, with no change
+ * to any of them.
+ */
+import type { SignalTypeCount } from "@descryy/ir";
+import type { Evidence, ServiceConfiguration } from "@descryy/runtime-contracts";
+import type { RunOptions } from "@descryy/runtime-controller";
+import type { EnvironmentProfile } from "@descryy/runtime-environment-profile";
+import { type ToolDefinition } from "./kit.ts";
+import { type RuntimeAdapterSpec } from "../runtime-registry.ts";
+/**
+ * One service's readiness declaration, derived from `RunOptions` rather than
+ * imported by name.
+ *
+ * `@descryy/runtime-controller` declares `ServiceReadinessSpec` and does not
+ * export it from its index — a real gap in that package, but fixing it there
+ * would mean a republish and a version bump across everything that pins the
+ * controller, to obtain a type this file can derive exactly. Deriving is also
+ * the more durable of the two: this cannot drift from what `run()` actually
+ * accepts, because it *is* what `run()` accepts.
+ */
+type ServiceReadinessSpec = RunOptions["readiness"][string];
+/** Where evidence lands when the call does not say. Beside the graph, not inside it. */
+export declare const DEFAULT_EVIDENCE_RELATIVE_PATH: string;
+/**
+ * What one declared service did, reported from the one source that survives the
+ * call: `Execution.processes`.
+ *
+ * **Deliberately not the controller's `ServiceStartResult`**, which carries a
+ * per-service `stage`/`readiness.reason` and would be the better answer.
+ * `runInstrumentedExecution` does not return it — `serviceStartResults` is a
+ * property of `ExecutionController`, which that function creates, uses and
+ * drops, so it is genuinely unavailable to a caller rather than merely
+ * unplumbed here. What is knowable is reported and nothing is invented to fill
+ * the gap: a service with no `ProcessHandle` did not start, and the
+ * execution-level `executionState` (`FAILED_START` in particular) is what says
+ * a readiness check is why.
+ *
+ * A `null` `exitCode` with a `null` `signal` on a process that has not exited
+ * is the healthy case, not a missing value — POSIX only sets an exit code on a
+ * normal `exit()`, so `signal` is what distinguishes a crash from a clean exit.
+ */
+export interface ObservedService {
+    readonly service: string;
+    /** False when no process handle exists for it at all — it never started. */
+    readonly started: boolean;
+    /** True when this service was attached to rather than spawned. Governs the safety gate — see the header. */
+    readonly attached: boolean;
+    /** The port it actually bound, when it listens on one. Null for a non-network process or before the port is known. */
+    readonly port: number | null;
+    /** Null while still running. Set once it exited and was reaped. */
+    readonly exitedAt: string | null;
+    readonly exitCode: number | null;
+    /** Non-null means killed by this signal, whatever `exitCode` says. */
+    readonly signal: string | null;
+}
+/**
+ * What the correlation pass resolved, by family. Counts rather than rows: a
+ * long run produces thousands of evidence items and this reply is read by an
+ * agent, not archived. The rows themselves are in the evidence store, keyed by
+ * `executionId`, which is returned so they can be found.
+ */
+export interface CorrelationSummary {
+    readonly considered: number;
+    readonly skipped: number;
+    readonly attributed: number;
+    readonly refused: number;
+    /** Service names carrying symbol evidence no scope named a repository for. Named, never guessed at. */
+    readonly unscopedServices: readonly string[];
+    /** Non-empty means the correlation machinery itself broke, not that it looked and found nothing. */
+    readonly harnessErrors: readonly string[];
+}
+/**
+ * The R4 write, reported in `applyRuntimeObservations`'s own six-way
+ * vocabulary so a reader can account for every observation without inspecting
+ * the store.
+ */
+export interface RuntimeWriteSummary {
+    /** Edges the graph already held below R4, now witnessed and raised to R4. */
+    readonly promoted: readonly string[];
+    /** Edges no static producer found, minted at R4 — §11B.3's "recall gap closed". */
+    readonly created: readonly string[];
+    /** Already at R4 and observed again. Reported, never silently dropped. */
+    readonly confirmed: readonly string[];
+    /** Observations the graph declined to act on, with the resolver's own reason. */
+    readonly refused: readonly string[];
+    /**
+     * Always empty today, and present so that stays visible rather than
+     * unstated. This tool emits no denial — see the header.
+     */
+    readonly contradictions: readonly string[];
+    /** A denial aimed at an edge already at R4. Out of scope by construction; reported, not laundered. */
+    readonly staleR4: readonly string[];
+}
+export interface ObserveRuntimeData {
+    /** Null when the run never started — see `services` and the disclosures for why. */
+    readonly executionId: string | null;
+    /** The controller's own terminal state for this execution. */
+    readonly executionState: string | null;
+    /** `RuntimeAdapter.language`, passed through verbatim. Nothing here branches on it (rule 1). */
+    readonly adapterLanguage: string | null;
+    readonly evidencePath: string;
+    readonly services: readonly ObservedService[];
+    /** Every evidence item this run wrote, by `eventType`. */
+    readonly evidenceByType: Readonly<Record<string, number>>;
+    readonly correlation: CorrelationSummary | null;
+    readonly wrote: RuntimeWriteSummary;
+}
+/** One service's declaration, resolved against the repository root. */
+interface DeclaredService {
+    readonly name: string;
+    readonly configuration: ServiceConfiguration;
+    readonly readiness: ServiceReadinessSpec;
+    readonly attached: boolean;
+}
+/**
+ * Every argument this tool takes, read and validated in one place.
+ *
+ * Extracted from `run` so that `describeAction` can call it too. That is the
+ * whole point of the extraction: an `action` tool's first call is the one a
+ * caller makes *before* it has a token, and therefore the only cheap place to
+ * learn its arguments are wrong. Minting a token, and a paragraph describing
+ * an action, for a declaration that cannot possibly run asks a developer to
+ * confirm something that was never going to happen — and delivers the real
+ * refusal on the second call, after the confirmation.
+ *
+ * Nothing here touches the filesystem, spawns anything or reads the graph: it
+ * is argument reading and nothing else, which is what makes it safe to run at
+ * mint time, outside the call budget.
+ *
+ * Ruled in `documents/decisions-inbox/DEC-387.md`.
+ *
+ * Exported for its own test: several of the argument rules are conditional and
+ * cheaper to assert directly than through a full run.
+ */
+export declare function readArguments(args: Record<string, unknown>, repoPath: string): {
+    readonly profile: EnvironmentProfile;
+    readonly adapterSpec: RuntimeAdapterSpec;
+    readonly declared: readonly DeclaredService[];
+    readonly observeForMs: number;
+    readonly timeoutMs: number;
+    readonly fidelityRaw: number;
+    readonly environmentTier: string;
+    readonly evidencePath: string;
+};
+/**
+ * The two fields the channel mapping actually reads.
+ *
+ * Narrower than `Evidence` on purpose: `observe_tests` counts its channels
+ * before its evidence has been through `EvidenceStore.write()`, so its items
+ * have no `evidenceId` or `executionId` yet. Widening the parameter is how
+ * both tools share one implementation of the count; the alternative was a cast
+ * at one call site, which buys nothing and hides that the extra fields were
+ * never used.
+ */
+type WitnessableEvidence = Pick<Evidence, "eventType" | "source">;
+/**
+ * `E` for this run — how many of the six channels it actually saw.
+ *
+ * The count itself is `@descryy/ir`'s `independentSignalTypes`, deliberately:
+ * the clamp to six and the drop of `null` signals are that function's rules,
+ * and a second implementation of them here is a second place for the
+ * vocabulary to drift. This function's only job is the translation above.
+ *
+ * Exported for its own test — the mapping decides whether a witnessed answer
+ * reads `strongly supported` or `unconfirmed`, which is too load-bearing to be
+ * asserted only through a category two layers downstream.
+ */
+export declare function witnessedSignalTypes(evidence: readonly WitnessableEvidence[]): SignalTypeCount;
+export declare const observeRuntimeTool: ToolDefinition;
+export {};
+//# sourceMappingURL=observe-runtime.d.ts.map

package/dist/tools/observe-runtime.d.ts.map

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