margin-meter 0.1.0 → 0.3.0

package/dist/index.js

@@ -21,11 +21,158 @@
  *    written `source` is forced server-side to the key's project slug — the
  *    client cannot spoof another project's economics.
  */
+import { extractUsage, StreamUsageAccumulator, } from "./providers.js";
+import { BATCH_PATH, Batcher, SHUTDOWN_TIMEOUT_MS, } from "./batching.js";
+// The Node analogue of Python's `contextvars`: it carries a value across the
+// async/await chain of the callback it runs, so a call metered several awaits
+// deep inside `stage(...)` still sees the enclosing step. `node:async_hooks` is
+// a Node builtin (stable since 16; this package requires node>=18) and is
+// present in Bun and the edge runtimes too. It is the ONE thing `stage`/`span`
+// need that a browser bundle would not have — and those primitives are the whole
+// reason to reach for it — so a caller instrumenting server-side agent code (the
+// only place an LLM key belongs) always has it.
+import { AsyncLocalStorage } from "node:async_hooks";
+export * from "./providers.js";
+export * from "./instrument.js";
+export * from "./batching.js";
+// Namespaced, not flattened: `BEDROCK` means two different things here — the
+// provider that bills for the model and the path the request took — and merging
+// them into one barrel would collide the names and blur the distinction the
+// substrate dimension exists to draw. `substrate.BEDROCK` reads as the path.
+export * as substrate from "./substrate.js";
+// Namespaced: an eval adapter reuses common verb names (`recordResults`,
+// `outcomeInput`), so `promptfoo.recordResults(...)` keeps the framework it
+// bridges legible at the call site — the Python SDK's `margin_meter.promptfoo`
+// twin (`docs/INTEGRATION_LADDER.md` rung 2).
+export * as promptfoo from "./promptfoo.js";
+// The second eval adapter (rung 2), same namespaced shape — `braintrust.recordResults(...)`.
+export * as braintrust from "./braintrust.js";
+// The third eval adapter (rung 2), same namespaced shape — `langsmith.recordResults(...)`.
+export * as langsmith from "./langsmith.js";
+// The test-runner adapter (rung 2/6): one vitest/jest JSON file, every test an
+// outcome — `vitest.recordResults(...)`. The pytest plugin's TS twin.
+export * as vitest from "./vitest.js";
 export const CALLS_PATH = "/api/ingest/calls";
 export const OUTCOMES_PATH = "/api/ingest/outcomes";
 export const KEY_HEADER = "X-Margin-Key";
-export const DEFAULT_INGEST_URL = "http://127.0.0.1:8000";
+// ⛔ No default ingest URL, on purpose. It used to be `http://127.0.0.1:8000`, so a
+// meter given a key and no URL POSTed to the caller's own laptop and dropped every row
+// (a real authorized run on 2026-09-15 spent money and landed nothing that way). An
+// unset URL is refused as `no_url` at once, like `no_key`, never guessed.
 export const DEFAULT_TIMEOUT_MS = 10_000;
