@kubun/plugin-connector 0.13.1 → 0.14.1

package/lib/index.js

@@ -3,7 +3,7 @@ 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 { createConnectorAPI, createCredentialAPI } from './api.js';
 import { DBCredentialProvider } from './credential.js';
 import { ConnectorManager } from './manager.js';
 import { OAuthService } from './oauth.js';
@@ -26,13 +26,60 @@ 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 };
+// 5m after a productive run; idle 15m→6h, error 1m→1h, offline 30s→15m.
+const DEFAULT_PERIODIC_SYNC_POLICY = {
+    changed: 300000,
+    idle: {
+        base: 900000,
+        max: 21600000
+    },
+    error: {
+        base: 60000,
+        max: 3600000
+    },
+    offline: {
+        base: 30000,
+        max: 900000
+    }
+};
+// Present the standalone local stack as the unified surface: the credential
+// provider for get/set/delete, its credential API for provenance. Service mode
+// gets provenance as one more procedure, so both modes read it off one object.
+function withProvenance(provider, api) {
+    return {
+        get: (providerName, ownerDID)=>provider.get(providerName, ownerDID),
+        set: (setParams)=>provider.set(setParams),
+        delete: (providerName, ownerDID)=>provider.delete(providerName, ownerDID),
+        getCredentialProvenance: (providerName, ownerDID)=>api.getCredentialProvenance(providerName, ownerDID)
+    };
+}
 // ---- Connector state resolution ----
