@trazum/cli 1.50.2 → 1.50.4

package/dist/gateway-server.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The proxy that stands in the path, and does as little as possible there.
+ *
+ * The decision lives in `@trazum/core`'s `gatewayDecision`, which never sees a
+ * prompt and cannot return a modified request. This file moves bytes: read a
+ * body, ask, and either forward it **unchanged** or answer with the refusal.
+ * The split is the safety property — everything that could go wrong in a
+ * judgement is tested without a socket, and everything that could go wrong on
+ * a socket has no judgement in it.
+ *
+ * **Loopback only, and the address is not a flag.** Same posture as `serve`
+ * since 1.44, and more load-bearing here: this thing has somebody's provider
+ * credential passing through it. `127.0.0.1` is compiled in.
+ *
+ * **The credential is not even borrowed.** The caller's own `authorization`
+ * and `x-api-key` headers are forwarded untouched and never read, never
+ * stored, never logged, and never put in a URL. Trazum holds no key for the
+ * gateway and has no way to make a call of its own through it — which is a
+ * stronger promise than the connector's *borrowed, never held*, and the right
+ * one for a component sitting between somebody and their provider.
+ *
+ * **The upstream is compiled in.** A flag naming the host would turn this into
+ * a credential-forwarding open proxy: anything that could rewrite a config on
+ * disk could point a company's API key at a machine it chose. `checkedEndpoint`
+ * has guarded Trazum's outbound calls on that principle since 1.14, and here
+ * there is no caller-supplied endpoint at all.
+ *
+ * **Nothing about the payload is written down.** The body is read to count
+ * tokens and to find the model, then forwarded and dropped. It is never
+ * logged, never stored, and never included in a refusal — the store has held
+ * aggregates since 1.42 and standing in the path changes nothing about that.
+ */
+import type { Server } from 'node:http';
+import type { GatewayPolicy, GatewayStanding, PricingCatalogue } from '@trazum/core';
+/** Compiled in. See the module note. */
+export declare const BIND_HOST = "127.0.0.1";
+export declare const DEFAULT_GATEWAY_PORT = 7318;
+/**
+ * Bodies larger than this are refused unread.
+ *
+ * Larger than `serve`'s limit because a real request carries a real prompt,
+ * and smaller than unbounded because a proxy that buffers whatever it is
+ * handed is a memory exhaustion away from taking down the application it was
+ * installed to protect.
+ */
+export declare const MAX_GATEWAY_BODY_BYTES: number;
+/**
+ * Where each provider actually is, and the one path this speaks for it.
+ *
+ * Deliberately narrow. A gateway that forwarded any path would be a general
+ * proxy for somebody's API key, and the budget decision only has meaning for
+ * the endpoint that spends tokens.
+ */
+export declare const UPSTREAMS: Readonly<Record<string, {
+    origin: string;
+    path: string;
+}>>;
+export interface GatewayContext {
+    provider: string;
+    catalogue: PricingCatalogue;
+    policy: GatewayPolicy;
+    /** Where the budget stands, refreshed by the caller — never read per request. */
+    standing: () => GatewayStanding | null;
+    /**
+     * Called after a forwarded call returns, with the provider's own counts.
+     *
+     * Counts only. There is no parameter here that could carry a prompt, which
+     * is what makes "nothing about the payload is written down" a fact about the
+     * interface rather than a discipline.
+     */
+    record: (measured: {
+        model: string;
+        label: string | null;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        substituted: boolean;
+    }) => void;
+    /** A line for the operator's terminal. Never given a body, ever. */
+    note: (line: string) => void;
+    /** Injected so the proxy is testable against a stub upstream. */
+    fetchImpl?: typeof fetch;
+}
+export declare function buildGateway(context: GatewayContext): Server;
+export declare function listenGateway(server: Server, where: {
+    port: number;
+} | {
+    socket: string;
+}): Promise<string>;
+//# sourceMappingURL=gateway-server.d.ts.map

package/dist/gateway-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-server.d.ts","sourceRoot":"","sources":["../src/gateway-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAmB,MAAM,EAAkB,MAAM,WAAW,CAAC;AAEzE,OAAO,KAAK,EAAmB,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEtG,wCAAwC;AACxC,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,QAAkB,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAGhF,CAAC;AAmBF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,eAAe,GAAG,IAAI,CAAC;IACvC;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,OAAO,CAAC;KACtB,KAAK,IAAI,CAAC;IACX,oEAAoE;IACpE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA+FD,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAgI5D;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,MAAM,CAAC,CAajB"}

package/dist/gateway-server.js

