@kubun/store-connector 0.17.2 → 0.18.0

package/lib/retention.js

@@ -0,0 +1,193 @@
+import { chunked } from '@kubun/db-adapter';
+import { rowToOperation, rowToWatch } from './serialization.js';
+// 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`);
+    }
+}
+export function createRetentionMethods(context) {
+    const { db } = context;
+    const methods = {
+        // --- Boot/periodic sweep: due operations + due/diverged watches ---
+        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);
+            }
+            // One batched read per chunk of candidates when the caller supplies a
+            // batch reader; a candidate absent from the map has no readable winner.
+            const winners = new Map();
+            if (opts.readWinners !== undefined) {
+                for (const ids of chunked(auditCandidateRows.map((row)=>row.document_id))){
+                    for (const [id, digest] of (await opts.readWinners(ids, db))){
+                        winners.set(id, digest);
+                    }
+                }
+            }
+            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;
+                if (opts.readWinners !== undefined) {
+                    const winner = winners.get(row.document_id);
+                    if (winner === undefined) continue;
+                    currentWinner = winner;
+                } else {
+                    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 methods;
+}

package/lib/serialization.d.ts

@@ -0,0 +1,63 @@
+import type { ConnectorOperation, ProjectionWatch, SyncState } from './api-types.js';
+export type SyncStateRow = {
+    checkpoint: string | null;
+    last_synced_at: string;
+    entity_count: number;
+    status: string;
+    error: string | null;
+    lease_expires_at: number | null;
+    recovery: string | null;
+    version: number;
+    incarnation: string | null;
+};
+export type OperationRow = {
+    caller_did: string;
+    operation_id: string;
+    node_key: string;
+    owner_did: string;
+    connector_name: string;
+    model: string;
+    op: string;
+    account_key: string;
+    target: string;
+    source_id: string | null;
+    deterministic_event_id: string;
+    payload_hash: string;
+    reissue_intent: string;
+    provider_etag: string | null;
+    document_id: string | null;
+    result_entity: string | null;
+    state: string;
+    attempts: number;
+    next_attempt_at: number | null;
+    last_kind: string | null;
+    last_http_status: number | null;
+    version: number;
+    incarnation: string | null;
+    lease_token: string | null;
+    lease_expires_at: number | null;
+    created_at: number;
+    updated_at: number;
+};
+export type WatchRow = {
+    owner_did: string;
+    connector_name: string;
+    model: string;
+    account_key: string;
+    source_id: string;
+    document_id: string;
+    verified_state_digest: string | null;
+    observed_winner_digest: string | null;
+    verification_status: string;
+    verification_attempts: number;
+    repair_generation: number;
+    next_attempt_at: number | null;
+    version: number;
+    created_at: number;
+    updated_at: number;
+};
+export declare function decodeJSONColumn(value: unknown): unknown;
+export declare function encodeJSONColumn(value: unknown): string | null;
+export declare function rowToSyncState(row: SyncStateRow): SyncState;
+export declare function rowToOperation(row: OperationRow): ConnectorOperation;
+export declare function rowToWatch(row: WatchRow): ProjectionWatch;

package/lib/serialization.js

@@ -0,0 +1,79 @@
+// --- 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`.
+export function decodeJSONColumn(value) {
+    if (value == null) return null;
+    return typeof value === 'string' ? JSON.parse(value) : value;
+}
+export function encodeJSONColumn(value) {
+    return value != null ? JSON.stringify(value) : null;
+}
+export function rowToSyncState(row) {
+    const state = {
+        checkpoint: decodeJSONColumn(row.checkpoint),
+        lastSyncedAt: row.last_synced_at,
+        entityCount: row.entity_count,
+        status: row.status,
+        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;
+}
+export 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
+    };
+}
+export 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
+    };
+}

package/lib/store-context.d.ts

@@ -0,0 +1,11 @@
+import type { Adapter } from '@kubun/db-adapter';
+import type { Kysely } from 'kysely';
+import type { ConnectorStoreDeps } from './api-types.js';
+import type { ConnectorTables } from './tables.js';
+export type ConnectorStoreContext = {
+    db: Kysely<ConnectorTables>;
+    adapter: Adapter;
+    isPostgres: boolean;
+    deps: ConnectorStoreDeps;
+    getRandomID: () => string;
+};

