@kubun/store-connector 0.17.0 → 0.17.2

package/lib/api.js

@@ -1,25 +1,135 @@
+import { AbstractPostgresAdapter } from '@kubun/db-adapter';
+// 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*';
 // --- Serialization helpers ---
+// `checkpoint` and `recovery` are JSON columns: ParseJSONResultsPlugin may have
+// already parsed them (Postgres) or left them as strings (SQLite), so handle
+// both. Mirrors the `scopes` handling in `consumePendingAuth`.
+function decodeJSONColumn(value) {
+    if (value == null) return null;
+    return typeof value === 'string' ? JSON.parse(value) : value;
+}
+function encodeJSONColumn(value) {
+    return value != null ? JSON.stringify(value) : null;
+}
 function rowToSyncState(row) {
-    // ParseJSONResultsPlugin may have already parsed the checkpoint value
-    let checkpoint = null;
-    if (row.checkpoint != null) {
-        checkpoint = typeof row.checkpoint === 'string' ? JSON.parse(row.checkpoint) : row.checkpoint;
-    }
     const state = {
-        checkpoint,
+        checkpoint: decodeJSONColumn(row.checkpoint),
         lastSyncedAt: row.last_synced_at,
         entityCount: row.entity_count,
         status: row.status,
-        leaseExpiresAt: row.lease_expires_at
+        leaseExpiresAt: row.lease_expires_at,
+        recovery: decodeJSONColumn(row.recovery),
+        version: row.version
     };
+    if (row.incarnation != null) {
+        state.incarnation = row.incarnation;
+    }
     if (row.error != null) {
         state.error = row.error;
     }
     return state;
 }
