@endora-commerce/platform 0.100.0

package/dist/kernel/lifecycle/registry-cache.d.ts

@@ -0,0 +1,318 @@
+import type { Redis } from 'ioredis';
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { RegistryState } from '@endora-commerce/contracts';
+import { type ModuleActivationDeclaration } from './activation-resolver.js';
+import type { CapabilityRegistry, ExclusiveCapabilityDeclaration } from './capability-registry.js';
+export declare const STATE_CHANGED_CHANNEL = "b2b:module:state-changed";
+export declare const FALLBACK_TTL_MS = 5000;
+/**
+ * Per-process cache of module presence. Hot path for the
+ * `defineModuleRoutes` / `defineModuleWorker` / `subscribeForModule` /
+ * `requireModuleEnabled` wrappers — every request hits it, so the read side
+ * MUST stay in-memory after the cold start.
+ *
+ * It holds **both** presence axes (feature 073):
+ *
+ *  - platform availability, from `module_registrations`;
+ *  - operator activation, from the declared activation `Setting` rows.
+ *
+ * They are rebuilt in the same refresh so a process that missed a
+ * notification cannot hold the two axes in disagreement. Combining them is
+ * `ModuleEffectiveState`'s job, not this class's: here they stay separate,
+ * because the Admin UI has to tell "not installed here" from "switched off".
+ *
+ * The cache keeps itself fresh by subscribing to the
+ * `b2b:module:state-changed` pub/sub channel. If that connection drops, a
+ * background timer re-reads from PostgreSQL every `FALLBACK_TTL_MS` until it
+ * recovers — PostgreSQL is the authority and stays reachable during a Redis
+ * outage, so degraded means *stale*, not *everything off*.
+ *
+ * **Loading and watching are two different things** (feature 072, D-38), and
+ * conflating them is what kept the backend from booting:
+ *
+ *  - {@link load} is awaited, fatal and PostgreSQL-only. It runs as a kernel
+ *    step inside `composeApp()`, before the first module registers, because a
+ *    boot hook resolving a gated port asks this cache and a composition-time
+ *    answer of "off" is indistinguishable from "nobody has read the database
+ *    yet".
+ *  - {@link watch} is armed after composition, is Redis-only and can never fail
+ *    a boot: losing the notification channel means *stale*, which is the
+ *    degraded mode above.
+ *
+ * Before a load there is no answer, and asking for one throws
+ * {@link ModulePresenceNotLoadedError} rather than being answered `false`. It
+ * is a wiring defect, and the one thing it must not do is look like data.
+ */
+/**
+ * A presence read reached the cache before anything loaded it.
+ *
+ * Not fail-open and not fail-closed — *loud*. Both of the other answers are
+ * answers to a question nobody has asked the database yet: `false` takes a
+ * correctly-installed platform down at boot (which is exactly what it did), and
+ * `true` runs a switched-off module's workers and subscribers.
+ */
+export declare class ModulePresenceNotLoadedError extends Error {
+    readonly read: string;
+    constructor(read: string);
+}
+export declare class ModuleRegistryCache {
+    /**
+     * The third state. `false` means "nothing has read the database", which is
+     * neither of the two answers a presence read can be given.
+     */
+    private loaded;
+    private enabled;
+    /** Every registry row's state, including the non-installed ones. */
+    private platformStates;
+    /** Resolved operator activation, per declaring module. */
+    private activation;
+    private declarations;
+    /**
+     * The derived capability families (feature 132), indexed the two ways they are
+     * read: key → declared member ids, and key → its owner's declaration.
+     *
+     * They live **here**, beside the activation declarations and the resolved
+     * activation, and that is the Redis cache-invalidation design rather than a
+     * convenience (`data-model.md` §2.2). An exclusion reads membership and
+     * activation together on every refusal, and this cache is refreshed by the
+     * `b2b:module:state-changed` pub/sub channel — the same refresh that
+     * re-resolves activation. Holding both in one structure with one invalidation
+     * is what stops them disagreeing; a family cached anywhere else would need a
+     * second refresh path and would be stale for exactly the window in which an
+     * operator is flipping a connector, which is the only window that matters.
+     */
+    private capabilityMembers;
+    private exclusiveCapabilities;
+    /**
+     * Content hash of the two axes, and the counter that moves with it.
+     *
+     * Issue #225 — a consumer that memoises anything derived from presence needs
+     * to know **when the presence it read from was replaced**, and a pub/sub
+     * message cannot tell it: the message announces a change whose effect on this
+     * cache is still a PostgreSQL round-trip away, so a snapshot rebuilt on the
+     * message is rebuilt from the pre-change maps and then kept. The version is
+     * the answer to that, and it is a *pull*: no registration, therefore no
+     * listener order to get wrong, and a consumer constructed after a refresh
+     * still reads the right number.
+     *
+     * It moves on **content**, not on refresh count. Every state-changed message
+     * refreshes every process and the degraded-mode timer refreshes every five
+     * seconds; a counter bumped per refresh would drop a consumer's cache each
+     * time and make it worthless during a Redis outage, for a presence that did
+     * not move. The hash costs one pass over ~70 entries, once per refresh, and
+     * never on the read path.
+     */
+    private presenceSignature;
+    private presenceVersionCounter;
+    private subscriber;
+    private degraded;
+    private fallbackTimer;
+    private fallbackStopped;
+    private presenceListeners;
+    /** True once {@link load} — or the test seam that stands in for it — has run. */
+    isLoaded(): boolean;
+    /**
+     * Run `listener` every time this cache **installs** presence — the pub/sub
+     * refresh, the degraded-mode refresh, the cold load and the test seams alike.
+     *
+     * It is the seam a consumer that owns something *stateful* needs, where
+     * {@link presenceVersion} is enough for one that merely memoises: a BullMQ
+     * worker is not re-read on a request path, so nothing would ever ask it the
+     * version, and the orchestrator's `pauseWorkersFor` reaches only the process
+     * that ran the orchestrator — never the `BACKEND_ROLE=worker` process, and
+     * never the `module:*` CLI, which composes nothing at all. Following the
+     * cache instead makes the answer per-process and therefore right in every
+     * process.
+     *
+     * Deliberately **level-triggered**: it fires on every install rather than
+     * only when the content moved, because a listener that failed once must get
+     * another chance — the degraded-mode timer is then a retry loop rather than a
+     * silence. Listeners are therefore obliged to be idempotent and cheap.
+     *
+     * Notification is synchronous and its errors are contained here: a consumer
+     * that throws must not take down a refresh that every gating seam depends on.
+     */
+    onPresenceInstalled(listener: () => void): () => void;
+    private notifyPresenceInstalled;
+    /**
+     * Monotonic counter over the *content* of both axes. It changes exactly when
+     * a load has installed presence that differs from the presence before it, so
+     * a consumer that caches a projection of presence can drop that cache by
+     * comparing the number it built under with the current one.
+     *
+     * Synchronous and allocation-free, like every other read here: it is meant to
+     * be asked on a request path.
+     */
+    presenceVersion(): number;
+    /**
+     * Re-sign both axes and bump the counter when the signature moved, then tell
+     * every {@link onPresenceInstalled} listener that presence was installed.
+     * Called at the end of every path that installs presence — the real refresh
+     * and the three test seams alike, because a seam that swaps presence without
+     * moving the version would leave a consumer serving the presence before it.
+     *
+     * The notification is unconditional where the counter is not: the counter
+     * answers "did the content move", which is the question a memoising consumer
+     * asks, and the listeners answer "reconcile yourself to what is here now",
+     * which has to keep being asked after a listener that failed.
+     */
+    private restamp;
+    private assertLoaded;
+    isEnabled(moduleId: string): boolean;
+    enabledIds(): string[];
+    /** Platform axis detail for the presence projection. */
+    platformStateOf(moduleId: string): RegistryState | 'not-installed';
+    /**
+     * Resolved activation for a module that declares a control, or `undefined`
+     * when nothing has been resolved for it yet.
+     */
+    activationValue(moduleId: string): boolean | undefined;
+    activationDeclaration(moduleId: string): ModuleActivationDeclaration | undefined;
+    /**
+     * The module that declares `settingCode` as its activation control, if any.
+     * Used by the settings write guards: an activation code has exactly one
+     * legitimate door, and it is not `PUT /settings/:code/value` (FR-009).
+     */
+    activationDeclarationByCode(settingCode: string): ModuleActivationDeclaration | undefined;
+    /**
+     * Install the activation declarations distilled from the manifests. Kept as
+     * plain data so the hot path never imports the manifest graph. Refreshing
+     * without them resolves the platform axis only, which is exactly the
+     * behaviour of a module that has declared no control.
+     */
+    setActivationDeclarations(declarations: readonly ModuleActivationDeclaration[]): void;
+    /**
+     * Install the derived capability registry. Plain data, for the same reason the
+     * activation declarations are: the hot path must never import the manifest
+     * graph.
+     *
+     * Replaces the whole registry rather than merging into it — a re-load is a
+     * re-derivation from the manifests this process composed, and a merge would
+     * keep a member that a `module:uninstall` has taken away.
+     */
+    setCapabilityDeclarations(registry: CapabilityRegistry): void;
+    /**
+     * Every module that **declared** membership of `key`, present or not, in
+     * manifest order.
+     *
+     * No `assertLoaded`, exactly like {@link activationDeclaration}: this is
+     * manifest data installed by the composition root before any database read,
+     * and the family owner registers its exclusion interceptor at that point. A
+     * read that threw before the load would make the family unreadable at the one
+     * moment it has to be readable.
+     */
+    declaredCapabilityMembers(key: string): readonly string[];
+    /**
+     * The owner and refusal code for `key`, or `undefined` when no installed
+     * module owns it — which is not an error (R3.5): the capability is simply not
+     * exclusive in that deployment.
+     */
+    exclusiveCapability(key: string): ExclusiveCapabilityDeclaration | undefined;
+    /** Union of everything the registry knows and everything that declared a control. */
+    knownModuleIds(): string[];
+    /**
+     * Load both axes from PostgreSQL. **Awaited, fatal, no Redis.**
+     *
+     * The composition root calls this before the first module registers, so a
+     * boot hook, a plugin body and a worker registration all read a cache that
+     * has an answer. Idempotent: a second call re-reads the tables.
+     *
+     * Fatal is not a new failure mode. `composeApp()` opens with `initOrm()` and
+     * MikroORM connects eagerly, so a backend whose database is unreachable
+     * already cannot boot; this adds one round-trip to a boot that makes several.
+     */
+    load(opts: {
+        em: () => EntityManager;
+        /** Activation declarations from the loaded manifests (feature 073). */
+        activationDeclarations?: readonly ModuleActivationDeclaration[];
+        /**
+         * The capability families derived from the same manifests (feature 132).
+         *
+         * In **this** call and in no other, on purpose: see the field's comment. The
+         * exclusion resolves membership against the activation this call resolves, so
+         * the two are installed by one caller and refreshed by one event.
+         */
+        capabilityRegistry?: CapabilityRegistry;
+    }): Promise<void>;
+    /**
+     * Arm the pub/sub subscriber that keeps the loaded state fresh. **Not fatal,
+     * no PostgreSQL read of its own.** Safe to call multiple times — a second
+     * call does not re-subscribe.
+     *
+     * A Redis outage must never fail a boot: the channel is a freshness
+     * optimisation over an authority that is still reachable, which is the whole
+     * argument for the degraded mode below. So a failing subscribe enters that
+     * mode instead of propagating.
+     */
+    watch(opts: {
+        redisSubscriber: Redis;
+        em: () => EntityManager;
+    }): Promise<void>;
+    /**
+     * Test seam — replaces both axes without touching Redis or the database.
+     * `ids` seeds platform availability; `opts.deactivated` seeds the operator
+     * axis to off, which is the axis an operator actually drives.
+     *
+     * It counts as a {@link load}: it is "the load, without a database", and a
+     * harness that seeds it has answered the question the tri-state asks.
+     */
+    __setEnabledForTesting(ids: readonly string[], opts?: {
+        deactivated?: readonly string[];
+    }): void;
+    /**
+     * Test seam — return the cache to the unloaded state, which is the one state
+     * a test cannot otherwise reach: the suite shares one process, so by the time
+     * a file runs, some earlier file has almost certainly seeded the singleton.
+     * The invariant "a presence read before the load is an error" is not testable
+     * without it.
+     */
+    __resetForTesting(): void;
+    /**
+     * Test seam — re-resolve the **operator** axis from the database, leaving the
+     * seeded platform axis alone.
+     *
+     * The shared test harness never populates `module_registrations`; it seeds
+     * the enabled-set directly through `__setEnabledForTesting`. A full
+     * `refreshFromDb` there would find an empty registry table and take every
+     * gated route down mid-run, so a test that has just written an activation
+     * value needs this narrower refresh to observe it.
+     *
+     * Production never calls it: a partial refresh is exactly how the two axes
+     * would drift apart in a process that missed a notification, which is why
+     * `refreshFromDb` rebuilds both together.
+     */
+    __refreshActivationForTesting(em: () => EntityManager): Promise<void>;
+    /** True when the pub/sub side is unhealthy and the cache is TTL-refreshing. */
+    isDegraded(): boolean;
+    /** Refresh both axes from the source-of-truth tables. Idempotent. */
+    refreshFromDb(em: () => EntityManager): Promise<void>;
+    /**
+     * Degraded-mode refresh. Runs on a timer rather than at the seam: the
+     * wrappers' check must stay synchronous (FR-004), so a lazy
+     * `await maybeRefresh()` on the hot path is not available.
+     *
+     * Refreshing from PostgreSQL rather than blanking the sets is deliberate.
+     * Fail-closed applies to *unresolved* state, not to stale state; treating a
+     * Redis blip as "every module is off" would take the platform down, and the
+     * database — the actual authority — is still reachable.
+     */
+    private enterDegradedMode;
+    private clearDegradedMode;
+    /**
+     * Stop the degraded-mode timer for good. Used by tests and by process
+     * shutdown: after this the cache will not re-arm, so tearing down the
+     * database behind it produces no background noise.
+     */
+    stopFallbackRefresh(): void;
+}
+/** Module-internal singleton consumed by the wrappers. */
+export declare const registryCache: ModuleRegistryCache;
+/**
+ * Publish a state-change notification. Called by the orchestrator on
+ * every successful install / uninstall / enable / disable.
+ */
+export declare function publishStateChanged(redis: Redis, payload: {
+    moduleId: string;
+    newState: string;
+}): Promise<void>;
+//# sourceMappingURL=registry-cache.d.ts.map

package/dist/kernel/lifecycle/registry-cache.d.ts.map

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