wavedb 0.1.8__py3-none-win_amd64.whl

wavedb/__init__.py

@@ -0,0 +1,36 @@
+"""WaveDB Python bindings."""
+
+from .config import WaveDBConfig, WaveDBEncryption
+from .database import WaveDB
+from .exceptions import (
+    EncryptionError,
+    GraphQLLayerError,
+    IOError_,
+    InvalidPathError,
+    NotFoundError,
+    WaveDBError,
+)
+from .graph_layer import GraphLayer, GraphQuery, GraphResult
+from .graphql_layer import GraphQLLayer, GraphQLError, GraphQLResult
+from .subtree import Subtree
+
+__version__ = "0.1.8"
+
+__all__ = [
+    "EncryptionError",
+    "GraphLayer",
+    "GraphQuery",
+    "GraphResult",
+    "GraphQLError",
+    "GraphQLLayer",
+    "GraphQLLayerError",
+    "GraphQLResult",
+    "IOError_",
+    "InvalidPathError",
+    "NotFoundError",
+    "Subtree",
+    "WaveDB",
+    "WaveDBError",
+    "WaveDBConfig",
+    "WaveDBEncryption",
+]

wavedb/_async.py

@@ -0,0 +1,314 @@
+"""Bridge between C promise_t callbacks and Python asyncio futures.
+
+The C library invokes promise callbacks on worker threads. We must not touch
+asyncio.Future from a foreign thread. Instead, the cffi callback schedules
+_deliver on the future's loop via loop.call_soon_threadsafe.
+"""
+from __future__ import annotations
+
+import asyncio
+import itertools
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from ._errors import map_error
+from ._native import ffi, lib, libc
+from .exceptions import WaveDBError
+
+
+_log = logging.getLogger("wavedb.async")
+
+
+def decode_identifier_payload(payload) -> "bytes | None":
+    """Decode the identifier_t* payload from database_get_raw /
+    database_subtree_get_raw.
+
+    Payload contract (verified against src/Database/database.c):
+      - Hit: identifier_t* with count=1, yield=1 (CONSUME'd by _database_get
+        before promise_resolve).
+      - Miss: NULL.
+
+    Decoding sequence:
+      1. identifier_get_data_copy -> malloc'd uint8_t* (freed with
+         database_raw_value_free).
+      2. Copy to Python bytes.
+      3. refcounter_reference -> consumes the yield without incrementing
+         count.
+      4. identifier_destroy -> decrements count to 0 and frees the
+         identifier.
+
+    REFERENCE is mandatory before destroy: identifier_destroy calls
+    refcounter_dereference which consumes the yield first — without
+    REFERENCE, the identifier would be leaked.
+    """
+    if payload == ffi.NULL:
+        return None
+    ident = ffi.cast("identifier_t*", payload)
+    try:
+        len_out = ffi.new("size_t*")
+        data_ptr = lib.identifier_get_data_copy(ident, len_out)
+        if data_ptr == ffi.NULL:
+            return None
+        try:
+            return ffi.buffer(data_ptr, len_out[0])[:]
+        finally:
+            lib.database_raw_value_free(data_ptr)
+    finally:
+        lib.refcounter_reference(ffi.cast("void*", ident))
+        lib.identifier_destroy(ident)
+
+
+@dataclass
+class PendingOp:
+    op_id: int
+    future: asyncio.Future
+    loop: asyncio.AbstractEventLoop
+    op_type: str
+    op_id_ptr: Any  # cffi-allocated intptr_t*; bridge owns lifetime via _all_op_id_ptrs
+    cancelled: bool = False
+
+
+class AsyncBridge:
+    """Per-database bridge. One instance per WaveDB connection."""
+
+    # Class-level: op-ids grow monotonically across connections; only meaningful
+    # within a bridge's _pending dict.
+    _id_counter = itertools.count(1)
+
+    def __init__(self) -> None:
+        self._pending: dict[int, PendingOp] = {}
+        # The bridge owns op_id_ptr lifetime for safety across any calling
+        # pattern. Each entry is 8 bytes; the high-water mark of concurrent ops
+        # bounds the count. Never cleared — freed when the bridge is GC'd
+        # (after database_destroy has drained the work pool and all promises
+        # are destroyed).
+        self._all_op_id_ptrs: list[Any] = []
+        # Shared cffi callbacks (kept alive at instance scope; never GC'd while
+        # C holds a pointer).
+        self._resolve_cb = ffi.callback("void(void*, void*)")(self._on_resolve)
+        self._reject_cb = ffi.callback("void(void*, async_error_t*)")(self._on_reject)
+
+    # ---- public API ----
+
+    def new_future(self, op_type: str = "unknown") -> tuple[asyncio.Future, int, Any]:
+        """Create a future + op-id pair. Returns (future, op_id, op_id_ptr).
+
+        Caller passes op_id_ptr as promise_create's ctx. Caller must call
+        register_pending() with the same op_id before invoking the C async fn.
+        """
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future = loop.create_future()
+        op_id = next(self._id_counter)
+        op_id_ptr = ffi.new("intptr_t*", op_id)
+        self._all_op_id_ptrs.append(op_id_ptr)  # bridge owns the lifetime
+        return fut, op_id, op_id_ptr
+
+    def register_pending(self, fut: asyncio.Future, op_id: int, op_id_ptr: Any, op_type: str) -> None:
+        loop = fut.get_loop()
+        self._pending[op_id] = PendingOp(
+            op_id=op_id, future=fut, loop=loop, op_type=op_type, op_id_ptr=op_id_ptr,
+        )
+        # Store op_id on the future for O(1) unregister without a reverse dict.
+        fut._wavedb_op_id = op_id  # type: ignore[attr-defined]
+
+    def dispatch(
+        self,
+        c_fn,
+        handle_ptr: Any,
+        key_b: bytes,
+        delimiter_byte: bytes,
+        op_type: str,
+        err_msg: str,
+        *extra_args,
+    ) -> tuple[asyncio.Future, Any]:
+        """Create a promise, register the pending op, call the C async function.
+
+        `handle_ptr` is the C handle (database_t* or database_subtree_t*) that
+        the C function is invoked on. `extra_args` are passed between the
+        delimiter and the promise in the C function call (e.g.,
+        value_b, len(value_b) for put).
+
+        Returns (fut, promise). On error the promise is destroyed and the
+        mapped exception is raised. On success the caller must promise_destroy
+        in a finally block after awaiting the future.
+        """
+        fut, op_id, op_id_ptr = self.new_future(op_type)
+        self.register_pending(fut, op_id, op_id_ptr, op_type)
+        promise = lib.promise_create(self._resolve_cb, self._reject_cb, op_id_ptr)
+        if promise == ffi.NULL:
+            # Clean up the orphaned pending op so it doesn't sit in _pending
+            # with a future that will never resolve.
+            self._pending.pop(op_id, None)
+            raise WaveDBError("promise_create failed")
+        try:
+            rc = c_fn(
+                handle_ptr, ffi.from_buffer(key_b), len(key_b),
+                delimiter_byte, *extra_args, promise,
+            )
+            if rc != 0:
+                raise map_error(rc, err_msg)
+        except BaseException:
+            lib.promise_destroy(promise)
+            self._pending.pop(op_id, None)
+            raise
+        return fut, promise
+
+    @property
+    def resolve_cb(self):
+        return self._resolve_cb
+
+    @property
+    def reject_cb(self):
+        return self._reject_cb
+
+    def cancel_all_pending(self) -> None:
+        for op in list(self._pending.values()):
+            op.cancelled = True
+            if not op.future.done():
+                try:
+                    op.future.cancel()
+                except (RuntimeError, asyncio.InvalidStateError):
+                    pass
+        self._pending.clear()
+
+    # ---- test helpers (also usable for non-C scheduling) ----
+
+    def schedule_resolve(self, fut: asyncio.Future, payload: Any) -> None:
+        """Schedule a resolve on the future's loop. Used by tests."""
+        loop = fut.get_loop()
+        try:
+            loop.call_soon_threadsafe(self._deliver, fut, payload, False)
+        except RuntimeError:
+            # Loop closed between scheduling and delivery — drop silently.
+            _log.warning("schedule_resolve on closed loop; dropping result")
+
+    def schedule_reject(self, fut: asyncio.Future, exception: BaseException) -> None:
+        """Schedule a rejection on the future's loop. Used by tests."""
+        loop = fut.get_loop()
+        try:
+            loop.call_soon_threadsafe(self._set_exception, fut, exception)
+        except RuntimeError:
+            _log.warning("schedule_reject on closed loop; dropping exception")
+
+    # ---- internal: cffi callbacks (run on C worker threads) ----
+
+    def _on_resolve(self, ctx: Any, payload: Any) -> None:
+        # Runs on C worker thread. GIL is held (cffi callback acquires it).
+        if ctx == ffi.NULL:
+            return
+        op_id_ptr = ffi.cast("intptr_t*", ctx)
+        op_id = int(op_id_ptr[0])
+        op = self._pending.get(op_id)
+        if op is None:
+            # Op was cancelled before C fired the callback. Free the payload
+            # if non-NULL — get ops resolve with identifier_t* (leaks if not
+            # freed); put/del/batch always resolve with NULL (no-op).
+            if payload != ffi.NULL:
+                _free_get_payload_if_applicable(payload, "get")
+            return
+        op_type = op.op_type
+        try:
+            op.loop.call_soon_threadsafe(self._deliver, op.future, payload, False, op_type)
+        except RuntimeError:
+            _log.warning("_on_resolve on closed loop; dropping result for op %d", op_id)
+            # Loop is closed — free the payload if it's a get-type identifier.
+            _free_get_payload_if_applicable(payload, op_type)
+
+    def _on_reject(self, ctx: Any, error: Any) -> None:
+        if ctx == ffi.NULL:
+            if error != ffi.NULL:
+                lib.error_destroy(error)
+            return
+        op_id_ptr = ffi.cast("intptr_t*", ctx)
+        op_id = int(op_id_ptr[0])
+        op = self._pending.get(op_id)
+        # Extract message and destroy the error object now (it's refcounted by C
+        # but we don't keep a reference once we've read the string).
+        msg = ""
+        if error != ffi.NULL:
+            cmsg = lib.error_get_message(error)
+            if cmsg != ffi.NULL:
+                msg = ffi.string(cmsg).decode("utf-8", errors="replace")
+            # Enrich with C source location (file:function:line) for debugging
+            cfile = lib.error_get_file(error)
+            cfunc = lib.error_get_function(error)
+            line = lib.error_get_line(error)
+            if cfile != ffi.NULL and cfunc != ffi.NULL:
+                loc = f" ({ffi.string(cfile).decode('utf-8', errors='replace')}:{line} in {ffi.string(cfunc).decode('utf-8', errors='replace')})"
+                msg = f"{msg}{loc}"
+            lib.error_destroy(error)
+        if op is None:
+            return
+        try:
+            op.loop.call_soon_threadsafe(self._deliver_error, op.future, msg)
+        except RuntimeError:
+            _log.warning("_on_reject on closed loop; dropping error for op %d", op_id)
+
+    # ---- internal: loop-thread delivery ----
+
+    def _deliver(self, fut: asyncio.Future, payload: Any, loop_closed: bool = False, op_type: str = "unknown") -> None:
+        # Runs on the loop thread (or directly in tests with loop_closed=True).
+        # loop_closed is a test-only escape hatch; in production,
+        # call_soon_threadsafe raises RuntimeError on a closed loop before
+        # _deliver is invoked.
+        if loop_closed or fut.done():
+            # Cancelled/closed before delivery. Free the payload if it's a
+            # get-type op (identifier_t* with yield=1 from CONSUME). put/del/batch
+            # resolve with NULL, so there's nothing to free.
+            _free_get_payload_if_applicable(payload, op_type)
+            return
+        fut.set_result(payload)
+        self._unregister(fut)
+
+    def _deliver_error(self, fut: asyncio.Future, message: str) -> None:
+        if fut.done():
+            return
+        fut.set_exception(map_error(0, message))
+        self._unregister(fut)
+
+    def _set_exception(self, fut: asyncio.Future, exception: BaseException) -> None:
+        """Used by schedule_reject (test path) to set an arbitrary exception."""
+        if fut.done():
+            return
+        fut.set_exception(exception)
+        self._unregister(fut)
+
+    def _unregister(self, fut: asyncio.Future) -> None:
+        op_id = getattr(fut, '_wavedb_op_id', None)
+        if op_id is not None:
+            self._pending.pop(op_id, None)
+        # Do NOT free op_id_ptr — the bridge owns it via _all_op_id_ptrs
+        # (see I-1) and keeps it alive until database_destroy has drained.
+
+
+# Op types whose promise payload is an identifier_t* (CONSUME'd by _database_get).
+# These need refcounter_reference + identifier_destroy to free when the future
+# is cancelled before delivery. Batch resolves with malloc'd int* (the result
+# code) which must be freed with libc.free on cancellation.
+_GET_OP_TYPES = frozenset({"get", "st_get"})
+_BATCH_OP_TYPES = frozenset({"batch"})
+
+
+def _free_get_payload_if_applicable(payload: Any, op_type: str) -> None:
+    """Free a cancelled op payload (identifier_t* for get, int* for batch).
+
+    No-op for op types with NULL payloads. Safe to call from any thread
+    (cffi callbacks hold the GIL).
+    """
+    if payload == ffi.NULL:
+        return
+    if op_type in _GET_OP_TYPES:
+        try:
+            ident = ffi.cast("identifier_t*", payload)
+            lib.refcounter_reference(ffi.cast("void*", ident))
+            lib.identifier_destroy(ident)
+        except Exception:
+            _log.warning("failed to free cancelled get payload", exc_info=True)
+        return
+    if op_type in _BATCH_OP_TYPES:
+        try:
+            libc.free(payload)
+        except Exception:
+            _log.warning("failed to free cancelled batch payload", exc_info=True)
+        return

