@kubun/store-credential 0.17.4 → 0.18.0

package/lib/api.js

@@ -1,994 +1,41 @@
-import { normalizeDID } from '@kokuin/token';
-import { sql } from 'kysely';
+import { createAliasesApi } from './api-aliases.js';
+import { createEntriesApi } from './api-entries.js';
+import { createKeysApi } from './api-keys.js';
+import { createProvisioningApi } from './api-provisioning.js';
+import { createRecordsApi } from './api-records.js';
+import { createStoreContext } from './store-context.js';
 /**
  * `refreshSeq` sentinel for a delegation chain that has no future refresh —
  * larger than any real ms timestamp, so a bounded refresh can never overtake
  * it. Consumed by `@kubun/plugin-p2p`.
  */ export const UNBOUNDED_REFRESH_SEQ = 8_640_000_000_000_000;
-/**
- * Run `write` as one atomic unit.
- *
- * A row and the op that speaks for it must land together or not at all: a crash
- * between a delete and its tombstone loses the deletion, and one between a put
- * and its op leaves a row nothing authenticates. Kysely rejects a nested
- * `transaction()`, and an ambient one already provides the atomicity, so inside
- * a caller's transaction the statements run inline.
- */ async function writeAtomically(db, write) {
-    if (db.isTransaction) {
-        await write(db);
-        return;
-    }
-    await db.transaction().execute(async (tx)=>{
-        await write(tx);
+export function createCredentialStore(db, adapter, advisoryIDForKey) {
+    const ctx = createStoreContext({
+        db,
+        adapter,
+        advisoryIDForKey,
+        getAPI: ()=>api
     });
-}
-/**
- * The strictly-greater-`refreshSeq` upsert shared by {@link CredentialStoreAPI.putWrappingAuthority}
- * and `putWrapping`'s own-transaction variant — one predicate, so the two entry
- * points cannot drift on what "newer" means.
- */ async function upsertWrappingAuthority(db, params) {
-    const values = {
-        wrapping_id: params.wrappingID,
-        authority_token: params.envelope,
-        refresh_seq: params.refreshSeq
-    };
-    await db.insertInto('kubun_credential_wrapping_authority').values(values).onConflict((oc)=>oc.column('wrapping_id').doUpdateSet({
-            authority_token: values.authority_token,
-            refresh_seq: values.refresh_seq
-        }).where('kubun_credential_wrapping_authority.refresh_seq', '<', values.refresh_seq)).execute();
-}
-const OP_REJECTED = Symbol('credential op rejected');
-// A repair that repoints a dangling alias can collide with UNIQUE(entry_id) when the
-// caller's entry is already aliased under another name. The error classes and codes
-// share nothing across the two drivers, so match a uniqueness marker AND the exact
-// identifier each driver reports — never a bare substring, which would also swallow an
-// unrelated error that merely mentions the column. Postgres: SQLSTATE 23505 plus the
-// constraint name (on the error or in the message). SQLite: "UNIQUE constraint failed"
-// plus the table.column.
-function isEntryAliasUniqueViolation(error) {
-    if (error == null || typeof error !== 'object') return false;
-    const { message, code, constraint_name, constraint } = error;
-    const msg = typeof message === 'string' ? message : '';
-    const name = typeof constraint === 'string' && constraint || typeof constraint_name === 'string' && constraint_name || '';
-    const entryConstraint = 'uq_kubun_credential_aliases_entry' // Postgres constraint
-    ;
-    const entryColumn = 'kubun_credential_aliases.entry_id' // SQLite column
-    ;
-    const postgres = (code === '23505' || msg.includes('duplicate key value')) && (name === entryConstraint || msg.includes(entryConstraint));
-    const sqlite = msg.includes('UNIQUE constraint failed') && msg.includes(entryColumn);
-    return postgres || sqlite;
-}
-async function writeOp(params) {
-    const { db, subjectKind, subjectID, op, deleted, allowKeyMove = false } = params;
-    const values = {
-        subject_kind: subjectKind,
-        subject_id: subjectID,
-        key_id: op.keyID,
-        author_did: op.authorDID,
-        hlc: op.hlc,
-        op_jwt: op.opJWT,
-        op_hash: op.opHash,
-        branch_id: op.branchID,
-        deleted
-    };
-    const result = await db.insertInto('kubun_credential_ops').values(values).onConflict((oc)=>{
-        const update = oc.columns([
-            'subject_kind',
-            'subject_id'
-        ]).doUpdateSet({
-            key_id: values.key_id,
-            author_did: values.author_did,
-            hlc: values.hlc,
-            op_jwt: values.op_jwt,
-            op_hash: values.op_hash,
-            branch_id: values.branch_id,
-            deleted: values.deleted
-        })// Ownership and the LWW comparison live in the conflict statement so
-        // concurrent replicas cannot both pass a preceding read.
-        .where((eb)=>eb.or([
-                eb('kubun_credential_ops.hlc', '<', values.hlc),
-                eb.and([
-                    eb('kubun_credential_ops.hlc', '=', values.hlc),
-                    eb('kubun_credential_ops.op_hash', '<', values.op_hash)
-                ]),
-                eb.and([
-                    eb('kubun_credential_ops.hlc', '=', values.hlc),
-                    eb('kubun_credential_ops.op_hash', '=', values.op_hash),
-                    eb('kubun_credential_ops.deleted', '<=', values.deleted)
-                ])
-            ]));
-        return allowKeyMove ? update : update.where('kubun_credential_ops.key_id', '=', values.key_id);
-    }).executeTakeFirst();
-    return (result.numInsertedOrUpdatedRows ?? 0n) > 0n;
-}
-export function createCredentialStore(db, adapter) {
-    /**
-   * Write a row and its op together, unless a tombstone already covers it.
-   *
-   * A `null` op writes the row on its own: the op is what a writer able to sign
-   * supplies, and nothing here can mint one.
-   */ async function writeSubject(params) {
-        const { subjectKind, subjectID, op, write, accept, allowKeyMove = false } = params;
-        if (op == null) {
-            if (accept == null) {
-                await write(db);
-            } else {
-                await writeAmbient(db, async (tx)=>{
-                    if (await accept(tx)) await write(tx);
-                });
-            }
-            return;
-        }
-        const ownsTransaction = !db.isTransaction;
-        try {
-            await writeAmbient(db, async (tx)=>{
-                if (!await writeOp({
-                    db: tx,
-                    subjectKind,
-                    subjectID,
-                    op,
-                    deleted: 0,
-                    allowKeyMove
-                })) return;
-                // The op conflict serializes concurrent writers before this read. A
-                // rejected version must roll its provisional op update back too.
-                if (accept != null && !await accept(tx)) throw OP_REJECTED;
-                await write(tx);
-            });
-        } catch (error) {
-            if (error === OP_REJECTED && ownsTransaction) return;
-            throw error;
-        }
-    }
-    async function deleteSubject(params) {
-        const { subjectKind, subjectID, tombstone, remove } = params;
-        if (tombstone == null) {
-            await remove(db);
-            return;
-        }
-        await writeAmbient(db, async (tx)=>{
-            if (!await writeOp({
-                db: tx,
-                subjectKind,
-                subjectID,
-                op: tombstone,
-                deleted: 1
-            })) return;
-            await remove(tx);
-        });
-    }
-    async function writeEntry(params, op, allowMove) {
-        const values = {
-            entry_id: params.entryID,
-            key_id: params.keyID,
-            key_version: params.keyVersion,
-            iv: adapter.encodeBinary(params.iv),
-            ciphertext: adapter.encodeBinary(params.ciphertext),
-            hlc: params.hlc
-        };
-        await writeSubject({
-            subjectKind: 'entry',
-            subjectID: params.entryID,
-            op,
-            write: async (tx)=>{
-                if (!allowMove) {
-                    const existing = await tx.selectFrom('kubun_credential_entries').select('key_id').where('entry_id', '=', params.entryID).executeTakeFirst();
-                    if (existing != null && existing.key_id !== params.keyID) {
-                        throw new Error(`Credential entry ${params.entryID} already belongs to key ${existing.key_id}`);
-                    }
-                }
-                const result = await tx.insertInto('kubun_credential_entries').values(values).onConflict((oc)=>{
-                    const update = oc.column('entry_id').doUpdateSet({
-                        key_id: values.key_id,
-                        key_version: values.key_version,
-                        iv: values.iv,
-                        ciphertext: values.ciphertext,
-                        hlc: values.hlc
-                    });
-                    return allowMove ? update : update.where('kubun_credential_entries.key_id', '=', values.key_id);
-                }).executeTakeFirst();
-                if (!allowMove && (result.numInsertedOrUpdatedRows ?? 0n) === 0n) {
-                    throw new Error(`Credential entry ${params.entryID} belongs to another key`);
-                }
-            },
-            allowKeyMove: allowMove
-        });
-    }
-    // One async gate serializes EVERY write that joins a caller-supplied ambient
-    // transaction. The SAVEPOINT sections below (updateEntryIfPresent's op+row fence,
-    // bindAliasIfAbsent's repair fence) then hold the connection exclusively for their
-    // whole open → rollback/release window, so a ROLLBACK TO SAVEPOINT can never undo
-    // another concurrent write's committed work — a savepoint rollback reverts ALL work
-    // since the savepoint, not just this operation's statements. getStates resolves its
-    // connectors with Promise.all over one shared request tx, the source of that
-    // concurrency. The gate covers not only the savepoint sections but every ambient
-    // write (writeAmbient, and the raw alias writers via gatedIfAmbient), so no ungated
-    // statement can land inside a savepoint window. Reads are never gated. Owned
-    // transactions (db.isTransaction === false) open their own connection and are
-    // serialized by the driver, so they skip the gate. The gate is per api instance:
-    // `db.isTransaction` is fixed per instance, so a fresh transaction builds a fresh
-    // store with its own gate.
-    let ambientWriteChain = Promise.resolve();
-    const withAmbientWrite = (fn)=>{
-        const run = ambientWriteChain.then(fn, fn);
-        ambientWriteChain = run.then(()=>undefined, ()=>undefined);
-        return run;
-    };
-    // Gate a single raw ambient statement; run it directly when this store owns no
-    // ambient transaction (nothing else can interleave a savepoint there).
-    const gatedIfAmbient = (fn)=>db.isTransaction ? withAmbientWrite(fn) : fn();
-    // writeAtomically, but the inline (ambient) branch runs under the gate so it cannot
-    // interleave a concurrent savepoint section. The owned branch opens its own tx.
-    const writeAmbient = (innerDb, write)=>innerDb.isTransaction ? withAmbientWrite(()=>writeAtomically(innerDb, write)) : writeAtomically(innerDb, write);
+    const { gatedIfAmbient, lockKeyRowInTransaction, lockKeyRowsInTransaction } = ctx;
     const api = {
+        isTransaction: db.isTransaction,
         async transaction (fn) {
             if (db.isTransaction) {
                 return await fn(api);
             }
-            return await db.transaction().execute(async (tx)=>await fn(createCredentialStore(tx, adapter)));
-        },
-        async putKey (params, op) {
-            await writeSubject({
-                subjectKind: 'key',
-                subjectID: params.keyID,
-                op,
-                write: async (tx)=>{
-                    await tx.insertInto('kubun_credential_keys').values({
-                        key_id: params.keyID,
-                        owner_did: params.ownerDID,
-                        suite: params.suite,
-                        version: params.version,
-                        state: params.state
-                    }).onConflict((oc)=>oc.column('key_id').doUpdateSet({
-                            owner_did: params.ownerDID,
-                            suite: params.suite,
-                            version: params.version,
-                            state: params.state
-                        })).execute();
-                },
-                accept: async (tx)=>{
-                    const existing = await tx.selectFrom('kubun_credential_keys').select('version').where('key_id', '=', params.keyID).executeTakeFirst();
-                    return existing == null || params.version >= existing.version;
-                }
-            });
-        },
-        async getKey (keyID) {
-            return await db.selectFrom('kubun_credential_keys').selectAll().where('key_id', '=', keyID).executeTakeFirst();
-        },
-        async listKeys (ownerDID) {
-            return await db.selectFrom('kubun_credential_keys').selectAll().where('owner_did', '=', ownerDID).orderBy('created_at', 'asc').orderBy('key_id', 'asc').execute();
-        },
-        async setKeyState (keyID, state, op) {
-            await writeSubject({
-                subjectKind: 'key',
-                subjectID: keyID,
-                op,
-                write: async (tx)=>{
-                    await tx.updateTable('kubun_credential_keys').set({
-                        state
-                    }).where('key_id', '=', keyID).execute();
-                }
-            });
-        },
-        async setKeyVersion (keyID, version, op) {
-            await writeSubject({
-                subjectKind: 'key',
-                subjectID: keyID,
-                op,
-                write: async (tx)=>{
-                    await tx.updateTable('kubun_credential_keys').set({
-                        version
-                    }).where('key_id', '=', keyID).execute();
-                },
-                accept: async (tx)=>{
-                    const existing = await tx.selectFrom('kubun_credential_keys').select('version').where('key_id', '=', keyID).executeTakeFirst();
-                    return existing == null || version >= existing.version;
-                }
-            });
-        },
-        async deleteKey (keyID, tombstone) {
-            await deleteSubject({
-                subjectKind: 'key',
-                subjectID: keyID,
-                tombstone,
-                remove: async (tx)=>{
-                    await tx.deleteFrom('kubun_credential_keys').where('key_id', '=', keyID).execute();
-                }
-            });
-        },
-        async recordKeyBranch (params) {
-            await db.insertInto('kubun_credential_key_branches').values({
-                key_id: params.keyID,
-                key_version: params.keyVersion,
-                op_hash: params.opHash,
-                author_did: params.authorDID,
-                hlc: params.hlc,
-                op_jwt: params.opJWT,
-                branch_id: params.branchID
-            }).onConflict((oc)=>oc.columns([
-                    'key_id',
-                    'key_version',
-                    'op_hash'
-                ]).doNothing()).execute();
-        },
-        async listKeyBranches (keyID, keyVersion) {
-            return await db.selectFrom('kubun_credential_key_branches').selectAll().where('key_id', '=', keyID).where('key_version', '=', keyVersion).orderBy('branch_id', 'asc').execute();
-        },
-        async putWrapping (params, op, authority) {
-            const values = {
-                wrapping_id: params.wrappingID,
-                key_id: params.keyID,
-                key_version: params.keyVersion,
-                factors: adapter.encodeJSON(params.factors),
-                iv: adapter.encodeBinary(params.iv),
-                wrapped_key: adapter.encodeBinary(params.wrappedKey),
-                recipient_did: params.recipientDID ?? null
-            };
-            await writeSubject({
-                subjectKind: 'wrapping',
-                subjectID: params.wrappingID,
-                op,
-                write: async (tx)=>{
-                    const existing = await tx.selectFrom('kubun_credential_wrappings').select('key_id').where('wrapping_id', '=', params.wrappingID).executeTakeFirst();
-                    if (existing != null && existing.key_id !== params.keyID) {
-                        throw new Error(`Credential wrapping ${params.wrappingID} already belongs to key ${existing.key_id}`);
-                    }
-                    const result = await tx.insertInto('kubun_credential_wrappings').values(values).onConflict((oc)=>oc.column('wrapping_id').doUpdateSet({
-                            key_id: values.key_id,
-                            key_version: values.key_version,
-                            factors: values.factors,
-                            iv: values.iv,
-                            wrapped_key: values.wrapped_key,
-                            recipient_did: values.recipient_did
-                        }).where('kubun_credential_wrappings.key_id', '=', values.key_id)).executeTakeFirst();
-                    if ((result.numInsertedOrUpdatedRows ?? 0n) === 0n) {
-                        throw new Error(`Credential wrapping ${params.wrappingID} belongs to another key`);
-                    }
-                    // Runs only after `writeOp` wins its LWW race, so a superseded
-                    // wrapping never persists an envelope it didn't actually establish.
-                    if (authority != null) {
-                        await upsertWrappingAuthority(tx, {
-                            wrappingID: params.wrappingID,
-                            envelope: authority.envelope,
-                            refreshSeq: authority.refreshSeq
-                        });
-                    }
-                }
-            });
-        },
-        async getWrapping (wrappingID) {
-            return await db.selectFrom('kubun_credential_wrappings').selectAll().where('wrapping_id', '=', wrappingID).executeTakeFirst();
-        },
-        async listWrappings (keyID, keyVersion) {
-            let query = db.selectFrom('kubun_credential_wrappings').selectAll().where('key_id', '=', keyID);
-            if (keyVersion != null) {
-                query = query.where('key_version', '=', keyVersion);
-            }
-            return await query.orderBy('created_at', 'asc').orderBy('wrapping_id', 'asc').execute();
-        },
-        async listWrappingsWithBranch (keyID, keyVersion) {
-            // LEFT JOIN so a wrapping with no op row still lists — its branch is the
-            // empty label. The ops PK is `(subject_kind, subject_id)`, so a wrapping
-            // matches at most one op and the join never fans out.
-            let query = db.selectFrom('kubun_credential_wrappings as w').leftJoin('kubun_credential_ops as o', (join)=>join.onRef('o.subject_id', '=', 'w.wrapping_id').on('o.subject_kind', '=', 'wrapping')).selectAll('w').select('o.branch_id as branch_id').where('w.key_id', '=', keyID);
-            if (keyVersion != null) {
-                query = query.where('w.key_version', '=', keyVersion);
-            }
-            const rows = await query.orderBy('w.created_at', 'asc').orderBy('w.wrapping_id', 'asc').execute();
-            return rows.map((row)=>({
-                    ...row,
-                    branch_id: row.branch_id ?? ''
-                }));
-        },
-        async deleteWrapping (wrappingID, tombstone) {
-            await deleteSubject({
-                subjectKind: 'wrapping',
-                subjectID: wrappingID,
-                tombstone,
-                remove: async (tx)=>{
-                    await tx.deleteFrom('kubun_credential_wrappings').where('wrapping_id', '=', wrappingID).execute();
-                }
-            });
-        },
-        async deleteWrappingsBelowVersion (keyID, keyVersion, tombstones) {
-            const remove = async (tx)=>{
-                await tx.deleteFrom('kubun_credential_wrappings').where('key_id', '=', keyID).where('key_version', '<', keyVersion).execute();
-            };
-            if (tombstones == null) {
-                await remove(db);
-                return;
-            }
-            await writeAmbient(db, async (tx)=>{
-                for (const tombstone of tombstones){
-                    if (!await writeOp({
-                        db: tx,
-                        subjectKind: 'wrapping',
-                        subjectID: tombstone.subjectID,
-                        op: tombstone,
-                        deleted: 1
-                    })) {
-                        continue;
-                    }
-                    await tx.deleteFrom('kubun_credential_wrappings').where('wrapping_id', '=', tombstone.subjectID).where('key_id', '=', keyID).where('key_version', '<', keyVersion).execute();
-                }
-            });
-        },
-        async putEntry (params, op) {
-            await writeEntry(params, op, false);
-        },
-        async moveEntry (params, op) {
-            await writeEntry(params, op, true);
-        },
-        async updateEntryIfPresent (params, op) {
-            let outcome = 'absent';
-            const runWrite = async (tx)=>{
-                // Op-first, like putEntry/deleteEntry: take the op lock before the entry row,
-                // the same order deleteEntry uses, so a row-first inversion cannot deadlock a
-                // concurrent delete. writeOp's LWW guard rejects a stale-HLC writeback and its
-                // key_id predicate (default allowKeyMove = false) one aimed at a key the entry
-                // was re-keyed away from; either way it returns false and nothing is touched.
-                // Its insert branch mints the signed op for a GraphQL-created op-less entry
-                // (putEntry(..., null)), so that entry's first refresh is preserved.
-                if (op != null && !await writeOp({
-                    db: tx,
-                    subjectKind: 'entry',
-                    subjectID: params.entryID,
-                    op,
-                    deleted: 0
-                })) {
-                    return;
-                }
-                // The op winning does NOT prove the entry row is present under this key: the
-                // GraphQL admin surface writes a row with no op (putEntry(..., null)) and
-                // removes a row without touching its op (deleteEntry(..., null)), so the row
-                // can be absent or re-keyed here. UPDATE-only, keyed on entry_id AND key_id;
-                // on a miss, throw to roll the provisional op back, so op and row never
-                // diverge and no live op is left without its row.
-                const result = await tx.updateTable('kubun_credential_entries').set({
-                    key_version: params.keyVersion,
-                    iv: adapter.encodeBinary(params.iv),
-                    ciphertext: adapter.encodeBinary(params.ciphertext),
-                    hlc: params.hlc
-                }).where('entry_id', '=', params.entryID).where('key_id', '=', params.keyID).executeTakeFirst();
-                if ((result.numUpdatedRows ?? 0n) === 0n) {
-                    if (op != null) throw OP_REJECTED;
-                    return;
-                }
-                outcome = 'updated';
-            };
-            if (!db.isTransaction) {
-                // We own the transaction: writeAtomically opens it and an OP_REJECTED throw
-                // rolls the provisional op back before it can commit.
-                try {
-                    await writeAmbient(db, runWrite);
-                } catch (error) {
-                    if (error === OP_REJECTED) return 'absent';
-                    throw error;
-                }
-                return outcome;
-            }
-            // Ambient caller transaction (e.g. a connector mutation's per-request refresh
-            // stack joins its tx). writeAtomically runs inline here with no rollback fence,
-            // and the refresh decorator catches every writeback error — so a bare throw
-            // would leave the provisional op committed with no row. Fence the op+row writes
-            // in a savepoint: a miss rolls back ONLY the provisional op, leaving the
-            // caller's transaction intact. The section runs under withAmbientWrite so no other
-            // ambient write can land inside this savepoint window and be reverted with it.
-            // SAVEPOINT is portable across SQLite and Postgres.
-            return await withAmbientWrite(async ()=>{
-                await sql`SAVEPOINT kubun_cred_update_entry`.execute(db);
-                try {
-                    await runWrite(db);
-                } catch (error) {
-                    await sql`ROLLBACK TO SAVEPOINT kubun_cred_update_entry`.execute(db);
-                    await sql`RELEASE SAVEPOINT kubun_cred_update_entry`.execute(db);
-                    if (error === OP_REJECTED) return 'absent';
-                    throw error;
-                }
-                await sql`RELEASE SAVEPOINT kubun_cred_update_entry`.execute(db);
-                return outcome;
-            });
-        },
-        async getEntry (entryID) {
-            return await db.selectFrom('kubun_credential_entries').selectAll().where('entry_id', '=', entryID).executeTakeFirst();
-        },
-        async getEntryWithProvenance (entryID) {
-            return await db.selectFrom('kubun_credential_entries as e').leftJoin('kubun_credential_ops as o', (join)=>join.onRef('o.subject_id', '=', 'e.entry_id').on('o.subject_kind', '=', 'entry')).selectAll('e').select('o.author_did as author_did').where('e.entry_id', '=', entryID).executeTakeFirst();
-        },
-        async listEntries (keyID) {
-            return await db.selectFrom('kubun_credential_entries').selectAll().where('key_id', '=', keyID).orderBy('created_at', 'asc').orderBy('entry_id', 'asc').execute();
-        },
-        async deleteEntry (entryID, tombstone) {
-            await deleteSubject({
-                subjectKind: 'entry',
-                subjectID: entryID,
-                tombstone,
-                remove: async (tx)=>{
-                    await tx.deleteFrom('kubun_credential_entries').where('entry_id', '=', entryID).execute();
-                }
-            });
-        },
-        async getMaxEntryHLC () {
-            const row = await db.selectFrom('kubun_credential_entries').select((eb)=>eb.fn.max('hlc').as('max_hlc')).executeTakeFirst();
-            return row?.max_hlc ?? null;
-        },
-        async getOp (subjectKind, subjectID) {
-            return await db.selectFrom('kubun_credential_ops').selectAll().where('subject_kind', '=', subjectKind).where('subject_id', '=', subjectID).executeTakeFirst();
-        },
-        async listOps (keyID) {
-            return await scanOps(db, keyID);
-        },
-        async listOpsForRequester (rawRequesterDID, keyID) {
-            const requesterDID = normalizeDID(rawRequesterDID);
-            // Recipient membership comes from the wrappings table, not the ops table: a
-            // rotation deletes a superseded wrapping's row but keeps its tombstone, and
-            // a former recipient of an opens-nothing wrapping is no longer a recipient.
-            // recipient_did is stored un-normalized, so fold at the compare.
-            const wrappings = await db.selectFrom('kubun_credential_wrappings').select([
-                'wrapping_id',
-                'key_id',
-                'recipient_did'
-            ]).where('recipient_did', 'is not', null).execute();
-            const recipientKeyIDs = new Set();
-            const requesterWrappingIDs = new Set();
-            for (const wrapping of wrappings){
-                if (wrapping.recipient_did != null && normalizeDID(wrapping.recipient_did) === requesterDID) {
-                    recipientKeyIDs.add(wrapping.key_id);
-                    requesterWrappingIDs.add(wrapping.wrapping_id);
-                }
-            }
-            const ops = await scanOps(db, keyID);
-            // A wrapping's ciphertext is usable only by its addressee, so its op travels
-            // only to the DID it names — a co-recipient's wrapping stays withheld. A
-            // key's row and its entries travel to any recipient of the key. A wrapping
-            // tombstone names no addressee once its row is gone, so it cannot route
-            // here; revocation propagation is a separate concern.
-            return ops.filter((op)=>{
-                if (op.subject_kind === 'wrapping') {
-                    return requesterWrappingIDs.has(op.subject_id);
-                }
-                return recipientKeyIDs.has(op.key_id);
-            });
-        },
-        async listHeldSubjects () {
-            const rows = await db.selectFrom('kubun_credential_ops').select([
-                'subject_kind',
-                'subject_id',
-                'op_hash'
-            ]).where('deleted', '=', 0).execute();
-            return rows.map((row)=>({
-                    subjectKind: row.subject_kind,
-                    subjectID: row.subject_id,
-                    opHash: row.op_hash
-                }));
-        },
-        async getAliasEntryID (namespace, key) {
-            const row = await db.selectFrom('kubun_credential_aliases').select('entry_id').where('namespace', '=', namespace).where('alias_key', '=', key).executeTakeFirst();
-            return row?.entry_id ?? null;
-        },
-        async aliasNamespaceForEntry (entryID) {
-            const row = await db.selectFrom('kubun_credential_aliases').select('namespace').where('entry_id', '=', entryID).executeTakeFirst();
-            return row?.namespace ?? null;
-        },
-        async setAliasEntryID (namespace, key, entryID) {
-            await gatedIfAmbient(()=>db.insertInto('kubun_credential_aliases').values({
-                    namespace,
-                    alias_key: key,
-                    entry_id: entryID
-                }).onConflict((oc)=>oc.columns([
-                        'namespace',
-                        'alias_key'
-                    ]).doUpdateSet({
-                        entry_id: entryID
-                    })).execute());
-        },
-        async bindAliasIfAbsent ({ namespace, aliasKey, entryID, expectedKeyID }) {
-            // Entry-existence-conditioned insert: the alias row is written only in the same
-            // statement that confirms the entry exists. ON CONFLICT DO NOTHING fires for either
-            // the (namespace, alias_key) PK or the UNIQUE(entry_id); the read-back names which.
-            //
-            // The table has no FK to entries (SQLite ships with foreign_keys OFF, so a declared
-            // FK would be unenforced there). The INSERT...SELECT closes the race on any
-            // single-writer store; deleteCredential removes the entry before the pointer so a
-            // bind racing a delete refuses cleanly rather than dangling. A pointer that still
-            // outlives its entry (a Postgres delete committing mid-statement) is recovered two
-            // ways: getCredential/getCredentialRef resolve a missing entry to null, and the
-            // repair path below repoints a dangling pointer to a fresh, present entry.
-            const tryInsert = async ()=>{
-                const inserted = await gatedIfAmbient(()=>db.insertInto('kubun_credential_aliases').columns([
-                        'namespace',
-                        'alias_key',
-                        'entry_id'
-                    ]).expression((eb)=>eb.selectFrom('kubun_credential_entries').where('entry_id', '=', entryID)// Same-statement key gate (see doc): bind only while the entry
-                        // still belongs to expectedKeyID, so a concurrent cross-key move
-                        // cannot slip an alias onto an entry that has left this key.
-                        .$if(expectedKeyID != null, (qb)=>qb.where('key_id', '=', expectedKeyID)).select((eb2)=>[
-                                eb2.val(namespace).as('namespace'),
-                                eb2.val(aliasKey).as('alias_key'),
-                                eb2.ref('entry_id').as('entry_id')
-                            ])).onConflict((oc)=>oc.doNothing()).returning('entry_id').executeTakeFirst());
-                return inserted != null;
-            };
-            const aliasAt = async ()=>{
-                const row = await db.selectFrom('kubun_credential_aliases').select('entry_id').where('namespace', '=', namespace).where('alias_key', '=', aliasKey).executeTakeFirst();
-                return row?.entry_id ?? null;
-            };
-            const entryExists = async (id)=>{
-                const row = await db.selectFrom('kubun_credential_entries').select('entry_id').where('entry_id', '=', id).executeTakeFirst();
-                return row != null;
-            };
-            // Repoint this alias to entryID, but ONLY while its stored pointer is still
-            // dangling (its entry row absent), so a concurrently-installed valid binding is
-            // never overwritten — the no-repoint guarantee. A UNIQUE(entry_id) clash (entryID
-            // already aliased elsewhere) must not abort an ambient Postgres transaction, so a
-            // caller-tx write is fenced in a savepoint and the clash mapped to conflict:'entry'.
-            const repairDangling = async (observedExisting)=>{
-                const doUpdate = async ()=>{
-                    const res = await db.updateTable('kubun_credential_aliases').set({
-                        entry_id: entryID
-                    }).where('namespace', '=', namespace).where('alias_key', '=', aliasKey)// Compare-and-swap on the pointer: repoint only while it still holds the
-                    // dangling id we observed. If a concurrent transaction repointed it onto a
-                    // freshly created entry, this matches zero rows — under Postgres READ
-                    // COMMITTED the re-checked current row carries the new id, so a valid binding
-                    // is never overwritten even when that new entry is outside our snapshot.
-                    .where('entry_id', '=', observedExisting)// The observed pointer must still be dangling (its entry absent)...
-                    .where((eb)=>eb.not(eb.exists(eb.selectFrom('kubun_credential_entries as e').select(sql`1`.as('one')).whereRef('e.entry_id', '=', 'kubun_credential_aliases.entry_id'))))// ...and the target must be present, so repair can never form a NEW dangling
-                    // pointer even if the target is deleted between the pre-check and here.
-                    // When key-gated, the target must also still belong to expectedKeyID, so a
-                    // repair cannot repoint onto an entry that has moved to another key.
-                    .where((eb)=>eb.exists(eb.selectFrom('kubun_credential_entries as t').select(sql`1`.as('one')).where('t.entry_id', '=', entryID).$if(expectedKeyID != null, (qb)=>qb.where('t.key_id', '=', expectedKeyID)))).executeTakeFirst();
-                    return (res.numUpdatedRows ?? 0n) > 0n;
-                };
-                if (!db.isTransaction) {
-                    try {
-                        return await doUpdate();
-                    } catch (error) {
-                        if (isEntryAliasUniqueViolation(error)) return 'entry-clash';
-                        throw error;
-                    }
-                }
-                return await withAmbientWrite(async ()=>{
-                    await sql`SAVEPOINT kubun_cred_bind_repair`.execute(db);
-                    try {
-                        const repaired = await doUpdate();
-                        await sql`RELEASE SAVEPOINT kubun_cred_bind_repair`.execute(db);
-                        return repaired;
-                    } catch (error) {
-                        await sql`ROLLBACK TO SAVEPOINT kubun_cred_bind_repair`.execute(db);
-                        await sql`RELEASE SAVEPOINT kubun_cred_bind_repair`.execute(db);
-                        if (isEntryAliasUniqueViolation(error)) return 'entry-clash';
-                        throw error;
-                    }
-                });
-            };
-            if (await tryInsert()) return 'inserted';
-            if (!await entryExists(entryID)) return 'entry-missing';
-            const existing = await aliasAt();
-            // PK free but the insert did not fire and the entry exists → the caller's entry is
-            // already aliased under another name (UNIQUE(entry_id)).
-            if (existing == null) return {
-                conflict: 'entry'
-            };
-            if (existing === entryID) return {
-                conflict: 'alias',
-                existing
-            };
-            // PK held by a different entry; repair only if that pointer is dangling.
-            if (await entryExists(existing)) return {
-                conflict: 'alias',
-                existing
-            };
-            const repaired = await repairDangling(existing);
-            if (repaired === true) return 'inserted';
-            if (repaired === 'entry-clash') return {
-                conflict: 'entry'
-            };
-            // The pointer stopped being dangling under us, or the target vanished (a
-            // concurrent rebind, repair, or delete). Reclassify against the current state,
-            // re-checking the target so a target that disappeared reports entry-missing
-            // rather than a spurious entry conflict.
-            if (await tryInsert()) return 'inserted';
-            if (!await entryExists(entryID)) return 'entry-missing';
-            const now = await aliasAt();
-            if (now == null) return {
-                conflict: 'entry'
-            };
-            if (now === entryID) return 'inserted';
-            return {
-                conflict: 'alias',
-                existing: now
-            };
-        },
-        async deleteAliasEntryID (namespace, key) {
-            await gatedIfAmbient(()=>db.deleteFrom('kubun_credential_aliases').where('namespace', '=', namespace).where('alias_key', '=', key).execute());
-        },
-        async deleteAliasIfEntry (namespace, key, entryID) {
-            await gatedIfAmbient(()=>db.deleteFrom('kubun_credential_aliases').where('namespace', '=', namespace).where('alias_key', '=', key).where('entry_id', '=', entryID).execute());
-        },
-        async listAliasKeys (namespace) {
-            const rows = await db.selectFrom('kubun_credential_aliases').select('alias_key').distinct().where('namespace', '=', namespace).execute();
-            return rows.map((row)=>row.alias_key);
-        },
-        async putWrappingAuthority (params) {
-            await upsertWrappingAuthority(db, params);
-        },
-        async getWrappingAuthority (wrappingID) {
-            const row = await db.selectFrom('kubun_credential_wrapping_authority').select([
-                'authority_token',
-                'refresh_seq'
-            ]).where('wrapping_id', '=', wrappingID).executeTakeFirst();
-            if (row == null) return undefined;
-            return {
-                envelope: row.authority_token,
-                refreshSeq: row.refresh_seq
-            };
+            return await db.transaction().execute(async (tx)=>await fn(createCredentialStore(tx, adapter, advisoryIDForKey)));
         },
-        async nextGrantorSequence (params) {
-            // Atomic INSERT ... ON CONFLICT DO UPDATE increments in place, so two
-            // concurrent callers can't observe the same seq. Normalize the tuple
-            // HERE (not left to callers) so a did:peer:4 recipient's short/long
-            // forms converge on one counter instead of splitting into two.
-            const row = await db.insertInto('kubun_credential_grantor_counters').values({
-                owner_did: normalizeDID(params.ownerDID),
-                recipient_did: normalizeDID(params.recipientDID),
-                grantor_did: normalizeDID(params.grantorDID),
-                seq: 1
-            }).onConflict((oc)=>oc.columns([
-                    'owner_did',
-                    'recipient_did',
-                    'grantor_did'
-                ]).doUpdateSet((eb)=>({
-                        seq: eb('kubun_credential_grantor_counters.seq', '+', 1)
-                    }))).returning('seq').executeTakeFirstOrThrow();
-            return row.seq;
+        async lockKeyRow (keyID) {
+            await gatedIfAmbient(async ()=>await lockKeyRowInTransaction(db, keyID));
         },
-        async nextProvisioningEpoch (params) {
-            // Atomic upsert to max(stored, minEpoch) + 1, guaranteeing monotonicity.
-            // Normalize the tuple HERE, same reasoning as `nextGrantorSequence`.
-            const ownerDid = normalizeDID(params.ownerDID);
-            const recipientDid = normalizeDID(params.recipientDID);
-            const grantorDid = normalizeDID(params.grantorDID);
-            const floor = Math.max(0, params.minEpoch);
-            const row = await db.insertInto('kubun_credential_provisioning_epochs').values({
-                owner_did: ownerDid,
-                recipient_did: recipientDid,
-                grantor_did: grantorDid,
-                epoch: floor + 1
-            }).onConflict((oc)=>oc.columns([
-                    'owner_did',
-                    'recipient_did',
-                    'grantor_did'
-                ]).doUpdateSet((eb)=>({
-                        // max(stored, floor) + 1, expressed without a portable GREATEST:
-                        epoch: eb.case().when('kubun_credential_provisioning_epochs.epoch', '<', floor).then(floor + 1).else(eb('kubun_credential_provisioning_epochs.epoch', '+', 1)).end()
-                    }))).returning('epoch').executeTakeFirstOrThrow();
-            return row.epoch;
+        async lockKeyRows (keyIDs) {
+            await gatedIfAmbient(async ()=>await lockKeyRowsInTransaction(db, keyIDs));
         },
-        async putManifest (record, token, delegationTokens) {
-            const values = {
-                owner_did: normalizeDID(record.ownerDID),
-                recipient_did: normalizeDID(record.recipientDID),
-                grantor_did: normalizeDID(record.grantorDID),
-                epoch: record.epoch,
-                sequence: record.sequence,
-                keys_json: adapter.encodeJSON(record.keys),
-                manifest_token: token,
-                delegation_tokens: adapter.encodeJSON(delegationTokens ?? [])
-            };
-            await db.insertInto('kubun_credential_manifests').values(values).onConflict((oc)=>oc.columns([
-                    'owner_did',
-                    'recipient_did',
-                    'grantor_did'
-                ]).doUpdateSet({
-                    epoch: values.epoch,
-                    sequence: values.sequence,
-                    keys_json: values.keys_json,
-                    manifest_token: values.manifest_token,
-                    delegation_tokens: values.delegation_tokens
-                })// Lexicographic: higher epoch always wins; within an epoch,
-                // strictly-greater sequence. A stale/replayed lower value is a silent no-op.
-                .where((eb)=>eb.or([
-                        eb('kubun_credential_manifests.epoch', '<', values.epoch),
-                        eb.and([
-                            eb('kubun_credential_manifests.epoch', '=', values.epoch),
-                            eb('kubun_credential_manifests.sequence', '<', values.sequence)
-                        ])
-                    ]))).execute();
-        },
-        async lockManifestRow (params) {
-            const owner = normalizeDID(params.ownerDID);
-            const recipient = normalizeDID(params.recipientDID);
-            const grantor = normalizeDID(params.grantorDID);
-            await writeAmbient(db, async (tx)=>{
-                await tx.updateTable('kubun_credential_manifests').set((eb)=>({
-                        epoch: eb.ref('kubun_credential_manifests.epoch')
-                    })).where('owner_did', '=', owner).where('recipient_did', '=', recipient).where('grantor_did', '=', grantor).execute();
-            });
-        },
-        async listManifests (params) {
-            const ownerDID = normalizeDID(params.ownerDID);
-            const recipientDID = normalizeDID(params.recipientDID);
-            const rows = await db.selectFrom('kubun_credential_manifests').select([
-                'owner_did',
-                'recipient_did',
-                'grantor_did',
-                'epoch',
-                'sequence',
-                'keys_json',
-                'manifest_token',
-                'delegation_tokens'
-            ]).where('owner_did', '=', ownerDID).where('recipient_did', '=', recipientDID).orderBy('grantor_did', 'asc').execute();
-            return rows.map((row)=>({
-                    record: {
-                        ownerDID: row.owner_did,
-                        recipientDID: row.recipient_did,
-                        grantorDID: row.grantor_did,
-                        epoch: row.epoch,
-                        sequence: row.sequence,
-                        keys: row.keys_json
-                    },
-                    token: row.manifest_token,
-                    delegationTokens: row.delegation_tokens
-                }));
-        },
-        async listDistributableKeys (params) {
-            const owner = normalizeDID(params.ownerDID);
-            const grantor = normalizeDID(params.grantorDID);
-            // One snapshot: active owner keys joined to wrappings at the key's current version.
-            const rows = await db.selectFrom('kubun_credential_keys as k').innerJoin('kubun_credential_wrappings as w', (join)=>join.onRef('w.key_id', '=', 'k.key_id').onRef('w.key_version', '=', 'k.version')).where('k.state', '=', 'active').select([
-                'k.key_id as keyID',
-                'k.version as version',
-                'k.owner_did as ownerDID',
-                'w.recipient_did as recipientDID'
-            ]).execute();
-            const seen = new Set();
-            const out = [];
-            for (const row of rows){
-                if (normalizeDID(row.ownerDID) !== owner) continue;
-                if (row.recipientDID == null || normalizeDID(row.recipientDID) !== grantor) continue;
-                if (seen.has(row.keyID)) continue;
-                seen.add(row.keyID);
-                out.push({
-                    keyID: row.keyID,
-                    version: row.version
-                });
-            }
-            return out;
-        },
-        async beginProvisioningAttempt (params) {
-            const ownerDid = normalizeDID(params.ownerDID);
-            const grantorDid = normalizeDID(params.grantorDID);
-            await writeAmbient(db, async (tx)=>{
-                // Ensure the expectation floor row exists, idempotent at floor 0.
-                await tx.insertInto('kubun_credential_provisioning_expectations').values({
-                    owner_did: ownerDid,
-                    grantor_did: grantorDid,
-                    epoch_floor: 0
-                }).onConflict((oc)=>oc.doNothing()).execute();
-                // Insert the outstanding attempt row, idempotent on the id.
-                await tx.insertInto('kubun_credential_provisioning_attempts').values({
-                    owner_did: ownerDid,
-                    grantor_did: grantorDid,
-                    attempt_id: params.attemptID
-                }).onConflict((oc)=>oc.doNothing()).execute();
-            });
-        },
-        async recordProvisioningAttempt (params) {
-            const ownerDid = normalizeDID(params.ownerDID);
-            const grantorDid = normalizeDID(params.grantorDID);
-            // Single atomic operation: if epoch > heldEpoch, delete attempt and raise floor.
-            let result = {
-                status: 'retry',
-                minEpoch: params.heldEpoch
-            };
-            await writeAmbient(db, async (tx)=>{
-                if (params.epoch > params.heldEpoch) {
-                    // Phantom-attempt guard: if the id names no live attempt, move
-                    // nothing — raising the floor for it would wedge readiness forever.
-                    const existing = await tx.selectFrom('kubun_credential_provisioning_attempts').select('attempt_id').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptID).executeTakeFirst();
-                    if (existing == null) {
-                        return;
-                    }
-                    // Delete the attempt row.
-                    await tx.deleteFrom('kubun_credential_provisioning_attempts').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptID).execute();
-                    // Raise the floor to max(stored, epoch).
-                    await tx.updateTable('kubun_credential_provisioning_expectations').set((eb)=>({
-                            epoch_floor: eb.case().when('epoch_floor', '<', params.epoch).then(params.epoch).else(eb.ref('epoch_floor')).end()
-                        })).where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).execute();
-                    result = {
-                        status: 'recorded'
-                    };
-                }
-            });
-            return result;
-        },
-        async abandonProvisioningAttempt (params) {
-            const ownerDid = normalizeDID(params.ownerDID);
-            const grantorDid = normalizeDID(params.grantorDID);
-            // Delete ONLY the attempt row, never the floor.
-            await db.deleteFrom('kubun_credential_provisioning_attempts').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).where('attempt_id', '=', params.attemptID).execute();
-        },
-        async abandonProvisioningAttempts (params) {
-            const ownerDid = normalizeDID(params.ownerDID);
-            const grantorDid = normalizeDID(params.grantorDID);
-            // Delete every attempt row for the scope, never the floor.
-            await db.deleteFrom('kubun_credential_provisioning_attempts').where('owner_did', '=', ownerDid).where('grantor_did', '=', grantorDid).execute();
-        },
-        async listProvisioningExpectations (params) {
-            const ownerDid = normalizeDID(params.ownerDID);
-            // Left join expectations to outstanding attempts, grouped by (owner, grantor).
-            // Return one row per (owner, grantor) with floor and outstanding count.
-            const rows = await db.selectFrom('kubun_credential_provisioning_expectations as e').leftJoin('kubun_credential_provisioning_attempts as a', (join)=>join.onRef('a.owner_did', '=', 'e.owner_did').onRef('a.grantor_did', '=', 'e.grantor_did')).select((eb)=>[
-                    'e.grantor_did as grantor_did',
-                    'e.epoch_floor as epoch_floor',
-                    eb.fn.count('a.attempt_id').as('outstanding')
-                ]).where('e.owner_did', '=', ownerDid).groupBy([
-                'e.owner_did',
-                'e.grantor_did',
-                'e.epoch_floor'
-            ]).orderBy('e.grantor_did', 'asc').execute();
-            return rows.map((row)=>({
-                    grantorDID: row.grantor_did,
-                    epochFloor: row.epoch_floor,
-                    outstanding: Number(row.outstanding)
-                }));
-        },
-        async listProvisioningExpectationOwners () {
-            const rows = await db.selectFrom('kubun_credential_provisioning_expectations').select('owner_did').distinct().execute();
-            const owners = new Set();
-            for (const row of rows){
-                owners.add(normalizeDID(row.owner_did));
-            }
-            return [
-                ...owners
-            ];
-        },
-        async refreshKeyOwnerDelegation (params) {
-            const values = {
-                key_id: params.keyID,
-                delegation_tokens: adapter.encodeJSON(params.delegationTokens),
-                refresh_seq: params.refreshSeq,
-                revision: 1
-            };
-            const result = await db.insertInto('kubun_credential_key_owner_delegation').values(values).onConflict((oc)=>oc.column('key_id').doUpdateSet({
-                    delegation_tokens: values.delegation_tokens,
-                    refresh_seq: values.refresh_seq,
-                    // Bump so a concurrent replace CAS on the pre-refresh revision fails.
-                    revision: (eb)=>eb('kubun_credential_key_owner_delegation.revision', '+', 1)
-                }).where('kubun_credential_key_owner_delegation.refresh_seq', '<', values.refresh_seq)).executeTakeFirst();
-            return (result.numInsertedOrUpdatedRows ?? 0n) > 0n;
-        },
-        async replaceKeyOwnerDelegationIfUnchanged (params) {
-            const result = await db.updateTable('kubun_credential_key_owner_delegation').set({
-                delegation_tokens: adapter.encodeJSON(params.delegationTokens),
-                refresh_seq: params.refreshSeq,
-                revision: (eb)=>eb('kubun_credential_key_owner_delegation.revision', '+', 1)
-            }).where('key_id', '=', params.keyID).where('revision', '=', params.expectedRevision).executeTakeFirst();
-            return (result.numUpdatedRows ?? 0n) > 0n;
-        },
-        async getKeyOwnerDelegation (keyID) {
-            const row = await db.selectFrom('kubun_credential_key_owner_delegation').select([
-                'delegation_tokens',
-                'refresh_seq',
-                'revision'
-            ]).where('key_id', '=', keyID).executeTakeFirst();
-            if (row == null) return undefined;
-            return {
-                delegationTokens: row.delegation_tokens,
-                refreshSeq: row.refresh_seq,
-                revision: row.revision
-            };
-        }
+        ...createKeysApi(ctx),
+        ...createEntriesApi(ctx),
+        ...createRecordsApi(ctx),
+        ...createAliasesApi(ctx),
+        ...createProvisioningApi(ctx)
     };
     return api;
 }
-/**
- * The ops leaf scan in stamp order — every one, or one key's. Two devices must
- * agree on this order, so it cannot be the insertion order, which is local.
- */ async function scanOps(db, keyID) {
-    let query = db.selectFrom('kubun_credential_ops').selectAll();
-    if (keyID != null) {
-        query = query.where('key_id', '=', keyID);
-    }
-    return await query.orderBy('hlc', 'asc').orderBy('subject_id', 'asc').execute();
-}