@descryy/mcp 0.11.5 → 0.11.6

package/dist/render.js

@@ -0,0 +1,968 @@
+/**
+ * The one way an engine answer becomes an MCP tool result.
+ *
+ * ## Why this file exists rather than each tool formatting its own reply
+ *
+ * `QueryResult` carries three things a caller would rather not think about: a
+ * staleness stamp (§27.3), a `truncated` flag, and `notes` — the plain-words
+ * disclosures that populate the five result states' `refused`/`empty`/`failed`/
+ * `timed_out` cases. The engine computes all three correctly today. Every one of
+ * them is one careless `return result.data` away from never reaching a user.
+ *
+ * So the tool handler's return type is `QueryResult`, not content. A handler
+ * *cannot* build a reply; it can only produce an answer, and this module is the
+ * only thing that turns an answer into frames. Rule 7 — honest degradation, no
+ * silent doing-less — becomes a property of the type system rather than of
+ * whoever writes the next tool.
+ *
+ * ## `ai-tool-contract.md` §2 — the frozen envelope
+ *
+ * This module used to ship a two-value `status: "ok" | "not_analysable"`. The
+ * contract froze five: `ok` / `empty` / `refused` / `failed` / `timed_out`
+ * (§1), plus `class`, `toolVersion`, `budget` and a structured `truncated`
+ * object (§2). `AnswerStatus`/`renderAnswer`'s old two-state shape is gone
+ * rather than kept alongside the new one — two envelope shapes on the wire is
+ * the thing DEC-277's "one process mints" reasoning exists to avoid one layer
+ * up, applied here to a type rather than a decision number.
+ *
+ * ## Four invariants, asserted rather than documented (§2.1)
+ *
+ * `render.ts` already enforced the first two; the other two are new.
+ *
+ * 1. `truncated != null` with empty `disclosures` → throw.
+ * 2. `state` in `{refused, failed, timed_out}` with empty `disclosures` → throw.
+ * 3. `state == "refused"` with no verbatim reason in `disclosures` → throw (§4).
+ * 4. `class == "action"` returning anything other than a handshake envelope on
+ *    the first call → throw (§7) — enforced in `action-handshake.ts` and
+ *    `server.ts`, not here: this module never sees a mint, only a redeemed run.
+ *
+ * ## A fifth invariant, B6: a truncated answer must carry real counts
+ *
+ * `result.truncated === true` with no `answer.truncatedDetail` used to fall
+ * back to a sentinel, `{shown: -1, total: -1}` — chosen to be "unmistakably
+ * fake," except that it is a number, so it passes any presence check and then
+ * poisons whatever arithmetic reads `total - shown`. A field that lies is
+ * worse than a field that is absent, which is the same argument the five
+ * result states rest on. So the sentinel is gone: a tool that sets
+ * `result.truncated` without a `truncatedDetail` is a programming error,
+ * thrown in every environment except production, where the envelope instead
+ * reports `truncated: null` plus a disclosure naming the gap — degraded
+ * honestly rather than dishonestly precise. See `capped()` in `./capped.ts`
+ * for how a tool is meant to avoid ever hitting this.
+ */
+import { randomUUID } from "node:crypto";
+import { aliasDisclosure } from "./tools/aliases.js";
+import { RELIABILITY_CLASSES, REPORT_CATEGORIES, RESULT_STATES, TOOL_CLASSES, existenceCategory as deriveExistenceCategory, reliabilityCap, reliabilityDisclosure, reportCategory as deriveReportCategory, } from "@descryy/ir";
+import { sampleChangedFiles } from "@descryy/core";
+/**
+ * MK-5 — which of the sixteen tools states a conclusion about the user's code
+ * versus which reports a fact about the graph.
+ *
+ * Lives here rather than in `@descryy/ir`: `tool-surface.ts`'s own header
+ * scopes that file to exactly `ResultState` and `ToolClass` ("and nothing
+ * else"), because those two cross into the pipeline and the desktop surface.
+ * This distinction is agent-mode-only (`plugin-and-mcp-surface.md` §3 PL-1),
+ * so a third shared union there would be scope creep the file's own doc
+ * disclaims. `kit.ts` imports it from here rather than the reverse, because
+ * `kit.ts` already depends on this module for `ToolAnswer`/`TruncationDetail`
+ * — defining it in `kit.ts` instead would make this module import back from
+ * `kit.ts` and cycle.
+ *
+ * - `conclusion` — the output is a statement about the user's code
+ *   (`validate`, `contracts`, `cross_pr`). Never raw candidates: an
+ *   already-adjudicated result carrying the category and the disclosure
+ *   sentence as one payload.
+ * - `evidence` — the output is a fact the graph computed, already carrying
+ *   its own resolution and qualification. The other thirteen.
+ */
+export const TOOL_TIERS = ["conclusion", "evidence"];
+const PROVENANCE = {
+    surface: "mcp",
+    adjudicatedBy: "descry",
+    presentedBy: "host-agent",
+    governancePipeline: false,
+};
+/**
+ * The ceiling on one rendered tool result, serialized — `content` frame and
+ * `structuredContent` envelope together, which is what a host actually
+ * receives and counts.
+ *
+ * A starting value, not a measurement, in this repo's usual sense: the one
+ * hard number behind it is a real failure, `get_git_diff` on an ordinary
+ * 48-file branch diff returning 84,516 characters and being rejected outright
+ * by the host before the caller saw any of it. 60,000 sits well under the
+ * smallest size observed to fail, with room for the narrated frame that
+ * repeats the disclosures alongside the envelope.
+ *
+ * Shared rather than per-tool on purpose: `get_git_diff` is the tool that hit
+ * this, twice, but nothing about the failure was specific to diffs. Any tool
+ * adopts the ceiling by implementing `ToolAnswer.fitToBudget`.
+ */
+export const MAX_REPLY_BYTES = 60_000;
+// ---------------------------------------------------------------------------
+// The wire schema for everything above
+// ---------------------------------------------------------------------------
+/** `T | null`, in the JSON Schema this server's declared subset uses. */
+function nullable(schema) {
+    return { anyOf: [schema, { type: "null" }] };
+}
+/**
+ * The envelope, declared for a host to validate against — MCP's `outputSchema`.
+ *
+ * ## Why this exists at all
+ *
+ * Every reply from this server carries `structuredContent`, and until this was
+ * added a host had no way to check what it received. `tools/list` already ships
+ * `class`, `tier` and `toolVersion` on the same reasoning — a fact about the
+ * reply that an external client cannot otherwise read — and this is the
+ * standard-shaped member of that group rather than a fourth non-standard field.
+ *
+ * ## `data` is deliberately open, and that is a disclosed gap
+ *
+ * The envelope's thirteen fields are uniform across all thirty-three tools, so they
+ * are described exactly. `data` is not: its shape is `ImpactData`, `ScopeData`
+ * and thirty-one others, and nothing today derives a JSON Schema from those
+ * TypeScript types. Hand-writing thirty-three schemas would put a second description
+ * of each shape in a second place with nothing checking the two agree — the
+ * drift this repo has already paid for once with the tool count in prose, and
+ * a schema that is confidently wrong about `data` is worse for a validating
+ * host than one that declines to describe it.
+ *
+ * So `data` is `{}` — "anything" — and this paragraph is the disclosure rather
+ * than a silent omission (rule 7). Tightening it is real work with a real
+ * prerequisite: a generator from the handler types, or the schemas checked
+ * against recorded replies. Until then the promise made here is exactly the
+ * promise kept.
+ *
+ * ## The enums are read, not restated
+ *
+ * `state`, `class`, `reportCategory` and `reliabilityCap` build their `enum`
+ * from the exported vocabulary arrays. A restated list is a second source of
+ * truth that goes stale in silence; spread from the array, adding a report
+ * category and forgetting the schema is a red test instead.
+ */
+export const ANSWER_ENVELOPE_SCHEMA = {
+    type: "object",
+    title: "Descry answer envelope",
+    description: "The uniform reply shape for every Descry tool. `state` distinguishes " +
+        "'looked and found nothing' (empty) from 'could not look' (refused); read " +
+        "`disclosures` before summarising the answer.",
+    properties: {
+        tool: { type: "string", description: "The tool that produced this reply." },
+        toolVersion: {
+            type: "string",
+            description: "Bumped on any behaviour change; recorded with the run.",
+        },
+        callId: {
+            type: "string",
+            description: "This call's own id in this session's recorded tool calls. Cite it in verify_claim's " +
+                "\"callId\" to check a claim against this exact call's real result.",
+        },
+        state: {
+            type: "string",
+            enum: [...RESULT_STATES],
+            description: "ok = found something; empty = looked completely and found nothing (a " +
+                "fact about your code); refused = could not look (a fact about Descry, " +
+                "never about your code); failed = something broke; timed_out = ran out " +
+                "of budget, partial answer.",
+        },
+        class: {
+            type: "string",
+            enum: [...TOOL_CLASSES],
+            description: "Retry semantics: read, stateful-read, or action.",
+        },
+        headline: { type: "string", description: "One-sentence plain-English answer." },
+        data: {
+            description: "The tool's own payload, or null on refused/failed/timed_out. Shape is " +
+                "per-tool and is not described here — see this schema's own " +
+                "documentation for why, and the tool description for the fields.",
+        },
+        graph: {
+            type: "object",
+            description: "What the answer rests on.",
+            properties: {
+                commitSha: nullable({ type: "string" }),
+                builtAt: nullable({ type: "string" }),
+                irSchemaVersion: { type: "integer" },
+                resolutionFloor: {
+                    ...nullable({ type: "integer", minimum: 0, maximum: 4 }),
+                    description: "R0 syntax only; R1 imports resolved; R2 references resolved; R3 " +
+                        "type checker; R4 observed at runtime. Null when the graph was not " +
+                        "consulted at all.",
+                },
+                reliabilityCap: {
+                    type: "string",
+                    enum: [...RELIABILITY_CLASSES],
+                    description: "C = unconfirmed behavioural prediction, must not be relayed as " +
+                        "fact; B = structural or reference evidence; A = as strong as this " +
+                        "graph makes it.",
+                },
+                freshness: nullable({
+                    type: "object",
+                    description: "Whether this graph still matches the repository on disk. Null only " +
+                        "when commitSha is null (nothing analysed yet, so nothing to be " +
+                        "fresh or stale relative to).",
+                    properties: {
+                        status: {
+                            type: "string",
+                            enum: ["current", "behind", "unknown"],
+                            description: "current = HEAD is the build commit and no indexed file is " +
+                                "uncommitted; behind = HEAD moved past the build, or an indexed " +
+                                "file has an uncommitted edit; unknown = not a git repository, " +
+                                "or git unavailable here — never reported as current.",
+                        },
+                        commitsSince: nullable({
+                            type: "integer",
+                            description: "Commits made after the build. Null when status isn't behind, " +
+                                "or when behind but the exact count could not be determined " +
+                                "(history rewritten since the build) — never a substitute for 0.",
+                        }),
+                        changedIndexedFiles: nullable({
+                            type: "integer",
+                            description: "How many indexed files differ from the build. Up to 5 of them " +
+                                "are named in disclosures. Null when status isn't behind.",
+                        }),
+                    },
+                    required: ["status", "commitsSince", "changedIndexedFiles"],
+                }),
+            },
+            required: ["commitSha", "builtAt", "irSchemaVersion", "resolutionFloor", "reliabilityCap", "freshness"],
+        },
+        truncated: nullable({
+            type: "object",
+            properties: {
+                shown: { type: "integer" },
+                total: { type: "integer", description: "The count before the cap." },
+                more: nullable({ type: "string" }),
+            },
+            required: ["shown", "total", "more"],
+        }),
+        refusals: nullable({
+            type: "object",
+            properties: {
+                count: { type: "integer" },
+                exemplar: { type: "string" },
+                handle: { type: "string", description: "Pass to refusal_fetch for the full list." },
+            },
+            required: ["count", "exemplar", "handle"],
+        }),
+        budget: {
+            type: "object",
+            properties: {
+                elapsedMs: { type: "integer" },
+                limitMs: { type: "integer" },
+            },
+            required: ["elapsedMs", "limitMs"],
+        },
+        disclosures: {
+            type: "array",
+            items: { type: "string" },
+            description: "What this answer does not cover. Never empty when the answer is " +
+                "degraded, truncated, refused, failed or timed out.",
+        },
+        configStale: {
+            type: "boolean",
+            description: "True when the running server's configuration no longer matches " +
+                ".descry/config.json on disk, so this reply (including graph and " +
+                "reportCategory) reflects the stale configuration loaded at startup. " +
+                "Restart the server to pick up the on-disk change; see disclosures " +
+                "for which fields changed.",
+        },
+        reportCategory: {
+            ...nullable({ type: "string", enum: [...REPORT_CATEGORIES] }),
+            description: "How strongly the CAUSE may be stated, capped by how well the code " +
+                "resolved. Null for conclusion-tier tools, and for replies that make no " +
+                "claim at all. 'confirmed' is unreachable from this surface by construction.",
+        },
+        existenceCategory: {
+            ...nullable({ type: "string", enum: [...REPORT_CATEGORIES] }),
+            description: "How strongly the evidence says the failure is REAL, read from what was " +
+                "observed and never capped by how well the code resolved. Read it beside " +
+                "reportCategory, not instead of it: a reply can be 'strongly supported' " +
+                "here and 'unconfirmed' there, which means the failure was witnessed and " +
+                "its cause was not established. Null wherever no evidence reading was " +
+                "taken — conclusion-tier tools, faults, and refusals.",
+        },
+        provenance: {
+            type: "object",
+            description: "Constant for this server. governancePipeline is always false here.",
+            properties: {
+                surface: { type: "string", enum: ["mcp"] },
+                adjudicatedBy: { type: "string", enum: ["descry"] },
+                presentedBy: { type: "string", enum: ["host-agent"] },
+                governancePipeline: { type: "boolean", enum: [false] },
+            },
+            required: ["surface", "adjudicatedBy", "presentedBy", "governancePipeline"],
+        },
+    },
+    // Every field is emitted on every path, including the ones that are always
+    // null on a fault — `renderFailed` and `renderTimedOut` build the whole
+    // envelope. So "required" here is the literal truth rather than a minimum.
+    required: [
+        "tool",
+        "toolVersion",
+        "callId",
+        "state",
+        "class",
+        "headline",
+        "data",
+        "graph",
+        "truncated",
+        "refusals",
+        "budget",
+        "disclosures",
+        "configStale",
+        "reportCategory",
+        "existenceCategory",
+        "provenance",
+    ],
+};
+/**
+ * The other shape a `tools/call` can return — `renderToolError`'s, now
+ * narrowed to the two cases where no tool was ever resolved (`name` not a
+ * string, or a name the registry does not have): there is no `ToolDefinition`
+ * to draw a real envelope from. A bad argument against a *resolved* tool goes
+ * through `renderRefusedInput` instead and is a real `state: "refused"`
+ * envelope — see that function's doc.
+ *
+ * Declared rather than quietly excluded. A schema that admitted only the
+ * envelope would be one the server itself violates on this narrower path.
+ * Declaring a union that is true beats declaring a single shape that is tidy.
+ */
+export const TOOL_ERROR_SCHEMA = {
+    type: "object",
+    title: "Tool argument error",
+    description: "Returned with isError when the call itself was malformed — fix the " +
+        "arguments and retry. Not a statement about the code either way.",
+    properties: {
+        tool: { type: "string" },
+        status: { type: "string", enum: ["error"] },
+        message: { type: "string" },
+    },
+    required: ["tool", "status", "message"],
+};
+/**
+ * What every tool declares as its `outputSchema`: the envelope or the argument
+ * error, discriminated by their required fields.
+ *
+ * One shared constant rather than a per-tool object because the shape genuinely
+ * is shared — the only per-tool part is `data`, which is open. When `data`
+ * becomes describable this becomes a function of the tool.
+ */
+export const TOOL_OUTPUT_SCHEMA = {
+    type: "object",
+    anyOf: [ANSWER_ENVELOPE_SCHEMA, TOOL_ERROR_SCHEMA],
+};
+export class DisclosureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DisclosureError";
+    }
+}
+/** Rule 7's label for a redemption that could not honour what the caller asked for. Names the
+ *  arguments rather than counting them — "1 argument was discarded" tells a caller something went
+ *  wrong without telling them what to fix — and names the recovery, which is the same one the
+ *  `confirmToken` descriptions prescribe. See `action-handshake.ts`'s header. */
+function discardedArgsNote(discarded) {
+    const names = discarded.map((key) => `"${key}"`).join(", ");
+    return (`This call supplied ${names} alongside a confirmToken, but a token runs the arguments frozen ` +
+        `when it was minted — the ones described for confirmation — so ${discarded.length === 1 ? "that value was" : "those values were"} discarded rather than used. ` +
+        "Call again without confirmToken to have the new arguments described, then confirm that token.");
+}
+/**
+ * MK-8's derivation, shared by every envelope-producing function below so the
+ * rule lives in one place rather than four.
+ */
+function deriveEnvelopeCategory(tier, state, resolutionFloor, nameLevel, witnessed) {
+    if (tier === "conclusion")
+        return null;
+    if (state === "failed" || state === "timed_out")
+        return null;
+    if (state === "refused")
+        return "not analysable";
+    return deriveReportCategory({
+        // G3's precondition, answered by the tool rather than assumed: a tool that
+        // ran nothing declares nothing here and short-circuits to `unconfirmed`,
+        // exactly as before. A tool that watched a real application declares what
+        // it watched.
+        hasRuntimeEvidence: witnessed !== undefined,
+        // Pinned false, and deliberately not something a tool may declare. `M` is
+        // G4's one route to `confirmed`, and DEC-334 reserves that category for a
+        // result that passed the full governance pipeline — which does not run in
+        // this surface. Accepting `M` here would let a tool mint the one label the
+        // ruling holds back, so the field is not offered rather than offered and
+        // then clamped: a clamp is a silent downgrade, and rule 7 forbids those.
+        directMechanismEvidence: false,
+        independentSignalTypes: witnessed?.independentSignalTypes ?? 0,
+        // `renderAnswer`'s own `state`/`disclosures` invariants guarantee a real
+        // graph was consulted whenever state is ok/empty, so this is never the
+        // null-graph sentinel — cast is safe, not asserted blind.
+        resolution: (resolutionFloor ?? 0),
+        nameLevel,
+        humanAsserted: false,
+    }).category;
+}
+/**
+ * The existence half — `documents/plans/gate_loosening.md` §3.3.
+ *
+ * Reads the same witnessed evidence the sibling above does and takes no resolution argument at
+ * all, which is the whole point: the structural floor is evidence about the cause and this is a
+ * statement about the failure. The two are computed apart so that neither can silently acquire
+ * the other's inputs.
+ *
+ * `directMechanismEvidence` is pinned `false` for exactly the reason the sibling pins it —
+ * DEC-334 holds `confirmed` for a result that passed the full governance pipeline, which does
+ * not run in an MCP call. So this tops out at `strongly supported` too, and the split changes
+ * which failures are *visible*, never which label this surface may mint.
+ *
+ * Null on refusal is deliberate and is not the same as `unconfirmed`: a refusal is a fact about
+ * Descry rather than about the application, and reporting it as an evidence reading would teach
+ * the caller that we looked and saw nothing.
+ */
+function deriveEnvelopeExistence(tier, state, witnessed) {
+    if (tier === "conclusion")
+        return null;
+    if (state === "failed" || state === "timed_out" || state === "refused")
+        return null;
+    return deriveExistenceCategory({
+        hasRuntimeEvidence: witnessed !== undefined,
+        directMechanismEvidence: false,
+        independentSignalTypes: witnessed?.independentSignalTypes ?? 0,
+    });
+}
+/**
+ * A refusal's reason must be the specific, verbatim thing that blocked it —
+ * never just the state name. This is a heuristic proxy for that rule (§4):
+ * `disclosures` must contain something a template did not produce, which we
+ * cannot verify from here, but we CAN verify the weaker, structurally
+ * checkable half — that at least one disclosure exists and it is not empty
+ * text — the same shape invariant 2 already asserts. The stronger claim (the
+ * reason is *this* refusal's actual cause, not a generic string) is a
+ * per-tool authoring discipline this function cannot see into; it is checked
+ * by `tool-contract-gate.mjs`'s exemplar reading instead.
+ */
+/**
+ * The retired-name disclosure, for every render path rather than the happy one.
+ *
+ * A call under a dead name that *fails* still needs to be told the name is
+ * dead — arguably more than a call that succeeds, since the caller is already
+ * debugging and "no such tool" is one release away. `renderAnswer` is not the
+ * only exit: a refusal, a failure, a handshake and a timeout are all replies a
+ * retired name can produce, and each assembles its own disclosure list.
+ */
+function aliasNotes(options) {
+    return options.aliasedFrom === undefined || options.aliasedTo === undefined
+        ? []
+        : [aliasDisclosure(options.aliasedFrom, options.aliasedTo)];
+}
+/**
+ * Lane "map-freshness" item 1 — `AnswerEnvelope.graph.freshness`'s structured
+ * half, shared by every envelope-building function in this file. `null` when
+ * `commitSha` is `null` (nothing to be fresh or stale relative to, same
+ * reasoning as `resolutionFloor: null` on an unconsulted graph). Otherwise
+ * `unknown` with both counts `null` when this call's `RenderOptions` never
+ * supplied a `freshness` — "not checked" must never render as the false
+ * positive "current" would be.
+ */
+function freshnessField(commitSha, freshness) {
+    if (commitSha === null)
+        return null;
+    if (freshness === undefined)
+        return { status: "unknown", commitsSince: null, changedIndexedFiles: null };
+    return {
+        status: freshness.status,
+        commitsSince: freshness.status === "behind" ? freshness.commitsSince : null,
+        changedIndexedFiles: freshness.status === "behind" ? freshness.changedFiles.length : null,
+    };
+}
+/**
+ * The plain-words half — "up to 5 of those files, plus the total" (lane
+ * "map-freshness" item 1). `undefined` on `current`/`unknown-with-nothing-
+ * to-say`: a disclosure that repeats "the map is current" on every single
+ * reply is exactly the noise `disclosure-ledger.ts` exists to avoid for the
+ * reliability sentence, and this field has no standing-ledger mechanism of
+ * its own to fall back to, so it says nothing rather than something on
+ * every call.
+ */
+function freshnessDisclosure(freshness) {
+    if (freshness === undefined || freshness.status === "current")
+        return undefined;
+    if (freshness.status === "unknown") {
+        return ("Whether the code map matches the current code could not be determined — this is not a git " +
+            "repository, or git is unavailable here.");
+    }
+    const { shown, total } = sampleChangedFiles(freshness);
+    const commitsPart = freshness.commitsSince === null
+        ? "an unknown number of commits (history was rewritten since the map was built)"
+        : freshness.commitsSince === 0
+            ? "0 commits"
+            : `${freshness.commitsSince} commit(s)`;
+    const filesPart = total === 0
+        ? "no indexed file is known to have changed"
+        : `${total} indexed file(s) changed since the map was built` +
+            (shown.length > 0 ? ` — including ${shown.join(", ")}${total > shown.length ? ", …" : ""}` : "");
+    return `The code map is behind the current code: ${commitsPart} since it was built. ${filesPart}.`;
+}
+/** Both halves of the lane "map-freshness" disclosure, shared by every
+ *  envelope-building function in this file (see `RenderOptions.autoNotes`/
+ *  `.freshness`'s own docs). Ordered ahead of everything else these
+ *  functions add — a caller needs to know the map just changed, or is
+ *  stale, before it needs any other caveat. */
+function freshnessCrossCuttingNotes(options) {
+    const note = freshnessDisclosure(options.freshness);
+    return [...(options.autoNotes ?? []), ...(note === undefined ? [] : [note])];
+}
+export function renderAnswer(tool, answer, options) {
+    const { result, nameLevel } = answer;
+    const state = answer.state ?? "ok";
+    if (result.truncated && result.notes.length === 0) {
+        throw new DisclosureError(`${tool} returned a truncated answer with no disclosure. A partial result that does not ` +
+            "say it is partial reads as a complete one, which is the failure rule 7 exists to " +
+            "prevent. Fix the query, not this check.");
+    }
+    if ((state === "refused" || state === "failed" || state === "timed_out") && result.notes.length === 0) {
+        throw new DisclosureError(`${tool} reported "${state}" without saying why. The five result states exist to distinguish ` +
+            '"we found nothing" from "we could not look" from "something broke"; with no reason attached ' +
+            "this reply says none of them.");
+    }
+    // B6, fifth invariant (module header): a truncated answer must carry real
+    // counts. The old fallback here was a sentinel, `{shown: -1, total: -1}` —
+    // worse than absent, because it passes a presence check and then poisons
+    // arithmetic. A tool that sets `result.truncated` without supplying
+    // `answer.truncatedDetail` has not held the two together the way
+    // `capped()` (`./capped.ts`) makes automatic, so this is a defect in that
+    // tool, caught here rather than shipped: thrown everywhere except
+    // production, where the honest degradation is `null` plus a disclosure
+    // that the count itself is unavailable — never a fabricated one.
+    let missingTruncationDetail = null;
+    if (result.truncated && answer.truncatedDetail === undefined) {
+        if (process.env["NODE_ENV"] !== "production") {
+            throw new DisclosureError(`${tool} set result.truncated without a truncatedDetail (shown/total). Build the capped ` +
+                'slice and its detail together — see capped() in "./capped.ts" — rather than capping ' +
+                "and reporting separately, where one of the two can be forgotten.");
+        }
+        missingTruncationDetail =
+            "this reply was truncated, but how much was withheld is unavailable — a defect in this " +
+                "tool, not a fact about your code";
+    }
+    const resolutionFloor = result.stamp.resolutionFloor;
+    const cap = reliabilityCap(resolutionFloor, nameLevel);
+    // Full the first time this connection meets this category, a short reference
+    // to it after — see `disclosure-ledger.ts`. The floor and the class are on
+    // every reply either way; only the argument for them collapses.
+    const reliability = reliabilityDisclosure(resolutionFloor, nameLevel);
+    const disclosures = [
+        ...result.notes,
+        // First among the disclosures, ahead of the reliability argument: a caller
+        // on a dead name needs to know that before it needs anything else.
+        ...aliasNotes(options),
+        ...(missingTruncationDetail === null ? [] : [missingTruncationDetail]),
+        options.disclosureLedger?.firstSighting(reliability.key) === false
+            ? reliability.brief
+            : reliability.full,
+        ...(result.stamp.commitSpread > 1
+            ? [
+                `a repository in this graph has runs spanning ${result.stamp.commitSpread} distinct ` +
+                    "commits; part of its graph may describe code that is no longer current",
+            ]
+            : []),
+        // A neutral fact, never a warning — cross-repo sharing (`link_workspace`) is
+        // what makes cross-repo contracts/validate/similar_incidents work at all.
+        // UAT phase 5: this used to be the same sentence as the staleness warning
+        // above, driven by a global (not per-repo) commit count, so it fired on
+        // every single reply in a shared workspace and read as decay that was
+        // never real — training the reader to ignore it before the day a genuine
+        // staleness warning needed attention.
+        ...(result.stamp.repoCount > 1
+            ? [`this graph spans ${result.stamp.repoCount} repositories, each at its own HEAD`]
+            : []),
+        ...(options.configDrift?.note === undefined ? [] : [options.configDrift.note]),
+        ...(options.discardedArgs === undefined || options.discardedArgs.length === 0
+            ? []
+            : [discardedArgsNote(options.discardedArgs)]),
+    ];
+    // Lane "map-freshness" items 1-3: an automatic build/refresh note (if one
+    // ran before this call) and the freshness disclosure itself, both ahead of
+    // every other disclosure — a caller needs to know the map just changed, or
+    // is stale, before it needs anything else this reply does not cover. See
+    // `freshnessCrossCuttingNotes` above.
+    const crossCuttingNotes = freshnessCrossCuttingNotes(options);
+    // B10 — minted by the caller before this call, so it is threaded through
+    // rather than generated here; a fallback exists only for the direct callers
+    // (tests) that have no session id sequence to draw from. See `callId`'s own
+    // doc on `AnswerEnvelope` and `RenderOptions`.
+    const callId = options.callId ?? randomUUID();
+    const build = (data, extraNotes, fitTruncation) => ({
+        tool,
+        toolVersion: options.toolVersion,
+        callId,
+        state,
+        class: options.toolClass,
+        headline: answer.headline,
+        data,
+        graph: {
+            commitSha: result.stamp.commitSha,
+            builtAt: result.stamp.graphBuiltAt === null
+                ? null
+                : new Date(result.stamp.graphBuiltAt).toISOString(),
+            irSchemaVersion: result.stamp.irSchemaVersion,
+            resolutionFloor,
+            reliabilityCap: cap,
+            freshness: freshnessField(result.stamp.commitSha, options.freshness),
+        },
+        truncated: fitTruncation ?? (!result.truncated ? null : (answer.truncatedDetail ?? null)),
+        refusals: answer.refusalSummary ?? null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        // The fit's own notes go first among the disclosures it added, ahead of
+        // the standing reliability sentence, for the same reason `narrate` puts
+        // disclosures last: what is specific to this call must not be buried
+        // under what is true of every call. `crossCuttingNotes` goes ahead of
+        // even that — see its own doc above.
+        disclosures: [
+            ...crossCuttingNotes,
+            ...(extraNotes.length === 0 ? disclosures : [...result.notes, ...extraNotes, ...disclosures.slice(result.notes.length)]),
+        ],
+        configStale: options.configDrift?.stale ?? false,
+        reportCategory: deriveEnvelopeCategory(options.toolTier, state, resolutionFloor, nameLevel, answer.runtimeEvidence),
+        existenceCategory: deriveEnvelopeExistence(options.toolTier, state, answer.runtimeEvidence),
+        provenance: PROVENANCE,
+    });
+    const frame = (envelope) => ({
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+    });
+    const rendered = frame(build(result.data, [], null));
+    const ceiling = options.maxReplyBytes ?? MAX_REPLY_BYTES;
+    if (answer.fitToBudget === undefined || sizeOf(rendered) <= ceiling)
+        return rendered;
+    // The tool is asked for a payload that fits in what is left once everything
+    // else is paid for. Its own disclosures cost bytes too, so the first budget
+    // can be slightly optimistic — the loop re-measures and asks again with the
+    // corrected figure rather than assuming one pass converges. Two passes is
+    // the observed cost; the third exists so a pathological oscillation ends.
+    let fitted = rendered;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const payloadBytes = Buffer.byteLength(JSON.stringify(dataOf(fitted)) ?? "null", "utf8");
+        const budget = ceiling - (sizeOf(fitted) - payloadBytes);
+        const fit = answer.fitToBudget(Math.max(budget, 0));
+        if (fit.truncatedDetail !== undefined && fit.notes.length === 0) {
+            throw new DisclosureError(`${tool} dropped items to fit the reply's size budget without saying so. A reply shrunk in ` +
+                "silence reads as a complete one — the same failure invariant 1 covers for a query's own " +
+                "truncation, arriving by a different route.");
+        }
+        fitted = frame(build(fit.data, fit.notes, fit.truncatedDetail ?? null));
+        if (sizeOf(fitted) <= ceiling)
+            break;
+    }
+    // Returned even if the last pass is still over: a tool that cannot shrink
+    // below the ceiling has an oversized answer either way, and an oversized
+    // answer beats a fabricated small one.
+    return fitted;
+}
+function sizeOf(rendered) {
+    return Buffer.byteLength(JSON.stringify(rendered), "utf8");
+}
+/** The `data` inside a rendered frame, for measuring its share of the total. */
+function dataOf(rendered) {
+    return rendered.structuredContent.data;
+}
+/**
+ * The text an agent actually reads.
+ *
+ * Ordered so that the disclosures are **last**, because that is what a model
+ * summarising the reply keeps. A caveat buried above the data is a caveat that
+ * gets dropped in the summary the developer sees.
+ */
+function narrate(envelope) {
+    const lines = [envelope.headline];
+    if (envelope.state !== "ok" && envelope.state !== "empty") {
+        lines.push("", `**${envelope.state}.** ` +
+            (envelope.state === "refused"
+                ? "This is not a result — see below for why Descry could not look."
+                : envelope.state === "failed"
+                    ? "Something broke while answering this call — see below."
+                    : "The call ran out of its declared time budget — see below."));
+    }
+    else if (envelope.state === "empty") {
+        lines.push("", "**Empty.** Descry looked completely and there was nothing to find — see below.");
+    }
+    // Three cases, not two (F3 / Part A §3, UAT Phase 5): `commitSha === null`
+    // is the only condition that actually means "nothing has been analysed" —
+    // `renderRefusedInput`/`renderFailed`/`renderTimedOut` used to hardcode it
+    // regardless of what the stored graph held, so every argument-validation
+    // refusal against an already-populated graph asserted a specific, checkable,
+    // false claim about the user's code. `resolutionFloor === null` is the
+    // existing, already-true signal for "this call never consulted the graph"
+    // (see the field's own doc on `AnswerEnvelope.graph`) — reused here rather
+    // than adding a second one that could drift from it.
+    const stale = envelope.graph.commitSha === null
+        ? "The graph is empty — nothing has been analysed into it yet."
+        : envelope.graph.resolutionFloor === null
+            ? `Graph at ${envelope.graph.commitSha.slice(0, 12)}` +
+                (envelope.graph.builtAt === null ? "" : `, built ${envelope.graph.builtAt}`) +
+                " is stored, but this reply made no use of it — no resolution or reliability class applies here."
+            : `Graph at ${envelope.graph.commitSha.slice(0, 12)}` +
+                (envelope.graph.builtAt === null ? "" : `, built ${envelope.graph.builtAt}`) +
+                `. Weakest evidence R${envelope.graph.resolutionFloor}; findings here cap at ` +
+                `reliability class ${envelope.graph.reliabilityCap}.`;
+    lines.push("", stale);
+    if (envelope.disclosures.length > 0) {
+        lines.push("", "What this answer does not cover:");
+        for (const note of envelope.disclosures)
+            lines.push(`- ${note}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * A malformed call the server cannot even attribute to one tool — the RPC
+ * named no string tool, or named a tool that does not exist in the registry.
+ *
+ * Returned as a tool result with `isError`, not as a JSON-RPC error, which is
+ * what the MCP spec asks for: protocol errors are for malformed protocol, tool
+ * errors are for tools, and an agent can act on the second only if it arrives as
+ * content it can read.
+ *
+ * Deliberately outside the five-state envelope, and narrowly so: there is no
+ * resolved `ToolDefinition` here to draw `toolVersion`/`class`/`tier` from, so
+ * no real envelope can be built — inventing placeholder values for them would
+ * be worse than the bare shape. Once a tool *is* identified, a bad argument
+ * against it is `renderRefusedInput`'s case, not this one — see that
+ * function's doc for why the two are different claims.
+ */
+export function renderToolError(tool, message) {
+    return {
+        content: [{ type: "text", text: `${tool}: ${message}` }],
+        structuredContent: { tool, status: "error", message },
+        isError: true,
+    };
+}
+/**
+ * `state: "refused"` — the call named a real, resolved tool, but its input
+ * was wrong, so the tool never ran (`ToolInputError`, thrown by a tool's own
+ * argument reading, or by the dispatcher's own shape check on `arguments`
+ * once a tool is known).
+ *
+ * This used to fall through to `renderToolError`'s bare `{tool, status,
+ * message}` shape — measured as a real defect (a live `observe_runtime` call
+ * with a malformed `profile` field returned that bare shape instead of an
+ * envelope), because unlike the two cases `renderToolError` still covers, a
+ * `ToolDefinition` *is* available here: `toolVersion`, `class` and `tier` are
+ * all real, so a real envelope can be built rather than invented. "The tool
+ * was never run because its input was wrong" is a fact about this call, not
+ * about the code being examined — exactly what `state: "refused"` already
+ * means everywhere else in this file, so it is rendered the same way rather
+ * than through a second, parallel shape.
+ *
+ * `data` is always `null` (§2.2): nothing ran, so there is nothing to stamp.
+ * `isError` stays `true` for the same reason `renderFailed`/`renderTimedOut`
+ * set it — a generic client that only reads the transport-level signal still
+ * sees a failure; an AI-layer-aware caller additionally gets the real
+ * `state`/`disclosures`/`reportCategory` to reason about.
+ */
+export function renderRefusedInput(tool, message, options) {
+    const stamp = options.graphStamp;
+    const envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        callId: options.callId ?? randomUUID(),
+        state: "refused",
+        class: options.toolClass,
+        headline: `${tool} could not run: ${message}`,
+        data: null,
+        graph: {
+            // Facts about the *stored* graph, independent of whether this refusal
+            // ever reached it (F3, UAT Phase 5) — `renderHandshake` already reads
+            // these from `graphStamp` the same way; `resolutionFloor` stays `null`
+            // regardless, because this call genuinely never consulted the graph.
+            commitSha: stamp?.commitSha ?? null,
+            builtAt: stamp?.graphBuiltAt === undefined || stamp.graphBuiltAt === null ? null : new Date(stamp.graphBuiltAt).toISOString(),
+            irSchemaVersion: stamp?.irSchemaVersion ?? 0,
+            resolutionFloor: null,
+            reliabilityCap: "C",
+            freshness: freshnessField(stamp?.commitSha ?? null, options.freshness),
+        },
+        truncated: null,
+        refusals: null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures: [...aliasNotes(options), message, ...(options.configDrift?.note === undefined ? [] : [options.configDrift.note])],
+        configStale: options.configDrift?.stale ?? false,
+        // Same rule `deriveEnvelopeCategory` applies everywhere else: a
+        // conclusion-tier tool states its verdict in `headline`'s own words, so
+        // this stays null there; an evidence-tier tool's refusal maps to "not
+        // analysable" — "could not look" either way, whether the graph refused
+        // the query or the call never reached the graph at all.
+        reportCategory: options.toolTier === "conclusion" ? null : "not analysable",
+        // A refusal read no evidence, so it makes no existence claim — see the field doc.
+        existenceCategory: null,
+        provenance: PROVENANCE,
+    };
+    return {
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+        isError: true,
+    };
+}
+/**
+ * `state: "failed"` — §1.1: "promoted from a transport error to a result."
+ *
+ * An unexpected/internal error, not a bad argument (`renderToolError` still
+ * handles those). `data` is always `null` here (§2.2): the tool does not know
+ * what happened, and anything it returned would be a guess about its own
+ * fault. `isError` stays `true` so a generic MCP client that only reads the
+ * transport-level signal still treats this as a failure; an AI-layer-aware
+ * caller additionally gets `state: "failed"` in `structuredContent` to reason
+ * about rather than a bare `{tool, status, message}` shape.
+ *
+ * `headline` is optional and exists for the *explained* half of "failed": a
+ * `ConfigError` (and any sibling raised specifically to be read, not merely
+ * caught) already carries a full written reason, and burying that behind a
+ * generic "X failed." while the real sentence sits only in `disclosures` is
+ * the bug 13.3.5 names — a caller reading just the headline learns nothing.
+ * An unexplained internal fault has no such sentence to offer, so it keeps
+ * the opaque default.
+ */
+export function renderFailed(tool, message, options, headline) {
+    const stamp = options.graphStamp;
+    const envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        callId: options.callId ?? randomUUID(),
+        state: "failed",
+        class: options.toolClass,
+        headline: headline ?? `${tool} failed.`,
+        data: null,
+        graph: {
+            // See `renderRefusedInput`'s identical comment (F3, UAT Phase 5): a
+            // fault is not a claim about the graph, but "nothing has been analysed"
+            // is a claim about the graph, and stating it falsely is worse than not
+            // stating a stored commit this call happened not to read.
+            commitSha: stamp?.commitSha ?? null,
+            builtAt: stamp?.graphBuiltAt === undefined || stamp.graphBuiltAt === null ? null : new Date(stamp.graphBuiltAt).toISOString(),
+            irSchemaVersion: stamp?.irSchemaVersion ?? 0,
+            resolutionFloor: null,
+            reliabilityCap: "C",
+            freshness: freshnessField(stamp?.commitSha ?? null, options.freshness),
+        },
+        truncated: null,
+        refusals: null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures: [...aliasNotes(options), message, ...(options.configDrift?.note === undefined ? [] : [options.configDrift.note])],
+        configStale: options.configDrift?.stale ?? false,
+        // A fault is not a claim about the code either way (§20) — no category applies.
+        reportCategory: null,
+        existenceCategory: null,
+        provenance: PROVENANCE,
+    };
+    return {
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+        isError: true,
+    };
+}
+/**
+ * The one legitimate producer of a pending-handshake payload — §7's mint call.
+ *
+ * `class == "action"` returning anything other than this shape on an
+ * unconfirmed first call is invariant 4 (§2.1): "throw." This function is
+ * where that shape is produced, so the throw lives at the one call site that
+ * builds anything else for an action tool's first call — `server.ts`'s
+ * dispatch loop calls this and only this when `resolveActionDispatch` returns
+ * `{kind: "handshake"}`, never `tool.run`.
+ *
+ * `state: "ok"` deliberately: a mint is not a refusal, a failure or an empty
+ * result — it is a successful "here is what I would do", and the *pending*
+ * flag inside `data` is what tells a caller nothing was performed yet.
+ */
+export function renderHandshake(tool, token, willDo, options) {
+    const stamp = options.graphStamp;
+    const envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        callId: options.callId ?? randomUUID(),
+        state: "ok",
+        class: options.toolClass,
+        headline: `Confirmation required: ${willDo}`,
+        data: { pending: true, token, willDo },
+        graph: {
+            commitSha: stamp?.commitSha ?? null,
+            builtAt: stamp?.graphBuiltAt === undefined || stamp.graphBuiltAt === null ? null : new Date(stamp.graphBuiltAt).toISOString(),
+            irSchemaVersion: stamp?.irSchemaVersion ?? 0,
+            // Nothing has been read for THIS call — a mint makes no claim, so it
+            // carries no resolution/reliability of its own, the same reasoning
+            // `renderFailed`/`renderTimedOut` use. Only commitSha/builtAt/
+            // irSchemaVersion are real facts about the stored graph, independent of
+            // whether this pending action has been confirmed yet.
+            resolutionFloor: null,
+            reliabilityCap: "C",
+            freshness: freshnessField(stamp?.commitSha ?? null, options.freshness),
+        },
+        truncated: null,
+        refusals: null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures: [
+            ...aliasNotes(options),
+            `Nothing was performed. Call ${tool} again with { "confirmToken": "${token}" } to actually do this — ` +
+                "the token expires in five minutes and is single-use.",
+            ...(options.configDrift?.note === undefined ? [] : [options.configDrift.note]),
+        ],
+        configStale: options.configDrift?.stale ?? false,
+        // Nothing was analysed yet — a confirmation prompt makes no claim to categorize.
+        reportCategory: null,
+        existenceCategory: null,
+        provenance: PROVENANCE,
+    };
+    return {
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+    };
+}
+/**
+ * `state: "timed_out"` — the call ran out of its declared budget.
+ *
+ * §6: "not a silent truncation and never a `failed`". `data` is `null` here
+ * because none of the registered tools currently produce genuine partial
+ * results mid-run (none checks `ctx.signal` internally yet — a disclosed gap,
+ * not a silent one, named in the returned disclosure); the envelope shape
+ * supports a populated partial `data` the day a tool does.
+ */
+export function renderTimedOut(tool, options) {
+    const stamp = options.graphStamp;
+    const envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        callId: options.callId ?? randomUUID(),
+        state: "timed_out",
+        class: options.toolClass,
+        headline: `${tool} timed out.`,
+        data: null,
+        graph: {
+            // See `renderRefusedInput`'s identical comment (F3, UAT Phase 5).
+            commitSha: stamp?.commitSha ?? null,
+            builtAt: stamp?.graphBuiltAt === undefined || stamp.graphBuiltAt === null ? null : new Date(stamp.graphBuiltAt).toISOString(),
+            irSchemaVersion: stamp?.irSchemaVersion ?? 0,
+            resolutionFloor: null,
+            reliabilityCap: "C",
+            freshness: freshnessField(stamp?.commitSha ?? null, options.freshness),
+        },
+        truncated: null,
+        refusals: null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures: [
+            ...aliasNotes(options),
+            `${tool} did not finish within its ${options.limitMs}ms budget. This is a partial answer, not ` +
+                "a finding of failure or of absence — retry, or narrow the request.",
+            ...(options.configDrift?.note === undefined ? [] : [options.configDrift.note]),
+        ],
+        configStale: options.configDrift?.stale ?? false,
+        // A partial run in progress makes no claim to categorize yet.
+        reportCategory: null,
+        existenceCategory: null,
+        provenance: PROVENANCE,
+    };
+    return {
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+        isError: true,
+    };
+}
+//# sourceMappingURL=render.js.map