keri-ts 2.0.1 → 2.2.0

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

@@ -0,0 +1,1062 @@
+/**
+ * Backend-neutral store contract shared by every `keri-ts` database backend.
+ *
+ * ADR-0015 owns the semantics. Backends supply row access and transactions;
+ * the ordinal, insertion-ordered set and insertion-ordered duplicate families
+ * below are built only on those primitives, so every backend shares them.
+ */
+import { b, bytesEqual, bytesHex, t } from "cesr-ts";
+import { onKey, splitOnKey, suffix, unsuffix } from "./keys.js";
+/** The pinned lmdb-js limit on keys and dupsort values, shared by every backend (ADR-0015). */
+export const MAX_KEY_BYTES = 1978;
+/** Default separator used by ordinal/suffix key helpers (`onKey`, `suffix`). */
+const DOT_SEP = b(".");
+/**
+ * Hex chars used for IoDup insertion ordinal prefix.
+ * Does not include trailing separator.
+ */
+const IODUP_PROEM_HEX_SIZE = 32;
+/**
+ * Full IoDup proem size:
+ * 32-hex ordinal + trailing `.` separator.
+ */
+const IODUP_PROEM_SIZE = 33;
+/**
+ * Dedupe binary values while preserving first-seen order.
+ * Example: `[a, b, a] -> [a, b]`.
+ */
+function asUniqueVals(vals) {
+    const seen = new Set();
+    const out = [];
+    for (const val of vals) {
+        const key = bytesHex(val);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(val);
+    }
+    return out;
+}
+/** Build IoDup ordering proem bytes (`000...00a.` for index `10`). */
+function iDupProem(index) {
+    return b(`${index.toString(16).padStart(IODUP_PROEM_HEX_SIZE, "0")}.`);
+}
+/** Prefix value bytes with IoDup ordering proem for insertion-order semantics. */
+function withIoDupProem(index, val) {
+    const proem = iDupProem(index);
+    const out = new Uint8Array(proem.length + val.length);
+    out.set(proem, 0);
+    out.set(val, proem.length);
+    return out;
+}
+/** Strip IoDup ordering proem from a stored duplicate value. */
+function stripIoDupProem(val) {
+    return val.length >= IODUP_PROEM_SIZE
+        ? val.slice(IODUP_PROEM_SIZE)
+        : new Uint8Array(0);
+}
+/** Parse IoDup insertion ordinal from proem-prefixed stored value. */
+function parseIoDupOrdinal(val) {
+    if (val.length < IODUP_PROEM_HEX_SIZE) {
+        return 0;
+    }
+    const parsed = Number.parseInt(t(val.slice(0, IODUP_PROEM_HEX_SIZE)), 16);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/**
+ * Shared base for every store backend.
+ *
+ * Subclasses implement the abstract row access. Everything concrete here must
+ * stay free of backend types so a new backend inherits identical family
+ * behavior.
+ */
+export class BaseDBer {
+    /*
+     * Ordinal-key family (`On*`)
+     * Logical shape: one logical key -> many values via fixed-width ordinal in key.
+     * Multiplicity: synthetic, stored in keyspace as `key.<on>`.
+     * Ordering: lexicographic key order matches numeric ordinal order.
+     * Parity status: direct KERIpy analogs plus TS rename conveniences.
+     */
+    /**
+     * Write `val` at the ordinal key `onKey(key, on)` only when absent.
+     *
+     * The ordinal is encoded into the physical key as a fixed-width 32-hex suffix
+     * so LMDB key order matches ordinal order. Mirrors KERIpy `putOnVal`.
+     */
+    putOnVal(db, key, on = 0, val = null, sep = DOT_SEP) {
+        if (val === null) {
+            return false;
+        }
+        return this.putVal(db, onKey(key, on, sep), val);
+    }
+    /**
+     * Write `val` at `onKey(key, on)`, overwriting any existing value.
+     *
+     * TypeScript-local rename of KERIpy `setOnVal`.
+     */
+    pinOnVal(db, key, on = 0, val = null, sep = DOT_SEP) {
+        if (!key.length || val === null) {
+            return false;
+        }
+        return this.setVal(db, onKey(key, on, sep), val);
+    }
+    /**
+     * Append `val` at the next ordinal slot for `key`.
+     *
+     * This scans backward from the `key.MaxON` boundary to find the current tail,
+     * then writes at the next ordinal. Returns the appended ordinal. Mirrors
+     * KERIpy `appendOnVal`.
+     */
+    appendOnVal(db, key, val, sep = DOT_SEP) {
+        this.assertOpen();
+        if (!key.length || val === null) {
+            throw new Error(`Bad append parameter: key=${Array.from(key)} val=${val}`);
+        }
+        // KERIpy parity: seek from key.MaxON boundary and step back to the tail
+        // key for this prefix (if any), rather than scanning key.000... upward.
+        const maxOnSuffix = b("f".repeat(32));
+        const start = new Uint8Array(key.length + sep.length + maxOnSuffix.length);
+        start.set(key, 0);
+        start.set(sep, key.length);
+        start.set(maxOnSuffix, key.length + sep.length);
+        let nextOn = 0;
+        for (const entry of this.scan(db, { start, reverse: true, limit: 1 })) {
+            const tailOnKey = entry.key;
+            const [ckey, cn] = splitOnKey(tailOnKey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            if (bytesEqual(tailOnKey, start)) {
+                throw new Error(`Number part cn=${cn} for key part ckey=${Array.from(ckey)} exceeds maximum size.`);
+            }
+            nextOn = cn + 1;
+            break;
+        }
+        const targetKey = onKey(key, nextOn, sep);
+        const added = this.putVal(db, targetKey, val);
+        if (added) {
+            return nextOn;
+        }
+        // Some compat/interop flows still surface LMDB-js range behavior where the
+        // reverse tail probe fails to observe the existing highest ordinal entry.
+        // Fall back to counting the live branch and append at that count instead of
+        // failing a logically valid append.
+        const fallbackOn = this.cntOnAll(db, key, 0, sep);
+        if (fallbackOn !== nextOn) {
+            const fallbackAdded = this.putVal(db, onKey(key, fallbackOn, sep), val);
+            if (fallbackAdded) {
+                return fallbackOn;
+            }
+        }
+        throw new Error(`Failed appending value at key=${Array.from(key)}.`);
+    }
+    /**
+     * TypeScript-only convenience returning the exact `(key, on, val)` triple.
+     *
+     * Returns `null` when that exact ordinal entry is missing.
+     */
+    getOnItem(db, key, on = 0, sep = DOT_SEP) {
+        const val = this.getOnVal(db, key, on, sep);
+        return val ? [key, on, val] : null;
+    }
+    /**
+     * Fetch the value stored exactly at `onKey(key, on)`.
+     *
+     * Returns `null` when the exact ordinal entry is missing. Empty logical keys
+     * are treated as absent. Mirrors KERIpy `getOnVal`.
+     */
+    getOnVal(db, key, on = 0, sep = DOT_SEP) {
+        if (!key.length) {
+            return null;
+        }
+        return this.getVal(db, onKey(key, on, sep));
+    }
+    /**
+     * Remove the value stored exactly at `onKey(key, on)`.
+     *
+     * Empty logical keys return `false`. TypeScript-local rename of KERIpy
+     * `delOnVal`.
+     */
+    remOn(db, key, on = 0, sep = DOT_SEP) {
+        if (!key.length) {
+            return false;
+        }
+        return this.delVal(db, onKey(key, on, sep));
+    }
+    /**
+     * Remove all ordinal entries for `key` starting at ordinal `on`.
+     *
+     * Empty `key` removes the whole DB branch. TypeScript-only convenience built
+     * on the same ordinal-key semantics as KERIpy `delOnVal`.
+     */
+    remOnAll(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        if (!key.length) {
+            return this.delTop(db, new Uint8Array(0));
+        }
+        this.assertOpen();
+        const start = onKey(key, on, sep);
+        const keys = [];
+        for (const entry of this.scan(db, { start })) {
+            const ckey = entry.key;
+            const [top] = splitOnKey(ckey, sep);
+            if (!bytesEqual(top, key)) {
+                break;
+            }
+            keys.push(new Uint8Array(ckey));
+        }
+        if (!keys.length) {
+            return false;
+        }
+        this.transaction(() => {
+            for (const k of keys) {
+                this.removeRow(db, k);
+            }
+        });
+        return true;
+    }
+    /**
+     * Count ordinal-keyed entries for `key` starting at ordinal `on`.
+     *
+     * Empty `key` counts the whole DB. TypeScript-local rename of KERIpy
+     * `cntOnVals`.
+     */
+    cntOnAll(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        this.assertOpen();
+        const start = key.length ? onKey(key, on, sep) : new Uint8Array(0);
+        let count = 0;
+        for (const entry of this.scan(db, { start })) {
+            const ckey = entry.key;
+            const [top] = splitOnKey(ckey, sep);
+            if (key.length && !bytesEqual(top, key)) {
+                break;
+            }
+            count += 1;
+        }
+        return count;
+    }
+    /**
+     * Iterate `(key, on, val)` triples whose physical keys begin with branch `top`.
+     *
+     * This is the ordinal-key version of `getTopItemIter`, so branch membership is
+     * still a lexicographic key-prefix concept. TypeScript-only convenience.
+     */
+    *getOnTopItemIter(db, top = new Uint8Array(0), sep = DOT_SEP) {
+        for (const [onkey, val] of this.getTopItemIter(db, top)) {
+            const [key, on] = splitOnKey(onkey, sep);
+            yield [key, on, val];
+        }
+    }
+    /**
+     * Iterate `(key, on, val)` triples for ordinals `>= on`.
+     *
+     * Empty `key` iterates the whole DB. Ordering follows the fixed-width ordinal
+     * encoded in the key. TypeScript-local rename of KERIpy `getOnItemIter`.
+     */
+    *getOnAllItemIter(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        this.assertOpen();
+        const start = key.length ? onKey(key, on, sep) : new Uint8Array(0);
+        for (const entry of this.scan(db, { start })) {
+            const ckey = entry.key;
+            const cval = entry.value;
+            const [top, cn] = splitOnKey(ckey, sep);
+            if (key.length && !bytesEqual(top, key)) {
+                break;
+            }
+            yield [top, cn, cval];
+        }
+    }
+    /*
+     * Synthetic insertion-ordered set family (`IoSet*`)
+     * Logical shape: one logical key -> many values without dupsort.
+     * Multiplicity: synthetic, stored in keyspace as `key.<ion>`.
+     * Ordering: hidden fixed-width insertion suffix in the physical key.
+     * Parity status: direct KERIpy analogs with TS naming tweaks.
+     */
+    /**
+     * Add each unique value in `vals` to the insertion-ordered set at `key`.
+     *
+     * This emulates duplicate-like behavior in keyspace, not native LMDB dupsort:
+     * values are stored under hidden suffixed keys `key.<ion>`. Existing logical
+     * members are skipped, new members append at the next suffix. Mirrors KERIpy
+     * `putIoSetVals`.
+     */
+    putIoSetVals(db, key, vals, sep = DOT_SEP) {
+        if (!key.length || vals === null) {
+            return false;
+        }
+        const uniqueVals = asUniqueVals(vals);
+        if (!uniqueVals.length) {
+            return false;
+        }
+        const existing = new Set();
+        let ion = 0;
+        const start = suffix(key, 0, sep);
+        for (const entry of this.scan(db, { start })) {
+            const iokey = entry.key;
+            const cval = entry.value;
+            const [ckey, cion] = unsuffix(iokey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            existing.add(bytesHex(cval));
+            ion = cion + 1;
+        }
+        const insert = uniqueVals.filter((val) => !existing.has(bytesHex(val)));
+        if (!insert.length) {
+            return false;
+        }
+        this.assertOpen();
+        this.transaction(() => {
+            for (const [index, val] of insert.entries()) {
+                this.putRow(db, suffix(key, ion + index, sep), val);
+            }
+        });
+        return true;
+    }
+    /**
+     * Replace the insertion-ordered set at `key` with the provided unique values.
+     *
+     * This clears the existing synthetic key run for `key`, then rewrites fresh
+     * hidden suffixes from zero. TypeScript-local rename of KERIpy `setIoSetVals`.
+     */
+    pinIoSetVals(db, key, vals, sep = DOT_SEP) {
+        if (!key.length || vals === null) {
+            return false;
+        }
+        const uniqueVals = asUniqueVals(vals);
+        if (!uniqueVals.length) {
+            return false;
+        }
+        this.remIoSet(db, key, sep);
+        this.assertOpen();
+        this.transaction(() => {
+            for (const [index, val] of uniqueVals.entries()) {
+                this.putRow(db, suffix(key, index, sep), val);
+            }
+        });
+        return true;
+    }
+    /**
+     * Add one value to the insertion-ordered set at `key` if it is not present.
+     *
+     * Membership is checked by scanning the synthetic key run for `key`; new
+     * values append at the next hidden suffix. Mirrors KERIpy `addIoSetVal`.
+     */
+    addIoSetVal(db, key, val, sep = DOT_SEP) {
+        this.assertOpen();
+        if (!key.length || val === null) {
+            return false;
+        }
+        let ion = 0;
+        const valHex = bytesHex(val);
+        const start = suffix(key, 0, sep);
+        for (const entry of this.scan(db, { start })) {
+            const iokey = entry.key;
+            const cval = entry.value;
+            const [ckey, cion] = unsuffix(iokey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            if (bytesHex(cval) === valHex) {
+                return false;
+            }
+            ion = cion + 1;
+        }
+        return this.putVal(db, suffix(key, ion, sep), val);
+    }
+    /**
+     * Iterate `(key, val)` pairs for the insertion-ordered set at `key`.
+     *
+     * Iteration starts at hidden insertion ordinal `ion`. Returned keys are the
+     * logical effective key with the hidden suffix removed. TypeScript-local item
+     * variant corresponding to KERIpy `getIoSetValsIter`.
+     */
+    *getIoSetItemIter(db, key, ion = 0, sep = DOT_SEP) {
+        this.assertOpen();
+        if (!key.length) {
+            return;
+        }
+        const start = suffix(key, ion, sep);
+        for (const entry of this.scan(db, { start })) {
+            const iokey = entry.key;
+            const cval = entry.value;
+            const [ckey] = unsuffix(iokey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            yield [ckey, cval];
+        }
+    }
+    /**
+     * Return the last logical set member at `key`, or `null`.
+     *
+     * "Last" means the entry stored under the greatest hidden insertion suffix,
+     * not the lexicographically greatest value bytes. TypeScript-local item
+     * variant corresponding to KERIpy `getIoSetValLast`.
+     */
+    getIoSetLastItem(db, key, sep = DOT_SEP) {
+        let last = null;
+        for (const item of this.getIoSetItemIter(db, key, 0, sep)) {
+            last = item;
+        }
+        return last;
+    }
+    /**
+     * Remove all insertion-ordered set members at `key`.
+     *
+     * This deletes the full synthetic key run for the effective key. TypeScript-
+     * local rename of KERIpy `delIoSetVals`.
+     */
+    remIoSet(db, key, sep = DOT_SEP) {
+        if (!key.length) {
+            return false;
+        }
+        this.assertOpen();
+        const keys = [];
+        const start = suffix(key, 0, sep);
+        for (const entry of this.scan(db, { start })) {
+            const iokey = entry.key;
+            const [ckey] = unsuffix(iokey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            keys.push(new Uint8Array(iokey));
+        }
+        if (!keys.length) {
+            return false;
+        }
+        this.transaction(() => {
+            for (const iokey of keys) {
+                this.removeRow(db, iokey);
+            }
+        });
+        return true;
+    }
+    /**
+     * Remove one logical set member at `key`, or all members when `val` is `null`.
+     *
+     * Delete-by-value requires a linear search because the caller does not know
+     * the hidden insertion suffix. As in KERIpy, suffix ordinals can grow
+     * monotonically over time after deletes and reinserts. TypeScript-local rename
+     * of KERIpy `delIoSetVal`.
+     */
+    remIoSetVal(db, key, val = null, sep = DOT_SEP) {
+        if (val === null) {
+            return this.remIoSet(db, key, sep);
+        }
+        if (!key.length) {
+            return false;
+        }
+        this.assertOpen();
+        const valHex = bytesHex(val);
+        let removeKey = null;
+        const start = suffix(key, 0, sep);
+        for (const entry of this.scan(db, { start })) {
+            const iokey = entry.key;
+            const cval = entry.value;
+            const [ckey] = unsuffix(iokey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            if (bytesHex(cval) === valHex) {
+                removeKey = new Uint8Array(iokey);
+                break;
+            }
+        }
+        if (!removeKey) {
+            return false;
+        }
+        this.transaction(() => {
+            this.removeRow(db, removeKey);
+        });
+        return true;
+    }
+    /**
+     * Count logical set members at `key` starting from hidden insertion ordinal `ion`.
+     *
+     * TypeScript-local item-count variant corresponding to KERIpy `cntIoSetVals`.
+     */
+    cntIoSet(db, key, ion = 0, sep = DOT_SEP) {
+        if (!key.length) {
+            return 0;
+        }
+        let count = 0;
+        for (const _ of this.getIoSetItemIter(db, key, ion, sep)) {
+            count += 1;
+        }
+        return count;
+    }
+    /**
+     * Iterate `(key, val)` pairs for all synthetic-set entries in branch `top`.
+     *
+     * Branch membership is still a lexicographic key-prefix scan over the
+     * physical suffixed keys; returned keys have the hidden insertion suffix
+     * removed. Mirrors KERIpy `getTopIoSetItemIter`.
+     */
+    *getTopIoSetItemIter(db, top = new Uint8Array(0), sep = DOT_SEP) {
+        for (const [iokey, val] of this.getTopItemIter(db, top)) {
+            const [key] = unsuffix(iokey, sep);
+            yield [key, val];
+        }
+    }
+    /**
+     * Iterate the last `(key, val)` member for each effective io-set key.
+     *
+     * Empty `key` iterates the whole DB. "Last" is determined by hidden suffix
+     * order. TypeScript-local item variant built from KERIpy `getIoSetValLast`
+     * and branch iteration semantics.
+     */
+    *getIoSetLastItemIterAll(db, key = new Uint8Array(0), sep = DOT_SEP) {
+        this.assertOpen();
+        const start = key.length ? suffix(key, 0, sep) : undefined;
+        let last = null;
+        let lkey = null;
+        for (const entry of this.scan(db, { start })) {
+            const iokey = entry.key;
+            const cval = entry.value;
+            const [ckey] = unsuffix(iokey, sep);
+            if (lkey === null) {
+                lkey = ckey;
+            }
+            if (!bytesEqual(ckey, lkey)) {
+                if (last) {
+                    yield last;
+                }
+                lkey = ckey;
+            }
+            last = [ckey, cval];
+        }
+        if (last) {
+            yield last;
+        }
+    }
+    /**
+     * Iterate only the last logical values for each effective io-set key `>= key`.
+     *
+     * TypeScript-only convenience built on `getIoSetLastItemIterAll`.
+     */
+    *getIoSetLastIterAll(db, key = new Uint8Array(0), sep = DOT_SEP) {
+        for (const [_, val] of this.getIoSetLastItemIterAll(db, key, sep)) {
+            yield val;
+        }
+    }
+    /*
+     * Ordinal synthetic insertion-ordered set family (`OnIoSet*`)
+     * Logical shape: ordinal buckets, each bucket holding an insertion-ordered set.
+     * Multiplicity: synthetic, stored in keyspace as `key.<on>.<ion>`.
+     * Ordering: exposed fixed-width ordinal in the key, then hidden insertion suffix.
+     * Parity status: TypeScript-only extension. KERIpy exposes `IoSet*` and
+     * `OnIoDup*`, but not `OnIoSet*`. This exists as extension surface for
+     * ordinal buckets + insertion-ordered set semantics without dupsort
+     * constraints, and currently has no production callers.
+     */
+    /**
+     * TypeScript-only extension. Add set members at ordinal effective key `onKey(key, on)`.
+     *
+     * This is the `On` + `IoSet` composition: exposed ordinal in keyspace, hidden
+     * insertion suffix inside that ordinal bucket.
+     */
+    putOnIoSetVals(db, key, on = 0, vals = null, sep = DOT_SEP) {
+        if (!key.length) {
+            return false;
+        }
+        return this.putIoSetVals(db, onKey(key, on, sep), vals, sep);
+    }
+    /**
+     * TypeScript-only extension. Replace set members at ordinal effective key.
+     *
+     * This is the ordinal-bucketed counterpart to `pinIoSetVals`.
+     */
+    pinOnIoSetVals(db, key, on = 0, vals = null, sep = DOT_SEP) {
+        if (!key.length) {
+            return false;
+        }
+        return this.pinIoSetVals(db, onKey(key, on, sep), vals, sep);
+    }
+    /**
+     * TypeScript-only extension. Append a new ordinal bucket for `key`.
+     *
+     * Returns the newly appended exposed ordinal. Within that bucket, the values
+     * are stored as an `IoSet` using hidden insertion suffixes.
+     */
+    appendOnIoSetVals(db, key, vals, sep = DOT_SEP) {
+        this.assertOpen();
+        if (!key.length || vals === null) {
+            throw new Error(`Bad append parameter: key=${Array.from(key)} vals=${vals}`);
+        }
+        let on = 0;
+        const start = suffix(onKey(key, 0, sep), 0, sep);
+        for (const entry of this.scan(db, { start })) {
+            const iokey = entry.key;
+            const [onkey] = unsuffix(iokey, sep);
+            const [ckey, con] = splitOnKey(onkey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            on = con + 1;
+        }
+        if (!this.putOnIoSetVals(db, key, on, vals, sep)) {
+            throw new Error(`Failed appending set values at key=${Array.from(key)}.`);
+        }
+        return on;
+    }
+    /**
+     * TypeScript-only extension. Add one set member inside an ordinal bucket.
+     *
+     * This is the ordinal-bucketed counterpart to `addIoSetVal`.
+     */
+    addOnIoSetVal(db, key, on = 0, val = null, sep = DOT_SEP) {
+        return this.addIoSetVal(db, onKey(key, on, sep), val, sep);
+    }
+    /**
+     * TypeScript-only extension. Iterate `(key, on, val)` members at one exact ordinal.
+     *
+     * Ordering inside the bucket follows the hidden insertion suffix.
+     */
+    *getOnIoSetItemIter(db, key, on = 0, ion = 0, sep = DOT_SEP) {
+        for (const [onkey, val] of this.getIoSetItemIter(db, onKey(key, on, sep), ion, sep)) {
+            const [k, o] = splitOnKey(onkey, sep);
+            yield [k, o, val];
+        }
+    }
+    /**
+     * TypeScript-only extension. Fetch the last member in one ordinal bucket.
+     *
+     * Returns `null` when that exact ordinal bucket is empty or missing.
+     */
+    getOnIoSetLastItem(db, key, on = 0, sep = DOT_SEP) {
+        const last = this.getIoSetLastItem(db, onKey(key, on, sep), sep);
+        if (!last) {
+            return null;
+        }
+        const [onkey, val] = last;
+        const [k, o] = splitOnKey(onkey, sep);
+        return [k, o, val];
+    }
+    /**
+     * TypeScript-only extension. Remove one member from an ordinal bucket.
+     *
+     * When `val` is `null`, removes the whole ordinal bucket.
+     */
+    remOnIoSetVal(db, key, on = 0, val = null, sep = DOT_SEP) {
+        return this.remIoSetVal(db, onKey(key, on, sep), val, sep);
+    }
+    /**
+     * TypeScript-only extension. Remove all ordinal buckets for `key` from `on` onward.
+     *
+     * Empty `key` removes the whole DB branch.
+     */
+    remOnAllIoSet(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        if (!key.length) {
+            return this.delTop(db, new Uint8Array(0));
+        }
+        this.assertOpen();
+        const start = suffix(onKey(key, on, sep), 0, sep);
+        const keys = [];
+        for (const entry of this.scan(db, { start })) {
+            const iokey = entry.key;
+            const [onkey] = unsuffix(iokey, sep);
+            const [ckey] = splitOnKey(onkey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            keys.push(new Uint8Array(iokey));
+        }
+        if (!keys.length) {
+            return false;
+        }
+        this.transaction(() => {
+            for (const iokey of keys) {
+                this.removeRow(db, iokey);
+            }
+        });
+        return true;
+    }
+    /**
+     * TypeScript-only extension. Count members in one ordinal bucket from insertion ordinal `ion`.
+     */
+    cntOnIoSet(db, key, on = 0, ion = 0, sep = DOT_SEP) {
+        return this.cntIoSet(db, onKey(key, on, sep), ion, sep);
+    }
+    /**
+     * TypeScript-only extension. Count all members across ordinal buckets for `key` from `on` onward.
+     */
+    cntOnAllIoSet(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        this.assertOpen();
+        if (!key.length) {
+            return this.cntAll(db);
+        }
+        let count = 0;
+        const start = suffix(onKey(key, on, sep), 0, sep);
+        for (const entry of this.scan(db, { start })) {
+            const [onkey] = unsuffix(entry.key, sep);
+            const [ckey] = splitOnKey(onkey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            count += 1;
+        }
+        return count;
+    }
+    /**
+     * TypeScript-only extension. Iterate `(key, on, val)` members in branch `top`.
+     *
+     * This is the branch-scan form of `OnIoSet*`, still based on lexicographic
+     * physical key-prefix traversal.
+     */
+    *getOnTopIoSetItemIter(db, top = new Uint8Array(0), sep = DOT_SEP) {
+        for (const [onkey, val] of this.getTopIoSetItemIter(db, top, sep)) {
+            const [key, on] = splitOnKey(onkey, sep);
+            yield [key, on, val];
+        }
+    }
+    /**
+     * TypeScript-only extension. Iterate `(key, on, val)` members for ordinals `>= on`.
+     *
+     * Empty `key` iterates the whole DB.
+     */
+    *getOnAllIoSetItemIter(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        this.assertOpen();
+        if (!key.length) {
+            yield* this.getOnTopIoSetItemIter(db, new Uint8Array(0), sep);
+            return;
+        }
+        const start = suffix(onKey(key, on, sep), 0, sep);
+        for (const entry of this.scan(db, { start })) {
+            const [onkey] = unsuffix(entry.key, sep);
+            const cval = entry.value;
+            const [ckey, con] = splitOnKey(onkey, sep);
+            if (!bytesEqual(ckey, key)) {
+                break;
+            }
+            yield [ckey, con, cval];
+        }
+    }
+    /**
+     * TypeScript-only extension. Iterate the last member for each ordinal bucket.
+     *
+     * Empty `key` iterates all logical keys and ordinals in the DB.
+     */
+    *getOnAllIoSetLastItemIter(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        if (!key.length) {
+            for (const [onkey, val] of this.getIoSetLastItemIterAll(db, new Uint8Array(0), sep)) {
+                const [k, o] = splitOnKey(onkey, sep);
+                yield [k, o, val];
+            }
+            return;
+        }
+        let last = null;
+        for (const [ckey, con, cval] of this.getOnAllIoSetItemIter(db, key, on, sep)) {
+            if (last === null) {
+                last = [ckey, con, cval];
+                continue;
+            }
+            if (con !== last[1]) {
+                yield last;
+            }
+            last = [ckey, con, cval];
+        }
+        if (last) {
+            yield last;
+        }
+    }
+    /**
+     * TypeScript-only extension. Iterate backward over `(key, on, val)` members.
+     *
+     * Backward order is materialized from the forward iterator, then reversed.
+     */
+    *getOnAllIoSetItemBackIter(db, key = new Uint8Array(0), on = null, sep = DOT_SEP) {
+        const items = key.length
+            ? [...this.getOnAllIoSetItemIter(db, key, 0, sep)]
+            : [...this.getOnTopIoSetItemIter(db, new Uint8Array(0), sep)];
+        for (let i = items.length - 1; i >= 0; i--) {
+            const item = items[i];
+            if (key.length && on !== null && item[1] > on) {
+                continue;
+            }
+            yield item;
+        }
+    }
+    /**
+     * TypeScript-only extension. Iterate backward over the last member per ordinal bucket.
+     */
+    *getOnAllIoSetLastItemBackIter(db, key = new Uint8Array(0), on = null, sep = DOT_SEP) {
+        const items = [...this.getOnAllIoSetLastItemIter(db, key, 0, sep)];
+        for (let i = items.length - 1; i >= 0; i--) {
+            const item = items[i];
+            if (key.length && on !== null && item[1] > on) {
+                continue;
+            }
+            yield item;
+        }
+    }
+    /*
+     * Insertion-ordered duplicate family (`IoDup*`)
+     * Logical shape: one physical key -> many native dupsort values.
+     * Multiplicity: native LMDB dupsort values.
+     * Ordering: hidden 33-byte value proem makes dupsort order equal insertion order.
+     * Parity status: direct KERIpy analogs with TS naming tweaks.
+     *
+     * Use this when dupsort size constraints are acceptable; use `IoSet*` when
+     * values may be too large for dupsort-backed storage.
+     */
+    /**
+     * Add insertion-ordered duplicate values at `key`.
+     *
+     * Each stored value gets a hidden 33-byte proem (`32 hex chars + '.'`) so
+     * LMDB's lexicographic duplicate ordering becomes logical insertion order.
+     * Returned values later strip that proem away. Mirrors KERIpy `putIoDupVals`.
+     */
+    putIoDupVals(db, key, vals) {
+        let result = false;
+        const existing = new Set(this.getIoDupVals(db, key).map((val) => bytesHex(val)));
+        let idx = 0;
+        const last = this.getValLast(db, key);
+        if (last) {
+            idx = parseIoDupOrdinal(last) + 1;
+        }
+        this.assertOpen();
+        this.transaction(() => {
+            for (const val of vals) {
+                const vh = bytesHex(val);
+                if (existing.has(vh)) {
+                    continue;
+                }
+                this.putRow(db, key, withIoDupProem(idx, val));
+                idx += 1;
+                existing.add(vh);
+                result = true;
+            }
+        });
+        return result;
+    }
+    /**
+     * Add one insertion-ordered duplicate value at `key` if absent.
+     *
+     * Mirrors KERIpy `addIoDupVal`.
+     */
+    addIoDupVal(db, key, val) {
+        const single = val === null ? [new Uint8Array(0)] : [val];
+        return this.putIoDupVals(db, key, single);
+    }
+    /**
+     * Get insertion-ordered duplicate values at `key`, with the hidden proem removed.
+     *
+     * Ordering is logical insertion order because the hidden proem controls LMDB
+     * dupsort ordering. Mirrors KERIpy `getIoDupVals`.
+     */
+    getIoDupVals(db, key) {
+        return this.getVals(db, key).map((val) => stripIoDupProem(val));
+    }
+    /**
+     * Iterate insertion-ordered duplicate values at `key`, with the hidden proem removed.
+     *
+     * Mirrors KERIpy `getIoDupValsIter`.
+     */
+    *getIoDupValsIter(db, key) {
+        for (const val of this.getValsIter(db, key)) {
+            yield stripIoDupProem(val);
+        }
+    }
+    /**
+     * Get the most recently inserted logical duplicate value at `key`.
+     *
+     * This uses the lexicographically last stored proem-prefixed duplicate and
+     * strips the hidden proem before returning. Mirrors KERIpy `getIoDupValLast`.
+     */
+    getIoDupValLast(db, key) {
+        const last = this.getValLast(db, key);
+        return last ? stripIoDupProem(last) : null;
+    }
+    /** Delete all insertion-ordered duplicates at `key`. Mirrors KERIpy `delIoDupVals`. */
+    delIoDupVals(db, key) {
+        return this.delVals(db, key);
+    }
+    /**
+     * Delete one insertion-ordered duplicate value at `key`, matching the stripped logical value.
+     *
+     * This performs a linear search over stored proem-prefixed duplicates. Mirrors
+     * KERIpy `delIoDupVal`.
+     */
+    delIoDupVal(db, key, val) {
+        this.assertOpen();
+        for (const proVal of this.getVals(db, key)) {
+            if (bytesEqual(stripIoDupProem(proVal), val)) {
+                return this.removeRow(db, key, proVal);
+            }
+        }
+        return false;
+    }
+    /** Count insertion-ordered duplicates at `key`. Mirrors KERIpy `cntIoDupVals`. */
+    cntIoDups(db, key) {
+        return this.cntVals(db, key);
+    }
+    /**
+     * Iterate `(key, val)` over branch `top`, stripping the hidden IoDup proem from each value.
+     *
+     * Mirrors KERIpy `getTopIoDupItemIter`.
+     */
+    *getTopIoDupItemIter(db, top = new Uint8Array(0)) {
+        for (const [key, val] of this.getTopItemIter(db, top)) {
+            yield [key, stripIoDupProem(val)];
+        }
+    }
+    /*
+     * Ordinal insertion-ordered duplicate family (`OnIoDup*`)
+     * Logical shape: ordinal buckets, each bucket holding native dupsort duplicates.
+     * Multiplicity: native LMDB dupsort values within each exposed ordinal key.
+     * Ordering: exposed fixed-width ordinal in the key, hidden 33-byte proem in each duplicate value.
+     * Parity status: direct KERIpy analogs plus a few TS-only convenience methods.
+     */
+    /**
+     * TypeScript-only convenience adding insertion-ordered duplicates at one exact ordinal key.
+     *
+     * This is the ordinal-bucketed counterpart to `putIoDupVals`. KERIpy exposes
+     * `addOnIoDupVal` and iterator-based accessors instead of this bulk helper.
+     */
+    putOnIoDupVals(db, key, on = 0, vals, sep = DOT_SEP) {
+        return this.putIoDupVals(db, onKey(key, on, sep), vals);
+    }
+    /** Add one insertion-ordered duplicate at ordinal effective key. Mirrors KERIpy `addOnIoDupVal`. */
+    addOnIoDupVal(db, key, on = 0, val = null, sep = DOT_SEP) {
+        return this.addIoDupVal(db, onKey(key, on, sep), val);
+    }
+    /**
+     * Append one insertion-ordered duplicate value at the next ordinal bucket for `key`.
+     *
+     * Mirrors KERIpy `appendOnIoDupVal`.
+     */
+    appendOnIoDupVal(db, key, val, sep = DOT_SEP) {
+        return this.appendOnVal(db, key, withIoDupProem(0, val), sep);
+    }
+    /**
+     * TypeScript-only convenience returning all logical duplicates at one exact ordinal.
+     *
+     * KERIpy exposes scan-style iterators across ordinals rather than this exact
+     * per-ordinal list helper.
+     */
+    getOnIoDupVals(db, key, on = 0, sep = DOT_SEP) {
+        if (!key.length) {
+            return [];
+        }
+        return this.getIoDupVals(db, onKey(key, on, sep));
+    }
+    /**
+     * TypeScript-only convenience iterating logical duplicates at one exact ordinal.
+     *
+     * No direct KERIpy equivalent: KERIpy `getOnIoDupValIter` scans all ordinals
+     * from `on` onward, which maps to `getOnIoDupIterAll` here.
+     */
+    *getOnIoDupValsIter(db, key, on = 0, sep = DOT_SEP) {
+        if (!key.length) {
+            return;
+        }
+        yield* this.getIoDupValsIter(db, onKey(key, on, sep));
+    }
+    /**
+     * TypeScript-only convenience fetching the last logical duplicate at one exact ordinal.
+     */
+    getOnIoDupLast(db, key, on = 0, sep = DOT_SEP) {
+        return this.getIoDupValLast(db, onKey(key, on, sep));
+    }
+    /** Iterate the last logical duplicate value per ordinal bucket. Mirrors KERIpy `getOnIoDupLastValIter`. */
+    *getOnIoDupLastValIter(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        for (const [_, __, val] of this.getOnIoDupLastItemIter(db, key, on, sep)) {
+            yield val;
+        }
+    }
+    /** Iterate `(key, on, val)` where `val` is the last logical duplicate per ordinal bucket. Mirrors KERIpy `getOnIoDupLastItemIter`. */
+    *getOnIoDupLastItemIter(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        this.assertOpen();
+        const start = key.length ? onKey(key, on, sep) : new Uint8Array(0);
+        let lonkey = null;
+        let lkey = null;
+        let lon = 0;
+        let last = null;
+        for (const entry of this.scan(db, { start })) {
+            const onkeyBytes = entry.key;
+            const cval = entry.value;
+            const [ckey, con] = splitOnKey(onkeyBytes, sep);
+            if (key.length && !bytesEqual(ckey, key)) {
+                break;
+            }
+            if (lonkey === null || !bytesEqual(lonkey, onkeyBytes)) {
+                if (lonkey !== null && lkey && last) {
+                    yield [lkey, lon, stripIoDupProem(last)];
+                }
+                lonkey = new Uint8Array(onkeyBytes);
+                lkey = ckey;
+                lon = con;
+            }
+            last = cval;
+        }
+        if (lonkey !== null && lkey && last) {
+            yield [lkey, lon, stripIoDupProem(last)];
+        }
+    }
+    /**
+     * Iterate `(key, on, val)` logical duplicates across a top branch.
+     *
+     * This mirrors the KERIpy helper added for normalized `OnIoDupSuber`
+     * branch iteration and strips the hidden insertion-order proem from each
+     * duplicate value before yielding it.
+     */
+    *getOnTopIoDupItemIter(db, top = new Uint8Array(0), sep = DOT_SEP) {
+        for (const [key, on, val] of this.getOnTopItemIter(db, top, sep)) {
+            yield [key, on, stripIoDupProem(val)];
+        }
+    }
+    /** Delete all insertion-ordered duplicates at one ordinal effective key. TypeScript-local rename of KERIpy `delOnIoDupVals`. */
+    delOnIoDups(db, key, on = 0, sep = DOT_SEP) {
+        return this.delIoDupVals(db, onKey(key, on, sep));
+    }
+    /** Delete one insertion-ordered duplicate at one ordinal effective key. Mirrors KERIpy `delOnIoDupVal`. */
+    delOnIoDupVal(db, key, on = 0, val = new Uint8Array(0), sep = DOT_SEP) {
+        return this.delIoDupVal(db, onKey(key, on, sep), val);
+    }
+    /**
+     * TypeScript-only convenience counting logical duplicates at one exact ordinal.
+     *
+     * KERIpy does not expose this exact count helper on `LMDBer`.
+     */
+    cntOnIoDups(db, key, on = 0, sep = DOT_SEP) {
+        return this.cntIoDups(db, onKey(key, on, sep));
+    }
+    /** Iterate backwards over logical duplicate values. Mirrors KERIpy `getOnIoDupValBackIter`. */
+    *getOnIoDupValBackIter(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        for (const [_, __, val] of this.getOnIoDupItemBackIter(db, key, on, sep)) {
+            yield val;
+        }
+    }
+    /** Iterate backwards over `(key, on, val)` logical duplicates. Mirrors KERIpy `getOnIoDupItemBackIter`. */
+    *getOnIoDupItemBackIter(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        const items = key.length
+            ? [...this.getOnIoDupItemIterAll(db, key, 0, sep)].filter((item) => item[1] <= on)
+            : [...this.getOnIoDupItemIterAll(db, new Uint8Array(0), 0, sep)];
+        for (let i = items.length - 1; i >= 0; i--) {
+            yield items[i];
+        }
+    }
+    /**
+     * Iterate logical duplicate values for ordinals `>= on`.
+     *
+     * TypeScript-local name for KERIpy `getOnIoDupValIter`.
+     */
+    *getOnIoDupIterAll(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        for (const [_, __, val] of this.getOnIoDupItemIterAll(db, key, on, sep)) {
+            yield val;
+        }
+    }
+    /**
+     * Iterate `(key, on, val)` logical duplicates for ordinals `>= on`.
+     *
+     * TypeScript-local name for KERIpy `getOnIoDupItemIter`.
+     */
+    *getOnIoDupItemIterAll(db, key = new Uint8Array(0), on = 0, sep = DOT_SEP) {
+        for (const [ckey, con, cval] of this.getOnAllItemIter(db, key, on, sep)) {
+            yield [ckey, con, stripIoDupProem(cval)];
+        }
+    }
+}