@relayburn/sdk 1.10.0 → 2.1.0

package/{index.d.ts → src/index.d.ts}

@@ -1,8 +1,36 @@
-export interface LedgerOpenOptions { home?: string }
-export declare class Ledger { static open(opts?: LedgerOpenOptions): Promise<Ledger> }
+// Type surface for `@relayburn/sdk@2.x`.
+//
+// Mirrors `packages/sdk/index.d.ts` (the TS 1.x SDK) byte-for-byte modulo:
+//   - `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).
+//   - 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.
+ */
+export declare class Ledger {
+  readonly home: string;
+  static open(opts?: LedgerOpenOptions): Promise<Ledger>;
+}
 
 export interface IngestOptions { sessionId?: string; harness?: 'claude-code'|'codex'|'opencode'; ledgerHome?: string }
-export declare function ingest(opts?: IngestOptions): Promise<unknown>
+export interface IngestReport {
+  scannedSessions: number | bigint;
+  ingestedSessions: number | bigint;
+  appendedTurns: number | bigint;
+}
+export declare function ingest(opts?: IngestOptions): Promise<IngestReport>
 
 export interface SummaryOptions {
   session?: string;
@@ -14,11 +42,22 @@ export interface SummaryOptions {
   onLog?: (msg: string) => void;
 }
 export declare function summary(opts?: SummaryOptions): Promise<{
-  totalTokens: number;
+  totalTokens: number | bigint;
   totalCost: number;
   turnCount: number;
-  byTool: Array<{ tool: string; tokens: number; cost: number; count: number }>;
-  byModel: Array<{ model: string; tokens: number; cost: number }>;
+  byTool: Array<{ tool: string; tokens: number | bigint; cost: number; count: number }>;
+  byModel: Array<{ model: string; tokens: number | bigint; cost: number }>;
+  replacementSavings?: {
+    calls: number | bigint;
+    collapsedCalls: number | bigint;
+    estimatedTokensSaved: number | bigint;
+    byTool: Array<{
+      tool: string;
+      calls: number | bigint;
+      collapsedCalls: number | bigint;
+      estimatedTokensSaved: number | bigint;
+    }>;
+  };
 }>
 
 export interface SessionCostOptions {
@@ -30,7 +69,7 @@ export interface SessionCostOptions {
 export interface SessionCostResult {
   sessionId: string | null;
   totalUSD: number;
-  totalTokens: number;
+  totalTokens: number | bigint;
   turnCount: number;
   models: string[];
   note?: string;
@@ -42,11 +81,8 @@ export type OverheadFileKind = 'claude-md' | 'agents-md';
 export type OverheadHarness = 'claude-code' | 'codex' | 'opencode';
 
 export interface OverheadOptions {
-  /** Project path to inspect; defaults to process.cwd(). */
   project?: string;
-  /** ISO timestamp or relative range (`24h`, `7d`, `4w`, `2m`); the SDK normalizes both forms before querying. */
   since?: string;
-  /** Narrow to a single overhead file kind. */
   kind?: OverheadFileKind;
   ledgerHome?: string;
   onLog?: (msg: string) => void;
@@ -56,7 +92,7 @@ export interface OverheadSection {
   heading: string;
   startLine: number;
   endLine: number;
-  tokens: number;
+  tokens: number | bigint;
 }
 
 export interface OverheadSectionCost {
@@ -80,8 +116,8 @@ export interface OverheadFileSummary {
   path: string;
   appliesTo: OverheadHarness[];
   totalLines: number;
-  bytes: number;
-  tokens: number;
+  bytes: number | bigint;
+  tokens: number | bigint;
   sections: OverheadSection[];
   groupingLevel: number;
 }
@@ -104,9 +140,7 @@ export interface OverheadResult {
 export declare function overhead(opts?: OverheadOptions): Promise<OverheadResult>
 
 export interface OverheadTrimOptions extends OverheadOptions {
-  /** Recommendations per file. Default 3. */
   top?: number;
-  /** Include the unified-diff text per recommendation (requires a file read per recommended file). Default true; pass false to skip. */
   includeDiff?: boolean;
 }
 
@@ -114,11 +148,11 @@ export interface OverheadTrimRecommendation {
   file: string;
   kind: OverheadFileKind;
   appliesTo: OverheadHarness[];
-  section: { heading: string; startLine: number; endLine: number; tokens: number };
+  section: { heading: string; startLine: number; endLine: number; tokens: number | bigint };
   projectedSavings: {
     perSessionUsd: number;
     acrossWindowUsd: number;
-    tokens: number;
+    tokens: number | bigint;
     tokenShare: number;
   };
   diff?: string;
@@ -145,68 +179,47 @@ export type HotspotsGroupBy = 'attribution' | 'bash' | 'bash-verb' | 'file' | 's
 export interface HotspotsOptions {
   session?: string;
   project?: string;
-  /** ISO timestamp (e.g. `2026-04-01T00:00:00Z`) or relative range (`24h`, `7d`, `4w`, `2m`). */
   since?: string;
-  /**
-   * Narrow the attribution result to a single aggregation axis. When omitted
-   * (or `'attribution'`), the full attribution shape is returned. Ignored
-   * when `patterns` is set — patterns always returns the `findings` shape.
-   */
   groupBy?: HotspotsGroupBy;
-  /**
-   * Pattern kinds to detect. Supported kinds:
-   *   - core (via `detectPatterns`): `retry-loop`, `failure-run`,
-   *     `cancellation-run`, `compaction-loss`, `edit-revert`, `edit-heavy`,
-   *     `skill-recall-dup`, `skill-pruning-protection`, `system-prompt-tax`
-   *   - side-channel: `tool-output-bloat`, `ghost-surface`, `tool-call-pattern`
-   *
-   * When omitted or empty, returns the attribution result instead of the
-   * findings shape.
-   */
   patterns?: 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;
 }
 
-/** Per-axis aggregation row (file). */
 export interface HotspotsFileRow {
   path: string;
   firstEmitTurnIndex: number;
-  initialTokens: number;
-  persistenceTokens: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
   ridingTurns: number;
   totalCost: number;
 }
 
-/** Per-axis aggregation row (bash, exact command). */
 export interface HotspotsBashRow {
   command: string | undefined;
   argsHash: string;
   callCount: number;
-  initialTokens: number;
-  persistenceTokens: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
   totalCost: number;
 }
 
-/** Per-axis aggregation row (bash, by leading verb). */
 export interface HotspotsBashVerbRow {
   verb: string;
   callCount: number;
   distinctCommands: number;
-  initialTokens: number;
-  persistenceTokens: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
   avgPersistenceTurns: number;
   totalCost: number;
   topExamples: string[];
 }
 
-/** Per-axis aggregation row (subagent / Agent / Task). */
 export interface HotspotsSubagentRow {
   subagentType: string;
   callCount: number;
-  initialTokens: number;
-  persistenceTokens: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
   totalCost: number;
 }
 
@@ -221,12 +234,10 @@ export interface HotspotsSessionTotal {
 export interface HotspotsFidelityBlock {
   analyzed: number;
   excluded: number;
-  /** Aggregate fidelity summary for the matched-window turns (analyzed + excluded). */
   summary: unknown;
   refused: boolean;
 }
 
-/** Full attribution shape — mirrors the CLI's `burn hotspots --json`. */
 export interface HotspotsAttributionResult {
   kind: 'attribution';
   turnsAnalyzed: number;
@@ -240,12 +251,10 @@ export interface HotspotsAttributionResult {
   bash: HotspotsBashRow[];
   subagents: HotspotsSubagentRow[];
   fidelity: HotspotsFidelityBlock;
-  /** Set when every matched turn lacked the coverage attribution needs. */
   refused?: boolean;
   refusalReason?: string;
 }
 
-/** Narrowed shapes — one aggregation axis only. */
 export interface HotspotsBashResult { kind: 'bash'; rows: HotspotsBashRow[]; refused?: boolean; refusalReason?: string }
 export interface HotspotsBashVerbResult { kind: 'bash-verb'; rows: HotspotsBashVerbRow[]; refused?: boolean; refusalReason?: string }
 export interface HotspotsFileResult { kind: 'file'; rows: HotspotsFileRow[]; refused?: boolean; refusalReason?: string }
@@ -263,7 +272,6 @@ export interface HotspotsFinding {
 export interface HotspotsFindingsResult {
   kind: 'findings';
   findings: HotspotsFinding[];
-  /** Aggregate fidelity summary for the matched-window turns. */
   summary: unknown;
 }
 
@@ -315,19 +323,14 @@ export interface CompareCellResult {
 }
 
 export interface CompareOptions {
-  /** Required: ≥2 model names to compare. */
   models: string[];
   session?: string;
   project?: string;
-  /** ISO timestamp (e.g. `2026-04-01T00:00:00Z`) or relative range (`24h`, `7d`, `4w`, `2m`). */
   since?: string;
   workflow?: string;
   agent?: string;
-  /** Resolved provider filter (e.g. `['anthropic', 'synthetic']`). */
   provider?: string[];
-  /** Insufficient-sample threshold; cells below this get flagged. Default 5. */
   minSample?: number;
-  /** Minimum fidelity class to include in the aggregate. Default `'usage-only'`. */
   minFidelity?: FidelityClass;
   ledgerHome?: string;
   onLog?: (msg: string) => void;
@@ -347,12 +350,84 @@ export interface CompareResult {
   };
 }
 
+/** Per-(model, activity) comparison shape. Powers `burn compare`. */
+export declare function compare(opts: CompareOptions): Promise<CompareResult>
+
+// ---------------------------------------------------------------------------
+// 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).
+// ---------------------------------------------------------------------------
+
+export interface SearchQueryOptions {
+  /** FTS5 query string. Phrase, boolean, and prefix syntax supported. */
+  query: string;
+  /** Hit cap. Defaults to 25 when omitted. */
+  limit?: number | bigint;
+  /** Restrict to a single session_id. Omit to search all sessions. */
+  sessionId?: string;
+  ledgerHome?: string;
+}
+
+export interface SearchHit {
+  sessionId: string;
+  messageId: string;
+  source: string;
+  /** FTS5 BM25 rank (lower = better match). */
+  rank: number;
+  /** `<b>…</b>`-highlighted snippet around the matching tokens. */
+  snippet: string;
+}
+
+export interface SearchResult {
+  query: string;
+  hits: SearchHit[];
+}
+
+/** FTS5-backed message-content search. 2.x extension over the TS surface. */
+export declare function search(opts: SearchQueryOptions): Promise<SearchResult>
+
+export interface ExportLedgerOptions { ledgerHome?: string }
+export interface ExportStampsOptions { ledgerHome?: string }
+
 /**
- * Per-(model, activity) comparison shape. Powers `burn compare` and the
- * future `burn__compare` MCP tool. Reads through the SQLite archive when
- * `minFidelity === 'partial'` and no provider filter is set; otherwise
- * walks the ledger so the fidelity gate / provider filter can be applied
- * per-turn. Falls back transparently to the ledger walk when the archive
- * read fails.
+ * Stream every event row as a JSONL-shaped JSON object. Each value has
+ * the form `{ v: 1, kind: '<kind>', record: <json> }`. 2.x extension.
  */
-export declare function compare(opts: CompareOptions): Promise<CompareResult>
+export declare function exportLedger(opts?: ExportLedgerOptions): Promise<unknown[]>
+
+/** Stream every stamp row as a JSONL-shaped JSON object. 2.x extension. */
+export declare function exportStamps(opts?: ExportStampsOptions): Promise<unknown[]>
+
+/**
+ * Tagged error code surfaced on the thrown JS `Error.code` property.
+ * Sync verbs reject with one of these; the async `ingest` verb's
+ * rejection currently sets `code: 'GenericFailure'` — see the binding
+ * crate's `ingest` doc comment for the napi-rs-2.x rationale.
+ *
+ * The values are the literal strings written to `e.code`, matching the
+ * Rust constants `SDK_ERROR_CODE` / `IO_ERROR_CODE` / `INVALID_ARGUMENT_ERROR_CODE`.
+ */
+export declare const BurnErrorCode: {
+  readonly Sdk: 'BURN_SDK';
+  readonly Io: 'BURN_IO';
+  readonly InvalidArgument: 'BURN_INVALID_ARGUMENT';
+};
+export type BurnErrorCodeValue = (typeof BurnErrorCode)[keyof typeof BurnErrorCode];
+
+/** Wire-value enum for `OverheadOptions.kind` and `OverheadTrimOptions.kind`. */
+export declare const OverheadFileKind: {
+  readonly ClaudeMd: 'claude-md';
+  readonly AgentsMd: 'agents-md';
+};
+
+/** Wire-value enum for `HotspotsOptions.groupBy`. */
+export declare const HotspotsGroupBy: {
+  readonly Attribution: 'attribution';
+  readonly Bash: 'bash';
+  readonly BashVerb: 'bash-verb';
+  readonly File: 'file';
+  readonly Subagent: 'subagent';
+};

package/src/index.js

@@ -0,0 +1,144 @@
+// 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`:
+//
+//   1. The sync `#[napi]` verbs (`summary`, `sessionCost`, `overhead`,
+//      `overheadTrim`, `hotspots`, `compare`) are re-exported as `async`
+//      functions so callers receive `Promise<T>` (matching the 1.x
+//      `Promise<...>` return shape). Awaiting an `async` wrapper around a
+//      sync return is free and preserves the typed `e.code` thrown by the
+//      binding (`BurnErrorCode.Sdk` / `Io` / `InvalidArgument`).
+//   2. `Ledger.open()` is a JS-side wrapper around the binding's
+//      `ledgerOpen()` smoke verb. The 1.x `Ledger` class only exposes a
+//      static `open(opts)` that returns a placeholder instance, so we
+//      keep the same shape here without adding a stateful `#[napi]` class
+//      (which would force `Mutex<LedgerHandle>` plumbing for no benefit).
+//
+// All query / compute logic lives in the Rust SDK (`crates/relayburn-sdk`);
+// the binding crate (`crates/relayburn-sdk-node`) wraps it for napi-rs.
+
+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.
+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') {
+    // Skip class instances we don't own (Date, Map, Set, Buffer, …) —
+    // walking their guts would be both wasteful and risky. Plain objects
+    // produced by napi-rs serde have a null or Object prototype.
+    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;
+}
+
+/**
+ * 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.
+ */
+export class Ledger {
+  constructor(home) {
+    /** @type {string} */
+    this.home = home;
+  }
+  /**
+   * Open and validate a ledger at `opts.home` (or `RELAYBURN_HOME`).
+   * Returns a `Promise<Ledger>` to mirror the 1.x async signature even
+   * though the underlying `ledgerOpen` binding is synchronous.
+   *
+   * @param {{ home?: string, contentHome?: string }} [opts]
+   * @returns {Promise<Ledger>}
+   */
+  static async open(opts) {
+    const home = binding.ledgerOpen(opts);
+    return new Ledger(home);
+  }
+}
+
+export async function ingest(opts) {
+  return coerceBigInts(await binding.ingest(opts));
+}
+
+export async function summary(opts) {
+  return coerceBigInts(await binding.summary(opts));
+}
+
+export async function sessionCost(opts) {
+  return coerceBigInts(await binding.sessionCost(opts));
+}
+
+export async function overhead(opts) {
+  return coerceBigInts(await binding.overhead(opts));
+}
+
+export async function overheadTrim(opts) {
+  return coerceBigInts(await binding.overheadTrim(opts));
+}
+
+export async function hotspots(opts) {
+  return coerceBigInts(await binding.hotspots(opts));
+}
+
+export async function compare(opts) {
+  return coerceBigInts(await binding.compare(opts));
+}
+
+// 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.
+export async function search(opts) {
+  return coerceBigInts(await binding.search(opts));
+}
+
+export async function exportLedger(opts) {
+  return coerceBigInts(await binding.exportLedger(opts));
+}
+
+export async function exportStamps(opts) {
+  return coerceBigInts(await binding.exportStamps(opts));
+}
+
+// Re-exported enums from the Rust binding. These come across as plain
+// string-valued objects (`{ Sdk: 'BURN_SDK', ... }`) and let JS callers
+// branch on `e.code === BurnErrorCode.Sdk` without stringly-typed
+// literals. `OverheadFileKind` and `HotspotsGroupBy` are likewise the
+// canonical wire values for the matching option-struct fields.
+export const BurnErrorCode = binding.BurnErrorCode;
+export const OverheadFileKind = binding.OverheadFileKind;
+export const HotspotsGroupBy = binding.HotspotsGroupBy;