@kubun/store-connector 0.17.2 → 0.18.0

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;
+}

package/lib/projection-watches.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export type ProjectionWatchesMethods = Pick<ConnectorStoreAPI, 'getWatch' | 'getWatchByDocument' | 'listWatchesByDocuments' | 'armWatch' | 'resumeOfflineDeferred' | 'resumeAuthDeferred' | 'deferWatch' | 'claimWatchAttempt' | 'recordVerification'>;
+export declare function createProjectionWatchesMethods(context: ConnectorStoreContext): ProjectionWatchesMethods;

package/lib/projection-watches.js

@@ -0,0 +1,265 @@
+import { chunked } from '@kubun/db-adapter';
+import { rowToWatch } from './serialization.js';
+export function createProjectionWatchesMethods(context) {
+    const { db, deps, isPostgres } = context;
+    const methods = {
+        // --- Connector projection verify/repair watch reads ---
+        async getWatch (identity) {
+            const row = await db.selectFrom('kubun_connector_projection_watch').selectAll().where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID).executeTakeFirst();
+            return row != null ? rowToWatch(row) : null;
+        },
+        async getWatchByDocument (documentID) {
+            const row = await db.selectFrom('kubun_connector_projection_watch').selectAll().where('document_id', '=', documentID).executeTakeFirst();
+            return row != null ? rowToWatch(row) : null;
+        },
+        async listWatchesByDocuments (documentIDs) {
+            const watches = [];
+            for (const chunk of chunked(documentIDs)){
+                const rows = await db.selectFrom('kubun_connector_projection_watch').selectAll().where('document_id', 'in', chunk).execute();
+                watches.push(...rows.map(rowToWatch));
+            }
+            return watches;
+        },
+        async armWatch (identity, reason, opts) {
+            if (reason === 'finalize') {
+                throw new Error("armWatch: reason 'finalize' is reserved — the finalize-arm transition is inlined " + 'in finalizeOperationAndArmWatch and must not be invoked through armWatch');
+            }
+            if (deps.readWinner == null) {
+                throw new Error('armWatch: createConnectorStore was not given a readWinner dependency ' + "(required for reasons 'ingress'/'manual')");
+            }
+            const readWinner = deps.readWinner;
+            const maxRetries = 5;
+            for(let attempt = 0; attempt <= maxRetries; attempt++){
+                // The ENTIRE gate — row read, current-winner read, and the
+                // ingress/manual decision — is re-run on every attempt, including
+                // retries. A concurrent writer between attempts may have changed the
+                // watch's status/watermarks such that the correct outcome flips
+                // (e.g. it already opened the generation, so this call must
+                // coalesce/noop rather than open a second) — caching the first
+                // read's decision and only retrying the write would miss that.
+                const attemptResult = await db.transaction().execute(async (tx)=>{
+                    const base = tx.selectFrom('kubun_connector_projection_watch').selectAll().where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID);
+                    const row = await (isPostgres ? base.forUpdate() : base).executeTakeFirst();
+                    // No watch row for this identity yet: nothing to arm (the row is
+                    // created by `finalizeOperationAndArmWatch`, not here).
+                    if (row == null) {
+                        return {
+                            settled: true,
+                            outcome: 'noop'
+                        };
+                    }
+                    // Read the CURRENT winner on the same transaction/lock as the row
+                    // above — never the top-level db (see `ReadWinner`'s doc).
+                    const currentWinner = await readWinner(row.document_id, tx);
+                    const now = Date.now();
+                    const openGeneration = async ()=>{
+                        const updated = await tx.updateTable('kubun_connector_projection_watch').set({
+                            repair_generation: row.repair_generation + 1,
+                            verification_attempts: 0,
+                            verification_status: 'pending_verification',
+                            observed_winner_digest: currentWinner,
+                            next_attempt_at: opts.dueAt,
+                            // A claim on the superseded generation does not carry over.
+                            claimed_until: null,
+                            defer_reason: null,
+                            version: row.version + 1,
+                            updated_at: now
+                        }).where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID).where('version', '=', row.version).executeTakeFirst();
+                        return {
+                            settled: (updated?.numUpdatedRows ?? 0n) > 0n,
+                            outcome: 'opened'
+                        };
+                    };
+                    if (reason === 'manual') {
+                        // Unconditional: overrides status and the coalesce rule.
+                        return await openGeneration();
+                    }
+                    // reason === 'ingress': the authoritative in-CAS re-check. `E`
+                    // must equal the freshly-read current winner AND differ from both
+                    // watermarks — this is what a caller-side pre-filter can only
+                    // approximate; this is the check that actually gates the write.
+                    const triggeringWinner = opts.triggeringWinner;
+                    const gatePasses = triggeringWinner != null && triggeringWinner === currentWinner && triggeringWinner !== row.verified_state_digest && triggeringWinner !== row.observed_winner_digest;
+                    if (!gatePasses) {
+                        return {
+                            settled: true,
+                            outcome: 'noop'
+                        };
+                    }
+                    if (row.verification_status === 'verified' || row.verification_status === 'repair_failed') {
+                        return await openGeneration();
+                    }
+                    // row.verification_status === 'pending_verification': coalesce.
+                    // `min` computed in JS from the already-read row value and written
+                    // as a literal — SQL LEAST/MIN differ across adapters.
+                    const coalescedNextAttemptAt = row.next_attempt_at == null ? opts.dueAt : Math.min(row.next_attempt_at, opts.dueAt);
+                    const updated = await tx.updateTable('kubun_connector_projection_watch').set({
+                        next_attempt_at: coalescedNextAttemptAt,
+                        version: row.version + 1,
+                        updated_at: now
+                    }).where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID).where('version', '=', row.version).executeTakeFirst();
+                    return {
+                        settled: (updated?.numUpdatedRows ?? 0n) > 0n,
+                        outcome: 'coalesced'
+                    };
+                });
+                if (attemptResult.settled) {
+                    return attemptResult.outcome;
+                }
+            }
+            throw new Error(`armWatch: CAS failed after ${maxRetries + 1} attempts for ${identity.ownerDID}/${identity.connectorName}/${identity.model}/${identity.accountKey}/${identity.sourceID}`);
+        },
+        async resumeOfflineDeferred (now) {
+            await db.updateTable('kubun_connector_operation').set({
+                next_attempt_at: now,
+                defer_reason: null,
+                updated_at: now
+            }).where('state', '=', 'attempted').where('defer_reason', '=', 'offline').execute();
+            await db.updateTable('kubun_connector_projection_watch').set((eb)=>({
+                    next_attempt_at: now,
+                    defer_reason: null,
+                    version: eb('kubun_connector_projection_watch.version', '+', 1),
+                    updated_at: now
+                })).where('verification_status', '=', 'pending_verification').where('defer_reason', '=', 'offline').execute();
+        },
+        async resumeAuthDeferred (params) {
+            if (params.connectorNames.length === 0) return;
+            await db.updateTable('kubun_connector_operation').set({
+                next_attempt_at: params.now,
+                defer_reason: null,
+                updated_at: params.now
+            }).where('state', '=', 'attempted').where('defer_reason', '=', 'auth').where('owner_did', '=', params.ownerDID).where('connector_name', 'in', params.connectorNames).execute();
+            await db.updateTable('kubun_connector_projection_watch').set((eb)=>({
+                    next_attempt_at: params.now,
+                    defer_reason: null,
+                    version: eb('kubun_connector_projection_watch.version', '+', 1),
+                    updated_at: params.now
+                })).where('verification_status', '=', 'pending_verification').where('defer_reason', '=', 'auth').where('owner_did', '=', params.ownerDID).where('connector_name', 'in', params.connectorNames).execute();
+        },
+        async deferWatch (identity, opts) {
+            const result = await db.updateTable('kubun_connector_projection_watch').set((eb)=>({
+                    next_attempt_at: opts.nextAttemptAt,
+                    defer_reason: opts.reason ?? null,
+                    claimed_until: null,
+                    version: eb('kubun_connector_projection_watch.version', '+', 1),
+                    updated_at: Date.now()
+                })).where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID).where('verification_status', '=', 'pending_verification').where('repair_generation', '=', opts.generation).where('claimed_until', '=', opts.claimedUntil).executeTakeFirst();
+            return (result?.numUpdatedRows ?? 0n) > 0n;
+        },
+        async claimWatchAttempt (identity, opts) {
+            const result = await db.updateTable('kubun_connector_projection_watch').set((eb)=>({
+                    claimed_until: opts.until,
+                    version: eb('kubun_connector_projection_watch.version', '+', 1),
+                    updated_at: Date.now()
+                })).where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID).where('verification_status', '=', 'pending_verification').where('repair_generation', '=', opts.generation).where('next_attempt_at', 'is not', null).where('next_attempt_at', '<=', opts.now).where((eb)=>eb.or([
+                    eb('claimed_until', 'is', null),
+                    eb('claimed_until', '<=', opts.now)
+                ])).executeTakeFirst();
+            return (result?.numUpdatedRows ?? 0n) > 0n;
+        },
+        async recordVerification (identity, input) {
+            if (deps.readWinner == null) {
+                throw new Error('recordVerification: createConnectorStore was not given a readWinner dependency');
+            }
+            const readWinner = deps.readWinner;
+            const maxRetries = 5;
+            for(let attempt = 0; attempt <= maxRetries; attempt++){
+                // The ENTIRE gate — row read, generation check, current-winner
+                // read, and the transition decision — is re-run on every attempt,
+                // mirroring armWatch: caching the first read's decision and only
+                // retrying the write would miss a concurrent re-arm or a
+                // concurrent winner move between attempts.
+                const attemptResult = await db.transaction().execute(async (tx)=>{
+                    const base = tx.selectFrom('kubun_connector_projection_watch').selectAll().where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID);
+                    const row = await (isPostgres ? base.forUpdate() : base).executeTakeFirst();
+                    // No watch row for this identity: nothing to verify against. See
+                    // `recordVerification`'s doc for why this maps to
+                    // 'stale-generation' rather than a throw or a fabricated
+                    // transition.
+                    if (row == null) {
+                        return {
+                            settled: true,
+                            outcome: 'stale-generation'
+                        };
+                    }
+                    // GENERATION GATE FIRST, before the winner read or any decision:
+                    // a re-arm bumped repair_generation past what this verify call
+                    // was scheduled against. Terminal — no write, no retry.
+                    if (row.repair_generation !== input.generation) {
+                        return {
+                            settled: true,
+                            outcome: 'stale-generation'
+                        };
+                    }
+                    if (input.claimedUntil != null && row.claimed_until !== input.claimedUntil) {
+                        return {
+                            settled: true,
+                            outcome: 'stale-claim'
+                        };
+                    }
+                    // Re-read the CURRENT winner inside this transaction/lock — never
+                    // the caller's apply-time `input.fetchedDigest`, and never the
+                    // top-level db (see `ReadWinner`'s doc). This is the assumption
+                    // under test: a concurrent ingress that moved the winner between
+                    // project and verify must be caught here, not trusted from the
+                    // caller.
+                    const currentWinner = await readWinner(row.document_id, tx);
+                    const now = Date.now();
+                    if (input.fetchedDigest != null && input.fetchedDigest === currentWinner) {
+                        const updated = await tx.updateTable('kubun_connector_projection_watch').set({
+                            verification_status: 'verified',
+                            observed_winner_digest: currentWinner,
+                            verified_state_digest: currentWinner,
+                            next_attempt_at: null,
+                            claimed_until: null,
+                            defer_reason: null,
+                            version: row.version + 1,
+                            updated_at: now
+                        }).where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID).where('version', '=', row.version).executeTakeFirst();
+                        return {
+                            settled: (updated?.numUpdatedRows ?? 0n) > 0n,
+                            outcome: 'verified'
+                        };
+                    }
+                    if (row.verification_attempts + 1 >= input.maxAttempts) {
+                        const updated = await tx.updateTable('kubun_connector_projection_watch').set({
+                            verification_status: 'repair_failed',
+                            observed_winner_digest: currentWinner,
+                            verification_attempts: row.verification_attempts + 1,
+                            next_attempt_at: null,
+                            claimed_until: null,
+                            defer_reason: null,
+                            version: row.version + 1,
+                            updated_at: now
+                        }).where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID).where('version', '=', row.version).executeTakeFirst();
+                        return {
+                            settled: (updated?.numUpdatedRows ?? 0n) > 0n,
+                            outcome: 'repair_failed'
+                        };
+                    }
+                    // Non-terminal mismatch: bump attempts, reschedule — LEAVE BOTH
+                    // WATERMARKS UNTOUCHED. Load-bearing for verify-races-ingress: a
+                    // concurrent winner move must not advance
+                    // observed_winner_digest while the row is still pending.
+                    const updated = await tx.updateTable('kubun_connector_projection_watch').set({
+                        verification_attempts: row.verification_attempts + 1,
+                        next_attempt_at: input.dueAt,
+                        claimed_until: null,
+                        defer_reason: null,
+                        version: row.version + 1,
+                        updated_at: now
+                    }).where('owner_did', '=', identity.ownerDID).where('connector_name', '=', identity.connectorName).where('model', '=', identity.model).where('account_key', '=', identity.accountKey).where('source_id', '=', identity.sourceID).where('version', '=', row.version).executeTakeFirst();
+                    return {
+                        settled: (updated?.numUpdatedRows ?? 0n) > 0n,
+                        outcome: 'pending'
+                    };
+                });
+                if (attemptResult.settled) {
+                    return attemptResult.outcome;
+                }
+            }
+            throw new Error(`recordVerification: CAS failed after ${maxRetries + 1} attempts for ${identity.ownerDID}/${identity.connectorName}/${identity.model}/${identity.accountKey}/${identity.sourceID}`);
+        }
+    };
+    return methods;
+}

package/lib/retention.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export type RetentionMethods = Pick<ConnectorStoreAPI, 'listDueOperations' | 'collectFinishedOperations'>;
+export declare function createRetentionMethods(context: ConnectorStoreContext): RetentionMethods;