keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/db/core/keys.js

@@ -88,7 +88,7 @@ export function splitKey(key, sep = ".") {
     const keyStr = t(keyBytes);
     const splitAt = keyStr.lastIndexOf(sepStr);
     if (splitAt <= 0 || splitAt + sepStr.length >= keyStr.length) {
-        throw new ValidationError(`Key must split into exactly 2 parts at rightmost separator`, { key: keyStr, separator: sepStr });
+        throw new ValidationError(`Key must split into exactly 2 parts at rightmost separator`);
     }
     return [
         b(keyStr.slice(0, splitAt)),
@@ -162,7 +162,7 @@ export function unsuffix(iokey, sep = ".") {
     const iokeyStr = t(iokeyBytes);
     const lastSepIndex = iokeyStr.lastIndexOf(sepStr);
     if (lastSepIndex === -1) {
-        throw new DatabaseKeyError(`No separator found in iokey`, { key: iokeyStr, separator: sepStr });
+        throw new DatabaseKeyError(`No separator found in iokey`);
     }
     const keyStr = iokeyStr.substring(0, lastSepIndex);
     const suffixStr = iokeyStr.substring(lastSepIndex + sepStr.length);

package/esm/keri/npm/src/db/core/lmdber.js

@@ -2,11 +2,9 @@
  * Core LMDB manager used by higher-level DB abstractions.
  */
 import * as dntShim from "../../_dnt.shims.js";
-import { b, bytesEqual, bytesHex, ResourceLimitError, t, toBytes } from "cesr-ts";
-import { versions } from "node:process";
-import { action } from "effection";
+import { b, bytesEqual, bytesHex, t, toBytes } from "cesr-ts";
+import { call, ensure } from "effection";
 import { open } from "lmdb";
-import * as lmdbBinding from "lmdb";
 import { startsWith } from "../../core/bytes.js";
 import { DatabaseKeyError, DatabaseNotOpenError, DatabaseOperationError } from "../../core/errors.js";
 import { consoleLogger } from "../../core/logger.js";
@@ -211,6 +209,10 @@ const DEFAULT_DB_VERSION = "1.0.0";
  *   `PathManager` lifecycle instead of inheriting KERIpy's exact structure
  */
 export class LMDBer {
+    /** Expose only a usable environment, never one whose shutdown has started or failed. */
+    get env() {
+        return this.closing ? null : this.root;
+    }
     constructor(options = {}, defaults) {
         Object.defineProperty(this, "pathManager", {
             enumerable: true,
@@ -218,12 +220,19 @@ export class LMDBer {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "env", {
+        Object.defineProperty(this, "root", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** A rejected close remains authoritative: the binding may have disabled only part of the handle. */
+        Object.defineProperty(this, "closing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         Object.defineProperty(this, "readonly", {
             enumerable: true,
             configurable: true,
@@ -249,6 +258,13 @@ export class LMDBer {
             writable: true,
             value: void 0
         });
+        /** Existing-store maintenance may neither create tables nor clear its target. */
+        Object.defineProperty(this, "existingOnly", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         this.defaults = { ...LMDBER_DEFAULTS, ...defaults };
         this.logger = options.logger ?? consoleLogger;
         this.configuredMapSize = options.mapSize;
@@ -266,7 +282,7 @@ export class LMDBer {
             perm: this.defaults.perm,
         };
         this.pathManager = new PathManager(options, pathDefaults);
-        this.env = null;
+        this.root = null;
         this.readonly = options.readonly || false;
     }
     /** Expose the resolved logical database name used for path derivation and temp dirs. */
@@ -281,6 +297,14 @@ export class LMDBer {
     get opened() {
         return this.pathManager.opened && this.env !== null;
     }
+    /** Inspect the pinned lmdb-js writer at the storage boundary, without exposing its native handle. */
+    get inWriteTransaction() {
+        const root = this.requireEnv();
+        if (!("env" in root) || !root.env || typeof root.env !== "object") {
+            throw new DatabaseOperationError("Unsupported LMDB writer inspection");
+        }
+        return "writeTxn" in root.env && root.env.writeTxn != null;
+    }
     /** Report whether this environment uses a temporary backing directory. */
     get temp() {
         return this.pathManager.temp;
@@ -297,29 +321,36 @@ export class LMDBer {
         return this.env;
     }
     /** Normalize low-level LMDB key-shape failures into one project-specific error type. */
-    formatDbKeyError(key, error) {
+    formatDbKeyError(error) {
         const message = error instanceof Error ? error.message : String(error);
-        return new DatabaseKeyError(`Key is empty, too big, or wrong size: ${message}`, {
-            key: Array.from(key),
-        });
-    }
-    /** Bridge async LMDB close into an Effection operation. */
-    *closeEnv(env) {
-        yield* action((resolve, reject) => {
-            env.close().then(() => resolve(undefined)).catch(reject);
-            return () => { };
-        });
-    }
-    /**
-     * Allow LMDB-js internal read-reset timers to flush before test/resource
-     * teardown completes. LMDB uses setTimeout(0/1) internally around read txn
-     * renewal/reset and deferred close paths.
-     */
-    *quiesceEnvTimers() {
-        yield* action((resolve) => {
-            const timeout = setTimeout(() => resolve(undefined), 1);
-            return () => clearTimeout(timeout);
-        });
+        return new DatabaseKeyError(`Key is empty, too big, or wrong size: ${message}`, { cause: error });
+    }
+    /** Join native shutdown even when the caller is cancelled; failed handles cannot be reused. */
+    *closeEnv() {
+        if (!this.closing && this.root) {
+            const root = this.root;
+            // lmdb-js disables reads/writes before completion. A rejection cannot prove
+            // whether the environment is usable or fully closed; retain it as failed.
+            this.closing = new Promise((resolve, reject) => {
+                // In 3.5.3 the callback runs after doClose, including outstanding reads.
+                // The returned Promise alone can resolve before that deferred branch.
+                const native = root;
+                native.close(resolve).catch(reject);
+            }).then(() => {
+                this.root = null;
+                this.pathManager.opened = false;
+            });
+        }
+        const pending = this.closing;
+        if (pending) {
+            yield* call(function* () {
+                // Register joining before the async leaf. Effection reports a failing
+                // ensure as destruction failure, including when its task is halted.
+                yield* ensure(() => call(() => pending));
+                yield* call(() => pending);
+            });
+            this.closing = null;
+        }
     }
     /**
      * Reopen the LMDB environment at the resolved path.
@@ -329,19 +360,9 @@ export class LMDBer {
      * and stamps the default version marker on newly-created writable envs.
      */
     *reopen(options = {}) {
+        yield* this.closeEnv();
         const readonly = options.readonly ?? this.readonly;
         this.readonly = readonly;
-        // Close existing database if open (prevents double-free when reopening)
-        if (this.env) {
-            try {
-                yield* this.closeEnv(this.env);
-            }
-            catch (error) {
-                // Ignore close errors (database might already be closed)
-                this.logger.warn(`Warning: Error closing existing LMDB environment: ${error}`);
-            }
-            this.env = null;
-        }
         // Reopen path manager (now an Effection operation)
         yield* this.pathManager.reopen(options);
         if (!this.pathManager.path) {
@@ -354,16 +375,42 @@ export class LMDBer {
         // For readonly mode, database files must exist
         if (readonly && !dbExists) {
             this.logger.error(`Cannot open readonly database: database files do not exist at ${dbPath}`);
-            this.env = null;
+            this.root = null;
             return false;
         }
-        // Prefer reopen-time option, then constructor option, then env, then default.
+        if (options.mapSize !== undefined)
+            this.configuredMapSize = options.mapSize;
+        this.existingOnly = false;
+        this.openEnvironment(dbPath, dbExists);
+        // KERIpy parity: stamp version metadata on newly-created DBs and temp DBs.
+        if (this.opened && !readonly && (!dbExists || this.temp)) {
+            this.setVer(DEFAULT_DB_VERSION);
+        }
+        return this.opened;
+    }
+    /**
+     * Open a resolved existing environment without path creation or version writes.
+     * All subsequent named-table bindings refuse creation, including writable ones.
+     */
+    *openExisting(path) {
+        if (this.root || this.closing || this.temp) {
+            throw new DatabaseOperationError("Existing-store opening requires a closed, persistent LMDBer");
+        }
+        const data = yield* this.pathManager.statFileOp(`${path}/data.mdb`);
+        if (!data.isFile) {
+            throw new DatabaseOperationError(`Existing database not found at ${path}`);
+        }
+        this.existingOnly = true;
+        this.openEnvironment(path, true);
+        this.pathManager.path = path;
+        this.pathManager.opened = true;
+    }
+    /** Open the native environment with the shared binary and map-size contract. */
+    openEnvironment(dbPath, dbExists) {
+        // Prefer the configured option, then env, then default.
         // When data.mdb already exists, raise to at least the stored map size so
         // KERIpy databases opened with KERI_BASER_MAP_SIZE=10GiB (etc.) do not abort
         // under an undersized lmdb-js virtual mapping.
-        if (options.mapSize !== undefined) {
-            this.configuredMapSize = options.mapSize;
-        }
         const dataMdbPath = dbExists ? `${dbPath}/data.mdb` : null;
         const effectiveMapSize = resolveLmdbMapSize({
             optionMapSize: this.configuredMapSize,
@@ -375,35 +422,27 @@ export class LMDBer {
         });
         const dbConfig = {
             path: dbPath, // Use directory path (Node.js lmdb should handle this)
+            noSubdir: false, // A dotted directory name must not select LMDB's single-file layout.
             maxDbs: this.defaults.maxNamedDBs,
             mapSize: effectiveMapSize,
-            readOnly: readonly,
+            readOnly: this.readonly,
             compression: false, // Disable compression for compatibility
             encoding: "binary", // to mimic KERIpy behavior
             keyEncoding: "binary", // to mimic KERIpy behavior
         };
-        this.logger.debug(`Opening LMDB at: ${dbPath} (readonly: ${readonly}, mapSize: ${effectiveMapSize})`);
+        this.logger.debug(`Opening LMDB at: ${dbPath} (readonly: ${this.readonly}, mapSize: ${effectiveMapSize})`);
         // Open LMDB environment
         // LMDB's open() will create data.mdb and lock.mdb if they don't exist
         try {
             // do sync because wrapping synchronous native operations in action() can cause
             // memory management issues with native bindings (double-free errors)
-            this.env = open(dbConfig);
+            this.root = open(dbConfig);
             this.logger.debug(`LMDB environment opened successfully`);
-            // KERIpy parity: stamp version metadata on newly-created DBs and temp DBs.
-            if (this.opened && !readonly && (!dbExists || this.temp)) {
-                this.setVer(DEFAULT_DB_VERSION);
-            }
-            return this.opened;
         }
         catch (error) {
-            this.env = null;
+            this.root = null;
             const message = error instanceof Error ? error.message : String(error);
-            throw new DatabaseOperationError(`Failed to open LMDB environment: ${message}`, {
-                path: dbPath,
-                readonly,
-                mapSize: effectiveMapSize,
-            });
+            throw new DatabaseOperationError(`Failed to open LMDB environment: ${message}`, { cause: error });
         }
     }
     /** True if the current env path already has a `data.mdb` file. */
@@ -417,25 +456,15 @@ export class LMDBer {
         return pathStat.isFile ?? false;
     }
     /**
-     * Close the root LMDB env and path manager.
-     *
-     * This waits for LMDB-js async close completion and its internal read-reset
-     * timers before optional path cleanup, so test/resource teardown does not
-     * leak across later work.
+     * Close the environment before path cleanup. Observable binding failures
+     * propagate and permanently prevent this wrapper from reusing or deleting it.
+     * Repeated closure of a known-closed environment is harmless.
      */
     *close(clear = false) {
-        if (this.env) {
-            try {
-                yield* this.closeEnv(this.env);
-                yield* this.quiesceEnvTimers(); // lmdb-js uses internal teardown timers to manage post-close; this lets them finish
-            }
-            catch (error) {
-                // Intentional recovery: close errors are non-fatal during shutdown paths.
-                this.logger.warn(`Error closing LMDB: ${error}`);
-            }
-            this.env = null;
+        if (clear && this.existingOnly) {
+            throw new DatabaseOperationError("Existing-store maintenance cannot clear its environment");
         }
-        // Close path manager (now an Effection operation)
+        yield* this.closeEnv();
         yield* this.pathManager.close(clear);
         return true;
     }
@@ -466,9 +495,7 @@ export class LMDBer {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new DatabaseOperationError(`Failed to set database version: ${message}`, {
-                version: val,
-            });
+            throw new DatabaseOperationError(`Failed to set database version: ${message}`, { cause: error });
         }
     }
     /**
@@ -479,11 +506,21 @@ export class LMDBer {
      */
     openDB(name, dupsort = false) {
         const env = this.requireEnv();
-        return env.openDB(name, {
+        // lmdb-js 3.5.3 supports create:false in open.js even though its public
+        // DatabaseOptions declaration omits it. Keep that native detail here.
+        const options = {
             keyEncoding: "binary",
             encoding: "binary", // Use binary encoding for values (raw bytes) to match KERIpy
             dupSort: dupsort,
-        });
+            create: !this.existingOnly,
+        };
+        const table = env.openDB(name, options);
+        // The native API returns undefined for an absent non-creating binding,
+        // despite declaring a non-null result. Maintenance must reject it; ordinary
+        // readonly Baser bindings already tolerate tables absent from Python layouts.
+        if (this.existingOnly && !table)
+            throw new DatabaseOperationError(`Database not found: ${name}`);
+        return table;
     }
     /*
      * Plain key/value family (`dupsort=false` parity surface)
@@ -512,7 +549,7 @@ export class LMDBer {
             return result;
         }
         catch (error) {
-            throw this.formatDbKeyError(key, error);
+            throw this.formatDbKeyError(error);
         }
     }
     /**
@@ -530,7 +567,7 @@ export class LMDBer {
             return true;
         }
         catch (error) {
-            throw this.formatDbKeyError(key, error);
+            throw this.formatDbKeyError(error);
         }
     }
     /**
@@ -551,64 +588,7 @@ export class LMDBer {
             }
         }
         catch (error) {
-            throw this.formatDbKeyError(key, error);
-        }
-    }
-    /**
-     * Read one owned row only after its byte ceiling admits materialization.
-     * Pin 3.5.3 NAPI or matching native Node V8/compression-off hooks.
-     * Fast V8 reads may create mapped views; native scratch/residency are separate.
-     * Borrow an active writer, otherwise hold one explicit snapshot through both reads.
-     * A synchronous beforeCopy callback may reserve credit after extent admission; it must not mutate rows.
-     * The caller owns that credit's lifetime; this ceiling does not bound other read APIs.
-     */
-    getValBounded(db, key, maxBytes, beforeCopy) {
-        const env = this.requireEnv();
-        if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
-            throw new RangeError("Invalid LMDB row byte ceiling");
-        const native = db;
-        const binding = lmdbBinding;
-        const version = binding.version;
-        const runtime = versions;
-        const matchingNodeV8 = version && Number.isSafeInteger(version.nodeCompiledVersion)
-            && version.nodeCompiledVersion >= 20
-            && version.nodeCompiledVersion === Number(runtime.node?.split(".")[0])
-            && Boolean(runtime.v8) && !runtime.deno && !runtime.bun
-            && binding.v8AccelerationEnabled === true;
-        if (!version || ("nodeCompiledVersion" in version && !matchingNodeV8) || native.encoding !== "binary"
-            || native.compression || native.useVersions
-            || native.env !== env.env
-            || typeof native.getBinaryFast !== "function" || typeof native.getBinary !== "function"
-            || typeof native._returnLargeBuffer !== "function" || typeof native.useReadTransaction !== "function") {
-            throw new DatabaseOperationError("Unsupported LMDB bounded-row binding; require lmdb 3.5.3 NAPI or matching native Node V8 binary mode");
-        }
-        const writer = native.env.writeTxn ?? null;
-        const transaction = writer ? undefined : native.useReadTransaction();
-        try {
-            const probe = Object.create(native);
-            // Native returns the required size before this hook grows/copies an insufficient target.
-            probe._returnLargeBuffer = () => undefined;
-            probe.getBinaryFast(key, { transaction });
-            const size = probe.lastSize;
-            if (size === -30798)
-                return null; // MDB_NOTFOUND
-            if (!Number.isSafeInteger(size) || size < 0)
-                throw new DatabaseOperationError("Invalid LMDB row extent");
-            if (size > maxBytes)
-                throw new ResourceLimitError("Stored LMDB row exceeds byte ceiling");
-            if ((native.env.writeTxn ?? null) !== writer)
-                throw new DatabaseOperationError("LMDB row transaction changed");
-            beforeCopy?.(size);
-            if ((native.env.writeTxn ?? null) !== writer)
-                throw new DatabaseOperationError("LMDB row transaction changed");
-            const value = native.getBinary(key, { transaction });
-            if (!value || value.length !== size || (native.env.writeTxn ?? null) !== writer) {
-                throw new DatabaseOperationError("LMDB row changed during bounded read");
-            }
-            return new Uint8Array(value);
-        }
-        finally {
-            transaction?.done();
+            throw this.formatDbKeyError(error);
         }
     }
     /**
@@ -634,7 +614,7 @@ export class LMDBer {
             return result;
         }
         catch (error) {
-            throw this.formatDbKeyError(key, error);
+            throw this.formatDbKeyError(error);
         }
     }
     /**
@@ -688,9 +668,7 @@ export class LMDBer {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new DatabaseOperationError(`Failed to count database branch: ${message}`, {
-                top: Array.from(top),
-            });
+            throw new DatabaseOperationError(`Failed to count database branch: ${message}`, { cause: error });
         }
     }
     /**
@@ -731,9 +709,7 @@ export class LMDBer {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new DatabaseOperationError(`Failed to delete database branch: ${message}`, {
-                top: Array.from(top),
-            });
+            throw new DatabaseOperationError(`Failed to delete database branch: ${message}`, { cause: error });
         }
     }
     /**
@@ -762,9 +738,7 @@ export class LMDBer {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new DatabaseOperationError(`Failed to iterate database branch: ${message}`, {
-                top: Array.from(top),
-            });
+            throw new DatabaseOperationError(`Failed to iterate database branch: ${message}`, { cause: error });
         }
     }
     /*

package/esm/keri/npm/src/db/core/path-manager.js

@@ -170,9 +170,7 @@ export class PathManager {
     set name(value) {
         // Check if path is absolute
         if (isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)) {
-            throw new InvalidPathNameError(`Not relative name=${value} path.`, {
-                name: value,
-            });
+            throw new InvalidPathNameError(`Not relative name=${value} path.`);
         }
         this._name = value;
     }
@@ -412,7 +410,7 @@ export class PathManager {
         const altReady = yield* this._ensurePathAccessible(alt);
         if (!altReady) {
             this.logger.error(`Alt path not available at ${alt}`);
-            throw new PathError(`Alt path not available at ${alt}`, { path: alt });
+            throw new PathError(`Alt path not available at ${alt}`);
         }
         return { path: alt, headDirPath: this.defaults.altHeadDirPath };
     }