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

package/dist/index.d.cts

@@ -0,0 +1,322 @@
+import { C as CheckReport, S as StableSnapshotReport, R as RestoreOptions, N as NativeLibrary, I as InferenceOptions, J as JsonInput, P as PullProgress, D as Database, U as Uint64Like } from './database-BY3WSLgt.cjs';
+export { a as Capabilities, b as CompactReport, G as GraphDirection, c as InferenceMode, d as InferenceStatus, L as LibraryNotFoundError, e as LibrarySource, f as MIN_THREAD_STACK_SIZE, M as MemoryAdmissionStats, O as OpenMode, g as OpenOptions, h as PendingWorkStatus, i as Profile, j as ReplayGeneratedEnrichmentsResult, k as ResolvedLibrary, l as SUPPORTED_ABI_VERSION, m as Status, n as Storage, o as StorageStatus, T as THREADING_SERIALIZED, p as TTLCleanupOptions, q as TxnStatus, r as UnsupportedPlatformError, V as VacuumReport, W as WriteIntent, s as create, t as createHosted, u as createWithOptions, v as embeddedPlatformPackageName, w as open, x as openHosted, y as openReadonly, z as openStatusOnly, A as openWithOptions, B as platformLibraryFileName, E as resolveLibrary } from './database-BY3WSLgt.cjs';
+import 'koffi';
+
+/** Thrown by validateAbi() when the loaded libantfly does not match the header this binding was written against. */
+declare class AbiMismatchError extends Error {
+    constructor(message: string);
+}
+/** Returns the loaded Antfly C ABI version (antfly_abi_version()). */
+declare function abiVersion(): number;
+/**
+ * Reports the loaded libantfly threading contract, like sqlite3_threadsafe().
+ * Always THREADING_SERIALIZED for the current libantfly.
+ */
+declare function threadingMode(): number;
+/**
+ * Verifies that the loaded C library matches the header this binding was
+ * compiled against: antfly_abi_version() and the antfly_open_options struct
+ * size. Called automatically by every open/create/checkFile call; exposed so
+ * applications can fail fast at startup too.
+ */
+declare function validateAbi(): void;
+/**
+ * Verifies that the loaded C library's antfly_inference_options struct size
+ * matches the header this binding was compiled against, like validateAbi()
+ * does for antfly_open_options. Called automatically by Inference.open();
+ * exposed so applications can fail fast at startup too.
+ */
+declare function validateInferenceAbi(): void;
+
+/**
+ * Stable Antfly C ABI error codes (antfly_error_code in antfly.h). Values and
+ * descriptions mirror go/pkg/embedded/errors.go so behavior stays identical
+ * across bindings; a conformance/errors test cross-checks these against the
+ * loaded library's antfly_error_code_name/antfly_error_code_description.
+ */
+declare enum ErrorCode {
+    OK = 0,
+    InvalidArgument = 1,
+    NotFound = 2,
+    VersionConflict = 3,
+    IntentConflict = 4,
+    TxnNotFound = 5,
+    Busy = 6,
+    /**
+     * The operation crossed its publication point, but crash durability could
+     * not be confirmed. Inspect the destination; do not retry automatically.
+     */
+    OutcomeUnknown = 7,
+    /**
+     * The operation requires a capability unavailable on this platform or
+     * filesystem. Retrying unchanged will not succeed.
+     */
+    Unsupported = 8,
+    /**
+     * A bounded drain such as runUntilIdle detected a managed index making no
+     * forward progress and gave up.
+     */
+    Stalled = 9,
+    /**
+     * The caller cancelled the call by returning false from its progress or
+     * stream callback (Inference.pull()'s onProgress, Inference.generateStream()'s
+     * onChunk).
+     */
+    Cancelled = 10,
+    Internal = 255
+}
+/** Stable symbolic C ABI name for code, e.g. "ANTFLY_BUSY". */
+declare function errorCodeName(code: number): string;
+/** Short stable description for code. */
+declare function errorCodeDescription(code: number): string;
+/**
+ * AntflyError wraps a stable Antfly C ABI error code. `.code` is the numeric
+ * antfly_error_code, `.codeName` is its stable symbolic name (e.g.
+ * "ANTFLY_BUSY"), matching antfly_error_code_name.
+ */
+declare class AntflyError extends Error {
+    readonly code: number;
+    readonly codeName: string;
+    /**
+     * Parsed JSON error body, when the failing call returned one. Currently
+     * only Inference calls populate this (embed/rerank/.../pull): libantfly
+     * always fills their antfly_buffer output with {"error": ..., "message":
+     * ...} on failure, even though the call also returns a non-OK error code.
+     */
+    body?: unknown;
+    constructor(code: number, message?: string);
+}
+declare class InvalidArgumentError extends AntflyError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends AntflyError {
+    constructor(message?: string);
+}
+declare class VersionConflictError extends AntflyError {
+    constructor(message?: string);
+}
+declare class IntentConflictError extends AntflyError {
+    constructor(message?: string);
+}
+declare class TxnNotFoundError extends AntflyError {
+    constructor(message?: string);
+}
+declare class BusyError extends AntflyError {
+    constructor(message?: string);
+}
+declare class OutcomeUnknownError extends AntflyError {
+    constructor(message?: string);
+}
+declare class UnsupportedError extends AntflyError {
+    constructor(message?: string);
+}
+declare class StalledError extends AntflyError {
+    constructor(message?: string);
+}
+declare class CancelledError extends AntflyError {
+    constructor(message?: string);
+}
+declare class InternalError extends AntflyError {
+    constructor(message?: string);
+}
+
+/** Runs Lite integrity checks for path without opening a database handle and returns the raw JSON result. */
+declare function checkFileRaw(path: string): Promise<Buffer>;
+/** Runs Lite integrity checks for path without opening a database handle and returns the typed result. */
+declare function checkFile(path: string): Promise<CheckReport>;
+/**
+ * Opens srcPath read-only, copies a stable Lite snapshot to destPath, and
+ * returns the raw JSON result. Neither path needs an open handle.
+ */
+declare function copyStableSnapshotFileRaw(srcPath: string, destPath: string, replace: boolean): Promise<Buffer>;
+/** Typed form of copyStableSnapshotFileRaw. */
+declare function copyStableSnapshotFile(srcPath: string, destPath: string, replace: boolean): Promise<StableSnapshotReport>;
+/**
+ * Creates a database at path from a portable Antfly backup archive, of the
+ * storage kind opts.storage selects (default Storage.Lite). A backup of
+ * either kind restores into either kind. For Lite destinations path must end
+ * with .aflite (checked client-side only). OutcomeUnknown means the
+ * destination was published but crash durability could not be confirmed;
+ * inspect it and do not retry automatically.
+ */
+declare function restore(path: string, backup: Uint8Array, opts?: RestoreOptions): Promise<void>;
+/**
+ * restore() reading the archive from backupPath. For Lite destinations it
+ * streams with bounded memory use. Busy means the source changed during
+ * streaming or the source/destination is concurrently locked; retry after
+ * the files are stable and no writer is active. Unsupported means the source
+ * filesystem lacks required advisory locking; copy the archive to a
+ * supported local filesystem.
+ */
+declare function restoreFile(path: string, backupPath: string, opts?: RestoreOptions): Promise<void>;
+/** Decodes a base64 artifact ID without opening a database. */
+declare function decodeArtifactIdRaw(artifactIdBase64: string): Promise<Buffer>;
+/** Typed form of decodeArtifactIdRaw. */
+declare function decodeArtifactId(artifactIdBase64: string): Promise<unknown>;
+
+/**
+ * Return false from a pull() onProgress or generateStream() onChunk
+ * callback to cancel; anything else (including void/undefined) continues.
+ */
+type CallbackResult = boolean | void;
+/**
+ * An embedded Antfly inference runtime handle: no database, just model
+ * inference (embed, rerank, chunk, generate, rewrite, decide, extract, read/OCR,
+ * transcribe) via the libantfly antfly_inference_* C ABI. Models load on
+ * first use and stay cached until close().
+ *
+ * Every JSON call except pull() and generateStream() is async (runs on
+ * koffi's worker thread pool via fn.async(...), like Database) and has the
+ * same close semantics: close() waits for every call this binding has
+ * dispatched before freeing the native handle, and rejects new calls
+ * immediately once close() has started.
+ *
+ * pull() and generateStream() are the exceptions: both run synchronously
+ * on the calling (JS main) thread and block the event loop for their
+ * duration. This is required for their callbacks (pull's onProgress,
+ * generateStream's onChunk) -- JS execution is single-threaded, so a
+ * callback koffi delivers from a background thread (as happens for a call
+ * made via fn.async(...), which runs on koffi's worker thread pool) has to
+ * be queued back onto the JS main thread rather than invoked in 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) antfly_slice data it
+ * points to, and could even deadlock if the main thread never yields.
+ * Calling synchronously keeps the whole call, including every callback
+ * invocation, on one OS thread throughout, matching antfly.h's "called on
+ * the calling thread" guarantee exactly. See README.md's "Embedded
+ * inference" section.
+ */
+declare class Inference implements AsyncDisposable {
+    #private;
+    /** @internal use Inference.open() instead of the constructor. */
+    constructor(native: NativeLibrary, handle: unknown);
+    /** Starts the embedded inference runtime with no database. Returns UnsupportedError if this build does not link the inference runtime or it cannot start. */
+    static open(options?: InferenceOptions): Promise<Inference>;
+    /** Idempotent; waits for in-flight calls before freeing the native handle. Calls made after close() rejects with InvalidArgumentError. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    embedRaw(request: JsonInput): Promise<Buffer>;
+    embed(request: JsonInput): Promise<unknown>;
+    rerankRaw(request: JsonInput): Promise<Buffer>;
+    rerank(request: JsonInput): Promise<unknown>;
+    chunkRaw(request: JsonInput): Promise<Buffer>;
+    chunk(request: JsonInput): Promise<unknown>;
+    /** A generate request with "stream": true fails with InvalidArgumentError; responses are always complete. Use generateStream() to stream. */
+    generateRaw(request: JsonInput): Promise<Buffer>;
+    generate(request: JsonInput): Promise<unknown>;
+    /**
+     * Streams a generate request (antfly_inference_generate_stream_json): the
+     * same request 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), as the model produces
+     * tokens.
+     *
+     * Returning `false` from onChunk stops generation early; the call then
+     * rejects with CancelledError. A thrown error also stops generation and
+     * is rethrown from this call (generation does not continue in the
+     * background). generateStream() runs synchronously on the JS thread and
+     * blocks the event loop for its duration -- see the class docstring for
+     * why (the same koffi callback-threading constraint as pull()); this is
+     * the reason this binding offers a callback, not an async iterator.
+     *
+     * A request rejected before generation starts (e.g. a missing model)
+     * rejects the same way generate() does, with the JSON error body on
+     * `.body`. A failure mid-stream rejects InternalError with
+     * `.body.error === "STREAM_FAILED"`.
+     */
+    generateStreamRaw(request: JsonInput, onChunk: (chunkJson: Buffer) => CallbackResult): Promise<Buffer>;
+    generateStream(request: JsonInput, onChunk: (chunk: unknown) => CallbackResult): Promise<unknown>;
+    /** Up to 128 non-streaming generate requests in one call; per-item failures are reported in the response. */
+    generateBatchRaw(request: JsonInput): Promise<Buffer>;
+    generateBatch(request: JsonInput): Promise<unknown>;
+    rewriteRaw(request: JsonInput): Promise<Buffer>;
+    rewrite(request: JsonInput): Promise<unknown>;
+    /** Named choice, ordinal score, and Boolean questions using DecideRequest JSON. */
+    decideRaw(request: JsonInput): Promise<Buffer>;
+    /** Parsed DecideResponse from the same contract as POST /ai/v1/decisions. */
+    decide(request: JsonInput): Promise<unknown>;
+    extractRaw(request: JsonInput): Promise<Buffer>;
+    extract(request: JsonInput): Promise<unknown>;
+    /** OCR. */
+    readRaw(request: JsonInput): Promise<Buffer>;
+    read(request: JsonInput): Promise<unknown>;
+    transcribeRaw(request: JsonInput): Promise<Buffer>;
+    transcribe(request: JsonInput): Promise<unknown>;
+    /** The installed models, as returned by GET /ai/v1/models. */
+    listModelsRaw(): Promise<Buffer>;
+    listModels(): Promise<unknown>;
+    /**
+     * Downloads a model from the Hugging Face Hub into the handle's models
+     * directory, like `antfly inference pull`. request: {"model": "owner/name[:variant]",
+     * required; "variants": [...]; "token": "..." (default $HF_TOKEN);
+     * "tasks"/"capabilities" to override the model manifest; "projector":
+     * "auto" | "none" | "match"; "max_artifact_bytes"/"max_model_bytes"}.
+     *
+     * onProgress (optional) is called synchronously, on the calling thread,
+     * as each file starts, every 16 MiB, and as it completes; see the class
+     * docstring for why pull() itself runs synchronously (blocking the event
+     * loop) rather than on koffi's async worker pool. 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 from this call.
+     *
+     * `signal` (optional) is a best-effort, honestly-limited cancellation
+     * knob: because pull() blocks the JS thread for its whole duration,
+     * there is no way to interrupt it asynchronously from the outside the
+     * way `fetch(url, { signal })` can. An already-aborted signal rejects
+     * immediately without starting the pull; otherwise the signal is polled
+     * only at the same report points as onProgress (each file start, every
+     * 16 MiB, file end) -- an abort in between those points is not observed
+     * until the next one. Prefer returning `false` from onProgress when you
+     * need precise control.
+     *
+     * A model missing from the hub rejects with NotFoundError, a bad request
+     * or a model over the size limits with InvalidArgumentError, and a
+     * network or hub failure with BusyError. close() waits for a pull in
+     * progress.
+     */
+    pullRaw(request: JsonInput, onProgress?: (progress: PullProgress) => CallbackResult, signal?: AbortSignal): Promise<Buffer>;
+    pull(request: JsonInput, onProgress?: (progress: PullProgress) => CallbackResult, signal?: AbortSignal): Promise<unknown>;
+}
+
+interface SqlDiagnostic {
+    code: string;
+    message: string;
+    hint?: string;
+    retryable?: boolean;
+}
+declare class SqlError extends Error {
+    readonly diagnostic: SqlDiagnostic;
+    readonly transactionId?: string | undefined;
+    readonly sqlstate: string;
+    constructor(diagnostic: SqlDiagnostic, transactionId?: string | undefined);
+}
+interface SqlColumn {
+    name: string;
+    type: string;
+}
+interface SqlResult<Row = Record<string, unknown>> {
+    columns: readonly SqlColumn[];
+    rows: Row[];
+    rowsAffected: bigint;
+    commandTag: string;
+}
+
+/** One SQL session. Use a separate Connection for concurrently active transactions. */
+declare class Connection {
+    #private;
+    readonly database: Database;
+    readonly session: Uint64Like;
+    private readonly direct;
+    private constructor();
+    static open(database: Database): Promise<Connection>;
+    execute<Row = Record<string, unknown>>(statement: string, parameters?: readonly unknown[]): Promise<SqlResult<Row>>;
+    query<Row = Record<string, unknown>>(statement: string, parameters?: readonly unknown[]): Promise<SqlResult<Row>>;
+    stream<Row = Record<string, unknown>>(statement: string, parameters?: readonly unknown[], chunkSize?: number): AsyncGenerator<SqlResult<Row>>;
+    transaction<T>(operation: (transaction: Connection) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+
+export { AbiMismatchError, AntflyError, BusyError, CancelledError, CheckReport, Connection, Database, ErrorCode, Inference, InferenceOptions, IntentConflictError, InternalError, InvalidArgumentError, JsonInput, NotFoundError, OutcomeUnknownError, PullProgress, RestoreOptions, type SqlColumn, SqlError, type SqlResult, StableSnapshotReport, StalledError, TxnNotFoundError, Uint64Like, UnsupportedError, VersionConflictError, abiVersion, checkFile, checkFileRaw, copyStableSnapshotFile, copyStableSnapshotFileRaw, decodeArtifactId, decodeArtifactIdRaw, errorCodeDescription, errorCodeName, restore, restoreFile, threadingMode, validateAbi, validateInferenceAbi };

package/dist/index.d.ts

@@ -0,0 +1,322 @@
+import { C as CheckReport, S as StableSnapshotReport, R as RestoreOptions, N as NativeLibrary, I as InferenceOptions, J as JsonInput, P as PullProgress, D as Database, U as Uint64Like } from './database-BY3WSLgt.js';
+export { a as Capabilities, b as CompactReport, G as GraphDirection, c as InferenceMode, d as InferenceStatus, L as LibraryNotFoundError, e as LibrarySource, f as MIN_THREAD_STACK_SIZE, M as MemoryAdmissionStats, O as OpenMode, g as OpenOptions, h as PendingWorkStatus, i as Profile, j as ReplayGeneratedEnrichmentsResult, k as ResolvedLibrary, l as SUPPORTED_ABI_VERSION, m as Status, n as Storage, o as StorageStatus, T as THREADING_SERIALIZED, p as TTLCleanupOptions, q as TxnStatus, r as UnsupportedPlatformError, V as VacuumReport, W as WriteIntent, s as create, t as createHosted, u as createWithOptions, v as embeddedPlatformPackageName, w as open, x as openHosted, y as openReadonly, z as openStatusOnly, A as openWithOptions, B as platformLibraryFileName, E as resolveLibrary } from './database-BY3WSLgt.js';
+import 'koffi';
+
+/** Thrown by validateAbi() when the loaded libantfly does not match the header this binding was written against. */
+declare class AbiMismatchError extends Error {
+    constructor(message: string);
+}
+/** Returns the loaded Antfly C ABI version (antfly_abi_version()). */
+declare function abiVersion(): number;
+/**
+ * Reports the loaded libantfly threading contract, like sqlite3_threadsafe().
+ * Always THREADING_SERIALIZED for the current libantfly.
+ */
+declare function threadingMode(): number;
+/**
+ * Verifies that the loaded C library matches the header this binding was
+ * compiled against: antfly_abi_version() and the antfly_open_options struct
+ * size. Called automatically by every open/create/checkFile call; exposed so
+ * applications can fail fast at startup too.
+ */
+declare function validateAbi(): void;
+/**
+ * Verifies that the loaded C library's antfly_inference_options struct size
+ * matches the header this binding was compiled against, like validateAbi()
+ * does for antfly_open_options. Called automatically by Inference.open();
+ * exposed so applications can fail fast at startup too.
+ */
+declare function validateInferenceAbi(): void;
+
+/**
+ * Stable Antfly C ABI error codes (antfly_error_code in antfly.h). Values and
+ * descriptions mirror go/pkg/embedded/errors.go so behavior stays identical
+ * across bindings; a conformance/errors test cross-checks these against the
+ * loaded library's antfly_error_code_name/antfly_error_code_description.
+ */
+declare enum ErrorCode {
+    OK = 0,
+    InvalidArgument = 1,
+    NotFound = 2,
+    VersionConflict = 3,
+    IntentConflict = 4,
+    TxnNotFound = 5,
+    Busy = 6,
+    /**
+     * The operation crossed its publication point, but crash durability could
+     * not be confirmed. Inspect the destination; do not retry automatically.
+     */
+    OutcomeUnknown = 7,
+    /**
+     * The operation requires a capability unavailable on this platform or
+     * filesystem. Retrying unchanged will not succeed.
+     */
+    Unsupported = 8,
+    /**
+     * A bounded drain such as runUntilIdle detected a managed index making no
+     * forward progress and gave up.
+     */
+    Stalled = 9,
+    /**
+     * The caller cancelled the call by returning false from its progress or
+     * stream callback (Inference.pull()'s onProgress, Inference.generateStream()'s
+     * onChunk).
+     */
+    Cancelled = 10,
+    Internal = 255
+}
+/** Stable symbolic C ABI name for code, e.g. "ANTFLY_BUSY". */
+declare function errorCodeName(code: number): string;
+/** Short stable description for code. */
+declare function errorCodeDescription(code: number): string;
+/**
+ * AntflyError wraps a stable Antfly C ABI error code. `.code` is the numeric
+ * antfly_error_code, `.codeName` is its stable symbolic name (e.g.
+ * "ANTFLY_BUSY"), matching antfly_error_code_name.
+ */
+declare class AntflyError extends Error {
+    readonly code: number;
+    readonly codeName: string;
+    /**
+     * Parsed JSON error body, when the failing call returned one. Currently
+     * only Inference calls populate this (embed/rerank/.../pull): libantfly
+     * always fills their antfly_buffer output with {"error": ..., "message":
+     * ...} on failure, even though the call also returns a non-OK error code.
+     */
+    body?: unknown;
+    constructor(code: number, message?: string);
+}
+declare class InvalidArgumentError extends AntflyError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends AntflyError {
+    constructor(message?: string);
+}
+declare class VersionConflictError extends AntflyError {
+    constructor(message?: string);
+}
+declare class IntentConflictError extends AntflyError {
+    constructor(message?: string);
+}
+declare class TxnNotFoundError extends AntflyError {
+    constructor(message?: string);
+}
+declare class BusyError extends AntflyError {
+    constructor(message?: string);
+}
+declare class OutcomeUnknownError extends AntflyError {
+    constructor(message?: string);
+}
+declare class UnsupportedError extends AntflyError {
+    constructor(message?: string);
+}
+declare class StalledError extends AntflyError {
+    constructor(message?: string);
+}
+declare class CancelledError extends AntflyError {
+    constructor(message?: string);
+}
+declare class InternalError extends AntflyError {
+    constructor(message?: string);
+}
+
+/** Runs Lite integrity checks for path without opening a database handle and returns the raw JSON result. */
+declare function checkFileRaw(path: string): Promise<Buffer>;
+/** Runs Lite integrity checks for path without opening a database handle and returns the typed result. */
+declare function checkFile(path: string): Promise<CheckReport>;
+/**
+ * Opens srcPath read-only, copies a stable Lite snapshot to destPath, and
+ * returns the raw JSON result. Neither path needs an open handle.
+ */
+declare function copyStableSnapshotFileRaw(srcPath: string, destPath: string, replace: boolean): Promise<Buffer>;
+/** Typed form of copyStableSnapshotFileRaw. */
+declare function copyStableSnapshotFile(srcPath: string, destPath: string, replace: boolean): Promise<StableSnapshotReport>;
+/**
+ * Creates a database at path from a portable Antfly backup archive, of the
+ * storage kind opts.storage selects (default Storage.Lite). A backup of
+ * either kind restores into either kind. For Lite destinations path must end
+ * with .aflite (checked client-side only). OutcomeUnknown means the
+ * destination was published but crash durability could not be confirmed;
+ * inspect it and do not retry automatically.
+ */
+declare function restore(path: string, backup: Uint8Array, opts?: RestoreOptions): Promise<void>;
+/**
+ * restore() reading the archive from backupPath. For Lite destinations it
+ * streams with bounded memory use. Busy means the source changed during
+ * streaming or the source/destination is concurrently locked; retry after
+ * the files are stable and no writer is active. Unsupported means the source
+ * filesystem lacks required advisory locking; copy the archive to a
+ * supported local filesystem.
+ */
+declare function restoreFile(path: string, backupPath: string, opts?: RestoreOptions): Promise<void>;
+/** Decodes a base64 artifact ID without opening a database. */
+declare function decodeArtifactIdRaw(artifactIdBase64: string): Promise<Buffer>;
+/** Typed form of decodeArtifactIdRaw. */
+declare function decodeArtifactId(artifactIdBase64: string): Promise<unknown>;
+
+/**
+ * Return false from a pull() onProgress or generateStream() onChunk
+ * callback to cancel; anything else (including void/undefined) continues.
+ */
+type CallbackResult = boolean | void;
+/**
+ * An embedded Antfly inference runtime handle: no database, just model
+ * inference (embed, rerank, chunk, generate, rewrite, decide, extract, read/OCR,
+ * transcribe) via the libantfly antfly_inference_* C ABI. Models load on
+ * first use and stay cached until close().
+ *
+ * Every JSON call except pull() and generateStream() is async (runs on
+ * koffi's worker thread pool via fn.async(...), like Database) and has the
+ * same close semantics: close() waits for every call this binding has
+ * dispatched before freeing the native handle, and rejects new calls
+ * immediately once close() has started.
+ *
+ * pull() and generateStream() are the exceptions: both run synchronously
+ * on the calling (JS main) thread and block the event loop for their
+ * duration. This is required for their callbacks (pull's onProgress,
+ * generateStream's onChunk) -- JS execution is single-threaded, so a
+ * callback koffi delivers from a background thread (as happens for a call
+ * made via fn.async(...), which runs on koffi's worker thread pool) has to
+ * be queued back onto the JS main thread rather than invoked in 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) antfly_slice data it
+ * points to, and could even deadlock if the main thread never yields.
+ * Calling synchronously keeps the whole call, including every callback
+ * invocation, on one OS thread throughout, matching antfly.h's "called on
+ * the calling thread" guarantee exactly. See README.md's "Embedded
+ * inference" section.
+ */
+declare class Inference implements AsyncDisposable {
+    #private;
+    /** @internal use Inference.open() instead of the constructor. */
+    constructor(native: NativeLibrary, handle: unknown);
+    /** Starts the embedded inference runtime with no database. Returns UnsupportedError if this build does not link the inference runtime or it cannot start. */
+    static open(options?: InferenceOptions): Promise<Inference>;
+    /** Idempotent; waits for in-flight calls before freeing the native handle. Calls made after close() rejects with InvalidArgumentError. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    embedRaw(request: JsonInput): Promise<Buffer>;
+    embed(request: JsonInput): Promise<unknown>;
+    rerankRaw(request: JsonInput): Promise<Buffer>;
+    rerank(request: JsonInput): Promise<unknown>;
+    chunkRaw(request: JsonInput): Promise<Buffer>;
+    chunk(request: JsonInput): Promise<unknown>;
+    /** A generate request with "stream": true fails with InvalidArgumentError; responses are always complete. Use generateStream() to stream. */
+    generateRaw(request: JsonInput): Promise<Buffer>;
+    generate(request: JsonInput): Promise<unknown>;
+    /**
+     * Streams a generate request (antfly_inference_generate_stream_json): the
+     * same request 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), as the model produces
+     * tokens.
+     *
+     * Returning `false` from onChunk stops generation early; the call then
+     * rejects with CancelledError. A thrown error also stops generation and
+     * is rethrown from this call (generation does not continue in the
+     * background). generateStream() runs synchronously on the JS thread and
+     * blocks the event loop for its duration -- see the class docstring for
+     * why (the same koffi callback-threading constraint as pull()); this is
+     * the reason this binding offers a callback, not an async iterator.
+     *
+     * A request rejected before generation starts (e.g. a missing model)
+     * rejects the same way generate() does, with the JSON error body on
+     * `.body`. A failure mid-stream rejects InternalError with
+     * `.body.error === "STREAM_FAILED"`.
+     */
+    generateStreamRaw(request: JsonInput, onChunk: (chunkJson: Buffer) => CallbackResult): Promise<Buffer>;
+    generateStream(request: JsonInput, onChunk: (chunk: unknown) => CallbackResult): Promise<unknown>;
+    /** Up to 128 non-streaming generate requests in one call; per-item failures are reported in the response. */
+    generateBatchRaw(request: JsonInput): Promise<Buffer>;
+    generateBatch(request: JsonInput): Promise<unknown>;
+    rewriteRaw(request: JsonInput): Promise<Buffer>;
+    rewrite(request: JsonInput): Promise<unknown>;
+    /** Named choice, ordinal score, and Boolean questions using DecideRequest JSON. */
+    decideRaw(request: JsonInput): Promise<Buffer>;
+    /** Parsed DecideResponse from the same contract as POST /ai/v1/decisions. */
+    decide(request: JsonInput): Promise<unknown>;
+    extractRaw(request: JsonInput): Promise<Buffer>;
+    extract(request: JsonInput): Promise<unknown>;
+    /** OCR. */
+    readRaw(request: JsonInput): Promise<Buffer>;
+    read(request: JsonInput): Promise<unknown>;
+    transcribeRaw(request: JsonInput): Promise<Buffer>;
+    transcribe(request: JsonInput): Promise<unknown>;
+    /** The installed models, as returned by GET /ai/v1/models. */
+    listModelsRaw(): Promise<Buffer>;
+    listModels(): Promise<unknown>;
+    /**
+     * Downloads a model from the Hugging Face Hub into the handle's models
+     * directory, like `antfly inference pull`. request: {"model": "owner/name[:variant]",
+     * required; "variants": [...]; "token": "..." (default $HF_TOKEN);
+     * "tasks"/"capabilities" to override the model manifest; "projector":
+     * "auto" | "none" | "match"; "max_artifact_bytes"/"max_model_bytes"}.
+     *
+     * onProgress (optional) is called synchronously, on the calling thread,
+     * as each file starts, every 16 MiB, and as it completes; see the class
+     * docstring for why pull() itself runs synchronously (blocking the event
+     * loop) rather than on koffi's async worker pool. 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 from this call.
+     *
+     * `signal` (optional) is a best-effort, honestly-limited cancellation
+     * knob: because pull() blocks the JS thread for its whole duration,
+     * there is no way to interrupt it asynchronously from the outside the
+     * way `fetch(url, { signal })` can. An already-aborted signal rejects
+     * immediately without starting the pull; otherwise the signal is polled
+     * only at the same report points as onProgress (each file start, every
+     * 16 MiB, file end) -- an abort in between those points is not observed
+     * until the next one. Prefer returning `false` from onProgress when you
+     * need precise control.
+     *
+     * A model missing from the hub rejects with NotFoundError, a bad request
+     * or a model over the size limits with InvalidArgumentError, and a
+     * network or hub failure with BusyError. close() waits for a pull in
+     * progress.
+     */
+    pullRaw(request: JsonInput, onProgress?: (progress: PullProgress) => CallbackResult, signal?: AbortSignal): Promise<Buffer>;
+    pull(request: JsonInput, onProgress?: (progress: PullProgress) => CallbackResult, signal?: AbortSignal): Promise<unknown>;
+}
+
+interface SqlDiagnostic {
+    code: string;
+    message: string;
+    hint?: string;
+    retryable?: boolean;
+}
+declare class SqlError extends Error {
+    readonly diagnostic: SqlDiagnostic;
+    readonly transactionId?: string | undefined;
+    readonly sqlstate: string;
+    constructor(diagnostic: SqlDiagnostic, transactionId?: string | undefined);
+}
+interface SqlColumn {
+    name: string;
+    type: string;
+}
+interface SqlResult<Row = Record<string, unknown>> {
+    columns: readonly SqlColumn[];
+    rows: Row[];
+    rowsAffected: bigint;
+    commandTag: string;
+}
+
+/** One SQL session. Use a separate Connection for concurrently active transactions. */
+declare class Connection {
+    #private;
+    readonly database: Database;
+    readonly session: Uint64Like;
+    private readonly direct;
+    private constructor();
+    static open(database: Database): Promise<Connection>;
+    execute<Row = Record<string, unknown>>(statement: string, parameters?: readonly unknown[]): Promise<SqlResult<Row>>;
+    query<Row = Record<string, unknown>>(statement: string, parameters?: readonly unknown[]): Promise<SqlResult<Row>>;
+    stream<Row = Record<string, unknown>>(statement: string, parameters?: readonly unknown[], chunkSize?: number): AsyncGenerator<SqlResult<Row>>;
+    transaction<T>(operation: (transaction: Connection) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+
+export { AbiMismatchError, AntflyError, BusyError, CancelledError, CheckReport, Connection, Database, ErrorCode, Inference, InferenceOptions, IntentConflictError, InternalError, InvalidArgumentError, JsonInput, NotFoundError, OutcomeUnknownError, PullProgress, RestoreOptions, type SqlColumn, SqlError, type SqlResult, StableSnapshotReport, StalledError, TxnNotFoundError, Uint64Like, UnsupportedError, VersionConflictError, abiVersion, checkFile, checkFileRaw, copyStableSnapshotFile, copyStableSnapshotFileRaw, decodeArtifactId, decodeArtifactIdRaw, errorCodeDescription, errorCodeName, restore, restoreFile, threadingMode, validateAbi, validateInferenceAbi };