@kubun/store-connector 0.17.1 → 0.18.0

package/lib/projection-watches.d.ts

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

package/lib/projection-watches.js

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

package/lib/retention.d.ts

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

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;