@vinary-tree/liblevenshtein 0.0.0 → 4.0.0-rc.4

package/README.md

@@ -1,5 +1,158 @@
-# Vinary Tree npm bootstrap
+# `@vinary-tree/liblevenshtein`
 
-This inert `0.0.0` artifact reserves an npm coordinate so its GitHub Actions
-OIDC trusted publisher can be configured before the first release candidate.
-Install the package's `next` or `latest` dist-tag instead.
+This package is the project-local JavaScript, TypeScript, and ClojureScript
+facade for liblevenshtein. It does not contain a second copy of the runtime.
+Every entry point re-exports the liblevenshtein namespace from the exact same
+version of `@vinary-tree/vinary-tree`, so objects created by
+`@vinary-tree/libdictenstein` can be passed directly to `transducer()`.
+
+```ts
+import { dynamicDawg } from "@vinary-tree/libdictenstein";
+import { transducer } from "@vinary-tree/liblevenshtein";
+
+using dictionary = dynamicDawg(["cat", "cot", "cut"]);
+using automaton = transducer(dictionary, "standard");
+using cursor = automaton.query("cat", 1);
+for (const match of cursor) console.log(match);
+```
+
+Node selects the native N-API runtime by default. Use
+`@vinary-tree/liblevenshtein/wasm` for the browser/static WebAssembly runtime or
+`@vinary-tree/liblevenshtein/wasi` for the Node/WASI runtime. The WASI facade is
+where preopened-directory persistent dictionaries are exposed as portable
+support lands; browser persistence remains unsupported.
+
+The ClojureScript facade mirrors the Clojure names: `transducer`, `query`,
+`reduce-batches`, `phonetic-pattern`, `phonetic-rules`, `rewrite`, and `close!`.
+
+<!-- BEGIN GENERATED BINDING OPERATIONS; DO NOT EDIT -->
+
+## Support and package contract
+
+| Property | Contract |
+|---|---|
+| Binding | JavaScript family |
+| Languages/runtime | JavaScript, TypeScript, and ClojureScript on Node.js, browsers, or WASI |
+| Support tier | Tier 1 |
+| Distribution | npm package `@vinary-tree/liblevenshtein` |
+| Native boundary | The facade delegates to the singleton `@vinary-tree/vinary-tree` runtime: native N-API by default, WebAssembly or WASI through explicit exports. |
+| Canonical facade source | [`bindings/javascript`](../../bindings/javascript) |
+
+The support tier controls release gating, not semantic quality: every tier has
+the same snapshot, ownership, status, and ABI compatibility laws. Consult the
+[binding architecture](../../docs/language-bindings.md) before implementing a custom provider
+and the [family hub](../../docs/bindings/README.md) when combining independently packaged projects.
+
+![The host-language facade crosses one project ABI and retains a versioned family resource rather than sharing Rust object layouts.](../../docs/diagrams/bindings/three-layer-architecture.svg)
+
+## Executable example and verification
+
+The repository's canonical executable example is
+[`bindings/javascript/test/facades.test.mjs`](../../bindings/javascript/test/facades.test.mjs). It exercises the same public package a user
+installs and is run by the binding CI with:
+
+```sh
+npm test --prefix bindings/javascript
+```
+
+Examples deliberately construct or receive resources through public project
+packages. They never import private Rust modules, depend on object layout, or
+reach behind the stable C/resource ABIs.
+
+## Public API and data model
+
+The idiomatic facade groups the stable surface into these concepts:
+
+| Concept | Semantics |
+|---|---|
+| Dictionary resource | A retained `vt.dictionary.v1` capability. Construction and mutation belong to a producer such as libdictenstein. |
+| Transducer | Immutable query configuration plus a retained dictionary provider; construction is constant-time with respect to dictionary size. |
+| Query cursor | A one-shot traversal over the immutable dictionary revision captured at query start. |
+| Match/batch | Owned matches are stable host values; a borrowed batch is valid only inside its documented callback or lease interval. |
+
+Strings are Unicode; `Uint8Array` and `BigUint64Array` select byte and packed-token queries. IDs are `bigint`, never lossy JavaScript numbers. Empty terms, embedded zero bytes, non-ASCII text, and the full
+unsigned 64-bit identifier range are represented explicitly; no facade may use
+a sentinel value that removes a valid input from the domain.
+
+For the exhaustive native function contract—including exact preconditions,
+returnable statuses, complexity, and thread-safety—use the
+[`llev_*` C ABI reference](../../docs/bindings/c-abi-reference.md). The facade
+source linked above is the authoritative idiomatic symbol inventory; its
+exhaustive coverage is governed by [`bindings/api-surface-map.json`](../../bindings/api-surface-map.json) and the [generated completeness matrix](../../bindings/conformance/completeness-matrix.tsv).
+
+## Ownership, snapshots, and resource handoff
+
+Use explicit resource management (`using`) where available or call `close()`/`close!` in `finally`. GC finalizers are fallback containment.
+
+A transducer retains the provider resource, and a query retains the revision
+visible at query start. Closing the original dictionary or publishing later
+mutations cannot invalidate that query. Acquisition either completes with one
+owned retain or fails with no ownership transfer. Teardown order is therefore
+free across dictionary, transducer, and completed query handles.
+
+Borrowed results are intentionally lexical. Copy data that must outlive the
+callback; retaining a raw address, slice, memory segment, or foreign pointer is
+an API violation even when the next operation happens to reuse the same arena.
+
+## Errors and failure containment
+
+Status codes become `VinaryTreeError` values carrying project, operation, status, and native diagnostic fields.
+
+Malformed utf-8, unsupported unit domains, incompatible resource versions, closed handles, invalid bounds, allocation failures, provider faults, and contained rust panics are distinct failures. Never parse diagnostic prose to
+branch on an error: inspect the typed status/exception first and treat the
+message as human context. Diagnostics must be copied before another native
+call on the same thread.
+
+## Concurrency and reentrancy
+
+Independent handles may be used concurrently. A cursor is single-consumer, callbacks are synchronous, and borrowed batches expire on callback return.
+
+Snapshot capture is a linearization point, not a dictionary-wide query lock.
+First-party immutable snapshots can be walked concurrently. A foreign provider
+that does not advertise parallel callbacks is serialized at its callback gate;
+the host language must not add a weaker promise.
+
+## Performance and marshalling
+
+- Reuse transducers for repeated queries against the same resource.
+- Prefer streaming cursors to whole-result materialization.
+- Prefer batch/reducer APIs when per-match boundary crossings dominate.
+- Keep Unicode, byte, and token domains explicit to avoid transcoding.
+- Measure native, WASM, and WASI paths independently; they have different
+  startup and marshalling costs but identical query semantics.
+
+No host wrapper should cache unbounded query results. Applications that add a
+memo use a revision key and a hard entry/weight bound; eviction may be
+approximate because all values remain derivable from the retained snapshot.
+
+## Security model
+
+Treat a foreign resource provider and all user-controlled queries as untrusted
+inputs. Validate lengths before allocation, preserve paging bounds, reject
+unknown enum values, contain callbacks/panics at the boundary, and never trust
+capability flags until interface negotiation succeeds. The normative duties
+are in the [binding trust model](../../docs/security/binding-trust-model.md).
+
+## Compatibility and troubleshooting
+
+The project ABI revision, family ABI version, interface identity/version,
+package version, and umbrella-runtime version are independent counters. Follow
+the [ABI evolution policy](https://github.com/vinary-tree/vinary-tree-interop/blob/master/docs/abi-evolution.md); never infer compatibility from a
+package version alone.
+
+When loading fails, check—in order—the documented runtime/toolchain version,
+CPU/OS artifact, native-access permission, loader search path, dependent
+interop package pin, and process-wide JavaScript runtime identity. When a query
+fails after construction, report the typed status and copied diagnostic before
+reducing the case to the smallest dictionary/query pair.
+
+## Maintainer checklist
+
+1. Update the machine-readable binding model before changing a public symbol.
+2. Regenerate headers/constants and the API coverage matrix.
+3. Extend the canonical executable example and negative-path tests.
+4. Run the language package, snapshot, leak, property, and cross-project suites.
+5. Verify package staging contains this guide and uses coherent sibling pins.
+6. Render diagrams headlessly and run the documentation/link/math gates.
+
+<!-- END GENERATED BINDING OPERATIONS -->

package/abi.d.ts

@@ -0,0 +1,33 @@
+/** Generated from bindings/api.json; do not edit numeric values manually. */
+export const ABI_VERSION: 1;
+export const API_REVISION: 2;
+export const DEFAULT_MATCH_BATCH: 256;
+export enum Status {
+  Ok = 0,
+  End = 1,
+  InvalidArgument = 2,
+  InvalidUtf8 = 3,
+  NullPointer = 4,
+  Panic = 5,
+  Unsupported = 6,
+  IoError = 7,
+  Closed = 8,
+  LimitExceeded = 9,
+  ProviderError = 10,
+  BatchInUse = 11,
+  DomainMismatch = 12,
+}
+export enum Algorithm {
+  Standard = 0,
+  Transposition = 1,
+  MergeAndSplit = 2,
+  DamerauLevenshtein = 3,
+}
+export enum Queryorder {
+  Traversal = 0,
+  DistanceThenTerm = 1,
+}
+export enum Phoneticrulesetkind {
+  EnglishOrthography = 0,
+  EnglishPhonetic = 1,
+}

package/cljs/vinary_tree/liblevenshtein.cljs

@@ -0,0 +1,38 @@
+(ns vinary-tree.liblevenshtein
+  "ClojureScript facade mirroring the Clojure resource/transducer API."
+  (:require ["@vinary-tree/liblevenshtein" :as native]))
+
+(defn transducer
+  ([dictionary] (native/transducer dictionary "standard"))
+  ([dictionary {:keys [algorithm] :or {algorithm :standard}}]
+   (native/transducer dictionary (name algorithm))))
+
+(defn close! [resource] (.close resource))
+
+(defn query
+  ([automaton term max-distance]
+   (.query automaton term max-distance "traversal"))
+  ([automaton term max-distance {:keys [order] :or {order :traversal}}]
+   (.query automaton term max-distance (name order))))
+
+(defn reduce-batches
+  "Allocation-minimizing batch reduction; borrowed views must not escape f."
+  [f initial cursor]
+  (try
+    (.reduceBatches cursor f initial)
+    (finally (close! cursor))))
+
+(defn cursor-seq [cursor]
+  (let [iterator (.call (aget cursor (.-iterator js/Symbol)) cursor)]
+    (letfn [(step []
+              (lazy-seq
+               (let [result (.next iterator)]
+                 (if (.-done result)
+                   (do (close! cursor) nil)
+                   (cons (.-value result) (step))))))]
+      (step))))
+
+(defn phonetic-pattern [source] (native/phoneticPattern source))
+(defn llre-pattern [source] (native/llrePattern source))
+(defn phonetic-rules [source] (native/phoneticRules (if (keyword? source) (name source) source)))
+(defn rewrite [rules input] (.apply rules input))

package/deps.cljs

@@ -0,0 +1 @@
+{:npm-deps {"@vinary-tree/liblevenshtein" "4.0.0-rc.4"}}

package/facades/clojurescript.cjs

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./native.cjs");

package/facades/clojurescript.d.ts

@@ -0,0 +1,2 @@
+export * from "../index.js";
+export { default } from "../index.js";

package/facades/clojurescript.mjs

@@ -0,0 +1,2 @@
+export * from "./native.mjs";
+export { default } from "./native.mjs";

package/facades/native.cjs

@@ -0,0 +1,13 @@
+"use strict";
+const namespace = require("@vinary-tree/vinary-tree").liblevenshtein;
+const { assertDictionaryResource, assertSameRuntime } = require("@vinary-tree/interop");
+if (!namespace || !namespace.runtimeIdentity) {
+  throw new Error("@vinary-tree/vinary-tree does not expose a runtime identity");
+}
+function transducer(dictionary, algorithm) {
+  assertDictionaryResource(dictionary);
+  assertSameRuntime(dictionary, namespace.runtimeIdentity);
+  return namespace.transducer(dictionary, algorithm);
+}
+const facade = Object.assign({}, namespace, { transducer });
+module.exports = Object.assign(facade, { default: facade });

package/facades/native.mjs

@@ -0,0 +1,24 @@
+import { liblevenshtein } from "@vinary-tree/vinary-tree";
+import { assertDictionaryResource, assertSameRuntime } from "@vinary-tree/interop";
+
+if (!liblevenshtein?.runtimeIdentity) {
+  throw new Error("@vinary-tree/vinary-tree does not expose a runtime identity");
+}
+
+export const runtimeIdentity = liblevenshtein.runtimeIdentity;
+export function transducer(dictionary, algorithm) {
+  assertDictionaryResource(dictionary);
+  assertSameRuntime(dictionary, runtimeIdentity);
+  return liblevenshtein.transducer(dictionary, algorithm);
+}
+export const phoneticPattern = liblevenshtein.phoneticPattern.bind(liblevenshtein);
+export const llrePattern = liblevenshtein.llrePattern.bind(liblevenshtein);
+export const phoneticRules = liblevenshtein.phoneticRules.bind(liblevenshtein);
+export default {
+  ...liblevenshtein,
+  runtimeIdentity,
+  transducer,
+  phoneticPattern,
+  llrePattern,
+  phoneticRules,
+};

package/facades/typescript.cjs

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./native.cjs");

package/facades/typescript.d.ts

@@ -0,0 +1,2 @@
+export * from "../index.js";
+export { default } from "../index.js";

package/facades/typescript.mjs

@@ -0,0 +1,2 @@
+export * from "./native.mjs";
+export { default } from "./native.mjs";

package/facades/wasi.cjs

@@ -0,0 +1,10 @@
+"use strict";
+const namespace = require("@vinary-tree/vinary-tree/wasi").liblevenshtein;
+const { assertDictionaryResource, assertSameRuntime } = require("@vinary-tree/interop");
+function transducer(dictionary, algorithm) {
+  assertDictionaryResource(dictionary);
+  assertSameRuntime(dictionary, namespace.runtimeIdentity);
+  return namespace.transducer(dictionary, algorithm);
+}
+const facade = Object.assign({}, namespace, { transducer });
+module.exports = Object.assign(facade, { default: facade });

package/facades/wasi.mjs

@@ -0,0 +1,17 @@
+import { liblevenshtein } from "@vinary-tree/vinary-tree/wasi";
+import { assertDictionaryResource, assertSameRuntime } from "@vinary-tree/interop";
+export const runtimeIdentity = liblevenshtein.runtimeIdentity;
+export function transducer(dictionary, algorithm) {
+  assertDictionaryResource(dictionary);
+  assertSameRuntime(dictionary, runtimeIdentity);
+  return liblevenshtein.transducer(dictionary, algorithm);
+}
+// The wasi build profile (--no-default-features --features wasi) has no
+// phonetic capability, so these namespace members may be absent; binding
+// them unconditionally crashed this module at import time (defect found by
+// the cross-language benchmark harness, 2026-08-13). Capability-gated
+// members stay undefined when the runtime does not provide them.
+export const phoneticPattern = liblevenshtein.phoneticPattern?.bind(liblevenshtein);
+export const llrePattern = liblevenshtein.llrePattern?.bind(liblevenshtein);
+export const phoneticRules = liblevenshtein.phoneticRules?.bind(liblevenshtein);
+export default { ...liblevenshtein, runtimeIdentity, transducer, phoneticPattern, llrePattern, phoneticRules };

package/facades/wasm.mjs

@@ -0,0 +1,12 @@
+import { liblevenshtein } from "@vinary-tree/vinary-tree/wasm";
+import { assertDictionaryResource, assertSameRuntime } from "@vinary-tree/interop";
+export const runtimeIdentity = liblevenshtein.runtimeIdentity;
+export function transducer(dictionary, algorithm) {
+  assertDictionaryResource(dictionary);
+  assertSameRuntime(dictionary, runtimeIdentity);
+  return liblevenshtein.transducer(dictionary, algorithm);
+}
+export const phoneticPattern = liblevenshtein.phoneticPattern.bind(liblevenshtein);
+export const llrePattern = liblevenshtein.llrePattern.bind(liblevenshtein);
+export const phoneticRules = liblevenshtein.phoneticRules.bind(liblevenshtein);
+export default { ...liblevenshtein, runtimeIdentity, transducer, phoneticPattern, llrePattern, phoneticRules };

package/index.d.ts

@@ -0,0 +1,82 @@
+import type { DictionaryResource } from "@vinary-tree/interop";
+
+export type Algorithm =
+  | "standard"
+  | "transposition"
+  | "merge-and-split"
+  | "damerau-levenshtein";
+export type QueryOrder = "traversal" | "distance-then-term";
+
+export type Term =
+  | { readonly domain: "unicode"; readonly value: string }
+  | { readonly domain: "byte"; readonly value: Uint8Array }
+  | { readonly domain: "u64"; readonly value: BigUint64Array };
+
+export interface Match {
+  readonly term: Term;
+  readonly distance: number;
+  readonly id: bigint | null;
+}
+
+export interface BorrowedMatch {
+  readonly distance: number;
+  readonly id: bigint | null;
+  readonly unitDomain: "byte" | "unicode" | "u64";
+  bytes(): Uint8Array;
+  utf8(): string;
+  u64(): BigUint64Array;
+}
+
+export interface BorrowedBatch extends Iterable<BorrowedMatch> {
+  readonly length: number;
+}
+
+export interface QueryCursor extends IterableIterator<Match> {
+  nextBatch(maximum: number): Match[];
+  reduceBatches<Accumulator>(
+    reducer: (accumulator: Accumulator, batch: readonly Match[]) => Accumulator,
+    initial: Accumulator,
+  ): Accumulator;
+  close(): void;
+}
+
+export interface AutomatonSize {
+  readonly states: number;
+  readonly transitions: number;
+}
+
+export interface PhoneticPattern {
+  readonly size: AutomatonSize;
+  matches(input: string): boolean;
+  close(): void;
+}
+
+export interface PhoneticRuleSet {
+  readonly size: number;
+  apply(input: string): string;
+  close(): void;
+}
+
+export interface Transducer {
+  query(query: string, maximumDistance: number, order?: QueryOrder): QueryCursor;
+  query(query: Uint8Array, maximumDistance: number): QueryCursor;
+  query(query: BigUint64Array, maximumDistance: number): QueryCursor;
+  query(pattern: PhoneticPattern, maximumDistance: number): QueryCursor;
+  close(): void;
+}
+
+export interface LiblevenshteinNamespace {
+  readonly runtimeIdentity: symbol | object;
+  transducer(dictionary: DictionaryResource, algorithm?: Algorithm): Transducer;
+  phoneticPattern(source: string): PhoneticPattern;
+  llrePattern(source: string): PhoneticPattern;
+  phoneticRules(source: string | "english-orthography" | "english-phonetic"): PhoneticRuleSet;
+}
+
+export const runtimeIdentity: symbol | object;
+export function transducer(dictionary: DictionaryResource, algorithm?: Algorithm): Transducer;
+export function phoneticPattern(source: string): PhoneticPattern;
+export function llrePattern(source: string): PhoneticPattern;
+export function phoneticRules(source: string | "english-orthography" | "english-phonetic"): PhoneticRuleSet;
+declare const liblevenshtein: LiblevenshteinNamespace;
+export default liblevenshtein;

package/package.json

@@ -1,20 +1,79 @@
 {
   "name": "@vinary-tree/liblevenshtein",
-  "version": "0.0.0",
-  "description": "Bootstrap reservation for the Vinary Tree liblevenshtein package",
+  "version": "4.0.0-rc.4",
+  "description": "Modular liblevenshtein facade over the shared vinary-tree runtime",
+  "author": {
+    "name": "Dylon Edwards",
+    "email": "dylon.devo@gmail.com"
+  },
   "type": "module",
+  "sideEffects": false,
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vinary-tree/liblevenshtein-rust.git"
+    "url": "git+https://github.com/vinary-tree/liblevenshtein-rust.git",
+    "directory": "bindings/javascript"
+  },
+  "engines": {
+    "node": ">=22.14"
+  },
+  "dependencies": {
+    "@vinary-tree/interop": "4.0.0-rc.4",
+    "@vinary-tree/vinary-tree": "4.0.0-rc.4"
+  },
+  "devDependencies": {
+    "@vinary-tree/libdictenstein": "file:../../../libdictenstein/bindings/javascript"
+  },
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./facades/native.mjs",
+      "require": "./facades/native.cjs"
+    },
+    "./typescript": {
+      "types": "./facades/typescript.d.ts",
+      "import": "./facades/typescript.mjs",
+      "require": "./facades/typescript.cjs"
+    },
+    "./clojurescript": {
+      "types": "./facades/clojurescript.d.ts",
+      "import": "./facades/clojurescript.mjs",
+      "require": "./facades/clojurescript.cjs"
+    },
+    "./wasm": {
+      "types": "./index.d.ts",
+      "default": "./facades/wasm.mjs"
+    },
+    "./wasi": {
+      "types": "./index.d.ts",
+      "import": "./facades/wasi.mjs"
+    },
+    "./cljs/vinary_tree/liblevenshtein.cljs": "./cljs/vinary_tree/liblevenshtein.cljs"
+  },
+  "cljs": {
+    "namespaces": {
+      "vinary-tree.liblevenshtein": "./cljs/vinary_tree/liblevenshtein.cljs"
+    }
   },
-  "exports": "./index.js",
   "files": [
-    "index.js",
+    "abi.d.ts",
+    "index.d.ts",
+    "facades/",
+    "cljs/",
+    "deps.cljs",
     "README.md"
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "bootstrap"
+    "provenance": true,
+    "tag": "next"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test:contract": "node --test test/facades.test.mjs && tsc -p tsconfig.test.json",
+    "test:clojurescript": "node test/clojurescript-test.mjs",
+    "test": "npm run test:contract && npm run test:clojurescript",
+    "prepack": "npm run build && npm test"
   }
 }

package/index.js

@@ -1,2 +0,0 @@
-/** Bootstrap reservation only. Install the `next` or `latest` release. */
-export const bootstrap = true;