@relayburn/sdk 1.10.0 → 2.1.0

package/CHANGELOG.md

@@ -1,46 +1,37 @@
-# Changelog
-
-All notable changes to `@relayburn/sdk`.
+# @relayburn/sdk (2.x)
 
 ## [Unreleased]
 
-## [1.10.0] - 2026-05-03
-
-### Breaking Changes
-
-- `hotspots()` now returns a discriminated union (`{ kind: 'attribution' | 'bash' | 'bash-verb' | 'file' | 'subagent' | 'findings' }`) instead of either an attribution blob or a raw findings array. Callers must branch on `kind`. The default (no `groupBy`, no `patterns`) returns the `attribution` shape that mirrors `burn hotspots --json`. Pass `patterns` to get `findings`. Pass `groupBy` to narrow attribution to one axis (`bash` / `bash-verb` / `file` / `subagent`). Warrants the SDK major bump.
-
-### Added
-
-- `hotspots({ groupBy })` narrows attribution to one aggregation axis: `bash`, `bash-verb`, `file`, or `subagent`. Useful for MCP tools and embedders that only want a single per-axis cut.
-- `hotspots({ project, since })` accept the same forwarded options the other SDK queries do (project filter + ISO/relative `since` window normalization).
-- `hotspots()` reads through the SQLite archive by default with transparent fallback to the JSONL ledger walk on archive failure. Pass `onLog` to capture the fallback reason.
-- `hotspots()` surfaces a coverage-refusal shape (`refused: true` + `refusalReason`) when every matched turn lacks the tool-call/tool-result coverage `attributeHotspots` needs, so presenters can map it to the user-facing exit-2 + stderr message.
-
-## [1.9.0] - 2026-05-03
-
-### Added
-
-- `compare({ models, … })` returns the per-(model, activity) `CompareResult` shape (`analyzedTurns`, `models`, `categories`, `totals`, flat `cells[]`, `fidelity { minimum, excluded, summary }`) — the JSON object `burn compare --json` now emits. Mirrors the CLI's archive-vs-ledger branching: archive when `minFidelity === 'partial'` and no provider filter, ledger walk otherwise. Falls back transparently to the ledger walk when the archive read fails.
-- `sessionCost({ session })` returns the compact per-session cost shape (`totalUSD`, `totalTokens`, `turnCount`, `models`) the MCP `burn__sessionCost` tool now wraps directly.
-- `summary()` result now includes `turnCount`.
-- `summary()` and `sessionCost()` read through the SQLite archive by default with transparent fallback to the JSONL ledger walk on archive failure. Pass `onLog` to capture the fallback reason.
-- `overhead({ project, since?, kind? })` returns per-file + per-section overhead cost attribution (the JSON shape `burn overhead --json` now consumes).
-- `overheadTrim({ project, since?, kind?, top?, includeDiff? })` returns trim recommendations with projected savings and (by default) embedded unified diffs (the JSON shape `burn overhead trim --json` now consumes). Pass `includeDiff: false` to skip the per-file disk reads.
-- `summary({ since })` and `overhead({ since })` / `overheadTrim({ since })` now accept either an ISO timestamp or a relative range (`24h`, `7d`, `4w`, `2m`); the SDK normalizes both forms before querying the ledger so direct SDK callers get the same forgiving input shape CLI users have. Previously a raw relative string would silently filter out every turn.
-
-## [1.7.0] - 2026-05-02
+## [2.1.0] - 2026-05-07
 
 ### Added
 
-- `hotspots({ patterns })` now also surfaces `tool-output-bloat`, `ghost-surface`, and `tool-call-pattern` findings (previously only the core `detectPatterns` set). Each side-channel detector loads its own inputs (Claude settings, tool-result events, on-disk surface) lazily based on the requested patterns.
-
-### Changed
-
-- SDK no longer depends on `@relayburn/cli`. `ingest()` now imports from the new `@relayburn/ingest` package, and `buildGhostSurfaceInputs` lives in `@relayburn/analyze`. The SDK's public surface is unchanged.
-
-## [1.5.0] - 2026-05-01
-
-### Added
+- `summary()` result now includes `replacementSavings` — a rollup of per-tool collapsed-call counts and tokens-saved estimates derived from `_meta`-annotated tool results. Omitted (field absent) when no replacement-tool calls exist in the queried window.
+
+## [2.0.0] - 2026-05-07
+
+- Initial scaffolding: umbrella package layout (`@relayburn/sdk`) +
+  per-platform packages (`@relayburn/sdk-{darwin-arm64,darwin-x64,linux-arm64-gnu,linux-x64-gnu}`)
+  resolved via `optionalDependencies`, TS facade re-exporting the napi-rs
+  binding, conformance scaffold against the TS 1.x SDK, esbuild bundle
+  smoke test. (#247 part b)
+- Shape conformance with TS `@relayburn/sdk@1.x`: `Ledger.open()` returns
+  a `Promise<Ledger>` instance, `sessionCost()` emits `totalUSD`
+  (screaming USD), every read verb is `async` (`Promise<T>`),
+  `IngestOptions` is `{ sessionId, harness, ledgerHome }`, `top` and
+  `minSample` accept plain `number`, and `onLog` callbacks are accepted
+  on every read verb's options (silently dropped at the napi boundary
+  until the SDK wires fallback logging). Adds `search`, `exportLedger`,
+  `exportStamps`, `BurnErrorCode`, `OverheadFileKind`, and
+  `HotspotsGroupBy` as 2.x extensions over the 1.x surface. (#247 part c)
+- Umbrella facade now coerces napi-rs `BigInt` return values to `Number`
+  for safe-range integers (`[Number.MIN_SAFE_INTEGER,
+  Number.MAX_SAFE_INTEGER]`), matching the TS 1.x runtime shape; values
+  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)
 
