@axorum/mcp 0.0.0-stage → 1.0.0

package/dist/render.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Turning what the ledger said into what the model reads.
+ *
+ * # The one idea in this package
+ *
+ * **A refusal is a result, not an error.**
+ *
+ * When the policy in force forbids an action, the intent still reaches the commit point,
+ * is still judged, and the refusal is still *recorded*. The ledger answers `200`. The
+ * client resolves. And this module renders it as an ordinary tool result with `isError`
+ * **unset** — because that is what it is. The model reads "Refused", learns why, and
+ * adapts: it proposes something else, or it tells its human that the policy will not allow
+ * this and a human has to decide. That loop is the entire product. It is why it is safe to
+ * hand a language model money-moving tools at all.
+ *
+ * Setting `isError` on a refusal would break that loop in a specific and bad way. `isError`
+ * is the channel that means *the tool malfunctioned* — and a well-built agent's response to
+ * a malfunction is to retry. So a refusal dressed as an error invites the model to retry
+ * the exact thing the policy just forbade, in a loop, and to report to its human that
+ * Axorum is broken rather than that the spend was denied. The refusal is the most valuable
+ * thing this ledger produces. It goes in the `content`, in plain language, where the model
+ * will read it.
+ *
+ * {@link renderError} is for the cases where the ledger genuinely never got to answer: the
+ * process is misconfigured, the wire broke, the pin would not hold. Those are malfunctions,
+ * they set `isError`, and they carry the machine-readable `code` and the load-bearing
+ * extras a caller needs to act.
+ *
+ * @packageDocumentation
+ */
+import { type AgentOutcome, type CurrencyWarning, type UsageBalanceReport } from "@axorum/client";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * The headline sentence for a verdict — the first thing the model reads, and often the
+ * only thing it needs.
+ *
+ * Every line leads with whether money moved, because that is the question. The five
+ * verdicts are not five shades of the same thing:
+ *
+ * - `Permitted` — allowed, and posted.
+ * - `ObligatedFulfilled` — allowed, posted, and it discharged a duty.
+ * - `ObligatedPending` — allowed, posted, and it *created* a duty that is now owed.
+ * - `ForbiddenRecorded` — forbidden, **but posted anyway**, and the violation is on the
+ *   ledger. This is the "record, don't block" policy stance — a real one, and the reason
+ *   `posted` is not simply the inverse of "forbidden".
+ * - `ForbiddenRejected` — forbidden, and **nothing posted**. The recorded refusal.
+ */
+export declare function verdictLine(outcome: AgentOutcome): string;
+/**
+ * The full result for a submitted intent: the verdict line, then the structured outcome.
+ *
+ * Two content blocks, deliberately. The first is prose a model acts on without parsing
+ * anything; the second is the record — verdict, policy, transaction id, obligations,
+ * provenance — for when it needs a detail or wants to quote one to a human. Recorded
+ * provenance preserves the optional evaluation-semantics stamp; archived and
+ * pre-versioning records omit it. `isError` is **never** set here: every value of
+ * `AgentOutcome`, refusal included, is the ledger answering the question it was asked.
+ */
+export declare function renderOutcome(outcome: AgentOutcome): CallToolResult;
+/**
+ * Whether a stored transaction record says the entries posted — or `undefined` if it does
+ * not say in a shape this server recognises.
+ *
+ * The record is **contractually opaque** in this version of the wire contract: its shape is
+ * not frozen, and this server must not pretend to understand it. But one thing *is*
+ * guaranteed — a committed transaction's record carries a `posted` boolean, and a recorded
+ * refusal appears with `posted: false`. That single fact is the one a model reading a
+ * record back actually needs, so it is worth digging for.
+ *
+ * So this looks in the two places it can honestly look — the top level, and one level in
+ * under an externally tagged key (the record arrives today as `{"Transaction": {…}}`) — and
+ * gives up rather than guessing if it finds neither. A caller that gets `undefined` still
+ * gets the whole record; it just does not get a headline about it.
+ */
+export declare function postedFlag(record: unknown): boolean | undefined;
+/**
+ * The headline for a transaction read back off the ledger.
+ *
+ * A refusal found here is the audit trail doing its job — the ledger judged an intent,
+ * forbade it, and *remembered* doing so. Saying that plainly matters, because a model that
+ * reads back a record and sees only a wall of JSON may well conclude the lookup failed.
+ */
+export declare function describeRecord(transaction: string, record: unknown): string;
+/**
+ * What an agent reads about a declared currency the policy in force refuses some action in:
+ * which actions, that it cannot change it, and the remedy to hand a human.
+ */
+export declare function currencyWarningSentence(currency: string, warning: CurrencyWarning): string;
+/**
+ * The headline for a usage balance read back off the ledger.
+ *
+ * **Leads with the service's own sentence.** `report.text` is the balance narrated in
+ * compliance English with exact figures — the ledger's own words, not a rendering this
+ * server assembles from the counters. Restating it from the raw numbers would be a second
+ * source of truth for a compliance figure, and a chance to disagree with the first.
+ *
+ * What this adds is the part the narration cannot know: what the model should *do*. A
+ * balance's headroom is exactly what bounds its next lawful move, so it is worth saying
+ * plainly rather than leaving a model to derive it by subtracting two figures out of the
+ * JSON.
+ *
+ * # Two things this prose must not get wrong
+ *
+ * **A headroom bounds a POSITIVE move, and only a positive one.** `UsageBalance::admits`
+ * checks the *post-state*, so a **negative** delta — a credit memo, a metering fix — is
+ * admitted whenever the chain still holds afterwards and no counter would go below zero.
+ * From a fully reconciled `1000/1000/1000`, `bill_usage: -500` is lawful and posts. Telling
+ * a model that a reconciled balance refuses every move until fresh consumption arrives
+ * would be false, and would talk it out of a correction the ledger would have accepted —
+ * a correction this server's own input schema advertises.
+ *
+ * **The headrooms are bounds against the balance as it STANDS, and they move together
+ * inside one intent.** The moves of a single intent are judged against their *combined*
+ * post-state, so a meter move in the same intent raises what may be billed in it: at
+ * `10000/6500/4000`, `meter_usage: +3500` with `bill_usage: +6000` is admitted, even though
+ * the standing bill headroom is only `2500`. Stating the standing figure as a hard per-intent
+ * ceiling would understate the lawful bound and make the model split one commit into two.
+ */
+export declare function describeUsage(report: UsageBalanceReport): string;
+/** A plain successful result: a line of prose, then the structured payload. */
+export declare function renderResult(summary: string, payload: unknown): CallToolResult;
+/** A successful result that is prose only — nothing structured worth showing. */
+export declare function renderText(summary: string): CallToolResult;
+/**
+ * What the model was doing when the call failed.
+ *
+ * It changes what the failure *means*, so it cannot be inferred from the error: a read that
+ * fails wrote nothing because it never intended to, and telling a model that "the ledger did
+ * not judge your intent" when it merely asked for a balance invites it to worry about a
+ * posting that was never in flight. Every tool says which it is.
+ *
+ * A submission is `"submit"` when this server minted its transaction id, and `"resubmit"`
+ * when the model supplied one. The difference is what a refusal can prove. `submit_intent`
+ * sends a minted id once (re-sent only to re-pin, after a `409` that recorded nothing), so an
+ * answer that recorded nothing proves the id holds nothing. A supplied id may have been sent
+ * by an earlier call that never heard its answer, and that call may still commit: the same
+ * answer then speaks for this attempt only, never for the id.
+ */
+export type Operation = "submit" | "resubmit" | "read";
+/**
+ * A genuine failure: the ledger never got to answer, or this process is misconfigured.
+ *
+ * `isError: true`, which tells the model the *tool* malfunctioned rather than that the
+ * *spend* was denied — see the module docs on why that distinction is load-bearing.
+ *
+ * The content carries the machine-readable `code` and the **load-bearing extras**. Those
+ * extras are not decoration: without `active` no caller can re-pin, and without
+ * `primary_api_addr` none can say which replica the follower believed was primary. `@axorum/client` is hand-written
+ * precisely so they survive, and this server would be throwing that away if it rendered a
+ * bare message.
+ *
+ * `operation` is **required** rather than defaulted: a default would silently render a
+ * failed read in submit-shaped prose, which is exactly the bug it exists to prevent.
+ */
+export declare function renderError(error: unknown, operation: Operation): CallToolResult;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAUL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAKzE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAmDzD;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,cAAc,CAOnE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAa/D;AAOD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAa3E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAO1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAsChE;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAO9E;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAE1D;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;AAkDvD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,cAAc,CAuBhF"}