package/lib/store-context.js

@@ -0,0 +1 @@
+export { };

package/lib/sweep-state.d.ts

@@ -0,0 +1,5 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export declare const MAX_SWEEP_APPLY_ATTEMPTS = 5;
+export type SweepStateMethods = Pick<ConnectorStoreAPI, 'recordRelistReceipt' | 'listSweepReceipts' | 'listSweepCandidates' | 'recordSweepOutcome' | 'recordSweepApplyFailure' | 'markSweepCandidateApplied' | 'commitSweepCheckpoint' | 'getSweepCheckpoint'>;
+export declare function createSweepStateMethods({ db, deps }: ConnectorStoreContext): SweepStateMethods;

package/lib/sweep-state.js

@@ -0,0 +1,180 @@
+import { decodeJSONColumn, encodeJSONColumn } from './serialization.js';
+export const MAX_SWEEP_APPLY_ATTEMPTS = 5;
+export function createSweepStateMethods({ db, deps }) {
+    const now = deps.now ?? Date.now;
+    return {
+        async recordRelistReceipt (receipt, candidates) {
+            if (!receipt.complete) return;
+            await db.transaction().execute(async (tx)=>{
+                const existing = await tx.selectFrom('kubun_connector_sweep_receipt').select('committed_at').where('owner_did', '=', receipt.ownerDID).where('connector_name', '=', receipt.connectorName).where('partition', '=', receipt.partition).where('provenance', '=', receipt.provenance).executeTakeFirst();
+                // A replay of a committed receipt has nothing left to verify.
+                if (existing?.committed_at != null) return;
+                if (existing == null) {
+                    // Recording order per partition, so an older receipt that commits
+                    // late never moves the sweep checkpoint back.
+                    const latest = await tx.selectFrom('kubun_connector_sweep_receipt').select((eb)=>eb.fn.max('sequence').as('sequence')).where('owner_did', '=', receipt.ownerDID).where('connector_name', '=', receipt.connectorName).where('partition', '=', receipt.partition).executeTakeFirst();
+                    await tx.insertInto('kubun_connector_sweep_receipt').values({
+                        owner_did: receipt.ownerDID,
+                        connector_name: receipt.connectorName,
+                        partition: receipt.partition,
+                        provenance: receipt.provenance,
+                        sequence: Number(latest?.sequence ?? 0) + 1,
+                        model_id: receipt.modelID,
+                        scope: encodeJSONColumn(receipt.scope),
+                        keep: encodeJSONColumn(receipt.keep),
+                        source_fetch_hlc: receipt.sourceFetchHLC,
+                        predicate: encodeJSONColumn(receipt.predicate),
+                        kind: receipt.kind,
+                        complete: 1,
+                        created_at: now(),
+                        committed_at: null
+                    }).execute();
+                }
+                for (const candidate of candidates){
+                    await tx.insertInto('kubun_connector_sweep_candidate').values({
+                        owner_did: receipt.ownerDID,
+                        connector_name: receipt.connectorName,
+                        partition: receipt.partition,
+                        provenance: receipt.provenance,
+                        document_id: candidate.documentID,
+                        source_id: candidate.sourceID,
+                        model_id: candidate.modelID,
+                        state: 'pending',
+                        attempts: 0,
+                        apply_failures: 0,
+                        last_error: null,
+                        updated_at: now(),
+                        next_attempt_at: 0
+                    }).onConflict((oc)=>oc.doNothing()).execute();
+                }
+            });
+        },
+        async listSweepReceipts (key) {
+            const rows = await db.selectFrom('kubun_connector_sweep_receipt').selectAll().where('owner_did', '=', key.ownerDID).where('connector_name', '=', key.connectorName).where('committed_at', 'is', null).orderBy('created_at').execute();
+            return rows.map((row)=>({
+                    ownerDID: row.owner_did,
+                    connectorName: row.connector_name,
+                    partition: row.partition,
+                    provenance: row.provenance,
+                    modelID: row.model_id,
+                    scope: decodeJSONColumn(row.scope),
+                    keep: decodeJSONColumn(row.keep),
+                    sourceFetchHLC: row.source_fetch_hlc,
+                    predicate: decodeJSONColumn(row.predicate),
+                    complete: row.complete === 1,
+                    kind: row.kind
+                }));
+        },
+        async listSweepCandidates (key) {
+            let query = db.selectFrom('kubun_connector_sweep_candidate').selectAll().where('owner_did', '=', key.ownerDID).where('connector_name', '=', key.connectorName).orderBy('updated_at').orderBy('document_id');
+            if (key.dueAt != null) {
+                query = query.where('state', 'not in', [
+                    'applied',
+                    'refused'
+                ]).where('next_attempt_at', '<=', key.dueAt);
+            }
+            const rows = await query.execute();
+            return rows.map((row)=>({
+                    ownerDID: row.owner_did,
+                    connectorName: row.connector_name,
+                    partition: row.partition,
+                    provenance: row.provenance,
+                    documentID: row.document_id,
+                    sourceID: row.source_id,
+                    modelID: row.model_id,
+                    state: row.state,
+                    attempts: row.attempts,
+                    applyFailures: row.apply_failures,
+                    lastError: row.last_error,
+                    updatedAt: Number(row.updated_at),
+                    nextAttemptAt: Number(row.next_attempt_at)
+                }));
+        },
+        async recordSweepOutcome (input) {
+            await db.updateTable('kubun_connector_sweep_candidate').set((eb)=>({
+                    state: input.outcome,
+                    attempts: eb('attempts', '+', 1),
+                    last_error: input.lastError ?? null,
+                    updated_at: now(),
+                    next_attempt_at: input.nextAttemptAt ?? 0
+                })).where('owner_did', '=', input.ownerDID).where('connector_name', '=', input.connectorName).where('partition', '=', input.partition).where('provenance', '=', input.provenance).where('document_id', '=', input.documentID).where('state', 'not in', [
+                'applied',
+                'refused'
+            ]).execute();
+        },
+        async recordSweepApplyFailure (input) {
+            const row = await db.updateTable('kubun_connector_sweep_candidate').set((eb)=>({
+                    state: eb.case().when('apply_failures', '>=', MAX_SWEEP_APPLY_ATTEMPTS - 1).then('refused').else('pending').end(),
+                    apply_failures: eb('apply_failures', '+', 1),
+                    last_error: input.lastError,
+                    next_attempt_at: input.nextAttemptAt,
+                    updated_at: now()
+                })).where('owner_did', '=', input.ownerDID).where('connector_name', '=', input.connectorName).where('partition', '=', input.partition).where('provenance', '=', input.provenance).where('document_id', '=', input.documentID).where('state', 'not in', [
+                'applied',
+                'refused'
+            ]).returning('state').executeTakeFirst();
+            return row?.state === 'refused';
+        },
+        async markSweepCandidateApplied (key) {
+            await db.updateTable('kubun_connector_sweep_candidate').set({
+                state: 'applied',
+                last_error: null,
+                next_attempt_at: 0,
+                updated_at: now()
+            }).where('owner_did', '=', key.ownerDID).where('connector_name', '=', key.connectorName).where('partition', '=', key.partition).where('provenance', '=', key.provenance).where('document_id', '=', key.documentID).where('state', 'in', [
+                'present',
+                'absent',
+                'cancelled'
+            ]).execute();
+        },
+        async commitSweepCheckpoint (key) {
+            return db.transaction().execute(async (tx)=>{
+                const receipt = await tx.selectFrom('kubun_connector_sweep_receipt').select([
+                    'complete',
+                    'committed_at',
+                    'sequence'
+                ]).where('owner_did', '=', key.ownerDID).where('connector_name', '=', key.connectorName).where('partition', '=', key.partition).where('provenance', '=', key.provenance).executeTakeFirst();
+                if (receipt?.complete !== 1 || receipt.committed_at != null) return false;
+                const unresolved = await tx.selectFrom('kubun_connector_sweep_candidate').select('document_id').where('owner_did', '=', key.ownerDID).where('connector_name', '=', key.connectorName).where('partition', '=', key.partition).where('provenance', '=', key.provenance).where('state', 'not in', [
+                    'applied',
+                    'refused'
+                ]).executeTakeFirst();
+                if (unresolved != null) return false;
+                const sequence = Number(receipt.sequence);
+                // A later relist must not advance past an earlier unresolved candidate.
+                const earlier = await tx.selectFrom('kubun_connector_sweep_candidate as candidate').innerJoin('kubun_connector_sweep_receipt as receipt', (join)=>join.onRef('receipt.owner_did', '=', 'candidate.owner_did').onRef('receipt.connector_name', '=', 'candidate.connector_name').onRef('receipt.partition', '=', 'candidate.partition').onRef('receipt.provenance', '=', 'candidate.provenance')).select('candidate.document_id').where('candidate.owner_did', '=', key.ownerDID).where('candidate.connector_name', '=', key.connectorName).where('candidate.partition', '=', key.partition).where('candidate.state', 'not in', [
+                    'applied',
+                    'refused'
+                ]).where('receipt.sequence', '<', sequence).executeTakeFirst();
+                if (earlier != null) return false;
+                await tx.insertInto('kubun_connector_sweep_checkpoint').values({
+                    owner_did: key.ownerDID,
+                    connector_name: key.connectorName,
+                    partition: key.partition,
+                    provenance: key.provenance,
+                    receipt_sequence: sequence,
+                    updated_at: now()
+                }).onConflict((oc)=>oc.columns([
+                        'owner_did',
+                        'connector_name',
+                        'partition'
+                    ]).doUpdateSet({
+                        provenance: key.provenance,
+                        receipt_sequence: sequence,
+                        updated_at: now()
+                    }).where('kubun_connector_sweep_checkpoint.receipt_sequence', '<', sequence)).execute();
+                // Applied rows can be discarded; refused rows retain their error for inspection.
+                // The committed receipt prevents replay from re-verifying either outcome.
+                await tx.deleteFrom('kubun_connector_sweep_candidate').where('owner_did', '=', key.ownerDID).where('connector_name', '=', key.connectorName).where('partition', '=', key.partition).where('provenance', '=', key.provenance).where('state', '=', 'applied').execute();
+                await tx.updateTable('kubun_connector_sweep_receipt').set({
+                    committed_at: now()
+                }).where('owner_did', '=', key.ownerDID).where('connector_name', '=', key.connectorName).where('partition', '=', key.partition).where('provenance', '=', key.provenance).execute();
+                return true;
+            });
+        },
+        async getSweepCheckpoint (key) {
+            const row = await db.selectFrom('kubun_connector_sweep_checkpoint').select('provenance').where('owner_did', '=', key.ownerDID).where('connector_name', '=', key.connectorName).where('partition', '=', key.partition).executeTakeFirst();
+            return row?.provenance ?? null;
+        }
+    };
+}

