@kubun/store-connector 0.17.1 → 0.18.0

package/lib/observation-records.d.ts

@@ -0,0 +1,52 @@
+import type { MethodRegistry } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import { type Adapter } from '@kubun/db-adapter';
+import { type RecordDecision, type RecordKey, type RecordStoreAdapter, type SignedRecord } from '@kubun/records';
+import { type Kysely } from 'kysely';
+import type { ConnectorTables } from './tables.js';
+export declare function observationProviderOfRecords(records: RecordStoreAdapter): StoreProvider | null;
+export declare class ConnectorObservationRecordTypeError extends Error {
+    constructor(type: string);
+}
+export declare class ConnectorObservationRecordError extends Error {
+    constructor(message: string);
+}
+export type ObservationRepair = {
+    documentID: string;
+    owner: string;
+    fetchHLC: string;
+    decisionHLC: string;
+    present: boolean;
+    valueDigest: string | null;
+};
+/** Where a reader of obligation writes stands: the last write it took. */
+export type ObservationRepairWrite = {
+    writtenAt: number;
+    documentID: string;
+};
+/** An obligation with the time it was last written. */
+export type WrittenObservationRepair = ObservationRepair & {
+    writtenAt: number;
+};
+export type ObservationRepairWritePage = {
+    after: ObservationRepairWrite | null;
+    limit: number;
+};
+export type ObservationRecordMethods = {
+    getObservationRecordDecision(key: RecordKey, methods?: MethodRegistry): Promise<RecordDecision | null>;
+    /** The decisions of many keys read together; a key with no valid copy is absent. */
+    getObservationRecordDecisions(keys: ReadonlyArray<RecordKey>, methods?: MethodRegistry): Promise<Array<RecordDecision>>;
+    listObservationRecordDecisions(types: ReadonlyArray<string>, methods?: MethodRegistry): Promise<Array<RecordDecision>>;
+    putObservationRecordCopy(record: SignedRecord, methods?: MethodRegistry): Promise<void>;
+    pruneObservationRecordCopy(key: RecordKey, signerDID: string, methods?: MethodRegistry): Promise<void>;
+    lockObservationRecordKeys(keys: ReadonlyArray<string>): Promise<void>;
+    getObservationRepair(documentID: string): Promise<ObservationRepair | null>;
+    /** The obligations of many documents read together; a document with none is absent. */
+    getObservationRepairs(documentIDs: ReadonlyArray<string>): Promise<Map<string, ObservationRepair>>;
+    /** One page of repair obligations in write order, written after `after`. */
+    listObservationRepairsWrittenSince(page: ObservationRepairWritePage): Promise<Array<WrittenObservationRepair>>;
+    putObservationRepair(repair: ObservationRepair): Promise<void>;
+    clearObservationRepair(documentID: string): Promise<void>;
+};
+export declare function createObservationRecordMethods(db: Kysely<ConnectorTables>, adapter: Adapter): ObservationRecordMethods;
+export declare function connectorObservationRecordAdapter(provider: StoreProvider, methods?: MethodRegistry): Promise<RecordStoreAdapter>;

package/lib/observation-records.js

