@kubun/plugin-connector 0.14.1 → 0.14.3

package/lib/index.js

@@ -1,14 +1,17 @@
-import { isSigningIdentity } from '@kokuin/token';
+import { isSigningIdentity, normalizeDID } 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, createCredentialAPI } from './api.js';
-import { DBCredentialProvider } from './credential.js';
+import { connectorAuthRequiredPayload } from './auth-required.js';
+import { DBCredentialProvider, RefreshingCredentialProvider } from './credential.js';
+import { bridgeCredentialRefreshEvents } from './credential-refresh-bridge.js';
 import { ConnectorManager } from './manager.js';
 import { OAuthService } from './oauth.js';
+import { periodicSyncSubject } from './periodic-sync.js';
 import { ConnectorRegistry } from './registry.js';
-import { createConnectorSchemaExtension, subscribeToConnectorSyncEvents } from './schema.js';
+import { createConnectorSchemaExtension, subscribeToConnectorLifecycleEvents, 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';
@@ -25,7 +28,7 @@ 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 };
+export { DBCredentialProvider, RefreshingCredentialProvider,  };
 // 5m after a productive run; idle 15m→6h, error 1m→1h, offline 30s→15m.
 const DEFAULT_PERIODIC_SYNC_POLICY = {
     changed: 300000,
@@ -42,14 +45,26 @@ const DEFAULT_PERIODIC_SYNC_POLICY = {
         max: 900000
     }
 };
+// The engine's own registry has no typed "no such plugin" error — an
+// unregistered `getAPI(name)` throws a plain `Error` with this exact message
+// (packages/engine/src/registry.ts). A message match is the only signal
+// available, so it stays narrow (exact equality, not a substring), and a
+// tripwire test elsewhere pins the engine's message so a future rename fails
+// loudly here instead of silently re-masking real init failures as absence.
+function isWorkflowPluginAbsent(err) {
+    return err instanceof Error && err.message === 'API not registered: workflow';
+}
 // 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.
+// provider for get/set/delete/peek, its credential API for provenance. Service
+// mode gets provenance as one more procedure, so both modes read it off one
+// object. The refreshing provider's `peek` is forwarded so a disconnect can test
+// existence without triggering a refresh.
 function withProvenance(provider, api) {
     return {
         get: (providerName, ownerDID)=>provider.get(providerName, ownerDID),
         set: (setParams)=>provider.set(setParams),
         delete: (providerName, ownerDID)=>provider.delete(providerName, ownerDID),
+        peek: (providerName, ownerDID)=>provider.peek(providerName, ownerDID),
         getCredentialProvenance: (providerName, ownerDID)=>api.getCredentialProvenance(providerName, ownerDID)
     };
 }
@@ -62,18 +77,37 @@ function displayStatusFor(status) {
     if (status === 'failed') return 'ERROR';
     return 'IDLE';
 }
