@wrongstack/wrongtrace 0.313.0

package/dist/client.js

@@ -0,0 +1,304 @@
+/**
+ * The integrated WrongTrace client.
+ *
+ *  ┌────────────────┐    ┌────────────────┐    ┌──────────────────┐
+ *  │  HTTP / REST   │ ←→ │  WrongTrace    │ ←→ │  IPC / MCP opt.  │
+ *  │  (always)      │    │  Client        │    │  (if discovered) │
+ *  └────────────────┘    └────────────────┘    └──────────────────┘
+ *
+ * Strategy:
+ *   - IPC-first: when `/api/health` reports a `socket_path`, JSON-RPC 2.0
+ *     over the pipe is preferred for every method the daemon exposes there.
+ *     Daemon v0.3.3 (live-verified 2026-08-24) answers telemetry/file_health,
+ *     telemetry/report_run, guardrail/unlock and get_atlas on the pipe;
+ *     older daemons reply -32601, which the transport surfaces as
+ *     {result:null} → HTTP fallback, so routing is a no-op there.
+ *   - ONE exception: guardrail/lock answers on the pipe but does NOT enforce
+ *     conflicts — a live probe (2026-08-24) showed IPC lock with force:false
+ *     silently TAKES OVER another owner's lock instead of rejecting with the
+ *     -32009 envelope the integration letter promises. lockFile therefore
+ *     stays HTTP-first to preserve the 409 conflict semantics production
+ *     gates depend on. Flip it when the daemon enforces conflicts on IPC.
+ *   - HTTP is the universal substrate — every method has an HTTP path and
+ *     serves as the fallback when the pipe is absent or fails.
+ *   - MCP is used when the host runtime supplies an MCP tool bag. In that
+ *     mode we prefer IPC, then the named MCP tools (lock_file,
+ *     get_file_health_score, etc.), then HTTP.
+ *
+ * Every method returns `null` (or `[]` for list endpoints) when the
+ * underlying transport failed OR the daemon was never reachable. The
+ * protocol promises callers can wire this client unconditionally and
+ * "pass" when WrongTrace is offline.
+ */
+import { createMcpTransport } from "./adapters/mcp.js";
+import { createIpcTransport } from "./adapters/ipc.js";
+import { discover } from "./discovery.js";
+const DEFAULT_TIMEOUT_MS = 4_000;
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "HttpError";
+    }
+}
+async function httpJson(baseUrl, path, init) {
+    const fetchImpl = globalThis.fetch;
+    if (typeof fetchImpl !== "function")
+        return null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), init?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const headers = { Accept: "application/json" };
+        if (init?.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const reqInit = {
+            method: init?.method ?? "GET",
+            signal: controller.signal,
+            headers,
+        };
+        if (init?.body !== undefined)
+            reqInit.body = JSON.stringify(init.body);
+        const res = await fetchImpl(`${baseUrl}${path}`, reqInit);
+        // Non-2xx statuses listed in acceptStatus carry a structured body the
+        // caller wants (e.g. lock conflicts: 409 + {ok:false, owner, expires_at}).
+        // Surface those bodies instead of swallowing them into null.
+        if (!res.ok && !(init?.acceptStatus ?? []).includes(res.status)) {
+            throw new HttpError(res.status, `${init?.method ?? "GET"} ${path} → ${res.status}`);
+        }
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function createWrongTraceClient(opts = {}) {
+    const discovery = await discover(opts);
+    const mcp = createMcpTransport(opts.mcpTools);
+    const ipc = createIpcTransport(discovery.socketPath);
+    const requireBaseUrl = () => {
+        if (!discovery.available || !discovery.baseUrl)
+            return null;
+        return discovery.baseUrl;
+    };
+    const notAvailable = () => null;
+    const client = {
+        _discovery: discovery,
+        get isAvailable() {
+            return discovery.available;
+        },
+        get baseUrl() {
+            return discovery.baseUrl;
+        },
+        get socketPath() {
+            return discovery.socketPath;
+        },
+        async getHealth() {
+            const base = requireBaseUrl();
+            if (!base)
+                return notAvailable();
+            return httpJson(base, "/api/health");
+        },
+        async getFileHealth(path) {
+            const base = requireBaseUrl();
+            if (!base)
+                return notAvailable();
+            // IPC-first: live-verified JSON-RPC method on the daemon's pipe
+            // (both instances, 2026-08-24). Falls back to HTTP when the pipe is
+            // absent, unreachable, or answers with an error envelope.
+            if (ipc.isWired) {
+                const viaIpc = await ipc.call("telemetry/file_health", { file_path: path });
+                if (viaIpc.result)
+                    return viaIpc.result;
+            }
+            if (mcp.isWired) {
+                const viaMcp = await mcp.invoke("get_file_health_score", { path });
+                if (viaMcp)
+                    return viaMcp;
+            }
+            return httpJson(base, `/api/file/health?path=${encodeURIComponent(path)}`);
+        },
+        async getSymbolLineage(path, signature) {
+            const base = requireBaseUrl();
+            if (!base)
+                return [];
+            // Daemon round-3: signature is optional — path-only returns every
+            // symbol event for the file. Loose names like "foo()" still yield [],
+            // so callers wanting a specific symbol should pass a daemon-format
+            // signature (`function:file.go::Name`); otherwise omit it.
+            const params = new URLSearchParams();
+            params.set("path", path);
+            if (signature !== undefined && signature !== "")
+                params.set("signature", signature);
+            const data = await httpJson(base, `/api/symbol/history?${params.toString()}`);
+            return Array.isArray(data) ? data : [];
+        },
+        async getFrictionMatrix(limit = 50) {
+            const base = requireBaseUrl();
+            if (!base)
+                return [];
+            const data = await httpJson(base, `/api/metrics/friction?limit=${limit}`);
+            // The daemon returns a report object ({edges, recent_collisions,
+            // total_collisions, ...}), not a bare array. Normalize: bare array
+            // passes through; report shape yields its edges, carrying
+            // `recent_collisions` as metadata so single-call consumers
+            // (getRecentActivity) don't lose the per-file collision history.
+            if (Array.isArray(data))
+                return data;
+            if (data && typeof data === "object") {
+                const report = data;
+                if (Array.isArray(report.edges)) {
+                    const rows = report.edges;
+                    if (Array.isArray(report.recent_collisions))
+                        rows.recent_collisions = report.recent_collisions;
+                    return rows;
+                }
+            }
+            return [];
+        },
+        async getAtlas(query) {
+            const base = requireBaseUrl();
+            if (!base)
+                return notAvailable();
+            const params = new URLSearchParams();
+            if (query?.workspace !== undefined && query.workspace !== "")
+                params.set("workspace", query.workspace);
+            if (query?.summary === true)
+                params.set("summary", "true");
+            if (query?.includeSymbols === false)
+                params.set("include_symbols", "false");
+            if (query?.limit !== undefined)
+                params.set("limit", String(query.limit));
+            if (query?.offset !== undefined)
+                params.set("offset", String(query.offset));
+            const qs = params.size > 0 ? `?${params.toString()}` : "";
+            // IPC-first since daemon v0.3.3 (live-verified 2026-08-24): get_atlas
+            // answers JSON-RPC on the pipe. Older daemons reply -32601 →
+            // {result:null} → HTTP fallback below. summary=true keeps the pipe
+            // payload small; full atlases are multi-hundred-ms either transport.
+            if (ipc.isWired) {
+                const viaIpc = await ipc.call("get_atlas", {
+                    ...(query?.workspace !== undefined && query.workspace !== "" ? { workspace: query.workspace } : {}),
+                    ...(query?.summary === true ? { summary: true } : {}),
+                    ...(query?.includeSymbols === false ? { include_symbols: false } : {}),
+                    ...(query?.limit !== undefined ? { limit: query.limit } : {}),
+                    ...(query?.offset !== undefined ? { offset: query.offset } : {}),
+                });
+                if (viaIpc.result)
+                    return viaIpc.result;
+            }
+            return httpJson(base, `/api/atlas${qs}`);
+        },
+        async lockFile(path, reason, opts) {
+            // Deliberately HTTP-first — the ONE IPC exception; see the strategy
+            // header. Live probe 2026-08-24: IPC guardrail/lock ignores conflicts
+            // (silently takes over even with force:false), so routing lock calls
+            // through the pipe would break the 409-conflict semantics the
+            // production guardrail depends on.
+            const body = { path, reason };
+            if (opts?.owner !== undefined)
+                body.owner = opts.owner;
+            if (opts?.ownerRunId !== undefined)
+                body.owner_run_id = opts.ownerRunId;
+            if (opts?.ttlSeconds !== undefined)
+                body.ttl_seconds = opts.ttlSeconds;
+            if (opts?.force === true)
+                body.force = true;
+            if (mcp.isWired) {
+                const viaMcp = await mcp.invoke("lock_file", { ...body });
+                if (viaMcp)
+                    return viaMcp;
+            }
+            const base = requireBaseUrl();
+            if (!base)
+                return notAvailable();
+            // 409 = lock conflict: the daemon returns {ok:false, owner, owner_run_id,
+            // locked_at, expires_at, error, message} — exactly what the caller needs
+            // to decide whether to wait or take over, so pass the body through.
+            return httpJson(base, "/api/guardrail/lock", {
+                method: "POST",
+                body,
+                acceptStatus: [409],
+            });
+        },
+        async unlockFile(path) {
+            // IPC-first since daemon v0.3.3 (live-verified 2026-08-24): the pipe
+            // shares the daemon's lock store — an IPC unlock releases HTTP-acquired
+            // locks. Shape differs from HTTP: {file_path, status} with no `ok`,
+            // normalized here to the HTTP contract.
+            if (ipc.isWired) {
+                const viaIpc = await ipc.call("guardrail/unlock", { path });
+                if (viaIpc.result) {
+                    return {
+                        ok: true,
+                        path: viaIpc.result.path ?? viaIpc.result.file_path ?? path,
+                        status: viaIpc.result.status ?? "unlocked",
+                    };
+                }
+            }
+            const body = { path };
+            if (mcp.isWired) {
+                const viaMcp = await mcp.invoke("unlock_file", { ...body });
+                if (viaMcp)
+                    return viaMcp;
+            }
+            const base = requireBaseUrl();
+            if (!base)
+                return notAvailable();
+            return httpJson(base, "/api/guardrail/unlock", { method: "POST", body });
+        },
+        async reportTelemetry(report) {
+            // IPC-first: telemetry/report_run is a live JSON-RPC method on the
+            // daemon's pipe (both instances, 2026-08-24). HTTP fallback keeps the
+            // no-op contract when the pipe is absent or fails.
+            if (ipc.isWired) {
+                const viaIpc = await ipc.call("telemetry/report_run", {
+                    ...report,
+                });
+                if (viaIpc.result) {
+                    // Daemon answers {"status":"ok"} — normalize to the HTTP contract.
+                    const ok = viaIpc.result.ok ?? viaIpc.result.status === "ok";
+                    return { ok };
+                }
+            }
+            if (mcp.isWired) {
+                const viaMcp = await mcp.invoke("report_telemetry", { ...report });
+                if (viaMcp)
+                    return viaMcp;
+            }
+            const base = requireBaseUrl();
+            if (!base)
+                return notAvailable();
+            return httpJson(base, "/api/telemetry", { method: "POST", body: report });
+        },
+        async getRecentEvents(query) {
+            const base = requireBaseUrl();
+            if (!base)
+                return [];
+            const params = new URLSearchParams();
+            if (query?.limit !== undefined)
+                params.set("limit", String(query.limit));
+            if (query?.since !== undefined)
+                params.set("since", query.since);
+            if (query?.repo !== undefined)
+                params.set("repo", query.repo);
+            if (query?.filePath !== undefined)
+                params.set("file_path", query.filePath);
+            const qs = params.size > 0 ? `?${params.toString()}` : "";
+            const data = await httpJson(base, `/api/events/recent${qs}`);
+            return Array.isArray(data) ? data : [];
+        },
+        async listLocks() {
+            const base = requireBaseUrl();
+            if (!base)
+                return [];
+            const data = await httpJson(base, "/api/guardrail/locks");
+            return Array.isArray(data) ? data : [];
+        },
+    };
+    return client;
+}
+//# sourceMappingURL=client.js.map

package/dist/discovery.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Discovers whether the external WrongTrace AI Observability daemon is
+ * reachable, and if so, where to talk to it.
+ *
+ * Discovery protocol (per the integration spec):
+ *   1. HTTP probe of `${baseUrl}/api/health` with a tight timeout.
+ *   2. If the daemon replies 2xx, read `socket_path` from the body for the
+ *      IPC path. If absent, fall back to platform-default locations.
+ *   3. If MCP tools are registered globally (e.g. via `wrongtrace mcp`),
+ *      MCP transport is preferred over HTTP/IPC for actual calls.
+ *
+ * The whole routine never throws — it returns a `DiscoveryResult` whose
+ * `available` flag tells the caller to either bind the full client or
+ * install a typed no-op shim. That makes it safe to invoke from the hot
+ * path of boot.
+ */
+export interface DiscoveryOptions {
+    /** Override the base URL. Default: process.env.WRONGTRACE_URL ?? "http://localhost:3444". */
+    baseUrl?: string;
+    /** Probe timeout in ms. Default: 1000. */
+    timeoutMs?: number;
+    /**
+     * Inject a `fetch`-compatible implementation. Tests use this to stub the
+     * probe without monkey-patching globals.
+     */
+    fetchImpl?: typeof fetch;
+}
+export interface DiscoveryResult {
+    available: boolean;
+    baseUrl?: string;
+    socketPath?: string;
+    version?: string;
+}
+/** Default IPC paths per platform — only consulted when `/api/health` did not return `socket_path`. */
+export declare function defaultSocketPath(home?: string): string;
+export declare function discover(opts?: DiscoveryOptions): Promise<DiscoveryResult>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.js

@@ -0,0 +1,65 @@
+/**
+ * Discovers whether the external WrongTrace AI Observability daemon is
+ * reachable, and if so, where to talk to it.
+ *
+ * Discovery protocol (per the integration spec):
+ *   1. HTTP probe of `${baseUrl}/api/health` with a tight timeout.
+ *   2. If the daemon replies 2xx, read `socket_path` from the body for the
+ *      IPC path. If absent, fall back to platform-default locations.
+ *   3. If MCP tools are registered globally (e.g. via `wrongtrace mcp`),
+ *      MCP transport is preferred over HTTP/IPC for actual calls.
+ *
+ * The whole routine never throws — it returns a `DiscoveryResult` whose
+ * `available` flag tells the caller to either bind the full client or
+ * install a typed no-op shim. That makes it safe to invoke from the hot
+ * path of boot.
+ */
+import { platform } from "node:os";
+import { join } from "node:path";
+/** Default IPC paths per platform — only consulted when `/api/health` did not return `socket_path`. */
+export function defaultSocketPath(home = process.env.HOME ?? process.env.USERPROFILE ?? "") {
+    if (platform() === "win32")
+        return "\\\\.\\pipe\\wrongtrace.sock";
+    if (home)
+        return join(home, ".wrongtrace", "ipc.sock");
+    return "/tmp/wrongtrace.sock";
+}
+export async function discover(opts = {}) {
+    const baseUrl = opts.baseUrl ?? process.env.WRONGTRACE_URL ?? "http://localhost:3444";
+    const timeoutMs = opts.timeoutMs ?? 1000;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        return { available: false };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(`${baseUrl}/api/health`, {
+            signal: controller.signal,
+            headers: { Accept: "application/json" },
+        });
+        if (!res.ok)
+            return { available: false, baseUrl };
+        const body = (await res.json().catch(() => ({})));
+        // Accept either contract the daemon might speak:
+        //   * { ok: true }                    (older / strict boolean schema)
+        //   * { status: "ok" }                (current WrongProxy-style schema)
+        if (body?.ok !== true && body?.status !== "ok")
+            return { available: false, baseUrl };
+        const result = { available: true, baseUrl };
+        if (typeof body.socket_path === "string")
+            result.socketPath = body.socket_path;
+        else
+            result.socketPath = defaultSocketPath();
+        if (typeof body.version === "string")
+            result.version = body.version;
+        return result;
+    }
+    catch {
+        return { available: false, baseUrl };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/gate-counters.d.ts

@@ -0,0 +1,53 @@
+/**
+ * WrongTrace gate-decision counter — hosted in the shared adapter so EVERY
+ * process that runs the gate (CLI leader + fleet, standalone WebUI server)
+ * records into the same tally contract and the same counters file.
+ *
+ * Design:
+ *   - Pure, transport-agnostic tally: `record()` accepts the typed event;
+ *     `snapshot()` returns one number per decision kind.
+ *   - Deliberately NOT wired as a new EventBus listener — the host emit
+ *     sites call `recordGateDecision()` inside their existing emit
+ *     closures, so this module never registers a listener it must remember
+ *     to dispose (the EventBus wildcard/named caps punish undisposed
+ *     registrations; see the core EventBus leak board card).
+ *   - A snapshot is persisted to `<projectRoot>/.wrongstack/
+ *     wrongtrace-gate-counters.json` so the standalone `wstack
+ *     proxy-status` command (fresh process) can report the latest writer's
+ *     CUMULATIVE firing rates — cross-process measurability.
+ *
+ * Shared file contract (CLI + standalone WebUI): both processes write the
+ * same path with the same snapshot shape; each process tallies its own
+ * sessions (module singleton per process), and the last writer wins. The
+ * CLI persists at session end (finalizeExecutionCleanup); the standalone
+ * WebUI server persists on each gate decision (its host session model has
+ * no single session-end hook). `wstack proxy-status` reads whatever the
+ * latest writer produced.
+ */
+import type { WrongTraceGateDecisionEvent } from './hooks.js';
+export interface WrongTraceGateCounterSnapshot {
+    deny: number;
+    allowFragile: number;
+    lockAcquired: number;
+    lockConflictRace: number;
+    lockReleased: number;
+    total: number;
+}
+export interface WrongTraceGateCounter {
+    record(event: WrongTraceGateDecisionEvent): void;
+    snapshot(): WrongTraceGateCounterSnapshot;
+    reset(): void;
+}
+export declare function createWrongTraceGateCounter(): WrongTraceGateCounter;
+/** Record one gate decision into the process-shared tally. */
+export declare function recordGateDecision(event: WrongTraceGateDecisionEvent): void;
+/** Snapshot the process-shared tally (for session-end persist / doctor). */
+export declare function snapshotGateDecisions(): WrongTraceGateCounterSnapshot;
+export declare function resetGateDecisions(): void;
+export declare function countersFilePath(projectRoot: string): string;
+/** Best-effort persist — the doctor surface must never fail a session end. */
+export declare function persistWrongTraceGateCounters(projectRoot: string, snapshot: WrongTraceGateCounterSnapshot): Promise<void>;
+export declare function loadWrongTraceGateCounters(projectRoot: string): Promise<WrongTraceGateCounterSnapshot | null>;
+/** Compact one-line report for the doctor surface. */
+export declare function formatGateCounterReport(s: WrongTraceGateCounterSnapshot): string;
+//# sourceMappingURL=gate-counters.d.ts.map

package/dist/gate-counters.js

@@ -0,0 +1,161 @@
+/**
+ * WrongTrace gate-decision counter — hosted in the shared adapter so EVERY
+ * process that runs the gate (CLI leader + fleet, standalone WebUI server)
+ * records into the same tally contract and the same counters file.
+ *
+ * Design:
+ *   - Pure, transport-agnostic tally: `record()` accepts the typed event;
+ *     `snapshot()` returns one number per decision kind.
+ *   - Deliberately NOT wired as a new EventBus listener — the host emit
+ *     sites call `recordGateDecision()` inside their existing emit
+ *     closures, so this module never registers a listener it must remember
+ *     to dispose (the EventBus wildcard/named caps punish undisposed
+ *     registrations; see the core EventBus leak board card).
+ *   - A snapshot is persisted to `<projectRoot>/.wrongstack/
+ *     wrongtrace-gate-counters.json` so the standalone `wstack
+ *     proxy-status` command (fresh process) can report the latest writer's
+ *     CUMULATIVE firing rates — cross-process measurability.
+ *
+ * Shared file contract (CLI + standalone WebUI): both processes write the
+ * same path with the same snapshot shape; each process tallies its own
+ * sessions (module singleton per process), and the last writer wins. The
+ * CLI persists at session end (finalizeExecutionCleanup); the standalone
+ * WebUI server persists on each gate decision (its host session model has
+ * no single session-end hook). `wstack proxy-status` reads whatever the
+ * latest writer produced.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+export function createWrongTraceGateCounter() {
+    let deny = 0;
+    let allowFragile = 0;
+    let lockAcquired = 0;
+    let lockConflictRace = 0;
+    let lockReleased = 0;
+    return {
+        record(event) {
+            switch (event.kind) {
+                case 'deny':
+                    deny++;
+                    break;
+                case 'allow-fragile':
+                    allowFragile++;
+                    break;
+                case 'lock-acquired':
+                    lockAcquired++;
+                    break;
+                case 'lock-conflict-race':
+                    lockConflictRace++;
+                    break;
+                case 'lock-released':
+                    lockReleased++;
+                    break;
+            }
+        },
+        snapshot() {
+            return {
+                deny,
+                allowFragile,
+                lockAcquired,
+                lockConflictRace,
+                lockReleased,
+                total: deny + allowFragile + lockAcquired + lockConflictRace + lockReleased,
+            };
+        },
+        reset() {
+            deny = 0;
+            allowFragile = 0;
+            lockAcquired = 0;
+            lockConflictRace = 0;
+            lockReleased = 0;
+        },
+    };
+}
+const COUNTERS_FILE = path.join('.wrongstack', 'wrongtrace-gate-counters.json');
+// Process-shared singleton — wired at the host emit sites (CLI leader +
+// fleet, standalone WebUI server) and read at session end / on each gate
+// decision, without registering any new EventBus listener (the leak
+// discipline from the EventBus board card).
+const shared = createWrongTraceGateCounter();
+/** Record one gate decision into the process-shared tally. */
+export function recordGateDecision(event) {
+    shared.record(event);
+}
+/** Snapshot the process-shared tally (for session-end persist / doctor). */
+export function snapshotGateDecisions() {
+    return shared.snapshot();
+}
+export function resetGateDecisions() {
+    shared.reset();
+}
+export function countersFilePath(projectRoot) {
+    return path.join(projectRoot, COUNTERS_FILE);
+}
+// In-process serialization so unawaited per-decision persists (the
+// standalone WebUI emit closure) cannot interleave: each write awaits the
+// previous one, then publishes atomically via temp-file + rename (an
+// interrupted write never leaves a truncated counters file).
+let persistChain = Promise.resolve();
+/** Best-effort persist — the doctor surface must never fail a session end. */
+export function persistWrongTraceGateCounters(projectRoot, snapshot) {
+    // Chain so overlapping callers serialize; fail-open and never reject the
+    // returned promise (observability must not break teardown).
+    persistChain = persistChain.then(async () => {
+        const file = countersFilePath(projectRoot);
+        const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+        try {
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            await fs.writeFile(tmp, JSON.stringify({ at: new Date().toISOString(), ...snapshot }, null, 2), 'utf8');
+            await fs.rename(tmp, file);
+        }
+        catch {
+            // best-effort: leave the prior file intact (rename is atomic; a failed
+            // write before it only orphans the tmp file).
+            try {
+                await fs.unlink(tmp).catch(() => { });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    });
+    return persistChain;
+}
+export async function loadWrongTraceGateCounters(projectRoot) {
+    try {
+        const raw = await fs.readFile(countersFilePath(projectRoot), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.deny !== 'number' ||
+            typeof parsed.allowFragile !== 'number' ||
+            typeof parsed.lockAcquired !== 'number' ||
+            typeof parsed.lockConflictRace !== 'number' ||
+            typeof parsed.lockReleased !== 'number') {
+            return null;
+        }
+        // Strip the `at` timestamp persist adds — the loader returns the pure
+        // counter shape so callers (doctor readout, tests) get exactly the
+        // snapshot contract, not the storage envelope.
+        return {
+            deny: parsed.deny,
+            allowFragile: parsed.allowFragile,
+            lockAcquired: parsed.lockAcquired,
+            lockConflictRace: parsed.lockConflictRace,
+            lockReleased: parsed.lockReleased,
+            total: parsed.deny +
+                parsed.allowFragile +
+                parsed.lockAcquired +
+                parsed.lockConflictRace +
+                parsed.lockReleased,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Compact one-line report for the doctor surface. */
+export function formatGateCounterReport(s) {
+    return (`deny=${s.deny} allow-fragile=${s.allowFragile} ` +
+        `lock-acquired=${s.lockAcquired} lock-conflict-race=${s.lockConflictRace} ` +
+        `lock-released=${s.lockReleased} total=${s.total}`);
+}
+//# sourceMappingURL=gate-counters.js.map