@basein/runner 0.1.0

package/dist/record/recorder.js

@@ -0,0 +1,39 @@
+/**
+ * Recorder — the surface both tiers use (§5).
+ *
+ * Deliberately identical in shape to RRepeat's `RemoteRecorder`, so the BaseIn
+ * service needs no new endpoints for v1: a BaseInstRunner run is the same row
+ * shape as an RRepeat one, discriminated only by `metadata.recorder`.
+ */
+export function isMatchAware(r) {
+    return typeof r.getMatch === "function";
+}
+export function isScenarioReporter(r) {
+    return typeof r.reportExecution === "function";
+}
+/**
+ * A recorder that drops everything. Used when auth is unavailable: recording is
+ * best-effort, and a session must never fail because BaseIn is unreachable (§10).
+ */
+export class NullRecorder {
+    n = 0;
+    startRun() {
+        return `run_local_${++this.n}`;
+    }
+    recordToolSelected() {
+        return `step_local_${++this.n}`;
+    }
+    recordToolResponse() {
+        return `step_local_${++this.n}`;
+    }
+    recordFinalAnswer() {
+        return `step_local_${++this.n}`;
+    }
+    finishRun() {
+        /* nothing to do */
+    }
+    async flush() {
+        /* nothing to await */
+    }
+}
+//# sourceMappingURL=recorder.js.map

package/dist/record/redact.d.ts

@@ -0,0 +1,37 @@
+/**
+ * redact — scrub secret material before anything leaves the process (Phase 4.3).
+ *
+ * The proxy sits on the credential path for every wrapped server (§9), and every
+ * argument and result it sees crosses a process boundary and then the network.
+ * So redaction runs on the recording copy of both arguments *and* results,
+ * before the step report is even queued.
+ *
+ * Three rules, in the order they fire:
+ *   1. **By key.** A value under a key matching {@link SECRET_KEY} is replaced
+ *      wholesale, whatever its type. `authorization: { scheme, token }` loses
+ *      both halves, because the object as a whole is the secret.
+ *   2. **`env` blocks.** An object under an `env` key has *every* value replaced.
+ *      MCP server configs put credentials there under arbitrary names, so no key
+ *      pattern would catch them.
+ *   3. **By shape.** A string that looks like a bearer token, a JWT, an
+ *      `sk-`/`ghp_`-style key or an AWS access key id is replaced wherever it
+ *      appears — including inside free text, where key-matching cannot reach.
+ *
+ * Redaction never throws and never mutates its input: a cycle, a `BigInt`, a
+ * getter that explodes — each degrades to a placeholder rather than losing the
+ * step or, worse, taking the session down.
+ */
+export declare const REDACTED = "[redacted]";
+/** Keys whose values are secret regardless of shape. */
+export declare const SECRET_KEY: RegExp;
+/** Replace every secret-shaped run inside a string. */
+export declare function redactText(text: string): string;
+/**
+ * Deep-clone `value` with secrets removed. The result is always JSON-safe, so
+ * the caller can serialise it without a second failure mode.
+ *
+ * @param value    anything, including cyclic structures.
+ * @param maxDepth guard against pathological nesting (default 24).
+ */
+export declare function redact(value: unknown, maxDepth?: number): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/record/redact.js

