@endora-commerce/platform 0.100.0

package/dist/kernel/lifecycle/plugin-helpers.d.ts

@@ -0,0 +1,165 @@
+import type { FastifyInstance } from 'fastify';
+import { type Worker } from 'bullmq';
+import { HttpError } from '../../http/error-envelope.js';
+import type { ModulePlugin } from '../../http/server.js';
+import type { PlatformLogger } from '../logging.js';
+/**
+ * Thrown when service-to-service code calls into a disabled module's
+ * surface. Surfaces as `503 Service Unavailable` via the standard error
+ * envelope, with `Retry-After` so a well-behaved client backs off rather than
+ * treating the module as gone.
+ *
+ * **`details` names the module** (issue #161, `moduleDisabledDetailsSchema`).
+ * The id was on the error object from the start, and every caller that catches
+ * the throw could read it — but the envelope replaces an operator-visible
+ * message with the registered sentence for its *code*, and this one code covers
+ * every gated port in the platform, so the wire carried a generic "Module
+ * Disabled." An operator refused a refund because a payment gateway is switched
+ * off was not told which module to switch back on, which also undercut D-71's
+ * own rationale: the remedy was named on the object, not on the response.
+ * `details` is the part of the envelope that survives the replacement, and the
+ * sentence interpolates `{module}` out of it. `carts` had already written the
+ * same key by hand for its one contribution-point refusal
+ * (`src/modules/carts/backend.ts`); this makes the platform-wide throw agree.
+ */
+export declare class ModuleDisabledError extends HttpError {
+    readonly moduleId: string;
+    constructor(moduleId: string);
+}
+/**
+ * Let a module's presence answer through a `catch` that legitimately absorbs
+ * everything else (issue #84 — the deferred half of feature 072's D-43).
+ *
+ * `lazyPort` resolves inside the forwarded call, so a switched-off owner
+ * surfaces as {@link ModuleDisabledError} **at the call site**. A
+ * `try { … } catch { return null }` around one silently converts fail-closed
+ * into fail-open: the caller answers "no data" where the truthful answer is
+ * "this capability is off", and the operator reads a working screen that is
+ * lying to them.
+ *
+ * The first fix for that is to delete the `catch` — most of them exist only
+ * because somebody was being defensive, and where a degrade genuinely belongs
+ * it belongs **inside the owner's implementation**, expressed in the return
+ * type (`allowedIdsFor(): Promise<string[] | null>` is the worked example).
+ *
+ * This helper is for the remainder: a tolerance that is correct *as a
+ * tolerance* — a per-item import failure recorded as an issue rather than
+ * failing the run, a compensating cleanup on a rollback path, a notification
+ * that must not undo the write it announces. None of those wants to absorb the
+ * presence answer too, because that answer is about the whole operation rather
+ * than the one item, and the run that "completed with 4 000 failures" is a
+ * worse report than the one that stopped saying `catalog` is switched off.
+ *
+ * ```ts
+ * } catch (error) {
+ *   rethrowIfModuleDisabled(error);
+ *   state.countFailed();
+ * }
+ * ```
+ *
+ * It is deliberately greppable: `scripts/check-port-catches.ts` reads it as the
+ * one spelling that distinguishes a narrowed tolerance from a bare `catch`.
+ */
+export declare function rethrowIfModuleDisabled(error: unknown): void;
+/**
+ * Programmatic gate. Throw from anywhere outside an HTTP request when
+ * an absent module's logic should not run. Surfaces consistently as
+ * the same 503 envelope when reached from a route handler.
+ *
+ * "Absent" is the **effective** state — platform availability AND operator
+ * activation (Constitution XVII). A caller never learns there are two axes;
+ * it learns the module is not there.
+ */
+export declare function requireModuleEnabled(moduleId: string): void;
+/**
+ * Wrap a Fastify plugin so every route registered inside it is gated on
+ * the module's effective state. Absent module → 503 with
+ * `Retry-After: 60`; enabled module → handler runs normally.
+ *
+ * Use it at the top of every module's `routes.admin.ts` /
+ * `routes.storefront.ts`:
+ *
+ *   export const blogRoutes = defineModuleRoutes('blog', async (app) => {
+ *     app.get('/api/v1/admin/blog/posts', { preHandler: requireAdmin() }, h);
+ *   });
+ *
+ * Two HTTP-level effects:
+ *   1. The wrapper registers a child encapsulated context, so the
+ *      preHandler hook only fires for routes registered inside `register`.
+ *   2. The 503 response includes `Retry-After: 60` so well-behaved
+ *      clients back off until the next enable-check window. The header now
+ *      travels on {@link ModuleDisabledError} itself, so the same 503 from a
+ *      service call or a port resolution carries it too.
+ */
+export declare function defineModuleRoutes(moduleId: string, register: (app: FastifyInstance) => Promise<void> | void): ModulePlugin;
+export interface DefineModuleWorkerOptions {
+    /**
+     * When provided, the worker's lifecycle events (ready / active / completed /
+     * failed / stalled / error) are logged with this logger. This gives the
+     * `worker` / `worker:dev` processes a visible heartbeat so operators can tell
+     * a queue is actually consuming jobs (and see why one fails or stalls).
+     */
+    logger?: PlatformLogger;
+}
+/**
+ * The fetch gate — bring every registered worker into agreement with its
+ * module's effective state.
+ *
+ * Level-triggered and idempotent, so it is safe to run on every presence
+ * install: BullMQ's own `pause()` and `resume()` are no-ops when the worker is
+ * already there, and the comparison below keeps even those off the common path.
+ *
+ * This is what makes the repair work across processes. Every composed process —
+ * API, `BACKEND_ROLE=worker`, `all` — keeps its own {@link registryCache} fresh
+ * from the same `b2b:module:state-changed` channel (and from the degraded-mode
+ * timer when Redis is unavailable), so following the cache means the worker
+ * process reacts to a flip written anywhere, including by a CLI that composed
+ * nothing.
+ */
+export declare function reconcileModuleWorkers(): void;
+/**
+ * Register a BullMQ Worker as its module's, so both gates apply to it.
+ *
+ * Two things happen, and only the first was ever true: the worker joins the
+ * per-module registry {@link pauseWorkersFor} iterates, **and** its processor is
+ * wrapped in the work gate while the registry itself is reconciled against the
+ * cache on every presence install. The returned worker is the same instance.
+ *
+ * A worker constructed outside this seam is a worker nothing can stop —
+ * `check:worker-seam` is the ratchet for that, and `pwa`'s push consumer was
+ * the live instance when it landed.
+ */
+export declare function defineModuleWorker<W extends Worker>(moduleId: string, worker: W, options?: DefineModuleWorkerOptions): W;
+/**
+ * Pause a module's workers now, without waiting for the next presence install.
+ *
+ * An **optimisation**, since the fetch gate above: the orchestrator's disable
+ * path refreshes the cache and publishes the state change, which reconciles
+ * every process including this one. Calling it here simply makes the local
+ * process's answer immediate rather than one refresh away.
+ */
+export declare function pauseWorkersFor(moduleId: string): Promise<void>;
+/**
+ * Resume a module's workers now. The mirror of {@link pauseWorkersFor}, and an
+ * optimisation on the same terms — note that it resumes on the **platform**
+ * axis alone, which is safe only because the work gate re-asks for the
+ * conjunction on every job.
+ */
+export declare function resumeWorkersFor(moduleId: string): Promise<void>;
+/**
+ * Test seam — empty the per-process worker registry.
+ *
+ * The suite shares one process per fork, so a worker registered by an earlier
+ * test is still there for the reconcile the next one triggers. Production never
+ * calls it: workers leave the registry when they close.
+ */
+export declare function resetModuleWorkersForTesting(): void;
+/**
+ * Wrap an EventBus subscription so the handler is a no-op when the
+ * owning module is absent. Mirrors `EventBus.on(eventName, handler)`'s
+ * unsubscribe-returning shape.
+ */
+export declare function subscribeForModule<E, P>(moduleId: string, bus: {
+    on(event: E, handler: (payload: P) => void | Promise<void>): () => void;
+}, event: E, handler: (payload: P) => void | Promise<void>): () => void;
+//# sourceMappingURL=plugin-helpers.d.ts.map

