quiverdb 0.6.2 → 0.9.2

package/src/database.ts

@@ -0,0 +1,171 @@
+import type { CsvOptions } from "./csv.ts";
+import { check, QuiverError } from "./errors.ts";
+import { allocPtrOut, makeDefaultOptions, readPtrOut, toCString } from "./ffi-helpers.ts";
+import type { NativePointer } from "./loader.ts";
+import { getSymbols } from "./loader.ts";
+import type { GroupMetadata, ScalarMetadata } from "./metadata.ts";
+import type { TimeSeriesData } from "./time-series.ts";
+import type { ElementData, QueryParam } from "./types.ts";
+
+export class Database {
+  private _ptr: NativePointer;
+  private _closed = false;
+
+  private constructor(nativePtr: NativePointer) {
+    this._ptr = nativePtr;
+  }
+
+  static fromSchema(dbPath: string, schemaPath: string): Database {
+    const lib = getSymbols();
+    const options = makeDefaultOptions();
+    const outDb = allocPtrOut();
+    const dbPathBuf = toCString(dbPath);
+    const schemaPathBuf = toCString(schemaPath);
+
+    check(
+      lib.quiver_database_from_schema(dbPathBuf.buf, schemaPathBuf.buf, options.buf, outDb.ptr),
+    );
+
+    return new Database(readPtrOut(outDb));
+  }
+
+  static fromMigrations(dbPath: string, migrationsPath: string): Database {
+    const lib = getSymbols();
+    const options = makeDefaultOptions();
+    const outDb = allocPtrOut();
+    const dbPathBuf = toCString(dbPath);
+    const migrPathBuf = toCString(migrationsPath);
+
+    check(
+      lib.quiver_database_from_migrations(dbPathBuf.buf, migrPathBuf.buf, options.buf, outDb.ptr),
+    );
+
+    return new Database(readPtrOut(outDb));
+  }
+
+  static open(dbPath: string): Database {
+    const lib = getSymbols();
+    const options = makeDefaultOptions();
+    const outDb = allocPtrOut();
+    const dbPathBuf = toCString(dbPath);
+
+    check(lib.quiver_database_open(dbPathBuf.buf, options.buf, outDb.ptr));
+
+    return new Database(readPtrOut(outDb));
+  }
+
+  close(): void {
+    if (this._closed) return;
+    const lib = getSymbols();
+    check(lib.quiver_database_close(this._ptr));
+    this._closed = true;
+  }
+
+  private ensureOpen(): void {
+    if (this._closed) {
+      throw new QuiverError("Database is closed");
+    }
+  }
+
+  /** @internal */
+  get _handle(): NativePointer {
+    this.ensureOpen();
+    return this._ptr;
+  }
+
+  // --- Element CRUD (implemented in create.ts) ---
+  declare createElement: (collection: string, data: ElementData) => number;
+  declare updateElement: (collection: string, id: number, data: ElementData) => void;
+  declare deleteElement: (collection: string, id: number) => void;
+
+  // --- Reads (implemented in read.ts) ---
+  declare readScalarIntegers: (collection: string, attribute: string) => number[];
+  declare readScalarFloats: (collection: string, attribute: string) => number[];
+  declare readScalarStrings: (collection: string, attribute: string) => string[];
+  declare readScalarIntegerById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => number | null;
+  declare readScalarFloatById: (collection: string, attribute: string, id: number) => number | null;
+  declare readScalarStringById: (
+    collection: string,
+    attribute: string,
+    id: number,
+  ) => string | null;
+  declare readElementIds: (collection: string) => number[];
+  declare readVectorIntegers: (collection: string, attribute: string) => number[][];
+  declare readVectorFloats: (collection: string, attribute: string) => number[][];
+  declare readVectorStrings: (collection: string, attribute: string) => string[][];
+  declare readVectorIntegersById: (collection: string, attribute: string, id: number) => number[];
+  declare readVectorFloatsById: (collection: string, attribute: string, id: number) => number[];
+  declare readVectorStringsById: (collection: string, attribute: string, id: number) => string[];
+  declare readSetIntegers: (collection: string, attribute: string) => number[][];
+  declare readSetFloats: (collection: string, attribute: string) => number[][];
+  declare readSetStrings: (collection: string, attribute: string) => string[][];
+  declare readSetIntegersById: (collection: string, attribute: string, id: number) => number[];
+  declare readSetFloatsById: (collection: string, attribute: string, id: number) => number[];
+  declare readSetStringsById: (collection: string, attribute: string, id: number) => string[];
+
+  // --- Queries (implemented in query.ts) ---
+  declare queryString: (sql: string, parameters?: QueryParam[]) => string | null;
+  declare queryInteger: (sql: string, parameters?: QueryParam[]) => number | null;
+  declare queryFloat: (sql: string, parameters?: QueryParam[]) => number | null;
+
+  // --- Transactions (implemented in transaction.ts) ---
+  declare beginTransaction: () => void;
+  declare commit: () => void;
+  declare rollback: () => void;
+  declare inTransaction: () => boolean;
+
+  // --- Metadata (implemented in metadata.ts) ---
+  declare getScalarMetadata: (collection: string, attribute: string) => ScalarMetadata;
+  declare getVectorMetadata: (collection: string, groupName: string) => GroupMetadata;
+  declare getSetMetadata: (collection: string, groupName: string) => GroupMetadata;
+  declare getTimeSeriesMetadata: (collection: string, groupName: string) => GroupMetadata;
+  declare listScalarAttributes: (collection: string) => ScalarMetadata[];
+  declare listVectorGroups: (collection: string) => GroupMetadata[];
+  declare listSetGroups: (collection: string) => GroupMetadata[];
+  declare listTimeSeriesGroups: (collection: string) => GroupMetadata[];
+
+  // --- Time series (implemented in time-series.ts) ---
+  declare readTimeSeriesGroup: (collection: string, group: string, id: number) => TimeSeriesData;
+  declare updateTimeSeriesGroup: (
+    collection: string,
+    group: string,
+    id: number,
+    data: TimeSeriesData,
+  ) => void;
+  declare hasTimeSeriesFiles: (collection: string) => boolean;
+  declare listTimeSeriesFilesColumns: (collection: string) => string[];
+  declare readTimeSeriesFiles: (collection: string) => Record<string, string | null>;
+  declare updateTimeSeriesFiles: (collection: string, data: Record<string, string | null>) => void;
+
+  // --- CSV (implemented in csv.ts) ---
+  declare exportCsv: (
+    collection: string,
+    group: string,
+    filePath: string,
+    options?: CsvOptions,
+  ) => void;
+  declare importCsv: (
+    collection: string,
+    group: string,
+    filePath: string,
+    options?: CsvOptions,
+  ) => void;
+
+  // --- Introspection (implemented in introspection.ts) ---
+  declare isHealthy: () => boolean;
+  declare currentVersion: () => number;
+  declare path: () => string;
+  declare describe: () => void;
+
+  // --- Composite helpers (implemented in composites.ts) ---
+  declare readScalarsById: (
+    collection: string,
+    id: number,
+  ) => Record<string, number | string | null>;
+  declare readVectorsById: (collection: string, id: number) => Record<string, number[] | string[]>;
+  declare readSetsById: (collection: string, id: number) => Record<string, number[] | string[]>;
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+import { CString } from "bun:ffi";
+import { getSymbols } from "./loader.ts";
+
+export class QuiverError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "QuiverError";
+  }
+}
+
+export function check(err: number): void {
+  if (err !== 0) {
+    const lib = getSymbols();
+    const ptr = lib.quiver_get_last_error();
+    if (ptr) {
+      const detail = new CString(ptr).toString();
+      throw new QuiverError(detail);
+    }
+    throw new QuiverError("Unknown error");
+  }
+}

