@antfly/embedded 0.0.0-stage → 0.3.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Antfly, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,455 @@
-# Temporary Holding Version
+# @antfly/embedded
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js binding for embedded Antfly databases and inference -- the stable `libantfly` C ABI --
+using [koffi](https://koffi.dev) for FFI (prebuilt binaries, no node-gyp).
+Applications embed a live `.aflite` database directly in the Node process
+instead of talking to the network SDK.
+
+**Node-only.** This package uses koffi to load a native shared library and
+does not work in browsers. Antfly Lite also ships a separate WebAssembly
+build for browser use; this package is unrelated to that build.
+
+## Installation
+
+```bash
+pnpm add @antfly/embedded
+```
+
+Published platform packages include the Apache-2.0 `libantfly` library,
+without installing CLI commands or an unused worker executable.
+Prebuilt embedded packages support Linux x86-64 and ARM64 with glibc 2.28
+or newer, and macOS ARM64. Windows, Intel macOS, and Alpine/musl do not
+have prebuilt language packages. The native release archive matrix is
+separate; a source build or native archive does not imply wheel/npm support.
+ Source checkouts
+can build the shared library with "Library discovery" below. From the
+`antfly` monorepo source tree, build it
+with `cd zig && zig build lite` (produces `zig/zig-out/lib/libantfly.*`);
+this package does not build it for you.
+
+## Quick start
+
+```typescript
+import { create, THREADING_SERIALIZED, threadingMode } from "@antfly/embedded";
+
+// `await using` calls Symbol.asyncDispose, which closes the handle.
+await using db = await create("my.aflite");
+
+await db.batch(
+  [{ key: "doc:1", value: { title: "hello", body: "world" } }],
+  BigInt(Date.now()) * 1_000_000n // nanoseconds
+);
+
+const doc = await db.lookup("doc:1"); // parsed JSON
+const raw = await db.lookupRaw("doc:1"); // raw JSON bytes (Buffer)
+
+const hits = await db.search({
+  full_text_search: { match: { field: "body", text: "world" } },
+  limit: 5,
+});
+
+console.log(threadingMode() === THREADING_SERIALIZED); // true
+```
+
+Without top-level `await using` support, call `close()` explicitly (ideally
+in a `finally` block), or rely on the best-effort `FinalizationRegistry`
+cleanup as a last resort.
+
+## Async-first, thread-safe by design
+
+Every operation that touches an open handle is **async** and runs on koffi's
+native worker thread pool via `fn.async(...)`, so database work never blocks
+the Node event loop and concurrent calls actually run in parallel. Only cheap
+metadata calls that never touch a handle -- `abiVersion()`, `threadingMode()`,
+`validateAbi()`, `errorCodeName()` / `errorCodeDescription()` -- are
+synchronous.
+
+`libantfly` runs in **serialized threading mode** (`antfly_threading_mode()`
+== `THREADING_SERIALIZED`, like `sqlite3_threadsafe()`): any thread may call
+any function on any handle concurrently. Reads (`lookup`, `search`, `scan`,
+`stats`, ...) run in parallel with each other and with writes; writes on one
+handle queue behind each other instead of failing with `BusyError`; and
+schema/index/enrichment changes wait for in-flight calls. See
+`zig/CAPI.md`'s "Thread Safety" section for the full contract. A `Database`
+is safe to share across any number of concurrent async operations -- open one
+handle per file, not one per call.
+
+### koffi's worker thread pool size
+
+koffi dispatches async calls through Node's native async-work queue, which
+runs on **libuv's shared threadpool** (the same pool used by `fs`, `dns`,
+`zlib`, and `crypto.pbkdf2`). Its default size is 4 threads
+(`UV_THREADPOOL_SIZE`, max 1024). If your application needs more than 4
+truly concurrent native calls in flight (across `@antfly/embedded` and any other
+libuv-threadpool consumer), set `UV_THREADPOOL_SIZE` **before the Node
+process starts** (it cannot be changed at runtime):
+
+```bash
+UV_THREADPOOL_SIZE=16 node app.js
+```
+
+`koffi.config()` additionally controls per-call memory pool sizing
+(`async_stack_size`, `async_heap_size`, `resident_async_pools`,
+`max_async_calls`) but does not change the number of worker threads; the
+defaults are sufficient for this binding since `antfly_buffer` outputs are a
+small fixed-size struct (the pointed-to bytes are heap-allocated by
+`libantfly`, not stack/heap-marshaled by koffi).
+
+### Close semantics
+
+`db.close()` is idempotent and safe to call concurrently. It:
+
+1. Immediately rejects (with `InvalidArgumentError`) any new call made after
+   `close()` has started.
+2. Waits for every call this binding has already dispatched (queued on
+   koffi's worker pool, or actively executing) to settle.
+3. Only then calls the native `antfly_db_close`, and marks the handle closed.
+
+This extra bookkeeping exists because `antfly_db_close` only drains C calls
+that have already **entered** the library; a koffi async call can be queued
+on the libuv threadpool but not yet dequeued ("entered") when `close()`
+starts. Freeing the handle while such a call is still queued would be a
+use-after-free once that call finally runs. `@antfly/embedded` tracks its own
+in-flight promises (comparable to the Go binding's `sync.RWMutex` held around
+every call, exclusively in `Close`) so this can never happen.
+
+`await using` (`Symbol.asyncDispose`) calls `close()` for you. A
+`FinalizationRegistry` also closes the handle as a best-effort fallback if a
+`Database` is garbage-collected without an explicit `close()` -- do not rely
+on this for anything but leak mitigation; it is not deterministic.
+
+## Library discovery
+
+`@antfly/embedded` resolves the `libantfly` shared library in this order:
+
+1. **`ANTFLY_LIBRARY`** environment variable -- an exact file path. Throws if
+   the file does not exist (fails loudly rather than silently falling
+   through).
+2. **`ANTFLY_LIB_DIR`** environment variable -- a directory expected to
+   contain the platform library file (see below). Throws if the file is
+   missing from that directory.
+3. The installed Apache **`@antfly/embedded-<platform>`** package's `lib/` directory,
+   resolved via `require.resolve`.
+4. **`zig/zig-out/lib/`** found by walking up from this package's own
+   directory -- for running against a local `antfly` monorepo source
+   checkout.
+5. The bare **system loader name**, resolved by the OS's normal shared
+   library search path (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH` /
+   rpath), matching the Go binding's fallback.
+
+Platform file names: `libantfly.dylib` (macOS), `libantfly.so` (Linux),
+`antfly.dll` (Windows).
+
+Call `resolveLibrary()` yourself to see which tier resolved and why, without
+loading the library.
+
+### Embedded inference
+
+`libantfly` runs inference **in-process**, in the calling process, on every
+backend -- Metal, CUDA, ONNX, and CPU alike -- for both `Database` (with
+`localRuntimeConfigured: true`) and the standalone `Inference` handle below.
+There is no separate worker process and no `ANTFLY_INFERENCE_WORKER`
+variable to configure. This is the trade SQLite makes for extensions that
+touch a GPU driver: a call that reaches the device or driver has no per-call
+abort, so `callTimeoutMs` and `close()` only take effect once the call
+returns, and a driver fault terminates the process. Calls on CPU backends
+still stop cooperatively. (The `antfly` server instead runs these backends
+in a worker process it can kill and restart; a library cannot do that to its
+host program.) See `zig/CAPI.md`'s "Inference In Process" section for the
+full rationale.
+
+### `Inference`: embedded inference without a database
+
+`Inference.open(options?)` starts the embedded inference runtime with no
+database attached -- models load on first use and stay cached until
+`close()`. Each call sends the request JSON and returns the response JSON of
+the matching `/ai/v1` route of the Antfly inference HTTP API
+(`specs/openapi/inference/api.yaml`):
+
+```typescript
+import { Inference } from "@antfly/embedded";
+
+const inf = await Inference.open({ modelsDir: "/path/to/models" });
+try {
+  const { data } = (await inf.chunk({
+    input: "Ants live in colonies. Workers gather food.",
+  })) as { data: unknown[] };
+
+  const embeddings = await inf.embed({ model: "owner/name", input: ["hello"] });
+} finally {
+  await inf.close();
+}
+```
+
+For decision question types and examples, see the
+[typed decision guide](../../../docs/guides/decisions.md).
+
+- **Calls**: `embed`, `rerank`, `chunk`, `generate`, `generateBatch`,
+  `rewrite`, `decide`, `extract`, `read` (OCR), `transcribe`, `listModels` -- each with
+  a bare form (parsed JSON) and a `...Raw` form (raw `Buffer`), following the
+  same convention as `Database`. Binary inputs (images, audio) go inline in
+  the request JSON, as base64 or `data:` URIs. Responses are always
+  complete: a `generate` request with `"stream": true` rejects with
+  `InvalidArgumentError` -- use `generateStream()` to stream.
+- **Errors**: every failed inference call still gets a JSON error body from
+  `libantfly` (`{"error": ..., "message": ...}`); this binding folds it into
+  the thrown `AntflyError`'s message and exposes the parsed body as
+  `.body`, in addition to the usual `.code`/`.codeName`. A model that is not
+  installed rejects with `NotFoundError` (`.body.error === "MODEL_NOT_FOUND"`).
+- **`generateStream(request, onChunk)`** streams a generate request (the
+  same body as `generate()`, with `"stream"` set for you). `onChunk` is
+  called **synchronously, on the calling thread**, once per streamed chunk
+  (a parsed `chat.completion.chunk` JSON object). Returning `false` from
+  `onChunk` stops generation early and the call rejects with
+  `CancelledError`; a thrown error also stops generation and is rethrown.
+  Like `pull()` below, `generateStream()` runs synchronously and blocks the
+  Node event loop for its duration -- the same koffi callback-threading
+  constraint applies, which is why this binding exposes a callback rather
+  than an async iterator (an async iterator would need the call running off
+  the JS thread, which a koffi callback cannot do safely). `generateStreamRaw`
+  gives `onChunk` the raw per-chunk `Buffer` instead of parsed JSON.
+- **`pull(request, onProgress?, signal?)`** downloads a model from the
+  Hugging Face Hub into the handle's models directory, like
+  `antfly inference pull`: `{ model: "owner/name[:variant]", variants?,
+  token?, tasks?, capabilities?, projector?, maxArtifactBytes?,
+  maxModelBytes? }` (as request JSON; field names follow the HTTP API, e.g.
+  `"model"`). The optional `onProgress` callback is called synchronously, on
+  the calling thread, as each file starts, every 16 MiB, and as it
+  completes. Returning `false` from `onProgress` cancels the pull -- the
+  call then rejects with `CancelledError`, and completed files stay staged,
+  so a later `pull()` for the same model resumes rather than restarts; a
+  thrown error also cancels the pull and is rethrown. The optional `signal`
+  (`AbortSignal`) is a best-effort, honestly-limited convenience on top of
+  that: because `pull()` blocks the JS thread for its whole duration, there
+  is no way to interrupt it asynchronously the way `fetch(url, { signal })`
+  can. An already-aborted signal rejects before the pull starts; otherwise
+  it is only checked at the same report points as `onProgress` -- prefer
+  returning `false` from `onProgress` when you need precise control.
+  Unlike every other `Inference`/`Database` call, **`pull()` runs
+  synchronously and blocks the Node event loop** for its duration -- this is
+  intentional: JS execution is single-threaded, and a callback koffi
+  delivers from a background thread (as happens for a call dispatched via
+  `fn.async(...)`, which runs on koffi's worker thread pool) has to be
+  queued back onto the JS main thread rather than invoked as a true
+  blocking round-trip; per koffi's docs that queuing only runs "as soon as
+  the event loop has a chance to run", which could reorder or delay a
+  report arbitrarily relative to the (already-freed) native data it points
+  to, or even deadlock. Calling synchronously keeps the whole call,
+  including every callback invocation, on one OS thread throughout,
+  matching the C API's "called on the calling thread" guarantee exactly.
+  `close()` waits for a pull in progress.
+- **Options**: `InferenceOptions` -- `modelsDir` (defaults to
+  `$ANTFLY_INFERENCE_MODELS_DIR`, else `~/.antfly/inference/models`),
+  the same `*BudgetMb` resource knobs as `Database`'s `OpenOptions`, and
+  `callTimeoutMs` (a deadline per call; 0 means none).
+- **Lifecycle**: `close()` is idempotent, safe to call concurrently, and
+  waits for in-flight calls; `Inference` implements `AsyncDisposable`
+  (`await using`), same as `Database`.
+
+## ABI validation
+
+`validateAbi()` checks that the loaded library's `antfly_abi_version()`
+(expected: 2) and `antfly_open_options` struct size match what this binding
+was compiled against, throwing `AbiMismatchError` otherwise. It runs
+automatically before every open/create call and before `checkFile()`; call
+it yourself at startup to fail fast.
+
+## Storage kinds
+
+Every open/create call accepts `storage` (`Storage.Lite`, the default, or
+`Storage.Directory`) via `OpenOptions.storage`:
+
+- `Storage.Lite` -- a single-file `.aflite` database (this package's usual
+  use case).
+- `Storage.Directory` -- a normal single-node Antfly directory. Directory
+  storage is created by opening a missing path with `open`/`openWithOptions`;
+  `create`/`createWithOptions` only create `.aflite` files.
+
+A portable `.afb` backup (`backup()`) round-trips across storage kinds: it
+restores into either kind with the module-level `restore`/`restoreFile`, and
+imports into an *empty* database of either kind with `importBackup()`.
+`restore(path, backup, { storage, replace })` and
+`restoreFile(path, backupPath, { storage, replace })` select the destination
+kind with `storage` (default `Storage.Lite`); the `.aflite` suffix is only
+required client-side when the destination is `Storage.Lite`.
+
+## JSON conventions
+
+Every request parameter that accepts a JSON body (`request`, `config`,
+`schema`, ...) accepts a plain object (JSON.stringify'd), a JSON string, or
+raw UTF-8 bytes (`Buffer` / `Uint8Array`).
+
+Every JSON-returning operation has two forms:
+
+- The bare name (e.g. `lookup`, `search`, `status`) returns **parsed JSON**
+  (typed as `unknown`, or a specific interface for `Status` /
+  `Capabilities` / the maintenance reports).
+- The `...Raw` suffix (e.g. `lookupRaw`, `searchRaw`, `statusRaw`) returns
+  the **raw JSON bytes** as a `Buffer`, skipping the parse.
+
+The packed **wire** searches (`denseSearchWire`, `textMatchWire`,
+`textTermWire`, `textMatchPhraseWire`) are a different, non-JSON binary
+format matching the server's wire protocol; they always take and return raw
+bytes (`Buffer` / `Uint8Array`), never JSON.
+
+`getRaw(key)` is the one exception to the naming scheme above: it mirrors
+`antfly_db_get_raw` / the Go binding's `Raw(key)`, returning the document's
+raw stored bytes (not JSON at all, since a document need not be JSON at the
+storage layer).
+
+Timestamps and versions that are `uint64_t` in the C ABI (`timestampNs`,
+`expectedVersion`, `commitVersion`, `busyTimeoutMs`, ...) accept both
+`number` and `bigint`; use `bigint` where precision matters; a nanosecond
+Unix timestamp exceeds `Number.MAX_SAFE_INTEGER`, so `commitVersion()`
+always returns `bigint`.
+
+## Errors
+
+Every failed call rejects with an `AntflyError` subclass carrying:
+
+- `.code` -- the numeric `antfly_error_code`.
+- `.codeName` -- the stable symbolic name, e.g. `"ANTFLY_BUSY"`, matching
+  `antfly_error_code_name()`.
+- `.message` -- built from `antfly_error_code_description()`.
+
+Subclasses: `InvalidArgumentError` (1), `NotFoundError` (2),
+`VersionConflictError` (3), `IntentConflictError` (4), `TxnNotFoundError` (5),
+`BusyError` (6), `OutcomeUnknownError` (7, not safe to retry automatically --
+publication may have succeeded but crash durability could not be confirmed),
+`UnsupportedError` (8, not transient), `StalledError` (9, a bounded drain
+like `runUntilIdle` made no progress and gave up), `CancelledError` (10, the
+caller returned `false` from an `Inference.pull()` `onProgress` or
+`Inference.generateStream()` `onChunk` callback -- a callback that throws
+instead stops the operation the same way, but rejects with the thrown error
+itself, not `CancelledError`), `InternalError` (255).
+
+## API surface
+
+Mirrors `go/pkg/embedded`'s surface idiomatically:
+
+- **Open/create**: `create`, `open`, `openReadonly`, `openStatusOnly`,
+  `openHosted`, `createHosted`, `openWithOptions`, `createWithOptions`, plus
+  `OpenOptions` (including `storage`), `Storage`, `OpenMode`, `Profile`,
+  `TxnStatus`, `GraphDirection`, `InferenceMode`, `THREADING_SERIALIZED`.
+- **`Database`**: `close()`, `[Symbol.asyncDispose]`; `batch`/`batchJson`;
+  `lookup`/`lookupRaw`/`getRaw`; `scan`/`search`/`stats`; `status`,
+  `capabilities`, `check`, `pendingWorkStats`, `runUntilIdle` /
+  `runUntilIdleStatus`, `replayGeneratedEnrichments`; `getSchema`/
+  `setSchema`; `listIndexes`/`addIndex`/`deleteIndex` (returns `boolean`);
+  `listEnrichments`/`addEnrichment`/`deleteEnrichment`; graph
+  (`edges`/`neighbors`/`traverseEdges`/`executeGraphQueries`/
+  `findShortestPath`/`findKShortestPaths`/`matchPattern`); wire searches
+  (`denseSearchWire`/`textMatchWire`/`textTermWire`/`textMatchPhraseWire`);
+  `aggregateHits`, `lookupArtifact`; `extractEnrichments`/
+  `computeEnrichments`; transactions (`beginTransaction`/`writeTransaction`/
+  `resolveTransaction`/`transactionStatus`/`commitVersion` -- 16-byte
+  transaction ids accepted as a `Uint8Array(16)` or a 32-char hex string);
+  `backup`/`importBackup`, `backupToFile`; `compact`/`vacuum`/
+  `copyStableSnapshot`.
+- **Module-level**: `checkFile`, `restore`/`restoreFile` (both take
+  `RestoreOptions` -- `{ storage, replace }`), `copyStableSnapshotFile`,
+  `decodeArtifactId`, `abiVersion`, `threadingMode`, `validateAbi`.
+- **`Inference`**: `Inference.open(options?)`, `close()`,
+  `[Symbol.asyncDispose]`; `embed`/`rerank`/`chunk`/`generate`/
+  `generateBatch`/`rewrite`/`extract`/`read`/`transcribe`/`listModels`
+  (each with a `...Raw` form); `generateStream(request, onChunk)` /
+  `generateStreamRaw`; `pull(request, onProgress?, signal?)`; plus
+  `InferenceOptions`, `PullProgress`, `CancelledError`,
+  `validateInferenceAbi`. See "Embedded inference" above.
+
+See `src/index.ts` for the full export list and `src/types.ts` for typed
+`Status` / `Capabilities` / report interfaces.
+
+## Testing
+
+```bash
+pnpm run typecheck
+pnpm run lint
+pnpm run build
+pnpm run test                                    # skips native-library tests cleanly if libantfly isn't found
+ANTFLY_LITE_REQUIRE_LIBRARY=1 pnpm run test       # fails instead of skipping if libantfly isn't found
+ANTFLY_LIBRARY=/nonexistent pnpm run test         # exercises the clean-skip path directly
+```
+
+`test/conformance.test.ts` runs every case under
+`zig/pkg/antfly-embedded/capi-conformance/cases/*.json` through this public API,
+mirroring `go/pkg/embedded/conformance_cgo_test.go`'s semantics, including the
+`storage`-typed opens and the `import_backup`/`restore_open` cross-storage
+cases. `test/storage.test.ts` adds coverage beyond conformance: restoring a
+`.aflite` backup into directory storage and reopening it. `test/
+concurrency.test.ts` covers mixed concurrent operations, `close()` racing
+in-flight calls, `busyTimeoutMs` behavior, and that concurrent searches
+overlap instead of serializing on the event loop. `test/errors.test.ts` and
+`test/discovery.test.ts` include pure tests that need no native library at
+all. `test/package.test.ts` builds and packs the package, then verifies CommonJS
+and ESM discovery in isolated Node processes outside a checkout. It checks all
+three platform packages and package-relative source discovery in installation
+paths containing spaces, `#`, and `?`, without loading the fixture libraries. `test/inference.test.ts` covers the `Inference` handle: open/close,
+calls that need no model (`chunk`, `listModels`), missing-model
+`NotFoundError` for both `embed` and `generateStream`, `pull({})`/
+streaming-`generate`/malformed-JSON-`generateStream` `InvalidArgumentError`
+cases, an optional real-embedding test gated on a locally installed Qwen
+model, an optional `generateStream` test gated on a locally installed Gemma
+generate model (`~/.antfly/inference/models/ggml-org/gemma-4-e2b-it-gguf*`)
+covering both a normal multi-chunk stream and cancelling after two chunks
+(`CancelledError`, exactly two `onChunk` calls), and a network-gated
+`pull()` test (`ANTFLY_INFERENCE_PULL_TEST_MODEL`, e.g.
+`sparse-encoder-testing/splade-bert-tiny-nq-onnx`) that cancels on the first
+progress report (`CancelledError`, model still absent from `listModels()`),
+then pulls the same model to completion with progress callbacks.
+
+## License
+
+Apache-2.0
+
+## SQL, Kysely, and multiple tables
+
+`Connection` provides a promise-based SQL session over a `Database`:
+
+```ts
+import { create, Connection } from "@antfly/embedded";
+const database = await create("app.aflite");
+const connection = await Connection.open(database);
+await connection.execute("CREATE TABLE people (id BIGINT PRIMARY KEY, name TEXT)");
+await connection.transaction(async tx => {
+  await tx.execute("INSERT INTO people (id,name) VALUES ($1,$2)", [1n, "Ada"]);
+});
+const result = await connection.query("SELECT id,name FROM people");
+for await (const page of connection.stream("SELECT id,name FROM people", [], 128)) {
+  console.log(page.rows);
+}
+await connection.close();
+await database.close();
+```
+
+`query` reads all native cursor pages; `stream` yields bounded pages. Integer
+columns use `bigint`, SQL NULL uses `null`, and JSON uses JavaScript values.
+Use bigint parameters when values exceed JavaScript's safe integer range.
+Errors carry `sqlstate` and an optional `transactionId`.
+
+Install Kysely 0.29 and import the optional dialect subpath:
+
+```ts
+import { Kysely } from "kysely";
+import { AntflyDialect } from "@antfly/embedded/kysely";
+const sql = new Kysely<{ people: { id: bigint; name: string } }>({
+  dialect: new AntflyDialect({ database }),
+});
+const people = await sql.selectFrom("people").selectAll().execute();
+await sql.destroy(); // The caller still owns database.
+```
+
+`createTable`, `listTables`, `openTable`, and `dropTable` expose the shared
+document catalog. Table handles reuse existing schema, index, enrichment,
+search, and document methods. Close them before dropping their tables;
+database close invalidates them.
+
+Portable `.afb` archives back up the entire database: its table catalog,
+schemas, documents, indexes, enrichments, and constraint records. Call backup
+on the database handle. Restore publishes all tables together into either
+Lite or directory storage; import requires an empty database with no open
+table handles, SQL sessions, or cursors. Table handles cannot export or import
+backups.
+
+See [the native SQL contract](../../../zig/CAPI.md#database-sql) for
+READ COMMITTED, savepoints, transactional DDL restrictions, and commit outcomes.