@relayburn/sdk 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-05-08
+
+### Breaking Changes
+
+- Removed the `onLog` option from `summary`, `sessionCost`, `overhead`, `overheadTrim`, `hotspots`, and `compare` option types. The 2.x stack is SQLite-native and has no archive-fallback path to surface, so the callback was already a no-op at the napi boundary. (#374)
+
+### Added
+
+- Exported `writePendingStamp()` so Node launchers can write generic
+  enrichment tags before spawning Claude, Codex, or OpenCode directly.
+- `summary()` options now accept `tags` and `groupByTag` for generic
+  enrichment filtering and cost/token grouping.
+- Exported `computeCompareExcluded()` from the Node facade for callers that
+  need the same fidelity-exclusion breakdown used by `compare()`.
+
+### Changed
+
+- Replaced the TypeScript 1.x deep-conformance test with native 2.x smoke
+  coverage against the committed fixture ledger.
+
+### Fixed
+
+- `search()` now accepts a numeric `limit` in the Node facade and normalizes it
+  before calling the napi-rs binding.
+
 ## [2.1.0] - 2026-05-07
 
 ### Added
@@ -30,8 +55,5 @@
   outside that range stay `BigInt` to avoid silent precision loss.
 - Conformance suite is now wired into CI: `napi build` writes its outputs
   (`.node`, `binding.cjs`, `binding.d.ts`) into `src/` so the generated
-  loader's local-file branch resolves; the suite seeds a deterministic
-  ledger via `tests/fixtures/cli-golden/scripts/build-ledger.mjs` and
-  flips `RELAYBURN_SDK_NAPI_BUILT=1` to enable the `deepStrictEqual` gate
-  against TS `@relayburn/sdk@1.x`. (#247 part d)
-
+  loader's local-file branch resolves; the suite was originally wired as a
+  deep-equality gate against TS `@relayburn/sdk@1.x`. (#247 part d)

package/README.md

@@ -1,10 +1,9 @@
-# @relayburn/sdk (2.x)
+# @relayburn/sdk
 
-Embeddable Relayburn SDK — napi-rs bindings over the Rust `relayburn-sdk`
-crate. Drop-in replacement for the TS `@relayburn/sdk@1.x` published from
-`packages/sdk/`.
+Embeddable Relayburn SDK for Node.js. The package is a napi-rs facade over the
+Rust `relayburn-sdk` crate.
 
-The 2.x umbrella resolves the right native binary for your platform via
+The package resolves the native binding for your platform via
 `optionalDependencies`:
 
 | Platform | Package |
@@ -16,21 +15,15 @@ The 2.x umbrella resolves the right native binary for your platform via
 
 Windows (`win32-x64-msvc`) is not yet shipped — see #247 follow-up.
 
-## Migration from 1.x
-
-Same imports, same option shapes, same return shapes — except:
-
-- **u64 token counts are `bigint`.** napi-rs maps Rust `u64` to JavaScript
-  `BigInt`. Code that does arithmetic on `summary().totalTokens` (and
-  similar fields on `hotspots`, `overhead`, `sessionCost`) needs to either
-  use `BigInt` literals (`100n`) or coerce with `Number(x)`. The TS
-  declarations widen these fields to `number | bigint` to keep existing
-  callers compiling.
-- Otherwise byte-for-byte compatible. Run your test suite — the conformance
-  test in `test/conformance.test.js` is what we use to validate.
-
-## Status
-
-This is a `2.0.0-pre` build published to npm under the `next` tag while
-the rest of the Rust port lands. Until the lockstep 2.0 cutover ships, the
-1.x TS SDK at `packages/sdk/` is still the source of truth.
+## API Notes
+
+- Large u64 token counts may be `bigint`. napi-rs maps Rust `u64` to
+  JavaScript `BigInt`; the facade downcasts safe-range integers to `number`
+  and leaves larger values as `bigint`. The declarations widen these fields
+  to `number | bigint`.
+- The SDK exposes read verbs such as `summary()`, `sessionCost()`,
+  `hotspots()`, `compare()`, `search()`, `exportLedger()`, and
+  `exportStamps()`.
+- Launchers can call `writePendingStamp({ harness, cwd, enrichment })`
+  before spawning Claude, Codex, or OpenCode, then run `ingest()` to fold
+  those generic enrichment tags onto the discovered turns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayburn/sdk",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Embeddable Relayburn SDK — napi-rs bindings over the Rust relayburn-sdk crate (2.x). Drop-in replacement for the TS @relayburn/sdk@1.x.",
   "type": "module",
   "main": "./src/index.js",
@@ -43,10 +43,10 @@
     ]
   },
   "optionalDependencies": {
-    "@relayburn/sdk-darwin-arm64": "2.3.0",
-    "@relayburn/sdk-darwin-x64": "2.3.0",
-    "@relayburn/sdk-linux-arm64-gnu": "2.3.0",
-    "@relayburn/sdk-linux-x64-gnu": "2.3.0"
+    "@relayburn/sdk-darwin-arm64": "2.4.0",
+    "@relayburn/sdk-darwin-x64": "2.4.0",
+    "@relayburn/sdk-linux-arm64-gnu": "2.4.0",
+    "@relayburn/sdk-linux-x64-gnu": "2.4.0"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.4",

package/src/binding.d.ts

@@ -19,3 +19,4 @@ export declare function overhead(opts?: unknown): Promise<unknown>;
 export declare function overheadTrim(opts?: unknown): Promise<unknown>;
 export declare function hotspots(opts?: unknown): Promise<unknown>;
 export declare function compare(opts: unknown): Promise<unknown>;
+export declare function writePendingStamp(opts: unknown): unknown;

package/src/index.cjs

@@ -4,7 +4,7 @@
 // package is `"type": "commonjs"` and the `exports.require` map is honored.
 //
 // Mirrors the ESM facade verb-for-verb. The sync binding verbs are wrapped
-// in `async` so callers see `Promise<T>` (matching the 1.x TS contract);
+// in `async` so callers see `Promise<T>` (matching the Node facade contract);
 // see `src/index.js` for the rationale.
 
 'use strict';
@@ -12,9 +12,8 @@
 const binding = require('./binding.cjs');
 
 // See `src/index.js` for the rationale: napi-rs serializes Rust `u64` /
-// `i64` as JS `BigInt`, while TS 1.x `@relayburn/sdk` emits plain
-// `Number`. We downcast safe-range BigInts to keep `deepStrictEqual`
-// passing in conformance and to match user expectations from 1.x.
+// `i64` as JS `BigInt`. We downcast safe-range BigInts to match common
+// JavaScript caller expectations while keeping larger values precise.
 const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
 const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
 
@@ -40,6 +39,16 @@ function coerceBigInts(value) {
   return value;
 }
 
+function normalizeSearchOptions(opts) {
+  if (!opts || typeof opts !== 'object' || typeof opts.limit !== 'number') {
+    return opts;
+  }
+  if (!Number.isSafeInteger(opts.limit) || opts.limit < 0) {
+    throw new RangeError('search limit must be a non-negative safe integer');
+  }
+  return { ...opts, limit: BigInt(opts.limit) };
+}
+
 class Ledger {
   constructor(home) {
     this.home = home;
@@ -50,6 +59,30 @@ class Ledger {
   }
 }
 
+function computeCompareExcluded(summary, minimum) {
+  const out = { total: 0, aggregateOnly: 0, costOnly: 0, partial: 0, usageOnly: 0 };
+  if (minimum === 'partial') return out;
+  const order = ['cost-only', 'aggregate-only', 'partial', 'usage-only', 'full'];
+  const need = order.indexOf(minimum);
+  if (need < 0) {
+    throw new Error(
+      `invalid minimum fidelity: ${minimum} (expected one of ${order.join(', ')})`,
+    );
+  }
+  const byClass = summary?.byClass ?? {};
+  for (const cls of order) {
+    if (order.indexOf(cls) >= need) continue;
+    const n = Number(byClass[cls] ?? 0);
+    if (!n) continue;
+    out.total += n;
+    if (cls === 'aggregate-only') out.aggregateOnly += n;
+    else if (cls === 'cost-only') out.costOnly += n;
+    else if (cls === 'partial') out.partial += n;
+    else if (cls === 'usage-only') out.usageOnly += n;
+  }
+  return out;
+}
+
 module.exports = {
   Ledger,
   ingest: async (opts) => coerceBigInts(await binding.ingest(opts)),
@@ -59,7 +92,9 @@ module.exports = {
   overheadTrim: async (opts) => coerceBigInts(await binding.overheadTrim(opts)),
   hotspots: async (opts) => coerceBigInts(await binding.hotspots(opts)),
   compare: async (opts) => coerceBigInts(await binding.compare(opts)),
-  search: async (opts) => coerceBigInts(await binding.search(opts)),
+  writePendingStamp: async (opts) => coerceBigInts(await binding.writePendingStamp(opts)),
+  computeCompareExcluded,
+  search: async (opts) => coerceBigInts(await binding.search(normalizeSearchOptions(opts))),
   exportLedger: async (opts) => coerceBigInts(await binding.exportLedger(opts)),
   exportStamps: async (opts) => coerceBigInts(await binding.exportStamps(opts)),
   BurnErrorCode: binding.BurnErrorCode,

package/src/index.d.ts

@@ -1,23 +1,20 @@
 // Type surface for `@relayburn/sdk@2.x`.
 //
-// Mirrors `packages/sdk/index.d.ts` (the TS 1.x SDK) byte-for-byte modulo:
+// Mirrors the Rust SDK verb surface through the napi-rs facade, with
+// compatibility affordances for callers migrating from the 1.x JS SDK:
 //   - `bigint` is allowed alongside `number` for u64-typed token counts (the
-//     napi-rs binding emits `BigInt` for `u64`; the TS shape is widened so
-//     existing callers that pass through `number` keep type-checking once
-//     bound to the Rust impl).
+//     napi-rs binding emits `BigInt` for `u64`; the facade downcasts safe-range
+//     values at runtime).
 //   - Async fns return `Promise<T>` — the napi-rs binding uses `async fn`
 //     where the Rust SDK does, which is everywhere except the `Ledger.open`
 //     constructor.
-//
-// Source-of-truth comment: track `packages/sdk/index.d.ts`. Whenever a verb
-// shape changes in TS, mirror it here AND in the Rust napi-rs binding (#247-a).
 
 export interface LedgerOpenOptions { home?: string; contentHome?: string }
 /**
- * Stateful ledger handle. The 1.x TS class only exposes the static
- * `open()` constructor; instances are placeholders today, with `home`
- * exposed for callers that want to confirm which ledger they attached
- * to. Verb methods are a future PR.
+ * Stateful ledger handle. The Node facade exposes the static `open()`
+ * constructor; instances carry the resolved home for callers that want
+ * to confirm which ledger they attached to. Verb methods are reserved
+ * for a future facade expansion.
  */
 export declare class Ledger {
   readonly home: string;
@@ -29,17 +26,48 @@ export interface IngestReport {
   scannedSessions: number | bigint;
   ingestedSessions: number | bigint;
   appendedTurns: number | bigint;
+  appliedPendingStamps: number | bigint;
 }
 export declare function ingest(opts?: IngestOptions): Promise<IngestReport>
 
+export type PendingStampHarness = 'claude' | 'codex' | 'opencode';
+export interface WritePendingStampOptions {
+  harness: PendingStampHarness;
+  cwd: string;
+  enrichment: Record<string, string>;
+  sessionDirHint?: string;
+  /** ISO timestamp, e.g. `2026-04-23T00:00:00.000Z`. Defaults to now. */
+  spawnStartTs?: string;
+  spawnerPid?: number;
+  ledgerHome?: string;
+}
+export interface PendingStamp {
+  v: number;
+  harness: PendingStampHarness;
+  spawnerPid: number;
+  spawnStartTs: string;
+  cwd: string;
+  enrichment: Record<string, string>;
+  sessionDirHint?: string;
+}
+export interface PendingStampWriteResult {
+  file: string;
+  stamp: PendingStamp;
+}
+export declare function writePendingStamp(
+  opts: WritePendingStampOptions,
+): Promise<PendingStampWriteResult>
+
 export interface SummaryOptions {
   session?: string;
   project?: string;
   /** ISO timestamp (e.g. `2026-04-01T00:00:00Z`) or relative range (`24h`, `7d`, `4w`, `2m`). */
   since?: string;
+  /** Folded enrichment tag filters; every key/value pair must match. */
+  tags?: Record<string, string>;
+  /** Group summary costs/tokens by this folded enrichment tag key. */
+  groupByTag?: string;
   ledgerHome?: string;
-  /** Optional logger invoked when the SQLite archive read fails and the SDK falls back to a full ledger walk. */
-  onLog?: (msg: string) => void;
 }
 export declare function summary(opts?: SummaryOptions): Promise<{
   totalTokens: number | bigint;
@@ -47,6 +75,13 @@ export declare function summary(opts?: SummaryOptions): Promise<{
   turnCount: number;
   byTool: Array<{ tool: string; tokens: number | bigint; cost: number; count: number }>;
   byModel: Array<{ model: string; tokens: number | bigint; cost: number }>;
+  byTag?: Array<{
+    tag: string;
+    value?: string;
+    tokens: number | bigint;
+    cost: number;
+    turnCount: number | bigint;
+  }>;
   replacementSavings?: {
     calls: number | bigint;
     collapsedCalls: number | bigint;
@@ -64,7 +99,6 @@ export interface SessionCostOptions {
   /** Session id to total. Omit for `{ note: 'no session id provided' }`. */
   session?: string;
   ledgerHome?: string;
-  onLog?: (msg: string) => void;
 }
 export interface SessionCostResult {
   sessionId: string | null;
@@ -85,7 +119,6 @@ export interface OverheadOptions {
   since?: string;
   kind?: OverheadFileKind;
   ledgerHome?: string;
-  onLog?: (msg: string) => void;
 }
 
 export interface OverheadSection {
@@ -183,7 +216,6 @@ export interface HotspotsOptions {
   groupBy?: HotspotsGroupBy;
   patterns?: string[];
   ledgerHome?: string;
-  onLog?: (msg: string) => void;
 }
 
 export interface HotspotsFileRow {
@@ -333,7 +365,6 @@ export interface CompareOptions {
   minSample?: number;
   minFidelity?: FidelityClass;
   ledgerHome?: string;
-  onLog?: (msg: string) => void;
 }
 
 export interface CompareResult {
@@ -352,13 +383,18 @@ export interface CompareResult {
 
 /** Per-(model, activity) comparison shape. Powers `burn compare`. */
 export declare function compare(opts: CompareOptions): Promise<CompareResult>
+export declare function computeCompareExcluded(
+  summary: FidelitySummaryShape,
+  minimum: FidelityClass
+): CompareExcludedBreakdown
 
 // ---------------------------------------------------------------------------
 // 2.x extensions — surfaces present in `relayburn-sdk` (the Rust crate)
 // but not in the TS 1.x `packages/sdk/index.d.ts`. Pre-1.0 widening per
-// the SDK shape rule; embedders that pinned to 1.x won't see these names
-// (the missing `onLog` etc. plus the absence of these is the only TS-vs-
-// napi gap the conformance gate measures).
+// the SDK shape rule; embedders that pinned to 1.x won't see these names.
+// The 1.x `onLog` callback is intentionally omitted: it surfaced the
+// archive-fallback path that no longer exists in the SQLite-native 2.x
+// stack (see issue #374), so there is nothing to log.
 // ---------------------------------------------------------------------------
 
 export interface SearchQueryOptions {

package/src/index.js

@@ -1,7 +1,7 @@
 // Thin ESM facade over the napi-rs binding. The verbs here re-export the
 // matching `#[napi]` exports from the platform package resolved by
-// `./binding.cjs`, with two adjustments to match the TS 1.x contract at
-// `packages/sdk/index.d.ts`:
+// `./binding.cjs`, with two compatibility adjustments carried forward from
+// the 1.x SDK contract:
 //
 //   1. The sync `#[napi]` verbs (`summary`, `sessionCost`, `overhead`,
 //      `overheadTrim`, `hotspots`, `compare`) are re-exported as `async`
@@ -23,18 +23,13 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const binding = require('./binding.cjs');
 
-// napi-rs serializes Rust `u64` / `i64` as JS `BigInt`, but the TS 1.x
-// `@relayburn/sdk` shape (mirrored in `src/index.d.ts`) emits plain
-// `Number` for the same fields. To keep the conformance gate's
-// `deepStrictEqual` checks honest — and to match the runtime shape that
-// 1.x callers expect (e.g. `result.turnCount === 0`, not `=== 0n`) — we
-// downcast every `BigInt` in a verb's return value to `Number` when it
-// fits in `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`. Values
-// outside that range are left as `BigInt`: realistic burn ledgers won't
-// hit 2^53 tokens, but if one ever does, leaking a `BigInt` that crashes
-// a `===` check is strictly safer than silently rounding to the nearest
-// 1024. The TS shape declares `number | bigint` everywhere this matters
-// so the type stays sound either way.
+// napi-rs serializes Rust `u64` / `i64` as JS `BigInt`, while 1.x emitted
+// plain `Number` for the same fields. To keep common caller expectations
+// intact (e.g. `result.turnCount === 0`, not `=== 0n`), downcast every
+// `BigInt` in a verb's return value to `Number` when it fits in
+// `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`. Values outside that
+// range are left as `BigInt`; leaking a `BigInt` is safer than silently
+// rounding a very large ledger.
 const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
 const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
 
@@ -63,12 +58,20 @@ function coerceBigInts(value) {
   return value;
 }
 
+function normalizeSearchOptions(opts) {
+  if (!opts || typeof opts !== 'object' || typeof opts.limit !== 'number') {
+    return opts;
+  }
+  if (!Number.isSafeInteger(opts.limit) || opts.limit < 0) {
+    throw new RangeError('search limit must be a non-negative safe integer');
+  }
+  return { ...opts, limit: BigInt(opts.limit) };
+}
+
 /**
- * Stateful ledger handle. Mirrors the TS 1.x `Ledger` class shape from
- * `packages/sdk/index.d.ts`. The 1.x version only exposes the static
- * `open(opts)` constructor — instance methods are reserved for a future
- * PR — so we replicate that surface and stash the resolved home for
- * introspection.
+ * Stateful ledger handle. The 1.x SDK only exposed the static `open(opts)`
+ * constructor; instance methods are reserved for a future PR. Keep that shape
+ * and stash the resolved home for introspection.
  */
 export class Ledger {
   constructor(home) {
@@ -117,13 +120,39 @@ export async function compare(opts) {
   return coerceBigInts(await binding.compare(opts));
 }
 
+export async function writePendingStamp(opts) {
+  return coerceBigInts(await binding.writePendingStamp(opts));
+}
+
+export function computeCompareExcluded(summary, minimum) {
+  const out = { total: 0, aggregateOnly: 0, costOnly: 0, partial: 0, usageOnly: 0 };
+  if (minimum === 'partial') return out;
+  const order = ['cost-only', 'aggregate-only', 'partial', 'usage-only', 'full'];
+  const need = order.indexOf(minimum);
+  if (need < 0) {
+    throw new Error(
+      `invalid minimum fidelity: ${minimum} (expected one of ${order.join(', ')})`,
+    );
+  }
+  const byClass = summary?.byClass ?? {};
+  for (const cls of order) {
+    if (order.indexOf(cls) >= need) continue;
+    const n = Number(byClass[cls] ?? 0);
+    if (!n) continue;
+    out.total += n;
+    if (cls === 'aggregate-only') out.aggregateOnly += n;
+    else if (cls === 'cost-only') out.costOnly += n;
+    else if (cls === 'partial') out.partial += n;
+    else if (cls === 'usage-only') out.usageOnly += n;
+  }
+  return out;
+}
+
 // 2.x extensions — exposed by the Rust SDK but not declared in
-// `packages/sdk/index.d.ts` (the 1.x TS surface). Per the SDK shape rule,
-// pre-1.0 widening is allowed; these are surfaced here so embedders can
-// reach the FTS5 search index and the JSONL export iterators without
-// dropping into the binding directly.
+// the 1.x SDK surface. These let embedders reach the FTS5 search index and
+// JSONL export iterators without dropping into the binding directly.
 export async function search(opts) {
-  return coerceBigInts(await binding.search(opts));
+  return coerceBigInts(await binding.search(normalizeSearchOptions(opts)));
 }
 
 export async function exportLedger(opts) {