@fixback/sdk-core 0.2.0 → 0.3.0

package/dist/stack.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * The **one stack parser** every Fixback SDK shares (ADR-0028): a single frame
+ * tokenizer ({@link parseStackLine}) and the structured-frame extraction the wire
+ * carries ({@link extractStructuredFrames}).
+ *
+ * Three consumers read a stack, and each used to carry its own copy of the same
+ * regexes: the fingerprint's compact top-frames signature (`fingerprint.ts`), the
+ * console crumb's `file:line` source (`trace/source.ts`), and the structured
+ * frames server-side symbolication matches against uploaded sourcemaps
+ * (`extractStructuredFrames`, #117 / ADR-0024). They now all tokenize a frame the
+ * same way, so a stack that parses on one surface parses identically on every
+ * other — the parity guarantee the shared fingerprint depends on.
+ *
+ * Both engine dialects are handled: V8/Hermes (`at fn (loc)` / `at loc`) and
+ * JSC/SpiderMonkey (`fn@loc` / `@loc`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStackLine = parseStackLine;
+exports.parseFrameLocation = parseFrameLocation;
+exports.extractStructuredFrames = extractStructuredFrames;
+const scrub_1 = require("./scrub");
+/** The most structured frames shipped per report (mirrors the server's cap). */
+const STRUCTURED_FRAME_LIMIT = 30;
+/**
+ * Tokenize one **trimmed** stack line into its function name and raw location, or
+ * `null` when the line is not a frame at all (the leading `Error: message`, a
+ * blank line). The single place the two engine dialects are recognised — every
+ * other stack reader in the core builds on this.
+ */
+function parseStackLine(line) {
+    // V8 / Hermes: "at fn (loc)"
+    const v8Named = line.match(/^at\s+(.+?)\s+\((.+)\)$/);
+    if (v8Named)
+        return { fn: v8Named[1] ?? null, location: v8Named[2] ?? "" };
+    // V8 / Hermes: "at loc"
+    const v8Bare = line.match(/^at\s+(.+)$/);
+    if (v8Bare)
+        return { fn: null, location: v8Bare[1] ?? "" };
+    // JSC / SpiderMonkey: "fn@loc" | "@loc"
+    const at = line.indexOf("@");
+    if (at >= 0) {
+        return { fn: at > 0 ? line.slice(0, at) : null, location: line.slice(at + 1) };
+    }
+    return null;
+}
+/**
+ * Split a `file:line:col` location into its parts; `null` when it carries no line
+ * number or names no locatable file. The file may itself contain colons
+ * (`https://…`, `node:internal/…`), so the numeric groups are taken from the right.
+ * Unlocatable frames (`native`, `<anonymous>`, eval) are rejected here.
+ */
+function parseFrameLocation(location) {
+    const match = location.match(/^(.*?):(\d+)(?::(\d+))?$/);
+    if (!match)
+        return null;
+    const file = match[1] ?? "";
+    if (file.length === 0 || file === "native" || file.includes("<anonymous>")) {
+        return null;
+    }
+    const line = Number(match[2]);
+    if (!Number.isFinite(line))
+        return null;
+    const column = match[3] !== undefined ? Number(match[3]) : null;
+    return { file, line, column };
+}
+/**
+ * Extract **structured** frames from a stack for the wire (#117, ADR-0024), top of
+ * stack first — unlike the fingerprint's compact signature (which drops the origin
+ * so a per-deploy asset hash cannot split a bug), these keep the full script path,
+ * because server-side symbolication matches it against uploaded sourcemap paths.
+ * Each URL is scrubbed (query dropped, path PII redacted) before it can leave the
+ * process; unlocatable frames are skipped; the count is capped.
+ */
+function extractStructuredFrames(stack, limit = STRUCTURED_FRAME_LIMIT) {
+    if (typeof stack !== "string" || stack.length === 0)
+        return [];
+    const frames = [];
+    for (const raw of stack.split("\n")) {
+        if (frames.length >= limit)
+            break;
+        const tokens = parseStackLine(raw.trim());
+        if (!tokens || !tokens.location)
+            continue;
+        const parsed = parseFrameLocation(tokens.location);
+        if (!parsed)
+            continue;
+        frames.push({
+            file: (0, scrub_1.scrubUrl)(parsed.file),
+            line: parsed.line,
+            column: parsed.column,
+            function: tokens.fn && tokens.fn.length > 0 ? tokens.fn : null,
+        });
+    }
+    return frames;
+}
+//# sourceMappingURL=stack.js.map

package/dist/stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.js","sourceRoot":"","sources":["../src/stack.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AAsBH,wCAaC;AAQD,gDAaC;AAUD,0DAoBC;AApFD,mCAAmC;AAGnC,gFAAgF;AAChF,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAUlC;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,IAAY;IACzC,6BAA6B;IAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACtD,IAAI,OAAO;QAAE,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAC3E,wBAAwB;IACxB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACzC,IAAI,MAAM;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAC3D,wCAAwC;IACxC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACZ,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;IACjF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAChC,QAAgB;IAEhB,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,uBAAuB,CACrC,KAAyB,EACzB,KAAK,GAAG,sBAAsB;IAE9B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC/D,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK;YAAE,MAAM;QAClC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,SAAS;QAC1C,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,IAAA,gBAAQ,EAAC,MAAM,CAAC,IAAI,CAAC;YAC3B,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;SAC/D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/trace/buffer.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The trace **ring buffer** (spec #122 §A/§B, decision D6) — the shared,
+ * runtime-agnostic store every Fixback capture SDK records crumbs into (ADR-0028).
+ *
+ * It holds **three independent FIFO rings** — `network`, `console`,
+ * `breadcrumbs` — each trimmed to its own budget so a chatty stream never evicts
+ * another's lead-up, plus a shared age cap. On `add`, a crumb passes through
+ * `beforeBreadcrumb`, is stamped with a stable `id` and a high-res `mono`
+ * timestamp (and an epoch `timestamp` if it has none), routed to its stream, then
+ * that stream is pruned by age and trimmed to its budget. `snapshot` prunes by age
+ * again, then merges the three streams into one `mono`-ordered array for transport
+ * — so the wire keeps its single `trace` field.
+ *
+ * Nothing here touches a DOM or a Node built-in: the instrumentation that *produces*
+ * crumbs lives in the consuming SDK, and the clocks are injectable so the buffer is
+ * unit-tested deterministically.
+ */
+import type { Breadcrumb, BreadcrumbLevel } from "../breadcrumb";
+/**
+ * The three independent trace streams (spec #122 §A, decision D6). Each is its own
+ * FIFO ring with its own size budget, so a chatty stream can't evict another's
+ * lead-up. Every crumb category maps to exactly one stream via {@link streamOf}.
+ */
+export type TraceStream = "network" | "console" | "breadcrumbs";
+/**
+ * Per-stream ring budgets — starting points from the grill (D6): network is the
+ * chattiest, breadcrumbs the sparsest. Per-project tunable, never frozen.
+ */
+export declare const DEFAULT_STREAM_BUDGETS: Readonly<Record<TraceStream, number>>;
+/**
+ * The shared age cap (spec #122 §A): entries older than this are pruned from every
+ * stream, whichever trims first. ~3 minutes and **on** by default, so an idle tab
+ * (or a backgrounded app) never ships stale context.
+ */
+export declare const DEFAULT_MAX_AGE_MS: number;
+/**
+ * Console levels captured by default (spec #122 §C, decision D7): **all** of them, so
+ * the Console tab is a real console and not just an error log. Eviction priority (not
+ * capture) is what keeps a chatty app's `log`/`info`/`debug` from burying the signal —
+ * see {@link PINNED_CONSOLE_LEVELS}.
+ */
+export declare const DEFAULT_CONSOLE_LEVELS: readonly BreadcrumbLevel[];
+/**
+ * The console levels **pinned** against eviction (spec #122 §C, decision D7). When the
+ * console stream overflows its budget, `warn`/`error`/`assert` are retained ahead of
+ * `log`/`info`/`debug`, so an error is never evicted by a burst of chatter — the
+ * low-priority levels fill the remainder and are dropped first.
+ */
+export declare const PINNED_CONSOLE_LEVELS: readonly BreadcrumbLevel[];
+/** Whether a console level is pinned against eviction (see {@link PINNED_CONSOLE_LEVELS}). */
+export declare function isPinnedConsoleLevel(level: BreadcrumbLevel | undefined): boolean;
+/**
+ * The console levels for which `source` (`file:line`) is captured (ticket #159).
+ *
+ * Capturing a call site constructs a `new Error()` to read its stack on **every** console
+ * call — a measurable hot-page cost when a chatty app logs in a tight loop. The
+ * spec-sanctioned mitigation (decision D7) narrows source capture to the **levels that
+ * matter for debugging** — the same `warn`/`error`/`assert` that are pinned against
+ * eviction — so `log`/`info`/`debug` pay no per-call stack cost and simply omit `source`.
+ * Per-project tunability of this set is future work; today it deliberately mirrors
+ * {@link PINNED_CONSOLE_LEVELS} so "what survives eviction" and "what carries a call
+ * site" stay one idea.
+ */
+export declare const SOURCE_CAPTURE_LEVELS: readonly BreadcrumbLevel[];
+/** Whether a console level captures `source` `file:line` (see {@link SOURCE_CAPTURE_LEVELS}). */
+export declare function capturesSource(level: BreadcrumbLevel): boolean;
+/**
+ * Which stream a crumb's category belongs to (spec #122 §A). Network APIs
+ * (`fetch` / `xhr` / `beacon`) form the network stream, `console` its own, and
+ * everything else (navigation, masked UI events, the failing error) breadcrumbs.
+ */
+export declare function streamOf(category: string): TraceStream;
+/** Filters or edits each crumb before it enters the buffer; `null` drops it. */
+export type BeforeBreadcrumb = (crumb: Breadcrumb) => Breadcrumb | null;
+/** Configuration for {@link createBreadcrumbBuffer}. All values are optional. */
+export interface BreadcrumbBufferConfig {
+    /**
+     * Per-stream size budgets (oldest drop, independently per stream). Any stream
+     * omitted falls back to {@link DEFAULT_STREAM_BUDGETS}.
+     */
+    readonly budgets?: Partial<Record<TraceStream, number>>;
+    /**
+     * Shared age cap in ms: entries older than this are dropped from every stream.
+     * Defaults to {@link DEFAULT_MAX_AGE_MS} (on); pass `0` (or a non-positive value)
+     * to disable age pruning.
+     */
+    readonly maxAgeMs?: number;
+    /** A per-crumb filter (mute a category, edit, or drop by returning `null`). */
+    readonly beforeBreadcrumb?: BeforeBreadcrumb | null;
+    /** Epoch clock source, injectable for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** High-res monotonic clock, injectable for tests. Defaults to {@link nowMono}. */
+    readonly mono?: () => number;
+    /** Stable id generator, injectable for tests. Defaults to a per-buffer sequence. */
+    readonly nextId?: () => string;
+}
+/** A live trace buffer. */
+export interface BreadcrumbBuffer {
+    /** Record a crumb (subject to `beforeBreadcrumb`, id/mono stamping, size, and age trimming). */
+    add(crumb: Breadcrumb): void;
+    /** The current crumbs, merged across streams and ordered in time — a fresh array. */
+    snapshot(): Breadcrumb[];
+    /** Drop every crumb. */
+    clear(): void;
+}
+/** Coerce a configured budget to a usable positive integer, else the default. */
+export declare function normalizeBudget(value: number | undefined, fallback: number): number;
+/** A per-buffer id factory: a short random salt + a base-36 sequence, stable once assigned. */
+export declare function createIdFactory(): () => string;
+/**
+ * Trim the **console** stream to its budget with eviction priority (spec #122 §C,
+ * decision D7): `warn`/`error`/`assert` are pinned, so the oldest `log`/`info`/`debug`
+ * entries are dropped first; a pinned entry is evicted only when dropping every
+ * low-priority one still leaves the stream over budget (oldest pinned first). Survivors
+ * keep their insertion order. A plain FIFO `slice(-budget)` handles every other stream.
+ */
+export declare function trimConsoleStream<T extends {
+    readonly crumb: Breadcrumb;
+}>(held: T[], budget: number): T[];
+/** Create the per-stream trace buffer. See the module doc. */
+export declare function createBreadcrumbBuffer(config?: BreadcrumbBufferConfig): BreadcrumbBuffer;

package/dist/trace/buffer.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * The trace **ring buffer** (spec #122 §A/§B, decision D6) — the shared,
+ * runtime-agnostic store every Fixback capture SDK records crumbs into (ADR-0028).
+ *
+ * It holds **three independent FIFO rings** — `network`, `console`,
+ * `breadcrumbs` — each trimmed to its own budget so a chatty stream never evicts
+ * another's lead-up, plus a shared age cap. On `add`, a crumb passes through
+ * `beforeBreadcrumb`, is stamped with a stable `id` and a high-res `mono`
+ * timestamp (and an epoch `timestamp` if it has none), routed to its stream, then
+ * that stream is pruned by age and trimmed to its budget. `snapshot` prunes by age
+ * again, then merges the three streams into one `mono`-ordered array for transport
+ * — so the wire keeps its single `trace` field.
+ *
+ * Nothing here touches a DOM or a Node built-in: the instrumentation that *produces*
+ * crumbs lives in the consuming SDK, and the clocks are injectable so the buffer is
+ * unit-tested deterministically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOURCE_CAPTURE_LEVELS = exports.PINNED_CONSOLE_LEVELS = exports.DEFAULT_CONSOLE_LEVELS = exports.DEFAULT_MAX_AGE_MS = exports.DEFAULT_STREAM_BUDGETS = void 0;
+exports.isPinnedConsoleLevel = isPinnedConsoleLevel;
+exports.capturesSource = capturesSource;
+exports.streamOf = streamOf;
+exports.normalizeBudget = normalizeBudget;
+exports.createIdFactory = createIdFactory;
+exports.trimConsoleStream = trimConsoleStream;
+exports.createBreadcrumbBuffer = createBreadcrumbBuffer;
+const env_1 = require("../env");
+/**
+ * Per-stream ring budgets — starting points from the grill (D6): network is the
+ * chattiest, breadcrumbs the sparsest. Per-project tunable, never frozen.
+ */
+exports.DEFAULT_STREAM_BUDGETS = {
+    network: 100,
+    console: 80,
+    breadcrumbs: 40,
+};
+/**
+ * The shared age cap (spec #122 §A): entries older than this are pruned from every
+ * stream, whichever trims first. ~3 minutes and **on** by default, so an idle tab
+ * (or a backgrounded app) never ships stale context.
+ */
+exports.DEFAULT_MAX_AGE_MS = 3 * 60 * 1000;
+/**
+ * Console levels captured by default (spec #122 §C, decision D7): **all** of them, so
+ * the Console tab is a real console and not just an error log. Eviction priority (not
+ * capture) is what keeps a chatty app's `log`/`info`/`debug` from burying the signal —
+ * see {@link PINNED_CONSOLE_LEVELS}.
+ */
+exports.DEFAULT_CONSOLE_LEVELS = [
+    "log",
+    "info",
+    "warn",
+    "error",
+    "assert",
+    "debug",
+];
+/**
+ * The console levels **pinned** against eviction (spec #122 §C, decision D7). When the
+ * console stream overflows its budget, `warn`/`error`/`assert` are retained ahead of
+ * `log`/`info`/`debug`, so an error is never evicted by a burst of chatter — the
+ * low-priority levels fill the remainder and are dropped first.
+ */
+exports.PINNED_CONSOLE_LEVELS = [
+    "warn",
+    "error",
+    "assert",
+];
+/** Whether a console level is pinned against eviction (see {@link PINNED_CONSOLE_LEVELS}). */
+function isPinnedConsoleLevel(level) {
+    return level !== undefined && exports.PINNED_CONSOLE_LEVELS.includes(level);
+}
+/**
+ * The console levels for which `source` (`file:line`) is captured (ticket #159).
+ *
+ * Capturing a call site constructs a `new Error()` to read its stack on **every** console
+ * call — a measurable hot-page cost when a chatty app logs in a tight loop. The
+ * spec-sanctioned mitigation (decision D7) narrows source capture to the **levels that
+ * matter for debugging** — the same `warn`/`error`/`assert` that are pinned against
+ * eviction — so `log`/`info`/`debug` pay no per-call stack cost and simply omit `source`.
+ * Per-project tunability of this set is future work; today it deliberately mirrors
+ * {@link PINNED_CONSOLE_LEVELS} so "what survives eviction" and "what carries a call
+ * site" stay one idea.
+ */
+exports.SOURCE_CAPTURE_LEVELS = exports.PINNED_CONSOLE_LEVELS;
+/** Whether a console level captures `source` `file:line` (see {@link SOURCE_CAPTURE_LEVELS}). */
+function capturesSource(level) {
+    return exports.SOURCE_CAPTURE_LEVELS.includes(level);
+}
+/**
+ * Which stream a crumb's category belongs to (spec #122 §A). Network APIs
+ * (`fetch` / `xhr` / `beacon`) form the network stream, `console` its own, and
+ * everything else (navigation, masked UI events, the failing error) breadcrumbs.
+ */
+function streamOf(category) {
+    if (category === "console")
+        return "console";
+    if (category === "fetch" || category === "xhr" || category === "beacon") {
+        return "network";
+    }
+    return "breadcrumbs";
+}
+/** Coerce a configured budget to a usable positive integer, else the default. */
+function normalizeBudget(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
+/** A per-buffer id factory: a short random salt + a base-36 sequence, stable once assigned. */
+function createIdFactory() {
+    const salt = Math.random().toString(36).slice(2, 8);
+    let seq = 0;
+    return () => `${salt}${(seq++).toString(36)}`;
+}
+/** The streams, in a fixed order for a deterministic merge. */
+const STREAMS = ["network", "console", "breadcrumbs"];
+/**
+ * Trim the **console** stream to its budget with eviction priority (spec #122 §C,
+ * decision D7): `warn`/`error`/`assert` are pinned, so the oldest `log`/`info`/`debug`
+ * entries are dropped first; a pinned entry is evicted only when dropping every
+ * low-priority one still leaves the stream over budget (oldest pinned first). Survivors
+ * keep their insertion order. A plain FIFO `slice(-budget)` handles every other stream.
+ */
+function trimConsoleStream(held, budget) {
+    const over = held.length - budget;
+    if (over <= 0)
+        return held;
+    const drop = new Set();
+    // First: oldest low-priority (not pinned) entries, until enough room is freed.
+    for (let i = 0; i < held.length && drop.size < over; i += 1) {
+        if (!isPinnedConsoleLevel(held[i].crumb.level))
+            drop.add(i);
+    }
+    // Then, only if the low-priority ones weren't enough: oldest pinned entries.
+    for (let i = 0; i < held.length && drop.size < over; i += 1) {
+        if (!drop.has(i))
+            drop.add(i);
+    }
+    return held.filter((_, i) => !drop.has(i));
+}
+/** Create the per-stream trace buffer. See the module doc. */
+function createBreadcrumbBuffer(config = {}) {
+    const budgets = {
+        network: normalizeBudget(config.budgets?.network, exports.DEFAULT_STREAM_BUDGETS.network),
+        console: normalizeBudget(config.budgets?.console, exports.DEFAULT_STREAM_BUDGETS.console),
+        breadcrumbs: normalizeBudget(config.budgets?.breadcrumbs, exports.DEFAULT_STREAM_BUDGETS.breadcrumbs),
+    };
+    const maxAgeMs = config.maxAgeMs === undefined ? exports.DEFAULT_MAX_AGE_MS : config.maxAgeMs;
+    const beforeBreadcrumb = config.beforeBreadcrumb;
+    const now = config.now ?? Date.now;
+    const mono = config.mono ?? env_1.nowMono;
+    const nextId = config.nextId ?? createIdFactory();
+    const streams = {
+        network: [],
+        console: [],
+        breadcrumbs: [],
+    };
+    let seq = 0;
+    function pruneByAge() {
+        if (typeof maxAgeMs !== "number" || maxAgeMs <= 0)
+            return;
+        const cutoff = now() - maxAgeMs;
+        for (const stream of STREAMS) {
+            const held = streams[stream];
+            if (held.length > 0) {
+                streams[stream] = held.filter((h) => h.crumb.timestamp >= cutoff);
+            }
+        }
+    }
+    return {
+        add(crumb) {
+            let entry = crumb;
+            if (beforeBreadcrumb) {
+                try {
+                    entry = beforeBreadcrumb(crumb);
+                }
+                catch {
+                    // A throwing filter must never break capture; keep the (already
+                    // masked) crumb rather than silently erasing the trace.
+                    entry = crumb;
+                }
+            }
+            if (!entry)
+                return;
+            // Stamp a stable id + high-res mono (and an epoch timestamp if absent) so
+            // every entry orders and cross-links exactly, whatever stream it lands in.
+            const stamped = {
+                ...entry,
+                id: entry.id ?? nextId(),
+                timestamp: typeof entry.timestamp === "number" ? entry.timestamp : now(),
+                mono: typeof entry.mono === "number" ? entry.mono : mono(),
+            };
+            const stream = streamOf(stamped.category);
+            streams[stream].push({ crumb: stamped, seq: seq++ });
+            // Age-prune every stream first (it may reassign the array), then trim this
+            // stream to its own budget — a flood here never evicts another stream.
+            pruneByAge();
+            const held = streams[stream];
+            const budget = budgets[stream];
+            if (held.length > budget) {
+                streams[stream] =
+                    stream === "console"
+                        ? trimConsoleStream(held, budget)
+                        : held.slice(-budget);
+            }
+        },
+        snapshot() {
+            pruneByAge();
+            const merged = [];
+            for (const stream of STREAMS)
+                merged.push(...streams[stream]);
+            // Order in time by the high-res mono clock (every entry has one), with the
+            // insertion sequence as a stable tiebreak so equal clocks never scramble.
+            merged.sort((a, b) => {
+                const am = typeof a.crumb.mono === "number" ? a.crumb.mono : a.crumb.timestamp;
+                const bm = typeof b.crumb.mono === "number" ? b.crumb.mono : b.crumb.timestamp;
+                return am - bm || a.seq - b.seq;
+            });
+            return merged.map((h) => h.crumb);
+        },
+        clear() {
+            streams.network = [];
+            streams.console = [];
+            streams.breadcrumbs = [];
+            seq = 0;
+        },
+    };
+}
+//# sourceMappingURL=buffer.js.map

package/dist/trace/buffer.js.map

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

package/dist/trace/console-args.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Structured **console arguments** (spec #122 §C, decision D7) — the shared,
+ * runtime-agnostic assembly that turns a `console.*` call's arguments into
+ * type-tagged, JSON-safe, size-capped {@link ConsoleArg} values, plus the one-line
+ * preview the crumb's `message` carries.
+ *
+ * Preserving arguments type-tagged rather than flattening them to a string is what
+ * lets the Console tab render an object or an Error expandably instead of
+ * `[object Object]`. Every cap is applied **at assembly**, so a single console
+ * crumb can never bloat a report and an exotic or circular value can never reach
+ * the wire unserialized.
+ */
+import type { ConsoleArg } from "../breadcrumb";
+/** Longest crumb message kept; a huge log line is truncated, never dropped. */
+export declare const MAX_MESSAGE_LENGTH = 300;
+/**
+ * Structured console argument caps (spec #122 §C/§F), all applied **at assembly** so a
+ * single console crumb can never bloat a report:
+ * - {@link MAX_ARG_DEPTH} bounds how deep a `json` argument is cloned (deeper nodes
+ *   collapse to an `[Object]`/`[Array]` marker);
+ * - {@link MAX_ARG_ITEMS} bounds how many keys/elements are kept at each level;
+ * - {@link MAX_ARG_STRING_LENGTH} truncates a single over-long string value;
+ * - {@link MAX_CONSOLE_ARGS_BYTES} bounds the serialized size of the whole args array
+ *   (trailing args are dropped to fit), kept well under ingest's per-entry byte cap.
+ */
+export declare const MAX_ARG_DEPTH = 4;
+export declare const MAX_ARG_ITEMS = 100;
+export declare const MAX_ARG_STRING_LENGTH = 1024;
+export declare const MAX_CONSOLE_ARGS_BYTES = 4096;
+/** Truncate a string to `max` with an ellipsis marker; keeps the value, never drops it. */
+export declare function capLength(value: string, max: number): string;
+/** Render one console argument to the flat text of the crumb's preview line. */
+export declare function stringifyArg(arg: unknown): string;
+/** The one-line preview a console crumb's `message` carries, length-capped. */
+export declare function joinArgs(args: readonly unknown[]): string;
+/** An Error rendered to a structured, size-capped `{ name, message, stack? }`. */
+export declare function describeErrorValue(error: Error): {
+    name: string;
+    message: string;
+    stack?: string;
+};
+/**
+ * Build a JSON-safe, depth-/breadth-/string-capped clone of a value for a `json`
+ * console argument. Beyond {@link MAX_ARG_DEPTH} the node collapses to a marker;
+ * at each level at most {@link MAX_ARG_ITEMS} keys/elements are kept; strings are
+ * truncated to {@link MAX_ARG_STRING_LENGTH}; circular references become
+ * `"[Circular]"`; and exotic values (bigint / symbol / function / undefined) are
+ * rendered to safe text — so the result is always serializable and bounded.
+ */
+export declare function safeCloneValue(value: unknown, depth: number, seen: Set<object>): unknown;
+/** Classify one console argument into a type-tagged {@link ConsoleArg} (spec #122 §C). */
+export declare function toConsoleArg(value: unknown): ConsoleArg;
+/**
+ * Cap an entry's structured args to {@link MAX_CONSOLE_ARGS_BYTES} (spec #122 §F):
+ * drop trailing args until the array fits, keeping the earliest (usually the format
+ * string / main message); if even a single arg is over budget, keep one honest
+ * placeholder rather than an unbounded value. Per-arg depth/breadth/string caps bound
+ * most cases already — this is the whole-entry backstop.
+ */
+export declare function capConsoleArgs(args: ConsoleArg[]): ConsoleArg[];