@descryy/mcp 0.5.0 → 0.7.0

package/dist/registry.js

@@ -1,47 +1,8 @@
-/**
- * How the server reaches adapters without this repository depending on them.
- *
- * `descry-core` must not import `descry-adapters`: the IR boundary is a
- * dependency-direction fact, and an import here would invert it in the one place
- * where it matters most — the process that runs everything. So sources are named
- * in configuration as module specifiers and loaded at runtime. The engine knows
- * `IRSource`; it never knows the word "python".
- *
- * ## The factory convention, and why it is a convention rather than an interface
- *
- * Every adapter in `descry-adapters` exports `ADAPTER_ID`, `ADAPTER_VERSION` and
- * a factory named `create<Something>Adapter` — `createGoAdapter`,
- * `createTypeScriptAdapter`, `createOpenApiAdapter`. There is no uniform name,
- * and inventing one now would be a breaking change across twelve packages to
- * save a regular expression. So: an explicit `export` in config wins; failing
- * that, the single export matching `create*Adapter` is used; **two matches is an
- * error, not a coin toss.**
- *
- * ## Failing to load a source is a disclosure, never a shrug
- *
- * An adapter that will not import is the difference between "we found no problem
- * in your Python service" and "we could not read your Python service" — §20.2
- * keeps those in different categories, and a registry that quietly skipped a
- * broken specifier would collapse them at the very bottom of the stack, where no
- * layer above could ever recover the distinction. Every failure comes back as a
- * `SourceLoadFailure` carrying the specifier and the reason, and the caller is
- * structurally unable to take the loaded sources without also taking the list of
- * ones that are missing.
- *
- * ## Two places to look, because the server and the repository are not the same tree
- *
- * `import(spec.module)` resolves relative to *this package's* location. That is
- * right for a side-by-side install — `npm i @descryy/mcp @descryy/adapter-x` puts
- * both under the repository's own `node_modules` — and useless under `npx -y
- * @descryy/mcp <repo>`, where the server runs out of an isolated npx cache
- * directory that contains no adapter the user ever installed. So a specifier is
- * resolved from the **repository root first** when one is known: that is where the
- * user installed the adapter and where their lockfile pins its version. The
- * server's own closure stays as the fallback, so the side-by-side install and the
- * absolute-path and `file:` specifiers that never needed a repository keep working
- * unchanged. When both fail, both are disclosed — a resolution nobody attempted is
- * the worst thing to make somebody debug.
- */
+/** How the server reaches adapters without depending on them: `descry-core` must never
+ *  import `descry-adapters` (rule 1, IR boundary) — sources are named as module specifiers
+ *  in config and loaded at runtime via a `create*Adapter` convention (an ambiguous match
+ *  errors, never guesses). A failed load is disclosed as `SourceLoadFailure`, never silently
+ *  skipped (§20.2). Specifiers resolve from the repo root first (npx isolates adapters there), then this package's own closure. */
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
         return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
@@ -52,19 +13,15 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { checkModuleTrust, checkRepoResolvedModuleTrust } from "./module-trust.js";
 const FACTORY_PATTERN = /^create[A-Za-z0-9]*Adapter$/;
 export function normaliseSpec(entry) {
     return typeof entry === "string" ? { module: entry } : entry;
 }
-/**
- * A loaded module is a `LanguageAdapter` when it can be asked what it supports.
- *
- * Duck-typed on the two methods that matter rather than on a marker, because the
- * adapters are compiled separately and `instanceof` across package boundaries is
- * a well-known way to be wrong. `detect` and `capabilities` are the two the
- * server actually calls; a source with both is one it can treat as an adapter.
- */
+/** A loaded module is a `LanguageAdapter` when it can be asked what it supports. Duck-typed
+ *  on `detect`/`capabilities` — the two methods the server calls — since `instanceof` across
+ *  separately-compiled adapter packages is unreliable. */
 function asAdapter(source) {
     const candidate = source;
     return typeof candidate.detect === "function" && typeof candidate.capabilities === "function"
@@ -78,11 +35,8 @@ function describe(error) {
     }
     return String(error);
 }
