@descryy/mcp 0.11.3 → 0.11.5

package/dist/render.js

@@ -1,867 +0,0 @@
-/**
- * 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";
-/**
- * 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.",
-                },
-            },
-            required: ["commitSha", "builtAt", "irSchemaVersion", "resolutionFloor", "reliabilityCap"],
-        },
-        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)];
-}
-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)]),
-    ];
-    // 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,
-        },
-        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.
-        disclosures: 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",
-        },
-        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",
-        },
-        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",
-        },
-        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",
-        },
-        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