@kubun/store-graph 0.17.1 → 0.18.0

package/lib/catalog-merge.d.ts

@@ -0,0 +1,5 @@
+import type { CatalogRule } from './catalog-scope.js';
+import type { CatalogDefinition, CatalogMergeResult, MergeCatalogDefinitionsParams } from './catalog-types.js';
+export declare function orderMergedCatalogRules(local: ReadonlyArray<CatalogRule>, upstream: ReadonlyArray<CatalogRule>, selected: ReadonlyMap<string, CatalogRule>): Array<CatalogRule>;
+export declare function mergeCatalogDefinitions(params: MergeCatalogDefinitionsParams): CatalogMergeResult;
+export declare function catalogLocalRevisionID(definition: CatalogDefinition): string;

package/lib/catalog-merge.js

@@ -0,0 +1,117 @@
+import { digestJSON } from '@kubun/id';
+import { toB64U } from '@sozai/codec';
+import { CatalogScopeRulesEmptyError, canonicalCatalogRuleContent, InvalidCatalogScopeError, validateScopeCatalog } from './catalog-scope.js';
+function sameRule(left, right) {
+    if (left === null || right === null) return left === right;
+    return canonicalCatalogRuleContent(left) === canonicalCatalogRuleContent(right);
+}
+export function orderMergedCatalogRules(local, upstream, selected) {
+    const localIDs = local.map((r)=>r.id).filter((id)=>selected.has(id));
+    const localSurvivors = new Set(localIDs);
+    const beginning = [];
+    const after = new Map();
+    let anchor = null;
+    for (const rule of upstream){
+        if (localSurvivors.has(rule.id)) anchor = rule.id;
+        else if (selected.has(rule.id)) {
+            if (anchor === null) beginning.push(rule.id);
+            else after.set(anchor, [
+                ...after.get(anchor) ?? [],
+                rule.id
+            ]);
+        }
+    }
+    const ids = [
+        ...beginning,
+        ...localIDs.flatMap((id)=>[
+                id,
+                ...after.get(id) ?? []
+            ])
+    ];
+    return ids.map((id)=>{
+        const rule = selected.get(id);
+        if (rule === undefined) throw new InvalidCatalogScopeError('Missing selected catalog rule');
+        return rule;
+    });
+}
+export function mergeCatalogDefinitions(params) {
+    const { base, local, upstream, resolutions } = params;
+    const baseRules = new Map(base.rules.map((rule)=>[
+            rule.id,
+            rule
+        ]));
+    const localRules = new Map(local.rules.map((rule)=>[
+            rule.id,
+            rule
+        ]));
+    const upstreamRules = new Map(upstream.rules.map((rule)=>[
+            rule.id,
+            rule
+        ]));
+    const ids = new Set([
+        ...baseRules.keys(),
+        ...localRules.keys(),
+        ...upstreamRules.keys()
+    ]);
+    const selected = new Map();
+    const conflicts = [];
+    for (const ruleID of ids){
+        const baseRule = baseRules.get(ruleID) ?? null;
+        const localRule = localRules.get(ruleID) ?? null;
+        const upstreamRule = upstreamRules.get(ruleID) ?? null;
+        let rule = localRule;
+        if (sameRule(localRule, baseRule)) rule = upstreamRule;
+        else if (!sameRule(upstreamRule, baseRule) && !sameRule(localRule, upstreamRule)) {
+            conflicts.push({
+                ruleID,
+                base: baseRule,
+                local: localRule,
+                upstream: upstreamRule
+            });
+        }
+        if (rule !== null) selected.set(ruleID, rule);
+    }
+    if (resolutions !== undefined) {
+        const conflictMap = new Map(conflicts.map((conflict)=>[
+                conflict.ruleID,
+                conflict
+            ]));
+        const resolved = new Set();
+        for (const resolution of resolutions){
+            const conflict = conflictMap.get(resolution.ruleID);
+            if (conflict === undefined || resolved.has(resolution.ruleID) || resolution.side !== 'LOCAL' && resolution.side !== 'UPSTREAM') {
+                throw new InvalidCatalogScopeError('Invalid catalog rule resolution choice');
+            }
+            resolved.add(resolution.ruleID);
+            const rule = resolution.side === 'LOCAL' ? conflict.local : conflict.upstream;
+            if (rule === null) selected.delete(resolution.ruleID);
+            else selected.set(resolution.ruleID, rule);
+        }
+        if (resolved.size !== conflicts.length) {
+            throw new InvalidCatalogScopeError('Every catalog rule conflict needs one resolution');
+        }
+    }
+    const merged = {
+        name: local.name === base.name ? upstream.name : local.name,
+        description: local.description === base.description ? upstream.description : local.description,
+        app: local.app,
+        rules: orderMergedCatalogRules(local.rules, upstream.rules, selected)
+    };
+    if (merged.rules.length === 0) throw new CatalogScopeRulesEmptyError();
+    if (resolutions !== undefined) validateScopeCatalog(merged);
+    return {
+        merged,
+        conflicts
+    };
+}
+export function catalogLocalRevisionID(definition) {
+    return toB64U(digestJSON({
+        name: definition.name,
+        description: definition.description ?? null,
+        app: definition.app ?? null,
+        rules: definition.rules.map((rule)=>({
+                id: rule.id,
+                content: canonicalCatalogRuleContent(rule)
+            }))
+    }));
+}