package/src/ffi-helpers.ts

@@ -0,0 +1,157 @@
+import { CString, type Pointer, ptr, read, toArrayBuffer } from "bun:ffi";
+import type { Allocation } from "./types.ts";
+
+const encoder = new TextEncoder();
+
+/**
+ * Construct the 8-byte quiver_database_options_t struct as an Allocation.
+ * Layout: offset 0 = int32 read_only (default 0), offset 4 = int32 console_level (default 1 = QUIVER_LOG_INFO).
+ */
+export function makeDefaultOptions(): Allocation {
+  const buf = new Uint8Array(8);
+  const dv = new DataView(buf.buffer);
+  dv.setInt32(0, 0, true); // read_only = false
+  dv.setInt32(4, 1, true); // console_level = QUIVER_LOG_INFO
+  return { ptr: ptr(buf), buf };
+}
+
+/** Allocate an 8-byte buffer for a pointer out-parameter. */
+export function allocPtrOut(): Allocation {
+  const buf = new Uint8Array(8);
+  return { ptr: ptr(buf), buf };
+}
+
+/** Read a pointer from an out-parameter buffer. */
+export function readPtrOut(alloc: Allocation): Pointer | null {
+  const dv = new DataView(alloc.buf.buffer);
+  const raw = dv.getBigUint64(0, true);
+  return raw === 0n ? null : (Number(raw) as Pointer);
+}
+
+/** Allocate an 8-byte buffer for a uint64 out-parameter. */
+export function allocUint64Out(): Allocation {
+  const buf = new Uint8Array(8);
+  return { ptr: ptr(buf), buf };
+}
+
+/** Read a uint64 value from an out-parameter buffer. */
+export function readUint64Out(alloc: Allocation): number {
+  const dv = new DataView(alloc.buf.buffer);
+  return Number(dv.getBigUint64(0, true));
+}
+
+/**
+ * Read a null-terminated C string from a pointer stored in an out-parameter buffer.
+ * Decodes the char* pointer via readPtrOut, then reads the C string with CString.
+ */
+export function decodeStringFromBuf(alloc: Allocation): string {
+  const p = readPtrOut(alloc);
+  if (!p) return "";
+  return new CString(p).toString();
+}
+
+/** Read an array of int64 values from a native pointer, returning JS numbers. */
+export function decodeInt64Array(p: Pointer | null, count: number): number[] {
+  if (!p || count === 0) return [];
+  const i64 = new BigInt64Array(toArrayBuffer(p, 0, count * 8));
+  return Array.from(i64, (v) => Number(v));
+}
+
+/** Read an array of float64 values from a native pointer. */
+export function decodeFloat64Array(p: Pointer | null, count: number): number[] {
+  if (!p || count === 0) return [];
+  const f64 = new Float64Array(toArrayBuffer(p, 0, count * 8));
+  return Array.from(f64);
+}
+
+/** Read an array of uint64 values from a native pointer, returning JS numbers. */
+export function decodeUint64Array(p: Pointer | null, count: number): number[] {
+  if (!p || count === 0) return [];
+  const u64 = new BigUint64Array(toArrayBuffer(p, 0, count * 8));
+  return Array.from(u64, (v) => Number(v));
+}
+
+/** Read an array of pointers from a native pointer using offset-based reading. */
+export function decodePtrArray(p: Pointer | null, count: number): (Pointer | null)[] {
+  if (!p || count === 0) return [];
+  const result: (Pointer | null)[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const v = read.ptr(p, i * 8);
+    result[i] = v === 0 ? null : (v as Pointer);
+  }
+  return result;
+}
+
+/** Read an array of C strings from a char** pointer. */
+export function decodeStringArray(p: Pointer | null, count: number): string[] {
+  if (!p || count === 0) return [];
+  const result: string[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const strPtr = read.ptr(p, i * 8);
+    result[i] = strPtr === 0 ? "" : new CString(strPtr as Pointer).toString();
+  }
+  return result;
+}
+
+/** Encode a JS string as a null-terminated C string buffer. */
+export function toCString(str: string): Allocation {
+  const encoded = encoder.encode(str + "\0");
+  const buf = new Uint8Array(encoded.length);
+  buf.set(encoded);
+  return { ptr: ptr(buf), buf };
+}
+
+/** Allocate native memory for an array of int64 values. */
+export function allocNativeInt64(values: number[]): Allocation {
+  const buf = new Uint8Array(values.length * 8);
+  const dv = new DataView(buf.buffer);
+  for (let i = 0; i < values.length; i++) {
+    dv.setBigInt64(i * 8, BigInt(values[i]), true);
+  }
+  return { ptr: ptr(buf), buf };
+}
+
+/** Allocate native memory for an array of float64 values. */
+export function allocNativeFloat64(values: number[]): Allocation {
+  const buf = new Uint8Array(values.length * 8);
+  const dv = new DataView(buf.buffer);
+  for (let i = 0; i < values.length; i++) {
+    dv.setFloat64(i * 8, values[i], true);
+  }
+  return { ptr: ptr(buf), buf };
+}
+
+/**
+ * Build a native pointer table from an array of native pointers.
+ * The returned allocation contains an array of void* addresses.
+ */
+export function allocNativePtrTable(ptrs: (Pointer | null)[]): Allocation {
+  const buf = new Uint8Array(ptrs.length * 8);
+  const dv = new DataView(buf.buffer);
+  for (let i = 0; i < ptrs.length; i++) {
+    const addr = ptrs[i] ? BigInt(ptrs[i] as number) : 0n;
+    dv.setBigUint64(i * 8, addr, true);
+  }
+  return { ptr: ptr(buf), buf };
+}
+
+/** Allocate a native string (null-terminated) and return its allocation. */
+export function allocNativeString(str: string): Allocation {
+  const buf = encoder.encode(str + "\0");
+  return { ptr: ptr(buf), buf };
+}
+
+/** Build a native string pointer table (const char* const*) from an array of strings. */
+export function allocNativeStringArray(strings: string[]): {
+  table: Allocation;
+  keepalive: Allocation[];
+} {
+  const strAllocs = strings.map((s) => allocNativeString(s));
+  const table = allocNativePtrTable(strAllocs.map((a) => a.ptr));
+  return { table, keepalive: strAllocs };
+}
+
+/** Get the native address of a pointer as BigInt. */
+export function nativeAddress(p: Pointer | null): bigint {
+  return p ? BigInt(p as number) : 0n;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+import "./create.ts";
+import "./read.ts";
+import "./query.ts";
+import "./transaction.ts";
+import "./metadata.ts";
+import "./time-series.ts";
+import "./csv.ts";
+import "./introspection.ts";
+import "./composites.ts";
+
+export type { CsvOptions } from "./csv.ts";
+export { Database } from "./database.ts";
+export { QuiverError } from "./errors.ts";
+export { LuaRunner } from "./lua-runner.ts";
+export type { GroupMetadata, ScalarMetadata } from "./metadata.ts";
+export type { TimeSeriesData } from "./time-series.ts";
+export type { ArrayValue, ElementData, QueryParam, ScalarValue, Value } from "./types.ts";

package/src/introspection.ts

@@ -0,0 +1,33 @@
+import { ptr } from "bun:ffi";
+import { Database } from "./database.ts";
+import { check } from "./errors.ts";
+import { allocPtrOut, decodeStringFromBuf, toCString } from "./ffi-helpers.ts";
+import { getSymbols } from "./loader.ts";
+
+Database.prototype.isHealthy = function (this: Database): boolean {
+  const lib = getSymbols();
+  const outBuf = new Uint8Array(4);
+  const outPtr = ptr(outBuf);
+  check(lib.quiver_database_is_healthy(this._handle, outPtr));
+  return new DataView(outBuf.buffer).getInt32(0, true) !== 0;
+};
+
+Database.prototype.currentVersion = function (this: Database): number {
+  const lib = getSymbols();
+  const outBuf = new Uint8Array(8);
+  const outPtr = ptr(outBuf);
+  check(lib.quiver_database_current_version(this._handle, outPtr));
+  return Number(new DataView(outBuf.buffer).getBigInt64(0, true));
+};
+
+Database.prototype.path = function (this: Database): string {
+  const lib = getSymbols();
+  const outPath = allocPtrOut();
+  check(lib.quiver_database_path(this._handle, outPath.ptr));
+  return decodeStringFromBuf(outPath);
+};
+
+Database.prototype.describe = function (this: Database): void {
+  const lib = getSymbols();
+  check(lib.quiver_database_describe(this._handle));
+};

package/src/loader.ts

@@ -0,0 +1,285 @@
+import { dlopen, type Library, type Pointer, suffix } from "bun:ffi";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { QuiverError } from "./errors.ts";
+
+// Bun FFI type shorthand constants. Deno's "buffer" parameter type (pass a
+// TypedArray, auto-converted to a pointer) has no Bun equivalent -- Bun rejects
+// `FFIType.buffer` as an argument ABI type -- so buffer args use "pointer";
+// Bun accepts a TypedArray for a pointer argument and pins it for the call.
+const P = "pointer" as const;
+const BUF = "pointer" as const;
+const I32 = "i32" as const;
+const I64 = "i64" as const;
+const USIZE = "usize" as const;
+const F64 = "f64" as const;
+const V = "void" as const;
+
+// Platform constants. `suffix` from bun:ffi is the platform-correct shared
+// library extension ("dll" | "dylib" | "so").
+const EXT = suffix;
+const C_API_LIB = `libquiver_c.${EXT}`;
+
+// Opaque pointer type for native handles.
+export type NativePointer = Pointer | null;
+
+// ---------------------------------------------------------------------------
+// Symbol definitions grouped by C API domain
+// ---------------------------------------------------------------------------
+
+const lifecycleSymbols = {
+  quiver_version: { args: [], returns: P },
+  quiver_get_last_error: { args: [], returns: P },
+  quiver_clear_last_error: { args: [], returns: V },
+  // quiver_database_options_default is intentionally omitted: it returns a
+  // struct by value, which Bun FFI does not support (oven-sh/bun#6139). It was
+  // never called -- makeDefaultOptions() in ffi-helpers.ts builds the options
+  // struct in JS.
+  quiver_database_from_schema: { args: [BUF, BUF, BUF, P], returns: I32 },
+  quiver_database_from_migrations: { args: [BUF, BUF, BUF, P], returns: I32 },
+  quiver_database_open: { args: [BUF, BUF, P], returns: I32 },
+  quiver_database_close: { args: [P], returns: I32 },
+  quiver_database_is_healthy: { args: [P, P], returns: I32 },
+  quiver_database_path: { args: [P, P], returns: I32 },
+  quiver_database_current_version: { args: [P, P], returns: I32 },
+  quiver_database_describe: { args: [P], returns: I32 },
+} as const;
+
+const elementSymbols = {
+  quiver_element_create: { args: [P], returns: I32 },
+  quiver_element_destroy: { args: [P], returns: I32 },
+  quiver_element_set_integer: { args: [P, BUF, I64], returns: I32 },
+  quiver_element_set_float: { args: [P, BUF, F64], returns: I32 },
+  quiver_element_set_string: { args: [P, BUF, BUF], returns: I32 },
+  quiver_element_set_null: { args: [P, BUF], returns: I32 },
+  quiver_element_set_array_integer: { args: [P, BUF, P, I32], returns: I32 },
+  quiver_element_set_array_float: { args: [P, BUF, P, I32], returns: I32 },
+  quiver_element_set_array_string: { args: [P, BUF, P, I32], returns: I32 },
+} as const;
+
+const crudSymbols = {
+  quiver_database_create_element: { args: [P, BUF, P, P], returns: I32 },
+  quiver_database_update_element: { args: [P, BUF, I64, P], returns: I32 },
+  quiver_database_delete_element: { args: [P, BUF, I64], returns: I32 },
+} as const;
+
+const readSymbols = {
+  quiver_database_read_scalar_integers: { args: [P, BUF, BUF, P, P], returns: I32 },
+  quiver_database_read_scalar_floats: { args: [P, BUF, BUF, P, P], returns: I32 },
+  quiver_database_read_scalar_strings: { args: [P, BUF, BUF, P, P], returns: I32 },
+  quiver_database_read_scalar_integer_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_scalar_float_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_scalar_string_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_vector_integers: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_vector_floats: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_vector_strings: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_set_integers: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_set_floats: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_set_strings: { args: [P, BUF, BUF, P, P, P], returns: I32 },
+  quiver_database_read_vector_integers_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_vector_floats_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_vector_strings_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_set_integers_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_set_floats_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_set_strings_by_id: { args: [P, BUF, BUF, I64, P, P], returns: I32 },
+  quiver_database_read_element_ids: { args: [P, BUF, P, P], returns: I32 },
+} as const;
+
+const querySymbols = {
+  quiver_database_query_string: { args: [P, BUF, P, P], returns: I32 },
+  quiver_database_query_integer: { args: [P, BUF, P, P], returns: I32 },
+  quiver_database_query_float: { args: [P, BUF, P, P], returns: I32 },
+  quiver_database_query_string_params: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
+  quiver_database_query_integer_params: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
+  quiver_database_query_float_params: { args: [P, BUF, P, P, USIZE, P, P], returns: I32 },
+} as const;
+
+const transactionSymbols = {
+  quiver_database_begin_transaction: { args: [P], returns: I32 },
+  quiver_database_commit: { args: [P], returns: I32 },
+  quiver_database_rollback: { args: [P], returns: I32 },
+  quiver_database_in_transaction: { args: [P, P], returns: I32 },
+} as const;
+
+const metadataSymbols = {
+  quiver_database_get_scalar_metadata: { args: [P, BUF, BUF, P], returns: I32 },
+  quiver_database_get_vector_metadata: { args: [P, BUF, BUF, P], returns: I32 },
+  quiver_database_get_set_metadata: { args: [P, BUF, BUF, P], returns: I32 },
+  quiver_database_get_time_series_metadata: { args: [P, BUF, BUF, P], returns: I32 },
+  quiver_database_free_scalar_metadata: { args: [P], returns: I32 },
+  quiver_database_free_group_metadata: { args: [P], returns: I32 },
+  quiver_database_list_scalar_attributes: { args: [P, BUF, P, P], returns: I32 },
+  quiver_database_list_vector_groups: { args: [P, BUF, P, P], returns: I32 },
+  quiver_database_list_set_groups: { args: [P, BUF, P, P], returns: I32 },
+  quiver_database_list_time_series_groups: { args: [P, BUF, P, P], returns: I32 },
+} as const;
+
+const timeSeriesSymbols = {
+  quiver_database_read_time_series_group: { args: [P, BUF, BUF, I64, P, P, P, P, P], returns: I32 },
+  quiver_database_update_time_series_group: {
+    args: [P, BUF, BUF, I64, P, P, P, USIZE, USIZE],
+    returns: I32,
+  },
+  quiver_database_free_time_series_data: { args: [P, P, P, USIZE, USIZE], returns: I32 },
+  quiver_database_has_time_series_files: { args: [P, BUF, P], returns: I32 },
+  quiver_database_list_time_series_files_columns: { args: [P, BUF, P, P], returns: I32 },
+  quiver_database_read_time_series_files: { args: [P, BUF, P, P, P], returns: I32 },
+  quiver_database_update_time_series_files: { args: [P, BUF, P, P, USIZE], returns: I32 },
+  quiver_database_free_time_series_files: { args: [P, P, USIZE], returns: I32 },
+} as const;
+
+const csvSymbols = {
+  quiver_database_export_csv: { args: [P, BUF, BUF, BUF, P], returns: I32 },
+  quiver_database_import_csv: { args: [P, BUF, BUF, BUF, P], returns: I32 },
+} as const;
+
+const freeSymbols = {
+  quiver_database_free_integer_array: { args: [P], returns: I32 },
+  quiver_database_free_float_array: { args: [P], returns: I32 },
+  quiver_database_free_string_array: { args: [P, USIZE], returns: I32 },
+  quiver_database_free_string: { args: [P], returns: I32 },
+  quiver_database_free_integer_vectors: { args: [P, P, USIZE], returns: I32 },
+  quiver_database_free_float_vectors: { args: [P, P, USIZE], returns: I32 },
+  quiver_database_free_string_vectors: { args: [P, P, USIZE], returns: I32 },
+  quiver_database_free_scalar_metadata_array: { args: [P, USIZE], returns: I32 },
+  quiver_database_free_group_metadata_array: { args: [P, USIZE], returns: I32 },
+} as const;
+
+const luaSymbols = {
+  quiver_lua_runner_new: { args: [P, P], returns: I32 },
+  quiver_lua_runner_free: { args: [P], returns: I32 },
+  quiver_lua_runner_run: { args: [P, BUF], returns: I32 },
+  quiver_lua_runner_get_error: { args: [P, P], returns: I32 },
+} as const;
+
+// Combined symbol map for dlopen.
+const allSymbols = {
+  ...lifecycleSymbols,
+  ...elementSymbols,
+  ...crudSymbols,
+  ...readSymbols,
+  ...querySymbols,
+  ...transactionSymbols,
+  ...metadataSymbols,
+  ...timeSeriesSymbols,
+  ...csvSymbols,
+  ...freeSymbols,
+  ...luaSymbols,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Library search and loading
+// ---------------------------------------------------------------------------
+
+// `import.meta.dir` is the absolute directory of this module on disk.
+const __dirname: string = import.meta.dir;
+
+// Map Bun's process.platform/arch onto the `libs/{os}-{arch}/` directory names
+// used by the bundled native libraries (e.g. "windows-x86_64", "linux-x86_64").
+const OS_NAMES: Record<string, string> = { win32: "windows", darwin: "darwin", linux: "linux" };
+const ARCH_NAMES: Record<string, string> = { x64: "x86_64", arm64: "aarch64" };
+const osName = OS_NAMES[process.platform] ?? process.platform;
+const archName = ARCH_NAMES[process.arch] ?? process.arch;
+const platformKey = `${osName}-${archName}`;
+const isWindows = process.platform === "win32";
+
+function getBundledLibDir(): string | null {
+  const libDir = join(__dirname, "..", "libs", platformKey);
+  if (existsSync(join(libDir, C_API_LIB))) {
+    return libDir;
+  }
+  return null;
+}
+
+function getSearchPaths(): string[] {
+  const paths: string[] = [];
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "build", "bin");
+    if (existsSync(join(candidate, C_API_LIB))) {
+      paths.push(candidate);
+    }
+    dir = dirname(dir);
+  }
+  return paths;
+}
+
+type QuiverLib = Library<typeof allSymbols>;
+
+// On Windows, libquiver_c.dll depends on libquiver.dll (the C++ core). The OS
+// loader resolves that sibling dependency via PATH, so put the library's own
+// directory on PATH before loading. (Unlike Deno, Bun's dlopen cannot preload
+// the core lib directly -- it rejects an empty symbol map.)
+function ensureCoreOnPath(dir: string): void {
+  if (!isWindows) return;
+  const current = process.env.PATH ?? "";
+  if (!current.split(";").includes(dir)) {
+    process.env.PATH = `${dir};${current}`;
+  }
+}
+
+function openLibrary(dir: string): QuiverLib {
+  ensureCoreOnPath(dir);
+  return dlopen(join(dir, C_API_LIB), allSymbols);
+}
+
+function initLibrary(): QuiverLib {
+  let lastError: unknown;
+
+  // Tier 1: Bundled libs/{os}-{arch}/ next to the loader (npm install / dev install).
+  const bundledDir = getBundledLibDir();
+  if (bundledDir) {
+    try {
+      return openLibrary(bundledDir);
+    } catch (e) {
+      lastError = e; // Bundled libs found but failed to load -- fall through.
+    }
+  }
+
+  // Tier 2: Dev mode -- walk up directories looking for build/bin/.
+  for (const dir of getSearchPaths()) {
+    try {
+      return openLibrary(dir);
+    } catch (e) {
+      lastError = e; // Try next path.
+    }
+  }
+
+  // Tier 3: System PATH fallback -- the core lib is expected to be discoverable
+  // on PATH alongside the C API lib.
+  try {
+    return dlopen(C_API_LIB, allSymbols);
+  } catch (e) {
+    lastError = e; // Fall through to error.
+  }
+
+  const searched = [
+    join(__dirname, "..", "libs", platformKey),
+    ...getSearchPaths(),
+    "system PATH",
+  ].join(", ");
+  const detail = lastError instanceof Error ? `: ${lastError.message}` : "";
+  throw new QuiverError(
+    `Cannot load native library '${C_API_LIB}'. Searched: ${searched}${detail}`,
+  );
+}
+
+// Resolve the native library lazily on first use. Initializing eagerly at
+// module-evaluation time would run during the loader<->errors import cycle,
+// before `errors.ts` has declared `QuiverError` -- making the not-found throw
+// hit a temporal dead zone. Deferring to first call lets the module graph
+// settle first; the result is cached, so callers still get it synchronously.
+let _lib: QuiverLib | null = null;
+
+export function loadLibrary(): QuiverLib {
+  if (_lib === null) {
+    _lib = initLibrary();
+  }
+  return _lib;
+}
+
+export function getSymbols() {
+  return loadLibrary().symbols;
+}
+
+export type Symbols = ReturnType<typeof getSymbols>;