-- Initial release with embedded `Ledger.open()`, `ingest()`, `summary()`, and `hotspots()` helpers.

package/README.md

@@ -1,50 +1,36 @@
-# @relayburn/sdk
-
-Embeddable Relayburn SDK for in-process ingestion and analysis. This package is the **source of truth** for the in-process query/compute surface — `@relayburn/mcp` and `@relayburn/cli` consume the SDK rather than duplicating its logic.
-
-```ts
-import {
-  Ledger,
-  ingest,
-  summary,
-  sessionCost,
-  compare,
-  overhead,
-  overheadTrim,
-  hotspots,
-} from '@relayburn/sdk';
-
-await Ledger.open({ home: '/tmp/relayburn-home' });
-await ingest({ ledgerHome: '/tmp/relayburn-home' });
-
-// Slice-wide rollup: turnCount + per-model + per-tool aggregates.
-const stats = await summary({ session: 'session-id', ledgerHome: '/tmp/relayburn-home' });
-
-// Compact session-scoped cost shape (totalUSD/totalTokens/turnCount/models).
-// Powers the MCP `burn__sessionCost` tool.
-const cost = await sessionCost({ session: 'session-id' });
-
-// Per-(model, activity) comparison shape — the JSON object `burn compare --json` emits.
-const cmp = await compare({
-  models: ['claude-sonnet-4-6', 'claude-haiku-4-5'],
-  since: '30d',
-  minFidelity: 'usage-only',
-});
-
-// Overhead-file (CLAUDE.md / AGENTS.md / .claude/CLAUDE.md) cost attribution.
-const oh = await overhead({ project: '/path/to/repo', since: '30d' });
-const trim = await overheadTrim({ project: '/path/to/repo', top: 3 });
-
-// Per-axis hotspot attribution + pattern findings. Returns a discriminated
-// union — branch on `kind`:
-//   { kind: 'attribution', files, bashVerbs, bash, subagents, sessions, … }
-//   { kind: 'bash' | 'bash-verb' | 'file' | 'subagent', rows: [...] }
-//   { kind: 'findings', findings: WasteFinding[], summary }
-const attribution = await hotspots({ session: 'session-id' });
-const fileRows = await hotspots({ session: 'session-id', groupBy: 'file' });
-const findings = await hotspots({ session: 'session-id', patterns: ['retry-loop'] });
-```
-
-`summary`, `sessionCost`, `compare`, `overhead`, `overheadTrim`, and `hotspots` read through the SQLite archive when available, transparently falling back to the JSONL ledger walk if the archive can't be opened. Pass `onLog` to surface fallback messages in your host's log channel.
-
-`overheadTrim` includes a unified-diff string per recommendation by default (matches `burn overhead trim --json`); pass `includeDiff: false` to skip the per-file disk reads when you only need the recommendation rows.
+# @relayburn/sdk (2.x)
+
+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/`.
+
+The 2.x umbrella resolves the right native binary for your platform via
+`optionalDependencies`:
+
+| Platform | Package |
+|---|---|
+| darwin-arm64 (Apple Silicon) | `@relayburn/sdk-darwin-arm64` |
+| darwin-x64 (Intel Mac) | `@relayburn/sdk-darwin-x64` |
+| linux-arm64-gnu | `@relayburn/sdk-linux-arm64-gnu` |
+| linux-x64-gnu | `@relayburn/sdk-linux-x64-gnu` |
+
+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.

package/package.json

@@ -1,35 +1,64 @@
 {
   "name": "@relayburn/sdk",
-  "version": "1.10.0",
-  "description": "Embeddable Relayburn SDK for in-process ingest, summary, and hotspots queries",
+  "version": "2.1.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": "./index.js",
-  "types": "./index.d.ts",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    }
+  },
   "files": [
-    "index.js",
-    "index.d.ts",
+    "src/index.js",
+    "src/index.cjs",
+    "src/index.d.ts",
+    "src/binding.cjs",
+    "src/binding.d.ts",
     "README.md",
     "CHANGELOG.md",
     "package.json"
   ],
+  "scripts": {
+    "build": "node -e \"process.exit(0)\"",
+    "build:napi": "napi build --platform --release --cargo-cwd ../../crates/relayburn-sdk-node --js binding.cjs --dts binding.d.ts src",
+    "build:napi:debug": "napi build --platform --cargo-cwd ../../crates/relayburn-sdk-node --js binding.cjs --dts binding.d.ts src",
+    "test": "node --test 'test/**/*.test.js'",
+    "test:bundle": "node test/esbuild-smoke.test.js"
+  },
   "engines": {
     "node": ">=22"
   },
-  "dependencies": {
-    "@relayburn/analyze": "1.10.0",
-    "@relayburn/ingest": "1.10.0",
-    "@relayburn/ledger": "1.10.0",
-    "@relayburn/reader": "1.10.0"
+  "napi": {
+    "binaryName": "relayburn-sdk",
+    "packageName": "@relayburn/sdk",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu"
+    ]
+  },
+  "optionalDependencies": {
+    "@relayburn/sdk-darwin-arm64": "2.1.0",
+    "@relayburn/sdk-darwin-x64": "2.1.0",
+    "@relayburn/sdk-linux-arm64-gnu": "2.1.0",
+    "@relayburn/sdk-linux-x64-gnu": "2.1.0"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4",
+    "esbuild": "^0.25.0"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/AgentWorkforce/burn",
-    "directory": "packages/sdk"
+    "directory": "packages/sdk-node"
   },
   "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "node -e \"process.exit(0)\""
+    "access": "public",
+    "tag": "next"
   }
-}
+}

package/src/binding.cjs

@@ -0,0 +1,91 @@
+// Native-binding loader. At publish time, `napi build` (via `@napi-rs/cli`)
+// regenerates this file to dispatch to the right per-platform package
+// (`@relayburn/sdk-darwin-arm64`, `@relayburn/sdk-linux-x64-gnu`, etc.) based
+// on `process.platform` + `process.arch` + libc detection. The generated
+// version pulls the prebuilt `.node` file out of `optionalDependencies` so
+// installs don't need a Rust toolchain.
+//
+// **File extension note:** this file is `.cjs` (not `.js`) because the
+// umbrella package is `"type": "module"`, which would make Node treat a
+// bare `.js` as ESM and reject the `module.exports` below at load time.
+// `napi build` is invoked with `--js src/binding.cjs` (see
+// `package.json` scripts + `.github/workflows/napi-build.yml`) so the
+// regeneration writes back to the `.cjs` path; both `src/index.js`
+// (ESM facade) and `src/index.cjs` (CJS facade) `require('./binding.cjs')`.
+//
+// This stub matches the napi-rs-generated dispatcher *shape* so the umbrella
+// package's TS facade (`src/index.js`) can import from it during local dev /
+// CI conformance scaffolding before the prebuilt binaries exist. While
+// #247-a is in flight, we throw a clear "binding not built" error instead of
+// requiring `*.node` artifacts that don't exist yet.
+//
+// Once `napi build` runs in CI for the first time, this file is overwritten;
+// see `.github/workflows/napi-build.yml`.
+
+const { existsSync, readFileSync } = require('node:fs');
+const { join } = require('node:path');
+const { platform, arch } = process;
+
+// Detect glibc vs musl on Linux. napi-rs generates this with `detect-libc`
+// at build time; we keep a minimal fallback so `require('./binding.cjs')`
+// doesn't crash when run before the binary build.
+function isMusl() {
+  if (!process.report) return false;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const { glibcVersionRuntime } = (process.report.getReport() || {}).header || {};
+    return !glibcVersionRuntime;
+  } catch (_) {
+    return false;
+  }
+}
+
+let nativeBinding = null;
+let loadError = null;
+
+function tryRequire(specifier, localFile) {
+  // Prefer the optional-dep platform package; fall back to a sibling .node
+  // that `napi build --release` drops next to this loader during local dev.
+  const localPath = localFile ? join(__dirname, '..', localFile) : null;
+  if (localPath && existsSync(localPath)) {
+    try {
+      return require(localPath);
+    } catch (e) {
+      loadError = e;
+    }
+  }
+  try {
+    return require(specifier);
+  } catch (e) {
+    loadError = e;
+    return null;
+  }
+}
+
+if (platform === 'darwin' && arch === 'arm64') {
+  nativeBinding = tryRequire('@relayburn/sdk-darwin-arm64', 'relayburn-sdk.darwin-arm64.node');
+} else if (platform === 'darwin' && arch === 'x64') {
+  nativeBinding = tryRequire('@relayburn/sdk-darwin-x64', 'relayburn-sdk.darwin-x64.node');
+} else if (platform === 'linux' && arch === 'arm64' && !isMusl()) {
+  nativeBinding = tryRequire('@relayburn/sdk-linux-arm64-gnu', 'relayburn-sdk.linux-arm64-gnu.node');
+} else if (platform === 'linux' && arch === 'x64' && !isMusl()) {
+  nativeBinding = tryRequire('@relayburn/sdk-linux-x64-gnu', 'relayburn-sdk.linux-x64-gnu.node');
+}
+
+if (!nativeBinding) {
+  // Surface a clear actionable error. While #247-a is still merging, this is
+  // the failure mode CI / dev machines will hit; the conformance test
+  // `test/conformance.test.js` checks for it and skips so the suite stays
+  // green until bindings land.
+  const detail = loadError
+    ? `\nUnderlying error: ${loadError.message}`
+    : '';
+  throw new Error(
+    `@relayburn/sdk: native binding not found for ${platform}-${arch}.\n` +
+    `Expected one of @relayburn/sdk-{darwin-arm64,darwin-x64,linux-arm64-gnu,linux-x64-gnu} ` +
+    `to be installed via optionalDependencies, or a sibling .node prebuilt by ` +
+    `\`pnpm --filter @relayburn/sdk run build:napi\`.${detail}`,
+  );
+}
+
+module.exports = nativeBinding;

