@kubun/plugin-connector 0.9.0 → 0.11.0

package/lib/schema.js

@@ -1,4 +1,90 @@
-import{PluginNodeID as t}from"@kubun/id";export function toConnectorSyncEventResult(t){return{type:"started"===t.type?"STARTED":"progress"===t.type?"PROGRESS":"completed"===t.type?"COMPLETED":"ERROR",connectorName:t.connectorName,entitiesProcessed:t.entitiesProcessed??null,entitiesFailed:t.entitiesFailed??null,totalProcessed:t.totalProcessed??null,totalFailed:t.totalFailed??null,duration:t.duration??null,error:t.error??null}}function e(t){if(null==t.connector)throw Error("connector plugin is not wired into this context");return t.connector}function n(t){let e=[];for(let n of Object.values(t.clusters))for(let t of Object.values(n.record)){let o=n.models[t];o?.name==null||e.includes(o.name)||e.push(o.name)}return e}export function createConnectorSchemaExtension(o){let r=o.registry,c=[];c.push(`
+import { PluginNodeID } from '@kubun/id';
+import { fromEmitter } from '@sozai/generator';
+/**
+ * Transform a raw `ConnectorSyncEventPayload` into the GraphQL result shape.
+ */ export function toConnectorSyncEventResult(event) {
+    return {
+        type: event.type === 'started' ? 'STARTED' : event.type === 'progress' ? 'PROGRESS' : event.type === 'completed' ? 'COMPLETED' : 'ERROR',
+        connectorName: event.connectorName,
+        entitiesProcessed: event.entitiesProcessed ?? null,
+        entitiesFailed: event.entitiesFailed ?? null,
+        totalProcessed: event.totalProcessed ?? null,
+        totalFailed: event.totalFailed ?? null,
+        duration: event.duration ?? null,
+        error: event.error ?? null
+    };
+}
+/**
+ * Subscribe to a connector sync-event emitter, yielding GraphQL result shapes.
+ *
+ * Implemented as a manual async iterator rather than an `async function*` wrapper
+ * so that a consumer's `return()` forwards directly to the underlying emitter
+ * generator, removing its listener immediately. A `for await` wrapper instead
+ * queues the `return()` behind a parked `next()` between events, so the emitter
+ * listener would leak until the next event arrives — for an idle subscription,
+ * potentially never.
+ */ export function subscribeToConnectorSyncEvents(emitter, connector) {
+    const filter = connector != null ? (event)=>event.connectorName === connector : undefined;
+    const generator = fromEmitter(emitter, 'sync', {
+        filter
+    });
+    return {
+        [Symbol.asyncIterator] () {
+            return this;
+        },
+        async next () {
+            const { done, value } = await generator.next();
+            return done ? {
+                done: true,
+                value: undefined
+            } : {
+                done: false,
+                value: toConnectorSyncEventResult(value)
+            };
+        },
+        async return () {
+            await generator.return();
+            return {
+                done: true,
+                value: undefined
+            };
+        },
+        async throw (reason) {
+            await generator.throw(reason);
+            return {
+                done: true,
+                value: undefined
+            };
+        }
+    };
+}
+function requireConnector(ctx) {
+    if (ctx.connector == null) {
+        throw new Error('connector plugin is not wired into this context');
+    }
+    return ctx.connector;
+}
+/**
+ * Extract model names from a connector's clusters.
+ * Each cluster has `record` (modelID → index) and `models` (array of model defs).
+ */ function getConnectorModelNames(connector) {
+    const names = [];
+    for (const cluster of Object.values(connector.clusters)){
+        for (const index of Object.values(cluster.record)){
+            const model = cluster.models[index];
+            if (model?.name != null && !names.includes(model.name)) {
+                names.push(model.name);
+            }
+        }
+    }
+    return names;
+}
+export function createConnectorSchemaExtension(params) {
+    const registry = params.registry;
+    // ---- Build SDL ----
+    const sdlParts = [];
+    // Core types
+    sdlParts.push(`
 enum ConnectorSyncStatus {
   IDLE
   SYNCING
@@ -62,35 +148,236 @@ type ConnectorActionError {
   requiredScopes: [String!]
 }
 
+type ConnectorWriteGrant {
+  connector: String!
+  provider: String!
+  modelURNs: [String!]!
+  exp: Int!
+  jti: String!
+}
+
 extend type Query {
   connector(name: String!): Connector!
   connectors: [Connector!]!
+  connectorWriteGrants: [ConnectorWriteGrant!]!
 }
 
 extend type Mutation {
   startConnectorAuth(provider: String!, redirectURL: String!, connectors: [String!], requestWriteAccess: Boolean): StartConnectorAuthResult!
-  completeConnectorAuth(provider: String!, code: String!, redirectURL: String!, state: String): CompleteConnectorAuthResult!
+  completeConnectorAuth(provider: String!, code: String!, redirectURL: String!, state: String!): CompleteConnectorAuthResult!
   syncConnector(connector: String!, full: Boolean): SyncTriggerResult!
+  grantConnectorWriteCapability(connector: String!, tokens: [String!]!): Boolean!
+  revokeConnectorWriteCapability(connector: String!): Boolean!
+  disconnectProvider(provider: String!): Boolean!
 }
 
 extend type Subscription {
   connectorSyncEvents(connector: String): ConnectorSyncEvent!
 }
-`);let i=[];if(null!=r){let t=new Set;for(let e of r.getAll()){if(null==e.actions||0===e.actions.length)continue;let o=e.actions.some(t=>"create"===t.name),r=e.actions.some(t=>"update"===t.name);if(o||r)for(let s of n(e).filter(t=>"ExternalEntity"!==t))t.has(s)||(t.add(s),c.push(`
-type Connector${s}Payload {
+`);
+    // Dynamic per-model action types and mutations from registered connectors
+    const dynamicMutationLines = [];
+    if (registry != null) {
+        const payloadTypesDefined = new Set();
+        for (const connector of registry.getAll()){
+            if (connector.actions == null || connector.actions.length === 0) {
+                continue;
+            }
+            const hasCreate = connector.actions.some((a)=>a.name === 'create');
+            const hasUpdate = connector.actions.some((a)=>a.name === 'update');
+            if (!hasCreate && !hasUpdate) {
+                continue;
+            }
+            const modelNames = getConnectorModelNames(connector).filter((name)=>name !== 'ExternalEntity');
+            for (const modelName of modelNames){
+                // Define payload type once per model
+                if (!payloadTypesDefined.has(modelName)) {
+                    payloadTypesDefined.add(modelName);
+                    sdlParts.push(`
+type Connector${modelName}Payload {
   documentID: String
   entity: JSON
   error: ConnectorActionError
 }
-`)),o&&(c.push(`
-input ConnectorCreate${s}Input {
-  input: JSON!
+`);
+                }
+                if (hasCreate) {
+                    sdlParts.push(`
+input ConnectorCreate${modelName}Input {
+  data: JSON!
 }
-`),i.push(`  connectorCreate${s}(input: ConnectorCreate${s}Input!): Connector${s}Payload!`)),r&&(c.push(`
-input ConnectorUpdate${s}Input {
+`);
+                    dynamicMutationLines.push(`  connectorCreate${modelName}(input: ConnectorCreate${modelName}Input!): Connector${modelName}Payload!`);
+                }
+                if (hasUpdate) {
+                    sdlParts.push(`
+input ConnectorUpdate${modelName}Input {
   sourceID: String!
-  input: JSON!
+  data: JSON!
+}
+`);
+                    dynamicMutationLines.push(`  connectorUpdate${modelName}(input: ConnectorUpdate${modelName}Input!): Connector${modelName}Payload!`);
+                }
+            }
+        }
+    }
+    if (dynamicMutationLines.length > 0) {
+        sdlParts.push(`extend type Mutation {\n${dynamicMutationLines.join('\n')}\n}`);
+    }
+    const sdl = sdlParts.join('\n');
+    // ---- Build resolvers ----
+    const queryFields = {
+        connector: (_source, args, context)=>{
+            const ctx = context;
+            return requireConnector(ctx).getState(args.name);
+        },
+        connectors: (_source, _args, context)=>{
+            const ctx = context;
+            return requireConnector(ctx).getStates();
+        },
+        connectorWriteGrants: (_source, _args, context)=>{
+            const ctx = context;
+            const conn = requireConnector(ctx);
+            if (conn.connectorWriteGrants == null) {
+                throw new Error('connector.connectorWriteGrants is not available in this context');
+            }
+            return conn.connectorWriteGrants();
+        }
+    };
+    const mutationFields = {
+        startConnectorAuth: (_source, args, context)=>{
+            const ctx = context;
+            return requireConnector(ctx).startAuth(args);
+        },
+        completeConnectorAuth: (_source, args, context)=>{
+            const ctx = context;
+            return requireConnector(ctx).completeAuth(args);
+        },
+        syncConnector: (_source, args, context)=>{
+            const ctx = context;
+            return requireConnector(ctx).triggerSync(args);
+        },
+        grantConnectorWriteCapability: (_source, args, context)=>{
+            const ctx = context;
+            const conn = requireConnector(ctx);
+            if (conn.grantWriteCapability == null) {
+                throw new Error('connector.grantWriteCapability is not available in this context');
+            }
+            return conn.grantWriteCapability(args);
+        },
+        revokeConnectorWriteCapability: (_source, args, context)=>{
+            const ctx = context;
+            const conn = requireConnector(ctx);
+            if (conn.revokeConnectorWriteCapability == null) {
+                throw new Error('connector.revokeConnectorWriteCapability is not available in this context');
+            }
+            return conn.revokeConnectorWriteCapability(args);
+        },
+        disconnectProvider: (_source, args, context)=>{
+            const ctx = context;
+            const conn = requireConnector(ctx);
+            if (conn.disconnectProvider == null) {
+                throw new Error('connector.disconnectProvider is not available in this context');
+            }
+            return conn.disconnectProvider(args);
+        }
+    };
+    // Dynamic per-model action resolvers
+    if (registry != null) {
+        for (const connector of registry.getAll()){
+            if (connector.actions == null || connector.actions.length === 0) {
+                continue;
+            }
+            const hasCreate = connector.actions.some((a)=>a.name === 'create');
+            const hasUpdate = connector.actions.some((a)=>a.name === 'update');
+            if (!hasCreate && !hasUpdate) {
+                continue;
+            }
+            const modelNames = getConnectorModelNames(connector).filter((name)=>name !== 'ExternalEntity');
+            for (const modelName of modelNames){
+                if (hasCreate) {
+                    const connectorName = connector.name;
+                    mutationFields[`connectorCreate${modelName}`] = async (_source, args, context, info)=>{
+                        const ctx = context;
+                        const conn = requireConnector(ctx);
+                        if (conn.executeAction == null) {
+                            throw new Error('connector.executeAction is not available in this context');
+                        }
+                        const input = args.input;
+                        const writeDocument = ({ owner, modelID, unique, data })=>ctx.executeSetMutation({
+                                modelID,
+                                unique,
+                                data,
+                                owner,
+                                info
+                            }).then(()=>undefined);
+                        return await conn.executeAction({
+                            connector: connectorName,
+                            action: 'create',
+                            model: modelName,
+                            input: input.data
+                        }, writeDocument);
+                    };
+                }
+                if (hasUpdate) {
+                    const connectorName = connector.name;
+                    mutationFields[`connectorUpdate${modelName}`] = async (_source, args, context, info)=>{
+                        const ctx = context;
+                        const conn = requireConnector(ctx);
+                        if (conn.executeAction == null) {
+                            throw new Error('connector.executeAction is not available in this context');
+                        }
+                        const input = args.input;
+                        const writeDocument = ({ owner, modelID, unique, data })=>ctx.executeSetMutation({
+                                modelID,
+                                unique,
+                                data,
+                                owner,
+                                info
+                            }).then(()=>undefined);
+                        return await conn.executeAction({
+                            connector: connectorName,
+                            action: 'update',
+                            model: modelName,
+                            input: input.data,
+                            sourceID: input.sourceID
+                        }, writeDocument);
+                    };
+                }
+            }
+        }
+    }
+    const subscriptionFields = {
+        connectorSyncEvents: {
+            resolve: (event)=>event,
+            subscribe: (_source, args, context)=>{
+                const ctx = context;
+                return requireConnector(ctx).subscribeToSyncEvents(args.connector);
+            }
+        }
+    };
+    return {
+        sdl,
+        resolvers: {
+            queryFields,
+            mutationFields,
+            subscriptionFields,
+            typeFields: {
+                Connector: {
+                    id: (source)=>{
+                        const state = source;
+                        return PluginNodeID.create('connector', 'Connector', state.name).toString();
+                    }
+                }
+            },
+            nodeResolvers: {
+                Connector: {
+                    resolve: (localID, context)=>{
+                        const ctx = context;
+                        return requireConnector(ctx).getState(localID);
+                    }
+                }
+            }
+        }
+    };
 }
-`),i.push(`  connectorUpdate${s}(input: ConnectorUpdate${s}Input!): Connector${s}Payload!`))}}i.length>0&&c.push(`extend type Mutation {
-${i.join("\n")}
-}`);let s=c.join("\n"),l={startConnectorAuth:(t,n,o)=>e(o).startAuth(n),completeConnectorAuth:(t,n,o)=>e(o).completeAuth(n),syncConnector:(t,n,o)=>e(o).triggerSync(n)};if(null!=r)for(let t of r.getAll()){if(null==t.actions||0===t.actions.length)continue;let o=t.actions.some(t=>"create"===t.name),r=t.actions.some(t=>"update"===t.name);if(o||r)for(let c of n(t).filter(t=>"ExternalEntity"!==t)){if(o){let n=t.name;l[`connectorCreate${c}`]=async(t,o,r)=>{let i=e(r);if(null==i.executeAction)throw Error("connector.executeAction is not available in this context");let s=o.input;return await i.executeAction({connector:n,action:"create",model:c,input:s.input})}}if(r){let n=t.name;l[`connectorUpdate${c}`]=async(t,o,r)=>{let i=e(r);if(null==i.executeAction)throw Error("connector.executeAction is not available in this context");let s=o.input;return await i.executeAction({connector:n,action:"update",model:c,input:s.input,sourceID:s.sourceID})}}}}return{sdl:s,resolvers:{queryFields:{connector:(t,n,o)=>e(o).getState(n.name),connectors:(t,n,o)=>e(o).getStates()},mutationFields:l,subscriptionFields:{connectorSyncEvents:{resolve:t=>t,subscribe:(t,n,o)=>e(o).subscribeToSyncEvents(n.connector)}},typeFields:{Connector:{id:e=>t.create("connector","Connector",e.name).toString()}},nodeResolvers:{Connector:{resolve:(t,n)=>e(n).getState(t)}}}}}

package/lib/sync/engine.d.ts

@@ -1,11 +1,16 @@
 import type { DataProvider, 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';
 export type SyncEngineParams = {
     stores: StoreProvider;
     stateStore: SyncStateStore;
     connectorName: string;
     clusters: ClustersRecord;
+    logger: Logger;
+    /** Engine-signed write helper routing imports through the mutation pipeline. */
+    mutateDocuments?: MutateDocuments;
 };
 export type RunSyncParams = {
     provider: DataProvider;
@@ -13,6 +18,7 @@ export type RunSyncParams = {
     boundary: SyncBoundary;
     full?: boolean;
     signal?: AbortSignal;
+    leaseMs: number;
 };
 export declare class SyncEngine {
     #private;

package/lib/sync/engine.js

@@ -1 +1,163 @@
-import{EventEmitter as t}from"@enkaku/event";import{EntityProcessor as e}from"./processor.js";export class SyncEngine{#t;#e;#n;#s;#o;#c=new Map;#r=new t;constructor(t){for(let e of(this.#t=t.stores,this.#e=t.stateStore,this.#n=t.connectorName,this.#s=t.clusters,this.#o=new Map,Object.values(t.clusters)))for(let[t,n]of Object.entries(e.record))this.#o.set(t,e.models[n])}on(t,e){return this.#r.on(t,e)}#i(t,n){let s=this.#c.get(t);if(null!=s)return s;let o=this.#o.get(t);if(null==o)throw Error(`Unknown model ID "${t}" in connector "${this.#n}"`);let c=new e({stores:this.#t,modelID:t,ownerDID:n,connectorName:this.#n,edgeFields:o.fieldsMeta,clusters:this.#s});return this.#c.set(t,c),c}async run(t){let{provider:e,ownerDID:n,boundary:s,full:o,signal:c}=t,r=Date.now(),i=await this.#e.get(this.#n,n),a=!o&&i?.checkpoint!=null,l=a?"incremental":"initial";await this.#e.set(this.#n,n,{checkpoint:i?.checkpoint??null,lastSyncedAt:i?.lastSyncedAt??new Date().toISOString(),entityCount:i?.entityCount??0,status:"syncing"});let h=0,y=0,m=0,u=i?.checkpoint??null;try{let t={boundary:s,checkpoint:a?i?.checkpoint:void 0,signal:c};for await(let s of a?e.fetchChanges({...t,lastSyncedAt:i?.lastSyncedAt?new Date(i.lastSyncedAt):void 0}):e.fetchAll(t)){m++;let t=this.#i(s.modelID,n),e=await t.processBatch(s);h+=e.created+e.updated+e.deleted,y+=e.failed,null!=s.checkpoint&&(u=s.checkpoint);let o={type:"sync:progress",connectorName:this.#n,phase:l,entitiesProcessed:h,entitiesFailed:y,currentBatch:m,checkpoint:u};await this.#r.emit("sync",o),await this.#e.set(this.#n,n,{checkpoint:u,lastSyncedAt:new Date().toISOString(),entityCount:(i?.entityCount??0)+h,status:"syncing"})}let o=Date.now()-r;await this.#e.set(this.#n,n,{checkpoint:u,lastSyncedAt:new Date().toISOString(),entityCount:(i?.entityCount??0)+h,status:"idle"});let d={type:"sync:complete",connectorName:this.#n,totalProcessed:h,totalFailed:y,duration:o};await this.#r.emit("sync",d)}catch(s){let t=s instanceof Error?s.message:String(s);await this.#e.set(this.#n,n,{checkpoint:u,lastSyncedAt:i?.lastSyncedAt??new Date().toISOString(),entityCount:i?.entityCount??0,status:"error",error:t});let e={type:"sync:error",connectorName:this.#n,error:t};await this.#r.emit("sync",e)}}}
+import { EventEmitter } from '@sozai/event';
+import { EntityProcessor, MAX_LOGGED_ERRORS } from './processor.js';
+export class SyncEngine {
+    #stores;
+    #stateStore;
+    #connectorName;
+    #clusters;
+    #logger;
+    #mutateDocuments;
+    #modelByID;
+    #processors = new Map();
+    #events = new EventEmitter();
+    constructor(params){
+        this.#stores = params.stores;
+        this.#stateStore = params.stateStore;
+        this.#connectorName = params.connectorName;
+        this.#clusters = params.clusters;
+        this.#logger = params.logger;
+        this.#mutateDocuments = params.mutateDocuments;
+        // Merge all cluster records into a single model lookup
+        this.#modelByID = new Map();
+        for (const cluster of Object.values(params.clusters)){
+            for (const [id, index] of Object.entries(cluster.record)){
+                this.#modelByID.set(id, cluster.models[index]);
+            }
+        }
+    }
+    on(event, callback) {
+        return this.#events.on(event, callback);
+    }
+    #getProcessor(modelID, ownerDID) {
+        const existing = this.#processors.get(modelID);
+        if (existing != null) return existing;
+        const model = this.#modelByID.get(modelID);
+        if (model == null) {
+            throw new Error(`Unknown model ID "${modelID}" in connector "${this.#connectorName}"`);
+        }
+        const mutateDocuments = this.#mutateDocuments;
+        if (mutateDocuments == null) {
+            throw new Error(`Connector "${this.#connectorName}" sync requires a signed-write helper to import documents`);
+        }
+        const processor = new EntityProcessor({
+            stores: this.#stores,
+            modelID,
+            ownerDID,
+            connectorName: this.#connectorName,
+            logger: this.#logger,
+            edgeFields: model.fieldsMeta,
+            clusters: this.#clusters,
+            writeDocument: (write)=>mutateDocuments({
+                    owner: write.owner,
+                    writes: [
+                        {
+                            type: 'set',
+                            modelID: write.modelID,
+                            unique: write.unique,
+                            data: write.data
+                        }
+                    ]
+                }).then(()=>undefined)
+        });
+        this.#processors.set(modelID, processor);
+        return processor;
+    }
+    async run(params) {
+        const { provider, ownerDID, boundary, full, signal, leaseMs } = params;
+        const startTime = Date.now();
+        const existingState = await this.#stateStore.get(this.#connectorName, ownerDID);
+        const isIncremental = !full && existingState?.checkpoint != null;
+        const phase = isIncremental ? 'incremental' : 'initial';
+        // Mark as syncing
+        await this.#stateStore.set(this.#connectorName, ownerDID, {
+            checkpoint: existingState?.checkpoint ?? null,
+            lastSyncedAt: existingState?.lastSyncedAt ?? new Date().toISOString(),
+            entityCount: existingState?.entityCount ?? 0,
+            status: 'syncing'
+        });
+        let totalProcessed = 0;
+        let totalFailed = 0;
+        let batchNumber = 0;
+        let latestCheckpoint = existingState?.checkpoint ?? null;
+        const failedSample = [];
+        try {
+            const fetchParams = {
+                boundary,
+                checkpoint: isIncremental ? existingState?.checkpoint : undefined,
+                signal
+            };
+            const iterable = isIncremental ? provider.fetchChanges({
+                ...fetchParams,
+                lastSyncedAt: existingState?.lastSyncedAt ? new Date(existingState.lastSyncedAt) : undefined
+            }) : provider.fetchAll(fetchParams);
+            for await (const batch of iterable){
+                batchNumber++;
+                const processor = this.#getProcessor(batch.modelID, ownerDID);
+                const result = await processor.processBatch(batch);
+                totalProcessed += result.created + result.updated + result.deleted;
+                totalFailed += result.failed;
+                for (const error of result.errors){
+                    if (failedSample.length >= MAX_LOGGED_ERRORS) break;
+                    failedSample.push(error);
+                }
+                if (batch.checkpoint != null) {
+                    latestCheckpoint = batch.checkpoint;
+                }
+                const progressEvent = {
+                    type: 'sync:progress',
+                    connectorName: this.#connectorName,
+                    phase,
+                    entitiesProcessed: totalProcessed,
+                    entitiesFailed: totalFailed,
+                    currentBatch: batchNumber,
+                    checkpoint: latestCheckpoint
+                };
+                await this.#events.emit('sync', progressEvent);
+                await this.#stateStore.set(this.#connectorName, ownerDID, {
+                    checkpoint: latestCheckpoint,
+                    lastSyncedAt: new Date().toISOString(),
+                    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, {
+                checkpoint: latestCheckpoint,
+                lastSyncedAt: new Date().toISOString(),
+                entityCount: (existingState?.entityCount ?? 0) + totalProcessed,
+                status: 'idle'
+            });
+            const completeEvent = {
+                type: 'sync:complete',
+                connectorName: this.#connectorName,
+                totalProcessed,
+                totalFailed,
+                duration,
+                ...failedSample.length > 0 ? {
+                    failedSample
+                } : {}
+            };
+            await this.#events.emit('sync', completeEvent);
+        } catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            await this.#stateStore.set(this.#connectorName, ownerDID, {
+                checkpoint: latestCheckpoint,
+                lastSyncedAt: existingState?.lastSyncedAt ?? new Date().toISOString(),
+                entityCount: existingState?.entityCount ?? 0,
+                status: 'error',
+                error: errorMessage
+            });
+            const errorEvent = {
+                type: 'sync:error',
+                connectorName: this.#connectorName,
+                error: errorMessage,
+                ...failedSample.length > 0 ? {
+                    failedSample
+                } : {}
+            };
+            await this.#events.emit('sync', errorEvent);
+        }
+    }
+}