+/** One batched request's byte ceiling, and the retry policy behind it. Full
+ *  reasoning in `docs/reference/SDK_BATCHING.md`; the short version:
+ *
+ *  - 1 MB is ~7x headroom over a worst-case 1500-byte row at the default 100
+ *    records, and far under any gateway limit. Vercel accepts 100 MB bodies;
+ *    that is a ceiling, not a target.
+ *  - 3 attempts with FULL jitter rather than plain exponential, because every
+ *    buffered client backs off on the same schedule and un-jittered retries
+ *    re-synchronise into a herd aimed at the endpoint that just failed.
+ *  - Duplicates from an at-least-once retry are free: every record carries an
+ *    `event_id` and the server is idempotent on `(source, event_id)`.
+ */
+export const MAX_BATCH_BYTES = 1_000_000;
+export const RETRY_ATTEMPTS = 3;
+export const RETRY_BASE_MS = 1_000;
+export const RETRY_CAP_MS = 30_000;
+/** Statuses worth resending. Everything else (401, 422, 400) fails identically
+ *  next time, so retrying is a hot loop that never drains — and against a bad key
+ *  it would hammer us forever. */
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+/** A fresh idempotency key per emit. Uses the platform crypto UUID (Node 16.7+,
+ *  modern browsers); falls back to a random-hex id where crypto is absent, which
+ *  is still unique enough to key a single call's dedup. */
+function newEventId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return (Date.now().toString(16) +
+        Math.random().toString(16).slice(2) +
+        Math.random().toString(16).slice(2));
+}
+// --------------------------------------------------------------------------- //
+// The chain — `stage()` and `span()` (MAR-899, the TS twin of the Python SDK).
+// --------------------------------------------------------------------------- //
+// The wire fields (`spanId` / `parentSpanId` / `taskClass`) have always been on
+// `RecordCallInput`, but a TS user had to thread the ids through their own code by
+// hand — so `margin_stage_plan`, the per-step model/effort advice, worked out of
+// the box for a Python customer and needed manual plumbing for a TS one. That is a
+// real asymmetry on the integration path we describe to design partners as two
+// plugs. These two blocks close it: wrap a step and every call it makes, however
+// many awaits deep, records under one node with the right label — no ids by hand.
+//
+// Honesty, identical to the Python side: `stage`/`span` RE-LABEL and LINK only.
+// Tokens, cost and the outcome are never touched, so a call inside one prices
+// byte-for-byte the same as one before this existed.
+/** A 32-hex span id, the shape of Python's `uuid4().hex` (no dashes). Uses the
+ *  platform crypto UUID where present, a random-hex id otherwise — either is
+ *  unique enough to key one run's tree. */
+function newSpanId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID().replace(/-/g, "");
+    return (Math.random().toString(16).slice(2) +
+        Math.random().toString(16).slice(2) +
+        Date.now().toString(16))
+        .replace(/[^0-9a-f]/g, "")
+        .slice(0, 32)
+        .padEnd(32, "0");
+}
+const _spanStore = new AsyncLocalStorage();
+const _stageStore = new AsyncLocalStorage();
+export function stage(operation, optsOrFn, maybeFn) {
+    const opts = typeof optsOrFn === "function" ? {} : optsOrFn;
+    const fn = (typeof optsOrFn === "function" ? optsOrFn : maybeFn);
+    const parent = _spanStore.getStore();
+    const ctx = {
+        spanId: newSpanId(),
+        parentSpanId: opts.parentSpanId ?? parent?.spanId,
+    };
+    const override = {
+        operation,
+        sessionId: opts.sessionId,
+        taskClass: opts.taskClass,
+    };
+    return _stageStore.run(override, () => _spanStore.run(ctx, () => fn(ctx.spanId)));
+}
+/** The active `(operation, sessionId, taskClass)` step override, or `undefined`
+ *  outside any `stage`. */
+export function currentStage() {
+    return _stageStore.getStore();
+}
+/** Mark every metered call inside `fn` as one node of an agent tree — the tree the
+ *  Money Map decomposes to ask what a BRANCH cost, which a flat list of calls
+ *  sharing a `sessionId` cannot answer. Nesting is what builds the tree; returns
+ *  whatever `fn` returns.
+ *
+ *  ```ts
+ *  await span({ pattern: "panel", branchWidth: 3, stoppingRule: "majority of 3" }, () =>
+ *    Promise.all(candidates.map((c) => judge(c))),   // each judge nests its own node
+ *  );
+ *  ```
+ *
+ *  `stage()` is the primitive to reach for on a plain pipeline step; `span()` adds
+ *  the orchestration shape when a block fans out. This is the TS twin of
+ *  `margin_meter.span`. */
+export function span(opts, fn) {
+    const parent = _spanStore.getStore();
+    const ctx = {
+        spanId: opts.spanId ?? newSpanId(),
+        parentSpanId: opts.parentSpanId ?? parent?.spanId,
+        pattern: opts.pattern,
+        branchWidth: opts.branchWidth,
+        stoppingRule: opts.stoppingRule,
+    };
+    return _spanStore.run(ctx, () => fn(ctx.spanId));
+}
+/** The active `(spanId, parentSpanId)`, or `undefined` outside any span/stage. */
+export function currentSpan() {
+    const ctx = _spanStore.getStore();
+    return ctx === undefined
+        ? undefined
+        : { spanId: ctx.spanId, parentSpanId: ctx.parentSpanId };
+}
 /** Raised (only in strict mode) when a row is rejected by the ingest API. */
 export class MarginIngestError extends Error {
     statusCode;
@@ -67,47 +214,406 @@ export class MarginMeter {
     apiKey;
     raiseOnError;
     transport;
+    attempted = 0;
+    delivered = 0;
+    droppedByReason = {};
+    attemptedByPath = {};
+    droppedByPath = {};
+    warnedOnDrop = false;
+    noUrl;
+    batcher;
+    exitFlush;
+    exitFlushArmed = false;
     constructor(options = {}) {
         const env = (typeof process !== "undefined" && process.env) || {};
-        this.ingestUrl = options.ingestUrl || env.MARGIN_INGEST_URL || DEFAULT_INGEST_URL;
+        this.ingestUrl = options.ingestUrl || env.MARGIN_INGEST_URL || "";
+        // An injected transport already knows where it posts; only our own fetch needs a URL.
+        this.noUrl = !this.ingestUrl && !options.transport;
         this.apiKey = options.apiKey || env.MARGIN_INGEST_KEY;
         this.raiseOnError = options.raiseOnError ?? false;
         this.transport =
             options.transport ||
                 new FetchTransport(this.ingestUrl, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        this.batcher = new Batcher((batch) => this.sendBatch(batch));
+        // ⭐ The shutdown flush. `beforeExit`, deliberately NOT a signal handler:
+        // installing SIGTERM/SIGINT from a library steals signal handling from a host
+        // that usually has its own graceful shutdown. It fires when the event loop
+        // empties — which the batcher's `unref`'d timer is careful not to prevent —
+        // and it is async-capable, unlike `exit`.
+        //
+        // ⛔ FLUSH, not close, and the difference is not cosmetic. `beforeExit` fires
+        // whenever the loop drains, which in a long-lived host happens between bursts
+        // of work rather than only at the end — closing there would wedge the meter
+        // for the rest of the process's life, and every later call would be dropped.
+        // Caught exactly that way: a test run went quiet for a tick and two subsequent
+        // rows were refused by a batcher that had "shut down" mid-suite. Flushing is
+        // idempotent and safe to fire any number of times; closing is an explicit,
+        // one-way act the host asks for with `await meter.close()`.
+        //
+        // ⚠️ A hard kill loses the buffer, bounded by the flush interval. Said plainly
+        // rather than glossed: no in-memory buffer survives SIGKILL, and pretending
+        // otherwise would be a fabricated guarantee.
+        //
+        // ⭐ BOUNDED, and registered LAZILY on the first buffered row (see `enqueue`).
+        // Registering in the constructor put one listener per meter on `process` for
+        // the process's lifetime, each pinning its meter and up to `maxQueue` records
+        // — Node warns at eleven, and the meter that never emits pays for a handler it
+        // will never need. `close()` removes it again.
+        this.exitFlush = () => {
+            void Promise.race([this.batcher.flush(), sleep(SHUTDOWN_TIMEOUT_MS)]);
+        };
+    }
+    /** Attach the process-exit flush, once, on the first row that will need it. */
+    armExitFlush() {
+        if (this.exitFlushArmed)
+            return;
+        if (typeof process === "undefined" || typeof process.on !== "function")
+            return;
+        this.exitFlushArmed = true;
+        process.on("beforeExit", this.exitFlush);
+    }
+    /** Record one emit attempt. Called at every exit point that knows its own
+     *  outcome, BEFORE any `raiseOnError` throw, so a strict-mode failure is
+     *  counted exactly like the fail-safe one it would otherwise have been. */
+    count(path, ok, reason) {
+        this.attempted += 1;
+        this.attemptedByPath[path] = (this.attemptedByPath[path] ?? 0) + 1;
+        if (ok) {
+            this.delivered += 1;
+            return;
+        }
+        const bucket = reason ?? "unknown";
+        this.droppedByReason[bucket] = (this.droppedByReason[bucket] ?? 0) + 1;
+        this.droppedByPath[path] = (this.droppedByPath[path] ?? 0) + 1;
+        if (!this.warnedOnDrop) {
+            this.warnedOnDrop = true;
+            // Once per meter, on the FIRST drop only, so a silent drop stops being
+            // silent without letting a flapping network flood the host's own logs.
+            // The RATE lives in deliveryStats(); this line exists to send someone there.
+            console.warn(`margin-meter: an emit was dropped (${bucket}) — this row is NOT in the ` +
+                `ledger. Metering is fail-safe, so the host call was unaffected. ` +
+                `Call meter.deliveryStats() for the running count.`);
+        }
     }
+    /** A snapshot of what this meter delivered against what it tried to.
+     *  See {@link DeliveryStats}. */
+    deliveryStats() {
+        const dropped = this.attempted - this.delivered;
+        return {
+            attempted: this.attempted,
+            delivered: this.delivered,
+            dropped,
+            dropRate: this.attempted ? dropped / this.attempted : 0,
+            droppedByReason: { ...this.droppedByReason },
+            attemptedByPath: { ...this.attemptedByPath },
+            droppedByPath: { ...this.droppedByPath },
+        };
+    }
+    /**
+     * Route one built payload to the wire or the buffer.
+     *
+     * Buffering is the default and the whole point (`docs/reference/SDK_BATCHING.md`).
+     * Two cases deliberately stay immediate, and neither is a knob:
+     *
+     * - **Strict mode** (`raiseOnError`) means "throw at MY call site when this row
+     *   is rejected", and a buffered emit has no call site left to throw at by the
+     *   time the POST happens. The two are incompatible, so strict posts now.
+     * - **No key**, because buffering rows that can never be sent would fill the
+     *   queue and then report `queue_full` — a diagnosis that sends the reader
+     *   hunting for a network problem when the answer is a missing variable.
+     *   A missing URL is the same case and is named `no_url`.
+     */
     async emit(path, payload) {
         if (!this.apiKey) {
             const error = "no ingest key (set MARGIN_INGEST_KEY or pass apiKey)";
+            this.count(path, false, "no_key");
+            if (this.raiseOnError)
+                throw new MarginConfigError(error);
+            return { ok: false, statusCode: 0, error, reason: "no_key" };
+        }
+        if (this.noUrl) {
+            const error = "no ingest URL (set MARGIN_INGEST_URL=https://trymargin.io or pass ingestUrl)";
+            this.count(path, false, "no_url");
             if (this.raiseOnError)
                 throw new MarginConfigError(error);
-            return { ok: false, statusCode: 0, error };
+            return { ok: false, statusCode: 0, error, reason: "no_url" };
+        }
+        if (!this.raiseOnError)
+            return this.enqueue(path, payload);
+        return await this.postNow(path, payload);
+    }
+    /** Hand one record to the buffer. Never blocks, never throws.
+     *
+     *  `ok: true` here means ACCEPTED INTO THE BUFFER, not written to the ledger —
+     *  the body says `queued` so nothing mistakes the two. What actually landed is
+     *  `deliveryStats()`, which exists for exactly this question. */
+    enqueue(path, payload) {
+        if (this.batcher.submit({ path, payload })) {
+            this.armExitFlush();
+            return { ok: true, statusCode: 0, body: { queued: true } };
+        }
+        // Refused. Either our endpoint is unreachable and the buffer filled, or the
+        // meter was explicitly closed and is still being written to — opposite fixes,
+        // so they are counted apart rather than under one bucket. Dropping is correct
+        // in both cases (an unbounded buffer would OOM the customer's agent) but it is
+        // COUNTED, because a meter that silently stops metering is the one failure
+        // this product cannot have.
+        const reason = this.batcher.closed ? "meter_closed" : "queue_full";
+        const error = this.batcher.closed
+            ? "meter is closed — this row is NOT in the ledger"
+            : `meter buffer full (${this.batcher.maxQueue} records) — this row is NOT in the ledger`;
+        this.count(path, false, reason);
+        return { ok: false, statusCode: 0, error, reason };
+    }
+    /** Resolve once every buffered row has been delivered or counted as dropped.
+     *
+     *  Call it before reading `deliveryStats()` if you need the counts to cover rows
+     *  you have only just emitted — buffering separates an emit from its delivery
+     *  in time by design. */
+    async flush() {
+        await this.batcher.flush();
+    }
+    /** Drain the buffer and stop the timer. Registered on `beforeExit`.
+     *
+     *  Anything the timeout strands is COUNTED as dropped rather than abandoned: the
+     *  records are handed back by `Batcher.close` precisely so the number is
+     *  knowable. */
+    async close(timeoutMs = SHUTDOWN_TIMEOUT_MS) {
+        // Detached first so a meter the host closed explicitly does not also hold a
+        // process-exit listener (and a reference to itself) alive for the rest of the
+        // process.
+        if (this.exitFlushArmed && typeof process !== "undefined") {
+            process.off("beforeExit", this.exitFlush);
+            this.exitFlushArmed = false;
+        }
+        for (const record of await this.batcher.close(timeoutMs)) {
+            this.count(record.path, false, "shutdown_timeout");
         }
+    }
+    async postNow(path, payload) {
         let resp;
         try {
             resp = await this.transport.post(path, {
                 json: payload,
-                headers: { [KEY_HEADER]: this.apiKey },
+                headers: { [KEY_HEADER]: this.apiKey ?? "" },
             });
         }
         catch (e) {
             const error = `transport error: ${e.message}`;
+            this.count(path, false, "transport");
             if (this.raiseOnError)
                 throw new MarginIngestError(0, e.message);
-            return { ok: false, statusCode: 0, error };
+            return { ok: false, statusCode: 0, error, reason: "transport" };
         }
         if (resp.status === 200) {
             const body = (await resp.json());
+            this.count(path, true);
             return { ok: true, statusCode: 200, body };
         }
+        const reason = `http_${resp.status}`;
+        this.count(path, false, reason);
         const detail = await extractDetail(resp);
         if (this.raiseOnError)
             throw new MarginIngestError(resp.status, detail);
-        return { ok: false, statusCode: resp.status, error: detail };
+        return { ok: false, statusCode: resp.status, error: detail, reason };
+    }
+    // --------------------------------------------------------------------- //
+    // Delivery — what happens off the caller's path
+    // --------------------------------------------------------------------- //
+    /** POST one buffered batch. Never rejects: it owns its own accounting.
+     *
+     *  ⛔ The blanket `catch` is load-bearing, not defensive habit. `Batcher.flush`
+     *  swallows a rejection to keep the drain going, so anything escaping here would
+     *  vanish with the counters reading a clean sheet — an uncounted loss, which
+     *  makes measured spend read CHEAPER than the bill. Scoped per chunk so records
+     *  already accounted for in an earlier chunk are not counted twice. */
+    async sendBatch(records) {
+        for (const chunk of this.chunkByBytes(records)) {
+            try {
+                await this.deliverChunk(chunk);
+            }
+            catch (e) {
+                console.warn(`margin-meter: batch send failed unexpectedly: ${e.message}`);
+                for (const record of chunk)
+                    this.count(record.path, false, "send_error");
+            }
+        }
+    }
+    /** Split a batch so no request exceeds {@link MAX_BATCH_BYTES}.
+     *
+     *  ⛔ A single record over the cap on its own is DROPPED and counted as
+     *  `oversize`. No split can send it, and keeping it would wedge the queue behind
+     *  one poisoned row forever. It is a bug in the caller — every open-vocabulary
+     *  field is already bounded server-side, so an honest row cannot come near a
+     *  megabyte.
+     *
+     *  ⛔ A payload that will not serialise is dropped and counted too, and that case
+     *  is not exotic — a `BigInt` anywhere in the payload makes `JSON.stringify`
+     *  throw. Unguarded, the throw escaped into the flush and the row vanished with
+     *  the counters reading a clean sheet. */
+    chunkByBytes(records) {
+        const chunks = [];
+        let current = [];
+        let size = 0;
+        for (const record of records) {
+            let weight;
+            try {
+                weight = JSON.stringify(record.payload).length + 2;
+            }
+            catch {
+                this.count(record.path, false, "unserializable");
+                continue;
+            }
+            if (weight > MAX_BATCH_BYTES) {
+                this.count(record.path, false, "oversize");
+                continue;
+            }
+            if (current.length > 0 && size + weight > MAX_BATCH_BYTES) {
+                chunks.push(current);
+                current = [];
+                size = 0;
+            }
+            current.push(record);
+            size += weight;
+        }
+        if (current.length > 0)
+            chunks.push(current);
+        return chunks;
+    }
+    async deliverChunk(records) {
+        const calls = records.filter((r) => r.path === CALLS_PATH);
+        const outcomes = records.filter((r) => r.path === OUTCOMES_PATH);
+        const body = {};
+        if (calls.length > 0)
+            body.calls = calls.map((r) => r.payload);
+        if (outcomes.length > 0)
+            body.outcomes = outcomes.map((r) => r.payload);
+        if (calls.length === 0 && outcomes.length === 0)
+            return;
+        const { parsed, reason } = await this.postBatchWithRetry(body);
+        if (!parsed) {
+            // The request never succeeded. Every record in it is a loss, counted under
+            // the reason that caused it — and NOT re-queued: an unbounded retry queue is
+            // the OOM this design bounds, arriving by another door.
+            for (const record of records)
+                this.count(record.path, false, reason);
+            return;
+        }
+        for (const [key, group] of [
+            ["calls", calls],
+            ["outcomes", outcomes],
+        ]) {
+            const raw = parsed[key];
+            const results = Array.isArray(raw) ? raw : [];
+            group.forEach((record, index) => {
+                const outcome = results[index];
+                // ⚠️ Positional alignment is the contract, so a short or missing results
+                // array means we cannot say what happened to this row. Counted as a drop
+                // under its own reason rather than assumed delivered — assuming success is
+                // how an invisible loss starts.
+                if (!outcome || typeof outcome !== "object") {
+                    this.count(record.path, false, "missing_result");
+                }
+                else if (outcome.ok) {
+                    this.count(record.path, true);
+                }
+                else {
+                    // ⭐ Split by the server's own `retryable` flag. A validation failure is
+                    // the caller's bug (fix the payload) and a rate-cap refusal is our
+                    // ceiling (the project is over its daily rows) — opposite fixes, and a
+                    // reader who cannot tell them apart looks in the wrong place.
+                    //
+                    // ⛔ Neither is re-queued, including the retryable one: the cap is a
+                    // 24-HOUR rolling window, so the server's honest `retry_after_seconds`
+                    // can be hours. Holding the queue that long would stall every later row
+                    // behind a wait the buffer cannot survive. The drop is made VISIBLE
+                    // instead — `rate_limited` in deliveryStats() tells a customer their cap
+                    // is the reason, and nothing else could.
+                    this.count(record.path, false, outcome.retryable ? "rate_limited" : "rejected");
+                }
+            });
+        }
+    }
+    /** POST one batch, retrying the failures that clear with time. */
+    async postBatchWithRetry(body) {
+        let reason = "transport";
+        for (let attempt = 0; attempt < RETRY_ATTEMPTS; attempt += 1) {
+            let retryAfterMs;
+            try {
+                const resp = await this.transport.post(BATCH_PATH, {
+                    json: body,
+                    headers: { [KEY_HEADER]: this.apiKey ?? "" },
+                });
+                if (resp.status === 200) {
+                    try {
+                        return { parsed: (await resp.json()), reason: "" };
+                    }
+                    catch {
+                        // A 200 whose body we cannot read tells us nothing about which rows
+                        // landed. Retrying is safe (event_id dedup) and beats guessing.
+                        reason = "unparseable_response";
+                    }
+                }
+                else if (RETRYABLE_STATUS.has(resp.status)) {
+                    reason = `http_${resp.status}`;
+                    retryAfterMs = retryAfterMs_(resp);
+                }
+                else {
+                    // 401/422/400: identical next time. Stop rather than loop.
+                    return { reason: `http_${resp.status}` };
+                }
+            }
+            catch {
+                reason = "transport";
+            }
+            if (attempt + 1 >= RETRY_ATTEMPTS)
+                break;
+            await sleep(backoffMs(attempt, retryAfterMs));
+        }
+        return { reason };
     }
     /** Emit one measured LLM call. Cost is computed server-side when `costUsd`
      *  is omitted. Never throws unless `raiseOnError`. */
     async recordCall(input) {
+        // Resolve the ambient step/tree BEFORE the payload, with the Python SDK's
+        // exact precedence — the two rules differ on purpose:
+        //   • a `stage`'s operation/sessionId OVERRIDE what the call passed (that is
+        //     how one run decomposes into named per-stage operations), while
+        //   • its taskClass and every span field FILL only what the call left unset
+        //     (an explicit `parentSpanId` is usually a branch reattached across a
+        //     worker boundary — the ambient span must not overwrite it).
+        // Labels and links only: no cost/token/outcome field is touched here.
+        const stageOv = _stageStore.getStore();
+        const spanCtx = _spanStore.getStore();
+        let operation = input.operation;
+        let sessionId = input.sessionId;
+        let taskClass = input.taskClass;
+        if (stageOv !== undefined) {
+            if (stageOv.operation !== undefined)
+                operation = stageOv.operation;
+            if (stageOv.sessionId !== undefined)
+                sessionId = stageOv.sessionId;
+            if (stageOv.taskClass !== undefined && taskClass === undefined) {
+                taskClass = stageOv.taskClass;
+            }
+        }
+        let spanId = input.spanId;
+        let parentSpanId = input.parentSpanId;
+        let orchestrationPattern = input.orchestrationPattern;
+        let branchWidth = input.branchWidth;
+        let stoppingRule = input.stoppingRule;
+        if (spanCtx !== undefined) {
+            if (spanId === undefined)
+                spanId = spanCtx.spanId;
+            if (parentSpanId === undefined)
+                parentSpanId = spanCtx.parentSpanId;
+            if (orchestrationPattern === undefined)
+                orchestrationPattern = spanCtx.pattern;
+            if (branchWidth === undefined)
+                branchWidth = spanCtx.branchWidth;
+            if (stoppingRule === undefined)
+                stoppingRule = spanCtx.stoppingRule;
+        }
         const payload = {
             workflow_id: input.workflowId,
             provider: input.provider,
@@ -115,17 +621,84 @@ export class MarginMeter {
             input_tokens: input.inputTokens ?? 0,
             output_tokens: input.outputTokens ?? 0,
             cache_read_tokens: input.cacheReadTokens ?? 0,
-            latency_ms: input.latencyMs ?? 0,
+            cache_creation_tokens: input.cacheCreationTokens ?? 0,
+            // ⛔ `?? null`, NOT `?? 0` (MAR-982). A caller who did not time the call must not
+            // have a zero invented for them — the server stores null as NULL, and nothing
+            // downstream can tell a substituted 0 from a real one.
+            latency_ms: input.latencyMs ?? null,
             status: input.status ?? "ok",
             is_retry: input.isRetry ?? false,
             is_simulated: input.isSimulated ?? false,
+            event_id: input.eventId ?? newEventId(),
         };
-        if (input.sessionId !== undefined)
-            payload.session_id = input.sessionId;
+        if (sessionId !== undefined)
+            payload.session_id = sessionId;
         if (input.promptId !== undefined)
             payload.prompt_id = input.promptId;
+        if (operation !== undefined)
+            payload.operation = operation;
+        // ⛔ CLAMPED to the server's column widths, matching the Python SDK and the in-repo meter.
+        // `ingest._require_str` RAISES rather than truncating, so an over-long label is a 422 for the
+        // whole row — and this client defaults to `raiseOnError=false`, so a caller setting e.g.
+        // environment="production-us-east-1-blue-green" (37 chars) would silently drop 100% of that
+        // service's metered spend. Truncating mislabels a row; raising loses it.
+        if (input.environment !== undefined)
+            payload.environment = input.environment.slice(0, 32);
+        if (input.team !== undefined)
+            payload.team = input.team.slice(0, 64);
         if (input.costUsd !== undefined)
             payload.cost_usd = input.costUsd;
+        // Only send a non-default tier: a synchronous call omits it (the server
+        // defaults "standard"), keeping the wire minimal and an older server that
+        // predates the field unaffected.
+        if (input.billingTier !== undefined && input.billingTier !== "standard") {
+            payload.billing_tier = input.billingTier;
+        }
+        // Only send the 1-hour cache-write bucket when a call used one: the common
+        // single-TTL call omits it (the server reads 0 and prices its whole cache
+        // creation at the 5-minute rate, unchanged), keeping the wire minimal and an
+        // older server that predates the field unaffected.
+        if (input.cacheCreation1hTokens) {
+            payload.cache_creation_1h_tokens = input.cacheCreation1hTokens;
+        }
+        // Only send the reasoning subset when a call spent thinking tokens: a
+        // non-reasoning call omits it (server reads 0). It never changes cost — it is a
+        // share of output already priced at the output rate.
+        if (input.reasoningTokens) {
+            payload.reasoning_tokens = input.reasoningTokens;
+        }
+        // The agent-tree fields ride only when a call belongs to one, so a
+        // single-agent call's wire is unchanged and an older server that predates them
+        // is unaffected. They carry structure, never money — no cost branch reads them.
+        if (spanId !== undefined)
+            payload.span_id = spanId;
+        if (parentSpanId !== undefined)
+            payload.parent_span_id = parentSpanId;
+        if (orchestrationPattern !== undefined) {
+            payload.orchestration_pattern = orchestrationPattern;
+        }
+        if (branchWidth !== undefined)
+            payload.branch_width = branchWidth;
+        if (stoppingRule !== undefined)
+            payload.stopping_rule = stoppingRule;
+        // The delivery path, sent only when it was actually determined.
+        if (input.substrate !== undefined)
+            payload.substrate = input.substrate;
+        // The unit of work this call served, sent only when the caller named it.
+        if (input.taskKey !== undefined)
+            payload.task_key = input.taskKey;
+        if (taskClass !== undefined)
+            payload.task_class = taskClass;
+        // WHICH AGENT SCAFFOLD drove the call (MAR-371). Clamped to the server's
+        // String(64) so an over-long harness costs the tail of the label, never the row
+        // (ingest._require_str raises on over-long, which would 422 the whole call).
+        if (input.harness !== undefined)
+            payload.harness = input.harness.slice(0, 64);
+        // WHY the generation ended, straight off the provider — a signal, never a
+        // billing verdict (MAR-209). Rides only when the provider reported one; absent
+        // it reads UNKNOWN server-side rather than a fabricated value. Never priced.
+        if (input.finishReason !== undefined)
+            payload.finish_reason = input.finishReason;
         return await this.emit(CALLS_PATH, payload);
     }
     /** Emit one outcome (a unit of productivity). `qualityMethod` records HOW the
@@ -135,13 +708,24 @@ export class MarginMeter {
             workflow_id: input.workflowId,
             passed: input.passed,
             is_simulated: input.isSimulated ?? false,
+            event_id: input.eventId ?? newEventId(),
         };
         if (input.qualityScore !== undefined)
             payload.quality_score = input.qualityScore;
         if (input.qualityMethod !== undefined)
             payload.quality_method = input.qualityMethod;
+        if (input.graderKind !== undefined)
+            payload.grader_kind = input.graderKind;
+        if (input.judgeModelId !== undefined)
+            payload.judge_model_id = input.judgeModelId;
+        if (input.graderConfidence !== undefined)
+            payload.grader_confidence = input.graderConfidence;
         if (input.link !== undefined)
             payload.link = input.link;
+        // Rides only when a value was actually supplied — absent is the first-class
+        // normal case (cost-per-outcome), never a defaulted 0 the customer did not send.
+        if (input.valueUsd !== undefined)
+            payload.value_usd = input.valueUsd;
         return await this.emit(OUTCOMES_PATH, payload);
     }
     /**
@@ -169,22 +753,321 @@ export class MarginMeter {
                 inputTokens: m.inputTokens,
                 outputTokens: m.outputTokens,
                 cacheReadTokens: m.cacheReadTokens,
+                cacheCreationTokens: m.cacheCreationTokens,
+                cacheCreation1hTokens: m.cacheCreation1hTokens,
                 latencyMs,
                 status: threw ? "error" : "ok",
             });
         }
     }
+    // --------------------------------------------------------------------- //
+    // Auto-instrumentation — meter straight off a provider response, no manual
+    // setTokens(). The "few lines to instrument a repo" path.
+    // --------------------------------------------------------------------- //
+    /**
+     * Meter one call by reading tokens straight off its provider `response`
+     * (OpenAI / Anthropic / Gemini result). The no-bookkeeping counterpart to
+     * `recordCall`: the `(provider, model, tokens)` are recovered by
+     * `extractUsage`. `provider` is optional when the shape is unambiguous but the
+     * instrumenter always passes it; `model` overrides a response that omits it
+     * (Gemini). Numbers are read verbatim. Never throws unless `raiseOnError`.
+     */
+    async recordResponse(input) {
+        const usage = extractUsage(input.response, {
+            provider: input.provider,
+            model: input.model,
+        });
+        return await this.recordCall({
+            workflowId: input.workflowId,
+            provider: usage.provider,
+            model: usage.model ?? "",
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            cacheReadTokens: usage.cacheReadTokens,
+            cacheCreationTokens: usage.cacheCreationTokens,
+            cacheCreation1hTokens: usage.cacheCreation1hTokens,
+            reasoningTokens: usage.reasoningTokens,
+            costUsd: usage.billedCostUsd,
+            latencyMs: input.latencyMs,
+            status: input.status ?? "ok",
+            isRetry: input.isRetry,
+            sessionId: input.sessionId,
+            promptId: input.promptId,
+            operation: input.operation,
+            isSimulated: input.isSimulated,
+            substrate: input.substrate,
+            taskKey: input.taskKey,
+            // The provider's stop/finish reason, read verbatim off the response and
+            // forwarded as finish_reason (MAR-209). A signal, never a billing verdict.
+            finishReason: usage.stopReason,
+        });
+    }
+    /**
+     * Return `fn` wrapped so every call is timed and auto-metered. The core
+     * auto-instrumentation primitive: give it any async LLM call
+     * (`client.chat.completions.create`, `client.messages.create`,
+     * `model.generateContent` …) and it returns a drop-in replacement that times
+     * the call, emits its economics from the returned response, and hands the
+     * ORIGINAL response back untouched. On a throw the call is metered with
+     * `status="error"` and the error re-thrown (never swallowed); a metering
+     * failure is fail-safe and never breaks the wrapped call. `provider` is
+     * required for a shape the extractor can't disambiguate; `model` supplies a
+     * model the response omits (Gemini); `resolveModel(args)` derives it per call
+     * (e.g. off a bound Gemini model). Signature-agnostic (`...args`).
+     */
+    wrap(fn, opts) {
+        const meter = this;
+        return async function (...args) {
+            let callModel = opts.model;
+            if (opts.resolveModel) {
+                try {
+                    const resolved = opts.resolveModel(args);
+                    if (resolved)
+                        callModel = resolved;
+                }
+                catch {
+                    /* a resolver hiccup never breaks the wrapped call */
+                }
+            }
+            // The unit of work, resolved off the host's ambient context per call — never a
+            // constant, which would collapse a run into one task class.
+            let callTaskKey;
+            if (opts.resolveTaskKey) {
+                try {
+                    callTaskKey = opts.resolveTaskKey();
+                }
+                catch {
+                    /* a resolver hiccup reads as UNKNOWN, never breaks the wrapped call */
+                }
+            }
+            // Ask OpenAI to include usage on a streamed call so the final chunk carries
+            // the count the accumulator needs (only when this is an OpenAI chat patch).
+            maybeInjectIncludeUsage(args, opts);
+            const start = now();
+            let response;
+            try {
+                response = (await fn(...args));
+            }
+            catch (e) {
+                const latencyMs = Math.round(now() - start);
+                try {
+                    await meter.recordCall({
+                        workflowId: opts.workflowId,
+                        provider: opts.provider ?? "unknown",
+                        model: callModel ?? "",
+                        latencyMs,
+                        status: "error",
+                        isRetry: opts.isRetry,
+                        sessionId: opts.sessionId,
+                        operation: opts.operation,
+                        isSimulated: opts.isSimulated,
+                        substrate: opts.substrate,
+                        taskKey: callTaskKey,
+                    });
+                }
+                catch {
+                    /* metering must never mask the host's real exception */
+                }
+                throw e;
+            }
+            // A streamed call resolves to an async-iterable of chunks, not a `.usage`
+            // response. Reading it here would throw and drop the call; instead hand back
+            // a transparent proxy that meters ONCE as the host consumes the stream.
+            if (isAsyncIterable(response)) {
+                return meteredStream(response, meter, opts, callModel, callTaskKey, start);
+            }
+            // Bedrock's streaming commands resolve to a plain object whose event stream rides
+            // under `.stream` (ConverseStream) or `.body` (InvokeModelWithResponseStream), with
+            // the usage in its final event. Swap that field for the metered proxy (MAR-1518).
+            const nestedKey = opts.provider === "bedrock" ? bedrockStreamKey(response) : undefined;
+            if (nestedKey !== undefined) {
+                const r = response;
+                r[nestedKey] = meteredStream(r[nestedKey], meter, opts, callModel, callTaskKey, start);
+                return response;
+            }
+            const latencyMs = Math.round(now() - start);
+            try {
+                await meter.recordResponse({
+                    workflowId: opts.workflowId,
+                    response,
+                    provider: opts.provider,
+                    model: callModel,
+                    latencyMs,
+                    isRetry: opts.isRetry,
+                    sessionId: opts.sessionId,
+                    operation: opts.operation,
+                    isSimulated: opts.isSimulated,
+                    substrate: opts.substrate,
+                    taskKey: callTaskKey,
+                });
+            }
+            catch {
+                /* fail-safe: an unreadable response must not break the host call */
+            }
+            return response;
+        };
+    }
+}
+/** True when `x` is an async-iterable (a provider stream), never a plain response
+ *  object, string, or array. The clean discriminator between a streamed call and
+ *  a normal one after the wrapped fn resolves. */
+function isAsyncIterable(x) {
+    return (x != null &&
+        (typeof x === "object" || typeof x === "function") &&
+        typeof x[Symbol.asyncIterator] === "function");
+}
+/** The field a Bedrock streaming response carries its event stream under, if any.
+ *  A non-streaming `InvokeModel` body is a Uint8Array, not async-iterable, so it is
+ *  never mistaken for one. */
+function bedrockStreamKey(response) {
+    if (response == null || typeof response !== "object")
+        return undefined;
+    const r = response;
+    if (isAsyncIterable(r.stream))
+        return "stream";
+    if (isAsyncIterable(r.body))
+        return "body";
+    return undefined;
+}
+/** When this wrapper is an OpenAI chat patch (`streamIncludeUsage`) AND the call
+ *  requests `stream: true`, add `stream_options.include_usage` so OpenAI emits its
+ *  usage on the final chunk. Clones the params object (never mutates the caller's),
+ *  and fills only when absent so an explicit caller choice is respected. */
+function maybeInjectIncludeUsage(args, opts) {
+    if (!opts.streamIncludeUsage)
+        return;
+    const params = args[0];
+    if (params == null || typeof params !== "object")
+        return;
+    const p = params;
+    if (p.stream !== true)
+        return;
+    const existing = p.stream_options;
+    if (existing == null) {
+        args[0] = { ...p, stream_options: { include_usage: true } };
+    }
+    else if (typeof existing === "object" &&
+        !("include_usage" in existing)) {
+        args[0] = {
+            ...p,
+            stream_options: { ...existing, include_usage: true },
+        };
+    }
+}
+/**
+ * A transparent proxy over a provider stream that meters on completion.
+ *
+ * The TS twin of `margin_meter`'s `_MeteredStream`. It hands every chunk to the
+ * host UNCHANGED while feeding it to a `StreamUsageAccumulator`; when the stream
+ * is exhausted, the host breaks early (its iterator's `return()`), or a chunk
+ * throws, it meters exactly once with the accumulated usage — or nothing when the
+ * stream carried no usage at all (an OpenAI stream without `include_usage`), since
+ * a zero-token row would misreport a real call as free. Every other property/method
+ * delegates to the wrapped stream, so `for await (const c of stream)`, `.tee()`,
+ * and the rest work unchanged. Fail-safe: a metering hiccup never breaks iteration.
+ */
+function meteredStream(stream, meter, opts, callModel, callTaskKey, start) {
+    const acc = new StreamUsageAccumulator(opts.provider, callModel);
+    let finished = false;
+    const finish = async () => {
+        if (finished)
+            return;
+        finished = true;
+        const usage = acc.finalize();
+        // Honest: a stream that carried no usage is NOT recorded — there is no real
+        // token count and a zero-token row would report the call as free.
+        if (usage === undefined)
+            return;
+        const latencyMs = Math.round(now() - start);
+        try {
+            await meter.recordCall({
+                workflowId: opts.workflowId,
+                provider: usage.provider ?? opts.provider ?? "unknown",
+                model: usage.model ?? callModel ?? "",
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+                cacheReadTokens: usage.cacheReadTokens,
+                cacheCreationTokens: usage.cacheCreationTokens,
+                cacheCreation1hTokens: usage.cacheCreation1hTokens,
+                reasoningTokens: usage.reasoningTokens,
+                costUsd: usage.billedCostUsd,
+                latencyMs,
+                status: "ok",
+                isRetry: opts.isRetry,
+                sessionId: opts.sessionId,
+                operation: opts.operation,
+                isSimulated: opts.isSimulated,
+                substrate: opts.substrate,
+                taskKey: callTaskKey,
+                // A streaming Anthropic message_delta carries stop_reason too (the
+                // accumulator merges it) — forward it so a streamed Fable fallback records
+                // its reason like a non-streamed one.
+                finishReason: usage.stopReason,
+            });
+        }
+        catch {
+            /* metering must never mask the host's real result */
+        }
+    };
+    return new Proxy(stream, {
+        get(target, prop, receiver) {
+            if (prop === Symbol.asyncIterator) {
+                return function meteredAsyncIterator() {
+                    const inner = target[Symbol.asyncIterator]();
+                    return {
+                        async next() {
+                            let r;
+                            try {
+                                r = await inner.next();
+                            }
+                            catch (e) {
+                                await finish(); // a mid-stream error still banks the partial usage seen
+                                throw e;
+                            }
+                            if (r.done) {
+                                await finish(); // metered once, cleanly, at the end of the stream
+                            }
+                            else {
+                                try {
+                                    acc.observe(r.value);
+                                }
+                                catch {
+                                    /* a malformed chunk never breaks the host's read */
+                                }
+                            }
+                            return r;
+                        },
+                        async return(value) {
+                            await finish(); // the host broke early — meter what was seen
+                            if (typeof inner.return === "function") {
+                                return inner.return(value);
+                            }
+                            return { done: true, value };
+                        },
+                    };
+                };
+            }
+            const val = Reflect.get(target, prop, receiver);
+            return typeof val === "function"
+                ? val.bind(target)
+                : val;
+        },
+    });
 }
 /** Token accumulator passed into `measure`'s callback. */
 export class Measurement {
     inputTokens = 0;
     outputTokens = 0;
     cacheReadTokens = 0;
+    cacheCreationTokens = 0;
+    cacheCreation1hTokens = 0;
     result;
     setTokens(tokens) {
         this.inputTokens = tokens.inputTokens ?? 0;
         this.outputTokens = tokens.outputTokens ?? 0;
         this.cacheReadTokens = tokens.cacheReadTokens ?? 0;
+        this.cacheCreationTokens = tokens.cacheCreationTokens ?? 0;
+        this.cacheCreation1hTokens = tokens.cacheCreation1hTokens ?? 0;
     }
 }
 async function extractDetail(resp) {
@@ -202,4 +1085,39 @@ async function extractDetail(resp) {
 function now() {
     return typeof performance !== "undefined" ? performance.now() : Date.now();
 }
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        // Unref'd for the same reason the flush timer is: a backoff must never be the
+        // thing keeping a short-lived script alive.
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+    });
+}
+/** The server's own `Retry-After`, in ms, when it sent one.
+ *
+ *  The ingest API computes the real wait from its rolling window rather than
+ *  sending a round number, so honouring it beats any backoff we could calculate
+ *  blind — a client that guesses either hammers or overshoots, and overshooting
+ *  drops exactly the calls the SDK was installed to record. */
+export function retryAfterMs_(resp) {
+    const headers = resp.headers;
+    const raw = headers?.get?.("Retry-After") ?? undefined;
+    if (raw === undefined || raw === null)
+        return undefined;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : undefined;
+}
+/** FULL jitter — `random(0, base * 2**attempt)`, capped, or the server's wait.
+ *
+ *  Jittered rather than plain exponential because every buffered client backs off
+ *  on the same schedule: un-jittered retries re-synchronise into a thundering herd
+ *  aimed at the endpoint that just failed, which is how a brief blip becomes an
+ *  outage. */
+export function backoffMs(attempt, retryAfter) {
+    if (retryAfter !== undefined)
+        return Math.min(RETRY_CAP_MS, retryAfter);
+    return Math.random() * Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** attempt);
+}
 //# sourceMappingURL=index.js.map