@gitsheets/core-napi 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @gitsheets/core-napi
+
+Node.js native binding for [`gitsheets-core`](../gitsheets-core) — the FFI
+marshalling boundary between the published `gitsheets` npm package (a thin
+TypeScript shell) and the Rust engine that owns the bytes: TOML parse/serialize,
+canonical normalization, path templates, JSON-Schema validation, the embedded
+JS engine, ICU collation, record CRUD / query / index, diff/patch, attachments,
+and the `Sheet`/`Transaction`/`Store` state machine. Tree/blob/commit ops run on
+`holo-tree` (gitoxide) inside the core.
+
+This package exists so that a consumer can `npm install gitsheets` and get a
+working native addon **without a Rust toolchain** — the matching prebuilt binary
+is pulled in as an `optionalDependency` platform package.
+
+## Building (in-repo development)
+
+Requires a Rust toolchain and `@napi-rs/cli` (a devDependency):
+
+```sh
+npm install
+npm run build:debug   # or: npm run build   (release)
+npm test              # node --test against scratch git repos
+```
+
+`napi build` emits `gitsheets-core.<triple>.node`. The generated `index.js`
+loader, `index.d.ts` types, and `binding.cjs` wrapper **are committed**; only the
+`.node` binaries are git-ignored (built per-platform in CI). The `npm/<triple>/`
+platform-package manifests are committed too; their `.node` payloads are dropped
+in at publish time.
+
+In-repo, the JS package resolves this binding through the npm-workspace symlink
+(`node_modules/@gitsheets/core-napi → rust/gitsheets-napi`) and loads the locally
+built `.node` next to `index.js`; the `optionalDependencies` platform packages
+are only used by external consumers.
+
+## Publishing / prebuilds
+
+Published as the scoped package **`@gitsheets/core-napi`** with per-platform
+prebuilt binaries shipped as `optionalDependencies`:
+
+| Platform package | Triple | Built on | Smoke-tested |
+| --- | --- | --- | --- |
+| `@gitsheets/core-napi-linux-x64-gnu` | `x86_64-unknown-linux-gnu` | ubuntu-latest | ✓ native |
+| `@gitsheets/core-napi-linux-arm64-gnu` | `aarch64-unknown-linux-gnu` | ubuntu-24.04-arm | ✓ native |
+| `@gitsheets/core-napi-linux-x64-musl` | `x86_64-unknown-linux-musl` | ubuntu-latest (zig cross) | build-only |
+| `@gitsheets/core-napi-darwin-arm64` | `aarch64-apple-darwin` | macos-latest | ✓ native |
+| `@gitsheets/core-napi-darwin-x64` | `x86_64-apple-darwin` | macos-latest (cross) | build-only |
+| `@gitsheets/core-napi-win32-x64-msvc` | `x86_64-pc-windows-msvc` | windows-latest | ✓ native |
+
+Native targets build + smoke-test on a matching runner; cross targets (musl,
+darwin-x64) build only, since their `.node` can't run on the host arch/libc (the
+logic is covered by the native runs). The `.github/workflows/core-napi.yml`
+workflow builds all six on every PR touching `rust/**`, and on a `core-napi-v*`
+tag it builds then publishes.
+
+Auth is **npm trusted publishing (OIDC)** — no tokens, matching the repo's
+`publish-npm.yml`. Trusted publishing is configured *per package*, and a package
+can't get a trusted publisher until it exists — so the seven packages
+(the main package + six platform packages) need a **one-time manual bootstrap**
+before automated releases work.
+
+### Prerequisite: the `@gitsheets` npm scope
+
+The `@gitsheets` org/scope must exist on npmjs.com and the person running the
+bootstrap must be a member with publish rights. (One-time human setup.)
+
+### One-time bootstrap (manual first publish, then configure trusted publishing)
+
+The seven packages all start at an early version (currently `0.1.0`). They must
+exist on npm before trusted publishing can be turned on.
+
+1. **Get the prebuilt binaries.** Run the `core-napi` workflow (open a PR
+   touching `rust/**`, or trigger `workflow_dispatch`) and download its six
+   `bindings-*` artifacts — they hold the `.node` for each platform. A single
+   machine can't build all six natively, so use the CI artifacts.
+
+2. **Publish all seven manually**, logged in as a `@gitsheets` org member
+   (`npm login`):
+
+   ```sh
+   cd rust/gitsheets-napi
+   npm install
+   npx napi artifacts --dir <downloaded-artifacts-dir>   # → npm/<triple>/*.node
+   # platform packages first, then the main package:
+   for d in npm/*/ ; do ( cd "$d" && npm publish --access public ); done
+   npm publish --access public --ignore-scripts          # main; skip the napi
+                                                         # prepublish hook
+   ```
+
+3. **Turn on trusted publishing** on npmjs.com for **each** of the seven packages
+   → package Settings → Trusted Publisher → GitHub Actions, repo
+   `JarvusInnovations/gitsheets`, workflow `core-napi.yml`.
+
+### Releases (after bootstrap — fully automated, tokenless)
+
+```sh
+git tag core-napi-v0.1.1 && git push origin core-napi-v0.1.1
+```
+
+The tag drives the published version; CI builds all six platforms, then publishes
+via OIDC (provenance). No secret needed. The `core-napi-v*` tag is the release
+marker — napi runs with `--skip-gh-release` so it does **not** create a bare
+`v<version>` GitHub release/tag (which would collide with the `gitsheets`
+JS-package `v*` release namespace owned by `publish-npm.yml`).
+
+**Version scheme.** `@gitsheets/core-napi` carries its own semver in its own
+`core-napi-v*` tag namespace, decoupled from the `gitsheets` package's `v*` tags.
+`packages/gitsheets` depends on it via a caret range (`^0.1.0`) so a compatible
+addon release is picked up without a lockstep bump; widen the range deliberately
+when the addon takes a breaking major.
+
+To add or drop a platform later, edit `napi.triples.additional` +
+`optionalDependencies` in `package.json`, run `npx napi create-npm-dir -t .`,
+add the matching matrix entry in the workflow, and (since it's a new package)
+bootstrap + trust that one package too.

package/binding.cjs

@@ -0,0 +1,178 @@
+'use strict';
+
+// Thin JS surface over the napi addon. The addon (./index.js) marshals records
+// with full type fidelity and throws *structured* errors (own `code`, `status`,
+// `gitsheetsClass`, and `issues`/`conflictingPaths` payloads). This wrapper owns
+// the one genuinely host-specific concern the Rust side can't: constructing real
+// instances of the typed `GitsheetsError` subclasses from `specs/api/errors.md`
+// so consumers can `instanceof` and switch on `err.code`.
+
+const addon = require('./index.js');
+
+class GitsheetsError extends Error {
+  constructor(message, { code, status, cause } = {}) {
+    super(message);
+    this.name = 'GitsheetsError';
+    this.code = code;
+    this.status = status;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+class ConfigError extends GitsheetsError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = 'ConfigError';
+  }
+}
+
+class ValidationError extends GitsheetsError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = 'ValidationError';
+    this.issues = opts.issues ?? [];
+  }
+}
+
+class TransactionError extends GitsheetsError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = 'TransactionError';
+  }
+}
+
+class IndexError extends GitsheetsError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = 'IndexError';
+    if (opts.conflictingPaths !== undefined) this.conflictingPaths = opts.conflictingPaths;
+  }
+}
+
+class RefError extends GitsheetsError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = 'RefError';
+  }
+}
+
+class PathTemplateError extends GitsheetsError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = 'PathTemplateError';
+  }
+}
+
+class NotFoundError extends GitsheetsError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = 'NotFoundError';
+  }
+}
+
+const CLASS_BY_NAME = {
+  ConfigError,
+  ValidationError,
+  TransactionError,
+  IndexError,
+  RefError,
+  PathTemplateError,
+  NotFoundError,
+};
+
+// Map a structured error raised by the addon onto its typed class. The mapping
+// keys off the `gitsheetsClass` discriminant the core sets — never the message.
+function mapCoreError(raw) {
+  const Cls = CLASS_BY_NAME[raw && raw.gitsheetsClass] ?? GitsheetsError;
+  const opts = { code: raw.code, status: raw.status, cause: raw };
+  if (raw.issues !== undefined) opts.issues = raw.issues;
+  if (raw.conflictingPaths !== undefined) opts.conflictingPaths = raw.conflictingPaths;
+  return new Cls(raw.message, opts);
+}
+
+// Wrap an addon call so any structured core error surfaces as its typed class.
+function wrap(fn) {
+  return (...args) => {
+    try {
+      return fn(...args);
+    } catch (raw) {
+      if (raw && typeof raw.gitsheetsClass === 'string') throw mapCoreError(raw);
+      throw raw;
+    }
+  };
+}
+
+module.exports = {
+  // Marshalling entry points (batch-first).
+  roundtrip: addon.roundtrip,
+  // Canonical TOML bytes-authority (batch-first). Parse/serialize can raise a
+  // structured core error (`config_invalid`), surfaced as its typed class.
+  parseRecords: wrap(addon.parseRecords),
+  serializeRecords: wrap(addon.serializeRecords),
+  // Definition logic (batch-first). Path rendering raises a typed
+  // PathTemplateError; schema compilation raises a typed ConfigError.
+  renderPathsBatch: wrap(addon.renderPathsBatch),
+  validateBatch: wrap(addon.validateBatch),
+  runComparator: wrap(addon.runComparator),
+  // Native locale array sort (declarative `sort = true`) — the ICU collator
+  // matching V8 `localeCompare`. Pure (no structured errors), so unwrapped.
+  collatorSort: addon.collatorSort,
+  // Stateful compiled definition (compile-once / reuse). Raw class — its
+  // structured errors carry `gitsheetsClass`; map with `mapCoreError` if needed.
+  CompiledDefinition: addon.CompiledDefinition,
+  // Record CRUD over the holo-tree substrate (batch-first). Substrate / record
+  // parse failures surface as typed core errors.
+  recordRead: wrap(addon.recordRead),
+  recordWrite: wrap(addon.recordWrite),
+  recordDelete: wrap(addon.recordDelete),
+  recordList: wrap(addon.recordList),
+  diffRecords: wrap(addon.diffRecords),
+  // Blob-write primitive: hash raw attachment bytes into the ODB. A substrate
+  // failure surfaces as a typed core error.
+  writeBlob: wrap(addon.writeBlob),
+  // Query traversal + filtering (batch-first): the template prunes the walk and
+  // the filter (equality / nested / `$pred` engine snippets) runs in the core.
+  recordQuery: wrap(addon.recordQuery),
+  recordQueryCandidates: wrap(addon.recordQueryCandidates),
+  templateFieldNames: wrap(addon.templateFieldNames),
+  // Secondary indexing (lazy, in-memory). A unique conflict surfaces as a typed
+  // IndexError(index_unique_conflict).
+  recordIndexUnique: wrap(addon.recordIndexUnique),
+  recordIndexMulti: wrap(addon.recordIndexMulti),
+  // Substrate (holo-tree) read/write counters — bulk benchmark instrumentation.
+  substrateStats: addon.substrateStats,
+  substrateReset: addon.substrateReset,
+  // Diff / patch primitives (RFC 6902 createPatch, RFC 7396 mergePatch).
+  createPatch: wrap(addon.createPatch),
+  applyMergePatch: wrap(addon.applyMergePatch),
+  // Orchestration: Sheet / Transaction / Store state machine (sheet-store-core).
+  // CoreTransaction is the stateful two-phase-protocol driver. Raw class — its
+  // methods throw structured errors carrying `gitsheetsClass`/`code`; map with
+  // `mapCoreError` where a typed instance is wanted.
+  CoreTransaction: addon.CoreTransaction,
+  coreDiscoverSheets: wrap(addon.coreDiscoverSheets),
+  coreCheckValidators: wrap(addon.coreCheckValidators),
+  // Markdown / mdx content-type codec. serialize/parse can raise a typed
+  // ValidationError/ConfigError; the H1 + normalize helpers are pure. Body
+  // NORMALIZATION is native — `markdownSerialize` runs the embedded
+  // `dprint-plugin-markdown` formatter (unless `normalize: false` is passed), and
+  // `markdownNormalizeBody` exposes it directly (see gitsheets_core::codec docs).
+  markdownSerialize: wrap(addon.markdownSerialize),
+  markdownParse: wrap(addon.markdownParse),
+  markdownParseHeaderOnly: wrap(addon.markdownParseHeaderOnly),
+  markdownExtractH1: addon.markdownExtractH1,
+  markdownRewriteH1: addon.markdownRewriteH1,
+  markdownNormalizeBody: addon.markdownNormalizeBody,
+  // Boundary-test entry: throws the typed class for a given stable code.
+  simulateCoreError: wrap(addon.simulateCoreError),
+  // Error machinery.
+  mapCoreError,
+  GitsheetsError,
+  ConfigError,
+  ValidationError,
+  TransactionError,
+  IndexError,
+  RefError,
+  PathTemplateError,
+  NotFoundError,
+};

