@kokuin/store-vault 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @kokuin/store-vault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local vault persistence for hozon. Register `vaultStoreDefinition`, then call `getVaultStore(provider)`.
+All addresses require an explicit owner DID. Owners and recipients round-trip verbatim.
+
+Keys contain public suite, version and state metadata. Wrappings and entries contain opaque encrypted bytes.
+Entry `kind`, `label` and string attributes remain public. Filters combine exact kind/label equality with conjunctive attribute-subset matching.
+
+Ordinary key puts accept equal or greater versions. Entry puts replace bytes without comparing HLC and refuse key reassociation.
+`moveEntry` stores caller-encrypted destination bytes while preserving the owner-qualified entry ID.
+It does nothing when the observed source disappears or changes key before locking.
+Conditional updates never insert or move rows. HLC CAS returns `updated`, `absent` or `superseded`.
+The caller supplies all encryption, authorisation and HLC values.
+
+`transaction` joins an enclosing host transaction. Obtain the store from the host's transaction provider for journal/outbox atomicity.
+Explicit key locks require a transaction. Declare the complete key set before authoritative reads when touching multiple keys.
+Writes use hozon key locks, including absent keys. Multi-key locking orders actual advisory IDs through hozon.
+Generic reads never acquire write locks or change rows.
+
+The shared lock namespace uses table `vault_keys` and tuple `[JSON.stringify([ownerDID, keyID])]`.
+This maps the database-free vault record lock `{ type: 'vault.key', key: JSON.stringify([ownerDID, keyID]) }`.
+Replicated adapters must reuse this mapping.
+
+The base schema contains only keys, wrappings and entries. Each row has a `local` or `replicated` mode.
+The package supplies coordinators. The consumer supplies transport.
+
+## Optional records
+
+Register `vaultRecordsStoreDefinition` alongside the base definition, then initialise it with
+`await getVaultRecordsStore(provider, opKind)` before opening caller transactions. It depends on `vault`.
+The base registration alone never creates records, decisions, candidates, branch proofs or revocations.
+
+`createVaultRecords({ store, opKind, authority, validateConsumerMetadata, nowMS, maxDriftMS })`
+creates a facade over the initialised store. The operation kind has no default.
+Initialisation binds the database permanently to that kind without taking vault key locks.
+Supplying a kind inside a caller transaction throws. Omit it only when retrieving already initialised storage.
+Apply only reads and compares the binding. Reads and writes refuse an absent or different durable kind.
+
+Use `apply(records, transportContext)` for receipt. Use `write({ records, preconditions })` for signed local output.
+Both run `@kokuin/records` apply. There is no direct signed put method.
+`preconditions.key` compares the expected version, including `null` for absence, and an optional complete branch set.
+`preconditions.entry` compares an entry's exact HLC, including `null` for absence.
+Every output must be covered by the named key or entry. Preconditions and apply share the transaction and key locks.
+Obtain the base store from the caller's transaction provider to join journal/outbox writes.
+An error requires the caller to roll back that transaction.
+
+The `adapter` implements `RecordStoreAdapter` for transport reconciliation and routed apply.
+Its `putCopy` and `pruneCopy` are trusted engine persistence ports, requiring an adapter transaction.
+Never submit untrusted signed records directly to those ports.
+`vaultRecordPortsFor(adapter)` resolves transaction-bound definition effects, including through `adapterForType` routing.
+Authority and signed consumer metadata validation always come from the caller.
+Transport and membership policy remain consumer-owned.
+
+Local mutation methods refuse replicated addresses with `VaultModeConflict`.
+Projections refuse local addresses, and their entire apply transaction rolls back.
+Mode reservations survive signed tombstones, suppressed wrappings and local physical deletion after optional registration.
+Entry mode is independent of the parent key. There is no adoption or unrevocation API.
+
+Branch reads return verified introducing operations. Wrappings and entries carry their signed branch as `provenance`.
+Candidate reads retain received authorised entry losers and prior tombstones.
+Exchange lists selected decisions and their signed copies, rather than all candidate history.
+Revocations permanently suppress recipient and DID-factor wrappings across versions.
+A survivor's same-decision endorsement can replace a removed signer's copy without losing content.
+
+`get` and `getMany` fail closed on unreadable decisions. `list` omits corrupt decisions and reports them through `onCorruptRow`.
+Generic reads never repair data or write history. Range leaves and fingerprints use the records package's functions.
+
+## Coordinators
+
+`createVaultCoordinator(params)` adds authority, opening, key lifecycle, rotation, repair and encrypted entry operations.
+Select `mode: 'local'` or `mode: 'replicated'` explicitly. Both require `CredentialAuthority`, a principal, runtime and `nextHLC`.
+Supply an agreement identity, or `null` for secret-only opening. Replicated mode additionally requires a signer and records configuration.
+Initialise the optional records store before constructing a replicated coordinator. Local coordinators need only the base store.
+
+The store-vault `CredentialAuthority` accepts unsigned operations and the vault's existing verified record requests.
+Unsigned requests use `source: 'local'` and include the selected mode, operation, verb, address and unchanged transport context.
+This includes replicated reads. No fabricated signed operation represents a local request.
+Record admission uses `source: 'record'`, verified fields and the transaction-bound records read port.
+Every public operation calls authority, including cached opens, missing entries, listings, repair and explicit re-endorsement.
+Reads use `read`. Persistent mutations use `administer`. Authority refusal stops the operation before database writes.
+Consumer metadata and effective membership remain consumer decisions. There is no default authority.
+
+`openKey` returns a private content-key buffer. The caller must erase that buffer after use.
+`unlock`, `lock`, `lockAll` and `status` manage the optional memory cache.
+Input-free opens share in-flight work. Input-bearing opens verify independently, even when a key is cached.
+All PIN-bearing opening paths share one throttle. Locks invalidate pending cache warming.
+Replicated opening selects authenticated branches by claim digest, then operation hash.
+It passes the signed wrapping's descriptor digest to unwrap. Local rows provide no independent trusted descriptor digest.
+
+`createKey` takes an explicit canonical owner DID and optional ordered wrapping factor sets.
+The default wrapping addresses the agreement identity in its resolvable form.
+`grant`, `addFactor` and `removeFactor` require administration and operate on the current version.
+A historical `atVersion` on those mutations refuses. `setKeyState` and `deleteKey` change lifecycle metadata.
+Replicated arbitration can refuse same-version reactivation after retirement. The coordinator reports that refusal as `VaultWriteConflict`.
+
+Entry operations accept explicit owner-qualified addresses, byte plaintext and public kind, label and string attributes.
+`putEntry` creates an absent address. Updates require an existing entry. HLC CAS returns updated, absent or superseded.
+`reKeyEntry` authorises both keys, preserves the entry address, and re-encrypts under the destination key.
+`getEntry`, `listEntries`, `listKeys`, `readEntry` and `openKey` never write or initiate recovery.
+Returned entry rows include stored provenance. No entry ID has application-specific meaning.
+
+`rotate` and `repairFork` require `excludedRecipients` and `reissue` arrays, including explicit empty arrays.
+Replicated rotation carries generic plaintext and public metadata forward, preserving content intent unless an instruction supplies another `contentHLC`.
+Local rotation stores a fresh entry HLC and ignores `contentHLC` and `consumer` instructions.
+A reissue instruction names one entry and selects `preserve`, `replace`, `delete` or `skip`.
+`replace` supplies new plaintext. In replicated mode, `consumer` optionally replaces signed opaque metadata.
+`skip` leaves the old entry untouched. Duplicate or unknown entry instructions refuse the whole operation.
+Replacement instructions target live entries. Tombstone preservation and explicit deletion require no plaintext.
+
+Exclusions match explicit recipients and DID factors. Replicated exclusions also publish permanent recipient denials through apply.
+Local exclusions delete existing matching wrappings. Local mode has no permanent revocation table.
+Repair uses received authenticated candidates, prior tombstones and vault branch proofs. It never discovers removed members.
+Repair returns rotated, not-needed or pending. Missing preservation factors leave the fork pending for an explicit retry.
+Received candidate history has no all-peers completeness guarantee.
+
+Replicated coordinators submit every signed output through `write` and apply with operation-specific preconditions.
+Rotation checks key version and branch set. Lifecycle changes check key version. Entry writes check the entry HLC.
+They refuse parked, rejected or losing output and roll back the operation. There is no direct signed put.
+Retained wrapping factors and reissued entry projections are checked against signed evidence before they become new signed output.
+`reendorse({ ownerDID, keyID, records })` re-signs only named stored decisions, including key tombstones, without changing their claims or payloads.
+The configured signer represents the effective consumer member. The consumer decides which records require re-endorsement.
+
+Mutations hold hozon's complete key-lock set through their joined transaction, including cryptographic work.
+Create the coordinator from the host transaction's store when journal/outbox changes must commit together.
+Propagate errors out of the host transaction so it rolls back. Temporary keys and decrypted plaintext are erased on success and failure.
+`nextHLC` belongs to the host. It must provide canonical, increasing stamps and any required restart floor.
+Crypto-only hosts continue to use `@kokuin/vault` directly.