package/lib/catalog-records.d.ts

@@ -0,0 +1,34 @@
+import type { MethodRegistry } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import { type Adapter } from '@kubun/db-adapter';
+import { type MergePolicy, type RecordDecision, type RecordKey, type RecordStoreAdapter, type SignedRecord, type VerifiedRecordOp } from '@kubun/records';
+import { type Kysely } from 'kysely';
+import type { GraphStoreAPI } from './api.js';
+import type { GraphTables } from './tables.js';
+export declare class GraphCatalogRecordTypeError extends Error {
+    constructor(type: string);
+}
+export declare class GraphCatalogRecordError extends Error {
+    constructor(message: string);
+}
+/** The merge policy the graph catalog store orders a type's decisions by. */
+export declare function catalogRecordPolicy(type: string): MergePolicy;
+export type GraphCatalogRecordMethods = {
+    getCatalogRecordDecision(key: RecordKey, methods?: MethodRegistry): Promise<RecordDecision | null>;
+    /** The decision of each key in `keys`, in order, from one read. */
+    getCatalogRecordDecisions(keys: ReadonlyArray<RecordKey>, methods?: MethodRegistry): Promise<Array<RecordDecision | null>>;
+    listCatalogRecordDecisions(types: ReadonlyArray<string>, methods?: MethodRegistry): Promise<Array<RecordDecision>>;
+    listCatalogRecordDecisionsForGroup(groupID: string, methods?: MethodRegistry): Promise<Array<RecordDecision>>;
+    putCatalogRecordCopy(record: SignedRecord, methods?: MethodRegistry): Promise<boolean>;
+    pruneCatalogRecordCopy(key: RecordKey, signerDID: string, methods?: MethodRegistry): Promise<void>;
+    lockCatalogRecordKeys(keys: ReadonlyArray<string>): Promise<void>;
+};
+export type GraphCatalogRecordMethodsParams = {
+    onClose?: (fn: () => void) => void;
+    /** Called once a custody assignment, acceptance or eligibility was stored, in the writing transaction. */
+    onCustodyRecordStored?: () => void;
+};
+export declare function createGraphCatalogRecordMethods(db: Kysely<GraphTables>, adapter: Adapter, params?: GraphCatalogRecordMethodsParams): GraphCatalogRecordMethods;
+export declare function graphCatalogRecordAdapter(provider: StoreProvider, methods?: MethodRegistry): Promise<RecordStoreAdapter>;
+export declare function graphStoreOfCatalogRecords(records: RecordStoreAdapter): GraphStoreAPI | null;
+export declare function verifyGraphCatalogRecord(records: RecordStoreAdapter, record: SignedRecord): Promise<VerifiedRecordOp | null>;

package/lib/catalog-records.js

