@kubun/store-connector 0.17.1 → 0.18.0

package/lib/api.js

@@ -1,179 +1,124 @@
-// --- 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) {
-    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;
-}
+import { AbstractPostgresAdapter } from '@kubun/db-adapter';
+import { createDocumentSweepMethods } from './document-sweep.js';
+import { createEntityTrimMethods } from './entity-trim.js';
+import { createObservationRecordMethods } from './observation-records.js';
+import { createOperationsMethods } from './operations.js';
+import { createPendingAuthMethods } from './pending-auth.js';
+import { createProjectionWatchesMethods } from './projection-watches.js';
+import { createRetentionMethods } from './retention.js';
+import { encodeJSONColumn } from './serialization.js';
+import { createSweepStateMethods } from './sweep-state.js';
+import { createSyncStateMethods } from './sync-state.js';
 // --- Factory function ---
-export function createConnectorStore(db, _adapter) {
-    return {
-        // --- 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: globalThis.crypto.randomUUID()
-            }).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: globalThis.crypto.randomUUID()
-                    }).onConflict((oc)=>oc.columns([
-                            'connector_name',
-                            'owner_did'
-                        ]).doNothing()).executeTakeFirst();
-                    if ((inserted?.numInsertedOrUpdatedRows ?? 0n) > 0n) return;
-                    continue;
+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 context = {
+        db,
+        adapter,
+        isPostgres,
+        deps,
+        getRandomID
+    };
+    const api = {
+        ...createObservationRecordMethods(db, adapter),
+        ...createSyncStateMethods(context),
+        ...createSweepStateMethods(context),
+        ...createEntityTrimMethods(context),
+        ...createDocumentSweepMethods(context),
+        ...createPendingAuthMethods(context),
+        ...createOperationsMethods(context),
+        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;
                 }
-                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
-                }));
-        },
-        // --- Pending OAuth authorization operations ---
-        async createPendingAuth (record) {
-            await db.insertInto('kubun_connector_pending_auth').values({
-                state: record.state,
-                code_verifier: record.codeVerifier,
-                provider: record.provider,
-                owner_did: record.ownerDID,
-                owner_wrappable_did: record.ownerWrappableDID ?? null,
-                controller_wrappable_did: record.controllerWrappableDID ?? null,
-                created_at: record.createdAt,
-                redirect_url: record.redirectURL,
-                scopes: JSON.stringify(record.scopes),
-                expires_at: record.expiresAt
-            }).execute();
+                // 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;
+            });
         },
-        async consumePendingAuth (state) {
-            // Atomic single-use read: DELETE ... RETURNING removes and returns the row
-            // in one statement so concurrent callbacks cannot both consume the state.
-            const row = await db.deleteFrom('kubun_connector_pending_auth').where('state', '=', state).returningAll().executeTakeFirst();
-            if (row == null) return null;
-            return {
-                state: row.state,
-                codeVerifier: row.code_verifier,
-                provider: row.provider,
-                ownerDID: row.owner_did,
-                ownerWrappableDID: row.owner_wrappable_did,
-                controllerWrappableDID: row.controller_wrappable_did,
-                createdAt: row.created_at,
-                redirectURL: row.redirect_url,
-                // ParseJSONResultsPlugin may have already parsed this column, same as
-                // `checkpoint` in `rowToSyncState`.
-                scopes: typeof row.scopes === 'string' ? JSON.parse(row.scopes) : row.scopes,
-                expiresAt: row.expires_at
-            };
+        ...createProjectionWatchesMethods(context),
+        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 deleteExpiredPendingAuth (cutoffMs) {
-            // Strict `<` matches @kokuin/oauth `completeAuthorization`, which treats a
-            // record as expired only when `expiresAt < now`. A record at exactly
-            // `expiresAt === cutoffMs` is therefore still consumable and is kept here
-            // (the next sweep, once `now > expiresAt`, removes it). This intentionally
-            // keeps one more record than the `PendingAuthStore.deleteExpired` port doc
-            // ("at or before nowMs") so the sweep and the consume check agree on the
-            // expiry boundary.
-            await db.deleteFrom('kubun_connector_pending_auth').where('expires_at', '<', cutoffMs).execute();
-        }
+        ...createRetentionMethods(context)
     };