package/lib/api.d.ts

@@ -0,0 +1,5 @@
+import type { Adapter } from '@hozon/adapter';
+import { type Kysely, type StoreContext } from '@hozon/db';
+import type { VaultStoreTables } from './tables.js';
+import type { VaultStoreAPI } from './types.js';
+export declare function createVaultStore(db: Kysely<VaultStoreTables>, adapter: Adapter, context: StoreContext): VaultStoreAPI;

package/lib/api.js

@@ -0,0 +1,504 @@
+import { sql, withKeyLock, withKeyLocks, withStoreTransaction } from '@hozon/db';
+import { deleteEntryRows, deleteWrappingRows, ENTRY_COLUMNS, selectEntries, selectWrappings, statementChunks, upsertEntries, upsertWrappings, WRAPPING_COLUMNS } from './batch.js';
+import { claimModes, VaultModeConflict, vaultDatabases } from './record-context.js';
+import { getVaultRecordsStore } from './record-definition.js';
+import { settleAll } from './settle.js';
+const databases = new WeakMap();
+async function transactionDatabase(provider) {
+    const store = await provider.getStore('vault');
+    const db = databases.get(store);
+    if (db == null) throw new Error('Vault store database is unavailable');
+    return db;
+}
+// The vault record lock's key is already framed as [owner, keyID]. Keep that identity intact.
+function lockTuple(address) {
+    return [
+        JSON.stringify([
+            address.ownerDID,
+            address.keyID
+        ])
+    ];
+}
+function decodeJSON(value) {
+    return typeof value === 'string' ? JSON.parse(value) : value;
+}
+function keyRow(row) {
+    return {
+        ownerDID: row.owner_did,
+        keyID: row.key_id,
+        suite: row.suite,
+        version: row.version,
+        state: row.state
+    };
+}
+function entryRow(row) {
+    return {
+        ownerDID: row.owner_did,
+        entryID: row.entry_id,
+        keyID: row.key_id,
+        keyVersion: row.key_version,
+        kind: row.kind,
+        label: row.label,
+        attributes: decodeJSON(row.attributes),
+        iv: Uint8Array.from(row.iv),
+        ciphertext: Uint8Array.from(row.ciphertext),
+        hlc: row.hlc,
+        provenance: row.provenance
+    };
+}
+function wrappingRow(row) {
+    return {
+        ownerDID: row.owner_did,
+        wrappingID: row.wrapping_id,
+        keyID: row.key_id,
+        keyVersion: row.key_version,
+        descriptors: decodeJSON(row.descriptors),
+        descriptorDigest: row.descriptor_digest,
+        iv: Uint8Array.from(row.iv),
+        wrappedKey: Uint8Array.from(row.wrapped_key),
+        recipientDID: row.recipient_did,
+        provenance: row.provenance
+    };
+}
+export function createVaultStore(db, adapter, context) {
+    const read = (fn)=>{
+        return withStoreTransaction(db, fn);
+    };
+    const locked = async (addresses, fn)=>{
+        const run = async (provider)=>{
+            return withStoreTransaction(await transactionDatabase(provider), fn);
+        };
+        const address = addresses[0];
+        if (addresses.length === 1 && address != null) {
+            return withKeyLock(context.provider, 'vault_keys', lockTuple(address), run);
+        }
+        return withKeyLocks(context.provider, 'vault_keys', addresses.map(lockTuple), run);
+    };
+    const localModes = async (trx, type, keys)=>{
+        if (keys.length === 0) return;
+        const table = type === 'vault.key' ? 'vault_keys' : type === 'vault.entry' ? 'vault_entries' : 'vault_wrappings';
+        const column = type === 'vault.key' ? 'key_id' : type === 'vault.entry' ? 'entry_id' : 'wrapping_id';
+        const rows = await settleAll(statementChunks(keys, 2).map((part)=>{
+            return trx.selectFrom(table).select('mode').where((eb)=>{
+                return eb.or(part.map((key)=>eb.and([
+                        eb('owner_did', '=', key.owner),
+                        eb(column, '=', key.id)
+                    ])));
+            }).execute();
+        }));
+        if (rows.flat().some((row)=>row.mode === 'replicated')) throw new VaultModeConflict();
+        if (context.provider.hasStore('vault-records')) {
+            await getVaultRecordsStore(context.provider);
+            await claimModes(trx, keys.map((key)=>({
+                    type,
+                    owner: key.owner,
+                    id: key.id
+                })), 'local');
+        }
+    };
+    const localMode = (trx, type, owner, id)=>{
+        return localModes(trx, type, [
+            {
+                owner,
+                id
+            }
+        ]);
+    };
+    // One lock per key, however many rows name it.
+    const keysOf = (rows)=>{
+        return [
+            ...new Map(rows.map((row)=>[
+                    JSON.stringify([
+                        row.ownerDID,
+                        row.keyID
+                    ]),
+                    {
+                        ownerDID: row.ownerDID,
+                        keyID: row.keyID
+                    }
+                ])).values()
+        ];
+    };
+    // The last write of each address wins, as sequential writes would. One address written under
+    // two keys is reported, so the caller can fail as the second sequential write would, after the
+    // mode checks that write would have passed first.
+    const lastWrites = (rows, address)=>{
+        const unique = new Map();
+        let rekeyed = false;
+        for (const row of rows){
+            const id = address(row);
+            const previous = unique.get(id);
+            if (previous !== undefined && previous.keyID !== row.keyID) rekeyed = true;
+            unique.delete(id);
+            unique.set(id, row);
+        }
+        return {
+            rows: [
+                ...unique.values()
+            ],
+            rekeyed
+        };
+    };
+    const wrappingValues = (row)=>{
+        return {
+            owner_did: row.ownerDID,
+            wrapping_id: row.wrappingID,
+            key_id: row.keyID,
+            key_version: row.keyVersion,
+            descriptors: adapter.encodeJSON(row.descriptors),
+            descriptor_digest: row.descriptorDigest,
+            iv: adapter.encodeBinary(row.iv),
+            wrapped_key: adapter.encodeBinary(row.wrappedKey),
+            recipient_did: row.recipientDID,
+            provenance: row.provenance
+        };
+    };
+    const written = (results)=>{
+        return results.reduce((sum, result)=>sum + (result.numInsertedOrUpdatedRows ?? 0n), 0n);
+    };
+    const selectEntry = (trx, address)=>{
+        return trx.selectFrom('vault_entries').selectAll().where('owner_did', '=', address.ownerDID).where('entry_id', '=', address.entryID);
+    };
+    const entryValues = (row)=>{
+        return {
+            owner_did: row.ownerDID,
+            entry_id: row.entryID,
+            key_id: row.keyID,
+            key_version: row.keyVersion,
+            kind: row.kind,
+            label: row.label,
+            attributes: adapter.encodeJSON(row.attributes),
+            iv: adapter.encodeBinary(row.iv),
+            ciphertext: adapter.encodeBinary(row.ciphertext),
+            hlc: row.hlc,
+            provenance: row.provenance
+        };
+    };
+    const updateEntry = async (row, expectedHLC)=>{
+        return locked([
+            row
+        ], async (trx)=>{
+            await localMode(trx, 'vault.entry', row.ownerDID, row.entryID);
+            let update = trx.updateTable('vault_entries').set(entryValues(row)).where('owner_did', '=', row.ownerDID).where('entry_id', '=', row.entryID).where('key_id', '=', row.keyID);
+            if (expectedHLC !== undefined) update = update.where('hlc', '=', expectedHLC);
+            const result = await update.executeTakeFirst();
+            if (result.numUpdatedRows > 0n) return 'updated';
+            if (expectedHLC !== undefined) {
+                const existing = await selectEntry(trx, row).where('key_id', '=', row.keyID).executeTakeFirst();
+                if (existing != null && existing.hlc !== expectedHLC) return 'superseded';
+            }
+            return 'absent';
+        });
+    };
+    const api = {
+        isTransaction: db.isTransaction,
+        async transaction (fn) {
+            return context.provider.withTransaction(async (tx)=>{
+                const store = await tx.getStore('vault');
+                return withStoreTransaction(await transactionDatabase(tx), async ()=>fn(store));
+            });
+        },
+        async lockKeyRow (address) {
+            if (!context.provider.isTransactionBound) throw new Error('Key locks require a transaction');
+            await locked([
+                address
+            ], async ()=>{});
+        },
+        async lockKeyRows (addresses) {
+            if (!context.provider.isTransactionBound) throw new Error('Key locks require a transaction');
+            await locked(addresses, async ()=>{});
+        },
+        async putKey (row) {
+            await locked([
+                row
+            ], async (trx)=>{
+                await localMode(trx, 'vault.key', row.ownerDID, row.keyID);
+                const values = {
+                    owner_did: row.ownerDID,
+                    key_id: row.keyID,
+                    suite: row.suite,
+                    version: row.version,
+                    state: row.state
+                };
+                await trx.insertInto('vault_keys').values(values).onConflict((oc)=>{
+                    return oc.columns([
+                        'owner_did',
+                        'key_id'
+                    ]).doUpdateSet({
+                        suite: row.suite,
+                        version: row.version,
+                        state: row.state
+                    }).where('vault_keys.version', '<=', row.version);
+                }).execute();
+            });
+        },
+        async getKey (address) {
+            return read(async (trx)=>{
+                const row = await trx.selectFrom('vault_keys').selectAll().where('owner_did', '=', address.ownerDID).where('key_id', '=', address.keyID).executeTakeFirst();
+                return row == null ? undefined : keyRow(row);
+            });
+        },
+        async listKeys (ownerDID) {
+            return read(async (trx)=>{
+                const rows = await trx.selectFrom('vault_keys').selectAll().where('owner_did', '=', ownerDID).orderBy('key_id').execute();
+                return rows.map(keyRow);
+            });
+        },
+        async setKeyState (row) {
+            await locked([
+                row
+            ], async (trx)=>{
+                await localMode(trx, 'vault.key', row.ownerDID, row.keyID);
+                await trx.updateTable('vault_keys').set({
+                    state: row.state
+                }).where('owner_did', '=', row.ownerDID).where('key_id', '=', row.keyID).execute();
+            });
+        },
+        async setKeyVersion (row) {
+            await locked([
+                row
+            ], async (trx)=>{
+                await localMode(trx, 'vault.key', row.ownerDID, row.keyID);
+                await trx.updateTable('vault_keys').set({
+                    version: row.version
+                }).where('owner_did', '=', row.ownerDID).where('key_id', '=', row.keyID).where('version', '<=', row.version).execute();
+            });
+        },
+        async deleteKey (address) {
+            await locked([
+                address
+            ], async (trx)=>{
+                await localMode(trx, 'vault.key', address.ownerDID, address.keyID);
+                await trx.deleteFrom('vault_keys').where('owner_did', '=', address.ownerDID).where('key_id', '=', address.keyID).execute();
+            });
+        },
+        async putWrapping (row) {
+            await api.putWrappings([
+                row
+            ]);
+        },
+        async putWrappings (input) {
+            const { rows, rekeyed } = lastWrites(input, (row)=>JSON.stringify([
+                    row.ownerDID,
+                    row.wrappingID
+                ]));
+            if (rows.length === 0) return;
+            await locked(keysOf(input), async (trx)=>{
+                await localModes(trx, 'vault.wrapping', rows.map((row)=>({
+                        owner: row.ownerDID,
+                        id: row.wrappingID
+                    })));
+                if (rekeyed) throw new Error('Wrapping belongs to another key');
+                const keyOf = new Map(rows.map((row)=>[
+                        JSON.stringify([
+                            row.ownerDID,
+                            row.wrappingID
+                        ]),
+                        row.keyID
+                    ]));
+                const existing = await settleAll(statementChunks(rows, 2).map((part)=>{
+                    return selectWrappings(trx, part.map((row)=>({
+                            owner_did: row.ownerDID,
+                            wrapping_id: row.wrappingID
+                        }))).execute();
+                }));
+                if (existing.flat().some((held)=>keyOf.get(JSON.stringify([
+                        held.owner_did,
+                        held.wrapping_id
+                    ])) !== held.key_id)) throw new Error('Wrapping belongs to another key');
+                const results = await settleAll(statementChunks(rows, WRAPPING_COLUMNS).map((part)=>{
+                    return upsertWrappings(trx, part.map(wrappingValues)).executeTakeFirstOrThrow();
+                }));
+                if (written(results) !== BigInt(rows.length)) throw new Error('Wrapping belongs to another key');
+            });
+        },
+        async getWrapping (address) {
+            return read(async (trx)=>{
+                const row = await trx.selectFrom('vault_wrappings').selectAll().where('owner_did', '=', address.ownerDID).where('wrapping_id', '=', address.wrappingID).executeTakeFirst();
+                return row == null ? undefined : wrappingRow(row);
+            });
+        },
+        async listWrappings (address) {
+            return read(async (trx)=>{
+                let query = trx.selectFrom('vault_wrappings').selectAll().where('owner_did', '=', address.ownerDID).where('key_id', '=', address.keyID);
+                if (address.keyVersion !== undefined) query = query.where('key_version', '=', address.keyVersion);
+                return (await query.orderBy('wrapping_id').execute()).map(wrappingRow);
+            });
+        },
+        async deleteWrapping (address) {
+            await api.deleteWrappings([
+                address
+            ]);
+        },
+        async deleteWrappings (addresses) {
+            if (addresses.length === 0) return;
+            // Discover each key before locking, then qualify deletion so a changed association survives.
+            const rows = (await read((trx)=>{
+                return settleAll(statementChunks(addresses, 2).map((part)=>{
+                    return selectWrappings(trx, part.map((address)=>{
+                        return {
+                            owner_did: address.ownerDID,
+                            wrapping_id: address.wrappingID
+                        };
+                    })).execute();
+                }));
+            })).flat();
+            if (rows.length === 0) return;
+            await locked(keysOf(rows.map((row)=>({
+                    ownerDID: row.owner_did,
+                    keyID: row.key_id
+                }))), async (trx)=>{
+                await localModes(trx, 'vault.wrapping', rows.map((row)=>({
+                        owner: row.owner_did,
+                        id: row.wrapping_id
+                    })));
+                await settleAll(statementChunks(rows, 3).map((part)=>deleteWrappingRows(trx, part).execute()));
+            });
+        },
+        async deleteWrappingsBelowVersion (address) {
+            await locked([
+                address
+            ], async (trx)=>{
+                const rows = await trx.selectFrom('vault_wrappings').selectAll().where('owner_did', '=', address.ownerDID).where('key_id', '=', address.keyID).where('key_version', '<', address.keyVersion).execute();
+                await localModes(trx, 'vault.wrapping', rows.map((row)=>({
+                        owner: row.owner_did,
+                        id: row.wrapping_id
+                    })));
+                await trx.deleteFrom('vault_wrappings').where('owner_did', '=', address.ownerDID).where('key_id', '=', address.keyID).where('key_version', '<', address.keyVersion).execute();
+            });
+        },
+        async putEntry (row) {
+            await api.putEntries([
+                row
+            ]);
+        },
+        async putEntries (input) {
+            const { rows, rekeyed } = lastWrites(input, (row)=>JSON.stringify([
+                    row.ownerDID,
+                    row.entryID
+                ]));
+            if (rows.length === 0) return;
+            await locked(keysOf(input), async (trx)=>{
+                await localModes(trx, 'vault.entry', rows.map((row)=>({
+                        owner: row.ownerDID,
+                        id: row.entryID
+                    })));
+                if (rekeyed) throw new Error('Entry belongs to another key');
+                const keyOf = new Map(rows.map((row)=>[
+                        JSON.stringify([
+                            row.ownerDID,
+                            row.entryID
+                        ]),
+                        row.keyID
+                    ]));
+                const existing = await settleAll(statementChunks(rows, 2).map((part)=>{
+                    return selectEntries(trx, part.map((row)=>({
+                            owner_did: row.ownerDID,
+                            entry_id: row.entryID
+                        }))).execute();
+                }));
+                if (existing.flat().some((held)=>keyOf.get(JSON.stringify([
+                        held.owner_did,
+                        held.entry_id
+                    ])) !== held.key_id)) throw new Error('Entry belongs to another key');
+                const results = await settleAll(statementChunks(rows, ENTRY_COLUMNS).map((part)=>{
+                    return upsertEntries(trx, part.map(entryValues)).executeTakeFirstOrThrow();
+                }));
+                if (written(results) !== BigInt(rows.length)) throw new Error('Entry belongs to another key');
+            });
+        },
+        async moveEntry (row) {
+            const source = await api.getEntry(row);
+            if (source == null) return;
+            await locked([
+                source,
+                row
+            ], async (trx)=>{
+                await localMode(trx, 'vault.entry', row.ownerDID, row.entryID);
+                // UPDATE-only plus the source predicate prevents resurrection and stale reassociation.
+                await trx.updateTable('vault_entries').set(entryValues(row)).where('owner_did', '=', row.ownerDID).where('entry_id', '=', row.entryID).where('key_id', '=', source.keyID).execute();
+            });
+        },
+        async updateEntryIfPresent (row) {
+            return await updateEntry(row);
+        },
+        async updateEntryIfUnchanged (row) {
+            return updateEntry(row, row.expectedHLC);
+        },
+        async getEntry (address) {
+            return read(async (trx)=>{
+                const row = await selectEntry(trx, address).executeTakeFirst();
+                return row == null ? undefined : entryRow(row);
+            });
+        },
+        async getEntryWithProvenance (address) {
+            return api.getEntry(address);
+        },
+        async listEntryOwners (entryID) {
+            return read(async (trx)=>{
+                const rows = await trx.selectFrom('vault_entries').select('owner_did').where('entry_id', '=', entryID).orderBy('owner_did').execute();
+                return rows.map((row)=>row.owner_did);
+            });
+        },
+        async listEntries (filter) {
+            return read(async (trx)=>{
+                let query = trx.selectFrom('vault_entries').selectAll().where('owner_did', '=', filter.ownerDID).where('key_id', '=', filter.keyID);
+                if (filter.kind !== undefined) query = query.where('kind', '=', filter.kind);
+                if (filter.label !== undefined) query = query.where('label', '=', filter.label);
+                if (filter.attributes !== undefined) {
+                    // One JSON bind handles arbitrary attribute sets without dynamic paths or bind growth.
+                    const attributes = JSON.stringify(filter.attributes);
+                    const column = sql.ref('vault_entries.attributes');
+                    query = query.where(adapter.kind === 'postgres' ? sql`${column} @> ${attributes}::text::jsonb` : sql`not exists (
+                select 1 from json_each(${attributes}) as wanted
+                where not exists (
+                  select 1 from json_each(${column}) as held
+                  where held.key = wanted.key and held.type = 'text' and held.value = wanted.value
+                )
+              )`);
+                }
+                return (await query.orderBy('entry_id').execute()).map(entryRow);
+            });
+        },
+        async deleteEntry (address) {
+            await api.deleteEntries([
+                address
+            ]);
+        },
+        async deleteEntries (addresses) {
+            if (addresses.length === 0) return;
+            const rows = (await read((trx)=>{
+                return settleAll(statementChunks(addresses, 2).map((part)=>{
+                    return selectEntries(trx, part.map((address)=>({
+                            owner_did: address.ownerDID,
+                            entry_id: address.entryID
+                        }))).execute();
+                }));
+            })).flat();
+            if (rows.length === 0) return;
+            await locked(keysOf(rows.map((row)=>({
+                    ownerDID: row.owner_did,
+                    keyID: row.key_id
+                }))), async (trx)=>{
+                await localModes(trx, 'vault.entry', rows.map((row)=>({
+                        owner: row.owner_did,
+                        id: row.entry_id
+                    })));
+                await settleAll(statementChunks(rows, 3).map((part)=>deleteEntryRows(trx, part).execute()));
+            });
+        },
+        async getMaxEntryHLC () {
+            return read(async (trx)=>{
+                const row = await trx.selectFrom('vault_entries').select((eb)=>eb.fn.max('hlc').as('max_hlc')).executeTakeFirst();
+                return row?.max_hlc ?? null;
+            });
+        }
+    };
+    vaultDatabases.set(api, {
+        db: db,
+        adapter,
+        context
+    });
+    databases.set(api, db);
+    return api;
+}