@@ -0,0 +1,290 @@
+/**
+ * The proxy that stands in the path, and does as little as possible there.
+ *
+ * The decision lives in `@trazum/core`'s `gatewayDecision`, which never sees a
+ * prompt and cannot return a modified request. This file moves bytes: read a
+ * body, ask, and either forward it **unchanged** or answer with the refusal.
+ * The split is the safety property — everything that could go wrong in a
+ * judgement is tested without a socket, and everything that could go wrong on
+ * a socket has no judgement in it.
+ *
+ * **Loopback only, and the address is not a flag.** Same posture as `serve`
+ * since 1.44, and more load-bearing here: this thing has somebody's provider
+ * credential passing through it. `127.0.0.1` is compiled in.
+ *
+ * **The credential is not even borrowed.** The caller's own `authorization`
+ * and `x-api-key` headers are forwarded untouched and never read, never
+ * stored, never logged, and never put in a URL. Trazum holds no key for the
+ * gateway and has no way to make a call of its own through it — which is a
+ * stronger promise than the connector's *borrowed, never held*, and the right
+ * one for a component sitting between somebody and their provider.
+ *
+ * **The upstream is compiled in.** A flag naming the host would turn this into
+ * a credential-forwarding open proxy: anything that could rewrite a config on
+ * disk could point a company's API key at a machine it chose. `checkedEndpoint`
+ * has guarded Trazum's outbound calls on that principle since 1.14, and here
+ * there is no caller-supplied endpoint at all.
+ *
+ * **Nothing about the payload is written down.** The body is read to count
+ * tokens and to find the model, then forwarded and dropped. It is never
+ * logged, never stored, and never included in a refusal — the store has held
+ * aggregates since 1.42 and standing in the path changes nothing about that.
+ */
+import { createServer } from 'node:http';
+import { estimateTokens, gatewayDecision, usageFromResponse } from '@trazum/core';
+/** Compiled in. See the module note. */
+export const BIND_HOST = '127.0.0.1';
+export const DEFAULT_GATEWAY_PORT = 7318;
+/**
+ * Bodies larger than this are refused unread.
+ *
+ * Larger than `serve`'s limit because a real request carries a real prompt,
+ * and smaller than unbounded because a proxy that buffers whatever it is
+ * handed is a memory exhaustion away from taking down the application it was
+ * installed to protect.
+ */
+export const MAX_GATEWAY_BODY_BYTES = 8 * 1024 * 1024;
+/**
+ * Where each provider actually is, and the one path this speaks for it.
+ *
+ * Deliberately narrow. A gateway that forwarded any path would be a general
+ * proxy for somebody's API key, and the budget decision only has meaning for
+ * the endpoint that spends tokens.
+ */
+export const UPSTREAMS = {
+    anthropic: { origin: 'https://api.anthropic.com', path: '/v1/messages' },
+    openai: { origin: 'https://api.openai.com', path: '/v1/chat/completions' },
+};
+/**
+ * Headers Trazum adds or removes. Everything else the caller sent is forwarded
+ * verbatim, including their credential, which this never reads.
+ */
+const HOP_BY_HOP = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    'host',
+    'content-length',
+]);
+async function readBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.from(chunk);
+        size += buffer.length;
+        if (size > MAX_GATEWAY_BODY_BYTES)
+            return null;
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * What the request is asking for, without keeping any of it.
+ *
+ * The token count is the heuristic estimator's — the same one every other
+ * estimate in this product uses, with the same documented error band. Counting
+ * exactly would mean an API call to count before the API call, which is a
+ * round trip in a hot path to make a budget decision marginally sharper.
+ *
+ * The returned object holds no text. That is the point: everything downstream
+ * of here, including the decision and the record, is structurally incapable of
+ * carrying a prompt.
+ */
+function describe(body, provider) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const request = parsed;
+    if (typeof request.model !== 'string')
+        return null;
+    // Every text field the wire format puts in front of the model, counted and
+    // then dropped. `JSON.stringify` of the messages over-counts by the
+    // structural characters, which is the safe direction for a budget: an
+    // estimate that runs high refuses slightly early rather than allowing
+    // slightly late.
+    const parts = [];
+    if (typeof request.system === 'string')
+        parts.push(request.system);
+    if (Array.isArray(request.messages))
+        parts.push(JSON.stringify(request.messages));
+    if (Array.isArray(request.input))
+        parts.push(JSON.stringify(request.input));
+    const text = parts.join('\n');
+    const max = provider === 'anthropic' ? request.max_tokens : request.max_completion_tokens ?? request.max_tokens;
+    return {
+        model: request.model,
+        inputTokens: text === '' ? null : estimateTokens(text),
+        maxOutputTokens: typeof max === 'number' && Number.isFinite(max) ? max : null,
+        /**
+         * `metadata.trazum_label`, and nothing inferred.
+         *
+         * A label is what makes a per-workload bill possible, and guessing one
+         * from a path or a user agent would attribute somebody's spend to a
+         * workload they never named.
+         */
+        label: labelOf(request),
+    };
+}
+function labelOf(request) {
+    const metadata = request.metadata;
+    if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata))
+        return null;
+    const label = metadata.trazum_label;
+    return typeof label === 'string' && label.trim() !== '' ? label : null;
+}
+/** The refusal, as the caller's SDK will receive it. */
+function refusalBody(decision) {
+    return `${JSON.stringify({
+        schemaVersion: 1,
+        error: { type: 'trazum_budget_refusal', message: decision.because },
+        reason: decision.reason,
+        cause: decision.cause,
+        restsOn: decision.restsOn,
+        standing: decision.standing,
+        estimatedUsd: decision.estimatedUsd,
+        alternatives: decision.alternatives,
+    }, null, 2)}\n`;
+}
+export function buildGateway(context) {
+    const upstream = UPSTREAMS[context.provider];
+    const doFetch = context.fetchImpl ?? fetch;
+    return createServer((request, response) => {
+        void (async () => {
+            if (upstream === undefined) {
+                response.writeHead(500, { 'content-type': 'application/json' });
+                response.end(`${JSON.stringify({ error: 'no upstream configured for this provider' })}\n`);
+                return;
+            }
+            if (request.method !== 'POST' || request.url !== upstream.path) {
+                // Only the one path that spends tokens. A gateway forwarding anything
+                // else is a general proxy for somebody's API key.
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(`${JSON.stringify({ error: 'not a path this gateway forwards' })}\n`);
+                return;
+            }
+            const body = await readBody(request);
+            if (body === null) {
+                response.writeHead(413, { 'content-type': 'application/json' });
+                response.end(`${JSON.stringify({ error: 'request body too large' })}\n`);
+                return;
+            }
+            const described = describe(body, context.provider);
+            if (described === null) {
+                response.writeHead(400, { 'content-type': 'application/json' });
+                response.end(`${JSON.stringify({ error: 'could not read a model out of this request' })}\n`);
+                return;
+            }
+            const decision = gatewayDecision({ provider: context.provider, ...described }, context.standing(), { catalogue: context.catalogue, policy: context.policy });
+            if (decision.kind === 'refuse') {
+                /**
+                 * **402, deliberately, and never 429.**
+                 *
+                 * Every provider SDK retries a 429 automatically — that is what the
+                 * code means to them — so answering a budget refusal with one turns a
+                 * single refusal into a retry storm against a gateway that will refuse
+                 * every time. 402 Payment Required is both literally correct and in
+                 * nobody's default retry list.
+                 */
+                response.writeHead(402, { 'content-type': 'application/json' });
+                response.end(refusalBody(decision));
+                context.note(`refused ${described.model}: ${decision.reason}`);
+                return;
+            }
+            const outgoing = new Headers();
+            for (const [name, value] of Object.entries(request.headers)) {
+                if (HOP_BY_HOP.has(name.toLowerCase()) || value === undefined)
+                    continue;
+                outgoing.set(name, Array.isArray(value) ? value.join(', ') : value);
+            }
+            /**
+             * The body forwarded is the body received, **byte for byte**, except on
+             * a configured substitution — which replaces exactly one field and says
+             * so in the record.
+             */
+            let forwarded = body;
+            if (decision.kind === 'substitute') {
+                const parsed = JSON.parse(body);
+                parsed.model = decision.to.id;
+                forwarded = JSON.stringify(parsed);
+                context.note(`substituted ${described.model} → ${decision.to.id}: ${decision.configuredReason}`);
+            }
+            else if (decision.unjudged !== null) {
+                context.note(`forwarded unjudged (${decision.unjudged}): fail-open`);
+            }
+            let upstreamResponse;
+            try {
+                upstreamResponse = await doFetch(`${upstream.origin}${upstream.path}`, {
+                    method: 'POST',
+                    headers: outgoing,
+                    body: forwarded,
+                });
+            }
+            catch (error) {
+                /**
+                 * The upstream is unreachable. This is **not** a budget refusal and
+                 * must not look like one: the caller needs to tell "your provider is
+                 * down" from "you are out of money", and a proxy that blurs them sends
+                 * somebody to fix the wrong thing.
+                 */
+                response.writeHead(502, { 'content-type': 'application/json' });
+                response.end(`${JSON.stringify({
+                    error: { type: 'trazum_upstream_unreachable', message: error instanceof Error ? error.message : String(error) },
+                })}\n`);
+                return;
+            }
+            const text = await upstreamResponse.text();
+            // Measured at the moment of the call, from the provider's own counts —
+            // the reason this beats a connector, which reports the runaway after it
+            // ran. Counts only reach `record`; the body is dropped here.
+            let measured;
+            try {
+                measured = JSON.parse(text);
+            }
+            catch {
+                measured = null;
+            }
+            const usage = usageFromResponse(context.provider, measured);
+            if (usage !== null) {
+                context.record({
+                    model: decision.kind === 'substitute' ? decision.to.id : described.model,
+                    label: described.label,
+                    substituted: decision.kind === 'substitute',
+                    ...usage,
+                });
+            }
+            const back = {};
+            upstreamResponse.headers.forEach((value, name) => {
+                if (!HOP_BY_HOP.has(name.toLowerCase()))
+                    back[name] = value;
+            });
+            response.writeHead(upstreamResponse.status, back);
+            response.end(text);
+        })();
+    });
+}
+export function listenGateway(server, where) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        if ('socket' in where) {
+            server.listen(where.socket, () => resolve(where.socket));
+            return;
+        }
+        server.listen(where.port, BIND_HOST, () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address !== null ? address.port : where.port;
+            resolve(`http://${BIND_HOST}:${port}`);
+        });
+    });
+}
+//# sourceMappingURL=gateway-server.js.map