-/**
- * @param repoPath Repository being analysed, when one is known. Specifiers are
- * resolved from here first; without it only the server's own closure is searched,
- * which is correct for callers that name modules by absolute path or `file:` URL.
- */
+/** @param repoPath Repo being analysed, when known — specifiers resolve from here first;
+ *  without it only this package's closure is searched (correct for absolute-path/`file:` callers). */
 export async function loadSources(entries, repoPath) {
     const loaded = [];
     const failed = [];
@@ -97,20 +51,9 @@ export async function loadSources(entries, repoPath) {
     }
     return { loaded, failed };
 }
-/**
- * Resolve a specifier as the repository itself would, from its own `node_modules`.
- *
- * `createRequire` anchored at the repository's `package.json` is the resolution a
- * script run inside that repository would get. It is CommonJS resolution, so it
- * reads `exports` under the `require`/`default` conditions — every adapter here
- * publishes a `default`, and one that did not would fall through to the server's
- * closure rather than fail the load. The resolved path is imported as a URL, so
- * the module itself is still loaded as ESM.
- *
- * Returns the reason on failure rather than throwing: a specifier the repository
- * cannot see is not yet a failure, only a fact worth disclosing if the second
- * attempt fails too.
- */
+/** Resolves a specifier as the repo's own `node_modules` would, via `createRequire` anchored
+ *  at its `package.json` (CJS resolution, `require`/`default` conditions), then imports the
+ *  resolved path as ESM. Returns the reason on failure rather than throwing — not yet a failure until the fallback also fails. */
 function resolveFromRepo(specifier, repoPath) {
     try {
         const require = createRequire(pathToFileURL(join(repoPath, "package.json")));
@@ -145,18 +88,29 @@ async function instantiate(spec, repoPath) {
     }
     return { source, adapter: asAdapter(source) };
 }
-/**
- * Repository root first, the server's own closure second.
- *
- * Only a *resolution* failure falls through. A module that resolves and then
- * throws while evaluating is that module's failure, and reporting it as "could
- * not be found" — or quietly loading a different copy from the server's closure
- * instead — would hide a broken adapter behind a wrong explanation.
- */
+/** Repository root first, the server's own closure second. Only a resolution failure falls
+ *  through — a module that resolves and then throws is that module's own failure, not "could not be found". */
 async function importSource(specifier, repoPath) {
+    // A-F1: specifier can come straight from the repo's own .descry/config.json (module-trust.ts).
+    // Checked on the raw string before either resolution attempt, since `resolveFromRepo` always
+    // turns its result into a `file:` URL regardless of whether the specifier was path-like.
+    const trust = checkModuleTrust(specifier);
+    if (!trust.allowed)
+        throw new Error(trust.reason);
     const fromRepo = repoPath === undefined ? { reason: "no repository root" } : resolveFromRepo(specifier, repoPath);
-    if ("url" in fromRepo)
+    if ("url" in fromRepo) {
+        // A-F1 follow-up: checkModuleTrust only sees the raw specifier, not that it resolves into
+        // the repo's own git-tracked node_modules — closes the gap where a hostile repo commits
+        // node_modules/<name> and delivers a payload on clone alone; override: DESCRY_ALLOW_TRACKED_NODE_MODULES=1.
+        const repoTrust = await checkRepoResolvedModuleTrust({
+            specifier,
+            repoPath: repoPath,
+            resolvedAbsolutePath: fileURLToPath(fromRepo.url),
+        });
+        if (!repoTrust.allowed)
+            throw new Error(repoTrust.reason);
         return await import(__rewriteRelativeImportExtension(fromRepo.url));
+    }
     try {
         return await import(__rewriteRelativeImportExtension(specifier));
     }
@@ -167,15 +121,9 @@ async function importSource(specifier, repoPath) {
             `(${fromRepo.reason})`, { cause: error });
     }
 }