package/index.d.ts

@@ -0,0 +1,422 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * Round-trip a **batch** of records through the core, preserving full type
+ * fidelity. The whole array crosses the FFI once. This is the foundation's
+ * stand-in for the real batch engine entry points (`upsertMany`, `queryAll`,
+ * …), which keep this same batch-first signature.
+ */
+export declare function roundtrip(records: Array<JsValue>): Array<JsValue>
+/**
+ * Parse a **batch** of TOML documents into records, marshalled to JS with full
+ * type fidelity. The whole array crosses the FFI once (batch-first). A
+ * malformed document surfaces as a structured, typed core error (`config_invalid`).
+ */
+export declare function parseRecords(documents: Array<string>): Array<JsValue>
+/**
+ * Serialize a **batch** of records to their canonical TOML bytes in one call
+ * (deep key sort + `toml`-crate default formatting; see `gitsheets_core::canonical`).
+ * A value TOML can't represent surfaces as a structured, typed core error.
+ */
+export declare function serializeRecords(records: Array<JsValue>): Array<string>
+/**
+ * One JSON-Schema validation failure, marshalled to the `ValidationIssue`
+ * shape the host surface uses (`source`/`schemaPath`/`code`, with snake fields
+ * rendered camelCase by napi). Returned by [`validate_batch`].
+ */
+export interface JsValidationIssue {
+  path: Array<string>
+  message: string
+  source: string
+  schemaPath?: string
+  code?: string
+}
+/**
+ * Render a path template against a **batch** of records, returning one path per
+ * record (no file extension; the caller appends `.toml`/`.md`). The template is
+ * parsed and its expression components compiled into the embedded engine
+ * **once**, then reused across the whole batch — the bulk path crosses the FFI
+ * a single time. A render failure surfaces as a structured, typed
+ * `PathTemplateError` (`path_render_failed` / `path_invalid_chars`). This is the
+ * path-template half of the `node:vm` parity gate.
+ */
+export declare function renderPathsBatch(template: string, records: Array<JsValue>): Array<string>
+/**
+ * Validate a **batch** of records against a JSON Schema, returning the issues
+ * for each record (an empty inner array ⇒ that record is valid). The schema is
+ * compiled **once**, then reused across the batch. Unlike the host's throwing
+ * `validateRecord`, this returns issues per record so a parity harness can diff
+ * the full pass/fail + path/keyword picture against `ajv`. A schema that won't
+ * compile surfaces as a structured, typed `ConfigError` (`config_invalid`).
+ */
+export declare function validateBatch(schema: JsValue, records: Array<JsValue>): Array<Array<JsValidationIssue>>
+/**
+ * Compile a raw-JS sort comparator (`rule`, the body of `(a, b) => { … }`) and
+ * run it once against `a`/`b`, returning its numeric result. The direct
+ * comparator-parity entry point: a harness asserts this equals the same rule
+ * run through `node:vm` for identical inputs.
+ */
+export declare function runComparator(rule: string, a: JsValue, b: JsValue): number
+/**
+ * Native locale array sort — the declarative `sort = true` path. Sorts the
+ * strings with the ICU collator that matches V8's `localeCompare(b, undefined,
+ * { sensitivity: 'base', ignorePunctuation: true, numeric: true })`. This is the
+ * exact function `Sheet::normalize_record` applies for a `sort = true` field, and
+ * it does **NOT** route through the boa engine (boa lacks `Intl`, so its
+ * `localeCompare` falls back to code-unit order and diverges from `node:vm` on
+ * non-ASCII / mixed-case input). Exposed so a `node --test` harness asserts
+ * byte-exact parity against `node`'s `localeCompare` — see
+ * `test/collator-parity.mjs`.
+ */
+export declare function collatorSort(strings: Array<string>): Array<string>
+/**
+ * Read a batch of records by path. Each result is the record (a plain object
+ * with full TOML type fidelity) or `null` when no blob lives at that path.
+ */
+export declare function recordRead(gitDir: string, treeRef: string, base: string, paths: Array<string>, extension?: string | undefined | null): Array<JsValue | undefined | null>
+/**
+ * The result of a `record_write`/`record_delete`: the new root tree hash plus
+ * per-record output (`blobHashes` for writes, `existed` for deletes).
+ */
+export interface JsWriteOutcome {
+  treeHash: string
+  blobHashes: Array<string>
+}
+/** The result of a `record_delete`. */
+export interface JsDeleteOutcome {
+  treeHash: string
+  existed: Array<boolean>
+}
+/**
+ * Write a batch of records (canonical TOML) under `base`, starting from the
+ * tree `baseRef`. `paths[i]` is written from `records[i]`. Returns the new root
+ * tree hash + each written blob hash. The bytes are produced by the core's
+ * bytes-authority, so two bindings writing the same record agree byte-for-byte.
+ */
+export declare function recordWrite(gitDir: string, baseRef: string, base: string, paths: Array<string>, records: Array<JsValue>, extension?: string | undefined | null): JsWriteOutcome
+/**
+ * Delete a batch of records by path under `base`, starting from `baseRef`.
+ * `existed[i]` reports whether `paths[i]` was actually present.
+ */
+export declare function recordDelete(gitDir: string, baseRef: string, base: string, paths: Array<string>, extension?: string | undefined | null): JsDeleteOutcome
+/**
+ * One record from `record_list`: its path (relative to `base`, no extension)
+ * and parsed value.
+ */
+export interface JsRecordEntry {
+  path: string
+  record: JsValue
+}
+/**
+ * List every record under `base` in the tree `treeRef`, in sorted
+ * (git-canonical) path order.
+ */
+export declare function recordList(gitDir: string, treeRef: string, base: string, extension?: string | undefined | null): Array<JsRecordEntry>
+/**
+ * Hash raw bytes into the object database as a loose blob, returning its git
+ * blob hash — the core's blob-write primitive (replaces the JS package's direct
+ * `@hologit/holo-tree` `writeBlob`). Used by the CLI/host to hash a binary
+ * attachment before staging it into a record's attachment tree with
+ * `CoreTransaction.setAttachment(s)`. The hash is a pure function of the bytes,
+ * so Node and Python hashing the same content produce the same object.
+ */
+export declare function writeBlob(gitDir: string, content: Buffer): string
+/**
+ * A snapshot of holo-tree's process-wide tree/blob counters — read-side
+ * instrumentation for the bulk benchmark and the hologit#464 perf finding.
+ */
+export interface JsSubstrateStats {
+  treesRead: number
+  treesWritten: number
+  treesSkippedClean: number
+  cacheHits: number
+  cacheMisses: number
+  blobsRead: number
+}
+/** Snapshot the substrate (holo-tree) counters. */
+export declare function substrateStats(): JsSubstrateStats
+/** Reset the substrate counters + the thread-local tree cache. */
+export declare function substrateReset(): void
+/**
+ * Query records under `base` in the tree `treeRef`, returning each matched
+ * `{ path, record }` in sorted path order. The template prunes the walk; the
+ * filter (equality / nested / `$pred` snippets) is applied to each candidate.
+ * Batch-first: the whole query crosses the FFI once.
+ */
+export declare function recordQuery(gitDir: string, treeRef: string, base: string, template: string, filter: object, extension?: string | undefined | null): Array<JsRecordEntry>
+/**
+ * The pruning candidate set alone (no content filter applied) — the direct
+ * parity target for the host `Template.queryTree`. `query` is a (partial)
+ * record of the path-template input fields. Returns candidate record paths
+ * (relative to `base`, no extension) in sorted order.
+ */
+export declare function recordQueryCandidates(gitDir: string, treeRef: string, base: string, template: string, query: JsValue, extension?: string | undefined | null): Array<string>
+/**
+ * The record fields that contribute to rendering `template` — the query
+ * auto-derivation set (`Template.getFieldNames` parity). Insertion-ordered,
+ * de-duplicated; expression components contribute a best-effort identifier
+ * scan minus JS keywords/globals.
+ */
+export declare function templateFieldNames(template: string): Array<string>
+/**
+ * Build a **unique** index over the records under `base` and look up each key.
+ * `results[i]` is the record for `keys[i]`, or `null` when no record carries
+ * it. A duplicate key throws `IndexError(index_unique_conflict)` naming both
+ * paths.
+ */
+export declare function recordIndexUnique(gitDir: string, treeRef: string, base: string, keySnippet: string, keys: Array<string>, extension?: string | undefined | null): Array<JsValue | undefined | null>
+/**
+ * Build a **non-unique** index over the records under `base` and look up each
+ * key. `results[i]` is every record carrying `keys[i]` (an empty array when
+ * none).
+ */
+export declare function recordIndexMulti(gitDir: string, treeRef: string, base: string, keySnippet: string, keys: Array<string>, extension?: string | undefined | null): Array<Array<JsValue>>
+/**
+ * Generate an RFC 6902 JSON Patch transforming `src` into `dst` — the core's
+ * `createPatch`, matching the `rfc6902` package op-for-op. `null`/`undefined`
+ * on either side is the JSON null `Sheet.diffFrom` passes for an added
+ * (`src=null`) or deleted (`dst=null`) record.
+ */
+export declare function createPatch(src?: JsValue | undefined | null, dst?: JsValue | undefined | null): object
+/**
+ * Apply an RFC 7396 JSON Merge Patch to `target` (`null` ⇒ absent), returning
+ * the merged record — the core's `mergePatch` behind `Sheet.patch`. A `null`
+ * in the patch deletes that key; an object merges recursively; anything else
+ * replaces wholesale. Returns `null` only when the patch deletes the record
+ * outright.
+ */
+export declare function applyMergePatch(target: JsValue | undefined | null, patch: JsMergePatch): JsValue | null
+/**
+ * Diff records between two trees (`srcRef` → `dstRef`) under `base`, returning
+ * one entry per change with status, src/dst blob hashes, the parsed src/dst
+ * records, and the RFC 6902 patch — the full `Sheet.diffFrom({records,
+ * patches})` payload, computed in the core. `srcRef` may be the empty-tree hash
+ * for a from-scratch diff.
+ */
+export declare function diffRecords(gitDir: string, srcRef: string, dstRef: string, base: string, extension?: string | undefined | null): object
+/**
+ * Throw the core error for a given stable `code`, surfaced as a **structured,
+ * matchable** JS error (own `code`, `status`, `gitsheetsClass`, and any
+ * `issues`/`conflictingPaths`). Boundary-test entry point: it exercises the
+ * error-variant → typed-class mapping without standing up real engine paths.
+ */
+export declare function simulateCoreError(code: string): void
+/** Commit identity for the JS surface. */
+export interface JsAuthor {
+  name: string
+  email: string
+}
+/** One ordered commit trailer (`Key: value`). */
+export interface JsTrailer {
+  key: string
+  value: string
+}
+/**
+ * Options for opening a [`CoreTransaction`]. `timeSeconds` / `offsetMinutes`
+ * carry the host clock + local-timezone offset (a host concern), exactly as the
+ * JS `commitTreeWithRepo` computes them today.
+ */
+export interface JsTransactionOptions {
+  parent?: string
+  branch?: string
+  author?: JsAuthor
+  committer?: JsAuthor
+  message: string
+  trailers?: Array<JsTrailer>
+  timeSeconds: number
+  offsetMinutes: number
+}
+/**
+ * The outcome of [`CoreTransaction::finalize`]. A no-op (no mutation, or the
+ * resulting tree equals the parent's) returns `commitHash = null`.
+ */
+export interface JsTransactionResult {
+  commitHash?: string
+  treeHash?: string
+  refName?: string
+  parentCommitHash?: string
+}
+/** The outcome of [`CoreTransaction::stage_upsert`]. */
+export interface JsStageOutcome {
+  blobHash: string
+  path: string
+}
+/**
+ * One attachment entry from `CoreTransaction.getAttachments`: its filename and
+ * blob hash (name → hash).
+ */
+export interface JsAttachmentEntry {
+  name: string
+  hash: string
+}
+/**
+ * Discover every sheet declared in `<openRoot>/.gitsheets/*.toml` in the tree
+ * `treeRef`. Sorted bare names. The `Store` discovery half (`openStore`).
+ */
+export declare function coreDiscoverSheets(gitDir: string, treeRef: string, openRoot: string): Array<string>
+/**
+ * The `openStore` `config_missing` check: every validator must name a declared
+ * sheet. Throws `ConfigError(config_missing)` otherwise.
+ */
+export declare function coreCheckValidators(declared: Array<string>, validatorNames: Array<string>): void
+/**
+ * Serialize a record to its on-disk markdown bytes (`+++` frontmatter + body),
+ * enforcing the title-from-H1 invariant when `titleField` is set. The body is
+ * normalized natively by the embedded `dprint-plugin-markdown` formatter unless
+ * `normalize` is `false` (then it is framed verbatim). A non-string body or a
+ * title that disagrees with the body's (normalized) H1 throws a typed
+ * `ValidationError`.
+ */
+export declare function markdownSerialize(record: JsValue, bodyField: string, titleField?: string | undefined | null, normalize?: boolean | undefined | null): string
+/**
+ * Normalize a markdown body with the native `dprint-plugin-markdown` formatter
+ * (the pinned aggressive `textWrap: never` config). Deterministic + idempotent.
+ * Exposed so the boundary suite can assert the normalizer directly.
+ */
+export declare function markdownNormalizeBody(body: string): string
+/**
+ * Parse on-disk markdown bytes into a full record (frontmatter fields + the
+ * body under `bodyField`). Mirrors `markdownFormat.parse`.
+ */
+export declare function markdownParse(text: string, bodyField: string, titleField?: string | undefined | null): JsValue
+/**
+ * Parse only the frontmatter — the lazy-body path. The body field is absent in
+ * the returned record. Mirrors `markdownFormat.parseHeaderOnly`.
+ */
+export declare function markdownParseHeaderOnly(text: string, bodyField: string): JsValue
+/**
+ * Extract the first ATX-style H1 from a markdown body, or `null` if absent.
+ * Mirrors `extractFirstH1`.
+ */
+export declare function markdownExtractH1(body: string): string | null
+/**
+ * Rewrite (or prepend) the first ATX H1 of a markdown body to `title`. Mirrors
+ * `rewriteLeadingH1` — the `Sheet.patch` title-reconciliation helper.
+ */
+export declare function markdownRewriteH1(body: string, title: string): string
+/**
+ * A compiled sheet definition: the embedded engine plus the definition's
+ * path template (and optional raw-JS sort comparator), **compiled once** at
+ * construction and reused across every method call. Holds a `!Send` boa
+ * context, so it is constructed and used on its owning JS thread — the
+ * thread-confinement the spec requires. Exists to demonstrate the
+ * compile-once-per-open / reuse-across-operations contract from JS.
+ */
+export declare class CompiledDefinition {
+  /**
+   * Compile a definition once: parse the path template (compiling its
+   * expression snippets into the engine) and, if given, compile a raw-JS sort
+   * comparator. All snippet compilation happens here — never per operation.
+   */
+  constructor(pathTemplate: string, sortRule?: string | undefined | null)
+  /** Render one record's path using the already-compiled template. */
+  renderPath(record: JsValue): string
+  /**
+   * Run the compiled sort comparator on two values, returning its numeric
+   * result. Errors if the definition was built without a sort rule.
+   */
+  compare(a: JsValue, b: JsValue): number
+  /**
+   * How many snippets were compiled into this definition's engine. Constant
+   * across operations — proof that compilation happened once at construction,
+   * not per `render_path` / `compare` call.
+   */
+  snippetCount(): number
+}
+/**
+ * A live transaction the JS boundary suite drives. Holds a `!Send`
+ * `Transaction` (repo + private tree) and the opened `Sheet`s, so it is
+ * constructed and used on its owning JS thread — the thread-confinement the
+ * spec requires.
+ */
+export declare class CoreTransaction {
+  /**
+   * Open a transaction against `gitDir`. Resolves the parent/branch, builds
+   * the private tree, and acquires the single-writer slot. A concurrent open
+   * on the same repo throws `TransactionError(transaction_in_progress)`.
+   */
+  static begin(gitDir: string, opts: JsTransactionOptions): CoreTransaction
+  /**
+   * Open a sheet against this transaction's tree (config read + template /
+   * schema / sort comparators compiled once).
+   */
+  openSheet(name: string, configPath: string, openRoot: string, prefix: string): void
+  /**
+   * Phase 1 of the two-phase protocol *(non-mutating)*. Returns the candidate
+   * (`path`, `nextText`, and the normalized `record`) for the host validator;
+   * the candidate is stashed for a subsequent `stageUpsert`. A JSON-Schema
+   * rejection throws `ValidationError` here, before any bytes are written.
+   */
+  prepareUpsert(name: string, record: JsValue, previousPath?: string | undefined | null, allowMissingBody?: boolean | undefined | null): object
+  /**
+   * Phase 3 *(mutating)*: write the stashed candidate from the last
+   * `prepareUpsert` for `name`. Marks the transaction mutated.
+   */
+  stageUpsert(name: string): JsStageOutcome
+  /**
+   * Pre-flight idempotency check (`Sheet.willChange`) — same phase-1 pipeline,
+   * then a byte comparison to the existing blob. Non-mutating.
+   */
+  willChange(name: string, record: JsValue, previousPath?: string | undefined | null, allowMissingBody?: boolean | undefined | null): object
+  /**
+   * Delete a record by its sheet-relative path *(mutating)*. Throws
+   * `NotFoundError(record_not_found)` when absent.
+   */
+  delete(name: string, recordPath: string): void
+  /** `Sheet.clear` *(mutating)* — empties the sheet's data subtree. */
+  clear(name: string): void
+  /**
+   * Stage attachments for a record *(mutating)*: place each `name → blobHash`
+   * at `<recordPath>/<name>` in this transaction's live tree, so the record
+   * and its attachments commit atomically. Write the blob first with the
+   * top-level `writeBlob`. Marks the transaction mutated.
+   */
+  setAttachments(name: string, recordPath: string, attachments: Record<string, string>): void
+  /** Stage a single attachment *(mutating)* — sugar over [`Self::set_attachments`]. */
+  setAttachment(name: string, recordPath: string, attachmentName: string, blobHash: string): void
+  /**
+   * Stage a raw text file at `path` in this transaction's private tree
+   * *(mutating)* — the generic file write the CLI uses to commit sheet-config
+   * edits (`init` / `infer` / `migrate-config`) atomically alongside nothing
+   * else. `path` is repo-root-relative. Returns the written blob hash.
+   */
+  writeFile(path: string, content: string): string
+  /**
+   * The blob-hash map of a record's attachments (`name → hash`, sorted by
+   * name), or `null` when the record has no attachment directory. Read-only.
+   */
+  getAttachments(name: string, recordPath: string): Array<JsAttachmentEntry> | null
+  /** The blob hash of a single named attachment, or `null` if absent. Read-only. */
+  getAttachment(name: string, recordPath: string, attachmentName: string): string | null
+  /**
+   * Remove a single named attachment *(mutating)*. Throws
+   * `NotFoundError(record_not_found)` when it doesn't exist. Marks mutated.
+   */
+  deleteAttachment(name: string, recordPath: string, attachmentName: string): void
+  /**
+   * Remove all attachments for a record *(mutating)*. A no-op when the record
+   * has no attachment directory — in that case the transaction is NOT marked
+   * mutated (so an otherwise-empty transaction still finalizes to no commit).
+   * Returns whether anything was removed.
+   */
+  deleteAttachments(name: string, recordPath: string): boolean
+  /**
+   * List every record under the sheet's base, decoded through the format
+   * codec, in sorted path order. `withBody` is the lazy-body switch for
+   * markdown sheets (`false` omits the body field); a no-op for TOML sheets.
+   * Read-only — does not mark the transaction mutated.
+   */
+  list(name: string, withBody: boolean): Array<JsRecordEntry>
+  /** The parent commit hash captured at open (null on a fresh repo). */
+  parentCommitHash(): string | null
+  /**
+   * Finalize: commit-on-success-only with no-op detection + `parent_moved`
+   * re-check + CAS ref movement. Consumes the transaction.
+   */
+  finalize(): JsTransactionResult
+  /** Discard without committing (handler threw). Releases the writer slot. */
+  discard(): void
+}