-async function resolveConnectorState({ connectorAPI, registry, credentialProvider, getWorkflowAPI, viewerDID, connectorName }) {
+async function resolveConnectorState({ connectorAPI, registry, credentialProvider, getWorkflowAPI, viewerDID: rawViewerDID, connectorName }) {
     const connector = registry.get(connectorName);
     if (connector == null) {
         throw new Error(`Connector "${connectorName}" not found`);
     }
+    // Credential and sync-state rows are keyed on the normalized owner (a viewer
+    // can arrive long-form); the workflow status is keyed on the same subject as
+    // the schedule. Fold once so all three reads hit the right rows.
+    const viewerDID = normalizeDID(rawViewerDID);
     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();
+    // A status read degrades to the syncState-only fallback below on a broken
+    // workflow plugin rather than failing outright — `getStates` fans this out
+    // over every registered connector with `Promise.all`, so one broken plugin
+    // would otherwise blank the whole list. `getWorkflowAPI` already logs the
+    // failure; this stays silent to avoid re-logging on every poll. The one
+    // signal kept is `workflowStatusError`: a genuine init failure (a caught
+    // rejection) sets it so a consumer can tell degraded-because-broken from
+    // degraded-because-absent (a resolved `undefined`, expected in local-only
+    // apps), which leaves it null.
+    let workflowStatusError = null;
+    let workflowAPI;
+    try {
+        workflowAPI = await getWorkflowAPI();
+    } catch  {
+        workflowStatusError = 'WORKFLOW_UNAVAILABLE';
+    }
     if (workflowAPI != null) {
         const instance = await workflowAPI.getCurrentInstance(CONNECTOR_SYNC_WORKFLOW, `${connectorName}:${viewerDID}`);
         if (instance != null) {
@@ -114,7 +148,8 @@ async function resolveConnectorState({ connectorAPI, registry, credentialProvide
             credentialWriterDID,
             lastSyncedAt: null,
             entityCount: null,
-            error: null
+            error: null,
+            workflowStatusError
         };
     }
     return {
@@ -127,7 +162,8 @@ async function resolveConnectorState({ connectorAPI, registry, credentialProvide
         credentialWriterDID,
         lastSyncedAt: syncState.lastSyncedAt ?? null,
         entityCount: syncState.entityCount ?? null,
-        error: syncState.error ?? null
+        error: syncState.error ?? null,
+        workflowStatusError
     };
 }
 // ---- Plugin factory ----
@@ -209,6 +245,12 @@ export function createConnectorPlugin(options) {
         // 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;
+        // Shared single-flight map for the standalone refresh decorator, one per plugin
+        // instance. The cached background stack and each per-request stack build their
+        // own decorator, but they all refresh the same stored credentials; sharing this
+        // map collapses the concurrent sync runs' refreshes of one credential to a
+        // single token exchange and a single emitted outcome.
+        const refreshInFlight = new Map();
         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.
@@ -220,13 +262,32 @@ export function createConnectorPlugin(options) {
                 serverWrappableDID,
                 getControllerMethods
             });
+            // The DB provider is storage-only; the decorator adds transparent
+            // refresh-on-read over it, writing a refreshed token back through the same
+            // storage provider so it joins the request's transaction.
+            const provider = new RefreshingCredentialProvider({
+                inner: new DBCredentialProvider({
+                    api
+                }),
+                runtime: params.runtime,
+                providers,
+                refreshInFlight
+            });
+            // Surface this decorator's refresh outcomes as connector lifecycle events.
+            // Each stack builds its own decorator with its own emitter, so the bridge
+            // is attached per construction; a per-request instance is short-lived, the
+            // background instance is cached. Deferring the emit through this stack's own
+            // `stores.onCommit` keeps a per-request refresh's lifecycle listener out of
+            // the mutation transaction that owns the single DB connection.
+            bridgeCredentialRefreshEvents({
+                source: provider.refreshEvents,
+                manager,
+                registry,
+                defer: (fn)=>stores.onCommit(fn)
+            });
             const stack = {
                 api,
-                provider: new DBCredentialProvider({
-                    api,
-                    runtime: params.runtime,
-                    providers
-                })
+                provider
             };
             if (stores === params.db) standaloneStack = stack;
             return stack;
@@ -237,6 +298,8 @@ export function createConnectorPlugin(options) {
         const resolveCredentialSurface = async (stores)=>{
             const serviceProvider = await credentialServiceProviderPromise;
             if (serviceProvider != null) {
+                // The remote service provider has no `peek`; a consumer falls back to
+                // its (non-local-refreshing) `get`.
                 return {
                     provider: serviceProvider
                 };
@@ -270,6 +333,15 @@ export function createConnectorPlugin(options) {
             logger,
             defaults: options.defaults
         });
+        // Emit `connector:authRequired` for a genuinely absent credential. The deep
+        // sync sites (workflow, orchestrate, action) only know `{ provider, ownerDID }`;
+        // the connector mapping, owner normalization and `reason: 'absent'` are folded
+        // in here. Timing is the caller's: the workflow and orchestrate sites emit
+        // directly (matching their sibling sync events); the action site defers via
+        // `stores.onCommit` because it runs inside the request's mutation transaction.
+        const emitAuthRequiredNow = (provider, ownerDID)=>{
+            manager.emitLifecycle('connector:authRequired', connectorAuthRequiredPayload(registry, provider, ownerDID));
+        };
         const oauthService = new OAuthService({
             runtime: params.runtime,
             providers,
@@ -288,7 +360,8 @@ export function createConnectorPlugin(options) {
             stores: params.db,
             mutateDocuments: params.graph.mutateDocuments,
             boundary: options.defaults?.boundary,
-            logger
+            logger,
+            emitAuthRequired: ({ provider, ownerDID })=>emitAuthRequiredNow(provider, ownerDID)
         });
         let workflowAPIPromise;
         const getWorkflowAPI = ()=>{
@@ -299,20 +372,198 @@ export function createConnectorPlugin(options) {
                     });
                     api.register(connectorSyncWorkflow.definition);
                     return api;
-                }).catch(()=>undefined);
+                }).catch((err)=>{
+                    if (isWorkflowPluginAbsent(err)) return undefined;
+                    // A present-but-broken plugin, not a genuinely absent one: don't
+                    // cache this rejection as a permanent no-op — reset so a later
+                    // call rebuilds the API instead of replaying a wedged failure
+                    // (or a transient one that has since cleared).
+                    workflowAPIPromise = undefined;
+                    logger.warn('workflow API resolution failed {error}', {
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                    throw err;
+                });
             }
             return workflowAPIPromise;
         };
+        // Register the connector-sync workflow eagerly at startup rather than on the
+        // first sync/schedule call. `getAPI` resolves only after the engine closes its
+        // plugin gate (every plugin's API registered), so this settles regardless of
+        // plugin order — and before any GraphQL request. Without it, a generic
+        // `periodicSync` query/mutation arriving first after a restart would see the
+        // workflow unregistered and bypass its managed-schedule protection.
+        void getWorkflowAPI().catch(()=>undefined);
+        // Owner-bound periodic-sync control. The public (viewer) path and the
+        // auto-enable-on-auth subscriber both route here so the schedule is keyed on
+        // the credential owner's normalized DID — matching the manual-sync singleton
+        // so scheduled and manual runs interlock. The emit is direct (not deferred):
+        // the sibling workflow call is already direct here, and the emit touches no
+        // store.
+        const enablePeriodicSyncForOwner = async (connector, ownerDID, policyOverride, scheduleOpts)=>{
+            if (!registry.has(connector)) {
+                throw new Error(`unknown connector: ${connector}`);
+            }
+            const workflowAPI = await getWorkflowAPI();
+            if (workflowAPI == null) {
+                throw new Error('workflow plugin required for periodic sync');
+            }
+            const { owner, subjectKey } = periodicSyncSubject(connector, ownerDID);
+            const policy = policyOverride ?? options.defaults?.periodicSyncPolicy ?? DEFAULT_PERIODIC_SYNC_POLICY;
+            const { id } = await workflowAPI.scheduleAdaptive(CONNECTOR_SYNC_WORKFLOW, {
+                connectorName: connector,
+                ownerDID: owner,
+                full: false
+            }, {
+                policy,
+                subjectKey,
+                reactivate: scheduleOpts?.reactivate
+            });
+            const result = await workflowAPI.getPeriodicSync(id);
+            // `reactivate: false` preserves a user-disabled row, so only announce
+            // `enabled` when the schedule actually is — a re-auth of a paused connector
+            // must not emit a state change that did not happen.
+            if (result?.enabled) {
+                manager.emitLifecycle('periodicSync:enabled', {
+                    connector,
+                    ownerDID: owner,
+                    subjectKey
+                });
+            }
+            return result;
+        };
+        const disablePeriodicSyncForOwner = async (connector, ownerDID)=>{
+            if (!registry.has(connector)) {
+                throw new Error(`unknown connector: ${connector}`);
+            }
+            const workflowAPI = await getWorkflowAPI();
+            if (workflowAPI == null) {
+                throw new Error('workflow plugin required for periodic sync');
+            }
+            const { owner, subjectKey } = periodicSyncSubject(connector, ownerDID);
+            const result = await workflowAPI.setPeriodicSyncEnabled(`${CONNECTOR_SYNC_WORKFLOW}:${subjectKey}`, false);
+            // A null result means no such schedule existed — nothing changed, so no
+            // `disabled` event.
+            if (result != null) {
+                manager.emitLifecycle('periodicSync:disabled', {
+                    connector,
+                    ownerDID: owner,
+                    subjectKey
+                });
+            }
+            return result;
+        };
+        // Arm-if-absent recovery for one owner: for every connector this owner holds
+        // a credential for, create a periodic schedule when none exists yet. An
+        // existing schedule — enabled or user-disabled — is left untouched, so this
+        // is safe to run repeatedly and never rewrites a live schedule's `next_run`
+        // or re-announces an already-enabled one. It is the shared body of both the
+        // auth-event subscriber and the boot sweep: arming the just-authenticated
+        // connectors and retrying any earlier arm that failed transiently for the
+        // same owner. Failures are isolated per connector and never propagate.
+        const reconcileOwnerNow = async (ownerDID)=>{
+            const workflowAPI = await getWorkflowAPI();
+            if (workflowAPI == null) return;
+            for (const connector of registry.getAll()){
+                if (connector.auth.provider === 'device') continue;
+                try {
+                    const credential = await backgroundCredentialProvider.get(connector.auth.provider, ownerDID);
+                    if (credential == null) continue;
+                    const { subjectKey } = periodicSyncSubject(connector.name, ownerDID);
+                    const existing = await workflowAPI.getPeriodicSync(`${CONNECTOR_SYNC_WORKFLOW}:${subjectKey}`);
+                    if (existing != null) continue;
+                    await enablePeriodicSyncForOwner(connector.name, ownerDID, undefined, {
+                        reactivate: false
+                    });
+                } catch (err) {
+                    logger.debug('auto-arm reconcile skipped {connector} {ownerDID}', {
+                        connector: connector.name,
+                        ownerDID,
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                }
+            }
+        };
+        // Serialize reconciles per owner. The arm-if-absent check (getPeriodicSync)
+        // and the arm are two steps, so two reconciles of the same owner running
+        // concurrently — the boot sweep racing an auth event, or two auth events in
+        // quick succession — could both read a subject as absent and both arm it. The
+        // atomic upsert stops that becoming a PK error, but the loser would still
+        // rewrite `next_run` and emit a second `periodicSync:enabled`, breaking the
+        // no-touch guarantee above. Chaining per normalized owner makes the later run
+        // observe the schedule the earlier one created, so it skips.
+        const reconcileChains = new Map();
+        const reconcileOwner = (ownerDID)=>{
+            const key = normalizeDID(ownerDID);
+            const prev = reconcileChains.get(key) ?? Promise.resolve();
+            const next = prev.catch(()=>{}).then(()=>reconcileOwnerNow(ownerDID));
+            reconcileChains.set(key, next);
+            void next.finally(()=>{
+                // Only the tail clears the entry; a newer chained run keeps it alive.
+                if (reconcileChains.get(key) === next) reconcileChains.delete(key);
+            });
+            return next;
+        };
+        // Opt-in: reconcile the authenticated owner on every `connector:authenticated`.
+        // Subscribed on `lifecycleEvents` (the merged, tagged channel), not the
+        // per-event `events` channel forwarded to external plugin consumers as
+        // `connectorPluginAPI.events` — this subscriber is the connector plugin's own
+        // internal wiring, not a consumer of its public surface, so it stays decoupled
+        // from whatever external listeners do with `events`. Reconciling the whole
+        // owner (not just `event.connectors`) means a connector whose arm failed at an
+        // earlier auth is recovered the next time the owner authenticates anything.
+        // Fire-and-forget and best-effort: any failure is caught inside
+        // `reconcileOwner` rather than thrown into the emitter's listener.
+        if (options.autoEnablePeriodicSync) {
+            manager.lifecycleEvents.on('lifecycle', (event)=>{
+                if (event.type !== 'connector:authenticated') return;
+                reconcileOwner(event.ownerDID).catch((err)=>{
+                    logger.debug('auto-arm reconcile (on auth) failed {ownerDID}', {
+                        ownerDID: event.ownerDID,
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                });
+            });
+            // Boot sweep (standalone only): on init, re-arm any owner authenticated in a
+            // previous run whose schedule is missing — the restart/mount recovery for a
+            // transient arm failure that no later auth would otherwise reach. It runs
+            // once, off the request path, so it is fire-and-forget and must not block or
+            // fail init. Service mode has no local credential store to enumerate and its
+            // remote backend owns its own reconcile, so the sweep is skipped there; the
+            // auth-event path above still recovers in both modes.
+            void (async ()=>{
+                const serviceProvider = await credentialServiceProviderPromise;
+                if (serviceProvider != null) return;
+                const { api } = getStandaloneStack(params.db);
+                const providers = new Set(registry.getAll().map((connector)=>connector.auth.provider).filter((provider)=>provider !== 'device'));
+                const owners = new Set();
+                for (const provider of providers){
+                    for (const owner of (await api.listSubjects(provider)))owners.add(owner);
+                }
+                for (const owner of owners)await reconcileOwner(owner);
+            })().catch((err)=>{
+                logger.debug('auto-arm boot sweep failed {error}', {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            });
+        }
         // Process-local dedup for the no-workflow-plugin fallback path only (the
         // workflow singleton guards the primary path).
         const orchestrateInFlight = new Set();
+        // The exposed API: storage surface plus a listen-only view of the live
+        // manager's event channel. Consumers subscribe through `events`; the emit
+        // side stays with the manager, which internal producers hold directly.
+        const connectorPluginAPI = {
+            ...connectorAPI,
+            events: manager.events
+        };
         return {
             name: 'connector',
             schemaExtension: (config)=>createConnectorSchemaExtension({
                     registry,
                     config: config
                 }),
-            api: connectorAPI,
+            api: connectorPluginAPI,
             createContextFactory: ()=>{
                 return (ctx, stores)=>{
                     // Per-request connector API backed by the request's StoreProvider
@@ -332,7 +583,10 @@ export function createConnectorPlugin(options) {
                     };
                     // 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.
+                    // mode resolves lazily behind it. `peek` uses the surface's
+                    // non-refreshing read when available, falling back to `get` (service
+                    // mode has no local peek), so a disconnect's existence check never
+                    // triggers a standalone refresh.
                     const requestProvider = {
                         get: async (providerName, ownerDID)=>(await getSurface()).provider.get(providerName, ownerDID),
                         set: async (setParams)=>{
@@ -341,6 +595,10 @@ export function createConnectorPlugin(options) {
                         delete: async (providerName, ownerDID)=>{
                             await (await getSurface()).provider.delete(providerName, ownerDID);
                         },
+                        peek: async (providerName, ownerDID)=>{
+                            const { provider } = await getSurface();
+                            return provider.peek != null ? provider.peek(providerName, ownerDID) : provider.get(providerName, ownerDID);
+                        },
                         getCredentialProvenance: async (providerName, ownerDID)=>(await getSurface()).provider.getCredentialProvenance(providerName, ownerDID)
                     };
                     return {
@@ -368,7 +626,27 @@ export function createConnectorPlugin(options) {
                         // `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),
+                        completeAuth: async (args)=>{
+                            const { output, ownerDID } = await oauthService.completeAuth(args, requestProvider, requestAPI);
+                            // Announce the authorization to lifecycle consumers (e.g. auto-enable),
+                            // carrying the provider's connectors and the owner in its normalized
+                            // (short) form — the same folding the credential row is keyed on.
+                            const connectors = registry.getAll().filter((connector)=>connector.auth.provider === output.providerName).map((connector)=>connector.name);
+                            const normalizedOwnerDID = normalizeDID(ownerDID);
+                            // After the mutation commits, never inside it: a subscriber that
+                            // schedules a sync writes through the top-level db, which would
+                            // deadlock the single-connection tx still held here (as triggerSync
+                            // defers its enqueue below for the same reason).
+                            stores.onCommit(()=>{
+                                manager.emitLifecycle('connector:authenticated', {
+                                    provider: output.providerName,
+                                    connectors,
+                                    ownerDID: normalizedOwnerDID,
+                                    scopes: output.scopes
+                                });
+                            });
+                            return output;
+                        },
                         triggerSync: async (args)=>{
                             if (!registry.has(args.connector)) {
                                 return {
@@ -377,7 +655,10 @@ export function createConnectorPlugin(options) {
                                 };
                             }
                             const connectorName = args.connector;
-                            const ownerDID = ctx.viewerDID;
+                            // Fold the owner to its short form so the singleton subject matches
+                            // the periodic schedule's, and the workflow reads the credential and
+                            // sync-state rows keyed on the normalized owner.
+                            const ownerDID = normalizeDID(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
@@ -408,22 +689,18 @@ export function createConnectorPlugin(options) {
                                         boundary: options.defaults?.boundary,
                                         inFlight: orchestrateInFlight,
                                         logger,
-                                        mutateDocuments: params.graph.mutateDocuments
+                                        mutateDocuments: params.graph.mutateDocuments,
+                                        emitAuthRequired: ({ provider, ownerDID: owner })=>emitAuthRequiredNow(provider, owner)
                                     });
                                 })().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.
+                                    // The emit is failure-isolated (a throwing subscriber is logged
+                                    // by the emitter), so it needs no guard of its own.
                                     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)
-                                        });
                                     });
                                 });
                             });
@@ -433,43 +710,30 @@ 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
+                        // Viewer-scoped façade over the manager's INTERNAL merged lifecycle
+                        // channel: the viewer captured here (folded to its short form, as
+                        // every lifecycle payload's owner is) gates delivery, so one viewer
+                        // never observes another's auth activity.
+                        subscribeToLifecycleEvents: (connector)=>subscribeToConnectorLifecycleEvents(manager.lifecycleEvents, {
+                                viewerDID: normalizeDID(ctx.viewerDID),
+                                connector
+                            }),
+                        // Recurring-sync control. The schedule binds to the viewer as the
+                        // credential owner; its subject is `${connector}:${normalizeDID(owner)}`
+                        // — 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);
-                        },
+                        enablePeriodicSync: (connector, policyOverride)=>enablePeriodicSyncForOwner(connector, ctx.viewerDID, policyOverride),
+                        disablePeriodicSync: (connector)=>disablePeriodicSyncForOwner(connector, ctx.viewerDID),
                         getPeriodicSync: async (connector)=>{
+                            if (!registry.has(connector)) {
+                                throw new Error(`unknown connector: ${connector}`);
+                            }
                             const workflowAPI = await getWorkflowAPI();
                             if (workflowAPI == null) {
                                 throw new Error('workflow plugin required for periodic sync');
                             }
-                            const subjectKey = `${connector}:${ctx.viewerDID}`;
+                            const { subjectKey } = periodicSyncSubject(connector, ctx.viewerDID);
                             return workflowAPI.getPeriodicSync(`${CONNECTOR_SYNC_WORKFLOW}:${subjectKey}`);
                         },
                         executeAction: async (args, writeDocument)=>{
@@ -488,10 +752,18 @@ export function createConnectorPlugin(options) {
                                     stores,
                                     registry,
                                     credentialProvider: requestProvider,
-                                    ownerDID: ctx.viewerDID,
+                                    // The credential row is keyed on the normalized owner.
+                                    ownerDID: normalizeDID(ctx.viewerDID),
                                     logger,
                                     writeDocument,
-                                    writeAttachment
+                                    writeAttachment,
+                                    // The action runs inside the request's mutation transaction;
+                                    // defer the emit past commit so a subscriber that schedules a
+                                    // sync does not deadlock the single-connection tx still held
+                                    // here (same guard as completeAuth and onCredentialRemoved).
+                                    emitAuthRequired: ({ provider, ownerDID })=>{
+                                        stores.onCommit(()=>emitAuthRequiredNow(provider, ownerDID));
+                                    }
                                 });
                                 return {
                                     documentID: result.documentID,
@@ -520,7 +792,23 @@ export function createConnectorPlugin(options) {
                             viewerDID: ctx.viewerDID,
                             stores,
                             credentialProvider: requestProvider,
-                            hlc: params.hlc
+                            hlc: params.hlc,
+                            // Announce a removed credential to lifecycle consumers, carrying the
+                            // provider's connectors and the owner in normalized (short) form.
+                            // After the mutation commits, never inside it: a subscriber that
+                            // schedules work writes through the top-level db, which would
+                            // deadlock the single-connection tx still held here (same guard as
+                            // completeAuth).
+                            onCredentialRemoved: ({ provider, ownerDID })=>{
+                                const connectors = registry.getAll().filter((connector)=>connector.auth.provider === provider).map((connector)=>connector.name);
+                                stores.onCommit(()=>{
+                                    manager.emitLifecycle('connector:deauthenticated', {
+                                        provider,
+                                        connectors,
+                                        ownerDID: normalizeDID(ownerDID)
+                                    });
+                                });
+                            }
                         })
                     };
                 };