@gitsheets/core-napi 0.3.0 → 0.5.0

package/binding.cjs

@@ -70,6 +70,15 @@ class NotFoundError extends GitsheetsError {
   }
 }
 
+class ContractError extends GitsheetsError {
+  constructor(message, opts = {}) {
+    super(message, opts);
+    this.name = 'ContractError';
+    if (opts.contract !== undefined) this.contract = opts.contract;
+    if (opts.issues !== undefined) this.issues = opts.issues;
+  }
+}
+
 const CLASS_BY_NAME = {
   ConfigError,
   ValidationError,
@@ -78,6 +87,7 @@ const CLASS_BY_NAME = {
   RefError,
   PathTemplateError,
   NotFoundError,
+  ContractError,
 };
 
 // Map a structured error raised by the addon onto its typed class. The mapping
@@ -87,6 +97,7 @@ function mapCoreError(raw) {
   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;
+  if (raw.contract !== undefined) opts.contract = raw.contract;
   return new Cls(raw.message, opts);
 }
 
@@ -113,6 +124,10 @@ module.exports = {
   // PathTemplateError; schema compilation raises a typed ConfigError.
   renderPathsBatch: wrap(addon.renderPathsBatch),
   validateBatch: wrap(addon.validateBatch),
+  // The contract identity primitive (specs/behaviors/contracts.md "Canonical
+  // form" / "Contract identity"): canonicalize → SHA-256 hex. A string input
+  // with no/invalid `format` raises a typed ConfigError.
+  canonicalContractHash: wrap(addon.canonicalContractHash),
   runComparator: wrap(addon.runComparator),
   // Native locale array sort (declarative `sort = true`) — the ICU collator
   // matching V8 `localeCompare`. Pure (no structured errors), so unwrapped.
@@ -134,6 +149,9 @@ module.exports = {
   // the filter (equality / nested / `$pred` engine snippets) runs in the core.
   recordQuery: wrap(addon.recordQuery),
   recordQueryCandidates: wrap(addon.recordQueryCandidates),
+  treeReadBlob: wrap(addon.treeReadBlob),
+  treeEntryHash: wrap(addon.treeEntryHash),
+  blobRead: wrap(addon.blobRead),
   templateFieldNames: wrap(addon.templateFieldNames),
   // Secondary indexing (lazy, in-memory). A unique conflict surfaces as a typed
   // IndexError(index_unique_conflict).
@@ -152,6 +170,11 @@ module.exports = {
   CoreTransaction: addon.CoreTransaction,
   coreDiscoverSheets: wrap(addon.coreDiscoverSheets),
   coreCheckValidators: wrap(addon.coreCheckValidators),
+  // Consumer-side contract verification — the two-rung ladder behind
+  // `openSheet(name, { contract })` (specs/behaviors/contracts.md "Consumer
+  // verification"). A verification failure raises a typed
+  // ContractError(contract_unsatisfied) carrying the conformance report.
+  verifySheetContract: wrap(addon.verifySheetContract),
   // 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
@@ -175,4 +198,5 @@ module.exports = {
   RefError,
   PathTemplateError,
   NotFoundError,
+  ContractError,
 };

package/index.d.ts

@@ -33,6 +33,17 @@ export interface JsValidationIssue {
   source: string
   schemaPath?: string
   code?: string
+  /**
+   * The contract name, when the failing branch is a declared contract
+   * composed via `allOf` (specs/behaviors/contracts.md).
+   */
+  contract?: string
+  /**
+   * The record's sheet-relative path, in a multi-record conformance
+   * report (`ContractError.issues` from consumer-side contract
+   * verification — specs/behaviors/contracts.md "Consumer verification").
+   */
+  record?: string
 }
 /**
  * Render a path template against a **batch** of records, returning one path per
@@ -53,6 +64,87 @@ export declare function renderPathsBatch(template: string, records: Array<JsValu
  * compile surfaces as a structured, typed `ConfigError` (`config_invalid`).
  */
 export declare function validateBatch(schema: JsValue, records: Array<JsValue>): Array<Array<JsValidationIssue>>
+/**
+ * The contract identity primitive (specs/behaviors/contracts.md "Canonical
+ * form" / "Contract identity"): canonicalize `input` → SHA-256 hex of the
+ * canonical TOML bytes. `input` is either already-parsed data (a JS
+ * object/array/etc.) or a string, in which case `format` says how to parse
+ * it (`"json"` or `"toml"` — required for a string input; a
+ * `ConfigError(config_invalid)` names the omission). The minimal JS surface
+ * over [`gitsheets_core::contract::canonical_contract_hash`].
+ */
+export declare function canonicalContractHash(input: string | JsValue, format?: string | undefined | null): string
+/**
+ * Validate a contract name (`specs/behaviors/contracts.md` "Contract names
+ * and the derived path") — the same check a sheet's `implements` entries run
+ * through at sheet-open. `contracts adopt` runs it on the name derived from a
+ * candidate document's `$id` before vendoring. Throws
+ * `ConfigError(config_invalid)` naming the violated rule.
+ */
+export declare function validateContractName(name: string): void
+/**
+ * The derived vendored path for a contract name — mechanical, no manifest:
+ * `.gitsheets/contracts/<name>.toml`. The minimal JS surface over
+ * [`gitsheets_core::contract_path`].
+ */
+export declare function contractPath(name: string): string
+/**
+ * Enforce the contract document requirements
+ * (`specs/behaviors/contracts.md` "Contract document requirements") against a
+ * NOT-yet-vendored candidate document — `contracts adopt`'s pre-vendor gate.
+ *
+ * `input` is either already-parsed data (a JS object) or a string, in which
+ * case `format` says how to parse it — mirrors `canonicalContractHash`'s
+ * shape exactly, for the same reason: a **JSON-text** input is parsed with
+ * `serde_json::from_str` directly (preserving a literal JSON `null`),
+ * deliberately NOT via the `JsValue`/core-`Value` marshalling boundary,
+ * which silently *drops* null-valued keys per the type-fidelity rules at the
+ * top of this file. Requirement 4 (no null-bearing keywords — `default:
+ * null`, `const: null`, a null in `enum`) can only ever be violated by a
+ * JSON-sourced document (TOML has no null literal at all), so routing
+ * through the null-dropping path would make that check silently unreachable
+ * for exactly the input shape it exists to catch. A TOML-text or
+ * already-parsed-data input has no such hazard (nothing they carry can be a
+ * TOML/core `Value` null in the first place), so those still go through the
+ * shared `value_to_json` conversion.
+ * Throws `ContractError(contract_invalid)` naming the violated rule.
+ */
+export declare function checkContractDocument(name: string, input: string | JsValue, format?: string | undefined | null): void
+/**
+ * Load a vendored contract document `name` from the committed tree at
+ * `treeRef` (scoped under `openRoot`), returning it as JSON text on success.
+ * The minimal JS surface over [`gitsheets_core::contract::load_contract`] —
+ * runs the exact compile-time check (byte-canonical, document requirements,
+ * `$id`↔path) `Sheet::open` composition relies on, so `contracts verify` /
+ * `contracts adopt --sheet` get the identical guarantee. Throws
+ * `ContractError('contract_missing' | 'contract_invalid')` on failure.
+ */
+export declare function contractLoad(gitDir: string, treeRef: string, openRoot: string, name: string): string
+/**
+ * The result of a successful [`verify_sheet_contract`] call — the wire shape
+ * for `sheet.contractVerification` minus `tree` (the JS binding attaches that
+ * from the read snapshot it already resolved to open the sheet).
+ */
+export interface JsConformanceReport {
+  name: string
+  /** `"declared"` or `"structural"` — which rung passed. */
+  rung: string
+  conforming: boolean
+  issues: Array<JsValidationIssue>
+}
+/**
+ * Consumer-side contract verification — the two-rung ladder behind
+ * `openSheet(name, { contract })` (specs/behaviors/contracts.md "Consumer
+ * verification", specs/api/repository.md `opts.contract`). Opens `sheetName`
+ * read-only against `treeRef` (config read + effective-schema compile, same
+ * as any other read), then verifies it against `schema` — parsed data, or
+ * text with `format` naming which text form (mirrors
+ * `canonicalContractHash`'s input handling: no format auto-detection). A
+ * verification failure (both rungs missed, or the attempted rung missed in
+ * `declared`/`structural` mode) surfaces as `ContractError(contract_unsatisfied)`
+ * carrying the conformance report in `issues`.
+ */
+export declare function verifySheetContract(gitDir: string, treeRef: string, sheetName: string, configPath: string, openRoot: string, prefix: string, schema: string | JsValue, format?: string | undefined | null, mode?: string | undefined | null): JsConformanceReport
 /**
  * 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
@@ -143,15 +235,47 @@ 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>
+ * filter (equality / nested / `$pred` snippets / `{ $gt, $gte, $lt, $lte }` ranges)
+ * is applied to each candidate; a range on a date-bucket path field prunes
+ * the walk to the bounded span of partitions. Batch-first: the whole query
+ * crosses the FFI once.
+ *
+ * Format-aware: pass `bodyField` (and optionally `titleField`) for a
+ * markdown/mdx sheet (the kind follows `extension`: `.mdx` → mdx, else
+ * markdown) and the core decodes each candidate through the frontmatter
+ * codec — `withBody: false` is the lazy-body switch (default `true`). Without
+ * `bodyField` records are canonical TOML. The binding never fetches record
+ * bytes itself (spec: `rust-core.md` "Query traversal + filtering").
+ */
+export declare function recordQuery(gitDir: string, treeRef: string, base: string, template: string, filter: object, extension?: string | undefined | null, bodyField?: string | undefined | null, titleField?: string | undefined | null, withBody?: boolean | undefined | null): Array<JsRecordEntry>
+/**
+ * A blob read by `treeRef:path` — the bytes plus the blob's object id, or
+ * `null` when nothing (or a subtree) lives at `path`. Backs sheet-config
+ * loading and lazy-body hydration without a `git cat-file` subprocess
+ * (spec: `rust-core.md` "Blob reads").
+ */
+export declare function treeReadBlob(gitDir: string, treeRef: string, path: string): JsBlobEntry | null
+/**
+ * The object id of the blob at `treeRef:path`, or `null` when absent or not
+ * a blob. The hash-only lookup (attachment handles, cache keys).
+ */
+export declare function treeEntryHash(gitDir: string, treeRef: string, path: string): string | null
+/**
+ * A blob's bytes by object id, or `null` when no object has that id. Backs
+ * attachment content reads and diff-side record reads.
+ */
+export declare function blobRead(gitDir: string, hash: string): Buffer | null
+/** A blob read by `treeRef:path`: its object id and bytes. */
+export interface JsBlobEntry {
+  hash: string
+  content: Buffer
+}
 /**
  * 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.
+ * record of the path-template input fields; a date-bucket field may carry a
+ * `{ $gte, $lt, … }` range object, which bounds the walk. 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>
 /**
@@ -384,6 +508,14 @@ export declare class CoreTransaction {
    * else. `path` is repo-root-relative. Returns the written blob hash.
    */
   writeFile(path: string, content: string): string
+  /**
+   * Delete a raw file at `path` (repo-root-relative) in this transaction's
+   * private tree *(mutating)* — `write_file`'s inverse. Returns whether a
+   * blob existed at `path` before the delete. Used by `contracts prune` to
+   * remove undeclared vendored contract documents; deep (slash-separated)
+   * paths are supported directly via `MutableTree::delete_child_deep`.
+   */
+  deleteFile(path: string): boolean
   /**
    * 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.
@@ -410,6 +542,22 @@ export declare class CoreTransaction {
    * Read-only — does not mark the transaction mutated.
    */
   list(name: string, withBody: boolean): Array<JsRecordEntry>
+  /**
+   * Query the sheet's records in the transaction's private tree — pruned by
+   * the path template exactly like a committed-ref query, decoded through
+   * the format codec, `withBody` the lazy-body switch (spec:
+   * `api/transaction.md` "Read isolation"). The filter takes the same forms
+   * as `recordQuery` (equality / nested / `$pred` / ranges). Read-only —
+   * does not mark the transaction mutated.
+   */
+  query(name: string, filter: object, withBody: boolean): Array<JsRecordEntry>
+  /**
+   * Read the one record at `recordPath` (relative to the sheet's base, no
+   * extension) in the transaction's private tree, decoded through the format
+   * codec — the tx-bound `Sheet.get`. `null` when absent; `withBody` is the
+   * lazy-body switch. Read-only.
+   */
+  readRecord(name: string, recordPath: string, withBody: boolean): JsValue | null
   /** The parent commit hash captured at open (null on a fresh repo). */
   parentCommitHash(): string | null
   /**

package/index.js

@@ -310,13 +310,19 @@ if (!nativeBinding) {
   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
+const { roundtrip, parseRecords, serializeRecords, renderPathsBatch, validateBatch, canonicalContractHash, validateContractName, contractPath, checkContractDocument, contractLoad, verifySheetContract, runComparator, collatorSort, CompiledDefinition, recordRead, recordWrite, recordDelete, recordList, writeBlob, substrateStats, substrateReset, recordQuery, treeReadBlob, treeEntryHash, blobRead, 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.canonicalContractHash = canonicalContractHash
+module.exports.validateContractName = validateContractName
+module.exports.contractPath = contractPath
+module.exports.checkContractDocument = checkContractDocument
+module.exports.contractLoad = contractLoad
+module.exports.verifySheetContract = verifySheetContract
 module.exports.runComparator = runComparator
 module.exports.collatorSort = collatorSort
 module.exports.CompiledDefinition = CompiledDefinition
@@ -328,6 +334,9 @@ module.exports.writeBlob = writeBlob
 module.exports.substrateStats = substrateStats
 module.exports.substrateReset = substrateReset
 module.exports.recordQuery = recordQuery
+module.exports.treeReadBlob = treeReadBlob
+module.exports.treeEntryHash = treeEntryHash
+module.exports.blobRead = blobRead
 module.exports.recordQueryCandidates = recordQueryCandidates
 module.exports.templateFieldNames = templateFieldNames
 module.exports.recordIndexUnique = recordIndexUnique

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitsheets/core-napi",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Node.js native binding for gitsheets-core — the FFI marshalling boundary.",
   "main": "binding.cjs",
   "types": "index.d.ts",
@@ -33,19 +33,19 @@
     "index.d.ts"
   ],
   "optionalDependencies": {
-    "@gitsheets/core-napi-linux-x64-gnu": "0.3.0",
-    "@gitsheets/core-napi-linux-arm64-gnu": "0.3.0",
-    "@gitsheets/core-napi-linux-x64-musl": "0.3.0",
-    "@gitsheets/core-napi-darwin-arm64": "0.3.0",
-    "@gitsheets/core-napi-darwin-x64": "0.3.0",
-    "@gitsheets/core-napi-win32-x64-msvc": "0.3.0"
+    "@gitsheets/core-napi-linux-x64-gnu": "0.5.0",
+    "@gitsheets/core-napi-linux-arm64-gnu": "0.5.0",
+    "@gitsheets/core-napi-linux-x64-musl": "0.5.0",
+    "@gitsheets/core-napi-darwin-arm64": "0.5.0",
+    "@gitsheets/core-napi-darwin-x64": "0.5.0",
+    "@gitsheets/core-napi-win32-x64-msvc": "0.5.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",
+    "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 test/contracts.mjs",
     "bench": "node bench/query-bench.mjs",
     "version": "napi version"
   },
@@ -54,6 +54,6 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "rfc6902": "^5.2.0",
-    "smol-toml": "^1.7.0"
+    "smol-toml": "^1.8.0"
   }
 }