package/dist/gateway-server.js.map

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

package/dist/i18n/en.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,EAAE,WA89DhB,CAAC"}
+{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,EAAE,WAmiEhB,CAAC"}

package/dist/i18n/en.js

@@ -48,6 +48,7 @@ ${bold('USAGE')}
   trazum conform <file|-> [--contract <name>]
   trazum models
   trazum rules
+  trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
   trazum feedback
   trazum --version
 
@@ -92,6 +93,22 @@ ${bold('OPTIONS FOR feedback')}
   anonymous counter, and a test fails the build if this command ever reaches
   the network.
 
+${bold('OPTIONS FOR gateway')}
+  --on-cannot-tell <policy>   Required, no default: fail-open or fail-closed.
+                              What happens when the gateway cannot judge a call
+                              — no budget, nothing measured, an unpriced model.
+  --port <n> | --socket <p>   Where to listen. Loopback only, always.
+
+  Stands between your SDK and the provider, speaking their wire format, so no
+  code changes. Usage is measured from the provider's own response as it comes
+  back — no export, no connector lag, no missing day.
+
+  It refuses and never substitutes: a call over budget gets HTTP 402 with the
+  cheaper alternatives named. Substitution happens only where you wrote it down
+  in spend.substitute, with your reason, and every substituted call is marked.
+
+  Your credential is forwarded untouched and never read. See docs/gateway.md.
+
 ${bold('OPTIONS FOR prune')}
   --cases <file>              One input per line, or a JSON array. Required.
   --yes                       Actually spend the calls. Without it the estimate is
@@ -571,6 +588,13 @@ ${bold('CONFIG FILE')}
     spend     { "maxUsd": 200, "byLabel": { "chat": 40 } } — money budgets for
               "trazum profile", in dollars. A budgeted label with no calls in
               the log is reported as not measured, never as a pass
+    outcomes  { "values": ["resolved", "escalated"], "success": ["resolved"] } —
+              your own vocabulary for what happened, and which of it counts as
+              a win. Both required: which words mean success is a judgement
+              about your product rather than your bill, and this tool has no
+              standing to make it. Use [] if none of them are successes. A
+              value in a log that "values" never declares is named as
+              undeclared, never counted as a failure
     waive     [{ "gate": "maxUsd", "reason": "August migration", "until":
               "2026-09-15" }] — a gate failure decided about, on the record.
               All three fields required: a waiver with no end date is a
@@ -840,6 +864,22 @@ ${bold('EXAMPLES')}
         existingRefused: (path) => `${path} already exists and was left alone. Pass --dry-run to see what would go in it, or --yes to replace it.`,
         existingUnparseable: (path) => `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
     },
+    gateway: {
+        badProvider: (given, known) => given === ''
+            ? `Name the provider to stand in front of. Known: ${known}.`
+            : `"${given}" is not a provider this gateway speaks for. Known: ${known}.`,
+        needsPolicy: (policies) => `--on-cannot-tell is required, and there is no default: ${policies}. When the gateway cannot judge a call — no budget, nothing measured, an unpriced model — one of these happens, and only you know which failure your product can survive. fail-open keeps it working and lets the bill run; fail-closed stops the bill and takes it down with it. Picking one for you would be the most consequential decision in your architecture, made silently at install time.`,
+        listening: (where, provider) => `Gateway on ${where}, in front of ${provider}`,
+        pointYourSdk: (where) => `Point your SDK's base URL at ${where} and change nothing else. It speaks the provider's own wire format, so no code changes and no new client.`,
+        credential: () => 'Your credential is forwarded untouched and never read, never stored, never logged and never put in a URL. Trazum holds no key here and cannot make a call of its own through this.',
+        neverSubstitutes: () => 'A call over budget is refused with HTTP 402 and the cheaper alternatives named — never silently swapped, trimmed or downgraded. 402 rather than 429 on purpose: every provider SDK retries a 429, which would turn one refusal into a retry storm.',
+        standing: (consumed, limit) => `Judging against ${consumed} of ${limit}, measured, read once at start — a file read in the request path would put this tool's latency between you and your provider on every call.`,
+        noStanding: () => 'Nothing measured for this period, so every call is unjudged and the failure policy below decides. Set spend.monthlyUsd and pull with trazum connect.',
+        policy: (policy) => policy === 'fail-open'
+            ? 'When it cannot judge: the call goes through, and the record says it was unjudged rather than within budget.'
+            : 'When it cannot judge: the call is refused. Nothing gets through unmeasured.',
+        measured: (model, label, input, output, substituted) => `  ${model}${label === null ? '' : ` [${label}]`}: ${input} in, ${output} out${substituted ? ' (substituted — marked, and never counted as the call that was asked for)' : ''}`,
+    },
     feedback: {
         heading: () => 'Telling us something',
         sendsNothing: () => 'This command sends nothing, and neither does anything else here. Trazum has no telemetry: no ping, no install hook, no anonymous counter. A tool whose whole argument is that it reads your bill without uploading it cannot also be quietly reporting on you, and a test fails the build if this command ever reaches the network.',
@@ -1287,6 +1327,19 @@ ${bold('EXAMPLES')}
         fleetBudgetMissing: (name) => `${name} has a budget in spend.bySource and no logs matched it in this run, so nothing was measured for it. Not a pass: a service that did not appear is not a service under budget.`,
         coverageHeading: () => 'What this log cannot answer yet',
         needsLabel: (seen) => `"label" on ${seen} records: without it every workload is one row, so no per-workload spend, no drill-down, and the levers describe a mixture rather than a decision.`,
+        needsOutcome: (seen) => `an "outcome" — ${seen}. The one field that changes what every other figure here means: without it this tool can say a workload got 40% cheaper and cannot say whether it stopped working. Record your own word for what happened and declare the vocabulary under "outcomes".`,
+        dryRunOutcomes: (share) => `cost per outcome and a success rate (${share} of records carry an "outcome")`,
+        outcomeHeading: () => 'Outcomes',
+        outcomeRate: (rate, ofUsd) => `${rate} of ${ofUsd} in declared outcomes succeeded \u2014 by spend rather than by call, because the two diverge exactly when the expensive half is the half that fails.`,
+        outcomeNoRate: (why) => why === 'nothing-recorded'
+            ? 'No success rate: nothing in this log recorded an outcome. That is not a rate of zero \u2014 a rate of zero is a real and terrible measurement, and this is nobody having told us.'
+            : 'No success rate: "outcomes.success" declares no values, so nothing here counts as one. A legitimate thing to declare, and it means the rate is not this tool\u2019s to compute.',
+        outcomeUnrecorded: (share, usd) => `${share} of the bill (${usd}) carried no outcome, and is in neither half of the rate above.`,
+        outcomeUndeclared: (values) => `Not declared in "outcomes.values": ${values}. Named rather than counted as failures \u2014 a typo in an exporter should look like a typo, not like a product regression.`,
+        outcomeColumns: { outcome: 'outcome', calls: 'calls', spend: 'spend' },
+        verdictSuccess: () => 'success',
+        verdictOther: () => '\u2014',
+        verdictUndeclared: () => 'undeclared',
         needsSession: (seen) => `"session" on ${seen} records: without it there is no conversation growth, no per-conversation cost, and no cache-TTL fit. It is grouped by and never printed.`,
         needsTs: (seen) => `"ts" on ${seen} records: without it the log has no period, no per-day or per-hour shape, and the cache-TTL question cannot be asked at all.`,
         needsStopReason: (seen) => `"stop_reason" (Anthropic) or "finish_reason" (OpenAI) on ${seen} records: without it, answers cut off at max_tokens are invisible — and silence there is not the same as none.`,