@antfly/embedded 0.3.0-rc.8 → 0.3.0

package/README.md

@@ -185,7 +185,7 @@ For decision question types and examples, see the
 [typed decision guide](../../../docs/reference/decisions.md).
 
 - **Calls**: `embed`, `rerank`, `chunk`, `generate`, `generateBatch`,
-  `rewrite`, `decide`, `extract`, `read` (OCR), `transcribe`, `listModels` -- each with
+  `rewrite`, `decide`, `extract`, `read` (documents, images, audio), `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
@@ -315,7 +315,8 @@ Every failed call rejects with an `AntflyError` subclass carrying:
 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),
+the operation may have taken effect, but whether it applied or became durable
+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
@@ -323,6 +324,25 @@ caller returned `false` from an `Inference.pull()` `onProgress` or
 instead stops the operation the same way, but rejects with the thrown error
 itself, not `CancelledError`), `InternalError` (255).
 
+### Outcome receipts
+
+When an autocommit SQL write (`sqlJson`, `Connection` outside a transaction)
+ends with ANTFLY_OUTCOME_UNKNOWN, the rejection (`SqlError`, or
+`OutcomeUnknownError` without a SQL diagnostic) carries `.outcomeReceipt`
+(`undefined` when none was issued). Resolve it on any handle for the same
+database with `db.outcomeReceiptStatus(receipt)`, which resolves to
+`"applied"` or `"not_applied"`, or rejects with `StalledError` while the
+uncertain commit is not reconciled yet (Lite: retry; directory database:
+close the issuing handle and reopen first). Call
+`db.forgetOutcomeReceipt(receipt)` once resolved; afterwards it can no
+longer be resolved.
+
+`batch`, `batchJson` and `batchJsonRaw` rejections carry `.outcomeReceipt`
+too: they use `antfly_db_batch_with_receipt` and
+`antfly_db_batch_json_with_receipt`, which return the receipt from the same
+native call (the thread-local `antfly_last_error_outcome_receipt` cannot follow
+an async call to a worker thread).
+
 ## API surface
 
 Mirrors `go/pkg/embedded`'s surface idiomatically:
@@ -351,7 +371,7 @@ Mirrors `go/pkg/embedded`'s surface idiomatically:
   `decodeArtifactId`, `abiVersion`, `threadingMode`, `validateAbi`.
 - **`Inference`**: `Inference.open(options?)`, `close()`,
   `[Symbol.asyncDispose]`; `embed`/`rerank`/`chunk`/`generate`/
-  `generateBatch`/`rewrite`/`extract`/`read`/`transcribe`/`listModels`
+  `generateBatch`/`rewrite`/`extract`/`read`/`listModels`
   (each with a `...Raw` form); `generateStream(request, onChunk)` /
   `generateStreamRaw`; `pull(request, onProgress?, signal?)`; plus
   `InferenceOptions`, `PullProgress`, `CancelledError`,
@@ -439,6 +459,11 @@ const people = await sql.selectFrom("people").selectAll().execute();
 await sql.destroy(); // The caller still owns database.
 ```
 
