@kubun/plugin-connector 0.12.1 → 0.13.0

package/lib/index.js

@@ -1,4 +1,7 @@
+import { isSigningIdentity } from '@kokuin/token';
+import { createCredentialManager } from '@kubun/credential';
 import { connectorStoreDefinition } from '@kubun/store-connector';
+import { credentialStoreDefinition, getCredentialStore } from '@kubun/store-credential';
 import { executeAction } from './action.js';
 import { createConnectorAPI } from './api.js';
 import { DBCredentialProvider } from './credential.js';
@@ -8,6 +11,8 @@ import { ConnectorRegistry } from './registry.js';
 import { createConnectorSchemaExtension, subscribeToConnectorSyncEvents } from './schema.js';
 import { orchestrateSync } from './sync/orchestrate.js';
 import { DBSyncStateStore } from './sync/state.js';
+import { CONNECTOR_SYNC_CONCURRENCY, CONNECTOR_SYNC_WORKFLOW, createConnectorSyncWorkflow } from './sync/workflow.js';
+import { wrappableDID } from './wrappable.js';
 import { createWriteGrantContext } from './write-grants.js';
 // ---- Re-exports ----
 export { executeAction } from './action.js';
@@ -19,9 +24,8 @@ export { SyncEngine } from './sync/engine.js';
 export { orchestrateSync } from './sync/orchestrate.js';
 export { EntityProcessor } from './sync/processor.js';
 export { DBSyncStateStore } from './sync/state.js';
+export { CONNECTOR_SYNC_CONCURRENCY, CONNECTOR_SYNC_WORKFLOW, createConnectorSyncWorkflow } from './sync/workflow.js';
 export { DBCredentialProvider };