package/dist/kernel/lifecycle/plugin-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-helpers.d.ts","sourceRoot":"","sources":["../../../src/kernel/lifecycle/plugin-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErD,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAYpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;aACpB,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAU7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAI3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACvD,YAAY,CAWd;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAsJD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAS7C;AA2DD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EACjD,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,yBAAyB,GAClC,CAAC,CAqBH;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIrE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAItE;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EACrC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE;IAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAA;CAAE,EAChF,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC5C,MAAM,IAAI,CAMZ"}

package/dist/kernel/lifecycle/plugin-helpers.js

@@ -0,0 +1,395 @@
+import { RateLimitError } from 'bullmq';
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '../../http/error-envelope.js';
+import { effectiveState } from './effective-state.js';
+import { FALLBACK_TTL_MS, registryCache } from './registry-cache.js';
+/**
+ * How long a client should wait before retrying a surface whose module is
+ * absent — one enable-check window. Carried by the error itself, so a route
+ * gate, a `requireModuleEnabled` call and a port resolution all answer the
+ * same thing (feature 072, T059).
+ */
+const RETRY_AFTER_SECONDS = '60';
+/**
+ * Thrown when service-to-service code calls into a disabled module's
+ * surface. Surfaces as `503 Service Unavailable` via the standard error
+ * envelope, with `Retry-After` so a well-behaved client backs off rather than
+ * treating the module as gone.
+ *
+ * **`details` names the module** (issue #161, `moduleDisabledDetailsSchema`).
+ * The id was on the error object from the start, and every caller that catches
+ * the throw could read it — but the envelope replaces an operator-visible
+ * message with the registered sentence for its *code*, and this one code covers
+ * every gated port in the platform, so the wire carried a generic "Module
+ * Disabled." An operator refused a refund because a payment gateway is switched
+ * off was not told which module to switch back on, which also undercut D-71's
+ * own rationale: the remedy was named on the object, not on the response.
+ * `details` is the part of the envelope that survives the replacement, and the
+ * sentence interpolates `{module}` out of it. `carts` had already written the
+ * same key by hand for its one contribution-point refusal
+ * (`src/modules/carts/backend.ts`); this makes the platform-wide throw agree.
+ */
+export class ModuleDisabledError extends HttpError {
+    moduleId;
+    constructor(moduleId) {
+        super(503, ERROR_CODES.MODULE_DISABLED, `Module '${moduleId}' is currently disabled.`, { module: moduleId }, { 'Retry-After': RETRY_AFTER_SECONDS });
+        this.moduleId = moduleId;
+        this.name = 'ModuleDisabledError';
+    }
+}
+/**
+ * Let a module's presence answer through a `catch` that legitimately absorbs
+ * everything else (issue #84 — the deferred half of feature 072's D-43).
+ *
+ * `lazyPort` resolves inside the forwarded call, so a switched-off owner
+ * surfaces as {@link ModuleDisabledError} **at the call site**. A
+ * `try { … } catch { return null }` around one silently converts fail-closed
+ * into fail-open: the caller answers "no data" where the truthful answer is
+ * "this capability is off", and the operator reads a working screen that is
+ * lying to them.
+ *
+ * The first fix for that is to delete the `catch` — most of them exist only
+ * because somebody was being defensive, and where a degrade genuinely belongs
+ * it belongs **inside the owner's implementation**, expressed in the return
+ * type (`allowedIdsFor(): Promise<string[] | null>` is the worked example).
+ *
+ * This helper is for the remainder: a tolerance that is correct *as a
+ * tolerance* — a per-item import failure recorded as an issue rather than
+ * failing the run, a compensating cleanup on a rollback path, a notification
+ * that must not undo the write it announces. None of those wants to absorb the
+ * presence answer too, because that answer is about the whole operation rather
+ * than the one item, and the run that "completed with 4 000 failures" is a
+ * worse report than the one that stopped saying `catalog` is switched off.
+ *
+ * ```ts
+ * } catch (error) {
+ *   rethrowIfModuleDisabled(error);
+ *   state.countFailed();
+ * }
+ * ```
+ *
+ * It is deliberately greppable: `scripts/check-port-catches.ts` reads it as the
+ * one spelling that distinguishes a narrowed tolerance from a bare `catch`.
+ */
+export function rethrowIfModuleDisabled(error) {
+    if (error instanceof ModuleDisabledError)
+        throw error;
+}
+/**
+ * Programmatic gate. Throw from anywhere outside an HTTP request when
+ * an absent module's logic should not run. Surfaces consistently as
+ * the same 503 envelope when reached from a route handler.
+ *
+ * "Absent" is the **effective** state — platform availability AND operator
+ * activation (Constitution XVII). A caller never learns there are two axes;
+ * it learns the module is not there.
+ */
+export function requireModuleEnabled(moduleId) {
+    if (!effectiveState.isPresent(moduleId)) {
+        throw new ModuleDisabledError(moduleId);
+    }
+}
+/**
+ * Wrap a Fastify plugin so every route registered inside it is gated on
+ * the module's effective state. Absent module → 503 with
+ * `Retry-After: 60`; enabled module → handler runs normally.
+ *
+ * Use it at the top of every module's `routes.admin.ts` /
+ * `routes.storefront.ts`:
+ *
+ *   export const blogRoutes = defineModuleRoutes('blog', async (app) => {
+ *     app.get('/api/v1/admin/blog/posts', { preHandler: requireAdmin() }, h);
+ *   });
+ *
+ * Two HTTP-level effects:
+ *   1. The wrapper registers a child encapsulated context, so the
+ *      preHandler hook only fires for routes registered inside `register`.
+ *   2. The 503 response includes `Retry-After: 60` so well-behaved
+ *      clients back off until the next enable-check window. The header now
+ *      travels on {@link ModuleDisabledError} itself, so the same 503 from a
+ *      service call or a port resolution carries it too.
+ */
+export function defineModuleRoutes(moduleId, register) {
+    return async (app) => {
+        await app.register(async (scoped) => {
+            scoped.addHook('onRequest', async () => {
+                if (!effectiveState.isPresent(moduleId)) {
+                    throw new ModuleDisabledError(moduleId);
+                }
+            });
+            await register(scoped);
+        });
+    };
+}
+/**
+ * Attach structured lifecycle logging to a BullMQ worker. Every queue consumer
+ * gets the same shape of log line — `{ module, queue, jobId, jobName, ... }` —
+ * so the `worker` process output reads consistently across modules.
+ */
+function attachWorkerLogging(moduleId, worker, logger) {
+    const queue = worker.name;
+    const base = { module: moduleId, queue };
+    logger.info(base, 'queue consumer registered');
+    worker.on('ready', () => {
+        logger.info(base, 'queue consumer ready (connected to Redis)');
+    });
+    worker.on('active', (job) => {
+        logger.info({ ...base, jobId: job.id, jobName: job.name, data: job.data }, 'queue job active');
+    });
+    worker.on('completed', (job) => {
+        const durationMs = job.finishedOn != null && job.processedOn != null
+            ? job.finishedOn - job.processedOn
+            : undefined;
+        logger.info({ ...base, jobId: job.id, jobName: job.name, durationMs }, 'queue job completed');
+    });
+    worker.on('failed', (job, err) => {
+        logger.error({
+            ...base,
+            jobId: job?.id,
+            jobName: job?.name,
+            data: job?.data,
+            attemptsMade: job?.attemptsMade,
+            err,
+        }, 'queue job failed');
+    });
+    worker.on('stalled', (jobId) => {
+        logger.warn({ ...base, jobId }, 'queue job stalled — moved back to wait list');
+    });
+    worker.on('error', (err) => {
+        logger.error({ ...base, err }, 'queue consumer error');
+    });
+}
+/**
+ * Every worker a module registered, in **this** process.
+ *
+ * Which is the whole reason the registry alone was never the gate: a push into
+ * it reaches the process that pushed and nothing else, and the two processes
+ * that flip presence are exactly the two that hold no workers — the API process
+ * serving `/api/v1/admin/modules/:id/activation`, and the `module:*` CLI, which
+ * composes nothing (D-157.2) and therefore registers nothing. See
+ * {@link reconcileModuleWorkers}.
+ */
+const moduleWorkers = new Map();
+/**
+ * How long a worker backs off after refusing a job for an absent module.
+ *
+ * One presence-refresh window — the degraded-mode cadence, which is the longest
+ * a process's answer can be behind the database when the notification channel
+ * is down. That makes the backoff "ask again when this process could plausibly
+ * have learned something new", which is the only thing it is for: once
+ * {@link reconcileModuleWorkers} has paused the worker nothing is fetched at
+ * all, so this is a fallback's cadence and never a steady state's.
+ *
+ * It is deliberately **not** {@link RETRY_AFTER_SECONDS}, the 60 s a 503'd HTTP
+ * client is told to wait, and the difference was measured rather than reasoned
+ * about: BullMQ's `waitForRateLimit` delays the fetch loop for the whole
+ * remaining window, and it holds across a `resume()`. At 60 s a job caught in
+ * the flip window sat for the better part of a minute after the operator
+ * switched the module back on — correct, and indistinguishable from broken.
+ */
+const ABSENT_JOB_BACKOFF_MS = FALLBACK_TTL_MS;
+/** Marks a worker whose processor already carries the work gate. */
+const GATED = Symbol.for('endora.moduleWorker.presenceGated');
+/**
+ * The work gate — Constitution XVII, and AGENTS.md's rule for an entry point
+ * with nowhere to throw to: *presence is decided before the work, first and
+ * outside the `try`*.
+ *
+ * A BullMQ processor is such an entry point. The fetch gate below stops a
+ * worker within one presence install of the flip, but a job already fetched
+ * when presence moved would still run its module's business logic — which for
+ * `google_analytics` means one more disclosure to a third party after the
+ * operator withdrew it. So the decision is per job.
+ *
+ * **What happens to the job: it is left waiting.** `Worker.rateLimit` plus
+ * `RateLimitError` is BullMQ's own idiom for "not now, put it back": the worker
+ * handles that error with `job.moveToWait(token)`, which RPUSHes the job onto
+ * the wait list, emits `waiting`, consumes no attempt and fires no `failed`
+ * handler. Failing the job would burn its retries against a decision that is
+ * not about the job, and completing it would drop work an operator never asked
+ * to lose. Deactivation is "non-destructive and reversible" (Principle XVII),
+ * so the job drains when the module comes back.
+ */
+function installWorkGate(moduleId, worker) {
+    const slot = worker;
+    if (slot[GATED])
+        return;
+    const inner = slot.processFn;
+    if (typeof inner !== 'function') {
+        throw new Error(`[kernel] module '${moduleId}' registered a queue consumer whose processor could not be ` +
+            `found (BullMQ's \`Worker.processFn\`). Without it the worker would keep running the ` +
+            `module's business logic after an operator switched the module off (Constitution XVII). ` +
+            `If BullMQ has renamed the property, \`installWorkGate\` is the one place that names it.`);
+    }
+    slot.processFn = async (job, token, signal) => {
+        // First, and outside every `try`: a switched-off module and a genuine
+        // failure must not share one silent no-op. `isPresent` throws on a cache
+        // nothing has loaded, and "nothing has read the database yet" is not an
+        // answer a processor can act on either — so it reads as absent, which is
+        // the direction that loses no work.
+        if (!isPresentOrUnresolved(moduleId)) {
+            await worker.rateLimit(ABSENT_JOB_BACKOFF_MS);
+            throw new RateLimitError();
+        }
+        return inner.call(worker, job, token, signal);
+    };
+    slot[GATED] = true;
+}
+/** Effective presence, with an unloaded cache reading as absent rather than throwing. */
+function isPresentOrUnresolved(moduleId) {
+    return registryCache.isLoaded() && effectiveState.isPresent(moduleId);
+}
+/**
+ * The fetch gate — bring every registered worker into agreement with its
+ * module's effective state.
+ *
+ * Level-triggered and idempotent, so it is safe to run on every presence
+ * install: BullMQ's own `pause()` and `resume()` are no-ops when the worker is
+ * already there, and the comparison below keeps even those off the common path.
+ *
+ * This is what makes the repair work across processes. Every composed process —
+ * API, `BACKEND_ROLE=worker`, `all` — keeps its own {@link registryCache} fresh
+ * from the same `b2b:module:state-changed` channel (and from the degraded-mode
+ * timer when Redis is unavailable), so following the cache means the worker
+ * process reacts to a flip written anywhere, including by a CLI that composed
+ * nothing.
+ */
+export function reconcileModuleWorkers() {
+    if (!registryCache.isLoaded())
+        return;
+    for (const [moduleId, workers] of moduleWorkers) {
+        const present = effectiveState.isPresent(moduleId);
+        for (const worker of workers) {
+            if (present === !worker.isPaused())
+                continue;
+            applyWorkerPresence(moduleId, worker, present);
+        }
+    }
+}
+/**
+ * Pause or resume one worker, without waiting for it.
+ *
+ * A presence install is synchronous — it happens inside a pub/sub callback or a
+ * timer tick — so this cannot be awaited, and `pause()` deliberately waits for
+ * the jobs already running to finish (the non-destructive half: an in-flight job
+ * completes, and nothing new is fetched).
+ *
+ * The `catch` is not a tolerance and is not a port catch (`Worker.pause` reaches
+ * no module): it is what keeps a fire-and-forget promise from becoming an
+ * **unhandled rejection**, which in a Node process is a crash rather than a
+ * message. It is reachable — `pause()` reconnects the blocking connection to
+ * wait for the active job, and a connection that is closing rejects — and it
+ * costs nothing to say so out loud. The worker is left where it was; the next
+ * presence install (the pub/sub message, or the degraded timer five seconds
+ * later) tries again, which is what level-triggering buys.
+ */
+function applyWorkerPresence(moduleId, worker, present) {
+    let settled;
+    try {
+        settled = present ? Promise.resolve(worker.resume()) : worker.pause();
+    }
+    catch (err) {
+        warnWorkerPresenceFailed(moduleId, worker, present, err);
+        return;
+    }
+    // No re-read once it settles, deliberately. `pause()` awaits the job already
+    // running, so two flips can settle out of order — but BullMQ sets `paused`
+    // **synchronously** and clears it the same way, so the flag already agrees
+    // with the last caller before either promise resolves. A convergence loop here
+    // would be machinery for a hazard nothing in this stack has.
+    void settled.catch((err) => warnWorkerPresenceFailed(moduleId, worker, present, err));
+}
+function warnWorkerPresenceFailed(moduleId, worker, present, err) {
+    console.warn(`[module-lifecycle] could not ${present ? 'resume' : 'pause'} a queue consumer of ` +
+        `'${moduleId}' (${worker.name}); the next presence refresh will retry: ${err instanceof Error ? err.message : String(err)}`);
+}
+let reconcilerArmed = false;
+function armWorkerReconciler() {
+    if (reconcilerArmed)
+        return;
+    reconcilerArmed = true;
+    registryCache.onPresenceInstalled(reconcileModuleWorkers);
+}
+/**
+ * Register a BullMQ Worker as its module's, so both gates apply to it.
+ *
+ * Two things happen, and only the first was ever true: the worker joins the
+ * per-module registry {@link pauseWorkersFor} iterates, **and** its processor is
+ * wrapped in the work gate while the registry itself is reconciled against the
+ * cache on every presence install. The returned worker is the same instance.
+ *
+ * A worker constructed outside this seam is a worker nothing can stop —
+ * `check:worker-seam` is the ratchet for that, and `pwa`'s push consumer was
+ * the live instance when it landed.
+ */
+export function defineModuleWorker(moduleId, worker, options) {
+    const set = moduleWorkers.get(moduleId) ?? new Set();
+    set.add(worker);
+    moduleWorkers.set(moduleId, set);
+    if (options?.logger) {
+        attachWorkerLogging(moduleId, worker, options.logger);
+    }
+    installWorkGate(moduleId, worker);
+    armWorkerReconciler();
+    // A closed worker is not a paused one, and resuming it would restart a queue
+    // consumer whose owner has gone. Leaving it in the registry is also how the
+    // map grew without bound across a long-lived process.
+    worker.on('closed', () => {
+        set.delete(worker);
+        if (set.size === 0)
+            moduleWorkers.delete(moduleId);
+    });
+    // If the module is currently absent at registration time, start paused.
+    if (!isPresentOrUnresolved(moduleId)) {
+        applyWorkerPresence(moduleId, worker, false);
+    }
+    return worker;
+}
+/**
+ * Pause a module's workers now, without waiting for the next presence install.
+ *
+ * An **optimisation**, since the fetch gate above: the orchestrator's disable
+ * path refreshes the cache and publishes the state change, which reconciles
+ * every process including this one. Calling it here simply makes the local
+ * process's answer immediate rather than one refresh away.
+ */
+export async function pauseWorkersFor(moduleId) {
+    for (const w of moduleWorkers.get(moduleId) ?? []) {
+        await w.pause();
+    }
+}
+/**
+ * Resume a module's workers now. The mirror of {@link pauseWorkersFor}, and an
+ * optimisation on the same terms — note that it resumes on the **platform**
+ * axis alone, which is safe only because the work gate re-asks for the
+ * conjunction on every job.
+ */
+export async function resumeWorkersFor(moduleId) {
+    for (const w of moduleWorkers.get(moduleId) ?? []) {
+        await w.resume();
+    }
+}
+/**
+ * Test seam — empty the per-process worker registry.
+ *
+ * The suite shares one process per fork, so a worker registered by an earlier
+ * test is still there for the reconcile the next one triggers. Production never
+ * calls it: workers leave the registry when they close.
+ */
+export function resetModuleWorkersForTesting() {
+    moduleWorkers.clear();
+}
+/**
+ * Wrap an EventBus subscription so the handler is a no-op when the
+ * owning module is absent. Mirrors `EventBus.on(eventName, handler)`'s
+ * unsubscribe-returning shape.
+ */
+export function subscribeForModule(moduleId, bus, event, handler) {
+    const wrapped = async (payload) => {
+        if (!effectiveState.isPresent(moduleId))
+            return;
+        await handler(payload);
+    };
+    return bus.on(event, wrapped);
+}
+//# sourceMappingURL=plugin-helpers.js.map

package/dist/kernel/lifecycle/plugin-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-helpers.js","sourceRoot":"","sources":["../../../src/kernel/lifecycle/plugin-helpers.ts"],"names":[],"mappings":"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"}