package/lib/sync-state.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export type SyncStateMethods = Pick<ConnectorStoreAPI, 'getSyncState' | 'setSyncState' | 'updateSyncProgress' | 'deleteSyncState' | 'listSyncStatesForConnector'>;
+export declare function createSyncStateMethods(context: ConnectorStoreContext): SyncStateMethods;

package/lib/sync-state.js

@@ -0,0 +1,107 @@
+import { decodeJSONColumn, encodeJSONColumn, rowToSyncState } from './serialization.js';
+export function createSyncStateMethods(context) {
+    const { db, getRandomID } = context;
+    const methods = {
+        // --- 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();
+            if (row == null) return null;
+            return rowToSyncState(row);
+        },
+        async setSyncState (connectorName, ownerDID, state) {
+            // `lease_expires_at` is dead: a fresh INSERT sets it null and a conflicting
+            // 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,
+                last_synced_at: state.lastSyncedAt,
+                entity_count: state.entityCount,
+                status: state.status,
+                error: state.error ?? null,
+                lease_expires_at: null,
+                recovery,
+                version: 0,
+                incarnation: getRandomID()
+            }).onConflict((oc)=>oc.columns([
+                    'connector_name',
+                    'owner_did'
+                ]).doUpdateSet({
+                    checkpoint,
+                    last_synced_at: state.lastSyncedAt,
+                    entity_count: state.entityCount,
+                    status: state.status,
+                    error: state.error ?? null,
+                    recovery
+                })).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();
+        },
+        async listSyncStatesForConnector (connectorName) {
+            const rows = await db.selectFrom('kubun_connector_sync_state').selectAll().where('connector_name', '=', connectorName).execute();
+            return rows.map((row)=>({
+                    ...rowToSyncState(row),
+                    connectorName: row.connector_name,
+                    ownerDID: row.owner_did
+                }));
+        }
+    };
+    return methods;
+}