package/src/binding.d.ts

@@ -0,0 +1,21 @@
+// Generated by `napi build --dts` at publish time. This stub matches the
+// expected exported function names from `crates/relayburn-sdk-node` (#247-a).
+// Once the bindings land, `napi build` overwrites this file with the real
+// generated declarations.
+//
+// The umbrella's `src/index.js` re-exports these directly. The runtime
+// shape is the discriminated unions / option objects defined in
+// `src/index.d.ts`; this file just declares "the binding exposes these
+// names as functions."
+
+export declare class Ledger {
+  static open(opts?: { home?: string }): Promise<Ledger>;
+}
+
+export declare function ingest(opts?: unknown): Promise<unknown>;
+export declare function summary(opts?: unknown): Promise<unknown>;
+export declare function sessionCost(opts?: unknown): Promise<unknown>;
+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>;

package/src/index.cjs

@@ -0,0 +1,68 @@
+// CommonJS variant of the umbrella facade. Required for tools that resolve
+// `require('@relayburn/sdk')` through CJS — the ESM `src/index.js` is the
+// canonical entry point, but Node falls back to this when a consumer's
+// 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);
+// see `src/index.js` for the rationale.
+
+'use strict';
+
+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.
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+
+function coerceBigInts(value) {
+  if (typeof value === 'bigint') {
+    return value >= MIN_SAFE && value <= MAX_SAFE ? Number(value) : value;
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      value[i] = coerceBigInts(value[i]);
+    }
+    return value;
+  }
+  if (value !== null && typeof value === 'object') {
+    const proto = Object.getPrototypeOf(value);
+    if (proto === null || proto === Object.prototype) {
+      for (const key of Object.keys(value)) {
+        value[key] = coerceBigInts(value[key]);
+      }
+    }
+    return value;
+  }
+  return value;
+}
+
+class Ledger {
+  constructor(home) {
+    this.home = home;
+  }
+  static async open(opts) {
+    const home = binding.ledgerOpen(opts);
+    return new Ledger(home);
+  }
+}
+
+module.exports = {
+  Ledger,
+  ingest: async (opts) => coerceBigInts(await binding.ingest(opts)),
+  summary: async (opts) => coerceBigInts(await binding.summary(opts)),
+  sessionCost: async (opts) => coerceBigInts(await binding.sessionCost(opts)),
+  overhead: async (opts) => coerceBigInts(await binding.overhead(opts)),
+  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)),
+  exportLedger: async (opts) => coerceBigInts(await binding.exportLedger(opts)),
+  exportStamps: async (opts) => coerceBigInts(await binding.exportStamps(opts)),
+  BurnErrorCode: binding.BurnErrorCode,
+  OverheadFileKind: binding.OverheadFileKind,
+  HotspotsGroupBy: binding.HotspotsGroupBy,
+};