@@ -0,0 +1,310 @@
+import { AbstractPostgresAdapter, chunked } from '@kubun/db-adapter';
+import { compareRecordDecisionHLC, parseCanonicalHLC, recordClaimDigest, recordDecisionFromVerifiedCopies, recordKeyText, recordPayloadMatches, recordSignerKey, verifySignedRecord } from '@kubun/records';
+import { sql } from 'kysely';
+const TYPE = 'connector.observation';
+const providers = new WeakMap();
+export function observationProviderOfRecords(records) {
+    return providers.get(records) ?? null;
+}
+export class ConnectorObservationRecordTypeError extends Error {
+    constructor(type){
+        super(`Unsupported connector observation record type: ${type}`);
+        this.name = 'ConnectorObservationRecordTypeError';
+    }
+}
+export class ConnectorObservationRecordError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'ConnectorObservationRecordError';
+    }
+}
+function requireType(type) {
+    if (type !== TYPE) throw new ConnectorObservationRecordTypeError(type);
+}
+function lockKey(key) {
+    return JSON.stringify([
+        key.type,
+        JSON.stringify([
+            key.owner,
+            key.id
+        ])
+    ]);
+}
+function copyFromRow(row) {
+    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)
+    };
+}
+async function verifiedRows(rows, methods) {
+    const result = [];
+    for (const row of rows){
+        const copy = copyFromRow(row);
+        const op = await verifySignedRecord(copy, methods);
+        if (op === null || !recordPayloadMatches(copy, op.claim)) continue;
+        if (typeof op.claim.meta.version !== 'string' || parseCanonicalHLC(op.claim.meta.version) === null) continue;
+        const signerKey = recordSignerKey(op.issuer, copy.opJWT);
+        if (signerKey !== null) result.push({
+            row,
+            copy,
+            op,
+            signerKey
+        });
+    }
+    return result;
+}
+function decision(key, rows) {
+    return recordDecisionFromVerifiedCopies(key, rows, 'version');
+}
+function repairFromRow(row) {
+    return {
+        documentID: row.document_id,
+        owner: row.owner,
+        fetchHLC: row.fetch_hlc,
+        decisionHLC: row.decision_hlc,
+        present: row.present === 1,
+        valueDigest: row.value_digest
+    };
+}
+export function createObservationRecordMethods(db, adapter) {
+    const rowsFor = async (key, tx = db)=>await tx.selectFrom('kubun_connector_observation_records').selectAll().where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).execute();
+    const lockKeys = async (tx, keys)=>{
+        if (!(adapter instanceof AbstractPostgresAdapter)) return;
+        for (const key of [
+            ...new Set(keys)
+        ].sort())await sql`select pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(tx);
+    };
+    const write = async (fn)=>db.isTransaction ? await fn(db) : await db.transaction().execute(fn);
+    return {
+        async getObservationRecordDecision (key, methods) {
+            requireType(key.type);
+            return decision(key, await verifiedRows(await rowsFor(key), methods));
+        },
+        async getObservationRecordDecisions (keys, methods) {
+            for (const key of keys)requireType(key.type);
+            const wanted = new Map();
+            for (const key of keys)wanted.set(JSON.stringify([
+                key.owner,
+                key.id
+            ]), key);
+            const ids = [
+                ...new Set(keys.map((key)=>key.id))
+            ];
+            const groups = new Map();
+            for (const chunk of chunked(ids)){
+                const rows = await db.selectFrom('kubun_connector_observation_records').selectAll().where('type', '=', TYPE).where('id', 'in', chunk).execute();
+                for (const row of rows){
+                    const address = JSON.stringify([
+                        row.owner,
+                        row.id
+                    ]);
+                    if (!wanted.has(address)) continue;
+                    const group = groups.get(address) ?? [];
+                    group.push(row);
+                    groups.set(address, group);
+                }
+            }
+            const result = [];
+            for (const [address, group] of groups){
+                const key = wanted.get(address);
+                if (key === undefined) continue;
+                const current = decision(key, await verifiedRows(group, methods));
+                if (current !== null) result.push(current);
+            }
+            return result;
+        },
+        async listObservationRecordDecisions (types, methods) {
+            for (const type of types)requireType(type);
+            if (types.length === 0) return [];
+            const rows = await db.selectFrom('kubun_connector_observation_records').selectAll().where('type', '=', TYPE).orderBy('owner').orderBy('id').execute();
+            const groups = new Map();
+            for (const row of rows){
+                const address = JSON.stringify([
+                    row.owner,
+                    row.id
+                ]);
+                const group = groups.get(address) ?? [];
+                group.push(row);
+                groups.set(address, group);
+            }
+            const result = [];
+            for (const group of groups.values()){
+                const first = group[0];
+                if (first === undefined) continue;
+                const current = decision({
+                    type: TYPE,
+                    owner: first.owner,
+                    id: first.id
+                }, await verifiedRows(group, methods));
+                if (current !== null) result.push(current);
+            }
+            return result;
+        },
+        async putObservationRecordCopy (record, methods) {
+            requireType(record.type);
+            const op = await verifySignedRecord(record, methods);
+            if (op === null || !recordPayloadMatches(record, op.claim)) throw new ConnectorObservationRecordError('Observation record is not a valid signed copy');
+            const version = op.claim.meta.version;
+            if (typeof version !== 'string' || parseCanonicalHLC(version) === null) throw new ConnectorObservationRecordError('Observation decision version is invalid');
+            const signerKey = recordSignerKey(op.issuer, record.opJWT);
+            if (signerKey === null) throw new ConnectorObservationRecordError('Observation signer key is invalid');
+            const key = {
+                type: TYPE,
+                owner: record.owner,
+                id: record.id
+            };
+            await write(async (tx)=>{
+                await lockKeys(tx, [
+                    lockKey(key)
+                ]);
+                const rows = await rowsFor(key, tx);
+                const valid = await verifiedRows(rows, methods);
+                const current = decision(key, valid);
+                const digest = recordClaimDigest(op.claim);
+                const order = current === null ? 1 : compareRecordDecisionHLC(version, current.decisionHLC) || (digest < current.contentDigest ? -1 : digest > current.contentDigest ? 1 : 0);
+                if (order < 0) return;
+                const retained = order === 0 ? valid.filter((entry)=>entry.op.claim.meta.version === version && recordClaimDigest(entry.op.claim) === digest) : [];
+                const sameSigner = retained.find((entry)=>entry.signerKey === signerKey);
+                const incomingWinsSigner = sameSigner === undefined || record.opHash < sameSigner.copy.opHash;
+                for (const row of rows){
+                    const entry = retained.find((candidate)=>candidate.row.op_hash === row.op_hash);
+                    if (entry !== undefined && entry.signerKey !== signerKey) continue;
+                    if (entry !== undefined && !incomingWinsSigner && entry.copy.opHash === sameSigner?.copy.opHash) continue;
+                    await tx.deleteFrom('kubun_connector_observation_records').where('type', '=', TYPE).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', '=', row.op_hash).execute();
+                }
+                if (!incomingWinsSigner) return;
+                await tx.insertInto('kubun_connector_observation_records').values({
+                    type: 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)
+                }).onConflict((oc)=>oc.columns([
+                        'type',
+                        'owner',
+                        'id',
+                        'op_hash'
+                    ]).doNothing()).execute();
+            });
+        },
+        async pruneObservationRecordCopy (key, signerDID, methods) {
+            requireType(key.type);
+            await write(async (tx)=>{
+                await lockKeys(tx, [
+                    lockKey(key)
+                ]);
+                const valid = await verifiedRows(await rowsFor(key, tx), 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_connector_observation_records').where('type', '=', TYPE).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', '=', entry.copy.opHash).execute();
+                }
+            });
+        },
+        async lockObservationRecordKeys (keys) {
+            if (!db.isTransaction) throw new ConnectorObservationRecordError('Observation locks require a transaction');
+            await lockKeys(db, keys);
+        },
+        async getObservationRepair (documentID) {
+            const row = await db.selectFrom('kubun_connector_observation_repair').selectAll().where('document_id', '=', documentID).executeTakeFirst();
+            return row === undefined ? null : repairFromRow(row);
+        },
+        async getObservationRepairs (documentIDs) {
+            const repairs = new Map();
+            for (const ids of chunked([
+                ...documentIDs
+            ])){
+                const rows = await db.selectFrom('kubun_connector_observation_repair').selectAll().where('document_id', 'in', ids).execute();
+                for (const row of rows)repairs.set(row.document_id, repairFromRow(row));
+            }
+            return repairs;
+        },
+        async listObservationRepairsWrittenSince (page) {
+            let query = db.selectFrom('kubun_connector_observation_repair').selectAll().orderBy('written_at').orderBy('document_id').limit(page.limit);
+            const after = page.after;
+            if (after !== null) {
+                query = query.where((eb)=>eb.or([
+                        eb('written_at', '>', after.writtenAt),
+                        eb.and([
+                            eb('written_at', '=', after.writtenAt),
+                            eb('document_id', '>', after.documentID)
+                        ])
+                    ]));
+            }
+            return (await query.execute()).map((row)=>({
+                    ...repairFromRow(row),
+                    writtenAt: Number(row.written_at)
+                }));
+        },
+        async putObservationRepair (repair) {
+            const values = {
+                owner: repair.owner,
+                fetch_hlc: repair.fetchHLC,
+                decision_hlc: repair.decisionHLC,
+                present: repair.present ? 1 : 0,
+                value_digest: repair.valueDigest,
+                written_at: Date.now()
+            };
+            await db.insertInto('kubun_connector_observation_repair').values({
+                document_id: repair.documentID,
+                ...values
+            }).onConflict((oc)=>oc.column('document_id').doUpdateSet(values)).execute();
+        },
+        async clearObservationRepair (documentID) {
+            await db.deleteFrom('kubun_connector_observation_repair').where('document_id', '=', documentID).execute();
+        }
+    };
+}
+export async function connectorObservationRecordAdapter(provider, methods) {
+    const connector = await provider.getStore('connector');
+    const records = {
+        isTransaction: provider.isTransactionBound,
+        async transaction (fn) {
+            return await provider.withTransaction(async (tx)=>await fn(await connectorObservationRecordAdapter(tx, methods)));
+        },
+        async get (key) {
+            requireType(key.type);
+            return await connector.getObservationRecordDecision(key, methods);
+        },
+        async getMany (keys) {
+            for (const key of keys)requireType(key.type);
+            const decisions = new Map();
+            for (const decision of (await connector.getObservationRecordDecisions(keys, methods))){
+                decisions.set(recordKeyText(decision.key), decision);
+            }
+            return decisions;
+        },
+        async list (types) {
+            for (const type of types)requireType(type);
+            return await connector.listObservationRecordDecisions(types, methods);
+        },
+        async putCopy (record) {
+            requireType(record.type);
+            await connector.putObservationRecordCopy(record, methods);
+        },
+        async pruneCopy (key, signerDID) {
+            requireType(key.type);
+            await connector.pruneObservationRecordCopy(key, signerDID, methods);
+        },
+        async lock (keys) {
+            for (const key of keys)requireType(key.type);
+            await connector.lockObservationRecordKeys(keys.map((key)=>JSON.stringify([
+                    key.type,
+                    key.key
+                ])));
+        },
+        async getObservationDocumentOwner (documentID) {
+            const graph = await provider.getStore('graph');
+            return (await graph.getDocument(documentID))?.owner ?? null;
+        }
+    };
+    providers.set(records, provider);
+    return records;
+}

package/lib/operations.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export type OperationsMethods = Pick<ConnectorStoreAPI, 'claimOperation' | 'acquireLease' | 'renewLease' | 'releaseLease' | 'getOperation' | 'listTrackedOperations' | 'hasNewerOperationOnDocument' | 'markSendStarted' | 'deferOperation' | 'recordOperation'>;
+export declare function createOperationsMethods(context: ConnectorStoreContext): OperationsMethods;

package/lib/operations.js

@@ -0,0 +1,223 @@
+import { chunked, IN_LIST_CHUNK } from '@kubun/db-adapter';
+import { encodeJSONColumn, rowToOperation } from './serialization.js';
+// The `send_marker` of an attempt that more than one run marked. It matches
+// no run's marker, so no run of that attempt can refund it.
+const CONTESTED_SEND_MARKER = '*contested*';
+// The `listTrackedOperations` order: oldest first, then caller and operation id.
+function compareOperations(a, b) {
+    if (a.createdAt !== b.createdAt) return a.createdAt - b.createdAt;
+    if (a.callerDID !== b.callerDID) return a.callerDID < b.callerDID ? -1 : 1;
+    if (a.operationID !== b.operationID) return a.operationID < b.operationID ? -1 : 1;
+    return 0;
+}
+export function createOperationsMethods(context) {
+    const { db, getRandomID } = context;
+    const methods = {
+        // --- Connector write-back operation envelope ---
+        async claimOperation (input) {
+            const now = Date.now();
+            // INSERT ... ON CONFLICT DO NOTHING RETURNING *, mirroring the insert-race
+            // half of `updateSyncProgress`: a fresh key wins the insert and is
+            // returned directly; a conflicting key returns nothing here and falls
+            // through to the read+compare below.
+            const insertedRow = await db.insertInto('kubun_connector_operation').values({
+                caller_did: input.callerDID,
+                operation_id: input.operationID,
+                node_key: getRandomID(),
+                owner_did: input.ownerDID,
+                connector_name: input.connectorName,
+                model: input.model,
+                op: input.op,
+                account_key: input.accountKey,
+                target: input.target,
+                source_id: input.sourceID,
+                deterministic_event_id: input.deterministicEventID,
+                payload_hash: input.payloadHash,
+                reissue_intent: encodeJSONColumn(input.reissueIntent) ?? 'null',
+                provider_etag: input.providerEtag ?? null,
+                document_id: input.documentID ?? null,
+                result_entity: null,
+                state: 'attempted',
+                attempts: 0,
+                next_attempt_at: null,
+                last_kind: null,
+                last_http_status: null,
+                version: 0,
+                incarnation: getRandomID(),
+                lease_token: input.leaseToken,
+                lease_expires_at: input.leaseExpiresAt,
+                created_at: now,
+                updated_at: now
+            }).onConflict((oc)=>oc.columns([
+                    'caller_did',
+                    'operation_id'
+                ]).doNothing()).returningAll().executeTakeFirst();
+            if (insertedRow != null) {
+                return {
+                    status: 'claimed',
+                    record: rowToOperation(insertedRow)
+                };
+            }
+            const row = await db.selectFrom('kubun_connector_operation').selectAll().where('caller_did', '=', input.callerDID).where('operation_id', '=', input.operationID).executeTakeFirst();
+            if (row == null) {
+                // The conflicting row vanished between the failed insert and this read
+                // (e.g. a concurrent delete) — neither a match nor a safe claim.
+                return {
+                    status: 'conflict'
+                };
+            }
+            // The immutable envelope tuple: equal on every field → the identical
+            // request replayed (`exists`); any drift is a genuine conflict, and the
+            // stored row is never overwritten.
+            const envelopeMatches = row.owner_did === input.ownerDID && row.connector_name === input.connectorName && row.model === input.model && row.op === input.op && row.account_key === input.accountKey && row.source_id === input.sourceID && row.deterministic_event_id === input.deterministicEventID && row.target === input.target && row.payload_hash === input.payloadHash;
+            return envelopeMatches ? {
+                status: 'exists',
+                record: rowToOperation(row)
+            } : {
+                status: 'conflict'
+            };
+        },
+        async acquireLease ({ callerDID, operationID, token, expiresAt }) {
+            const now = Date.now();
+            const result = await db.updateTable('kubun_connector_operation').set({
+                lease_token: token,
+                lease_expires_at: expiresAt,
+                updated_at: now
+            }).where('caller_did', '=', callerDID).where('operation_id', '=', operationID).where((eb)=>eb.or([
+                    eb('lease_token', 'is', null),
+                    eb('lease_expires_at', '<', now),
+                    eb('lease_token', '=', token)
+                ])).returning('operation_id').executeTakeFirst();
+            return result != null;
+        },
+        async renewLease ({ callerDID, operationID, token, expiresAt }) {
+            const now = Date.now();
+            const result = await db.updateTable('kubun_connector_operation').set({
+                lease_expires_at: expiresAt,
+                updated_at: now
+            }).where('caller_did', '=', callerDID).where('operation_id', '=', operationID).where((eb)=>eb.or([
+                    eb('lease_token', 'is', null),
+                    eb('lease_expires_at', '<', now),
+                    eb('lease_token', '=', token)
+                ])).returning('operation_id').executeTakeFirst();
+            return result != null;
+        },
+        async releaseLease ({ callerDID, operationID, token }) {
+            const now = Date.now();
+            const result = await db.updateTable('kubun_connector_operation').set({
+                lease_token: null,
+                lease_expires_at: null,
+                updated_at: now
+            }).where('caller_did', '=', callerDID).where('operation_id', '=', operationID).where((eb)=>eb.or([
+                    eb('lease_token', 'is', null),
+                    eb('lease_expires_at', '<', now),
+                    eb('lease_token', '=', token)
+                ])).returning('operation_id').executeTakeFirst();
+            return result != null;
+        },
+        async getOperation (callerDID, operationID) {
+            const row = await db.selectFrom('kubun_connector_operation').selectAll().where('caller_did', '=', callerDID).where('operation_id', '=', operationID).executeTakeFirst();
+            return row != null ? rowToOperation(row) : null;
+        },
+        async listTrackedOperations (filter) {
+            if (filter.states?.length === 0 || filter.documentIDs?.length === 0) return [];
+            if (filter.documentIDs != null && filter.documentIDs.length > IN_LIST_CHUNK) {
+                const chunks = [];
+                for (const documentIDs of chunked(filter.documentIDs)){
+                    chunks.push(await methods.listTrackedOperations({
+                        ...filter,
+                        documentIDs
+                    }));
+                }
+                return chunks.flat().sort(compareOperations);
+            }
+            const rows = await db.selectFrom('kubun_connector_operation').selectAll().$if(filter.nodeKey != null, (qb)=>qb.where('node_key', '=', filter.nodeKey)).$if(filter.callerDID != null, (qb)=>qb.where('caller_did', '=', filter.callerDID)).$if(filter.operationID != null, (qb)=>qb.where('operation_id', '=', filter.operationID)).$if(filter.visibleTo != null, (qb)=>qb.where((eb)=>eb.or([
+                        eb('caller_did', '=', filter.visibleTo),
+                        eb('owner_did', '=', filter.visibleTo)
+                    ]))).$if(filter.connectorName != null, (qb)=>qb.where('connector_name', '=', filter.connectorName)).$if(filter.states != null, (qb)=>qb.where('state', 'in', filter.states)).$if(filter.documentIDs != null, (qb)=>qb.where('document_id', 'in', filter.documentIDs)).orderBy('created_at').orderBy('caller_did').orderBy('operation_id').execute();
+            return rows.map(rowToOperation);
+        },
+        async hasNewerOperationOnDocument (callerDID, operationID) {
+            const row = await db.selectFrom('kubun_connector_operation as o').innerJoin('kubun_connector_operation as n', 'n.document_id', 'o.document_id').select('n.operation_id').where('o.caller_did', '=', callerDID).where('o.operation_id', '=', operationID).where((order)=>order.or([
+                    order('n.created_at', '>', order.ref('o.created_at')),
+                    order.and([
+                        order('n.created_at', '=', order.ref('o.created_at')),
+                        order('n.caller_did', '>', order.ref('o.caller_did'))
+                    ]),
+                    order.and([
+                        order('n.created_at', '=', order.ref('o.created_at')),
+                        order('n.caller_did', '=', order.ref('o.caller_did')),
+                        order('n.operation_id', '>', order.ref('o.operation_id'))
+                    ])
+                ])).limit(1).executeTakeFirst();
+            return row != null;
+        },
+        async markSendStarted (params) {
+            if (params.marker === CONTESTED_SEND_MARKER) {
+                throw new Error('markSendStarted: marker is reserved');
+            }
+            const result = await db.updateTable('kubun_connector_operation').set((eb)=>({
+                    // A second run marking the same attempt means an earlier run may
+                    // already have sent: the attempt becomes refundable by no run.
+                    send_marker: eb.case().when(eb.or([
+                        eb('send_marker', 'is', null),
+                        eb('send_marker', '=', params.marker)
+                    ])).then(params.marker).else(CONTESTED_SEND_MARKER).end(),
+                    updated_at: Date.now()
+                })).where('caller_did', '=', params.callerDID).where('operation_id', '=', params.operationID).where('state', '=', 'attempted').where('lease_token', '=', params.leaseToken).executeTakeFirst();
+            return (result?.numUpdatedRows ?? 0n) > 0n;
+        },
+        async deferOperation (params) {
+            const now = Date.now();
+            const result = await db.updateTable('kubun_connector_operation').set({
+                next_attempt_at: params.nextAttemptAt,
+                defer_reason: params.reason ?? null,
+                updated_at: now
+            }).where('caller_did', '=', params.callerDID).where('operation_id', '=', params.operationID).where('state', '=', 'attempted').where((eb)=>{
+                const free = [
+                    eb('lease_token', 'is', null),
+                    eb('lease_expires_at', '<', now)
+                ];
+                return eb.or(params.leaseToken != null ? [
+                    ...free,
+                    eb('lease_token', '=', params.leaseToken)
+                ] : free);
+            }).executeTakeFirst();
+            return (result?.numUpdatedRows ?? 0n) > 0n;
+        },
+        async recordOperation (input) {
+            // The type excludes `'committed'` from `toState`; this guards a caller
+            // that forces it through with a cast.
+            if (input.toState === 'committed') {
+                throw new Error('recordOperation cannot reach committed; use finalizeOperationAndArmWatch');
+            }
+            const now = Date.now();
+            const result = await db.updateTable('kubun_connector_operation').set((eb)=>({
+                    state: input.toState,
+                    provider_etag: input.providerEtag ?? null,
+                    attempts: input.refundAttempt === true ? eb('attempts', '-', 1) : input.countAttempt === false ? eb.ref('attempts') : eb('attempts', '+', 1),
+                    next_attempt_at: input.nextAttemptAt ?? null,
+                    defer_reason: input.deferReason ?? null,
+                    // A newly consumed attempt has started no send yet. A refund
+                    // clears the marker too: it only applies when the attempt is
+                    // unmarked or marked by the refunding run alone (see the guard
+                    // below), so a contested or other run's mark is never erased, and
+                    // the next run of the attempt starts unmarked.
+                    ...input.refundAttempt === true || input.countAttempt !== false ? {
+                        send_marker: null
+                    } : {},
+                    last_kind: input.kind ?? null,
+                    last_http_status: input.httpStatus ?? null,
+                    version: eb('version', '+', 1),
+                    updated_at: now
+                })).where('caller_did', '=', input.callerDID).where('operation_id', '=', input.operationID).where('state', '=', input.fromState).where('version', '=', input.version).where('lease_token', '=', input.leaseToken).$if(input.refundAttempt === true, (qb)=>qb.where('attempts', '>', 0).where((eb)=>eb.or([
+                        eb('send_marker', 'is', null),
+                        ...input.sendMarker != null ? [
+                            eb('send_marker', '=', input.sendMarker)
+                        ] : []
+                    ]))).executeTakeFirst();
+            return (result?.numUpdatedRows ?? 0n) > 0n;
+        }
+    };
+    return methods;
+}

package/lib/pending-auth.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export type PendingAuthMethods = Pick<ConnectorStoreAPI, 'createPendingAuth' | 'getPendingAuth' | 'consumePendingAuth' | 'deleteExpiredPendingAuth'>;
+export declare function createPendingAuthMethods(context: ConnectorStoreContext): PendingAuthMethods;

package/lib/pending-auth.js

@@ -0,0 +1,69 @@
+export function createPendingAuthMethods(context) {
+    const { db } = context;
+    const methods = {
+        // --- Pending OAuth authorization operations ---
+        async createPendingAuth (record) {
+            await db.insertInto('kubun_connector_pending_auth').values({
+                state: record.state,
+                code_verifier: record.codeVerifier,
+                provider: record.provider,
+                owner_did: record.ownerDID,
+                owner_wrappable_did: record.ownerWrappableDID ?? null,
+                controller_wrappable_did: record.controllerWrappableDID ?? null,
+                created_at: record.createdAt,
+                redirect_url: record.redirectURL,
+                scopes: JSON.stringify(record.scopes),
+                is_incremental: record.incremental ? 1 : 0,
+                expires_at: record.expiresAt
+            }).execute();
+        },
+        async getPendingAuth (state) {
+            const row = await db.selectFrom('kubun_connector_pending_auth').selectAll().where('state', '=', state).executeTakeFirst();
+            return row == null ? null : {
+                state: row.state,
+                codeVerifier: row.code_verifier,
+                provider: row.provider,
+                ownerDID: row.owner_did,
+                ownerWrappableDID: row.owner_wrappable_did,
+                controllerWrappableDID: row.controller_wrappable_did,
+                createdAt: row.created_at,
+                redirectURL: row.redirect_url,
+                scopes: typeof row.scopes === 'string' ? JSON.parse(row.scopes) : row.scopes,
+                incremental: row.is_incremental === 1,
+                expiresAt: row.expires_at
+            };
+        },
+        async consumePendingAuth (state) {
+            // Atomic single-use read: DELETE ... RETURNING removes and returns the row
+            // in one statement so concurrent callbacks cannot both consume the state.
+            const row = await db.deleteFrom('kubun_connector_pending_auth').where('state', '=', state).returningAll().executeTakeFirst();
+            if (row == null) return null;
+            return {
+                state: row.state,
+                codeVerifier: row.code_verifier,
+                provider: row.provider,
+                ownerDID: row.owner_did,
+                ownerWrappableDID: row.owner_wrappable_did,
+                controllerWrappableDID: row.controller_wrappable_did,
+                createdAt: row.created_at,
+                redirectURL: row.redirect_url,
+                // ParseJSONResultsPlugin may have already parsed this column, same as
+                // `checkpoint` in `rowToSyncState`.
+                scopes: typeof row.scopes === 'string' ? JSON.parse(row.scopes) : row.scopes,
+                incremental: row.is_incremental === 1,
+                expiresAt: row.expires_at
+            };
+        },
+        async deleteExpiredPendingAuth (cutoffMs) {
+            // Strict `<` matches @kokuin/oauth `completeAuthorization`, which treats a
+            // record as expired only when `expiresAt < now`. A record at exactly
+            // `expiresAt === cutoffMs` is therefore still consumable and is kept here
+            // (the next sweep, once `now > expiresAt`, removes it). This intentionally
+            // keeps one more record than the `PendingAuthStore.deleteExpired` port doc
+            // ("at or before nowMs") so the sweep and the consume check agree on the
+            // expiry boundary.
+            await db.deleteFrom('kubun_connector_pending_auth').where('expires_at', '<', cutoffMs).execute();
+        }
+    };
+    return methods;
+}