-// --- Factory function ---
-export function createConnectorStore(db, _adapter) {
+function rowToOperation(row) {
+    return {
+        callerDID: row.caller_did,
+        operationID: row.operation_id,
+        nodeKey: row.node_key,
+        ownerDID: row.owner_did,
+        connectorName: row.connector_name,
+        model: row.model,
+        op: row.op,
+        accountKey: row.account_key,
+        target: row.target,
+        sourceID: row.source_id,
+        deterministicEventID: row.deterministic_event_id,
+        payloadHash: row.payload_hash,
+        reissueIntent: decodeJSONColumn(row.reissue_intent),
+        providerEtag: row.provider_etag,
+        documentID: row.document_id,
+        resultEntity: decodeJSONColumn(row.result_entity),
+        state: row.state,
+        attempts: row.attempts,
+        nextAttemptAt: row.next_attempt_at,
+        lastKind: row.last_kind,
+        lastHTTPStatus: row.last_http_status,
+        version: row.version,
+        incarnation: row.incarnation,
+        leaseToken: row.lease_token,
+        leaseExpiresAt: row.lease_expires_at,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    };
+}
+function rowToWatch(row) {
     return {
+        ownerDID: row.owner_did,
+        connectorName: row.connector_name,
+        model: row.model,
+        accountKey: row.account_key,
+        sourceID: row.source_id,
+        documentID: row.document_id,
+        verifiedStateDigest: row.verified_state_digest,
+        observedWinnerDigest: row.observed_winner_digest,
+        verificationStatus: row.verification_status,
+        verificationAttempts: row.verification_attempts,
+        repairGeneration: row.repair_generation,
+        nextAttemptAt: row.next_attempt_at,
+        version: row.version,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    };
+}
+// The most ids one `IN (...)` list binds; longer lists are read in chunks,
+// well inside every adapter's bind-parameter limit.
+const IN_LIST_CHUNK = 500;
+function chunked(values) {
+    // Deduplicated first, as a single `IN` would be: a value repeated across
+    // two chunks would otherwise return its rows twice.
+    const unique = [
+        ...new Set(values)
+    ];
+    const chunks = [];
+    for(let start = 0; start < unique.length; start += IN_LIST_CHUNK){
+        chunks.push(unique.slice(start, start + IN_LIST_CHUNK));
+    }
+    return chunks;
+}
+// A retention cleanup's cutoff and batch size: finite, and a positive whole
+// batch. Fails closed on anything else rather than deleting unbounded.
+function assertCollectParams(method, params) {
+    if (!Number.isFinite(params.before)) {
+        throw new Error(`${method}: before must be a finite number`);
+    }
+    if (!Number.isInteger(params.limit) || params.limit <= 0) {
+        throw new Error(`${method}: limit must be a positive integer`);
+    }
+}
+// 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;
+}
+// --- Factory function ---
+export function createConnectorStore(db, adapter, deps) {
+    // `.forUpdate()` compiles to a `FOR UPDATE` clause via Kysely's default
+    // compiler; SQLite has no dedicated override and errors on it (no such
+    // clause), so it is applied conditionally, never on SQLite. Postgres row
+    // locking is what makes a concurrent `armWatch`/`finalizeOperationAndArmWatch`
+    // on the same identity block instead of interleave; SQLite's single
+    // connection already serializes the whole transaction with no clause
+    // needed.
+    const isPostgres = adapter instanceof AbstractPostgresAdapter;
+    const { getRandomID } = deps;
+    // Declared as a named const (not an inline `return {...}`) so
+    // `requestRepull` can delegate to `api.armWatch` below — by the time
+    // `requestRepull` is actually invoked, `api` has long since finished
+    // initializing (closures capture the binding, not a snapshot), so the
+    // forward reference is safe.
+    const api = {
         // --- Sync state operations ---
         async getSyncState (connectorName, ownerDID) {
             const row = await db.selectFrom('kubun_connector_sync_state').selectAll().where('connector_name', '=', connectorName).where('owner_did', '=', ownerDID).executeTakeFirst();
@@ -28,48 +138,86 @@ export function createConnectorStore(db, _adapter) {
         },
         async setSyncState (connectorName, ownerDID, state) {
             // `lease_expires_at` is dead: a fresh INSERT sets it null and a conflicting
-            // update leaves it untouched.
+            // update leaves it untouched. A fresh INSERT seeds version 0 and a random
+            // incarnation; a conflicting update leaves both untouched (this path is not
+            // the CAS write — it does not bump version or churn the incarnation).
+            const checkpoint = encodeJSONColumn(state.checkpoint);
+            const recovery = encodeJSONColumn(state.recovery);
             await db.insertInto('kubun_connector_sync_state').values({
                 connector_name: connectorName,
                 owner_did: ownerDID,
-                checkpoint: state.checkpoint != null ? JSON.stringify(state.checkpoint) : null,
+                checkpoint,
                 last_synced_at: state.lastSyncedAt,
                 entity_count: state.entityCount,
                 status: state.status,
                 error: state.error ?? null,
-                lease_expires_at: null
+                lease_expires_at: null,
+                recovery,
+                version: 0,
+                incarnation: getRandomID()
             }).onConflict((oc)=>oc.columns([
                     'connector_name',
                     'owner_did'
                 ]).doUpdateSet({
-                    checkpoint: state.checkpoint != null ? JSON.stringify(state.checkpoint) : null,
+                    checkpoint,
                     last_synced_at: state.lastSyncedAt,
                     entity_count: state.entityCount,
                     status: state.status,
-                    error: state.error ?? null
+                    error: state.error ?? null,
+                    recovery
                 })).execute();
         },
-        async updateSyncProgress (connectorName, ownerDID, progress) {
-            const checkpoint = progress.checkpoint != null ? JSON.stringify(progress.checkpoint) : null;
-            const error = progress.error ?? null;
-            await db.insertInto('kubun_connector_sync_state').values({
-                connector_name: connectorName,
-                owner_did: ownerDID,
-                checkpoint,
-                last_synced_at: progress.lastSyncedAt,
-                entity_count: progress.entityCount,
-                status: 'idle',
-                error,
-                lease_expires_at: null
-            }).onConflict((oc)=>oc.columns([
-                    'connector_name',
-                    'owner_did'
-                ]).doUpdateSet({
-                    checkpoint,
-                    last_synced_at: progress.lastSyncedAt,
-                    entity_count: progress.entityCount,
-                    error
-                })).execute();
+        async updateSyncProgress (connectorName, ownerDID, recompute, options) {
+            // The caller passes the authoritative MAX_CAS_RETRIES; 5 is a defensive
+            // fallback for direct callers/tests.
+            const maxRetries = options?.maxRetries ?? 5;
+            for(let attempt = 0; attempt <= maxRetries; attempt++){
+                const row = await db.selectFrom('kubun_connector_sync_state').selectAll().where('connector_name', '=', connectorName).where('owner_did', '=', ownerDID).executeTakeFirst();
+                if (row == null) {
+                    // No row yet: INSERT ... ON CONFLICT DO NOTHING so a lost insert race
+                    // (a concurrent writer created the row first) falls through to reload
+                    // and take the update path.
+                    const result = await recompute(null);
+                    const inserted = await db.insertInto('kubun_connector_sync_state').values({
+                        connector_name: connectorName,
+                        owner_did: ownerDID,
+                        checkpoint: encodeJSONColumn(result.checkpoint),
+                        last_synced_at: result.lastSyncedAt,
+                        entity_count: result.entityCount,
+                        status: 'idle',
+                        error: result.error ?? null,
+                        lease_expires_at: null,
+                        recovery: encodeJSONColumn(result.recovery),
+                        version: 0,
+                        incarnation: getRandomID()
+                    }).onConflict((oc)=>oc.columns([
+                            'connector_name',
+                            'owner_did'
+                        ]).doNothing()).executeTakeFirst();
+                    if ((inserted?.numInsertedOrUpdatedRows ?? 0n) > 0n) return;
+                    continue;
+                }
+                const result = await recompute({
+                    checkpoint: decodeJSONColumn(row.checkpoint),
+                    recovery: decodeJSONColumn(row.recovery),
+                    version: row.version,
+                    incarnation: row.incarnation ?? ''
+                });
+                // Single conditional UPDATE guarded on the read version AND incarnation.
+                // `status` is deliberately omitted (workflow owns it). Zero rows means a
+                // concurrent writer won, or the row was delete+recreated (incarnation
+                // differs) ⇒ reload and recompute.
+                const updated = await db.updateTable('kubun_connector_sync_state').set({
+                    checkpoint: encodeJSONColumn(result.checkpoint),
+                    last_synced_at: result.lastSyncedAt,
+                    entity_count: result.entityCount,
+                    error: result.error ?? null,
+                    recovery: encodeJSONColumn(result.recovery),
+                    version: row.version + 1
+                }).where('connector_name', '=', connectorName).where('owner_did', '=', ownerDID).where('version', '=', row.version).where('incarnation', '=', row.incarnation).executeTakeFirst();
+                if ((updated?.numUpdatedRows ?? 0n) > 0n) return;
+            }
+            throw new Error(`updateSyncProgress: CAS failed after ${maxRetries + 1} attempts for ${connectorName}/${ownerDID}`);
         },
         async deleteSyncState (connectorName, ownerDID) {
             await db.deleteFrom('kubun_connector_sync_state').where('connector_name', '=', connectorName).where('owner_did', '=', ownerDID).execute();
@@ -126,6 +274,705 @@ export function createConnectorStore(db, _adapter) {
             // ("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();
+        },
+        // --- 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 api.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;
+        },
+        async finalizeOperationAndArmWatch (input) {
+            const now = Date.now();
+            return await db.transaction().execute(async (tx)=>{
+                // Conditional UPDATE first: the fenced lease CAS gate. `version` is
+                // deliberately NOT bumped here (see `FinalizeOperationInput`'s doc) —
+                // only the watch row's own `version` advances below.
+                const updated = await tx.updateTable('kubun_connector_operation').set({
+                    state: 'committed',
+                    document_id: input.documentID,
+                    result_entity: encodeJSONColumn(input.resultEntity),
+                    updated_at: now
+                }).where('caller_did', '=', input.key.callerDID).where('operation_id', '=', input.key.operationID).where('state', 'in', [
+                    'attempted',
+                    'committed'
+                ]).where('version', '=', input.version).where('lease_token', '=', input.leaseToken).executeTakeFirst();
+                // Lost CAS: the transaction commits with NO watch write — the point
+                // is that the upsert below never runs, so a stale-lease finalize
+                // leaves the watch row untouched (absent if it never existed).
+                if ((updated?.numUpdatedRows ?? 0n) === 0n) {
+                    return false;
+                }
+                // One watch per document: a watch the document still has under
+                // another provider identity (the same provider id written under a
+                // second account, say) is superseded by this one, not kept beside it.
+                const identity = input.watchIdentity;
+                await tx.deleteFrom('kubun_connector_projection_watch').where('owner_did', '=', identity.ownerDID).where('model', '=', identity.model).where('document_id', '=', input.documentID).where((eb)=>eb.or([
+                        eb('connector_name', '!=', identity.connectorName),
+                        eb('account_key', '!=', identity.accountKey),
+                        eb('source_id', '!=', identity.sourceID)
+                    ])).execute();
+                await tx.insertInto('kubun_connector_projection_watch').values({
+                    owner_did: input.watchIdentity.ownerDID,
+                    connector_name: input.watchIdentity.connectorName,
+                    model: input.watchIdentity.model,
+                    account_key: input.watchIdentity.accountKey,
+                    source_id: input.watchIdentity.sourceID,
+                    document_id: input.documentID,
+                    verified_state_digest: null,
+                    observed_winner_digest: input.currentWinnerDigest,
+                    verification_status: 'pending_verification',
+                    verification_attempts: 0,
+                    repair_generation: 0,
+                    next_attempt_at: now,
+                    version: 0,
+                    created_at: now,
+                    updated_at: now
+                }).onConflict((oc)=>oc.columns([
+                        'owner_did',
+                        'connector_name',
+                        'model',
+                        'account_key',
+                        'source_id'
+                    ]).doUpdateSet((eb)=>({
+                            repair_generation: eb('kubun_connector_projection_watch.repair_generation', '+', 1),
+                            verification_attempts: 0,
+                            verification_status: 'pending_verification',
+                            observed_winner_digest: input.currentWinnerDigest,
+                            verified_state_digest: null,
+                            next_attempt_at: now,
+                            claimed_until: null,
+                            defer_reason: null,
+                            version: eb('kubun_connector_projection_watch.version', '+', 1),
+                            updated_at: now
+                        }))).execute();
+                return true;
+            });
+        },
+        // --- 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}`);
+        },
+        // --- Boot/periodic sweep: due operations + due/diverged watches ---
+        async requestRepull (identity, opts) {
+            // Thin wrapper: re-arm only. The caller is responsible for scheduling
+            // the actual sweep tick that picks this back up via
+            // `listDueOperations` — this method's whole job is to make the watch
+            // due again (unconditionally opening a new generation, same as any
+            // other `'manual'` arm).
+            await api.armWatch(identity, 'manual', {
+                dueAt: opts.dueAt
+            });
+        },
+        async listDueOperations (now, opts) {
+            // The one non-terminal operation state, `attempted`, once its re-drive
+            // is due. The terminal states are excluded: a `committed` write already
+            // landed (its projection is tracked by the watch, below), and `dead` /
+            // `reconcile_only` need a user's action, not another re-drive.
+            const operationRows = await db.selectFrom('kubun_connector_operation').selectAll().where('state', '=', 'attempted')// A re-drive backed off into the future is not due yet.
+            .where((eb)=>eb.or([
+                    eb('next_attempt_at', 'is', null),
+                    eb('next_attempt_at', '<=', now)
+                ])).execute();
+            const operations = operationRows.map(rowToOperation);
+            // --- watches: union of the SCHEDULE branch and the AUDIT branch ---
+            // SCHEDULE branch: the ordinary due-by-time verify loop. A
+            // `repair_failed` row has its schedule cleared to null by
+            // `recordVerification` on exhaustion, so this branch naturally
+            // excludes exhausted rows without needing to name the status
+            // explicitly — a `pending_verification` row with a null
+            // `verified_state_digest` is serviced here, by its own schedule, and
+            // never by the audit branch below.
+            const scheduleRows = await db.selectFrom('kubun_connector_projection_watch').selectAll().where('verification_status', '!=', 'verified').where('next_attempt_at', 'is not', null).where('next_attempt_at', '<=', now).execute();
+            // AUDIT branch: the crash-durable divergence sweep. `armWatch`'s
+            // 'ingress' reason re-arms the fast path the instant an event proves
+            // the winner moved — but that re-arm write can itself be lost to a
+            // crash between the winner moving and the write landing. This branch
+            // is the boot/periodic backstop that catches exactly that case,
+            // without reopening a K-exhausted row whose winner has not actually
+            // moved (which would make K unbounded).
+            //
+            // Deliberately NOT filtered on `next_attempt_at`: both `verified` and
+            // exhausted `repair_failed` rows have it cleared to null — filtering
+            // on it here would drop precisely the rows this branch exists to
+            // reopen. Candidates are gathered by a plain SELECT (no
+            // store-connector transaction held open across it — this is a
+            // read-only sweep, and `readWinner` is called per candidate in code
+            // below, never inside a `db.transaction()`, to avoid nesting a
+            // transaction on SQLite's single connection).
+            //
+            // The winner digest is not a store-connector column — it lives in the
+            // store-graph registers (`readWinnerStateDigest`) — so this
+            // predicate cannot be expressed in pure SQL over this table alone;
+            // the actual divergence check runs in code against `readWinner`.
+            const auditCandidateRows = await db.selectFrom('kubun_connector_projection_watch').selectAll().where('verification_status', 'in', [
+                'verified',
+                'repair_failed'
+            ]).execute();
+            const identityKey = (row)=>`${row.owner_did}\u0000${row.connector_name}\u0000${row.model}\u0000${row.account_key}\u0000${row.source_id}`;
+            const dueByIdentity = new Map();
+            for (const row of scheduleRows){
+                dueByIdentity.set(identityKey(row), row);
+            }
+            for (const row of auditCandidateRows){
+                // Each candidate gets its own short-lived read via the top-level
+                // `db` handle — not a held-open transaction spanning every
+                // candidate, and not a nested store-connector transaction.
+                // A document whose winner cannot be read (none stored yet, say) has
+                // no divergence to audit: skip it rather than abort the whole sweep
+                // and every re-drive with it.
+                let currentWinner;
+                try {
+                    currentWinner = await opts.readWinner(row.document_id, db);
+                } catch  {
+                    continue;
+                }
+                // Null-safe by construction: `currentWinner` is always a real
+                // digest string, so `currentWinner !== null` is trivially true when
+                // a watermark is null — a `repair_failed` row with
+                // `verified_state_digest: null` is excluded here whenever the
+                // current winner already equals `observed_winner_digest` (the
+                // K-bounded negative), and included only when the winner differs
+                // from BOTH watermarks.
+                const diverged = currentWinner !== row.verified_state_digest && currentWinner !== row.observed_winner_digest;
+                if (diverged) {
+                    dueByIdentity.set(identityKey(row), row);
+                }
+            }
+            const watches = Array.from(dueByIdentity.values()).map(rowToWatch);
+            return {
+                operations,
+                watches
+            };
+        },
+        // --- Retention cleanup ---
+        async collectFinishedOperations (params) {
+            assertCollectParams('collectFinishedOperations', params);
+            const now = Date.now();
+            // One statement: the keep rule and the delete see the same rows, so no
+            // two batches (or two concurrent cleanups) can each take another row to
+            // be the newest. A row is only ever collected while a newer row of its
+            // kind exists in the same partition; the newest of a partition never has
+            // one, and operations never leave a terminal state, so it is never
+            // collected.
+            //
+            // No change events: a collected row is one a newer row supersedes (or
+            // one linked to no document), so no document's derived write state
+            // changes.
+            const result = await db.deleteFrom('kubun_connector_operation').where((eb)=>eb(eb.refTuple('caller_did', 'operation_id'), 'in', eb.selectFrom('kubun_connector_operation as o').select([
+                    'o.caller_did',
+                    'o.operation_id'
+                ]).where('o.state', 'in', [
+                    'committed',
+                    'dead'
+                ]).where('o.updated_at', '<', params.before).where((inner)=>inner.or([
+                        inner('o.lease_token', 'is', null),
+                        inner('o.lease_expires_at', '<', now)
+                    ])).where((inner)=>{
+                    // A newer operation of `states` on the same document with the
+                    // same `column` (caller or owner) as `o`.
+                    const newerExists = (column, states)=>inner.exists(inner.selectFrom('kubun_connector_operation as n').select('n.operation_id').whereRef('n.document_id', '=', 'o.document_id').whereRef(`n.${column}`, '=', `o.${column}`).where('n.state', 'in', states).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'))
+                                ])
+                            ])));
+                    return inner.or([
+                        inner('o.document_id', 'is', null),
+                        inner.and([
+                            // Not the newest commit of its caller, nor of its owner:
+                            // the latest commit bounds which older rows still count.
+                            inner.or([
+                                inner('o.state', '!=', 'committed'),
+                                newerExists('caller_did', [
+                                    'committed'
+                                ])
+                            ]),
+                            inner.or([
+                                inner('o.state', '!=', 'committed'),
+                                newerExists('owner_did', [
+                                    'committed'
+                                ])
+                            ]),
+                            // Not the newest finished row of its caller, nor of its
+                            // owner: the newest one decides whether the document shows
+                            // a failure.
+                            newerExists('caller_did', [
+                                'committed',
+                                'dead'
+                            ]),
+                            newerExists('owner_did', [
+                                'committed',
+                                'dead'
+                            ])
+                        ])
+                    ]);
+                }).orderBy('o.updated_at').limit(params.limit).$asTuple('caller_did', 'operation_id')))// Re-checked on the row being deleted: a row a lease was taken on
+            // between the candidate read and the delete (Postgres, read committed)
+            // was written since, and is kept.
+            .where('updated_at', '<', params.before).where((eb)=>eb.or([
+                    eb('lease_token', 'is', null),
+                    eb('lease_expires_at', '<', now)
+                ])).executeTakeFirst();
+            return Number(result?.numDeletedRows ?? 0n);
         }
     };
+    return api;
 }