@@ -0,0 +1,119 @@
+/**
+ * redact — scrub secret material before anything leaves the process (Phase 4.3).
+ *
+ * The proxy sits on the credential path for every wrapped server (§9), and every
+ * argument and result it sees crosses a process boundary and then the network.
+ * So redaction runs on the recording copy of both arguments *and* results,
+ * before the step report is even queued.
+ *
+ * Three rules, in the order they fire:
+ *   1. **By key.** A value under a key matching {@link SECRET_KEY} is replaced
+ *      wholesale, whatever its type. `authorization: { scheme, token }` loses
+ *      both halves, because the object as a whole is the secret.
+ *   2. **`env` blocks.** An object under an `env` key has *every* value replaced.
+ *      MCP server configs put credentials there under arbitrary names, so no key
+ *      pattern would catch them.
+ *   3. **By shape.** A string that looks like a bearer token, a JWT, an
+ *      `sk-`/`ghp_`-style key or an AWS access key id is replaced wherever it
+ *      appears — including inside free text, where key-matching cannot reach.
+ *
+ * Redaction never throws and never mutates its input: a cycle, a `BigInt`, a
+ * getter that explodes — each degrades to a placeholder rather than losing the
+ * step or, worse, taking the session down.
+ */
+export const REDACTED = "[redacted]";
+/** Keys whose values are secret regardless of shape. */
+export const SECRET_KEY = /(token|secret|password|passwd|api[_-]?key|apikey|authorization|auth|cookie|session[_-]?id|credential|private[_-]?key|access[_-]?key|client[_-]?secret)/i;
+/** Keys whose *children* are all secret (values only — the names stay). */
+const ENV_KEY = /^env(ironment)?$/i;
+/** Value shapes that are secret wherever they appear, including inside prose. */
+const SECRET_SHAPES = [
+    /\bBearer\s+[A-Za-z0-9\-._~+/]+=*/gi, // Authorization header value
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*/g, // JWT
+    /\bsk-[A-Za-z0-9_-]{16,}/g, // OpenAI / Anthropic style
+    /\bgh[pousr]_[A-Za-z0-9]{16,}/g, // GitHub tokens
+    /\bxox[abposr]-[A-Za-z0-9-]{10,}/g, // Slack tokens
+    /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key id
+    /\b(?:AIza)[0-9A-Za-z_-]{20,}/g, // Google API key
+];
+/** Replace every secret-shaped run inside a string. */
+export function redactText(text) {
+    let out = text;
+    for (const shape of SECRET_SHAPES) {
+        shape.lastIndex = 0;
+        out = out.replace(shape, REDACTED);
+    }
+    return out;
+}
+/**
+ * Deep-clone `value` with secrets removed. The result is always JSON-safe, so
+ * the caller can serialise it without a second failure mode.
+ *
+ * @param value    anything, including cyclic structures.
+ * @param maxDepth guard against pathological nesting (default 24).
+ */
+export function redact(value, maxDepth = 24) {
+    return walk(value, undefined, 0, maxDepth, new WeakSet());
+}
+function walk(value, key, depth, maxDepth, seen) {
+    if (key !== undefined && SECRET_KEY.test(key))
+        return REDACTED;
+    if (value === null || value === undefined)
+        return value ?? null;
+    switch (typeof value) {
+        case "string":
+            return redactText(value);
+        case "number":
+            return Number.isFinite(value) ? value : String(value);
+        case "boolean":
+            return value;
+        case "bigint":
+            return value.toString();
+        case "function":
+        case "symbol":
+            return `[${typeof value}]`;
+        default:
+            break;
+    }
+    if (depth >= maxDepth)
+        return "[max depth]";
+    const obj = value;
+    if (seen.has(obj))
+        return "[circular]";
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            return obj.map((item) => walk(item, undefined, depth + 1, maxDepth, seen));
+        }
+        if (obj instanceof Date)
+            return obj.toISOString();
+        if (obj instanceof Error)
+            return { name: obj.name, message: redactText(obj.message) };
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (SECRET_KEY.test(k)) {
+                out[k] = REDACTED;
+            }
+            else if (ENV_KEY.test(k) && v && typeof v === "object" && !Array.isArray(v)) {
+                // Rule 2: an env block's names are useful, its values never are.
+                const env = {};
+                for (const name of Object.keys(v))
+                    env[name] = REDACTED;
+                out[k] = env;
+            }
+            else {
+                out[k] = walk(v, k, depth + 1, maxDepth, seen);
+            }
+        }
+        return out;
+    }
+    catch {
+        // A throwing getter or an exotic proxy. One step's fidelity is not worth a
+        // crash on the recording path.
+        return "[unreadable]";
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+//# sourceMappingURL=redact.js.map

package/dist/record/remote-recorder.d.ts

@@ -0,0 +1,110 @@
+/**
+ * RemoteRecorder — streams each step to the BaseIn auth-service (Phase 4.2).
+ *
+ * Ported unchanged in shape from RRepeat's `server/remote-recorder.ts`, so the
+ * already-live endpoints need no v1 changes:
+ *   POST  /recordings/runs
+ *   POST  /recordings/runs/:id/steps
+ *   PATCH /recordings/runs/:id/steps/:stepId
+ *   POST  /recordings/runs/:id/finish
+ *
+ * Four properties matter, and each is load-bearing:
+ *   - **Client-generated ids** (`run_`/`step_` uuids) so callers get an id
+ *     synchronously and never await the network on the hot path.
+ *   - **One ordered promise chain per run**, so steps arrive in the order they
+ *     were recorded even though every send is fire-and-forget.
+ *   - **Best-effort.** A failed send is logged and dropped, never retried inline
+ *     and never thrown at the caller (§10).
+ *   - **One token refresh on 401**, then one retry. Sessions outlive access tokens.
+ *
+ * SIMILAR-PROMPT HITS. `POST /recordings/runs` may answer `{ id: null, matched }`,
+ * meaning the server recognised the prompt and did **not** create a run. Every
+ * later step post for that id would then 404, so callers must stop recording —
+ * {@link RemoteRecorder.getMatch} is how they find out. v1 only stops; replay is v2.
+ */
+import { type AuthSession } from "../auth/client.js";
+import type { ExecutionReport, Recorder, RunMatch, RunMetrics } from "./recorder.js";
+export interface RemoteRecorderOptions {
+    baseUrl: string;
+    session: AuthSession;
+    /** Value for the run's `framework` column. Defaults to `baseinstrunner`. */
+    framework?: string;
+}
+export declare class RemoteRecorder implements Recorder {
+    private readonly baseUrl;
+    private readonly framework;
+    private session;
+    /** runId → tail of that run's ordered send chain. */
+    private readonly chains;
+    /** runId → the similar-prompt outcome of its create call. */
+    private readonly matches;
+    /**
+     * Execution reports ride their own chain: a matched turn has no run on the
+     * service (that is what a match means), so there is no run chain to append to.
+     */
+    private readonly executionChainKey;
+    constructor(opts: RemoteRecorderOptions);
+    startRun(input: string, metadata?: Record<string, unknown>): string;
+    /** Await the similar-prompt match for a run's create call (null = fresh run). */
+    getMatch(runId: string): Promise<RunMatch | null>;
+    recordToolSelected(runId: string, stepIndex: number, data: {
+        toolName: string;
+        toolInput: string;
+        context?: string;
+    }): string;
+    recordToolResponse(runId: string, stepIndex: number, data: {
+        toolName: string;
+        toolOutput?: string;
+        toolError?: string;
+    }): string;
+    recordFinalAnswer(runId: string, stepIndex: number, data: {
+        answer: string;
+    }): string;
+    /** Backfill a step's `context` (the model's reasoning) after the fact. */
+    backfillContext(runId: string, stepId: string, context: string): void;
+    finishRun(runId: string, finalOutput?: string, metrics?: RunMetrics): void;
+    /**
+     * Report what a matched turn cost (docs/calculatedReplay.md §11.2).
+     *
+     * Queued on the run's own chain so it lands after that run's last step and so
+     * `flush` waits for it — a report is the last thing a matched turn produces.
+     * Best-effort like everything else here: an unredeemed ticket leaves no
+     * execution row at all, which loses a saving but can never invent one.
+     *
+     * A doubled report (a retry, `Stop` racing `SessionEnd`) is safe by
+     * construction: the ticket *is* the row's id, so the service books once and
+     * answers `200 { duplicate: true }`.
+     */
+    reportExecution(report: ExecutionReport): void;
+    /** Await every queued send for a run, including its execution report. */
+    flush(runId: string): Promise<void>;
+    /** Append to this run's ordered chain; failures are logged, not thrown. */
+    private enqueue;
+    private post;
+    private patch;
+    private send;
+    /**
+     * Adopt a newer session written by a sibling process, if there is one.
+     *
+     * Returns true when this recorder now holds a usable token it did not have to
+     * spend a refresh on.
+     */
+    private adoptStoredSession;
+    /**
+     * Silent token refresh.
+     *
+     * WHY THIS IS NOT JUST A POST. Several processes share one credentials file —
+     * `bir-hooks` and one `bir-proxy` per wrapped server — and the service rotates
+     * the refresh token on every use. So when two of them hit a 401 together, both
+     * refresh, one wins, and the loser's token is now invalid *forever*: it fails,
+     * gives up, and silently records nothing for the rest of the session while
+     * logging one warning per dropped step. Observed, not hypothetical.
+     *
+     * The fix is to treat the credentials file as the shared source of truth:
+     * check it before spending our token, and check it again if our refresh is
+     * rejected, because the process that beat us has already written a good one.
+     */
+    private refresh;
+    private refreshOverNetwork;
+}
+//# sourceMappingURL=remote-recorder.d.ts.map

package/dist/record/remote-recorder.js

@@ -0,0 +1,301 @@
+/**
+ * RemoteRecorder — streams each step to the BaseIn auth-service (Phase 4.2).
+ *
+ * Ported unchanged in shape from RRepeat's `server/remote-recorder.ts`, so the
+ * already-live endpoints need no v1 changes:
+ *   POST  /recordings/runs
+ *   POST  /recordings/runs/:id/steps
+ *   PATCH /recordings/runs/:id/steps/:stepId
+ *   POST  /recordings/runs/:id/finish
+ *
+ * Four properties matter, and each is load-bearing:
+ *   - **Client-generated ids** (`run_`/`step_` uuids) so callers get an id
+ *     synchronously and never await the network on the hot path.
+ *   - **One ordered promise chain per run**, so steps arrive in the order they
+ *     were recorded even though every send is fire-and-forget.
+ *   - **Best-effort.** A failed send is logged and dropped, never retried inline
+ *     and never thrown at the caller (§10).
+ *   - **One token refresh on 401**, then one retry. Sessions outlive access tokens.
+ *
+ * SIMILAR-PROMPT HITS. `POST /recordings/runs` may answer `{ id: null, matched }`,
+ * meaning the server recognised the prompt and did **not** create a run. Every
+ * later step post for that id would then 404, so callers must stop recording —
+ * {@link RemoteRecorder.getMatch} is how they find out. v1 only stops; replay is v2.
+ */
+import { randomUUID } from "node:crypto";
+import { loadCredentials, saveCredentials } from "../auth/client.js";
+import { logLine, errText } from "../util/log.js";
+export class RemoteRecorder {
+    baseUrl;
+    framework;
+    session;
+    /** runId → tail of that run's ordered send chain. */
+    chains = new Map();
+    /** runId → the similar-prompt outcome of its create call. */
+    matches = new Map();
+    /**
+     * Execution reports ride their own chain: a matched turn has no run on the
+     * service (that is what a match means), so there is no run chain to append to.
+     */
+    executionChainKey = "__executions__";
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.session = opts.session;
+        this.framework = opts.framework ?? "baseinstrunner";
+    }
+    startRun(input, metadata) {
+        const id = "run_" + randomUUID();
+        let resolveMatch;
+        this.matches.set(id, new Promise((r) => {
+            resolveMatch = r;
+        }));
+        this.enqueue(id, async () => {
+            try {
+                const body = await this.post("/recordings/runs", {
+                    id,
+                    framework: this.framework,
+                    input,
+                    metadata,
+                });
+                const matched = body && typeof body === "object"
+                    ? (body.matched ?? null)
+                    : null;
+                resolveMatch(matched);
+            }
+            catch (err) {
+                resolveMatch(null); // fail-safe: on a create error, record normally
+                throw err; // preserve enqueue's dropped-send logging
+            }
+        });
+        return id;
+    }
+    /** Await the similar-prompt match for a run's create call (null = fresh run). */
+    async getMatch(runId) {
+        const pending = this.matches.get(runId);
+        return pending ? await pending : null;
+    }
+    recordToolSelected(runId, stepIndex, data) {
+        const id = "step_" + randomUUID();
+        this.enqueue(runId, () => this.post(`/recordings/runs/${runId}/steps`, {
+            id,
+            stepIndex,
+            type: "tool_selected",
+            toolName: data.toolName,
+            toolInput: data.toolInput,
+            context: data.context,
+        }));
+        return id;
+    }
+    recordToolResponse(runId, stepIndex, data) {
+        const id = "step_" + randomUUID();
+        this.enqueue(runId, () => this.post(`/recordings/runs/${runId}/steps`, {
+            id,
+            stepIndex,
+            type: "tool_response",
+            toolName: data.toolName,
+            toolOutput: data.toolOutput,
+            toolError: data.toolError,
+        }));
+        return id;
+    }
+    recordFinalAnswer(runId, stepIndex, data) {
+        const id = "step_" + randomUUID();
+        this.enqueue(runId, () => this.post(`/recordings/runs/${runId}/steps`, {
+            id,
+            stepIndex,
+            type: "final_answer",
+            answer: data.answer,
+        }));
+        return id;
+    }
+    /** Backfill a step's `context` (the model's reasoning) after the fact. */
+    backfillContext(runId, stepId, context) {
+        this.enqueue(runId, () => this.patch(`/recordings/runs/${runId}/steps/${stepId}`, { context }));
+    }
+    finishRun(runId, finalOutput, metrics) {
+        this.enqueue(runId, () => this.post(`/recordings/runs/${runId}/finish`, {
+            finalOutput,
+            originalCostUsd: metrics?.costUsd,
+            originalMs: metrics?.durationMs,
+        }));
+    }
+    /**
+     * Report what a matched turn cost (docs/calculatedReplay.md §11.2).
+     *
+     * Queued on the run's own chain so it lands after that run's last step and so
+     * `flush` waits for it — a report is the last thing a matched turn produces.
+     * Best-effort like everything else here: an unredeemed ticket leaves no
+     * execution row at all, which loses a saving but can never invent one.
+     *
+     * A doubled report (a retry, `Stop` racing `SessionEnd`) is safe by
+     * construction: the ticket *is* the row's id, so the service books once and
+     * answers `200 { duplicate: true }`.
+     */
+    reportExecution(report) {
+        const costUsd = report.deriveCostUsd + report.sessionCostUsd + report.fallbackCostUsd;
+        this.enqueue(this.executionChainKey, async () => {
+            const body = await this.post(`/scenarios/${report.scenarioId}/executions`, {
+                ticket: report.ticket,
+                outcome: report.outcome,
+                costUsd,
+                deriveCostUsd: report.deriveCostUsd,
+                sessionCostUsd: report.sessionCostUsd,
+                fallbackCostUsd: report.fallbackCostUsd,
+                durationMs: report.durationMs,
+                stepsPlanned: report.stepsPlanned,
+                stepsPinned: report.stepsPinned,
+                measured: report.measured,
+                pricingVersion: report.pricingVersion,
+                prompt: report.prompt,
+                // Per-step verdicts and the headline failure (errorshandling.md). All
+                // optional on the service side, so an older service ignores them rather
+                // than rejecting the report — and the costs still book.
+                steps: report.steps,
+                error: report.error,
+                errorStage: report.errorStage,
+                errorStepIndex: report.errorStepIndex,
+                errorToolName: report.errorToolName,
+            });
+            const r = (body ?? {});
+            const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
+            logLine("execution.reported", {
+                scenario: report.scenarioId,
+                outcome: report.outcome,
+                derive: report.deriveCostUsd.toFixed(4),
+                session: report.sessionCostUsd.toFixed(4),
+                fallback: report.fallbackCostUsd.toFixed(4),
+                savedUsd: r.savedUsd ?? undefined,
+                duplicate: r.duplicate ? true : undefined,
+                measured: report.measured,
+                steps: report.steps?.length,
+                stepsFailed: failed || undefined,
+            });
+        });
+    }
+    /** Await every queued send for a run, including its execution report. */
+    async flush(runId) {
+        await (this.chains.get(runId) ?? Promise.resolve());
+        this.chains.delete(runId);
+        this.matches.delete(runId);
+        // Reports live on their own chain (a matched run has no run chain of its own
+        // — the service created no run), so draining that chain is a separate step.
+        await (this.chains.get(this.executionChainKey) ?? Promise.resolve());
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    /** Append to this run's ordered chain; failures are logged, not thrown. */
+    enqueue(runId, fn) {
+        const prev = this.chains.get(runId) ?? Promise.resolve();
+        const next = prev.then(fn).catch((err) => {
+            // A dropped send means this run's recording is incomplete — something an
+            // auditor has to be able to see, so it is never verbose-only.
+            logLine("recorder.send_failed", {
+                run: runId,
+                why: "this run's recording is incomplete",
+                error: errText(err),
+            });
+        });
+        this.chains.set(runId, next);
+    }
+    post(path, body) {
+        return this.send("POST", path, body);
+    }
+    patch(path, body) {
+        return this.send("PATCH", path, body);
+    }
+    async send(method, path, body, retried = false) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${this.session.accessToken}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (res.status === 401 && !retried) {
+            await this.refresh();
+            return this.send(method, path, body, true);
+        }
+        const text = await res.text().catch(() => "");
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status} ${method} ${path}${text ? ` — ${text}` : ""}`);
+        }
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Adopt a newer session written by a sibling process, if there is one.
+     *
+     * Returns true when this recorder now holds a usable token it did not have to
+     * spend a refresh on.
+     */
+    adoptStoredSession() {
+        const stored = loadCredentials();
+        if (!stored)
+            return false;
+        if (stored.accessToken === this.session.accessToken)
+            return false;
+        if (stored.accessExpiresAt - 30_000 <= Date.now())
+            return false;
+        this.session = stored;
+        logLine("auth.adopted", { why: "another process had already refreshed" });
+        return true;
+    }
+    /**
+     * Silent token refresh.
+     *
+     * WHY THIS IS NOT JUST A POST. Several processes share one credentials file —
+     * `bir-hooks` and one `bir-proxy` per wrapped server — and the service rotates
+     * the refresh token on every use. So when two of them hit a 401 together, both
+     * refresh, one wins, and the loser's token is now invalid *forever*: it fails,
+     * gives up, and silently records nothing for the rest of the session while
+     * logging one warning per dropped step. Observed, not hypothetical.
+     *
+     * The fix is to treat the credentials file as the shared source of truth:
+     * check it before spending our token, and check it again if our refresh is
+     * rejected, because the process that beat us has already written a good one.
+     */
+    async refresh() {
+        if (this.adoptStoredSession())
+            return;
+        try {
+            await this.refreshOverNetwork();
+        }
+        catch (err) {
+            // Someone may have refreshed while we were failing to.
+            if (this.adoptStoredSession())
+                return;
+            throw err;
+        }
+    }
+    async refreshOverNetwork() {
+        const res = await fetch(`${this.baseUrl}/auth/refresh`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ refreshToken: this.session.refreshToken }),
+        });
+        if (!res.ok)
+            throw new Error(`refresh failed: HTTP ${res.status}`);
+        const r = (await res.json());
+        this.session = {
+            accessToken: r.accessToken,
+            refreshToken: r.refreshToken,
+            accessExpiresAt: Date.now() + r.expiresIn * 1000,
+            user: r.user,
+        };
+        try {
+            saveCredentials(this.session); // persist so the next run reuses it
+        }
+        catch (err) {
+            // Persisting is a convenience for the *next* process. Letting it throw
+            // here aborts the retry this refresh exists to enable, and loses the step.
+            logLine("auth.save_failed", { error: errText(err), why: "the token still works in-process" });
+        }
+    }
+}
+//# sourceMappingURL=remote-recorder.js.map

package/dist/record/truncate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * truncate — payload size caps (Phase 4.4).
+ *
+ * A single `chrome-devtools` screenshot is a megabyte of base64. Left alone it
+ * dominates the run, the request body and the corpus, and it is worth nothing to
+ * a scenario. So every recorded payload is capped twice:
+ *
+ *   1. **Per string**, so one enormous leaf cannot hide inside an otherwise small
+ *      structure and so the rest of that structure still survives intact.
+ *   2. **Per payload**, on the serialized form, as the actual guarantee. If the
+ *      whole thing still exceeds the cap after step 1 it is replaced by an
+ *      explicit marker rather than silently clipped mid-JSON.
+ *
+ * Truncation is always **visible**: a truncated string keeps a suffix naming the
+ * bytes dropped, and a truncated payload serialises to
+ * `{ truncated: true, originalBytes, preview }`. A consumer can tell a short
+ * result from a clipped one, which is the whole point.
+ */
+/** 64 KiB per payload, as suggested in Phase 4.4. */
+export declare const DEFAULT_MAX_PAYLOAD_BYTES: number;
+/** 8 KiB per individual string leaf. */
+export declare const DEFAULT_MAX_STRING_BYTES: number;
+export interface TruncateOptions {
+    maxPayloadBytes?: number;
+    maxStringBytes?: number;
+}
+/** Clip one string to `max` bytes, appending a marker naming what was dropped. */
+export declare function truncateString(text: string, max: number): string;
+/** Deep-copy `value`, clipping every string leaf. Input is never mutated. */
+export declare function truncateStrings(value: unknown, max: number, depth?: number): unknown;
+/**
+ * Serialize `value` for recording, capped and with truncation made explicit.
+ * Never throws: an unserialisable payload becomes a marker string.
+ */
+export declare function serializeCapped(value: unknown, opts?: TruncateOptions): string;
+//# sourceMappingURL=truncate.d.ts.map