@vincentt-xr/harness 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# @vincentt-xr/harness
+
+The Vincentt AR dev-loop harness. It is **one always-on diagnostics channel**
+between the AR app running on a phone and the coding agent running on a laptop,
+so the agent can see what the phone sees — console logs, network requests,
+performance — without the developer hand-ferrying DevTools traces or pasting
+console output.
+
+Agent-agnostic: the agent side is a plain **MCP server**, so any MCP-capable
+agent (Claude Code, Codex, Cursor, Cline, …) uses it the same way.
+
+## The three parts
+
+```
+  PHONE (preview app)          RELAY (laptop)         AGENT (laptop)
+  ┌──────────────────┐    ┌────────────────┐    ┌────────────────────┐
+  │ HarnessProvider  │    │  harness-relay │    │  harness-mcp       │
+  │ • patch console  │─ws→│  ring buffer   │←──→│  diag_logs         │
+  │ • wrap fetch/XHR │    │  per session   │http│  diag_network      │
+  │ • sample perf    │    │                │    │  diag_trace        │
+  └──────────────────┘    └────────────────┘    └────────────────────┘
+   src/client (npm pkg)      src/relay (bin)        src/mcp (bin)
+```
+
+- **`src/client`** — the in-app half; the published npm package. `HarnessProvider`
+  patches `console.*`, wraps `fetch`/`XHR`, and samples `performance`, shipping
+  events to the relay over a WebSocket. Auto-on in a dev build, no-op (and
+  tree-shaken) in production.
+- **`src/relay`** — a small WebSocket + HTTP server beside Vite. Holds a bounded
+  ring buffer of recent events per session. The phone pushes; the agent pulls.
+- **`src/mcp`** — the agent-agnostic MCP server. Exposes `diag_logs`,
+  `diag_network`, `diag_trace` that pull from the relay.
+
+- **`src/shared/events.ts`** — the wire contract all three import, so they can't
+  drift on the event shape.
+
+## Use it
+
+**In the app (once):**
+
+```tsx
+import { HarnessProvider } from "@vincentt-xr/harness";
+
+<HarnessProvider>
+  <App />
+</HarnessProvider>;
+```
+
+That's the whole author-facing surface. It self-activates in dev and disappears
+in the production build.
+
+**Run the relay** beside your dev server (the preview tunnel carries its socket
+to the phone):
+
+```
+npx harness-relay          # listens on :7331, ws path /__harness
+```
+
+**Point your agent at the MCP server.** In the agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "vincentt-harness": { "command": "npx", "args": ["harness-mcp"] }
+  }
+}
+```
+
+Then, while the app is open on the phone, the agent calls `diag_logs`,
+`diag_network`, `diag_trace` to read what the device is doing — no DevTools, no
+copy-paste.
+
+## Develop
+
+```
+pnpm install
+pnpm test         # unit tests (pure event-shaping, buffer, ring store, formatting, fps)
+pnpm typecheck
+pnpm build        # emits dist/ (client = npm surface; relay/mcp = bins)
+```
+
+## Status
+
+Local-first. The diagnostics limb is built and proven end-to-end
+(phone → relay → agent). The platform lifecycle (per-project server-minted
+tunnels, `createProject`/`publish`, auth) is a separate later phase; the same
+client + relay also feed the production client-review service.

package/dist/client/HarnessProvider.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from "react";
+export interface HarnessProviderProps {
+    children: ReactNode;
+    /**
+     * Force diagnostics on/off. Defaults to `import.meta.env.DEV` — on in the dev
+     * server + preview build, off in the production bundle.
+     */
+    enabled?: boolean;
+    /**
+     * WebSocket URL of the relay. Defaults to the same host the app is served
+     * from on port 7331 (what `harness-relay` listens on, tunneled alongside the
+     * app). Override for the production review-service sink.
+     */
+    relayUrl?: string;
+    /** Session id grouping this preview run's events. Defaults to a per-load id. */
+    sessionId?: string;
+    captureConsole?: boolean;
+    captureNetwork?: boolean;
+    captureTrace?: boolean;
+}
+export declare function HarnessProvider(props: HarnessProviderProps): ReactNode;

package/dist/client/HarnessProvider.js

@@ -0,0 +1,64 @@
+// The one thing an app author touches. Wrap the app once:
+//
+//   import { HarnessProvider } from "@vincentt-xr/harness";
+//   <HarnessProvider><App /></HarnessProvider>
+//
+// It self-activates in a dev build and is a no-op (and tree-shakes to nothing)
+// in production, so there is no way to ship diagnostics to real users by
+// accident. The relay URL and session id default to what the preview loop sets,
+// but both are overridable for the production review-service path later.
+import { useEffect } from "react";
+function defaultRelayUrl() {
+    if (typeof window === "undefined")
+        return "ws://localhost:7331";
+    const proto = window.location.protocol === "https:" ? "wss" : "ws";
+    // Default: the relay rides the same tunnel host as the app on a fixed path,
+    // so one cloudflared tunnel carries both. The relay CLI serves this path.
+    return `${proto}://${window.location.host}/__harness`;
+}
+function defaultSessionId() {
+    if (typeof window === "undefined")
+        return "server";
+    const key = "__vincentt_harness_session";
+    const existing = window.sessionStorage?.getItem(key);
+    if (existing)
+        return existing;
+    // Per-load id; not security-sensitive, just needs to be distinct enough that
+    // two phones on one relay don't collide. No Math.random dependency in the
+    // pure layer — this imperative shell may use it.
+    const id = `s_${Date.now().toString(36)}_${Math.floor(Math.random() * 1e6).toString(36)}`;
+    window.sessionStorage?.setItem(key, id);
+    return id;
+}
+const DEV = typeof import.meta !== "undefined" &&
+    import.meta.env?.DEV;
+export function HarnessProvider(props) {
+    const enabled = props.enabled ?? Boolean(DEV);
+    useEffect(() => {
+        if (!enabled)
+            return undefined;
+        let teardown;
+        let cancelled = false;
+        // Dynamic import: the instrumentation module (and its whole dependency
+        // chain) is only fetched when enabled, so prod builds never include it.
+        void import("./instrument.js").then(({ installInstrumentation }) => {
+            if (cancelled)
+                return;
+            teardown = installInstrumentation({
+                sessionId: props.sessionId ?? defaultSessionId(),
+                relayUrl: props.relayUrl ?? defaultRelayUrl(),
+                captureConsole: props.captureConsole,
+                captureNetwork: props.captureNetwork,
+                captureTrace: props.captureTrace,
+            });
+        });
+        return () => {
+            cancelled = true;
+            teardown?.();
+        };
+        // Instrumentation is installed once for the provider's lifetime; option
+        // changes mid-session are not a supported case.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [enabled]);
+    return props.children;
+}

package/dist/client/buffer.d.ts

@@ -0,0 +1,28 @@
+import type { ClientToRelay, DiagEvent } from "../shared/events.js";
+export interface BufferOptions {
+    sessionId: string;
+    /** Coalesce window: events within this many ms flush together. */
+    flushIntervalMs?: number;
+    /** Hard cap on pending events; oldest dropped past this (backpressure). */
+    maxPending?: number;
+    /** Injected transport. Returns true if the batch was accepted (socket open). */
+    send: (batch: ClientToRelay) => boolean;
+    /** Injected timer so tests are deterministic; defaults to setTimeout. */
+    schedule?: (fn: () => void, ms: number) => void;
+}
+export declare class EventBuffer {
+    private seq;
+    private pending;
+    private flushArmed;
+    private readonly opts;
+    constructor(options: BufferOptions);
+    /** Next sequence number without consuming it — for makeXEvent(seq, ...). */
+    nextSeq(): number;
+    /** Stamp and enqueue an event (seq already baked in via nextSeq). */
+    add(event: DiagEvent): void;
+    private armFlush;
+    /** Send everything pending; keep it buffered if the transport rejects it. */
+    flush(): void;
+    /** Test/introspection helper. */
+    pendingCount(): number;
+}

package/dist/client/buffer.js

@@ -0,0 +1,66 @@
+// The client's outbound buffer: assigns each event a monotonic seq, holds them
+// until a flush, and coalesces flushes so a burst of console.logs becomes one
+// socket message. Pure and transport-agnostic — you inject a `send` function,
+// and a `now`/`schedule` so tests control time. instrument.ts wires the real
+// WebSocket + setTimeout in.
+export class EventBuffer {
+    seq = 0;
+    pending = [];
+    flushArmed = false;
+    opts;
+    constructor(options) {
+        this.opts = {
+            flushIntervalMs: 250,
+            maxPending: 500,
+            schedule: (fn, ms) => setTimeout(fn, ms),
+            ...options,
+        };
+    }
+    /** Next sequence number without consuming it — for makeXEvent(seq, ...). */
+    nextSeq() {
+        return this.seq;
+    }
+    /** Stamp and enqueue an event (seq already baked in via nextSeq). */
+    add(event) {
+        // Trust the caller used nextSeq(); advance the counter to match.
+        this.seq = Math.max(this.seq, event.seq + 1);
+        this.pending.push(event);
+        // Drop oldest on overflow rather than grow unbounded on a runaway logger.
+        if (this.pending.length > this.opts.maxPending) {
+            this.pending.splice(0, this.pending.length - this.opts.maxPending);
+        }
+        this.armFlush();
+    }
+    armFlush() {
+        if (this.flushArmed)
+            return;
+        this.flushArmed = true;
+        this.opts.schedule(() => {
+            this.flushArmed = false;
+            this.flush();
+        }, this.opts.flushIntervalMs);
+    }
+    /** Send everything pending; keep it buffered if the transport rejects it. */
+    flush() {
+        if (this.pending.length === 0)
+            return;
+        const batch = {
+            type: "events",
+            sessionId: this.opts.sessionId,
+            events: this.pending,
+        };
+        const accepted = this.opts.send(batch);
+        if (accepted) {
+            this.pending = [];
+        }
+        else {
+            // Socket not open yet — keep the events, re-arm so we retry. Bounded by
+            // maxPending so a never-connecting socket can't leak memory.
+            this.armFlush();
+        }
+    }
+    /** Test/introspection helper. */
+    pendingCount() {
+        return this.pending.length;
+    }
+}

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+export { HarnessProvider } from "./HarnessProvider.js";
+export type { HarnessProviderProps } from "./HarnessProvider.js";
+export type { DiagEvent, LogEvent, NetworkEvent, TraceEvent } from "../shared/events.js";

package/dist/client/index.js

@@ -0,0 +1,5 @@
+// The published surface of @vincentt-xr/harness — the in-app half. Everything
+// here is imported by app code and ships in the app bundle (dev only; prod
+// tree-shakes it). The relay and MCP server are NOT exported here; they are
+// run-from-bin, not imported.
+export { HarnessProvider } from "./HarnessProvider.js";

package/dist/client/instrument.d.ts

@@ -0,0 +1,13 @@
+export interface InstrumentOptions {
+    sessionId: string;
+    relayUrl: string;
+    captureConsole?: boolean;
+    captureNetwork?: boolean;
+    captureTrace?: boolean;
+}
+/**
+ * Install the diagnostics instrumentation. Returns a teardown that fully
+ * restores the originals — important so dev double-mounts (React StrictMode)
+ * don't stack patches. Idempotent per window via a guard.
+ */
+export declare function installInstrumentation(opts: InstrumentOptions): () => void;

package/dist/client/instrument.js

@@ -0,0 +1,160 @@
+// The imperative shell: patch console.* and wrap fetch/XHR so every log and
+// request becomes a DiagEvent handed to the buffer. Kept deliberately thin —
+// all the formatting/batching decisions live in serialize.ts + buffer.ts. This
+// file only does the monkey-patching and owns the WebSocket.
+import { EventBuffer } from "./buffer.js";
+import { startSampler } from "./sampler.js";
+import { describeRequest, makeLogEvent, makeNetworkEvent } from "./serialize.js";
+const LEVELS = ["log", "info", "warn", "error", "debug"];
+/**
+ * Install the diagnostics instrumentation. Returns a teardown that fully
+ * restores the originals — important so dev double-mounts (React StrictMode)
+ * don't stack patches. Idempotent per window via a guard.
+ */
+export function installInstrumentation(opts) {
+    const w = window;
+    if (w.__vincenttHarness)
+        return () => undefined;
+    w.__vincenttHarness = true;
+    const socket = openSocket(opts.relayUrl);
+    const buffer = new EventBuffer({
+        sessionId: opts.sessionId,
+        send: (batch) => {
+            if (socket.ready()) {
+                socket.send(JSON.stringify(batch));
+                return true;
+            }
+            return false;
+        },
+    });
+    const restores = [];
+    if (opts.captureConsole !== false) {
+        restores.push(patchConsole(buffer));
+    }
+    if (opts.captureNetwork !== false) {
+        restores.push(patchFetch(buffer));
+        restores.push(patchXHR(buffer));
+    }
+    if (opts.captureTrace !== false) {
+        restores.push(startSampler(buffer));
+    }
+    return () => {
+        restores.forEach((r) => r());
+        socket.close();
+        w.__vincenttHarness = false;
+    };
+}
+/** A tiny reconnecting WebSocket wrapper. */
+function openSocket(url) {
+    let ws = null;
+    let closed = false;
+    const connect = () => {
+        if (closed)
+            return;
+        try {
+            ws = new WebSocket(url);
+            ws.onclose = () => {
+                ws = null;
+                if (!closed)
+                    setTimeout(connect, 1000);
+            };
+            ws.onerror = () => ws?.close();
+        }
+        catch {
+            if (!closed)
+                setTimeout(connect, 1000);
+        }
+    };
+    connect();
+    return {
+        ready: () => ws?.readyState === WebSocket.OPEN,
+        send: (data) => ws?.send(data),
+        close: () => {
+            closed = true;
+            ws?.close();
+        },
+    };
+}
+function patchConsole(buffer) {
+    const original = {};
+    for (const level of LEVELS) {
+        // eslint-disable-next-line no-console
+        const orig = console[level];
+        original[level] = orig;
+        // eslint-disable-next-line no-console
+        console[level] = (...args) => {
+            try {
+                const seq = buffer.nextSeq();
+                buffer.add(makeLogEvent(level, args, seq, Date.now()));
+            }
+            catch {
+                // Never let instrumentation break the app's own logging.
+            }
+            orig.apply(console, args);
+        };
+    }
+    return () => {
+        for (const level of LEVELS) {
+            if (original[level]) {
+                // eslint-disable-next-line no-console
+                console[level] = original[level];
+            }
+        }
+    };
+}
+function patchFetch(buffer) {
+    if (typeof window.fetch !== "function")
+        return () => undefined;
+    const orig = window.fetch.bind(window);
+    window.fetch = async (input, init) => {
+        const desc = describeRequest(input, init);
+        const start = Date.now();
+        try {
+            const res = await orig(input, init);
+            record(buffer, desc, res.status, Date.now() - start);
+            return res;
+        }
+        catch (err) {
+            record(buffer, desc, 0, Date.now() - start, err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    };
+    return () => {
+        window.fetch = orig;
+    };
+}
+function patchXHR(buffer) {
+    const OrigXHR = window.XMLHttpRequest;
+    if (typeof OrigXHR !== "function")
+        return () => undefined;
+    const openOrig = OrigXHR.prototype.open;
+    const sendOrig = OrigXHR.prototype.send;
+    OrigXHR.prototype.open = function (method, url) {
+        this.__h = describeRequest(typeof url === "string" ? url : url.toString(), { method });
+        // eslint-disable-next-line prefer-rest-params
+        return openOrig.apply(this, arguments);
+    };
+    OrigXHR.prototype.send = function (...rest) {
+        const meta = this.__h;
+        const start = Date.now();
+        if (meta) {
+            this.addEventListener("loadend", () => {
+                record(buffer, meta, this.status, Date.now() - start, this.status === 0 ? "network error" : undefined);
+            });
+        }
+        return sendOrig.apply(this, rest);
+    };
+    return () => {
+        OrigXHR.prototype.open = openOrig;
+        OrigXHR.prototype.send = sendOrig;
+    };
+}
+function record(buffer, desc, status, durationMs, error) {
+    try {
+        const seq = buffer.nextSeq();
+        buffer.add(makeNetworkEvent(desc, status, durationMs, seq, Date.now(), error));
+    }
+    catch {
+        // swallow — diagnostics must never break the request path
+    }
+}

package/dist/client/sampler.d.ts

@@ -0,0 +1,11 @@
+import { EventBuffer } from "./buffer.js";
+export interface SamplerOptions {
+    /** How often to emit a TraceEvent, ms. */
+    windowMs?: number;
+}
+/**
+ * Start sampling. Returns a teardown. Degrades gracefully where APIs are
+ * missing (PerformanceObserver / longtask are not universal) — fps still works
+ * from rAF alone, which is the signal that mattered for the readback finding.
+ */
+export declare function startSampler(buffer: EventBuffer, opts?: SamplerOptions): () => void;

package/dist/client/sampler.js

@@ -0,0 +1,72 @@
+// The imperative perf sampler: drive a TraceAccumulator from real browser
+// signals (rAF for frames, PerformanceObserver for long tasks + marks) and
+// flush one TraceEvent per window into the buffer. Thin shell — all the math is
+// in trace.ts. instrument.ts installs this alongside the console/network
+// patches when the trace tier is on.
+import { TraceAccumulator } from "./trace.js";
+/**
+ * Start sampling. Returns a teardown. Degrades gracefully where APIs are
+ * missing (PerformanceObserver / longtask are not universal) — fps still works
+ * from rAF alone, which is the signal that mattered for the readback finding.
+ */
+export function startSampler(buffer, opts = {}) {
+    if (typeof requestAnimationFrame !== "function")
+        return () => undefined;
+    const windowMs = opts.windowMs ?? 5000;
+    const acc = new TraceAccumulator();
+    let rafId = null;
+    let stopped = false;
+    const onFrame = (t) => {
+        if (stopped)
+            return;
+        acc.frame(t);
+        rafId = requestAnimationFrame(onFrame);
+    };
+    rafId = requestAnimationFrame(onFrame);
+    let observer = null;
+    if (typeof PerformanceObserver === "function") {
+        try {
+            observer = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    if (entry.entryType === "longtask")
+                        acc.task(entry.duration);
+                    else if (entry.entryType === "mark")
+                        acc.mark(entry.name);
+                }
+            });
+            // longtask isn't supported everywhere (notably iOS Safari) — try each
+            // type independently so one unsupported type doesn't kill the others.
+            trySubscribe(observer, "longtask");
+            trySubscribe(observer, "mark");
+        }
+        catch {
+            observer = null;
+        }
+    }
+    const timer = setInterval(() => {
+        if (!acc.hasSamples())
+            return;
+        const seq = buffer.nextSeq();
+        buffer.add(acc.summarize(performanceNow(), seq));
+    }, windowMs);
+    return () => {
+        stopped = true;
+        if (rafId !== null)
+            cancelAnimationFrame(rafId);
+        clearInterval(timer);
+        observer?.disconnect();
+    };
+}
+function trySubscribe(observer, type) {
+    try {
+        observer.observe({ type, buffered: true });
+    }
+    catch {
+        // this entry type isn't supported here; the others still work
+    }
+}
+function performanceNow() {
+    return typeof performance !== "undefined"
+        ? performance.timeOrigin + performance.now()
+        : Date.now();
+}

package/dist/client/serialize.d.ts

@@ -0,0 +1,32 @@
+import type { LogEvent, NetworkEvent } from "../shared/events.js";
+/**
+ * Safely stringify one console argument. The phone's console is fed anything —
+ * Errors, DOM nodes, cyclic objects, huge arrays — and this has to survive all
+ * of them without throwing (a throwing logger would take the app down) and
+ * without shipping megabytes over the socket.
+ */
+export declare function stringifyArg(arg: unknown, maxLen?: number): string;
+/** Join console.* varargs into one message the way the devtools console would. */
+export declare function formatLogArgs(args: unknown[], maxLen?: number): string;
+/** Build a LogEvent from a console call. seq/t are supplied by the buffer. */
+export declare function makeLogEvent(level: LogEvent["level"], args: unknown[], seq: number, t: number): LogEvent;
+/** First stack frame that isn't runtime/library noise, best-effort. */
+export declare function firstAppFrame(err?: Error): string | undefined;
+/**
+ * Normalize the many shapes fetch() is called with (string, URL, Request) into
+ * a {method, url} pair without consuming the body.
+ */
+export declare function describeRequest(input: string | URL | {
+    url?: string;
+    method?: string;
+}, init?: {
+    method?: string;
+}): {
+    method: string;
+    url: string;
+};
+/** Build a NetworkEvent from a settled request. */
+export declare function makeNetworkEvent(desc: {
+    method: string;
+    url: string;
+}, status: number, durationMs: number, seq: number, t: number, error?: string): NetworkEvent;

package/dist/client/serialize.js

@@ -0,0 +1,99 @@
+// Pure event-shaping for the in-app client. The imperative shell (patching
+// console, wrapping fetch) lives in instrument.ts and calls into here, so all
+// the fiddly formatting logic is testable without a browser.
+/**
+ * Safely stringify one console argument. The phone's console is fed anything —
+ * Errors, DOM nodes, cyclic objects, huge arrays — and this has to survive all
+ * of them without throwing (a throwing logger would take the app down) and
+ * without shipping megabytes over the socket.
+ */
+export function stringifyArg(arg, maxLen = 2000) {
+    if (typeof arg === "string")
+        return truncate(arg, maxLen);
+    if (arg instanceof Error) {
+        return truncate(`${arg.name}: ${arg.message}${arg.stack ? `\n${arg.stack}` : ""}`, maxLen);
+    }
+    if (typeof arg === "number" || typeof arg === "boolean" || arg == null) {
+        return String(arg);
+    }
+    if (typeof arg === "function")
+        return `[Function: ${arg.name || "anonymous"}]`;
+    try {
+        return truncate(JSON.stringify(arg, cyclicSafeReplacer()), maxLen);
+    }
+    catch {
+        return truncate(String(arg), maxLen);
+    }
+}
+/** Join console.* varargs into one message the way the devtools console would. */
+export function formatLogArgs(args, maxLen = 2000) {
+    return truncate(args.map((a) => stringifyArg(a, maxLen)).join(" "), maxLen);
+}
+function truncate(s, maxLen) {
+    return s.length > maxLen ? `${s.slice(0, maxLen)}… (${s.length - maxLen} more)` : s;
+}
+/** A JSON.stringify replacer that renders cyclic refs as a marker, not a throw. */
+function cyclicSafeReplacer() {
+    const seen = new WeakSet();
+    return (_key, value) => {
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value))
+                return "[Circular]";
+            seen.add(value);
+        }
+        return value;
+    };
+}
+/** Build a LogEvent from a console call. seq/t are supplied by the buffer. */
+export function makeLogEvent(level, args, seq, t) {
+    const message = formatLogArgs(args);
+    // For errors, surface the first meaningful stack frame so the agent can jump
+    // to a file:line without the whole trace.
+    const origin = level === "error"
+        ? firstAppFrame(args.find((a) => a instanceof Error))
+        : undefined;
+    return origin
+        ? { kind: "log", level, message, seq, t, origin }
+        : { kind: "log", level, message, seq, t };
+}
+/** First stack frame that isn't runtime/library noise, best-effort. */
+export function firstAppFrame(err) {
+    if (!err?.stack)
+        return undefined;
+    const lines = err.stack.split("\n").slice(1);
+    const appLine = lines.find((l) => !l.includes("node_modules") &&
+        !l.includes("/harness/") &&
+        !l.includes("node:") &&
+        l.trim().startsWith("at "));
+    return appLine?.trim();
+}
+/**
+ * Normalize the many shapes fetch() is called with (string, URL, Request) into
+ * a {method, url} pair without consuming the body.
+ */
+export function describeRequest(input, init) {
+    let url = "";
+    let method = init?.method;
+    if (typeof input === "string")
+        url = input;
+    else if (input instanceof URL)
+        url = input.toString();
+    else {
+        url = input.url ?? "";
+        method = method ?? input.method;
+    }
+    return { method: (method ?? "GET").toUpperCase(), url };
+}
+/** Build a NetworkEvent from a settled request. */
+export function makeNetworkEvent(desc, status, durationMs, seq, t, error) {
+    const base = {
+        kind: "network",
+        method: desc.method,
+        url: desc.url,
+        status,
+        durationMs: Math.round(durationMs),
+        seq,
+        t,
+    };
+    return error ? { ...base, error } : base;
+}