-// ---- Plugin factory options ----
-/** Default sync-lease TTL (5 minutes) — an in-flight sync heartbeats this before expiry. */ const DEFAULT_LEASE_TTL_MS = 300_000;
 // ---- Connector state resolution ----
 async function resolveConnectorState(connectorAPI, registry, credentialProvider, viewerDID, connectorName) {
     const connector = registry.get(connectorName);
@@ -32,10 +36,15 @@ async function resolveConnectorState(connectorAPI, registry, credentialProvider,
     let authenticated = false;
     let hasWriteAccess = false;
     let authExpiresAt = null;
+    let credentialUpdatedAt = null;
+    let credentialWriterDID = null;
     if (connector.auth.provider !== 'device') {
         const credential = await credentialProvider.get(connector.auth.provider, viewerDID);
         if (credential != null) {
             authenticated = true;
+            const provenance = await connectorAPI.getCredentialProvenance(connector.auth.provider, viewerDID);
+            credentialUpdatedAt = provenance?.updatedAt ?? null;
+            credentialWriterDID = provenance?.writerDID ?? null;
             if (credential.expiresAt != null) {
                 authExpiresAt = credential.expiresAt.toISOString();
             }
@@ -54,6 +63,8 @@ async function resolveConnectorState(connectorAPI, registry, credentialProvider,
             authenticated,
             hasWriteAccess,
             authExpiresAt,
+            credentialUpdatedAt,
+            credentialWriterDID,
             lastSyncedAt: null,
             entityCount: null,
             error: null
@@ -65,6 +76,8 @@ async function resolveConnectorState(connectorAPI, registry, credentialProvider,
         authenticated,
         hasWriteAccess,
         authExpiresAt,
+        credentialUpdatedAt,
+        credentialWriterDID,
         lastSyncedAt: syncState.lastSyncedAt ?? null,
         entityCount: syncState.entityCount ?? null,
         error: syncState.error ?? null
@@ -73,9 +86,17 @@ async function resolveConnectorState(connectorAPI, registry, credentialProvider,
 // ---- Plugin factory ----
 export function createConnectorPlugin(options) {
     const providers = options.providers ?? [];
-    const leaseMs = options.syncLeaseTTL ?? DEFAULT_LEASE_TTL_MS;
     return (params)=>{
         params.db.register(connectorStoreDefinition);
+        params.db.register(credentialStoreDefinition);
+        // Refused at construction, not at the first write: every credential row this
+        // plugin stores carries an op signed by this identity, so an engine identity
+        // that cannot sign would fail on the first connector authorization instead
+        // of when the plugin was installed.
+        if (!isSigningIdentity(params.identity)) {
+            throw new Error('The connector plugin requires a SigningIdentity');
+        }
+        const identity = params.identity;
         const logger = params.getLogger('connector');
         // On a multi-tenant server the connector signs writes with the server
         // identity, but imported documents must be owned by the account viewer. A
@@ -86,9 +107,49 @@ export function createConnectorPlugin(options) {
         for (const connector of options.connectors){
             registry.register(connector);
         }
+        // Resolve the blob plugin's API lazily and once. Absent in a local-only app
+        // with no blob plugin — actions that need it must handle that. The action
+        // runs inside the request's mutation transaction, so the row insert must go
+        // through the request's provider (writeAttachmentTx), not the plugin's
+        // top-level db, which would open a second, deadlocking transaction.
+        let blobAPIPromise;
+        const getBlobAPI = ()=>{
+            if (blobAPIPromise == null) {
+                blobAPIPromise = params.engine.getAPI('blob').catch(()=>undefined);
+            }
+            return blobAPIPromise;
+        };
+        const serverWrappableDID = wrappableDID(params.identity);
+        // One manager per StoreProvider: the request-scoped provider is the
+        // mutation's transaction, and a manager built over the base provider would
+        // read outside it. The key cache is per-manager, which is the same scope the
+        // content key should have.
+        const managers = new WeakMap();
+        function getCredentialManager(stores) {
+            let manager = managers.get(stores);
+            if (manager == null) {
+                manager = getCredentialStore(stores).then((store)=>createCredentialManager({
+                        store,
+                        identity,
+                        runtime: params.runtime,
+                        hlc: params.hlc
+                    }));
+                managers.set(stores, manager);
+            }
+            return manager;
+        }
+        // Controller resolvers for `did:kokuin:` wrapping recipients, scoped to the
+        // request's transaction provider so a resolve reads the mutation's tx rather
+        // than a second connection.
+        const getControllerMethods = (stores)=>[
+                params.controllerResolverFor(stores)
+            ];
         const connectorAPI = createConnectorAPI({
             stores: params.db,
-            cipher: params.cipher
+            logger,
+            getCredentialManager,
+            serverWrappableDID,
+            getControllerMethods
         });
         const credentialProvider = new DBCredentialProvider({
             api: connectorAPI,
@@ -110,6 +171,35 @@ export function createConnectorPlugin(options) {
             credentialProvider,
             connectorAPI
         });
+        // The primary sync path: enqueue a durable `connector-sync` workflow whose
+        // engine owns the lease, checkpointing and crash-recovery. Built once here;
+        // registered lazily the first time the workflow API resolves.
+        const connectorSyncWorkflow = createConnectorSyncWorkflow({
+            registry,
+            credentialProvider,
+            stateStore,
+            syncEventEmitter: manager,
+            stores: params.db,
+            mutateDocuments: params.graph.mutateDocuments,
+            boundary: options.defaults?.boundary,
+            logger
+        });
+        let workflowAPIPromise;
+        const getWorkflowAPI = ()=>{
+            if (workflowAPIPromise == null) {
+                workflowAPIPromise = params.engine.getAPI('workflow').then((api)=>{
+                    api.defineQueue(CONNECTOR_SYNC_WORKFLOW, {
+                        concurrency: CONNECTOR_SYNC_CONCURRENCY
+                    });
+                    api.register(connectorSyncWorkflow.definition);
+                    return api;
+                }).catch(()=>undefined);
+            }
+            return workflowAPIPromise;
+        };
+        // Process-local dedup for the no-workflow-plugin fallback path only (the
+        // workflow singleton guards the primary path).
+        const orchestrateInFlight = new Set();
         return {
             name: 'connector',
             schemaExtension: (config)=>createConnectorSchemaExtension({
@@ -123,7 +213,10 @@ export function createConnectorPlugin(options) {
                     // request's StoreProvider (transactional during mutations).
                     const requestAPI = createConnectorAPI({
                         stores,
-                        cipher: params.cipher
+                        logger,
+                        getCredentialManager,
+                        serverWrappableDID,
+                        getControllerMethods
                     });
                     const requestCredentialProvider = new DBCredentialProvider({
                         api: requestAPI,
@@ -145,24 +238,41 @@ export function createConnectorPlugin(options) {
                                     connectorName: args.connector
                                 };
                             }
-                            // Defer sync to after transaction commits — orchestrateSync starts
-                            // fire-and-forget background work that uses KubunDB.getStore() directly,
-                            // which would deadlock if the mutation transaction still holds the connection.
+                            const connectorName = args.connector;
+                            const ownerDID = ctx.viewerDID;
+                            const full = args.full ?? false;
+                            // Defer to after the mutation commits — both the workflow enqueue
+                            // (a store insert) and the fallback background run use the top-level
+                            // db, which would deadlock if the mutation still held the connection.
                             stores.onCommit(()=>{
-                                orchestrateSync({
-                                    connectorName: args.connector,
-                                    full: args.full ?? false,
-                                    registry,
-                                    syncEventEmitter: manager,
-                                    stateStore,
-                                    credentialProvider,
-                                    ownerDID: ctx.viewerDID,
-                                    stores: params.db,
-                                    boundary: options.defaults?.boundary,
-                                    leaseMs,
-                                    logger,
-                                    mutateDocuments: params.graph.mutateDocuments
-                                }).catch(()=>{});
+                                void (async ()=>{
+                                    const workflowAPI = await getWorkflowAPI();
+                                    if (workflowAPI != null) {
+                                        await workflowAPI.enqueue(CONNECTOR_SYNC_WORKFLOW, {
+                                            connectorName,
+                                            ownerDID,
+                                            full
+                                        }, {
+                                            singletonKey: `${connectorName}:${ownerDID}`
+                                        });
+                                        return;
+                                    }
+                                    // No workflow plugin (local-only app): run inline.
+                                    await orchestrateSync({
+                                        connectorName,
+                                        full,
+                                        registry,
+                                        syncEventEmitter: manager,
+                                        stateStore,
+                                        credentialProvider,
+                                        ownerDID,
+                                        stores: params.db,
+                                        boundary: options.defaults?.boundary,
+                                        inFlight: orchestrateInFlight,
+                                        logger,
+                                        mutateDocuments: params.graph.mutateDocuments
+                                    });
+                                })().catch(()=>{});
                             });
                             return {
                                 status: 'STARTED',
@@ -172,6 +282,10 @@ export function createConnectorPlugin(options) {
                         subscribeToSyncEvents: (connector)=>subscribeToConnectorSyncEvents(manager.syncEvents, connector),
                         executeAction: async (args, writeDocument)=>{
                             try {
+                                // Bind the blob write to THIS request's transactional provider so
+                                // the row insert joins the mutation transaction.
+                                const blob = await getBlobAPI();
+                                const writeAttachment = blob != null ? (input, options)=>blob.writeAttachmentTx(stores, input, options) : undefined;
                                 const result = await executeAction({
                                     connector: args.connector,
                                     action: args.action,
@@ -184,7 +298,8 @@ export function createConnectorPlugin(options) {
                                     credentialProvider: requestCredentialProvider,
                                     ownerDID: ctx.viewerDID,
                                     logger,
-                                    writeDocument
+                                    writeDocument,
+                                    writeAttachment
                                 });
                                 return {
                                     documentID: result.documentID,

package/lib/manager.d.ts

@@ -21,7 +21,6 @@ export type ConnectorManagerParams = {
     logger: Logger;
     defaults?: {
         boundary?: SyncBoundary;
-        pollingInterval?: string;
     };
 };
 export declare class ConnectorManager {
@@ -29,7 +28,6 @@ export declare class ConnectorManager {
     constructor(params: ConnectorManagerParams);
     get defaults(): {
         boundary: SyncBoundary;
-        pollingInterval: string;
     };
     activateForGraph(graphID: string, connectorNames: Array<string>): void;
     deactivateForGraph(graphID: string, connectorNames: Array<string>): void;

package/lib/manager.js

@@ -12,8 +12,7 @@ export class ConnectorManager {
         this.#defaults = {
             boundary: params.defaults?.boundary ?? {
                 maxAge: 'P90D'
-            },
-            pollingInterval: params.defaults?.pollingInterval ?? 'PT5M'
+            }
         };
     }
     get defaults() {

package/lib/oauth.js

@@ -1,5 +1,6 @@
 import { sha256 } from '@noble/hashes/sha2.js';
 import { fromUTF, toB64U } from '@sozai/codec';
+import { canWrapTo } from './wrappable.js';
 // Pending authorization records self-expire after this window; a callback
 // presenting an older state is rejected and the row is swept on the next start.
 const PENDING_AUTH_TTL_MS = 10 * 60 * 1000;
@@ -31,6 +32,19 @@ export class OAuthService {
         if (provider.clientID == null) {
             throw new Error(`OAuth provider "${args.provider}" is missing clientID`);
         }
+        // Carried from here to the callback: the client knows its own long form, and
+        // the callback is the only moment at which the key gets minted.
+        const ownerWrappableDID = args.viewerWrappableDID ?? ownerDID;
+        // Asked here rather than at the mint, which is where it used to fail. By
+        // then the pending row is consumed and the authorization code is spent, so
+        // the provider has issued a real token pair that the failure discards and
+        // the user has to run the whole dance again.
+        if (!await canWrapTo(ownerWrappableDID)) {
+            throw new Error(`Cannot start OAuth for "${args.provider}": nothing can be encrypted to "${ownerWrappableDID}", so the credential's owner could never read it. Pass \`viewerWrappableDID\` — for a did:peer:4 viewer that is the long form, which carries the agreement key.`);
+        }
+        // Carried to the mint like the owner's wrappable DID; it becomes a
+        // recovery recipient later.
+        const controllerWrappableDID = args.controllerWrappableDID ?? undefined;
         const requestWriteAccess = args.requestWriteAccess === true;
         const scopes = new Set(provider.baseScopes ?? []);
         const connectorNames = args.connectors ?? this.#registry.list();
@@ -56,7 +70,13 @@ export class OAuthService {
             state,
             codeVerifier,
             provider: args.provider,
+            // Not normalized: nothing looks this row up by DID — it is keyed on
+            // `state` — and the `ConnectorAPI` boundary normalizes when it files the
+            // credential. Folding it here would put a normalized DID one line from a
+            // wrappable one that must not be.
             ownerDID,
+            ownerWrappableDID,
+            controllerWrappableDID,
             createdAt: Date.now()
         });
         await api.deleteExpiredPendingAuth(Date.now() - PENDING_AUTH_TTL_MS);
@@ -123,11 +143,17 @@ export class OAuthService {
         const scopes = tokenData.scope?.split(' ') ?? [];
         // Bind the credential to the owner that initiated the flow, not the ambient
         // viewer completing the callback, so a stolen code cannot land under another DID.
-        await (credentialProvider ?? this.#credentialProvider).set(args.provider, pending.ownerDID, {
-            accessToken: tokenData.access_token,
-            refreshToken: tokenData.refresh_token,
-            expiresAt: tokenData.expires_in != null ? new Date(Date.now() + tokenData.expires_in * 1000) : undefined,
-            scopes
+        await (credentialProvider ?? this.#credentialProvider).set({
+            providerName: args.provider,
+            ownerDID: pending.ownerDID,
+            credential: {
+                accessToken: tokenData.access_token,
+                refreshToken: tokenData.refresh_token,
+                expiresAt: tokenData.expires_in != null ? new Date(Date.now() + tokenData.expires_in * 1000) : undefined,
+                scopes
+            },
+            ownerWrappableDID: pending.ownerWrappableDID ?? pending.ownerDID,
+            controllerWrappableDID: pending.controllerWrappableDID ?? undefined
         });
         return {
             providerName: args.provider,

package/lib/schema.d.ts

@@ -13,6 +13,8 @@ export type ConnectorState = {
     authenticated: boolean;
     hasWriteAccess: boolean;
     authExpiresAt: string | null;
+    credentialUpdatedAt: string | null;
+    credentialWriterDID: string | null;
     lastSyncedAt: string | null;
     entityCount: number | null;
     error: string | null;
@@ -25,6 +27,22 @@ export type StartConnectorAuthInput = {
     redirectURL: string;
     connectors?: Array<string> | null;
     requestWriteAccess?: boolean | null;
+    /**
+     * The viewer's own DID in a form that can be encrypted to.
+     *
+     * Supplied rather than derived: the viewer DID reaching the server is a
+     * mutation's `iss`, which for `did:peer:4` is the long form only on first
+     * contact with an audience and the short form after. The client always knows
+     * its own long form, and handing it over is what keeps a peer:4 owner able to
+     * read the credential minted for them.
+     */
+    viewerWrappableDID?: string | null;
+    /**
+     * A recovery recipient's DID in a form that can be encrypted to, carried
+     * through to the mint like `viewerWrappableDID`. Not yet turned into a
+     * wrapping.
+     */
+    controllerWrappableDID?: string | null;
 };
 export type StartConnectorAuthOutput = {
     url: string;

package/lib/schema.js

@@ -111,6 +111,8 @@ type Connector implements Node {
   authenticated: Boolean!
   hasWriteAccess: Boolean!
   authExpiresAt: String
+  credentialUpdatedAt: String
+  credentialWriterDID: String
   lastSyncedAt: String
   entityCount: Int
   error: String
@@ -163,7 +165,7 @@ extend type Query {
 }
 
 extend type Mutation {
-  startConnectorAuth(provider: String!, redirectURL: String!, connectors: [String!], requestWriteAccess: Boolean): StartConnectorAuthResult!
+  startConnectorAuth(provider: String!, redirectURL: String!, connectors: [String!], requestWriteAccess: Boolean, viewerWrappableDID: String, controllerWrappableDID: String): StartConnectorAuthResult!
   completeConnectorAuth(provider: String!, code: String!, redirectURL: String!, state: String!): CompleteConnectorAuthResult!
   syncConnector(connector: String!, full: Boolean): SyncTriggerResult!
   grantConnectorWriteCapability(connector: String!, tokens: [String!]!): Boolean!

package/lib/sync/engine.d.ts

@@ -1,8 +1,8 @@
-import type { DataProvider, SyncBoundary, SyncEvent, SyncStateStore } from '@kubun/connector';
+import type { DataProvider, EntityBatch, SyncBoundary, SyncEvent, SyncStateStore } from '@kubun/connector';
 import type { StoreProvider } from '@kubun/db';
 import type { Logger } from '@kubun/logger';
 import type { ClustersRecord } from '@kubun/protocol';
-import { type MutateDocuments } from './processor.js';
+import { type MutateDocuments, type ProcessBatchResult } from './processor.js';
 export type SyncEngineParams = {
     stores: StoreProvider;
     stateStore: SyncStateStore;
@@ -18,11 +18,16 @@ export type RunSyncParams = {
     boundary: SyncBoundary;
     full?: boolean;
     signal?: AbortSignal;
-    leaseMs: number;
 };
 export declare class SyncEngine {
     #private;
     constructor(params: SyncEngineParams);
     on(event: 'sync', callback: (event: SyncEvent) => void): () => void;
+    /**
+     * Fetch + import a single provider batch. The workflow-driven sync path calls
+     * this once per durable tick, reusing the engine's model lookup and processor
+     * cache; {@link run} calls it inline for the no-workflow-plugin fallback.
+     */
+    processBatch(batch: EntityBatch, ownerDID: string): Promise<ProcessBatchResult>;
     run(params: RunSyncParams): Promise<void>;
 }

package/lib/sync/engine.js

@@ -62,8 +62,16 @@ export class SyncEngine {
         this.#processors.set(modelID, processor);
         return processor;
     }
+    /**
+   * Fetch + import a single provider batch. The workflow-driven sync path calls
+   * this once per durable tick, reusing the engine's model lookup and processor
+   * cache; {@link run} calls it inline for the no-workflow-plugin fallback.
+   */ async processBatch(batch, ownerDID) {
+        const processor = this.#getProcessor(batch.modelID, ownerDID);
+        return processor.processBatch(batch);
+    }
     async run(params) {
-        const { provider, ownerDID, boundary, full, signal, leaseMs } = params;
+        const { provider, ownerDID, boundary, full, signal } = params;
         const startTime = Date.now();
         const existingState = await this.#stateStore.get(this.#connectorName, ownerDID);
         const isIncremental = !full && existingState?.checkpoint != null;
@@ -119,8 +127,6 @@ export class SyncEngine {
                     entityCount: (existingState?.entityCount ?? 0) + totalProcessed,
                     status: 'syncing'
                 });
-                // Heartbeat the lease so a long-running sync is not reclaimed mid-flight.
-                await this.#stateStore.renewSync(this.#connectorName, ownerDID, leaseMs);
             }
             const duration = Date.now() - startTime;
             await this.#stateStore.set(this.#connectorName, ownerDID, {

package/lib/sync/orchestrate.d.ts

@@ -21,10 +21,17 @@ export type OrchestrateSyncParams = {
     ownerDID: string;
     stores: StoreProvider;
     boundary?: SyncBoundary;
-    leaseMs: number;
     logger: Logger;
     /** Engine-signed write helper routing imports through the mutation pipeline. */
     mutateDocuments?: MutateDocuments;
+    /**
+     * Process-local guard against a concurrent duplicate pass for the same
+     * (connector, owner). This is the fallback path taken only when no workflow
+     * plugin is installed (a local-only app); the workflow engine's singleton is
+     * the guard on the primary path. Omitted = no guard (double-runs are benign:
+     * imports upsert by unique key).
+     */
+    inFlight?: Set<string>;
 };
 export type OrchestrateSyncResult = {
     status: 'started' | 'already_syncing' | 'error';

package/lib/sync/orchestrate.js

@@ -1,35 +1,41 @@
 import { SyncEngine } from './engine.js';
 export async function orchestrateSync(params) {
-    const { connectorName, full, registry, syncEventEmitter, stateStore, credentialProvider, ownerDID, stores, leaseMs, logger } = params;
+    const { connectorName, full, registry, syncEventEmitter, stateStore, credentialProvider, ownerDID, stores, inFlight, logger } = params;
     const connector = registry.get(connectorName);
     if (connector == null) {
         return {
             status: 'error'
         };
     }
+    // Reserve the (connector, owner) synchronously — before any await — so two
+    // concurrent triggers cannot both pass the check. Released once the run
+    // settles (or here on any early bail).
+    const guardKey = `${connectorName}:${ownerDID}`;
+    if (inFlight != null) {
+        if (inFlight.has(guardKey)) {
+            return {
+                status: 'already_syncing'
+            };
+        }
+        inFlight.add(guardKey);
+    }
+    const release = ()=>inFlight?.delete(guardKey);
     // Get credentials for OAuth connectors
     const providerName = connector.auth.provider !== 'device' ? connector.auth.provider : null;
     const credential = providerName ? await credentialProvider.get(providerName, ownerDID) : null;
     if (providerName != null && credential == null) {
+        release();
         return {
             status: 'error'
         };
     }
     // Ensure server provider is available
     if (connector.serverProvider == null) {
+        release();
         return {
             status: 'error'
         };
     }
-    // Atomically claim the sync lease. This happens after the validation paths
-    // above so a failed claim never leaves a live lease with no running sync.
-    // A stale/expired lease (e.g. from a crashed run) is reclaimed automatically.
-    const claimed = await stateStore.claimSync(connectorName, ownerDID, leaseMs);
-    if (!claimed) {
-        return {
-            status: 'already_syncing'
-        };
-    }
     const effectiveBoundary = params.boundary ?? {
         maxAge: 'P90D'
     };
@@ -85,15 +91,14 @@ export async function orchestrateSync(params) {
         provider,
         ownerDID,
         boundary: effectiveBoundary,
-        full,
-        leaseMs
+        full
     }).catch(async (err)=>{
         await syncEventEmitter.emitSyncEvent({
             type: 'error',
             connectorName,
             error: err instanceof Error ? err.message : String(err)
         });
-    });
+    }).finally(release);
     return {
         status: 'started'
     };

package/lib/sync/state.d.ts

@@ -12,8 +12,6 @@ export declare class DBSyncStateStore implements SyncStateStore {
     });
     get(connectorName: string, ownerDID: string): Promise<SyncState | null>;
     set(connectorName: string, ownerDID: string, state: SyncState): Promise<void>;
-    claimSync(connectorName: string, ownerDID: string, leaseMs: number): Promise<boolean>;
-    renewSync(connectorName: string, ownerDID: string, leaseMs: number): Promise<void>;
     delete(connectorName: string, ownerDID: string): Promise<void>;
     listForConnector(connectorName: string): Promise<Array<SyncStateEntry>>;
 }

package/lib/sync/state.js

@@ -31,12 +31,6 @@
             error: state.error ?? null
         });
     }
-    async claimSync(connectorName, ownerDID, leaseMs) {
-        return this.#api.claimSync(connectorName, ownerDID, leaseMs);
-    }
-    async renewSync(connectorName, ownerDID, leaseMs) {
-        await this.#api.renewSync(connectorName, ownerDID, leaseMs);
-    }
     async delete(connectorName, ownerDID) {
         await this.#api.deleteSyncState(connectorName, ownerDID);
     }

package/lib/sync/workflow.d.ts

@@ -0,0 +1,59 @@
+import type { CredentialProvider, SyncBoundary, SyncStateStore } from '@kubun/connector';
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { ConnectorRegistry } from '../registry.js';
+import type { SyncEventEmitter } from './orchestrate.js';
+import { type MutateDocuments } from './processor.js';
+/** Queue lane (and workflow name) for connector sync. */
+export declare const CONNECTOR_SYNC_WORKFLOW = "connector-sync";
+/** How many connector syncs may run at once on this peer. */
+export declare const CONNECTOR_SYNC_CONCURRENCY = 4;
+type HandlerContext = {
+    state: Record<string, unknown>;
+    params?: unknown;
+    signal?: AbortSignal;
+};
+type HandlerResult = {
+    status: 'action';
+    state: Record<string, unknown>;
+    action: {
+        name: string;
+    };
+} | {
+    status: 'end';
+    state: Record<string, unknown>;
+};
+type ConnectorSyncHandler = (ctx: HandlerContext) => Promise<HandlerResult>;
+export type ConnectorSyncWorkflowDefinition = {
+    name: string;
+    initialAction: {
+        name: string;
+    };
+    handlers: Record<string, ConnectorSyncHandler>;
+};
+export type ConnectorSyncWorkflowParams = {
+    registry: ConnectorRegistry;
+    credentialProvider: CredentialProvider;
+    stateStore: SyncStateStore;
+    syncEventEmitter: SyncEventEmitter;
+    stores: StoreProvider;
+    mutateDocuments?: MutateDocuments;
+    boundary?: SyncBoundary;
+    logger: Logger;
+};
+/**
+ * Build the `connector-sync` workflow definition. One sync pass is a self-looping
+ * flow: `start` validates + seeds state, `batch` fetches+imports ONE provider
+ * batch per durable tick and advances the checkpoint, `finalize` marks idle. The
+ * workflow engine checkpoints the row and renews the lease between ticks, so the
+ * hand-rolled per-batch lease heartbeat is gone; the engine's crash-recovery
+ * re-drives `batch` from the persisted checkpoint.
+ *
+ * Each call returns a definition with its OWN in-process session map, so two
+ * definitions (two "boots" over one DB) do not share iterators — which is what
+ * makes crash-recovery re-open the provider from the checkpoint.
+ */
+export declare function createConnectorSyncWorkflow(params: ConnectorSyncWorkflowParams): {
+    definition: ConnectorSyncWorkflowDefinition;
+};
+export {};