package/dist/render.js

@@ -0,0 +1,482 @@
+/**
+ * Turning what the ledger said into what the model reads.
+ *
+ * # The one idea in this package
+ *
+ * **A refusal is a result, not an error.**
+ *
+ * When the policy in force forbids an action, the intent still reaches the commit point,
+ * is still judged, and the refusal is still *recorded*. The ledger answers `200`. The
+ * client resolves. And this module renders it as an ordinary tool result with `isError`
+ * **unset** — because that is what it is. The model reads "Refused", learns why, and
+ * adapts: it proposes something else, or it tells its human that the policy will not allow
+ * this and a human has to decide. That loop is the entire product. It is why it is safe to
+ * hand a language model money-moving tools at all.
+ *
+ * Setting `isError` on a refusal would break that loop in a specific and bad way. `isError`
+ * is the channel that means *the tool malfunctioned* — and a well-built agent's response to
+ * a malfunction is to retry. So a refusal dressed as an error invites the model to retry
+ * the exact thing the policy just forbade, in a loop, and to report to its human that
+ * Axorum is broken rather than that the spend was denied. The refusal is the most valuable
+ * thing this ledger produces. It goes in the `content`, in plain language, where the model
+ * will read it.
+ *
+ * {@link renderError} is for the cases where the ledger genuinely never got to answer: the
+ * process is misconfigured, the wire broke, the pin would not hold. Those are malfunctions,
+ * they set `isError`, and they carry the machine-readable `code` and the load-bearing
+ * extras a caller needs to act.
+ *
+ * @packageDocumentation
+ */
+import { ApiError, AttestationError, AxorumError, CommitUnavailableError, NotPrimaryError, StalePolicyError, TransactionReusedError, UnknownAgentError, refusalOf, } from "@axorum/client";
+import { ConfigurationError } from "./config.js";
+import { toJsonText } from "./json.js";
+/**
+ * The headline sentence for a verdict — the first thing the model reads, and often the
+ * only thing it needs.
+ *
+ * Every line leads with whether money moved, because that is the question. The five
+ * verdicts are not five shades of the same thing:
+ *
+ * - `Permitted` — allowed, and posted.
+ * - `ObligatedFulfilled` — allowed, posted, and it discharged a duty.
+ * - `ObligatedPending` — allowed, posted, and it *created* a duty that is now owed.
+ * - `ForbiddenRecorded` — forbidden, **but posted anyway**, and the violation is on the
+ *   ledger. This is the "record, don't block" policy stance — a real one, and the reason
+ *   `posted` is not simply the inverse of "forbidden".
+ * - `ForbiddenRejected` — forbidden, and **nothing posted**. The recorded refusal.
+ */
+export function verdictLine(outcome) {
+    switch (outcome.verdict) {
+        case "Permitted":
+            return "Posted. Verdict: Permitted — the policy in force allows this action, and the entries were posted to the ledger.";
+        case "ObligatedFulfilled":
+            return "Posted. Verdict: ObligatedFulfilled — the entries were posted, and this action discharged an explicitly selected duty the actor was authorized to perform.";
+        case "ObligatedPending":
+            return ("Posted. Verdict: ObligatedPending — the entries were posted, and this action leaves " +
+                `${describeDuties(outcome.obligations_pending.length)} open. ` +
+                "Something now has to happen to discharge them; check get_obligations.");
+        case "ForbiddenRecorded":
+            return ("Posted, and recorded as a violation. Verdict: ForbiddenRecorded — the policy in force " +
+                "forbids this action, but the policy's stance is to record rather than block, so the " +
+                "entries WERE posted and the violation is on the ledger. Tell your human: this went " +
+                "through, and it went through against policy.");
+        case "ForbiddenRejected": {
+            // The server's reason (contract 5.0.0) names the rule that fired, states the exact
+            // figures its guard compared (with the headroom, the largest amount that would pass),
+            // and says what to do next; a server older than that sends none, so fall back to the
+            // general sentence. The structured conditions and figures ride in the second content
+            // block, every amount an exact decimal string (see toJsonText), so a model that wants
+            // to retry at the headroom reads the number rather than parsing prose.
+            const refusal = refusalOf(outcome);
+            const why = refusal
+                ? `Why (${refusal.code}): ${refusal.explanation}`
+                : "The policy in force forbids this action.";
+            return (`Refused — nothing posted. ${why} The refusal itself is now recorded on the ledger. ` +
+                "This is a verdict, not a failure: the system worked exactly as intended. Do NOT " +
+                "retry this unchanged — it will be refused again. Either propose an action the policy " +
+                "allows, or tell your human why it was refused and that a human has to change the " +
+                "policy to permit it.");
+        }
+        default:
+            // The verdict set is closed in this version of the contract, but a newer service may
+            // widen it. Report the verdict verbatim rather than guessing at its meaning — and
+            // lead with `posted`, which is the fact that matters either way.
+            return outcome.posted
+                ? `Posted. Verdict: ${String(outcome.verdict)} — a verdict this server does not have prose for. The entries WERE posted.`
+                : `Nothing posted. Verdict: ${String(outcome.verdict)} — a verdict this server does not have prose for. The entries were NOT posted.`;
+    }
+}
+/**
+ * The sentence that leads a replayed answer (contract 5.0.0): the transaction was already
+ * on the ledger, so this is its original outcome and nothing new was written. Without it
+ * a model would read "Posted." and believe it had just spent the money a second time.
+ */
+function replayPrefix(outcome) {
+    if (outcome.replayed !== true) {
+        return "";
+    }
+    const replay = `REPLAY: transaction ${outcome.transaction} was already on the ledger, so this is its ` +
+        "original outcome and NOTHING new was written. ";
+    return outcome.content_verified === false
+        ? replay +
+            "The ledger could not compare this request with the one it stored (the id was " +
+            "committed before 1.0.0), so if you changed the request, that change was NOT " +
+            "applied: submit it under a new transaction id. "
+        : replay;
+}
+/** `1 obligation` / `N obligations`, so the sentence above reads correctly either way. */
+function describeDuties(count) {
+    return count === 1 ? "1 obligation" : `${count} obligations`;
+}
+/**
+ * The full result for a submitted intent: the verdict line, then the structured outcome.
+ *
+ * Two content blocks, deliberately. The first is prose a model acts on without parsing
+ * anything; the second is the record — verdict, policy, transaction id, obligations,
+ * provenance — for when it needs a detail or wants to quote one to a human. Recorded
+ * provenance preserves the optional evaluation-semantics stamp; archived and
+ * pre-versioning records omit it. `isError` is **never** set here: every value of
+ * `AgentOutcome`, refusal included, is the ledger answering the question it was asked.
+ */
+export function renderOutcome(outcome) {
+    return {
+        content: [
+            { type: "text", text: replayPrefix(outcome) + verdictLine(outcome) },
+            { type: "text", text: toJsonText(outcome) },
+        ],
+    };
+}
+/**
+ * Whether a stored transaction record says the entries posted — or `undefined` if it does
+ * not say in a shape this server recognises.
+ *
+ * The record is **contractually opaque** in this version of the wire contract: its shape is
+ * not frozen, and this server must not pretend to understand it. But one thing *is*
+ * guaranteed — a committed transaction's record carries a `posted` boolean, and a recorded
+ * refusal appears with `posted: false`. That single fact is the one a model reading a
+ * record back actually needs, so it is worth digging for.
+ *
+ * So this looks in the two places it can honestly look — the top level, and one level in
+ * under an externally tagged key (the record arrives today as `{"Transaction": {…}}`) — and
+ * gives up rather than guessing if it finds neither. A caller that gets `undefined` still
+ * gets the whole record; it just does not get a headline about it.
+ */
+export function postedFlag(record) {
+    if (!isObject(record)) {
+        return undefined;
+    }
+    if (typeof record["posted"] === "boolean") {
+        return record["posted"];
+    }
+    for (const value of Object.values(record)) {
+        if (isObject(value) && typeof value["posted"] === "boolean") {
+            return value["posted"];
+        }
+    }
+    return undefined;
+}
+/** Whether a value is a non-null, non-array object. */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The headline for a transaction read back off the ledger.
+ *
+ * A refusal found here is the audit trail doing its job — the ledger judged an intent,
+ * forbade it, and *remembered* doing so. Saying that plainly matters, because a model that
+ * reads back a record and sees only a wall of JSON may well conclude the lookup failed.
+ */
+export function describeRecord(transaction, record) {
+    switch (postedFlag(record)) {
+        case true:
+            return `Transaction '${transaction}' is on the ledger, and it POSTED — the entries were written.`;
+        case false:
+            return (`Transaction '${transaction}' is on the ledger, and it was REFUSED — nothing posted. ` +
+                "The refusal itself is the record: the ledger judged this intent, the policy forbade it, " +
+                "and the ledger remembered doing so. This lookup succeeded; it is telling you the answer was no.");
+        default:
+            return `The stored ledger record for transaction '${transaction}'.`;
+    }
+}
+/**
+ * What an agent reads about a declared currency the policy in force refuses some action in:
+ * which actions, that it cannot change it, and the remedy to hand a human.
+ */
+export function currencyWarningSentence(currency, warning) {
+    const actions = warning.actions.map((action) => `'${action}'`).join(", ");
+    return (`The policy in force refuses ${actions} in ${currency}, whatever the intent carries. ` +
+        "You cannot change that: use a currency with no warning, or hand this remedy to a human " +
+        `operator: ${warning.remedy}.`);
+}
+/**
+ * The headline for a usage balance read back off the ledger.
+ *
+ * **Leads with the service's own sentence.** `report.text` is the balance narrated in
+ * compliance English with exact figures — the ledger's own words, not a rendering this
+ * server assembles from the counters. Restating it from the raw numbers would be a second
+ * source of truth for a compliance figure, and a chance to disagree with the first.
+ *
+ * What this adds is the part the narration cannot know: what the model should *do*. A
+ * balance's headroom is exactly what bounds its next lawful move, so it is worth saying
+ * plainly rather than leaving a model to derive it by subtracting two figures out of the
+ * JSON.
+ *
+ * # Two things this prose must not get wrong
+ *
+ * **A headroom bounds a POSITIVE move, and only a positive one.** `UsageBalance::admits`
+ * checks the *post-state*, so a **negative** delta — a credit memo, a metering fix — is
+ * admitted whenever the chain still holds afterwards and no counter would go below zero.
+ * From a fully reconciled `1000/1000/1000`, `bill_usage: -500` is lawful and posts. Telling
+ * a model that a reconciled balance refuses every move until fresh consumption arrives
+ * would be false, and would talk it out of a correction the ledger would have accepted —
+ * a correction this server's own input schema advertises.
+ *
+ * **The headrooms are bounds against the balance as it STANDS, and they move together
+ * inside one intent.** The moves of a single intent are judged against their *combined*
+ * post-state, so a meter move in the same intent raises what may be billed in it: at
+ * `10000/6500/4000`, `meter_usage: +3500` with `bill_usage: +6000` is admitted, even though
+ * the standing bill headroom is only `2500`. Stating the standing figure as a hard per-intent
+ * ceiling would understate the lawful bound and make the model split one commit into two.
+ */
+export function describeUsage(report) {
+    // A balance that has never been moved is `reconciled` too — vacuously, since 0 = 0 = 0.
+    // It is a different situation from a reconciled balance with real figures behind it, and
+    // the advice is different, so it is answered first. The "nothing consumed yet" statement
+    // is now carried by `report.text` itself — the ledger narrates the empty balance as unused —
+    // so this layer no longer restates it and adds only the actionable guidance.
+    if (report.consumed === 0n && report.metered === 0n && report.billed === 0n) {
+        return (`${report.text} Record consumption with \`consume_usage\` before you meter or bill ` +
+            "anything: there is nothing yet to measure or to charge for, so a positive meter or " +
+            "bill move against it would be refused.");
+    }
+    if (report.reconciled) {
+        return (`${report.text} This balance is fully reconciled: everything consumed has been metered, ` +
+            "and everything metered has been billed. There is no headroom for a POSITIVE move: " +
+            "metering or billing anything FURTHER would break the chain unless fresh consumption is " +
+            "recorded first. A NEGATIVE correction is a different matter and is still lawful — a " +
+            "credit memo or a metering fix may unwind up to " +
+            `${report.billed.toString()} minor units of billing — because the ledger checks the state ` +
+            "an intent would LEAVE BEHIND, not the state it found. It is admitted as long as no " +
+            "counter would go below zero and the chain still holds afterwards.");
+    }
+    return (`${report.text} The chain has NOT reconciled. Against the balance as it stands you may ` +
+        `meter up to ${report.unmetered.toString()} more minor units of consumption already ` +
+        `recorded, and bill up to ${report.unbilled.toString()} more minor units of usage already ` +
+        "metered. Those two bounds move together inside a single intent: its moves are judged " +
+        "against their combined post-state, so metering more in the SAME intent raises what you " +
+        "may bill in it. What is never allowed is breaking the chain — metering more than has " +
+        "been consumed is phantom usage, and billing more than has been metered is billing with " +
+        "nothing to back it. A negative correction is lawful here too, so long as no counter " +
+        "would go below zero.");
+}
+/** A plain successful result: a line of prose, then the structured payload. */
+export function renderResult(summary, payload) {
+    return {
+        content: [
+            { type: "text", text: summary },
+            { type: "text", text: toJsonText(payload) },
+        ],
+    };
+}
+/** A successful result that is prose only — nothing structured worth showing. */
+export function renderText(summary) {
+    return { content: [{ type: "text", text: summary }] };
+}
+/** Whether `operation` is a submission, whoever minted its transaction id. Pure. */
+function submits(operation) {
+    return operation !== "read";
+}
+/**
+ * What the ledger did not do, when it got the call but refused it. For a resubmission,
+ * only what this attempt did not do: see {@link Operation}.
+ */
+function nothingHappened(operation) {
+    switch (operation) {
+        case "submit":
+            return "NOTHING was recorded.";
+        case "resubmit":
+            return ("This attempt recorded nothing, but your intent MAY OR MAY NOT have been recorded: you " +
+                "supplied its transaction id, so an earlier submission under that id may have landed or " +
+                "may still commit. Do not assume it failed: read it back with get_transaction using the " +
+                "transaction id you supplied, and never submit it again under a new id, or it may post twice.");
+        case "read":
+            return "Nothing was read, and nothing was written — a read never writes.";
+    }
+}
+/**
+ * What a `421` leaves of a submission: a primary stepping down can turn the write away
+ * after proposing it, so it may still land, whoever minted the transaction id. A read
+ * writes nothing either way.
+ */
+function turnedAway(operation) {
+    return submits(operation)
+        ? "Your intent MAY OR MAY NOT have been recorded: a primary stepping down can turn a " +
+            "write away after proposing it."
+        : nothingHappened(operation);
+}
+/**
+ * What did not happen when the call never reached the ledger at all.
+ *
+ * Distinct from {@link nothingHappened}: a misconfigured server and an unexpected throw are
+ * failures *before* the wire, so the honest thing to say is that the request never left,
+ * not that the ledger declined to record it.
+ */
+function nothingLeftTheProcess(operation) {
+    return submits(operation) ? "Nothing was submitted." : "Nothing was read.";
+}
+/**
+ * A genuine failure: the ledger never got to answer, or this process is misconfigured.
+ *
+ * `isError: true`, which tells the model the *tool* malfunctioned rather than that the
+ * *spend* was denied — see the module docs on why that distinction is load-bearing.
+ *
+ * The content carries the machine-readable `code` and the **load-bearing extras**. Those
+ * extras are not decoration: without `active` no caller can re-pin, and without
+ * `primary_api_addr` none can say which replica the follower believed was primary. `@axorum/client` is hand-written
+ * precisely so they survive, and this server would be throwing that away if it rendered a
+ * bare message.
+ *
+ * `operation` is **required** rather than defaulted: a default would silently render a
+ * failed read in submit-shaped prose, which is exactly the bug it exists to prevent.
+ */
+export function renderError(error, operation) {
+    if (error instanceof ConfigurationError) {
+        return failure(`This Axorum MCP server is misconfigured, so it cannot talk to the ledger at all. ` +
+            `${nothingLeftTheProcess(operation)} This is not something you can fix by retrying or ` +
+            `by changing your request — a human has to fix the server's environment. ` +
+            `Tell them: ${error.message}`, { code: "configuration", detail: error.message });
+    }
+    if (error instanceof AxorumError) {
+        return failure(`${advice(error, operation)} (error code: ${error.code})`, details(error));
+    }
+    // Not ours, and not the ledger's — a bug here, or something the runtime threw. Say so
+    // plainly rather than dressing it up as a ledger verdict.
+    const message = error instanceof Error ? error.message : String(error);
+    return failure(`The Axorum MCP server hit an unexpected failure and could not complete the call. ` +
+        `${nothingLeftTheProcess(operation)} Report this to a human: ${message}`, { code: "unexpected", detail: message });
+}
+/** Prose telling the model what this failure means and what to do about it. */
+function advice(error, operation) {
+    const preamble = submits(operation)
+        ? "The ledger did not judge your intent"
+        : "The ledger did not answer your read";
+    if (error instanceof NotPrimaryError) {
+        return (`${preamble}: this replica is not the cluster's primary, so it turned the write away. ` +
+            `${turnedAway(operation)} ` +
+            (error.primaryApiAddr === null
+                ? "It does not know which replica is the primary. "
+                : `It named '${error.primaryApiAddr}' as the primary's API origin, a hint that may be stale. `) +
+            "Do NOT try to follow that address yourself and do NOT retry — a replica turning writes " +
+            "away is a topology change, and a human operator needs to see it. Report it and stop.");
+    }
+    if (error instanceof StalePolicyError) {
+        return (`${preamble}: the policy moved while the intent was in flight, and it kept moving — this ` +
+            `server re-pinned and resubmitted, and the policy changed again each time. ` +
+            `${nothingHappened(operation)} The policy in force was last seen as '${error.active}'. A policy rotating this ` +
+            "fast is an operational event, not something to retry into. Report it to a human.");
+    }
+    if (error instanceof TransactionReusedError) {
+        const refused = `${preamble}: the transaction id was already used for a DIFFERENT intent, so it was ` +
+            "refused and NOTHING was recorded. A transaction id names exactly one intent. For a new " +
+            "intent, submit again WITHOUT a transaction id and one is minted for you.";
+        // No hashes means the id was committed by another party: there is nothing of
+        // this agent's to read back under it.
+        return error.storedContentHash === undefined
+            ? `${refused} The id belongs to a transaction another party committed.`
+            : `${refused} To read what the original transaction did, use get_transaction with ` +
+                "the id below.";
+    }
+    if (error instanceof CommitUnavailableError) {
+        return ("The cluster could not confirm the commit, so your intent MAY OR MAY NOT have been " +
+            "recorded — this is the one genuinely ambiguous outcome. Do not assume it failed and do " +
+            "not assume it succeeded. Read it back with get_transaction using the transaction id " +
+            "below; if it is there, it landed. Retrying the identical intent under the same " +
+            "transaction id is also safe: the id is the ledger's idempotency key, so a retry replays " +
+            "the stored outcome rather than posting twice.");
+    }
+    if (error instanceof UnknownAgentError) {
+        return (`${preamble}: the ledger does not recognise the agent identity this server acts under, so ` +
+            `it was refused at the door. ${nothingHappened(operation)} This is a setup problem, not ` +
+            "something your request can fix — a human has to bind this agent's URI to a party in the " +
+            "ledger's registry. Report it and stop.");
+    }
+    if (error instanceof AttestationError) {
+        return (`${preamble}: the ledger rejected this server's capability attestation — it is expired, ` +
+            "signed by an issuer the ledger does not trust, or does not grant the capability this " +
+            `action needs. ${nothingHappened(operation)} A human has to mint a valid attestation; ` +
+            "retrying will not help. Report it and stop.");
+    }
+    if (error.body?.cause === "undeclared_currency") {
+        const codes = error.body.currencies ?? [];
+        const named = codes.length > 0 ? codes.map((code) => `'${code}'`).join(", ") : "a currency";
+        return (`${preamble}: it names ${named}, which this ledger's operator has not declared, so the ` +
+            `ledger cannot read its amounts. ${nothingHappened(operation)} You cannot declare a ` +
+            "currency, and retrying will not help. Either use a currency the ledger already holds, " +
+            "or report this to a human operator with the command the ledger gave: " +
+            `${error.message}`);
+    }
+    if (submits(operation) && error.code === "idempotency_seed_refused" && error.wroteNothing) {
+        return (`${preamble}: the ledger refused the primary's idempotency seed, so the primary turns ` +
+            `every submission away before proposing it, until an operator fails it over. ` +
+            `${nothingHappened(operation)} Retrying will not help until then, under this id or any ` +
+            `other. Report it to a human operator: ${error.message}`);
+    }
+    if (error.code === "quarantined" && error.status === 503) {
+        return (`${preamble}: this ledger node found a divergence when it verified its own history, and ` +
+            `refuses every request until an operator resolves it. ${nothingHappened(operation)} ` +
+            `Retrying will not help until then. Report it to a human operator: ${error.message}`);
+    }
+    // An answer that recorded nothing says so, for a minted id as for the id alone; for a
+    // supplied one it speaks for this attempt only (see `Operation`).
+    const proven = submits(operation) && error.wroteNothing ? ` ${nothingHappened(operation)}` : "";
+    if (error.isRetriable) {
+        return submits(operation)
+            ? `${preamble}: ${error.message}${proven} Retrying is safe — the transaction id is the ` +
+                "ledger's idempotency key, so a retry either lands it once or replays the outcome it " +
+                "already has. It cannot double-post."
+            : `${preamble}: ${error.message} Retrying is safe — a read changes nothing, whether it ` +
+                "succeeds or fails.";
+    }
+    return submits(operation)
+        ? `${preamble}: ${error.message}${proven} Retrying this unchanged will not help.`
+        : `${preamble}: ${error.message} Retrying this unchanged will not help, and nothing was ` +
+            "written — a read never writes. If the id was refused as unknown, that may mean it does " +
+            "not exist OR that it is not yours to read; the ledger deliberately does not say which, " +
+            "so do not conclude it is absent.";
+}
+/**
+ * The structured detail for a failure, extras intact.
+ *
+ * Built by hand rather than by serializing the error object, because an `Error`'s own
+ * enumerable properties are not its interesting ones — the interesting ones are the typed
+ * fields the client lifted out of the wire body.
+ */
+function details(error) {
+    const detail = {
+        code: error.code,
+        message: error.message,
+        status: error.status,
+        retriable: error.isRetriable,
+        requires_repin: error.requiresRepin,
+    };
+    if (error instanceof NotPrimaryError) {
+        detail["primary_api_addr"] = error.primaryApiAddr;
+        detail["reason"] = error.reason;
+    }
+    if (error instanceof StalePolicyError) {
+        detail["pinned"] = error.pinned;
+        detail["active"] = error.active;
+    }
+    if (error instanceof CommitUnavailableError) {
+        detail["reason"] = error.reason;
+    }
+    if (error instanceof ApiError && error.retryAfterMs !== null) {
+        detail["retry_after_ms"] = error.retryAfterMs;
+    }
+    if (error instanceof UnknownAgentError) {
+        detail["uri"] = error.uri;
+    }
+    if (error instanceof TransactionReusedError && error.storedContentHash !== undefined) {
+        detail["stored_content_hash"] = error.storedContentHash;
+        detail["submitted_content_hash"] = error.submittedContentHash;
+    }
+    // The service's own body, whenever there was one: it may carry extras a newer service
+    // invented that this client has no typed field for, and dropping them would be exactly
+    // the flattening `@axorum/client` exists to avoid.
+    if (error.body !== null) {
+        detail["body"] = error.body;
+    }
+    return detail;
+}
+/** An `isError` result: the prose, then the structured detail. */
+function failure(summary, detail) {
+    return {
+        isError: true,
+        content: [
+            { type: "text", text: summary },
+            { type: "text", text: toJsonText(detail) },
+        ],
+    };
+}
+//# sourceMappingURL=render.js.map