@gitsheets/core-napi 0.2.0 → 0.4.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.
@@ -152,6 +167,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 +195,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
@@ -384,6 +476,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.

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, 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitsheets/core-napi",
-  "version": "0.2.0",
+  "version": "0.4.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.2.0",
-    "@gitsheets/core-napi-linux-arm64-gnu": "0.2.0",
-    "@gitsheets/core-napi-linux-x64-musl": "0.2.0",
-    "@gitsheets/core-napi-darwin-arm64": "0.2.0",
-    "@gitsheets/core-napi-darwin-x64": "0.2.0",
-    "@gitsheets/core-napi-win32-x64-msvc": "0.2.0"
+    "@gitsheets/core-napi-linux-x64-gnu": "0.4.0",
+    "@gitsheets/core-napi-linux-arm64-gnu": "0.4.0",
+    "@gitsheets/core-napi-linux-x64-musl": "0.4.0",
+    "@gitsheets/core-napi-darwin-arm64": "0.4.0",
+    "@gitsheets/core-napi-darwin-x64": "0.4.0",
+    "@gitsheets/core-napi-win32-x64-msvc": "0.4.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"
   },