@@ -0,0 +1,527 @@
+import { AbstractPostgresAdapter, chunked } from '@kubun/db-adapter';
+import { compareRecordOps, parseCanonicalHLC, recordClaimDigest, recordKeyText, recordPayloadMatches, recordSignerKey, verifySignedRecord } from '@kubun/records';
+import { sql } from 'kysely';
+function exposureVersion(claim) {
+    const stamp = typeof claim.meta.version === 'string' ? parseCanonicalHLC(claim.meta.version) : null;
+    return stamp === null ? [
+        Number.NaN
+    ] : [
+        stamp.wallTime,
+        stamp.counter
+    ];
+}
+function custodyGeneration(claim) {
+    const generation = claim.meta.generation;
+    return [
+        typeof generation === 'number' && Number.isSafeInteger(generation) && generation >= 0 ? generation : Number.NaN
+    ];
+}
+// The store decides with the same policy apply uses, so it never drops a write apply accepted.
+const POLICIES = new Map([
+    [
+        'catalog',
+        {
+            kind: 'lww'
+        }
+    ],
+    [
+        'catalog.exposure',
+        {
+            kind: 'monotonic',
+            versionOrder: 'hlc',
+            version: exposureVersion
+        }
+    ],
+    [
+        'catalog.version',
+        {
+            kind: 'immutable'
+        }
+    ],
+    [
+        'catalog.custody',
+        {
+            kind: 'monotonic',
+            version: custodyGeneration
+        }
+    ],
+    [
+        'catalog.custody-acceptance',
+        {
+            kind: 'lww'
+        }
+    ],
+    [
+        'catalog.custody-eligibility',
+        {
+            kind: 'lww'
+        }
+    ]
+]);
+const TYPES = new Set(POLICIES.keys());
+export class GraphCatalogRecordTypeError extends Error {
+    constructor(type){
+        super(`Unsupported graph catalog record type: ${type}`);
+        this.name = 'GraphCatalogRecordTypeError';
+    }
+}
+export class GraphCatalogRecordError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'GraphCatalogRecordError';
+    }
+}
+function requireType(type) {
+    if (!TYPES.has(type)) throw new GraphCatalogRecordTypeError(type);
+}
+/** The merge policy the graph catalog store orders a type's decisions by. */ export function catalogRecordPolicy(type) {
+    const policy = POLICIES.get(type);
+    if (policy === undefined) throw new GraphCatalogRecordTypeError(type);
+    return policy;
+}
+function copyFromRow(row) {
+    if ([
+        row.type,
+        row.owner,
+        row.id,
+        row.hlc,
+        row.op_jwt,
+        row.op_hash
+    ].some((value)=>typeof value !== 'string' || value.length === 0)) return null;
+    return {
+        type: row.type,
+        owner: row.owner,
+        id: row.id,
+        hlc: row.hlc,
+        opJWT: row.op_jwt,
+        opHash: row.op_hash,
+        payload: row.payload === null ? null : Uint8Array.from(row.payload)
+    };
+}
+const PEER4_PREFIX = 'did:peer:4';
+/**
+ * Issuers whose key is read from the DID itself: did:key, and long-form did:peer:4, which
+ * carries its document. Any other issuer may depend on resolution state that can change.
+ */ function isSelfCertifyingIssuer(issuer) {
+    return issuer.startsWith('did:key:') || issuer.startsWith(PEER4_PREFIX) && issuer.indexOf(':', PEER4_PREFIX.length) !== -1;
+}
+// Self-certifying rows, across transactions; others remain transaction-local per methods.
+const verifiedCopiesByAdapter = new WeakMap();
+const clearVerifiedCopiesByAdapter = new WeakMap();
+function sameRow(left, right) {
+    return left.type === right.type && left.owner === right.owner && left.id === right.id && left.op_hash === right.op_hash && left.hlc === right.hlc && left.op_jwt === right.op_jwt && left.catalog_id === right.catalog_id && left.group_id === right.group_id && left.circle_id === right.circle_id && (left.payload === null ? right.payload === null : right.payload !== null && left.payload.length === right.payload.length && left.payload.every((byte, index)=>byte === right.payload?.[index]));
+}
+async function verifiedRows(rows, caches, methods) {
+    const result = [];
+    const hashes = new Set(rows.map((row)=>row.op_hash));
+    for (const cache of [
+        caches.shared,
+        caches.local
+    ]){
+        if (cache == null) continue;
+        for (const hash of cache.keys())if (!hashes.has(hash)) cache.delete(hash);
+    }
+    const remember = (row, verified)=>{
+        if (verified !== null && caches.shared != null && isSelfCertifyingIssuer(verified.op.issuer)) {
+            caches.shared.set(row.op_hash, {
+                row,
+                verified
+            });
+        } else {
+            caches.shared?.delete(row.op_hash);
+            caches.local?.set(row.op_hash, {
+                row,
+                verified
+            });
+        }
+    };
+    for (const row of rows){
+        const known = [
+            caches.shared?.get(row.op_hash),
+            caches.local?.get(row.op_hash)
+        ].find((entry)=>entry !== undefined && sameRow(row, entry.row));
+        if (known !== undefined) {
+            if (known.verified !== null) result.push(known.verified);
+            continue;
+        }
+        const copy = copyFromRow(row);
+        if (copy === null) {
+            remember(row, null);
+            continue;
+        }
+        const op = await verifySignedRecord(copy, methods);
+        if (op === null || !recordPayloadMatches(copy, op.claim)) {
+            remember(row, null);
+            continue;
+        }
+        const signerKey = recordSignerKey(op.issuer, copy.opJWT);
+        if (signerKey === null) {
+            remember(row, null);
+            continue;
+        }
+        const decisionHLC = row.type === 'catalog.exposure' ? op.claim.meta.version : op.claim.hlc;
+        if (typeof decisionHLC !== 'string' || parseCanonicalHLC(decisionHLC) === null) {
+            remember(row, null);
+            continue;
+        }
+        const verified = {
+            row,
+            copy,
+            op,
+            signerKey,
+            decisionHLC,
+            contentDigest: recordClaimDigest(op.claim)
+        };
+        remember(row, verified);
+        result.push(verified);
+    }
+    return result;
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function sameDecision(left, right) {
+    return left.decisionHLC === right.decisionHLC && left.contentDigest === right.contentDigest;
+}
+/** Whether `incoming` replaces `stored` under the type's policy; a fork keeps the greater digest. */ function prefers(incoming, stored, policy) {
+    const decision = compareRecordOps(incoming.op, stored?.op ?? null, policy);
+    return decision.status === 'apply' || decision.status === 'fork' && stored !== null && compareStrings(incoming.contentDigest, stored.contentDigest) > 0;
+}
+function winningRow(key, rows) {
+    const policy = catalogRecordPolicy(key.type);
+    let winner = null;
+    for (const entry of rows){
+        if (winner !== null && sameDecision(entry, winner)) continue;
+        if (prefers(entry, winner, policy)) winner = entry;
+    }
+    return winner;
+}
+function decisionFromVerified(key, copies) {
+    const winner = winningRow(key, copies);
+    if (winner === null) return null;
+    return {
+        key,
+        decisionHLC: winner.decisionHLC,
+        contentDigest: winner.contentDigest,
+        copies: copies.filter((entry)=>sameDecision(entry, winner)).map(({ copy })=>({
+                ...copy,
+                payload: copy.payload?.slice() ?? null
+            })).sort((a, b)=>compareStrings(a.opHash, b.opHash))
+    };
+}
+const CUSTODY_TYPES = new Set([
+    'catalog.custody',
+    'catalog.custody-acceptance',
+    'catalog.custody-eligibility'
+]);
+export function createGraphCatalogRecordMethods(db, adapter, params = {}) {
+    const { onClose } = params;
+    let clearShared = clearVerifiedCopiesByAdapter.get(adapter);
+    if (clearShared === undefined) {
+        clearShared = ()=>verifiedCopiesByAdapter.delete(adapter);
+        clearVerifiedCopiesByAdapter.set(adapter, clearShared);
+    }
+    onClose?.(clearShared);
+    const verifiedCopies = new Map();
+    const cachesFor = (address, methods)=>{
+        const caches = {};
+        // Whatever the methods: only self-certifying rows enter it, and those never consult them.
+        let byKey = verifiedCopiesByAdapter.get(adapter);
+        if (byKey === undefined) {
+            byKey = new Map();
+            verifiedCopiesByAdapter.set(adapter, byKey);
+        }
+        caches.shared = byKey.get(address) ?? new Map();
+        byKey.set(address, caches.shared);
+        if (db.isTransaction) {
+            let byMethods = verifiedCopies.get(address);
+            if (byMethods === undefined) {
+                byMethods = new Map();
+                verifiedCopies.set(address, byMethods);
+            }
+            caches.local = byMethods.get(methods) ?? new Map();
+            byMethods.set(methods, caches.local);
+        }
+        return caches;
+    };
+    const verifiedRowsFor = async (key, rows, methods)=>{
+        const address = JSON.stringify([
+            key.type,
+            key.owner,
+            key.id
+        ]);
+        // A key without rows keeps no cache entry, and with it no copy of its last row.
+        if (rows.length === 0) {
+            verifiedCopiesByAdapter.get(adapter)?.delete(address);
+            verifiedCopies.delete(address);
+            return [];
+        }
+        const verified = await verifiedRows(rows, cachesFor(address, methods), methods);
+        // Rows the shared cache may not hold leave its entry empty.
+        const byKey = verifiedCopiesByAdapter.get(adapter);
+        if (byKey?.get(address)?.size === 0) byKey.delete(address);
+        return verified;
+    };
+    const lockKeys = async (tx, keys)=>{
+        if (!(adapter instanceof AbstractPostgresAdapter)) return;
+        for (const key of [
+            ...new Set(keys)
+        ].sort(compareStrings)){
+            await sql`select pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(tx);
+        }
+    };
+    const keyText = (key)=>JSON.stringify([
+            key.type,
+            key.owner,
+            key.id
+        ]);
+    const rowsFor = async (key)=>await db.selectFrom('kubun_graph_catalog_records').selectAll().where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).execute();
+    const decisionsFromRows = async (rows, methods)=>{
+        const groups = new Map();
+        for (const row of rows){
+            const id = JSON.stringify([
+                row.type,
+                row.owner,
+                row.id
+            ]);
+            const group = groups.get(id) ?? [];
+            group.push(row);
+            groups.set(id, group);
+        }
+        const decisions = [];
+        for (const group of groups.values()){
+            const first = group[0];
+            if (first === undefined) continue;
+            const key = {
+                type: first.type,
+                owner: first.owner,
+                id: first.id
+            };
+            const decision = decisionFromVerified(key, await verifiedRowsFor(key, group, methods));
+            if (decision !== null) decisions.push(decision);
+        }
+        return decisions;
+    };
+    return {
+        async getCatalogRecordDecision (key, methods) {
+            requireType(key.type);
+            return decisionFromVerified(key, await verifiedRowsFor(key, await rowsFor(key), methods));
+        },
+        async getCatalogRecordDecisions (keys, methods) {
+            for (const key of keys)requireType(key.type);
+            if (keys.length === 0) return [];
+            // The exact keys as one row-value list: an OR per key would nest one
+            // expression level each, past SQLite's depth limit for large batches.
+            const unique = new Map(keys.map((key)=>[
+                    keyText(key),
+                    key
+                ]));
+            const wanted = sql.join(Array.from(unique.values(), (key)=>sql`(${key.type}, ${key.owner}, ${key.id})`));
+            const rows = await db.selectFrom('kubun_graph_catalog_records').selectAll().where(sql`(${sql.ref('type')}, ${sql.ref('owner')}, ${sql.ref('id')}) in (values ${wanted})`).execute();
+            const rowsByKey = new Map();
+            for (const row of rows){
+                const text = keyText(row);
+                const group = rowsByKey.get(text) ?? [];
+                group.push(row);
+                rowsByKey.set(text, group);
+            }
+            const decisions = new Map();
+            for (const key of keys){
+                const text = keyText(key);
+                if (decisions.has(text)) continue;
+                decisions.set(text, decisionFromVerified(key, await verifiedRowsFor(key, rowsByKey.get(text) ?? [], methods)));
+            }
+            return keys.map((key)=>decisions.get(keyText(key)) ?? null);
+        },
+        async listCatalogRecordDecisions (types, methods) {
+            for (const type of types)requireType(type);
+            if (types.length === 0) return [];
+            const rows = await db.selectFrom('kubun_graph_catalog_records').selectAll().where('type', 'in', [
+                ...types
+            ]).orderBy('type').orderBy('owner').orderBy('id').execute();
+            return await decisionsFromRows(rows, methods);
+        },
+        async listCatalogRecordDecisionsForGroup (groupID, methods) {
+            const rows = await db.selectFrom('kubun_graph_catalog_records').selectAll().where('type', '=', 'catalog.exposure').where('group_id', '=', groupID).orderBy('owner').orderBy('id').execute();
+            return await decisionsFromRows(rows, methods);
+        },
+        async putCatalogRecordCopy (record, methods) {
+            requireType(record.type);
+            const op = await verifySignedRecord(record, methods);
+            if (op === null || !recordPayloadMatches(record, op.claim)) throw new GraphCatalogRecordError('Catalog record is not a valid signed copy');
+            const signerKey = recordSignerKey(op.issuer, record.opJWT);
+            if (signerKey === null) throw new GraphCatalogRecordError('Catalog signer key is invalid');
+            const key = {
+                type: record.type,
+                owner: record.owner,
+                id: record.id
+            };
+            const incomingHLC = record.type === 'catalog.exposure' ? op.claim.meta.version : op.claim.hlc;
+            if (typeof incomingHLC !== 'string' || parseCanonicalHLC(incomingHLC) === null) return false;
+            const incomingDigest = recordClaimDigest(op.claim);
+            const write = async (tx)=>{
+                await lockKeys(tx, [
+                    keyText(key)
+                ]);
+                const rows = await tx.selectFrom('kubun_graph_catalog_records').selectAll().where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).execute();
+                const valid = await verifiedRowsFor(key, rows, methods);
+                const winner = winningRow(key, valid);
+                if (record.type === 'catalog' && record.payload !== null && winner !== null && winner.copy.payload === null) return false;
+                const incoming = {
+                    op,
+                    decisionHLC: incomingHLC,
+                    contentDigest: incomingDigest
+                };
+                const retained = winner !== null && sameDecision(incoming, winner) ? valid.filter((entry)=>sameDecision(entry, incoming)) : [];
+                if (retained.length === 0 && !prefers(incoming, winner, catalogRecordPolicy(key.type))) return false;
+                const keepBySigner = new Map([
+                    [
+                        signerKey,
+                        record.opHash
+                    ]
+                ]);
+                for (const entry of retained){
+                    const previous = keepBySigner.get(entry.signerKey);
+                    if (previous === undefined || compareStrings(entry.copy.opHash, previous) < 0) {
+                        keepBySigner.set(entry.signerKey, entry.copy.opHash);
+                    }
+                }
+                for (const row of rows){
+                    const entry = retained.find((candidate)=>candidate.row.op_hash === row.op_hash);
+                    if (entry === undefined || keepBySigner.get(entry.signerKey) !== row.op_hash) {
+                        await tx.deleteFrom('kubun_graph_catalog_records').where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', '=', row.op_hash).execute();
+                    }
+                }
+                if (keepBySigner.get(signerKey) !== record.opHash) return false;
+                const meta = op.claim.meta;
+                await tx.insertInto('kubun_graph_catalog_records').values({
+                    type: record.type,
+                    owner: record.owner,
+                    id: record.id,
+                    op_hash: record.opHash,
+                    hlc: record.hlc,
+                    op_jwt: record.opJWT,
+                    payload: record.payload === null ? null : adapter.encodeBinary(record.payload),
+                    catalog_id: typeof meta.catalogID === 'string' ? meta.catalogID : null,
+                    group_id: typeof meta.groupID === 'string' ? meta.groupID : null,
+                    circle_id: typeof meta.circleID === 'string' ? meta.circleID : null
+                }).onConflict((oc)=>oc.columns([
+                        'type',
+                        'owner',
+                        'id',
+                        'op_hash'
+                    ]).doNothing()).execute();
+                return true;
+            };
+            const stored = db.isTransaction ? await write(db) : await db.transaction().execute(write);
+            if (stored && CUSTODY_TYPES.has(record.type)) params.onCustodyRecordStored?.();
+            return stored;
+        },
+        async pruneCatalogRecordCopy (key, signerDID, methods) {
+            requireType(key.type);
+            const write = async (tx)=>{
+                await lockKeys(tx, [
+                    keyText(key)
+                ]);
+                const valid = await verifiedRowsFor(key, await tx.selectFrom('kubun_graph_catalog_records').selectAll().where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).execute(), methods);
+                if (valid.filter((entry)=>entry.op.issuer !== signerDID).length === 0) return;
+                for (const entry of valid){
+                    if (entry.op.issuer !== signerDID) continue;
+                    await tx.deleteFrom('kubun_graph_catalog_records').where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', '=', entry.copy.opHash).execute();
+                }
+            };
+            if (db.isTransaction) await write(db);
+            else await db.transaction().execute(write);
+        },
+        async lockCatalogRecordKeys (keys) {
+            if (!db.isTransaction) throw new GraphCatalogRecordError('Catalog record locks require a transaction');
+            await lockKeys(db, keys);
+        }
+    };
+}
+export async function graphCatalogRecordAdapter(provider, methods) {
+    const graph = await provider.getStore('graph');
+    const records = {
+        isTransaction: provider.isTransactionBound,
+        async transaction (fn) {
+            return await provider.withTransaction(async (tx)=>await fn(await graphCatalogRecordAdapter(tx, methods)));
+        },
+        async get (key) {
+            requireType(key.type);
+            return await graph.getCatalogRecordDecision(key, methods);
+        },
+        async getMany (keys) {
+            for (const key of keys)requireType(key.type);
+            const decisions = new Map();
+            for (const chunk of chunked(keys)){
+                const found = await graph.getCatalogRecordDecisions(chunk, methods);
+                chunk.forEach((key, index)=>{
+                    const decision = found[index];
+                    if (decision != null) decisions.set(recordKeyText(key), decision);
+                });
+            }
+            return decisions;
+        },
+        async list (types) {
+            for (const type of types)requireType(type);
+            return await graph.listCatalogRecordDecisions(types, methods);
+        },
+        async listByGroup (type, groupID) {
+            if (type !== 'catalog.exposure') throw new GraphCatalogRecordTypeError(type);
+            return await graph.listCatalogRecordDecisionsForGroup(groupID, methods);
+        },
+        async putCopy (record) {
+            requireType(record.type);
+            await graph.putCatalogRecordCopy(record, methods);
+        },
+        async pruneCopy (key, signerDID) {
+            requireType(key.type);
+            await graph.pruneCatalogRecordCopy(key, signerDID, methods);
+        },
+        async lock (keys) {
+            for (const key of keys)requireType(key.type);
+            await graph.lockCatalogRecordKeys(keys.map((entry)=>JSON.stringify([
+                    entry.type,
+                    entry.key
+                ])));
+        }
+    };
+    graphStores.set(records, graph);
+    verificationMethods.set(records, methods);
+    return records;
+}
+const graphStores = new WeakMap();
+const verificationMethods = new WeakMap();
+export function graphStoreOfCatalogRecords(records) {
+    return graphStores.get(records) ?? null;
+}
+const VERIFIED_OPS_LIMIT = 4096;
+// Ops of self-certifying issuers, by every record field verification reads: they verify the same
+// under any methods. Callers verify copies a read already verified, to learn the op; recompute
+// does so for every custody guard of every document.
+const verifiedOps = new Map();
+export async function verifyGraphCatalogRecord(records, record) {
+    const key = JSON.stringify([
+        record.opJWT,
+        record.type,
+        record.owner,
+        record.id,
+        record.hlc,
+        record.opHash
+    ]);
+    const known = verifiedOps.get(key);
+    if (known !== undefined) {
+        verifiedOps.delete(key);
+        verifiedOps.set(key, known);
+        return known;
+    }
+    const op = await verifySignedRecord(record, verificationMethods.get(records));
+    if (op !== null && isSelfCertifyingIssuer(op.issuer)) {
+        if (verifiedOps.size >= VERIFIED_OPS_LIMIT) {
+            const oldest = verifiedOps.keys().next().value;
+            if (oldest !== undefined) verifiedOps.delete(oldest);
+        }
+        verifiedOps.set(key, op);
+    }
+    return op;
+}