+    return api;
 }

package/lib/definition.d.ts

@@ -1,4 +1,9 @@
 import type { StoreDefinition } from '@kubun/db';
-import type { ConnectorStoreAPI } from './api.js';
+import type { ConnectorStoreAPI, ConnectorStoreDeps } from './api.js';
 import type { ConnectorTables } from './tables.js';
-export declare const connectorStoreDefinition: StoreDefinition<ConnectorTables, ConnectorStoreAPI>;
+/**
+ * The connector store's definition, its API bound to `deps`:
+ * `KubunDB.register`/`getStore` call `createAPI(db, adapter)` with exactly two
+ * arguments, so the dependencies close over here.
+ */
+export declare function createConnectorStoreDefinition(deps: ConnectorStoreDeps): StoreDefinition<ConnectorTables, ConnectorStoreAPI>;

package/lib/definition.js

@@ -1,7 +1,13 @@
 import { createConnectorStore } from './api.js';
 import { getConnectorMigrations } from './migrations.js';
-export const connectorStoreDefinition = {
-    name: 'connector',
-    migrations: getConnectorMigrations,
-    createAPI: createConnectorStore
-};
+/**
+ * The connector store's definition, its API bound to `deps`:
+ * `KubunDB.register`/`getStore` call `createAPI(db, adapter)` with exactly two
+ * arguments, so the dependencies close over here.
+ */ export function createConnectorStoreDefinition(deps) {
+    return {
+        name: 'connector',
+        migrations: getConnectorMigrations,
+        createAPI: (db, adapter)=>createConnectorStore(db, adapter, deps)
+    };
+}

package/lib/document-sweep.d.ts

@@ -0,0 +1,8 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export declare class ConnectorDocumentSweepError extends Error {
+    get code(): 'CONNECTOR_SWEEP_UNFINISHED_OPERATION';
+    constructor(documentID: string);
+}
+export type DocumentSweepMethods = Pick<ConnectorStoreAPI, 'hasDocumentConnectorWork' | 'sweepDocumentRows'>;
+export declare function createDocumentSweepMethods({ db }: ConnectorStoreContext): DocumentSweepMethods;

package/lib/document-sweep.js

@@ -0,0 +1,46 @@
+const OBSERVATION_TYPE = 'connector.observation';
+/** States an operation can still leave: its row is the idempotency record of a provider write. */ const UNFINISHED = [
+    'attempted',
+    'reconcile_only'
+];
+const FINISHED = [
+    'committed',
+    'dead'
+];
+export class ConnectorDocumentSweepError extends Error {
+    get code() {
+        return 'CONNECTOR_SWEEP_UNFINISHED_OPERATION';
+    }
+    constructor(documentID){
+        super(`Document ${documentID} has an unfinished connector operation`);
+        this.name = 'ConnectorDocumentSweepError';
+    }
+}
+// Plain statements on `db`, never `db.transaction()`: both run inside the caller's sweep
+// transaction, where a nested transaction is refused.
+export function createDocumentSweepMethods({ db }) {
+    const unfinishedOperation = async (documentID)=>{
+        const row = await db.selectFrom('kubun_connector_operation').select('operation_id').where('document_id', '=', documentID).where('state', 'in', UNFINISHED).limit(1).executeTakeFirst();
+        return row !== undefined;
+    };
+    const anyRow = async (table, documentID)=>{
+        const row = await db.selectFrom(table).select('document_id').where('document_id', '=', documentID).limit(1).executeTakeFirst();
+        return row !== undefined;
+    };
+    return {
+        async hasDocumentConnectorWork (documentID) {
+            return await anyRow('kubun_connector_projection_watch', documentID) || await anyRow('kubun_connector_sweep_candidate', documentID) || await anyRow('kubun_connector_entity_trim', documentID) || await unfinishedOperation(documentID);
+        },
+        async sweepDocumentRows (documentID) {
+            // Deleting it would let a replayed request write to the provider again.
+            if (await unfinishedOperation(documentID)) throw new ConnectorDocumentSweepError(documentID);
+            // Every copy, whatever its owner or signer: the document ID names one document.
+            await db.deleteFrom('kubun_connector_observation_records').where('type', '=', OBSERVATION_TYPE).where('id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_observation_repair').where('document_id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_entity_trim').where('document_id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_projection_watch').where('document_id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_sweep_candidate').where('document_id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_operation').where('document_id', '=', documentID).where('state', 'in', FINISHED).execute();
+        }
+    };
+}