+For typed search relations, migration-table setup, and generated Kysely schema
+interfaces, see the [Kysely reference](../sdk/docs/kysely.md) and
+[`examples/kysely.mjs`](examples/kysely.mjs). The optional shared helpers live in
+`@antfly/sdk/kysely`.
+
 `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;
@@ -453,3 +478,25 @@ backups.
 
 See [the native SQL contract](../../../zig/CAPI.md#database-sql) for
 READ COMMITTED, savepoints, transactional DDL restrictions, and commit outcomes.
+
+## Cypher and SQL graph composition
+
+`graphCatalogJson`, `cypherJson`, and `graphWriteStatus` expose durable named graphs, Cypher queries and mutations, and
+transaction receipts through libantfly. Catalog requests use `action` (`put`,
+`get`, `list`, `drop`), a graph `name`, and a `definition` for puts. Replacement
+and drop require the current decimal-string `expected_revision`.
+
+Queries use the same request contract as the server: `query`, `parameters` or
+lossless `typed_parameters`, optional limits, and `write_request_id`. Results
+contain tagged graph values; integer values are decimal strings. Native writes
+return a commit receipt. Retain the request ID and resolve an unknown outcome
+through the status method instead of replaying the query. `GraphError` preserves
+the diagnostic code, span, outcome, and transaction ID when available.
+
+Local SQL supports `GRAPH_TABLE` over these catalogs, including ordinary-table
+joins and staged SQL rows in an explicit transaction. Graph definitions pin
+local table and graph-index identities across reopen. Raw embedded calls reject
+protected tables; authenticated principal queries use the server API.
+
+See [the Cypher contract](../../../zig/CYPHER.md) for grammar, mapping, value,
+mutation, and deployment semantics.

package/dist/{chunk-4KIXT2VQ.js → chunk-MUBX3DSJ.js}

@@ -6,15 +6,21 @@ var __filename = /* @__PURE__ */ getFilename();
 
 // src/sql-types.ts
 var SqlError = class extends Error {
-  constructor(diagnostic, transactionId) {
+  /**
+   * @param outcomeReceipt Set when an autocommit write ended with an unknown
+   *   outcome; resolve it later with `Database.outcomeReceiptStatus()`.
+   */
+  constructor(diagnostic, transactionId, outcomeReceipt) {
     super(`${diagnostic.code}: ${diagnostic.message}`);
     this.diagnostic = diagnostic;
     this.transactionId = transactionId;
+    this.outcomeReceipt = outcomeReceipt;
     this.name = "SqlError";
     this.sqlstate = diagnostic.code;
   }
   diagnostic;
   transactionId;
+  outcomeReceipt;
   sqlstate;
 };
 

package/dist/{database-BT18eJuO.d.cts → database-DAUsGvzu.d.cts}

@@ -76,6 +76,11 @@ declare enum TxnStatus {
     Committed = 1,
     Aborted = 2
 }
+/**
+ * Resolved outcome of a write that ended with ANTFLY_OUTCOME_UNKNOWN
+ * (ANTFLY_OUTCOME_RECEIPT_APPLIED / ANTFLY_OUTCOME_RECEIPT_NOT_APPLIED).
+ */
+type OutcomeReceiptStatus = "applied" | "not_applied";
 /** Inference mode strings returned by Lite status and capabilities JSON. */
 declare const InferenceMode: {
     readonly CallerSuppliedOrDisabled: "caller_supplied_or_disabled";
@@ -225,6 +230,7 @@ interface Capabilities {
     object_storage_primary: boolean;
 }
 interface PendingWorkStatus {
+    background_publications?: unknown;
     derived_target_sequence: number;
     has_async_indexes: boolean;
     portable_import_publication_in_progress: boolean;
@@ -246,7 +252,20 @@ interface Status {
 interface ReplayGeneratedEnrichmentsResult {
     replayed: number;
 }
+/** Logical key/value payload, excluding physical headers. */
+interface LiveByteCategory {
+    records: number;
+    key_bytes: number;
+    value_bytes: number;
+}
+interface LiveByteAccounting {
+    metadata_catalog: LiveByteCategory;
+    index_catalog: LiveByteCategory;
+    control_documents: LiveByteCategory;
+    documents: LiveByteCategory;
+}
 interface CheckReport {
+    live_accounting?: LiveByteAccounting | null;
     valid: boolean;
     file_size: number;
     valid_prefix_size: number;
@@ -322,6 +341,9 @@ interface NativeLibrary {
     dbClose: KoffiFunc<(handle: unknown) => void>;
     bufferFree: KoffiFunc<(buffer: object) => void>;
     dbSqlJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
+    dbGraphCatalogJson?: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
+    dbCypherJson?: KoffiFunc<(handle: unknown, graph: object, request: object, out: object) => number>;
+    dbGraphWriteStatusJson?: KoffiFunc<(handle: unknown, transactionId: object, out: object) => number>;
     dbOpenTable: KoffiFunc<(handle: unknown, name: object, out: unknown[]) => number>;
     dbCreateTableJson: KoffiFunc<(handle: unknown, name: object, schema: object) => number>;
     dbDropTable: KoffiFunc<(handle: unknown, name: object) => number>;
@@ -348,7 +370,19 @@ interface NativeLibrary {
     dbReplayGeneratedEnrichmentsJson: KoffiFunc<(handle: unknown, out: object) => number>;
     dbPendingWorkStatsJson: KoffiFunc<(handle: unknown, out: object) => number>;
     dbBatch: KoffiFunc<(handle: unknown, writes: object[] | null, writeCount: number, predicates: object[] | null, predicateCount: number, timestampNs: number | bigint, syncLevel: number) => number>;
+    /** Struct batch that returns the outcome receipt in the same call. */
+    dbBatchWithReceipt: KoffiFunc<(handle: unknown, writes: object[] | null, writeCount: number, predicates: object[] | null, predicateCount: number, timestampNs: number | bigint, syncLevel: number, receiptOut: object) => number>;
     dbBatchJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
+    /** Batch JSON that returns the outcome receipt in the same call. */
+    dbBatchJsonWithReceipt: KoffiFunc<(handle: unknown, request: object, out: object, receiptOut: object) => number>;
+    /**
+     * Thread-local: valid only on the OS thread that ran the failed call, so
+     * it cannot follow an async (worker-thread) call. SQL error bodies carry
+     * the same receipt as "outcome_receipt".
+     */
+    lastErrorOutcomeReceipt: KoffiFunc<(out: object) => number>;
+    dbOutcomeReceiptStatus: KoffiFunc<(handle: unknown, receipt: object, outStatus: number[]) => number>;
+    dbOutcomeReceiptForget: KoffiFunc<(handle: unknown, receipt: object) => number>;
     dbBeginTransactionWithId: KoffiFunc<(handle: unknown, txnId: Uint8Array, timestampNs: number | bigint, participants: object[] | null, participantCount: number) => number>;
     dbWriteTransaction: KoffiFunc<(handle: unknown, txnId: Uint8Array, writes: object[] | null, writeCount: number, predicates: object[] | null, predicateCount: number) => number>;
     dbResolveIntents: KoffiFunc<(handle: unknown, txnId: Uint8Array, status: number, commitVersion: number | bigint) => number>;
@@ -410,7 +444,6 @@ interface NativeLibrary {
     inferenceDecideJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
     inferenceExtractJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
     inferenceReadJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
-    inferenceTranscribeJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
     inferenceListModelsJson: KoffiFunc<(handle: unknown, out: object) => number>;
     inferencePullJson: KoffiFunc<(handle: unknown, request: object, progress: unknown, progressContext: unknown, out: object) => number>;
 }
@@ -451,6 +484,9 @@ declare class Database implements AsyncDisposable {
     /** @internal use open()/create()/openHosted()/etc. instead of the constructor. */
     constructor(native: NativeLibrary, handle: unknown, owner?: Database | undefined);
     sqlJson(request: JsonInput): Promise<unknown>;
+    graphCatalogJson(request: JsonInput): Promise<unknown>;
+    cypherJson(graph: string, request: JsonInput): Promise<unknown>;
+    graphWriteStatus(transactionId: string): Promise<unknown>;
     createTable(name: string, schema: JsonInput): Promise<void>;
     dropTable(name: string): Promise<void>;
     listTables(): Promise<string[]>;
@@ -557,6 +593,16 @@ declare class Database implements AsyncDisposable {
     writeTransaction(txnId: Uint8Array | string, writes: WriteIntent[]): Promise<void>;
     resolveTransaction(txnId: Uint8Array | string, status: TxnStatus, commitVersion?: Uint64Like): Promise<void>;
     transactionStatus(txnId: Uint8Array | string): Promise<TxnStatus>;
+    /**
+     * Resolves an outcome receipt (`SqlError.outcomeReceipt` or
+     * `OutcomeUnknownError.outcomeReceipt`) on any handle for the same
+     * database. Rejects with `StalledError` while the uncertain commit is not
+     * reconciled yet: retry on a Lite database; for a directory database,
+     * close the issuing handle and reopen first.
+     */
+    outcomeReceiptStatus(receipt: string): Promise<OutcomeReceiptStatus>;
+    /** Removes a resolved receipt's durable marker; afterwards it cannot be resolved. */
+    forgetOutcomeReceipt(receipt: string): Promise<void>;
     commitVersion(txnId: Uint8Array | string): Promise<bigint>;
 }
 /** Opens an existing native Antfly Lite database file for writing. */
@@ -582,4 +628,4 @@ declare function openHosted(path: string): Promise<Database>;
  */
 declare function createHosted(path: string): Promise<Database>;
 
-export { openWithOptions as A, platformLibraryFileName as B, type CheckReport as C, Database as D, resolveLibrary as E, GraphDirection as G, type InferenceOptions as I, type JsonInput as J, LibraryNotFoundError as L, type MemoryAdmissionStats as M, type NativeLibrary as N, OpenMode as O, type PullProgress as P, type RestoreOptions as R, type StableSnapshotReport as S, THREADING_SERIALIZED as T, type Uint64Like as U, type VacuumReport as V, type WriteIntent as W, type Capabilities as a, type CompactReport as b, InferenceMode as c, type InferenceStatus as d, type LibrarySource as e, NATIVE_STACK_SIZE as f, type OpenOptions as g, type PendingWorkStatus as h, Profile as i, type ReplayGeneratedEnrichmentsResult as j, type ResolvedLibrary as k, SUPPORTED_ABI_VERSION as l, type Status as m, Storage as n, type StorageStatus as o, type TTLCleanupOptions as p, TxnStatus as q, UnsupportedPlatformError as r, create as s, createHosted as t, createWithOptions as u, embeddedPlatformPackageName as v, open as w, openHosted as x, openReadonly as y, openStatusOnly as z };
+export { openHosted as A, openReadonly as B, type CheckReport as C, Database as D, openStatusOnly as E, openWithOptions as F, GraphDirection as G, platformLibraryFileName as H, type InferenceOptions as I, type JsonInput as J, resolveLibrary as K, LibraryNotFoundError as L, type MemoryAdmissionStats as M, type NativeLibrary as N, OpenMode as O, type PullProgress as P, type RestoreOptions as R, type StableSnapshotReport as S, THREADING_SERIALIZED as T, type Uint64Like as U, type VacuumReport as V, type WriteIntent as W, type Capabilities as a, type CompactReport as b, InferenceMode as c, type InferenceStatus as d, type LibrarySource as e, type LiveByteAccounting as f, type LiveByteCategory as g, NATIVE_STACK_SIZE as h, type OpenOptions as i, type OutcomeReceiptStatus as j, type PendingWorkStatus as k, Profile as l, type ReplayGeneratedEnrichmentsResult as m, type ResolvedLibrary as n, SUPPORTED_ABI_VERSION as o, type Status as p, Storage as q, type StorageStatus as r, type TTLCleanupOptions as s, TxnStatus as t, UnsupportedPlatformError as u, create as v, createHosted as w, createWithOptions as x, embeddedPlatformPackageName as y, open as z };

package/dist/{database-BT18eJuO.d.ts → database-DAUsGvzu.d.ts}

@@ -76,6 +76,11 @@ declare enum TxnStatus {
     Committed = 1,
     Aborted = 2
 }
+/**
+ * Resolved outcome of a write that ended with ANTFLY_OUTCOME_UNKNOWN
+ * (ANTFLY_OUTCOME_RECEIPT_APPLIED / ANTFLY_OUTCOME_RECEIPT_NOT_APPLIED).
+ */
+type OutcomeReceiptStatus = "applied" | "not_applied";
 /** Inference mode strings returned by Lite status and capabilities JSON. */
 declare const InferenceMode: {
     readonly CallerSuppliedOrDisabled: "caller_supplied_or_disabled";
@@ -225,6 +230,7 @@ interface Capabilities {
     object_storage_primary: boolean;
 }
 interface PendingWorkStatus {
+    background_publications?: unknown;
     derived_target_sequence: number;
     has_async_indexes: boolean;
     portable_import_publication_in_progress: boolean;
@@ -246,7 +252,20 @@ interface Status {
 interface ReplayGeneratedEnrichmentsResult {
     replayed: number;
 }
+/** Logical key/value payload, excluding physical headers. */
+interface LiveByteCategory {
+    records: number;
+    key_bytes: number;
+    value_bytes: number;
+}
+interface LiveByteAccounting {
+    metadata_catalog: LiveByteCategory;
+    index_catalog: LiveByteCategory;
+    control_documents: LiveByteCategory;
+    documents: LiveByteCategory;
+}
 interface CheckReport {
+    live_accounting?: LiveByteAccounting | null;
     valid: boolean;
     file_size: number;
     valid_prefix_size: number;
@@ -322,6 +341,9 @@ interface NativeLibrary {
     dbClose: KoffiFunc<(handle: unknown) => void>;
     bufferFree: KoffiFunc<(buffer: object) => void>;
     dbSqlJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
+    dbGraphCatalogJson?: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
+    dbCypherJson?: KoffiFunc<(handle: unknown, graph: object, request: object, out: object) => number>;
+    dbGraphWriteStatusJson?: KoffiFunc<(handle: unknown, transactionId: object, out: object) => number>;
     dbOpenTable: KoffiFunc<(handle: unknown, name: object, out: unknown[]) => number>;
     dbCreateTableJson: KoffiFunc<(handle: unknown, name: object, schema: object) => number>;
     dbDropTable: KoffiFunc<(handle: unknown, name: object) => number>;
@@ -348,7 +370,19 @@ interface NativeLibrary {
     dbReplayGeneratedEnrichmentsJson: KoffiFunc<(handle: unknown, out: object) => number>;
     dbPendingWorkStatsJson: KoffiFunc<(handle: unknown, out: object) => number>;
     dbBatch: KoffiFunc<(handle: unknown, writes: object[] | null, writeCount: number, predicates: object[] | null, predicateCount: number, timestampNs: number | bigint, syncLevel: number) => number>;
+    /** Struct batch that returns the outcome receipt in the same call. */
+    dbBatchWithReceipt: KoffiFunc<(handle: unknown, writes: object[] | null, writeCount: number, predicates: object[] | null, predicateCount: number, timestampNs: number | bigint, syncLevel: number, receiptOut: object) => number>;
     dbBatchJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
+    /** Batch JSON that returns the outcome receipt in the same call. */
+    dbBatchJsonWithReceipt: KoffiFunc<(handle: unknown, request: object, out: object, receiptOut: object) => number>;
+    /**
+     * Thread-local: valid only on the OS thread that ran the failed call, so
+     * it cannot follow an async (worker-thread) call. SQL error bodies carry
+     * the same receipt as "outcome_receipt".
+     */
+    lastErrorOutcomeReceipt: KoffiFunc<(out: object) => number>;
+    dbOutcomeReceiptStatus: KoffiFunc<(handle: unknown, receipt: object, outStatus: number[]) => number>;
+    dbOutcomeReceiptForget: KoffiFunc<(handle: unknown, receipt: object) => number>;
     dbBeginTransactionWithId: KoffiFunc<(handle: unknown, txnId: Uint8Array, timestampNs: number | bigint, participants: object[] | null, participantCount: number) => number>;
     dbWriteTransaction: KoffiFunc<(handle: unknown, txnId: Uint8Array, writes: object[] | null, writeCount: number, predicates: object[] | null, predicateCount: number) => number>;
     dbResolveIntents: KoffiFunc<(handle: unknown, txnId: Uint8Array, status: number, commitVersion: number | bigint) => number>;
@@ -410,7 +444,6 @@ interface NativeLibrary {
     inferenceDecideJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
     inferenceExtractJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
     inferenceReadJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
-    inferenceTranscribeJson: KoffiFunc<(handle: unknown, request: object, out: object) => number>;
     inferenceListModelsJson: KoffiFunc<(handle: unknown, out: object) => number>;
     inferencePullJson: KoffiFunc<(handle: unknown, request: object, progress: unknown, progressContext: unknown, out: object) => number>;
 }
@@ -451,6 +484,9 @@ declare class Database implements AsyncDisposable {
     /** @internal use open()/create()/openHosted()/etc. instead of the constructor. */
     constructor(native: NativeLibrary, handle: unknown, owner?: Database | undefined);
     sqlJson(request: JsonInput): Promise<unknown>;
+    graphCatalogJson(request: JsonInput): Promise<unknown>;
+    cypherJson(graph: string, request: JsonInput): Promise<unknown>;
+    graphWriteStatus(transactionId: string): Promise<unknown>;
     createTable(name: string, schema: JsonInput): Promise<void>;
     dropTable(name: string): Promise<void>;
     listTables(): Promise<string[]>;
@@ -557,6 +593,16 @@ declare class Database implements AsyncDisposable {
     writeTransaction(txnId: Uint8Array | string, writes: WriteIntent[]): Promise<void>;
     resolveTransaction(txnId: Uint8Array | string, status: TxnStatus, commitVersion?: Uint64Like): Promise<void>;
     transactionStatus(txnId: Uint8Array | string): Promise<TxnStatus>;
+    /**
+     * Resolves an outcome receipt (`SqlError.outcomeReceipt` or
+     * `OutcomeUnknownError.outcomeReceipt`) on any handle for the same
+     * database. Rejects with `StalledError` while the uncertain commit is not
+     * reconciled yet: retry on a Lite database; for a directory database,
+     * close the issuing handle and reopen first.
+     */
+    outcomeReceiptStatus(receipt: string): Promise<OutcomeReceiptStatus>;
+    /** Removes a resolved receipt's durable marker; afterwards it cannot be resolved. */
+    forgetOutcomeReceipt(receipt: string): Promise<void>;
     commitVersion(txnId: Uint8Array | string): Promise<bigint>;
 }
 /** Opens an existing native Antfly Lite database file for writing. */
@@ -582,4 +628,4 @@ declare function openHosted(path: string): Promise<Database>;
  */
 declare function createHosted(path: string): Promise<Database>;
 
-export { openWithOptions as A, platformLibraryFileName as B, type CheckReport as C, Database as D, resolveLibrary as E, GraphDirection as G, type InferenceOptions as I, type JsonInput as J, LibraryNotFoundError as L, type MemoryAdmissionStats as M, type NativeLibrary as N, OpenMode as O, type PullProgress as P, type RestoreOptions as R, type StableSnapshotReport as S, THREADING_SERIALIZED as T, type Uint64Like as U, type VacuumReport as V, type WriteIntent as W, type Capabilities as a, type CompactReport as b, InferenceMode as c, type InferenceStatus as d, type LibrarySource as e, NATIVE_STACK_SIZE as f, type OpenOptions as g, type PendingWorkStatus as h, Profile as i, type ReplayGeneratedEnrichmentsResult as j, type ResolvedLibrary as k, SUPPORTED_ABI_VERSION as l, type Status as m, Storage as n, type StorageStatus as o, type TTLCleanupOptions as p, TxnStatus as q, UnsupportedPlatformError as r, create as s, createHosted as t, createWithOptions as u, embeddedPlatformPackageName as v, open as w, openHosted as x, openReadonly as y, openStatusOnly as z };
+export { openHosted as A, openReadonly as B, type CheckReport as C, Database as D, openStatusOnly as E, openWithOptions as F, GraphDirection as G, platformLibraryFileName as H, type InferenceOptions as I, type JsonInput as J, resolveLibrary as K, LibraryNotFoundError as L, type MemoryAdmissionStats as M, type NativeLibrary as N, OpenMode as O, type PullProgress as P, type RestoreOptions as R, type StableSnapshotReport as S, THREADING_SERIALIZED as T, type Uint64Like as U, type VacuumReport as V, type WriteIntent as W, type Capabilities as a, type CompactReport as b, InferenceMode as c, type InferenceStatus as d, type LibrarySource as e, type LiveByteAccounting as f, type LiveByteCategory as g, NATIVE_STACK_SIZE as h, type OpenOptions as i, type OutcomeReceiptStatus as j, type PendingWorkStatus as k, Profile as l, type ReplayGeneratedEnrichmentsResult as m, type ResolvedLibrary as n, SUPPORTED_ABI_VERSION as o, type Status as p, Storage as q, type StorageStatus as r, type TTLCleanupOptions as s, TxnStatus as t, UnsupportedPlatformError as u, create as v, createHosted as w, createWithOptions as x, embeddedPlatformPackageName as y, open as z };

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   Database: () => Database,
   ErrorCode: () => ErrorCode,
   GraphDirection: () => GraphDirection,
+  GraphError: () => GraphError,
   Inference: () => Inference,
   InferenceMode: () => InferenceMode,
   IntentConflictError: () => IntentConflictError,
@@ -241,7 +242,7 @@ var ERROR_CODE_DESCRIPTIONS = {
   [4 /* IntentConflict */]: "a transaction intent conflicts with the requested operation",
   [5 /* TxnNotFound */]: "the requested transaction was not found",
   [6 /* Busy */]: "the requested resource is temporarily busy or changed during streaming; stabilize it and retry",
-  [7 /* OutcomeUnknown */]: "the operation was published, but crash durability could not be confirmed; inspect the destination and do not retry automatically",
+  [7 /* OutcomeUnknown */]: "the operation may have taken effect, but whether it applied or became durable could not be confirmed; inspect the affected data and do not retry automatically",
   [8 /* Unsupported */]: "the operation requires a capability that is not supported by this platform or filesystem",
   [9 /* Stalled */]: "derived work stalled or failed; inspect pending-work diagnostics and repair or reopen the database",
   [10 /* Cancelled */]: "the caller cancelled the operation",
@@ -315,9 +316,16 @@ var BusyError = class extends AntflyError {
   }
 };
 var OutcomeUnknownError = class extends AntflyError {
-  constructor(message) {
+  /**
+   * The receipt the database issued for an autocommit SQL write that ended
+   * with an unknown outcome, if any. Resolve it later with
+   * `Database.outcomeReceiptStatus()`.
+   */
+  outcomeReceipt;
+  constructor(message, outcomeReceipt) {
     super(7 /* OutcomeUnknown */, message);
     this.name = "OutcomeUnknownError";
+    if (outcomeReceipt !== void 0) this.outcomeReceipt = outcomeReceipt;
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
@@ -555,6 +563,31 @@ function buildNative() {
   configureKoffiStacks();
   const handle = import_koffi.default.load(resolved.path);
   const f = handle.func.bind(handle);
+  let dbGraphCatalogJson;
+  let dbCypherJson;
+  let dbGraphWriteStatusJson;
+  try {
+    dbGraphCatalogJson = f("antfly_db_graph_catalog_json", "uint32_t", [
+      PAntflyDb,
+      AntflySlice,
+      PAntflyBufferOut
+    ]);
+    dbCypherJson = f("antfly_db_cypher_json", "uint32_t", [
+      PAntflyDb,
+      AntflySlice,
+      AntflySlice,
+      PAntflyBufferOut
+    ]);
+    dbGraphWriteStatusJson = f("antfly_db_graph_write_status_json", "uint32_t", [
+      PAntflyDb,
+      AntflySlice,
+      PAntflyBufferOut
+    ]);
+  } catch {
+    dbGraphCatalogJson = void 0;
+    dbCypherJson = void 0;
+    dbGraphWriteStatusJson = void 0;
+  }
   return {
     handle,
     resolved,
@@ -579,6 +612,9 @@ function buildNative() {
     dbClose: f("antfly_db_close", "void", [PAntflyDb]),
     bufferFree: f("antfly_buffer_free", "void", [import_koffi.default.pointer(AntflyBuffer)]),
     dbSqlJson: f("antfly_db_sql_json", "uint32_t", [PAntflyDb, AntflySlice, PAntflyBufferOut]),
+    dbGraphCatalogJson,
+    dbCypherJson,
+    dbGraphWriteStatusJson,
     dbOpenTable: f("antfly_db_open_table", "uint32_t", [PAntflyDb, AntflySlice, PAntflyDbOut]),
     dbCreateTableJson: f("antfly_db_create_table_json", "uint32_t", [
       PAntflyDb,
@@ -661,7 +697,33 @@ function buildNative() {
       "uint64_t",
       "uint8_t"
     ]),
+    dbBatchWithReceipt: f("antfly_db_batch_with_receipt", "uint32_t", [
+      PAntflyDb,
+      PAntflyWriteIntentArray,
+      "size_t",
+      PAntflyVersionPredicateArray,
+      "size_t",
+      "uint64_t",
+      "uint8_t",
+      PAntflyBufferOut
+    ]),
     dbBatchJson: f("antfly_db_batch_json", "uint32_t", [PAntflyDb, AntflySlice, PAntflyBufferOut]),
+    dbBatchJsonWithReceipt: f("antfly_db_batch_json_with_receipt", "uint32_t", [
+      PAntflyDb,
+      AntflySlice,
+      PAntflyBufferOut,
+      PAntflyBufferOut
+    ]),
+    lastErrorOutcomeReceipt: f("antfly_last_error_outcome_receipt", "uint32_t", [PAntflyBufferOut]),
+    dbOutcomeReceiptStatus: f("antfly_db_outcome_receipt_status", "uint32_t", [
+      PAntflyDb,
+      AntflySlice,
+      PUint8Out
+    ]),
+    dbOutcomeReceiptForget: f("antfly_db_outcome_receipt_forget", "uint32_t", [
+      PAntflyDb,
+      AntflySlice
+    ]),
     dbBeginTransactionWithId: f("antfly_db_begin_transaction_with_id", "uint32_t", [
       PAntflyDb,
       "const uint8_t *",
@@ -941,11 +1003,6 @@ function buildNative() {
       AntflySlice,
       PAntflyBufferOut
     ]),
-    inferenceTranscribeJson: f("antfly_inference_transcribe_json", "uint32_t", [
-      PAntflyInference,
-      AntflySlice,
-      PAntflyBufferOut
-    ]),
     inferenceListModelsJson: f("antfly_inference_list_models_json", "uint32_t", [
       PAntflyInference,
       PAntflyBufferOut
@@ -1004,6 +1061,18 @@ function validateInferenceAbi() {
 var fsp = __toESM(require("fs/promises"), 1);
 var import_node_path2 = require("path");
 
+// src/graph-types.ts
+var GraphError = class extends Error {
+  constructor(diagnostic, nativeCode) {
+    super(diagnostic.message);
+    this.diagnostic = diagnostic;
+    this.nativeCode = nativeCode;
+    this.name = "GraphError";
+  }
+  diagnostic;
+  nativeCode;
+};
+
 // src/marshal.ts
 var import_node_util = require("util");
 var import_koffi3 = __toESM(require("koffi"), 1);
@@ -1118,19 +1187,27 @@ function parseMemoryJson(buf) {
 
 // src/sql-types.ts
 var SqlError = class extends Error {
-  constructor(diagnostic, transactionId) {
+  /**
+   * @param outcomeReceipt Set when an autocommit write ended with an unknown
+   *   outcome; resolve it later with `Database.outcomeReceiptStatus()`.
+   */
+  constructor(diagnostic, transactionId, outcomeReceipt) {
     super(`${diagnostic.code}: ${diagnostic.message}`);
     this.diagnostic = diagnostic;
     this.transactionId = transactionId;
+    this.outcomeReceipt = outcomeReceipt;
     this.name = "SqlError";
     this.sqlstate = diagnostic.code;
   }
   diagnostic;
   transactionId;
+  outcomeReceipt;
   sqlstate;
 };
 
 // src/database.ts
+var OUTCOME_RECEIPT_APPLIED = 1;
+var OUTCOME_RECEIPT_NOT_APPLIED = 2;
 var OPEN_FLAG_NO_SYNC = 1 << 0;
 var OPEN_FLAG_TTL_CLEANUP = 1 << 1;
 var OPEN_FLAG_REMOTE_PROVIDER_CONFIGURED = 1 << 2;
@@ -1238,7 +1315,12 @@ var Database = class _Database {
       const code = await callAsync(fn, handle, ...args, out);
       const body = takeBuffer(this.#native, out);
       const value = body.length ? JSON.parse(body.toString("utf8")) : void 0;
-      if (code && value?.error) throw new SqlError(value.error, value.transaction_id);
+      if (code && value?.error) {
+        throw new SqlError(value.error, value.transaction_id, value.outcome_receipt);
+      }
+      if (code === 7 /* OutcomeUnknown */ && typeof value?.outcome_receipt === "string") {
+        throw new OutcomeUnknownError(void 0, value.outcome_receipt);
+      }
       checkCode(code);
       return value;
     });
@@ -1246,6 +1328,31 @@ var Database = class _Database {
   sqlJson(request2) {
     return this.#invokeSql(this.#native.dbSqlJson, jsonSlice(request2));
   }
+  // biome-ignore lint/suspicious/noExplicitAny: native signatures vary
+  #invokeGraph(fn, ...args) {
+    if (!fn)
+      return Promise.reject(
+        new UnsupportedError("This native library does not expose Cypher graphs")
+      );
+    return this.#run(async (handle) => {
+      const out = newBufferOut();
+      const code = await callAsync(fn, handle, ...args, out);
+      const body = takeBuffer(this.#native, out);
+      const value = body.length ? JSON.parse(body.toString("utf8")) : void 0;
+      if (code && value?.code) throw new GraphError(value, code);
+      checkCode(code);
+      return value;
+    });
+  }
+  graphCatalogJson(request2) {
+    return this.#invokeGraph(this.#native.dbGraphCatalogJson, jsonSlice(request2));
+  }
+  cypherJson(graph, request2) {
+    return this.#invokeGraph(this.#native.dbCypherJson, stringSlice(graph), jsonSlice(request2));
+  }
+  graphWriteStatus(transactionId) {
+    return this.#invokeGraph(this.#native.dbGraphWriteStatusJson, stringSlice(transactionId));
+  }
   createTable(name, schema) {
     return this.#invokeCode(this.#native.dbCreateTableJson, stringSlice(name), jsonSlice(schema));
   }
@@ -1389,21 +1496,44 @@ var Database = class _Database {
   batch(writes, timestampNs) {
     return this.#run(async (handle) => {
       const cWrites = writes.length ? writes.map(toNativeWriteIntent) : null;
+      const receiptOut = newBufferOut();
       const code = await callAsync(
-        this.#native.dbBatch,
+        this.#native.dbBatchWithReceipt,
         handle,
         cWrites,
         writes.length,
         null,
         0,
         timestampNs,
-        0
+        0,
+        receiptOut
       );
+      const receipt = takeBuffer(this.#native, receiptOut);
+      if (code === 7 /* OutcomeUnknown */ && receipt.length) {
+        throw new OutcomeUnknownError(void 0, receipt.toString("utf8"));
+      }
       checkCode(code);
     });
   }
   batchJsonRaw(request2) {
-    return this.#invokeBuffer(this.#native.dbBatchJson, jsonSlice(request2));
+    return this.#run(async (handle) => {
+      const out = newBufferOut();
+      const receiptOut = newBufferOut();
+      const code = await callAsync(
+        this.#native.dbBatchJsonWithReceipt,
+        handle,
+        jsonSlice(request2),
+        out,
+        receiptOut
+      );
+      const receipt = takeBuffer(this.#native, receiptOut);
+      if (code === 7 /* OutcomeUnknown */ && receipt.length) {
+        takeBuffer(this.#native, out);
+        throw new OutcomeUnknownError(void 0, receipt.toString("utf8"));
+      }
+      checkCode(code);
+      return takeBuffer(this.#native, out);
+    });
   }
   async batchJson(request2) {
     return parseJson(await this.batchJsonRaw(request2));
@@ -1730,6 +1860,32 @@ var Database = class _Database {
       return out[0];
     });
   }
+  /**
+   * Resolves an outcome receipt (`SqlError.outcomeReceipt` or
+   * `OutcomeUnknownError.outcomeReceipt`) on any handle for the same
+   * database. Rejects with `StalledError` while the uncertain commit is not
+   * reconciled yet: retry on a Lite database; for a directory database,
+   * close the issuing handle and reopen first.
+   */
+  outcomeReceiptStatus(receipt) {
+    return this.#run(async (handle) => {
+      const out = [0];
+      const code = await callAsync(
+        this.#native.dbOutcomeReceiptStatus,
+        handle,
+        stringSlice(receipt),
+        out
+      );
+      checkCode(code);
+      if (out[0] === OUTCOME_RECEIPT_APPLIED) return "applied";
+      if (out[0] === OUTCOME_RECEIPT_NOT_APPLIED) return "not_applied";
+      throw new InternalError(`unexpected outcome receipt status ${out[0]}`);
+    });
+  }
+  /** Removes a resolved receipt's durable marker; afterwards it cannot be resolved. */
+  forgetOutcomeReceipt(receipt) {
+    return this.#invokeCode(this.#native.dbOutcomeReceiptForget, stringSlice(receipt));
+  }
   commitVersion(txnId) {
     return this.#run(async (handle) => {
       const id = txnIdBytes(txnId);
@@ -2162,19 +2318,13 @@ var Inference = class _Inference {
   async extract(request2) {
     return parseJson(await this.extractRaw(request2));
   }
-  /** OCR. */
+  /** Read images, documents, or audio. */
   readRaw(request2) {
     return this.#invokeJson(this.#native.inferenceReadJson, request2);
   }
   async read(request2) {
     return parseJson(await this.readRaw(request2));
   }
-  transcribeRaw(request2) {
-    return this.#invokeJson(this.#native.inferenceTranscribeJson, request2);
-  }
-  async transcribe(request2) {
-    return parseJson(await this.transcribeRaw(request2));
-  }
   /** The installed models, as returned by GET /ai/v1/models. */
   listModelsRaw() {
     return this.#run(async (handle) => {
@@ -2451,6 +2601,7 @@ var Connection = class _Connection {
   Database,
   ErrorCode,
   GraphDirection,
+  GraphError,
   Inference,
   InferenceMode,
   IntentConflictError,