package/lib/sync/orchestrate.d.ts

@@ -1,6 +1,8 @@
 import type { ConnectorSyncEventPayload, 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 { MutateDocuments } from './processor.js';
 /**
  * Minimal interface for the sync event emitter dependency.
  * ConnectorManager (not yet ported) satisfies this — when it is ported,
@@ -19,6 +21,10 @@ 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;
 };
 export type OrchestrateSyncResult = {
     status: 'started' | 'already_syncing' | 'error';

package/lib/sync/orchestrate.js

@@ -1 +1,100 @@
-import{SyncEngine as e}from"./engine.js";export async function orchestrateSync(t){let{connectorName:r,full:n,registry:s,syncEventEmitter:a,stateStore:i,credentialProvider:o,ownerDID:c,stores:l}=t,u=s.get(r);if(null==u)return{status:"error"};let y=await i.get(r,c);if(y?.status==="syncing")return{status:"already_syncing"};let d="device"!==u.auth.provider?u.auth.provider:null,p=d?await o.get(d,c):null;if(null!=d&&null==p||null==u.serverProvider)return{status:"error"};let v=t.boundary??{maxAge:"P90D"},g=u.serverProvider({credential:p??{accessToken:"",scopes:[]},boundary:v}),m=new e({stores:l,stateStore:i,connectorName:r,clusters:u.clusters});return await a.emitSyncEvent({type:"started",connectorName:r}),m.on("sync",e=>{"sync:progress"===e.type?a.emitSyncEvent({type:"progress",connectorName:r,entitiesProcessed:e.entitiesProcessed,entitiesFailed:e.entitiesFailed}):"sync:complete"===e.type?a.emitSyncEvent({type:"completed",connectorName:r,totalProcessed:e.totalProcessed,totalFailed:e.totalFailed,duration:e.duration}):"sync:error"===e.type&&a.emitSyncEvent({type:"error",connectorName:r,error:e.error})}),m.run({provider:g,ownerDID:c,boundary:v,full:n}).catch(async e=>{await a.emitSyncEvent({type:"error",connectorName:r,error:e instanceof Error?e.message:String(e)})}),{status:"started"}}
+import { SyncEngine } from './engine.js';
+export async function orchestrateSync(params) {
+    const { connectorName, full, registry, syncEventEmitter, stateStore, credentialProvider, ownerDID, stores, leaseMs, logger } = params;
+    const connector = registry.get(connectorName);
+    if (connector == null) {
+        return {
+            status: 'error'
+        };
+    }
+    // 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) {
+        return {
+            status: 'error'
+        };
+    }
+    // Ensure server provider is available
+    if (connector.serverProvider == null) {
+        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'
+    };
+    const provider = connector.serverProvider({
+        credential: credential ?? {
+            accessToken: '',
+            scopes: []
+        },
+        boundary: effectiveBoundary
+    });
+    const engine = new SyncEngine({
+        stores,
+        stateStore,
+        connectorName,
+        clusters: connector.clusters,
+        logger,
+        mutateDocuments: params.mutateDocuments
+    });
+    // Emit started event
+    await syncEventEmitter.emitSyncEvent({
+        type: 'started',
+        connectorName
+    });
+    // Bridge engine events to sync event emitter
+    engine.on('sync', (event)=>{
+        if (event.type === 'sync:progress') {
+            syncEventEmitter.emitSyncEvent({
+                type: 'progress',
+                connectorName,
+                entitiesProcessed: event.entitiesProcessed,
+                entitiesFailed: event.entitiesFailed
+            });
+        } else if (event.type === 'sync:complete') {
+            syncEventEmitter.emitSyncEvent({
+                type: 'completed',
+                connectorName,
+                totalProcessed: event.totalProcessed,
+                totalFailed: event.totalFailed,
+                duration: event.duration,
+                failedSample: event.failedSample
+            });
+        } else if (event.type === 'sync:error') {
+            syncEventEmitter.emitSyncEvent({
+                type: 'error',
+                connectorName,
+                error: event.error,
+                failedSample: event.failedSample
+            });
+        }
+    });
+    // Run sync (fire-and-forget — mutation returns immediately)
+    engine.run({
+        provider,
+        ownerDID,
+        boundary: effectiveBoundary,
+        full,
+        leaseMs
+    }).catch(async (err)=>{
+        await syncEventEmitter.emitSyncEvent({
+            type: 'error',
+            connectorName,
+            error: err instanceof Error ? err.message : String(err)
+        });
+    });
+    return {
+        status: 'started'
+    };
+}