wavedb/_cffi_build.py

@@ -0,0 +1,269 @@
+"""Build-time cffi builder for compiled out-of-line mode.
+
+Defines all C API cdef declarations and provides a configure() function
+that setup.py calls with build-time parameters (library_dirs, rpath, etc.)
+before invoking ffibuilder.compile().
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from cffi import FFI
+
+
+ffibuilder = FFI()
+
+# Minimal C preamble for set_source — includes standard headers for the
+# types used in the cdef (uint8_t, size_t, etc.). Opaque struct typedefs
+# are generated by cffi from the cdef; no real WaveDB headers needed.
+# raw_op_t and raw_result_t are fully declared here (not in cdef) so cffi
+# uses this definition for field access without generating a conflicting one.
+_C_SOURCE = """
+#include <stdint.h>
+#include <stddef.h>
+
+/* Forward-declare ALL opaque types used in function signatures.
+   cffi generates the actual typedefs later in the file, but the
+   _cffi_d_ check functions at the top reference the type names
+   before the definitions appear. Forward-declaring here avoids
+   "unknown type name" errors. These must match the cdef exactly. */
+typedef struct refcounter_s refcounter_t;
+typedef struct database_s database_t;
+typedef struct database_config_s database_config_t;
+typedef struct encrypted_database_config_s encrypted_database_config_t;
+typedef struct promise_s promise_t;
+typedef struct async_error_s async_error_t;
+typedef struct database_iterator_s database_iterator_t;
+typedef struct path_s path_t;
+typedef struct identifier_s identifier_t;
+typedef struct database_subtree_s database_subtree_t;
+typedef struct graph_layer_config_s graph_layer_config_t;
+typedef struct graph_layer_s graph_layer_t;
+typedef struct graph_query_s graph_query_t;
+typedef struct graph_result_s graph_result_t;
+typedef struct graphql_layer_config_s graphql_layer_config_t;
+typedef struct graphql_layer_s graphql_layer_t;
+typedef struct graphql_result_s graphql_result_t;
+
+/* Fully-declared structs (fields accessible from Python).
+   cffi uses this definition for field access via the `...` form in cdef. */
+typedef struct { const char* key; size_t key_len; const uint8_t* value; size_t value_len; int type; } raw_op_t;
+typedef struct { char* key; size_t key_len; uint8_t* value; size_t value_len; } raw_result_t;
+"""
+
+# ---- Types ----
+# All WaveDB structs are declared opaque via forward declarations.
+# Works identically in API mode — cffi emits the typedef into the generated
+# C file; no real header required.
+ffibuilder.cdef("""
+typedef struct refcounter_s refcounter_t;
+typedef struct database_s database_t;
+typedef struct database_config_s database_config_t;
+typedef struct encrypted_database_config_s encrypted_database_config_t;
+typedef struct promise_s promise_t;
+typedef struct async_error_s async_error_t;
+typedef struct database_iterator_s database_iterator_t;
+typedef struct path_s path_t;
+typedef struct identifier_s identifier_t;
+typedef struct database_subtree_s database_subtree_t;
+typedef struct graph_layer_config_s graph_layer_config_t;
+typedef struct graph_layer_s graph_layer_t;
+typedef struct graph_query_s graph_query_t;
+typedef struct graph_result_s graph_result_t;
+typedef struct graphql_layer_config_s graphql_layer_config_t;
+typedef struct graphql_layer_s graphql_layer_t;
+typedef struct graphql_result_s graphql_result_t;
+
+typedef struct { ...; } raw_op_t;
+typedef struct { ...; } raw_result_t;
+""")
+
+ffibuilder.cdef("""
+uint8_t* identifier_get_data_copy(const identifier_t* id, size_t* out_len);
+void identifier_destroy(identifier_t* id);
+void* refcounter_reference(void* refcounter);
+""")
+
+ffibuilder.cdef("""
+/* unused in v1 — Python uses database_create_with_config */
+database_t* database_create(const char* location, size_t lru_memory_mb,
+    void* wal_config, uint8_t chunk_size, uint32_t btree_node_size,
+    uint8_t enable_persist, void* pool, void* wheel, int* error_code);
+database_t* database_create_with_config(const char* location,
+    database_config_t* config, int* error_code);
+database_t* database_create_encrypted(const char* location,
+    encrypted_database_config_t* config, int* error_code);
+void database_destroy(database_t* db);
+
+database_config_t* database_config_default(void);
+database_config_t* database_config_copy(const database_config_t* config);
+void database_config_destroy(database_config_t* config);
+void database_config_set_chunk_size(database_config_t*, uint8_t);
+void database_config_set_btree_node_size(database_config_t*, uint32_t);
+void database_config_set_enable_persist(database_config_t*, uint8_t);
+void database_config_set_lru_memory_mb(database_config_t*, size_t);
+void database_config_set_lru_shards(database_config_t*, uint16_t);
+void database_config_set_wal_sync_mode(database_config_t*, uint8_t);
+void database_config_set_wal_debounce_ms(database_config_t*, uint64_t);
+void database_config_set_worker_threads(database_config_t*, uint8_t);
+void database_config_set_sync_only(database_config_t*, uint8_t);
+
+encrypted_database_config_t* encrypted_database_config_default(void);
+void encrypted_database_config_destroy(encrypted_database_config_t*);
+void encrypted_database_config_set_type(encrypted_database_config_t*, int);
+void encrypted_database_config_set_symmetric_key(encrypted_database_config_t*, const uint8_t*, size_t);
+void encrypted_database_config_set_asymmetric_private_key(encrypted_database_config_t*, const uint8_t*, size_t);
+void encrypted_database_config_set_asymmetric_public_key(encrypted_database_config_t*, const uint8_t*, size_t);
+""")
+
+ffibuilder.cdef("""
+int database_put_sync_raw(database_t* db,
+    const char* key, size_t key_len, char delimiter,
+    const uint8_t* value, size_t value_len);
+int database_get_sync_raw(database_t* db,
+    const char* key, size_t key_len, char delimiter,
+    uint8_t** value_out, size_t* value_len_out);
+int database_delete_sync_raw(database_t* db,
+    const char* key, size_t key_len, char delimiter);
+void database_raw_value_free(uint8_t* value);
+int database_batch_sync_raw(database_t* db, char delimiter,
+    const raw_op_t* ops, size_t count);
+int database_scan_sync_raw(database_t* db,
+    const char* prefix, size_t prefix_len, char delimiter,
+    raw_result_t** results, size_t* count);
+int database_scan_range_sync_raw(database_t* db,
+    const char* start_prefix, size_t start_prefix_len,
+    const char* end_prefix, size_t end_prefix_len,
+    char delimiter,
+    raw_result_t** results, size_t* count);
+void database_raw_results_free(raw_result_t* results, size_t count);
+""")
+
+ffibuilder.cdef("""
+int database_put_raw(database_t* db,
+    const char* key, size_t key_len, char delimiter,
+    const uint8_t* value, size_t value_len, promise_t* promise);
+int database_get_raw(database_t* db,
+    const char* key, size_t key_len, char delimiter, promise_t* promise);
+int database_delete_raw(database_t* db,
+    const char* key, size_t key_len, char delimiter, promise_t* promise);
+int database_batch_raw(database_t* db, char delimiter,
+    const raw_op_t* ops, size_t count, promise_t* promise);
+""")
+
+ffibuilder.cdef("""
+typedef void (*promise_resolve_cb)(void* ctx, void* payload);
+typedef void (*promise_reject_cb)(void* ctx, async_error_t* error);
+promise_t* promise_create(promise_resolve_cb resolve, promise_reject_cb reject, void* ctx);
+void promise_destroy(promise_t* promise);
+void promise_resolve(promise_t* promise, void* payload);
+void promise_reject(promise_t* promise, async_error_t* error);
+const char* error_get_message(async_error_t* error);
+const char* error_get_file(async_error_t* error);
+const char* error_get_function(async_error_t* error);
+int error_get_line(async_error_t* error);
+void error_destroy(async_error_t* error);
+""")
+
+ffibuilder.cdef("""
+/* unused in v1 — Task 10 iterator uses database_scan_range_sync_raw (string-based) */
+database_iterator_t* database_scan_start(database_t* db,
+    path_t* start_path, path_t* end_path);
+int database_scan_next(database_iterator_t* iter,
+    path_t** out_path, identifier_t** out_value);
+void database_scan_end(database_iterator_t* iter);
+""")
+
+ffibuilder.cdef("""
+database_subtree_t* database_subtree_open(database_t* db,
+    const char* prefix, char delimiter);
+int database_subtree_delete_prefix(database_t* db,
+    const char* prefix, char delimiter);
+void database_subtree_close(database_subtree_t* subtree);
+int database_subtree_put_sync_raw(database_subtree_t* st,
+    const char* key, size_t key_len, char delimiter,
+    const uint8_t* value, size_t value_len);
+int database_subtree_get_sync_raw(database_subtree_t* st,
+    const char* key, size_t key_len, char delimiter,
+    uint8_t** value_out, size_t* value_len_out);
+int database_subtree_delete_sync_raw(database_subtree_t* st,
+    const char* key, size_t key_len, char delimiter);
+int database_subtree_put_raw(database_subtree_t* st,
+    const char* key, size_t key_len, char delimiter,
+    const uint8_t* value, size_t value_len, promise_t* promise);
+int database_subtree_get_raw(database_subtree_t* st,
+    const char* key, size_t key_len, char delimiter, promise_t* promise);
+int database_subtree_delete_raw(database_subtree_t* st,
+    const char* key, size_t key_len, char delimiter, promise_t* promise);
+""")
+
+ffibuilder.cdef("""
+graph_layer_t* graph_layer_create(const char* path,
+    graph_layer_config_t* config, database_subtree_t* subtree,
+    int* error_code);
+void graph_layer_destroy(graph_layer_t* layer);
+int graph_insert_sync(graph_layer_t* layer, const char* s, const char* p, const char* o);
+size_t graph_triple_expand_ops(graph_layer_t* layer,
+    const char* s, const char* p, const char* o,
+    int type, raw_op_t* out_ops, size_t max_ops);
+graph_query_t* graph_query_create(graph_layer_t* layer);
+void graph_query_destroy(graph_query_t* q);
+int graph_query_vertex(graph_query_t* q, const char* id);
+int graph_query_out(graph_query_t* q, const char* predicate);
+int graph_query_in(graph_query_t* q, const char* predicate);
+int graph_query_has(graph_query_t* q, const char* predicate, const char* value);
+int graph_query_intersect(graph_query_t* q, graph_query_t* left, graph_query_t* right);
+int graph_query_union(graph_query_t* q, graph_query_t* left, graph_query_t* right);
+int graph_query_limit(graph_query_t* q, size_t limit);
+graph_result_t* graph_query_execute_sync(graph_query_t* q);
+size_t graph_result_count(graph_result_t* r);
+const char* const* graph_result_vertices(graph_result_t* r);
+void graph_result_destroy(graph_result_t* r);
+""")
+
+ffibuilder.cdef("""
+graphql_layer_t* graphql_layer_create(const char* path,
+    const graphql_layer_config_t* config, database_subtree_t* subtree,
+    int* error_code);
+void graphql_layer_destroy(graphql_layer_t* layer);
+int graphql_schema_parse(graphql_layer_t* layer, const char* sdl, char** error_out);
+graphql_result_t* graphql_query_sync(graphql_layer_t* layer, const char* query);
+void graphql_result_destroy(graphql_result_t* r);
+const char* graphql_result_to_json(graphql_result_t* result);
+void free(void* ptr);
+""")
+
+
+def configure(library_dir: str, include_dirs: list[str] | None = None) -> None:
+    """Call set_source with build-time parameters.
+
+    setup.py calls this after the CMake build produces libwavedb.so in
+    library_dir. The rpath ensures the compiled extension finds the .so
+    at runtime relative to the package directory.
+    """
+    if sys.platform == "darwin":
+        rpath = "@loader_path/_lib"
+    elif sys.platform == "win32":
+        rpath = None  # Windows: no rpath; .dll is in the same dir
+    else:
+        rpath = "$ORIGIN/_lib"
+
+    extra_link_args = []
+    if rpath:
+        extra_link_args.append(f"-Wl,-rpath,{rpath}")
+
+    kwargs = dict(
+        libraries=["wavedb"],
+        library_dirs=[library_dir],
+        extra_link_args=extra_link_args,
+    )
+    if include_dirs:
+        kwargs["include_dirs"] = include_dirs
+
+    ffibuilder.set_source(
+        "wavedb._native_ext",
+        _C_SOURCE,
+        **kwargs,
+    )

wavedb/_errors.py

@@ -0,0 +1,49 @@
+"""Map C error codes and string markers to typed Python exceptions."""
+from __future__ import annotations
+
+from typing import Callable
+
+from .exceptions import (
+    EncryptionError,
+    IOError_,
+    InvalidPathError,
+    NotFoundError,
+    WaveDBError,
+)
+
+
+_DATABASE_ERR_ENCRYPTION_REQUIRED = -100
+_DATABASE_ERR_ENCRYPTION_KEY_INVALID = -101
+_DATABASE_ERR_ENCRYPTION_UNSUPPORTED = -102
+
+
+def map_error(code: int, message: str) -> WaveDBError:
+    msg = message or ""
+
+    if code == _DATABASE_ERR_ENCRYPTION_REQUIRED:
+        return EncryptionError(msg or "encryption required")
+    if code == _DATABASE_ERR_ENCRYPTION_KEY_INVALID:
+        return EncryptionError(msg or "invalid encryption key")
+    if code == _DATABASE_ERR_ENCRYPTION_UNSUPPORTED:
+        return EncryptionError(msg or "encryption unsupported")
+
+    # String markers below are a Python-side convention for surfacing error
+    # context; the C sync APIs return integer codes, not strings. Markers
+    # match what the Node.js C++ layer emits for parity.
+    upper = msg.upper()
+    if "NOT_FOUND" in upper or "KEY NOT FOUND" in upper:
+        return NotFoundError(msg)
+    if "INVALID_PATH" in upper or "INVALID PATH" in upper:
+        return InvalidPathError(msg)
+    if "IO_ERROR" in upper or "I/O ERROR" in upper or "DATABASE_CLOSED" in upper:
+        return IOError_(msg)
+    if "ENCRYPTION" in upper:
+        return EncryptionError(msg)
+
+    return WaveDBError(msg or f"WaveDB error (code {code})")
+
+
+def raise_on_error(code: int, message_factory: "Callable[[], str] | str") -> None:
+    """If code != 0, raise a mapped exception. message_factory is called only on error."""
+    if code != 0:
+        raise map_error(code, message_factory() if callable(message_factory) else str(message_factory))

wavedb/_lib/__init__.py

@@ -0,0 +1 @@
+"""Directory holding the bundled libwavedb shared library."""