package/lib/entity-trim.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export type EntityTrimMethods = Pick<ConnectorStoreAPI, 'getEntityTrim' | 'setEntityTrim' | 'clearEntityTrim'>;
+export declare function createEntityTrimMethods(context: ConnectorStoreContext): EntityTrimMethods;

package/lib/entity-trim.js

@@ -0,0 +1,36 @@
+import { decodeJSONColumn } from './serialization.js';
+export function createEntityTrimMethods(context) {
+    const { db } = context;
+    const methods = {
+        // --- Entity trim records ---
+        async getEntityTrim (documentID) {
+            const row = await db.selectFrom('kubun_connector_entity_trim').selectAll().where('document_id', '=', documentID).executeTakeFirst();
+            if (row == null) return null;
+            return {
+                documentID: row.document_id,
+                ownerDID: row.owner_did,
+                connectorName: row.connector_name,
+                trimmedFields: decodeJSONColumn(row.trimmed_fields),
+                updatedAt: row.updated_at
+            };
+        },
+        async setEntityTrim (input) {
+            const trimmedFields = JSON.stringify(input.trimmedFields);
+            const updatedAt = Date.now();
+            await db.insertInto('kubun_connector_entity_trim').values({
+                document_id: input.documentID,
+                owner_did: input.ownerDID,
+                connector_name: input.connectorName,
+                trimmed_fields: trimmedFields,
+                updated_at: updatedAt
+            }).onConflict((oc)=>oc.column('document_id').doUpdateSet({
+                    trimmed_fields: trimmedFields,
+                    updated_at: updatedAt
+                })).execute();
+        },
+        async clearEntityTrim (documentID) {
+            await db.deleteFrom('kubun_connector_entity_trim').where('document_id', '=', documentID).execute();
+        }
+    };
+    return methods;
+}

package/lib/index.d.ts

@@ -1,8 +1,11 @@
 import type { StoreProvider } from '@kubun/db';
 import type { ConnectorStoreAPI } from './api.js';
-export type { ConnectorStoreAPI, PendingAuthRecord, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStatus, } from './api.js';
+export type { AcquireLeaseParams, ArmWatchOptions, ArmWatchOutcome, ArmWatchReason, ClaimOperationInput, ConnectorOperation, ConnectorOperationOp, ConnectorOperationState, ConnectorStoreAPI, ConnectorStoreDeps, DeferReason, EntityTrimInput, EntityTrimRecord, FinalizeOperationInput, PendingAuthRecord, ProjectionWatch, ProjectionWatchIdentity, ProjectionWatchVerificationStatus, ReadWinner, ReadWinners, RecordOperationInput, RecordVerificationInput, RecordVerificationOutcome, ReleaseLeaseParams, RenewLeaseParams, SweepApplyFailureInput, SweepCandidate, SweepCandidateInput, SweepCandidateKey, SweepKey, SweepOutcomeInput, SweepReceipt, SweepReceiptKey, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStatus, TrackedOperationFilter, UpdateSyncProgressParams, } from './api.js';
 export { createConnectorStore } from './api.js';
-export { connectorStoreDefinition } from './definition.js';
+export { createConnectorStoreDefinition } from './definition.js';
+export { ConnectorDocumentSweepError } from './document-sweep.js';
+export { ConnectorObservationRecordError, ConnectorObservationRecordTypeError, connectorObservationRecordAdapter, type ObservationRepair, type ObservationRepairWrite, type ObservationRepairWritePage, observationProviderOfRecords, type WrittenObservationRepair, } from './observation-records.js';
+export { MAX_SWEEP_APPLY_ATTEMPTS } from './sweep-state.js';
 export declare const CONNECTOR_STORE: "connector";
 export declare function getConnectorStore(provider: StoreProvider): Promise<ConnectorStoreAPI>;
-export type { ConnectorSyncState, ConnectorSyncStateTable, ConnectorTables, } from './tables.js';
+export type { ConnectorEntityTrim, ConnectorEntityTrimTable, ConnectorSyncState, ConnectorSyncStateTable, ConnectorTables, } from './tables.js';

package/lib/index.js

@@ -1,5 +1,8 @@
 export { createConnectorStore } from './api.js';
-export { connectorStoreDefinition } from './definition.js';
+export { createConnectorStoreDefinition } from './definition.js';
+export { ConnectorDocumentSweepError } from './document-sweep.js';
+export { ConnectorObservationRecordError, ConnectorObservationRecordTypeError, connectorObservationRecordAdapter, observationProviderOfRecords } from './observation-records.js';
+export { MAX_SWEEP_APPLY_ATTEMPTS } from './sweep-state.js';
 export const CONNECTOR_STORE = 'connector';
 export function getConnectorStore(provider) {
     return provider.getStore(CONNECTOR_STORE);

package/lib/migrations.js

@@ -2,6 +2,30 @@ export function getConnectorMigrations(ctx) {
     const t = ctx.types;
     const init = {
         async up (db) {
+            await db.schema.createTable('kubun_connector_sweep_receipt').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('partition', t.text, (col)=>col.notNull()).addColumn('provenance', t.text, (col)=>col.notNull()).addColumn('sequence', t.bigint, (col)=>col.notNull()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('scope', t.text, (col)=>col.notNull()).addColumn('keep', t.text, (col)=>col.notNull()).addColumn('source_fetch_hlc', t.text, (col)=>col.notNull()).addColumn('predicate', t.text).addColumn('kind', t.text, (col)=>col.notNull()).addColumn('complete', 'integer', (col)=>col.notNull()).addColumn('created_at', t.bigint, (col)=>col.notNull()).addColumn('committed_at', t.bigint).addPrimaryKeyConstraint('kubun_connector_sweep_receipt_pkey', [
+                'owner_did',
+                'connector_name',
+                'partition',
+                'provenance'
+            ]).execute();
+            await db.schema.createTable('kubun_connector_sweep_candidate').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('partition', t.text, (col)=>col.notNull()).addColumn('provenance', t.text, (col)=>col.notNull()).addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('source_id', t.text, (col)=>col.notNull()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('state', t.text, (col)=>col.notNull()).addColumn('attempts', 'integer', (col)=>col.notNull()).addColumn('apply_failures', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('last_error', t.text).addColumn('next_attempt_at', t.bigint, (col)=>col.notNull().defaultTo(0)).addColumn('updated_at', t.bigint, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_connector_sweep_candidate_pkey', [
+                'owner_did',
+                'connector_name',
+                'partition',
+                'provenance',
+                'document_id'
+            ]).execute();
+            await db.schema.createIndex('kubun_connector_sweep_candidate_due_idx').ifNotExists().on('kubun_connector_sweep_candidate').columns([
+                'owner_did',
+                'connector_name',
+                'state',
+                'next_attempt_at'
+            ]).execute();
+            await db.schema.createTable('kubun_connector_sweep_checkpoint').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('partition', t.text, (col)=>col.notNull()).addColumn('provenance', t.text, (col)=>col.notNull()).addColumn('receipt_sequence', t.bigint, (col)=>col.notNull()).addColumn('updated_at', t.bigint, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_connector_sweep_checkpoint_pkey', [
+                'owner_did',
+                'connector_name',
+                'partition'
+            ]).execute();
             // Connector sync state
             await db.schema.createTable('kubun_connector_sync_state').ifNotExists().addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('checkpoint', t.text).addColumn('last_synced_at', t.text, (col)=>col.notNull()).addColumn('entity_count', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('status', t.text, (col)=>col.notNull()).addColumn('error', t.text)// Lease expiry for atomic sync-claim coordination. ms-epoch (Date.now)
             // overflows int32 on Postgres; bigint holds it and the adapter's int8
@@ -29,12 +53,106 @@ export function getConnectorMigrations(ctx) {
             // time, both needed to complete the token exchange and to fill in
             // `PendingAuthRecord`'s required fields.
             .addColumn('redirect_url', t.text, (col)=>col.notNull())// JSON-encoded `Array<string>`.
-            .addColumn('scopes', t.text, (col)=>col.notNull())// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            .addColumn('scopes', t.text, (col)=>col.notNull())// 1 when start-auth requested only the missing scopes, else 0.
+            .addColumn('is_incremental', 'integer', (col)=>col.notNull())// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
             // the adapter's int8 parser reads it back as a JS number. The sweep in
             // `deleteExpiredPendingAuth` keys off this column, not `created_at`.
             .addColumn('expires_at', t.bigint, (col)=>col.notNull()).execute();
+            // Connector write-back operation envelope: one row per attempted create/
+            // update, keyed by the caller's idempotency key so a replayed request
+            // (crash recovery, retry) converges on the same row instead of double-
+            // writing to the provider.
+            await db.schema.createTable('kubun_connector_operation').ifNotExists().addColumn('caller_did', t.text, (col)=>col.notNull()).addColumn('operation_id', t.text, (col)=>col.notNull())// An opaque random key assigned at claim time, the operation's public
+            // identity (its GraphQL node id). Kept apart from the caller-supplied
+            // `operation_id`, which is an idempotency key and says nothing about
+            // who may look the operation up.
+            .addColumn('node_key', t.text, (col)=>col.notNull()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('model', t.text, (col)=>col.notNull()).addColumn('op', t.text, (col)=>col.notNull()).addColumn('account_key', t.text, (col)=>col.notNull()).addColumn('target', t.text, (col)=>col.notNull()).addColumn('source_id', t.text).addColumn('deterministic_event_id', t.text, (col)=>col.notNull()).addColumn('payload_hash', t.text, (col)=>col.notNull()).addColumn('reissue_intent', t.text, (col)=>col.notNull()).addColumn('provider_etag', t.text).addColumn('document_id', t.text).addColumn('result_entity', t.text).addColumn('state', t.text, (col)=>col.notNull()).addColumn('attempts', 'integer', (col)=>col.notNull().defaultTo(0))// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            // the adapter's int8 parser reads it back as a JS number.
+            .addColumn('next_attempt_at', t.bigint)// Why `next_attempt_at` was pushed out without spending an attempt, when
+            // that reason can lapse on its own: 'offline' is made due again as soon
+            // as the device reconnects, 'auth' as soon as the owner authorizes.
+            // Null for a backoff or any other deferral.
+            .addColumn('defer_reason', t.text)// The run that started a provider write in the current attempt (a
+            // per-run marker), cleared when a new attempt begins: a re-run of the
+            // same attempt cannot claim no request was ever sent.
+            .addColumn('send_marker', t.text).addColumn('last_kind', t.text).addColumn('last_http_status', 'integer').addColumn('version', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('incarnation', t.text).addColumn('lease_token', t.text)// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            // the adapter's int8 parser reads it back as a JS number.
+            .addColumn('lease_expires_at', t.bigint)// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            // the adapter's int8 parser reads it back as a JS number.
+            .addColumn('created_at', t.bigint, (col)=>col.notNull()).addColumn('updated_at', t.bigint, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_connector_operation_pkey', [
+                'caller_did',
+                'operation_id'
+            ]).execute();
+            await db.schema.createIndex('uq_connector_operation_node_key').ifNotExists().on('kubun_connector_operation').column('node_key').unique().execute();
+            // The operations of a document (its write state), read by document id.
+            await db.schema.createIndex('idx_connector_operation_document').ifNotExists().on('kubun_connector_operation').column('document_id').execute();
+            // The operations an owner may see (`listTrackedOperations({ visibleTo })`
+            // matches the caller through the primary key, the owner through this).
+            await db.schema.createIndex('idx_connector_operation_owner').ifNotExists().on('kubun_connector_operation').column('owner_did').execute();
+            // The retention cleanup's candidates: finished operations by last update.
+            await db.schema.createIndex('idx_connector_operation_state_updated').ifNotExists().on('kubun_connector_operation').columns([
+                'state',
+                'updated_at'
+            ]).execute();
+            // Connector projection verify/repair watch: one row per ingested
+            // provider document being tracked for eventual verification against the
+            // local converged state, with a unique ingress index so the same
+            // (owner, model, document) is only ever watched under one source.
+            await db.schema.createTable('kubun_connector_projection_watch').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('model', t.text, (col)=>col.notNull()).addColumn('account_key', t.text, (col)=>col.notNull()).addColumn('source_id', t.text, (col)=>col.notNull()).addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('verified_state_digest', t.text).addColumn('observed_winner_digest', t.text).addColumn('verification_status', t.text, (col)=>col.notNull()).addColumn('verification_attempts', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('repair_generation', 'integer', (col)=>col.notNull().defaultTo(0))// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            // the adapter's int8 parser reads it back as a JS number.
+            .addColumn('next_attempt_at', t.bigint)// Until when a verifier holds the current attempt (`claimWatchAttempt`);
+            // kept apart from `next_attempt_at`, which an ingress coalesce moves.
+            .addColumn('claimed_until', t.bigint)// As on the operation table: 'offline' when the pending attempt was
+            // deferred only for being offline.
+            .addColumn('defer_reason', t.text).addColumn('version', 'integer', (col)=>col.notNull().defaultTo(0))// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            // the adapter's int8 parser reads it back as a JS number.
+            .addColumn('created_at', t.bigint, (col)=>col.notNull()).addColumn('updated_at', t.bigint, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_connector_projection_watch_pkey', [
+                'owner_did',
+                'connector_name',
+                'model',
+                'account_key',
+                'source_id'
+            ]).execute();
+            // Ingress index: within one owner+model, a given provider document may
+            // only be watched under a single source. A write-back finalized for the
+            // document under another source supersedes the earlier row.
+            await db.schema.createIndex('uq_connector_watch_ingress').ifNotExists().on('kubun_connector_projection_watch').columns([
+                'owner_did',
+                'model',
+                'document_id'
+            ]).unique().execute();
+            // Document lookup: an applied write names only its document id
+            // (`getWatchByDocument`), which the ingress index cannot serve alone.
+            await db.schema.createIndex('idx_connector_watch_document').ifNotExists().on('kubun_connector_projection_watch').column('document_id').execute();
+            await db.schema.createTable('kubun_connector_observation_records').ifNotExists().addColumn('type', t.text, (col)=>col.notNull()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('id', t.text, (col)=>col.notNull()).addColumn('op_hash', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('op_jwt', t.text, (col)=>col.notNull()).addColumn('payload', t.binary).addPrimaryKeyConstraint('kubun_connector_observation_records_pkey', [
+                'type',
+                'owner',
+                'id',
+                'op_hash'
+            ]).execute();
+            await db.schema.createTable('kubun_connector_observation_repair').ifNotExists().addColumn('document_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('fetch_hlc', t.text, (col)=>col.notNull()).addColumn('decision_hlc', t.text, (col)=>col.notNull()).addColumn('present', 'integer', (col)=>col.notNull()).addColumn('value_digest', t.text)// When the obligation was last written, so a reader can take only the
+            // ones written since it last looked.
+            .addColumn('written_at', t.bigint, (col)=>col.notNull()).execute();
+            await db.schema.createIndex('idx_connector_observation_repair_written').ifNotExists().on('kubun_connector_observation_repair').columns([
+                'written_at',
+                'document_id'
+            ]).execute();
+            // The source values fitted to a model's caps when a document was last
+            // written, keyed by that document. Replaced on every write that trims,
+            // removed by one that does not.
+            await db.schema.createTable('kubun_connector_entity_trim').ifNotExists().addColumn('document_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('trimmed_fields', t.text, (col)=>col.notNull())// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            // the adapter's int8 parser reads it back as a JS number.
+            .addColumn('updated_at', t.bigint, (col)=>col.notNull()).execute();
         },
         async down (db) {
+            await db.schema.dropTable('kubun_connector_sweep_checkpoint').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_sweep_candidate').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_sweep_receipt').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_observation_repair').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_observation_records').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_entity_trim').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_projection_watch').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_operation').ifExists().execute();
             await db.schema.dropTable('kubun_connector_pending_auth').ifExists().execute();
             await db.schema.dropTable('kubun_connector_sync_state').ifExists().execute();
         }