package/index.js

@@ -0,0 +1,347 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'gitsheets-core.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./gitsheets-core.android-arm64.node')
+          } else {
+            nativeBinding = require('@gitsheets/core-napi-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'gitsheets-core.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./gitsheets-core.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@gitsheets/core-napi-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'gitsheets-core.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./gitsheets-core.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@gitsheets/core-napi-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'gitsheets-core.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./gitsheets-core.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@gitsheets/core-napi-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'gitsheets-core.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./gitsheets-core.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@gitsheets/core-napi-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'gitsheets-core.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./gitsheets-core.darwin-universal.node')
+      } else {
+        nativeBinding = require('@gitsheets/core-napi-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'gitsheets-core.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./gitsheets-core.darwin-x64.node')
+          } else {
+            nativeBinding = require('@gitsheets/core-napi-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'gitsheets-core.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./gitsheets-core.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@gitsheets/core-napi-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'gitsheets-core.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./gitsheets-core.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@gitsheets/core-napi-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'gitsheets-core.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./gitsheets-core.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@gitsheets/core-napi-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'gitsheets-core.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./gitsheets-core.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@gitsheets/core-napi-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'gitsheets-core.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./gitsheets-core.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@gitsheets/core-napi-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'gitsheets-core.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./gitsheets-core.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@gitsheets/core-napi-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'gitsheets-core.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./gitsheets-core.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@gitsheets/core-napi-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'gitsheets-core.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./gitsheets-core.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@gitsheets/core-napi-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'gitsheets-core.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./gitsheets-core.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@gitsheets/core-napi-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'gitsheets-core.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./gitsheets-core.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@gitsheets/core-napi-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'gitsheets-core.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./gitsheets-core.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@gitsheets/core-napi-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { roundtrip, parseRecords, serializeRecords, renderPathsBatch, validateBatch, runComparator, collatorSort, CompiledDefinition, recordRead, recordWrite, recordDelete, recordList, writeBlob, substrateStats, substrateReset, recordQuery, recordQueryCandidates, templateFieldNames, recordIndexUnique, recordIndexMulti, createPatch, applyMergePatch, diffRecords, simulateCoreError, CoreTransaction, coreDiscoverSheets, coreCheckValidators, markdownSerialize, markdownNormalizeBody, markdownParse, markdownParseHeaderOnly, markdownExtractH1, markdownRewriteH1 } = nativeBinding
+
+module.exports.roundtrip = roundtrip
+module.exports.parseRecords = parseRecords
+module.exports.serializeRecords = serializeRecords
+module.exports.renderPathsBatch = renderPathsBatch
+module.exports.validateBatch = validateBatch
+module.exports.runComparator = runComparator
+module.exports.collatorSort = collatorSort
+module.exports.CompiledDefinition = CompiledDefinition
+module.exports.recordRead = recordRead
+module.exports.recordWrite = recordWrite
+module.exports.recordDelete = recordDelete
+module.exports.recordList = recordList
+module.exports.writeBlob = writeBlob
+module.exports.substrateStats = substrateStats
+module.exports.substrateReset = substrateReset
+module.exports.recordQuery = recordQuery
+module.exports.recordQueryCandidates = recordQueryCandidates
+module.exports.templateFieldNames = templateFieldNames
+module.exports.recordIndexUnique = recordIndexUnique
+module.exports.recordIndexMulti = recordIndexMulti
+module.exports.createPatch = createPatch
+module.exports.applyMergePatch = applyMergePatch
+module.exports.diffRecords = diffRecords
+module.exports.simulateCoreError = simulateCoreError
+module.exports.CoreTransaction = CoreTransaction
+module.exports.coreDiscoverSheets = coreDiscoverSheets
+module.exports.coreCheckValidators = coreCheckValidators
+module.exports.markdownSerialize = markdownSerialize
+module.exports.markdownNormalizeBody = markdownNormalizeBody
+module.exports.markdownParse = markdownParse
+module.exports.markdownParseHeaderOnly = markdownParseHeaderOnly
+module.exports.markdownExtractH1 = markdownExtractH1
+module.exports.markdownRewriteH1 = markdownRewriteH1

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@gitsheets/core-napi",
+  "version": "0.1.0",
+  "description": "Node.js native binding for gitsheets-core — the FFI marshalling boundary.",
+  "main": "binding.cjs",
+  "types": "index.d.ts",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JarvusInnovations/gitsheets.git",
+    "directory": "rust/gitsheets-napi"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "napi": {
+    "name": "gitsheets-core",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-unknown-linux-musl",
+        "aarch64-apple-darwin",
+        "x86_64-apple-darwin",
+        "x86_64-pc-windows-msvc"
+      ]
+    }
+  },
+  "files": [
+    "binding.cjs",
+    "index.js",
+    "index.d.ts"
+  ],
+  "optionalDependencies": {
+    "@gitsheets/core-napi-linux-x64-gnu": "0.1.0",
+    "@gitsheets/core-napi-linux-arm64-gnu": "0.1.0",
+    "@gitsheets/core-napi-linux-x64-musl": "0.1.0",
+    "@gitsheets/core-napi-darwin-arm64": "0.1.0",
+    "@gitsheets/core-napi-darwin-x64": "0.1.0",
+    "@gitsheets/core-napi-win32-x64-msvc": "0.1.0"
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "prepublishOnly": "napi prepublish -t npm --skip-gh-release",
+    "test": "node --test test/roundtrip.mjs test/errors.mjs test/canonical.mjs test/path-template.mjs test/validation-parity.mjs test/engine-parity.mjs test/collator-parity.mjs test/record-crud.mjs test/record-query.mjs test/record-index.mjs test/sheet-store.mjs test/sheet-markdown.mjs test/sheet-attachments.mjs",
+    "bench": "node bench/query-bench.mjs",
+    "version": "napi version"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "rfc6902": "^5.2.0",
+    "smol-toml": "^1.7.0"
+  }
+}