Skip to content

[G2] Node SDK and MCP packaging with the relayhistory backend: single native addon, IngestOptions.source, platform matrix, bundle smoke test #559

Description

@willwashburn

Part of #553 (group 2 — depends on burn #557 backend; parallel with #558/#561).

Problem

@relayburn/sdk is a napi-rs facade (crates/relayburn-sdk-node → packages/sdk-node, prebuilt @relayburn/sdk-<platform> packages) and @relayburn/mcp sits on top of it. The Node surface exposes no reader/parser API (packages/sdk-node/src/index.d.ts is verbs only: ingest, writePendingStamp, summary, hotspots, …), and IngestOptions is { sessionId?, harness?: 'claude-code'|'codex'|'opencode', ledgerHome? } — it does not expose IngestRoots, so nothing in JS needs to change semantically. What changes is the build:

  • The ai-hist Rust crate links statically into relayburn-sdk-node, so no second native addon is needed and ai-hist-native (relayhistory's own napi package) must not become a dependency — a JS consumer that also installs ai-hist would otherwise load two SQLite copies against the same DB file.
  • Both crates bundle SQLite (rusqlite bundled); one binary, one SQLite.
  • The platform matrix in .github/workflows/napi-build.yml / cli-build.yml must still build (glibc floor, musl, Windows — burn Add Windows targets to napi sdk-node + CLI binary distribution #359 is open for Windows).
  • pnpm run test:bundle (esbuild smoke) must keep passing.

Scope

  1. IngestOptions gains source?: 'builtin' | 'relayhistory' and historyDbPath?: string (maps to StoreOptions.db_path; default = relayhistory's own default path resolution incl. AI_HIST_DB). LedgerOpenOptions gains the same so Ledger.open can pin a backend for the process. writePendingStamp.harness type widened per [G3] Harness expansion through relayhistory: Cursor and Grok in burn (SourceKind, pricing, TOOL_ALIASES, overhead mapping, fidelity policy) and collector-backlog transfer #560.
  2. Surface relayhistory's typed Error variants (SyncLocked, WatermarkAheadOfStore, SourceMismatch, database-open failure) as @relayburn/sdk error classes with codes, alongside the existing ledger errors.
  3. Build: enable the relayhistory-source feature in the napi and CLI release builds (feature stays off for the plain cargo build until [G3] Cutover: relayhistory becomes the default and only source; delete the harness readers, walkers, cursors and fs watcher; ship as a major release #562); verify binary size delta and startup time; document in packages/sdk-node/CHANGELOG.md.
  4. CI: extend napi-build.yml/cli-build.yml so every platform artefact runs burn --ledger-path <tmp> ingest with RELAYBURN_SOURCE=relayhistory against a corpus fixture HOME and asserts appendedTurns > 0; extend verify-publish.yml accordingly.
  5. @relayburn/mcp: no tool changes; add a test that burn mcp-server over a relayhistory-backed ledger returns the same summary as the builtin ledger (fixture).
  6. Docs: packages/sdk-node/README + index.d.ts JSDoc for the new options; state that @relayburn/sdk does not depend on ai-hist-native.

Acceptance

  • npm ls in a project with both @relayburn/sdk and ai-hist shows no shared native package; both open the same ai-history.db sequentially without error (WAL, read-only in burn).
  • All platform artefacts pass the ingest smoke under the relayhistory backend.
  • pnpm run test and pnpm run test:bundle green.

Out of scope

Default flip (#562).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions