@endora-commerce/platform 0.100.0

package/dist/kernel/lifecycle/registry-cache.js

@@ -0,0 +1,509 @@
+import { createHash } from 'node:crypto';
+import { ModuleRegistration } from './module-registration.entity.js';
+import { inProcessCaches } from '../cache/in-process-cache-registry.js';
+import { enterSystemScope } from '../scope.js';
+import { resolveActivation, } from './activation-resolver.js';
+export const STATE_CHANGED_CHANNEL = 'b2b:module:state-changed';
+export const FALLBACK_TTL_MS = 5_000;
+/**
+ * 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 class ModulePresenceNotLoadedError extends Error {
+    read;
+    constructor(read) {
+        super(`[module-lifecycle] module presence was read (${read}) before it was loaded. ` +
+            `\`loadModulePresence()\` runs as a composition step in \`composeApp()\`, ` +
+            `before the first module registers; a read earlier than that is a wiring defect.`);
+        this.read = read;
+        this.name = 'ModulePresenceNotLoadedError';
+    }
+}
+export 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.
+     */
+    loaded = false;
+    enabled = new Set();
+    /** Every registry row's state, including the non-installed ones. */
+    platformStates = new Map();
+    /** Resolved operator activation, per declaring module. */
+    activation = new Map();
+    declarations = new Map();
+    /**
+     * 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.
+     */
+    capabilityMembers = new Map();
+    exclusiveCapabilities = new Map();
+    /**
+     * 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.
+     */
+    presenceSignature = '';
+    presenceVersionCounter = 0;
+    subscriber = null;
+    degraded = false;
+    fallbackTimer = null;
+    fallbackStopped = false;
+    presenceListeners = new Set();
+    /** True once {@link load} — or the test seam that stands in for it — has run. */
+    isLoaded() {
+        return this.loaded;
+    }
+    /**
+     * 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) {
+        this.presenceListeners.add(listener);
+        return () => {
+            this.presenceListeners.delete(listener);
+        };
+    }
+    notifyPresenceInstalled() {
+        for (const listener of this.presenceListeners) {
+            try {
+                listener();
+            }
+            catch (err) {
+                console.warn(`[module-lifecycle] a presence listener threw: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * 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() {
+        return this.presenceVersionCounter;
+    }
+    /**
+     * 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.
+     */
+    restamp() {
+        const parts = [];
+        for (const moduleId of [...this.platformStates.keys()].sort()) {
+            parts.push(`p:${moduleId}=${this.platformStates.get(moduleId) ?? ''}`);
+        }
+        for (const moduleId of [...this.activation.keys()].sort()) {
+            parts.push(`a:${moduleId}=${this.activation.get(moduleId) === true ? '1' : '0'}`);
+        }
+        const signature = createHash('sha1').update(parts.join('\n')).digest('hex');
+        if (signature !== this.presenceSignature) {
+            this.presenceSignature = signature;
+            this.presenceVersionCounter += 1;
+        }
+        this.notifyPresenceInstalled();
+    }
+    assertLoaded(read) {
+        if (!this.loaded)
+            throw new ModulePresenceNotLoadedError(read);
+    }
+    isEnabled(moduleId) {
+        this.assertLoaded('isEnabled');
+        return this.enabled.has(moduleId);
+    }
+    enabledIds() {
+        this.assertLoaded('enabledIds');
+        return [...this.enabled].sort();
+    }
+    /** Platform axis detail for the presence projection. */
+    platformStateOf(moduleId) {
+        this.assertLoaded('platformStateOf');
+        return this.platformStates.get(moduleId) ?? 'not-installed';
+    }
+    /**
+     * Resolved activation for a module that declares a control, or `undefined`
+     * when nothing has been resolved for it yet.
+     */
+    activationValue(moduleId) {
+        this.assertLoaded('activationValue');
+        return this.activation.get(moduleId);
+    }
+    activationDeclaration(moduleId) {
+        return this.declarations.get(moduleId);
+    }
+    /**
+     * 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) {
+        for (const declaration of this.declarations.values()) {
+            if (declaration.settingCode === settingCode)
+                return declaration;
+        }
+        return 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) {
+        this.declarations = new Map(declarations.map((d) => [d.moduleId, d]));
+    }
+    /**
+     * 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) {
+        const members = new Map();
+        for (const declaration of registry.declarations) {
+            for (const key of declaration.capabilities) {
+                const list = members.get(key) ?? [];
+                list.push(declaration.moduleId);
+                members.set(key, list);
+            }
+        }
+        this.capabilityMembers = members;
+        this.exclusiveCapabilities = new Map(registry.exclusive.map((entry) => [entry.key, entry]));
+    }
+    /**
+     * 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) {
+        return this.capabilityMembers.get(key) ?? [];
+    }
+    /**
+     * 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) {
+        return this.exclusiveCapabilities.get(key);
+    }
+    /** Union of everything the registry knows and everything that declared a control. */
+    knownModuleIds() {
+        this.assertLoaded('knownModuleIds');
+        return [...new Set([...this.platformStates.keys(), ...this.declarations.keys()])].sort();
+    }
+    /**
+     * 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.
+     */
+    async load(opts) {
+        if (opts.activationDeclarations) {
+            this.setActivationDeclarations(opts.activationDeclarations);
+        }
+        if (opts.capabilityRegistry) {
+            this.setCapabilityDeclarations(opts.capabilityRegistry);
+        }
+        await this.refreshFromDb(opts.em);
+    }
+    /**
+     * 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.
+     */
+    async watch(opts) {
+        if (this.subscriber)
+            return;
+        this.subscriber = opts.redisSubscriber;
+        this.subscriber.on('message', (channel) => {
+            if (channel !== STATE_CHANGED_CHANNEL)
+                return;
+            // D-174 — this process's caches that are derived from module state, first
+            // and synchronously. The channel is the only cross-process announcement
+            // of an install rewriting a module's palette rows or another module's
+            // translation bundles, and `presenceVersion()` is blind to both: it
+            // hashes the two presence axes and nothing else. A module may not name
+            // this channel — a transport detail, carrying a payload it does not read
+            // — so it registers a layer and the kernel's own subscriber drops it.
+            // Before the refresh below, deliberately: the drop's whole value over the
+            // version pull is that it lands on receipt rather than a PostgreSQL
+            // round-trip later. Errors are contained inside the registry.
+            void inProcessCaches.invalidateForModuleStateChange();
+            // Issue #235 — the same reason the degraded timer below states, for the
+            // same call: this refresh reads `module_registrations` and `settings` from
+            // a Redis pub/sub callback, delivered off a socket the composition opened,
+            // so there is no caller to inherit a context from. Both entities are
+            // `@GlobalEntity()` today and the tenant filters therefore contribute
+            // nothing — an accident of classification, not a design, and one that
+            // stops holding the moment either query path gains a scoped sibling.
+            void enterSystemScope('_lifecycle: registry refresh on state-change notification', () => this.refreshFromDb(opts.em), { entryPoint: 'message' }).catch((err) => {
+                // Slip into degraded mode; the fallback timer keeps re-reading.
+                this.enterDegradedMode(opts.em);
+                console.warn(`[module-lifecycle] registry-cache refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        });
+        this.subscriber.on('end', () => {
+            this.enterDegradedMode(opts.em);
+        });
+        try {
+            await this.subscriber.subscribe(STATE_CHANGED_CHANNEL);
+        }
+        catch (err) {
+            this.enterDegradedMode(opts.em);
+            console.warn(`[module-lifecycle] registry-cache could not subscribe to ${STATE_CHANGED_CHANNEL} — ` +
+                `serving the loaded state and re-reading PostgreSQL every ${FALLBACK_TTL_MS}ms: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // No Redis mirror of the enabled set (feature 073, T140). One existed —
+        // `b2b:module:enabled-set` — written here and read by nothing: a cold start
+        // reads `module_registrations`, which is the authority, and every later
+        // refresh is triggered by the pub/sub notification above. A second copy of
+        // presence that nothing consults can only be a thing to keep in sync and a
+        // thing to mislead whoever finds it.
+    }
+    /**
+     * 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, opts) {
+        this.loaded = true;
+        this.enabled = new Set(ids);
+        this.platformStates = new Map(ids.map((id) => [id, 'installed']));
+        this.activation = new Map(ids.map((id) => [id, true]));
+        for (const id of opts?.deactivated ?? []) {
+            this.activation.set(id, false);
+        }
+        this.restamp();
+    }
+    /**
+     * 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() {
+        this.loaded = false;
+        this.enabled = new Set();
+        this.platformStates = new Map();
+        this.activation = new Map();
+        this.declarations = new Map();
+        this.capabilityMembers = new Map();
+        this.exclusiveCapabilities = new Map();
+        this.restamp();
+    }
+    /**
+     * 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.
+     */
+    async __refreshActivationForTesting(em) {
+        this.activation = await resolveActivation(em(), [...this.declarations.values()]);
+        this.restamp();
+    }
+    /** True when the pub/sub side is unhealthy and the cache is TTL-refreshing. */
+    isDegraded() {
+        return this.degraded;
+    }
+    /** Refresh both axes from the source-of-truth tables. Idempotent. */
+    async refreshFromDb(em) {
+        const fork = em();
+        const rows = await fork.find(ModuleRegistration, {});
+        const freshEnabled = new Set();
+        const freshStates = new Map();
+        for (const r of rows) {
+            freshStates.set(r.moduleId, r.state);
+            if (r.state === 'installed')
+                freshEnabled.add(r.moduleId);
+        }
+        const freshActivation = await resolveActivation(fork, [...this.declarations.values()]);
+        this.enabled = freshEnabled;
+        this.platformStates = freshStates;
+        this.activation = freshActivation;
+        this.loaded = true;
+        this.restamp();
+        this.clearDegradedMode();
+    }
+    /**
+     * 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.
+     */
+    enterDegradedMode(em) {
+        this.degraded = true;
+        // A disconnecting ioredis client keeps emitting `'end'` while it retries,
+        // so without this an explicitly stopped cache re-arms itself and outlives
+        // its owner — polling a closed EntityManager for the rest of the process.
+        if (this.fallbackStopped)
+            return;
+        if (this.fallbackTimer)
+            return;
+        this.fallbackTimer = setInterval(() => {
+            // Feature 072 (T034) — the degraded refresh reads `module_registrations`
+            // from a timer, with no caller to inherit a context from.
+            void enterSystemScope('_lifecycle: degraded registry refresh', () => this.refreshFromDb(em), { entryPoint: 'interval' }).catch((err) => {
+                console.warn(`[module-lifecycle] degraded refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+                // Stay degraded and try again on the next tick.
+                this.degraded = true;
+            });
+        }, FALLBACK_TTL_MS);
+        // Do not hold the process open for the sake of a cache refresh.
+        this.fallbackTimer.unref?.();
+    }
+    clearDegradedMode() {
+        this.degraded = false;
+        if (this.fallbackTimer) {
+            clearInterval(this.fallbackTimer);
+            this.fallbackTimer = null;
+        }
+    }
+    /**
+     * 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() {
+        this.fallbackStopped = true;
+        if (this.fallbackTimer) {
+            clearInterval(this.fallbackTimer);
+            this.fallbackTimer = null;
+        }
+    }
+}
+/** Module-internal singleton consumed by the wrappers. */
+export const registryCache = new ModuleRegistryCache();
+/**
+ * Publish a state-change notification. Called by the orchestrator on
+ * every successful install / uninstall / enable / disable.
+ */
+export async function publishStateChanged(redis, payload) {
+    await redis.publish(STATE_CHANGED_CHANNEL, JSON.stringify(payload));
+}
+//# sourceMappingURL=registry-cache.js.map

package/dist/kernel/lifecycle/registry-cache.js.map

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

package/dist/kernel/lifecycle/required-modules.d.ts

@@ -0,0 +1,137 @@
+import type { ModuleManifest, RegistryState } from '@endora-commerce/contracts';
+/**
+ * The modules a composition is **required to have**, and the refusal when it
+ * does not (issue #258, owner ruling: *"`settings` is too important to be
+ * absent from a deployment"*).
+ *
+ * ## The gap this closes
+ *
+ * `activation.nonDeactivatable` guards **withdrawal**: since D-69 the lifecycle
+ * orchestrator refuses to disable or uninstall a module that declares it, soft
+ * and hard alike, with no `--force`. D-101 then bound the **initial state** for
+ * the two absences a manifest analysis can see — a module this deployment never
+ * shipped that another manifest names, and a module carrying a
+ * `module_registrations` row the boot reconciler will not repair. Both refuse
+ * from `loadModulePresence`, before the registry is even read.
+ *
+ * Neither of them can see the state that actually breaks a first boot: presence
+ * answering *absent* for a required module at the moment the boot phase starts.
+ * `loadModulePresence` runs before the first module registers, so it knows the
+ * manifests but not what was composed; and it is the *first* writer of presence,
+ * not the only one. This runs at the other end of the registration pass, where
+ * both answers exist at once.
+ *
+ * ## What a mis-built deployment used to see
+ *
+ * `invoices` grandfathers its numbering pattern from a `ctx.onBoot` hook
+ * (feature 078, D-95.3) and the write goes through `settings`' port.
+ * `NumberingConfigurationService` re-throws `ModuleDisabledError` on purpose —
+ * the write is the whole point of the hook — `runBootHooks` attributes the
+ * failure to `invoices` and re-throws as `ModuleCompositionError`, and
+ * `index.ts` turns that into `process.exit(1)`. So the platform did not degrade,
+ * it exited, saying:
+ *
+ *     [kernel] module 'invoices' failed in its boot hook:
+ *     Module 'settings' is currently disabled.
+ *
+ * — the wrong module, and no remedy. It had never been seen because on any
+ * database where the platform booted once the grandfather write has already
+ * happened and the hook finds nothing to do; only a genuinely first boot reaches
+ * the port.
+ *
+ * ## Why this is not `assertDeactivatable` and not `assertLockedModulesPresent`
+ *
+ * Three refusals now rest on one manifest declaration, and D-101 already ruled
+ * that they must stay three: *"they share a declaration and share nothing else —
+ * not a call site, not an error type, not a message. Anyone reading either
+ * should be able to tell which question they are looking at without reading the
+ * other."* `assertDeactivatable` refuses a **transition an operator asked for**
+ * and answers it with an HTTP envelope. `assertLockedModulesPresent` refuses a
+ * **deployment that was assembled wrong**, from the manifests, before the
+ * database is touched. This refuses a **composition that reached its boot phase
+ * without a module it requires**, from what was actually registered and what
+ * presence actually says — the last question, at the last point where the answer
+ * is still cheap.
+ *
+ * ## The required set is derived, never written down
+ *
+ * D-100 and `check:lock-claims`: a hand-written copy of a derived fact goes stale
+ * silently. {@link requiredModulesFrom} reads the shipped manifests on every
+ * composition, so an owner who withdraws a lock changes this refusal in the same
+ * run, with no list to edit. **"Required to be installed" and "cannot be switched
+ * off" are therefore the same set, by derivation and by decision** — the manifest
+ * needs no second field, because a module whose author wrote "the platform cannot
+ * run without this" has already answered both questions with one sentence, and
+ * that sentence is what the refusal below prints.
+ *
+ * The one absence it cannot see is the one D-101's header names: a module that is
+ * not shipped at all takes its manifest with it, so *"was it locked?"* has no
+ * answer here. That case belongs to `assertLockedModulesPresent`, which asks it
+ * from the declarations of the modules that stayed.
+ */
+/** A module this composition must have, and the sentence its manifest gives. */
+export interface RequiredModule {
+    readonly moduleId: string;
+    /** The module's own `activation.reason` — why the platform cannot run without it. */
+    readonly reason: string;
+}
+/**
+ * The two ways a composition can reach its boot phase without a module it
+ * requires.
+ *
+ *  - `not-composed` — the manifests declare it, but no module registered it.
+ *    The composed module list and the manifest index disagree, which is a
+ *    mis-built artefact rather than an operator's choice.
+ *  - `absent` — it was composed, and presence says it is not there. For a
+ *    required module that is always the platform axis: `effectiveState` forces
+ *    the operator axis of a non-deactivatable module on whatever a Setting says,
+ *    so there is no operator choice that can produce this.
+ */
+export type RequiredModuleFinding = {
+    readonly kind: 'not-composed';
+    readonly moduleId: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'absent';
+    readonly moduleId: string;
+    readonly reason: string;
+    readonly platformState: RegistryState | 'not-installed';
+};
+/**
+ * The presence answers this analysis needs, and nothing else — structurally the
+ * two `EffectiveModuleState` members it uses, so a fixture supplies them and
+ * nothing more.
+ */
+export interface RequiredModulePresence {
+    isPresent(moduleId: string): boolean;
+    presence(moduleId: string): {
+        readonly platformState: RegistryState | 'not-installed';
+    } | undefined;
+}
+/**
+ * The refusal. A distinct type from every other absence refusal, per D-101's
+ * closing rule.
+ */
+export declare class RequiredModuleAbsentError extends Error {
+    readonly findings: readonly RequiredModuleFinding[];
+    constructor(findings: readonly RequiredModuleFinding[]);
+}
+/**
+ * The required set, straight from the shipped manifests.
+ *
+ * Pure and exported so its proof drives the classification from a fixture that
+ * enters at the top of the analysis, rather than from a value a composition
+ * already computed.
+ */
+export declare function requiredModulesFrom(manifests: readonly ModuleManifest[]): readonly RequiredModule[];
+/**
+ * Every required module this composition cannot serve, in manifest order.
+ *
+ * Pure, and that is load-bearing rather than stylistic — the same reason
+ * `assertLockedModulesPresent` is: its whole input is the three things a
+ * composition has by the end of its registration pass.
+ */
+export declare function absentRequiredModules(required: readonly RequiredModule[], composed: ReadonlySet<string>, presence: RequiredModulePresence): readonly RequiredModuleFinding[];
+/** {@link absentRequiredModules}, as the refusal the composer makes. */
+export declare function assertRequiredModulesPresent(required: readonly RequiredModule[], composed: ReadonlySet<string>, presence: RequiredModulePresence): void;
+//# sourceMappingURL=required-modules.d.ts.map

package/dist/kernel/lifecycle/required-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-modules.d.ts","sourceRoot":"","sources":["../../../src/kernel/lifecycle/required-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAEH,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrF;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,eAAe,CAAC;CACzD,CAAC;AAEN;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,QAAQ,CACN,QAAQ,EAAE,MAAM,GACf;QAAE,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,eAAe,CAAA;KAAE,GAAG,SAAS,CAAC;CAC5E;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;gBAExC,QAAQ,EAAE,SAAS,qBAAqB,EAAE;CAKvD;AAkCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,cAAc,EAAE,GACnC,SAAS,cAAc,EAAE,CAQ3B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,QAAQ,EAAE,sBAAsB,GAC/B,SAAS,qBAAqB,EAAE,CAkBlC;AAED,wEAAwE;AACxE,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,QAAQ,EAAE,sBAAsB,GAC/B,IAAI,CAGN"}