-/**
- * Ask each loaded adapter whether it claims this repository.
- *
- * A source that is not a `LanguageAdapter` — the git history reader is the
- * standing example — has nothing to detect and always runs. A `detect` that
- * throws is treated as "did not detect", **with the reason recorded**: a broken
- * detector must not be able to fail the whole run, and must not be able to hide
- * either.
- */
+/** Asks each loaded adapter whether it claims this repository. A non-`LanguageAdapter`
+ *  source (the git reader) always runs. A throwing `detect` counts as "did not detect",
+ *  with the reason recorded — it can't fail the whole run, and can't hide either. */
 export async function detectSources(sources, root) {
     const applicable = [];
     const skipped = [];

package/dist/registry.js.map

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

package/dist/render.d.ts

@@ -35,6 +35,20 @@
  * 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 { type ReliabilityClass, type ReportCategory } from "@descryy/ir";
 import type { ResultState, SignalTypeCount, ToolClass } from "@descryy/ir";
@@ -231,6 +245,19 @@ export interface AnswerEnvelope<T = unknown> {
     readonly tool: string;
     /** Contract §6, rule 8. A behaviour change is a version bump; recorded with the run. */
     readonly toolVersion: string;
+    /**
+     * B10 — this call's own id in `Session#recordedCalls()`, minted before
+     * rendering (`Session#allocateCallId`) so it can be carried here rather
+     * than only discovered after the fact. A caller reads this off a real
+     * reply and cites it in `verify_claim`'s `callId` — the positive path that
+     * was previously unreachable because the id used to be minted only when
+     * `Session#recordCall` ran, one step after the envelope that would have
+     * carried it was already built and sent. Not recorded here — `verify_claim`
+     * itself is excluded from `Session#recordCall` (MK-12) and every other
+     * path still records under this same value, so the id an agent reads is
+     * always the id `recordedCall` will actually find.
+     */
+    readonly callId: string;
     readonly state: ResultState;
     /** DEC-278's three classes — §6's retry table reads this. */
     readonly class: ToolClass;
@@ -332,13 +359,16 @@ export interface AnswerEnvelope<T = unknown> {
  */
 export declare const ANSWER_ENVELOPE_SCHEMA: Record<string, unknown>;
 /**
- * The other shape a `tools/call` can return — `renderToolError`'s.
- *
- * Declared rather than quietly excluded. A bad argument is the most ordinary
- * failure a tool has, it deliberately does not use the five-state envelope
- * (see `renderToolError`), and a schema that admitted only the envelope would
- * be one the server itself violates on that path. Declaring a union that is
- * true beats declaring a single shape that is tidy.
+ * 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 declare const TOOL_ERROR_SCHEMA: Record<string, unknown>;
 /**
@@ -360,6 +390,16 @@ export interface RenderOptions {
     readonly toolTier: ToolTier;
     readonly elapsedMs: number;
     readonly limitMs: number;
+    /**
+     * B10 — the id this call will be recorded under, minted by
+     * `Session#allocateCallId()` before `renderAnswer` runs so it can be
+     * threaded into the envelope's own `callId`. Optional so every direct
+     * `renderAnswer` call in a test — none of which has a session's id
+     * sequence to draw from, and none of which asserts on `callId` — keeps
+     * compiling unchanged; a random id fills the gap there. `server.ts` is the
+     * one caller for which this matters and it always supplies a real one.
+     */
+    readonly callId?: string;
     /**
      * This connection's record of which standing disclosures it has already been
      * given in full. Optional: a caller with no session to dedupe within (every
@@ -389,18 +429,46 @@ export interface RenderOptions {
  */
 export declare function renderAnswer<T>(tool: string, answer: ToolAnswer<T>, options: RenderOptions): CallToolResult;
 /**
- * A failure that is the caller's to fix — a bad argument, a missing graph.
+ * 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: a bad argument is not a
- * statement about what Descry found or could not find, it is "fix your call
- * and retry" — a different kind of thing than `refused`/`failed`.
+ * 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 declare function renderToolError(tool: string, message: string): CallToolResult;
+/**
+ * `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 declare function renderRefusedInput(tool: string, message: string, options: RenderOptions): CallToolResult;
 /**
  * `state: "failed"` — §1.1: "promoted from a transport error to a result."
  *

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH,OAAO,EAQL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAmB,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,UAAU,qCAAsC,CAAC;AAC9D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,EAAE,KAAK,CAAC;CACpC;AASD,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,sBAAsB,EAAE,eAAe,CAAC;CAClD;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC;IAC7C;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IAC5C;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzG;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC;CAC7C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,4EAA4E;QAC5E,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QACxC,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC;KAC3C,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzG,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,sFAAsF;IACtF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/C,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAuI1D,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAYrD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAGtD,CAAC;AAEF,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAuCD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,aAAa,GACrB,cAAc,CAuIhB;AAoDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,GACrB,cAAc,CAiChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,GACrB,cAAc,CA6BhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,GACrB,cAAc,CA+BhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,cAAc,CAgCnF"}

package/dist/render.js

@@ -35,7 +35,22 @@
  * 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 { RELIABILITY_CLASSES, REPORT_CATEGORIES, RESULT_STATES, TOOL_CLASSES, reliabilityCap, reliabilityDisclosure, reportCategory as deriveReportCategory, } from "@descryy/ir";
 /**
  * MK-5 — which of the sixteen tools states a conclusion about the user's code
@@ -136,6 +151,11 @@ export const ANSWER_ENVELOPE_SCHEMA = {
             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],
@@ -233,6 +253,7 @@ export const ANSWER_ENVELOPE_SCHEMA = {
     required: [
         "tool",
         "toolVersion",
+        "callId",
         "state",
         "class",
         "headline",
@@ -247,13 +268,16 @@ export const ANSWER_ENVELOPE_SCHEMA = {
     ],
 };
 /**
- * The other shape a `tools/call` can return — `renderToolError`'s.
+ * 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 bad argument is the most ordinary
- * failure a tool has, it deliberately does not use the five-state envelope
- * (see `renderToolError`), and a schema that admitted only the envelope would
- * be one the server itself violates on that path. Declaring a union that is
- * true beats declaring a single shape that is tidy.
+ * 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",
@@ -342,6 +366,26 @@ export function renderAnswer(tool, answer, options) {
             '"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
@@ -350,6 +394,7 @@ export function renderAnswer(tool, answer, options) {
     const reliability = reliabilityDisclosure(resolutionFloor, nameLevel);
     const disclosures = [
         ...result.notes,
+        ...(missingTruncationDetail === null ? [] : [missingTruncationDetail]),
         options.disclosureLedger?.firstSighting(reliability.key) === false
             ? reliability.brief
             : reliability.full,
@@ -360,9 +405,15 @@ export function renderAnswer(tool, answer, 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,
@@ -376,10 +427,7 @@ export function renderAnswer(tool, answer, options) {
             resolutionFloor,
             reliabilityCap: cap,
         },
-        truncated: fitTruncation ??
-            (!result.truncated
-                ? null
-                : (answer.truncatedDetail ?? { shown: -1, total: -1, more: null })),
+        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
@@ -464,16 +512,20 @@ function narrate(envelope) {
     return lines.join("\n");
 }
 /**
- * A failure that is the caller's to fix — a bad argument, a missing graph.
+ * 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: a bad argument is not a
- * statement about what Descry found or could not find, it is "fix your call
- * and retry" — a different kind of thing than `refused`/`failed`.
+ * 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 {
@@ -482,6 +534,63 @@ export function renderToolError(tool, 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 envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        callId: options.callId ?? randomUUID(),
+        state: "refused",
+        class: options.toolClass,
+        headline: `${tool} could not run: ${message}`,
+        data: null,
+        graph: {
+            commitSha: null,
+            builtAt: null,
+            irSchemaVersion: 0,
+            resolutionFloor: null,
+            reliabilityCap: "C",
+        },
+        truncated: null,
+        refusals: null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures: [message],
+        // 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",
+        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."
  *
@@ -497,6 +606,7 @@ export function renderFailed(tool, message, options) {
     const envelope = {
         tool,
         toolVersion: options.toolVersion,
+        callId: options.callId ?? randomUUID(),
         state: "failed",
         class: options.toolClass,
         headline: `${tool} failed.`,
@@ -540,6 +650,7 @@ export function renderHandshake(tool, token, willDo, options) {
     const envelope = {
         tool,
         toolVersion: options.toolVersion,
+        callId: options.callId ?? randomUUID(),
         state: "ok",
         class: options.toolClass,
         headline: `Confirmation required: ${willDo}`,
@@ -580,6 +691,7 @@ export function renderTimedOut(tool, options) {
     const envelope = {
         tool,
         toolVersion: options.toolVersion,
+        callId: options.callId ?? randomUUID(),
         state: "timed_out",
         class: options.toolClass,
         headline: `${tool} timed out.`,