-async function resolveConnectorState(connectorAPI, registry, credentialProvider, viewerDID, connectorName) {
+// Map a workflow instance status to the connector display status. A run in
+// progress reads SYNCING, a failed terminal ERROR; every other terminal
+// (completed/cancelled) is IDLE.
+function displayStatusFor(status) {
+    if (status === 'pending' || status === 'running') return 'SYNCING';
+    if (status === 'failed') return 'ERROR';
+    return 'IDLE';
+}
+async function resolveConnectorState({ connectorAPI, registry, credentialProvider, getWorkflowAPI, viewerDID, connectorName }) {
     const connector = registry.get(connectorName);
     if (connector == null) {
         throw new Error(`Connector "${connectorName}" not found`);
     }
     const syncState = await connectorAPI.getSyncState(connectorName, viewerDID);
+    // The durable, lease-fenced truth: the workflow instance status. Preferred over
+    // the hand-written syncState.status row, which a zombie handler can transiently
+    // regress after crash-recovery. Falls back to that row only with no workflow
+    // plugin (local-only sync) or no instance yet.
+    let workflowStatus = null;
+    const workflowAPI = await getWorkflowAPI();
+    if (workflowAPI != null) {
+        const instance = await workflowAPI.getCurrentInstance(CONNECTOR_SYNC_WORKFLOW, `${connectorName}:${viewerDID}`);
+        if (instance != null) {
+            workflowStatus = displayStatusFor(instance.status);
+        }
+    }
     let authenticated = false;
     let hasWriteAccess = false;
     let authExpiresAt = null;
@@ -42,7 +89,7 @@ async function resolveConnectorState(connectorAPI, registry, credentialProvider,
         const credential = await credentialProvider.get(connector.auth.provider, viewerDID);
         if (credential != null) {
             authenticated = true;
-            const provenance = await connectorAPI.getCredentialProvenance(connector.auth.provider, viewerDID);
+            const provenance = await credentialProvider.getCredentialProvenance(connector.auth.provider, viewerDID);
             credentialUpdatedAt = provenance?.updatedAt ?? null;
             credentialWriterDID = provenance?.writerDID ?? null;
             if (credential.expiresAt != null) {
@@ -59,7 +106,7 @@ async function resolveConnectorState(connectorAPI, registry, credentialProvider,
     if (syncState == null) {
         return {
             name: connectorName,
-            status: 'IDLE',
+            status: workflowStatus ?? 'IDLE',
             authenticated,
             hasWriteAccess,
             authExpiresAt,
@@ -72,7 +119,7 @@ async function resolveConnectorState(connectorAPI, registry, credentialProvider,
     }
     return {
         name: connectorName,
-        status: syncState.status === 'idle' ? 'IDLE' : syncState.status === 'syncing' ? 'SYNCING' : 'ERROR',
+        status: workflowStatus ?? (syncState.status === 'idle' ? 'IDLE' : syncState.status === 'syncing' ? 'SYNCING' : 'ERROR'),
         authenticated,
         hasWriteAccess,
         authExpiresAt,
@@ -123,39 +170,98 @@ export function createConnectorPlugin(options) {
         // 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;
-        }
+        // content key should have. Parameterised by the signing identity and HLC so a
+        // manager over an external credential graph stamps with that graph's writer,
+        // not the engine's.
+        const credentialManagerFor = (mgrIdentity, mgrHLC)=>{
+            const managers = new WeakMap();
+            return (stores)=>{
+                let manager = managers.get(stores);
+                if (manager == null) {
+                    manager = getCredentialStore(stores).then((store)=>createCredentialManager({
+                            store,
+                            identity: mgrIdentity,
+                            runtime: params.runtime,
+                            hlc: mgrHLC
+                        }));
+                    managers.set(stores, manager);
+                }
+                return manager;
+            };
+        };
+        // The engine-scoped builder: still the manager for the engine's own request
+        // transaction on the no-backend path.
+        const getCredentialManager = credentialManagerFor(identity, params.hlc);
         // 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.
+        // resolved provider so a resolve reads that provider's controller store
+        // rather than a second connection.
         const getControllerMethods = (stores)=>[
                 params.controllerResolverFor(stores)
             ];
+        // Mode is decided by provider presence, resolved once. A registered
+        // `credential-provider` (service mode) routes every credential op through the
+        // remote credential service; its absence (standalone) builds the local stack
+        // over the engine's own db, exactly as before. The registry gate closes after
+        // construction, so this promise settles lazily — memoized by capture.
+        const credentialServiceProviderPromise = params.engine.getProvider('credential-provider');
+        // The standalone credential stack over the engine's own db, built lazily and
+        // once — only ever touched when no service provider is registered. `stores`
+        // defaults to params.db for the background (workflow/orchestrate) paths, which
+        // run outside any request transaction. A request path passes its own tx.
+        let standaloneStack;
+        const getStandaloneStack = (stores = params.db)=>{
+            // The background stack is cached on params.db; a per-request tx builds a
+            // fresh stack so its reads and writes join that transaction.
+            if (stores === params.db && standaloneStack != null) return standaloneStack;
+            const api = createCredentialAPI({
+                stores,
+                logger,
+                getCredentialManager,
+                serverWrappableDID,
+                getControllerMethods
+            });
+            const stack = {
+                api,
+                provider: new DBCredentialProvider({
+                    api,
+                    runtime: params.runtime,
+                    providers
+                })
+            };
+            if (stores === params.db) standaloneStack = stack;
+            return stack;
+        };
+        // Resolve the unified credential surface for a given store provider. Service
+        // mode reuses the registry provider as-is (plugin-scoped, not the request tx);
+        // standalone wraps the local stack, exposing provenance off its credential API.
+        const resolveCredentialSurface = async (stores)=>{
+            const serviceProvider = await credentialServiceProviderPromise;
+            if (serviceProvider != null) {
+                return {
+                    provider: serviceProvider
+                };
+            }
+            const { api, provider } = getStandaloneStack(stores);
+            return {
+                provider: withProvenance(provider, api)
+            };
+        };
         const connectorAPI = createConnectorAPI({
             stores: params.db,
-            logger,
-            getCredentialManager,
-            serverWrappableDID,
-            getControllerMethods
-        });
-        const credentialProvider = new DBCredentialProvider({
-            api: connectorAPI,
-            runtime: params.runtime,
-            providers
+            logger
         });
+        // The plugin-scope credential surface for the background paths (workflow,
+        // fallback orchestrate, OAuth callback fallback). It switches on mode per call
+        // so a service provider registered after construction is still honoured.
+        const backgroundCredentialProvider = {
+            get: async (providerName, ownerDID)=>(await resolveCredentialSurface(params.db)).provider.get(providerName, ownerDID),
+            set: async (setParams)=>{
+                await (await resolveCredentialSurface(params.db)).provider.set(setParams);
+            },
+            delete: async (providerName, ownerDID)=>{
+                await (await resolveCredentialSurface(params.db)).provider.delete(providerName, ownerDID);
+            }
+        };
         const stateStore = new DBSyncStateStore({
             api: connectorAPI
         });
@@ -168,7 +274,7 @@ export function createConnectorPlugin(options) {
             runtime: params.runtime,
             providers,
             registry,
-            credentialProvider,
+            credentialProvider: backgroundCredentialProvider,
             connectorAPI
         });
         // The primary sync path: enqueue a durable `connector-sync` workflow whose
@@ -176,7 +282,7 @@ export function createConnectorPlugin(options) {
         // registered lazily the first time the workflow API resolves.
         const connectorSyncWorkflow = createConnectorSyncWorkflow({
             registry,
-            credentialProvider,
+            credentialProvider: backgroundCredentialProvider,
             stateStore,
             syncEventEmitter: manager,
             stores: params.db,
@@ -209,28 +315,60 @@ export function createConnectorPlugin(options) {
             api: connectorAPI,
             createContextFactory: ()=>{
                 return (ctx, stores)=>{
-                    // Per-request connector API and credential provider backed by the
-                    // request's StoreProvider (transactional during mutations).
+                    // Per-request connector API backed by the request's StoreProvider
+                    // (transactional during mutations). Sync-state stays Space-local, so
+                    // this always rebuilds over the request tx.
                     const requestAPI = createConnectorAPI({
                         stores,
-                        logger,
-                        getCredentialManager,
-                        serverWrappableDID,
-                        getControllerMethods
-                    });
-                    const requestCredentialProvider = new DBCredentialProvider({
-                        api: requestAPI,
-                        runtime: params.runtime,
-                        providers
+                        logger
                     });
+                    // Resolve the request's credential surface once. Service mode reuses the
+                    // registry provider (not the request tx); standalone rebuilds the local
+                    // stack over the request's transactional provider.
+                    let surfacePromise;
+                    const getSurface = ()=>{
+                        if (surfacePromise == null) surfacePromise = resolveCredentialSurface(stores);
+                        return surfacePromise;
+                    };
+                    // A base provider that defers to the resolved surface, so synchronous
+                    // consumers (write-grants, executeAction) get one object while the
+                    // mode resolves lazily behind it.
+                    const requestProvider = {
+                        get: async (providerName, ownerDID)=>(await getSurface()).provider.get(providerName, ownerDID),
+                        set: async (setParams)=>{
+                            await (await getSurface()).provider.set(setParams);
+                        },
+                        delete: async (providerName, ownerDID)=>{
+                            await (await getSurface()).provider.delete(providerName, ownerDID);
+                        },
+                        getCredentialProvenance: async (providerName, ownerDID)=>(await getSurface()).provider.getCredentialProvenance(providerName, ownerDID)
+                    };
                     return {
-                        getState: (name)=>resolveConnectorState(requestAPI, registry, requestCredentialProvider, ctx.viewerDID, name),
+                        getState: (name)=>resolveConnectorState({
+                                connectorAPI: requestAPI,
+                                registry,
+                                credentialProvider: requestProvider,
+                                getWorkflowAPI,
+                                viewerDID: ctx.viewerDID,
+                                connectorName: name
+                            }),
                         getStates: ()=>{
                             const names = registry.list();
-                            return Promise.all(names.map((name)=>resolveConnectorState(requestAPI, registry, requestCredentialProvider, ctx.viewerDID, name)));
+                            return Promise.all(names.map((name)=>resolveConnectorState({
+                                    connectorAPI: requestAPI,
+                                    registry,
+                                    credentialProvider: requestProvider,
+                                    getWorkflowAPI,
+                                    viewerDID: ctx.viewerDID,
+                                    connectorName: name
+                                })));
                         },
-                        startAuth: (args)=>oauthService.startAuth(args, ctx.viewerDID, requestAPI),
-                        completeAuth: (args)=>oauthService.completeAuth(args, requestCredentialProvider, requestAPI),
+                        // The owner pre-flight resolves against the engine's OWN controller
+                        // methods, bound to the request tx (`stores`), in both modes. Using
+                        // `params.db` here would open a second connection inside the
+                        // startConnectorAuth mutation tx and deadlock single-connection SQLite.
+                        startAuth: async (args)=>oauthService.startAuth(args, ctx.viewerDID, requestAPI, getControllerMethods(stores)),
+                        completeAuth: (args)=>oauthService.completeAuth(args, requestProvider, requestAPI),
                         triggerSync: async (args)=>{
                             if (!registry.has(args.connector)) {
                                 return {
@@ -264,7 +402,7 @@ export function createConnectorPlugin(options) {
                                         registry,
                                         syncEventEmitter: manager,
                                         stateStore,
-                                        credentialProvider,
+                                        credentialProvider: backgroundCredentialProvider,
                                         ownerDID,
                                         stores: params.db,
                                         boundary: options.defaults?.boundary,
@@ -272,7 +410,22 @@ export function createConnectorPlugin(options) {
                                         logger,
                                         mutateDocuments: params.graph.mutateDocuments
                                     });
-                                })().catch(()=>{});
+                                })().catch((err)=>{
+                                    // Surface a deferred-run failure instead of swallowing it — the
+                                    // workflow enqueue and the fallback orchestrate both settle here.
+                                    // The emission itself rejects if a subscriber throws, so guard it:
+                                    // an unhandled rejection here could crash a strict host.
+                                    manager.emitSyncEvent({
+                                        type: 'error',
+                                        connectorName,
+                                        error: err instanceof Error ? err.message : String(err)
+                                    }).catch((emitErr)=>{
+                                        logger.warn('connector sync error event delivery failed {connectorName}', {
+                                            connectorName,
+                                            error: emitErr instanceof Error ? emitErr.message : String(emitErr)
+                                        });
+                                    });
+                                });
                             });
                             return {
                                 status: 'STARTED',
@@ -280,6 +433,45 @@ export function createConnectorPlugin(options) {
                             };
                         },
                         subscribeToSyncEvents: (connector)=>subscribeToConnectorSyncEvents(manager.syncEvents, connector),
+                        // Recurring-sync control. Viewer-at-enable: the schedule is registered
+                        // under a viewer and its subject is `${connector}:${ownerDID}` —
+                        // identical to the manual sync singletonKey, so scheduled and manual
+                        // runs interlock. Scheduled fires later write with no viewer, via the
+                        // engine-signed mutateDocuments path the workflow already uses.
+                        enablePeriodicSync: async (connector, policyOverride)=>{
+                            const workflowAPI = await getWorkflowAPI();
+                            if (workflowAPI == null) {
+                                throw new Error('workflow plugin required for periodic sync');
+                            }
+                            const ownerDID = ctx.viewerDID;
+                            const subjectKey = `${connector}:${ownerDID}`;
+                            const policy = policyOverride ?? options.defaults?.periodicSyncPolicy ?? DEFAULT_PERIODIC_SYNC_POLICY;
+                            const { id } = await workflowAPI.scheduleAdaptive(CONNECTOR_SYNC_WORKFLOW, {
+                                connectorName: connector,
+                                ownerDID,
+                                full: false
+                            }, {
+                                policy,
+                                subjectKey
+                            });
+                            return workflowAPI.getPeriodicSync(id);
+                        },
+                        disablePeriodicSync: async (connector)=>{
+                            const workflowAPI = await getWorkflowAPI();
+                            if (workflowAPI == null) {
+                                throw new Error('workflow plugin required for periodic sync');
+                            }
+                            const subjectKey = `${connector}:${ctx.viewerDID}`;
+                            return workflowAPI.setPeriodicSyncEnabled(`${CONNECTOR_SYNC_WORKFLOW}:${subjectKey}`, false);
+                        },
+                        getPeriodicSync: async (connector)=>{
+                            const workflowAPI = await getWorkflowAPI();
+                            if (workflowAPI == null) {
+                                throw new Error('workflow plugin required for periodic sync');
+                            }
+                            const subjectKey = `${connector}:${ctx.viewerDID}`;
+                            return workflowAPI.getPeriodicSync(`${CONNECTOR_SYNC_WORKFLOW}:${subjectKey}`);
+                        },
                         executeAction: async (args, writeDocument)=>{
                             try {
                                 // Bind the blob write to THIS request's transactional provider so
@@ -295,7 +487,7 @@ export function createConnectorPlugin(options) {
                                 }, {
                                     stores,
                                     registry,
-                                    credentialProvider: requestCredentialProvider,
+                                    credentialProvider: requestProvider,
                                     ownerDID: ctx.viewerDID,
                                     logger,
                                     writeDocument,
@@ -327,7 +519,7 @@ export function createConnectorPlugin(options) {
                             serverDID,
                             viewerDID: ctx.viewerDID,
                             stores,
-                            credentialProvider: requestCredentialProvider,
+                            credentialProvider: requestProvider,
                             hlc: params.hlc
                         })
                     };

package/lib/oauth.d.ts

@@ -1,6 +1,7 @@
-import type { CredentialProvider, OAuthProviderDefinition } from '@kubun/connector';
+import type { MethodRegistry } from '@kokuin/token';
+import type { CredentialProvider, OAuthProviderDefinition } from '@kubun/credential-types';
 import type { Runtime } from '@sozai/runtime';
-import type { ConnectorAPI } from './api.js';
+import type { ConnectorAPI, CredentialAPI } from './api.js';
 import type { ConnectorRegistry } from './registry.js';
 import type { CompleteConnectorAuthInput, CompleteConnectorAuthOutput, StartConnectorAuthInput, StartConnectorAuthOutput } from './schema.js';
 export type OAuthServiceParams = {
@@ -9,10 +10,11 @@ export type OAuthServiceParams = {
     registry: ConnectorRegistry;
     credentialProvider: CredentialProvider;
     connectorAPI: ConnectorAPI;
+    credentialAPI?: CredentialAPI;
 };
 export declare class OAuthService {
     #private;
     constructor(params: OAuthServiceParams);
-    startAuth(args: StartConnectorAuthInput, ownerDID: string, connectorAPI?: ConnectorAPI): Promise<StartConnectorAuthOutput>;
+    startAuth(args: StartConnectorAuthInput, ownerDID: string, connectorAPI?: ConnectorAPI, preflightMethods?: MethodRegistry): Promise<StartConnectorAuthOutput>;
     completeAuth(args: CompleteConnectorAuthInput, credentialProvider?: CredentialProvider, connectorAPI?: ConnectorAPI): Promise<CompleteConnectorAuthOutput>;
 }

package/lib/oauth.js

@@ -14,14 +14,18 @@ export class OAuthService {
     #providers;
     #registry;
     #connectorAPI;
+    #preflightMethods;
     constructor(params){
         this.#credentialProvider = params.credentialProvider;
         this.#runtime = params.runtime;
         this.#providers = params.providers;
         this.#registry = params.registry;
         this.#connectorAPI = params.connectorAPI;
+        this.#preflightMethods = params.credentialAPI?.getControllerMethods();
     }
-    async startAuth(args, ownerDID, connectorAPI) {
+    async startAuth(args, ownerDID, connectorAPI, // The controller methods the owner pre-flight resolves against; `undefined`
+    // falls back to the constructor-captured methods (the direct unit tests).
+    preflightMethods) {
         // Prefer the request-scoped API so the pending-auth write joins the mutation
         // transaction; the base API would deadlock a single-connection SQLite tx.
         const api = connectorAPI ?? this.#connectorAPI;
@@ -45,7 +49,8 @@ export class OAuthService {
         // `did:kokuin:` owner's agreement key resolves only through the controller
         // resolver, and asking without it would fail closed and block a flow the
         // mint would have completed.
-        if (!await canWrapTo(ownerWrappableDID, api.getControllerMethods())) {
+        const methods = preflightMethods ?? this.#preflightMethods;
+        if (methods != null && !await canWrapTo(ownerWrappableDID, methods)) {
             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

package/lib/schema.d.ts

@@ -1,5 +1,6 @@
 import type { ConnectorSyncEventPayload } from '@kubun/connector';
 import type { SchemaExtension } from '@kubun/engine';
+import type { AdaptivePolicy } from '@kubun/plugin-workflow-api';
 import type { EventEmitter } from '@sozai/event';
 import type { ConnectorRegistry } from './registry.js';
 import type { SignedDocumentWriter } from './sync/processor.js';
@@ -164,6 +165,9 @@ export type ConnectorQueryContext = {
         provider: string;
     }) => Promise<boolean>;
     connectorWriteGrants?: () => Promise<Array<ConnectorWriteGrant>>;
+    enablePeriodicSync?: (connector: string, policyOverride?: AdaptivePolicy) => Promise<unknown>;
+    disablePeriodicSync?: (connector: string) => Promise<unknown | null>;
+    getPeriodicSync?: (connector: string) => Promise<unknown | null>;
 };
 declare module '@kubun/graphql' {
     interface PluginContextMap {
@@ -172,6 +176,7 @@ declare module '@kubun/graphql' {
 }
 export type ConnectorExtensionConfig = {
     connectors?: Array<string>;
+    periodicSync?: boolean;
 };
 export declare function createConnectorSchemaExtension(params: {
     registry?: ConnectorRegistry;

package/lib/schema.js

@@ -177,6 +177,22 @@ extend type Subscription {
   connectorSyncEvents(connector: String): ConnectorSyncEvent!
 }
 `);
+    // Recurring-sync control. Gated because it references `PeriodicSync`, which is
+    // defined by the co-deployed workflow plugin — referencing it on a connector-only
+    // graph would fail schema build with an unknown type.
+    const periodicSyncEnabled = params.config.periodicSync === true;
+    if (periodicSyncEnabled) {
+        sdlParts.push(`
+extend type Query {
+  connectorPeriodicSync(connector: String!): PeriodicSync
+}
+
+extend type Mutation {
+  enableConnectorPeriodicSync(connector: String!, policy: JSON): PeriodicSync!
+  disableConnectorPeriodicSync(connector: String!): PeriodicSync
+}
+`);
+    }
     // Dynamic per-model action types and mutations from registered connectors
     const dynamicMutationLines = [];
     if (registry != null) {
@@ -284,6 +300,32 @@ input ConnectorUpdate${modelName}Input {
             return conn.disconnectProvider(args);
         }
     };
+    // Resolvers for the gated recurring-sync fields. Attached only when the SDL
+    // above declared them, since the resolver-attach step rejects a resolver with
+    // no matching field. The ownerDID is the viewer, captured by the context factory.
+    if (periodicSyncEnabled) {
+        queryFields.connectorPeriodicSync = (_source, args, context)=>{
+            const conn = requireConnector(context);
+            if (conn.getPeriodicSync == null) {
+                throw new Error('connector.getPeriodicSync is not available in this context');
+            }
+            return conn.getPeriodicSync(args.connector);
+        };
+        mutationFields.enableConnectorPeriodicSync = (_source, args, context)=>{
+            const conn = requireConnector(context);
+            if (conn.enablePeriodicSync == null) {
+                throw new Error('connector.enablePeriodicSync is not available in this context');
+            }
+            return conn.enablePeriodicSync(args.connector, args.policy);
+        };
+        mutationFields.disableConnectorPeriodicSync = (_source, args, context)=>{
+            const conn = requireConnector(context);
+            if (conn.disablePeriodicSync == null) {
+                throw new Error('connector.disablePeriodicSync is not available in this context');
+            }
+            return conn.disablePeriodicSync(args.connector);
+        };
+    }
     // Dynamic per-model action resolvers
     if (registry != null) {
         for (const connector of registry.getAll()){
@@ -360,6 +402,17 @@ input ConnectorUpdate${modelName}Input {
     };
     return {
         sdl,
+        // These write to the workflow store, not the graph, and must return the
+        // resulting projection synchronously. Running them inside `mutateGraph`'s
+        // write transaction would hold the shared single-connection DB across the
+        // workflow-store write and deadlock (as `syncConnector` defers its enqueue to
+        // `onCommit` for the same reason).
+        ...periodicSyncEnabled ? {
+            nonTransactionalMutationFields: [
+                'enableConnectorPeriodicSync',
+                'disableConnectorPeriodicSync'
+            ]
+        } : {},
         resolvers: {
             queryFields,
             mutationFields,

package/lib/sync/orchestrate.d.ts

@@ -1,4 +1,5 @@
-import type { ConnectorSyncEventPayload, CredentialProvider, SyncBoundary, SyncStateStore } from '@kubun/connector';
+import type { ConnectorSyncEventPayload, SyncBoundary, SyncStateStore } from '@kubun/connector';
+import type { CredentialProvider } from '@kubun/credential-types';
 import type { StoreProvider } from '@kubun/db';
 import type { Logger } from '@kubun/logger';
 import type { ConnectorRegistry } from '../registry.js';