@endora-commerce/platform 0.100.0

package/dist/kernel/index.js

@@ -0,0 +1,160 @@
+/**
+ * The kernel (feature 072) — the platform's module-facing surface.
+ * Peer of `events/`, `tenancy/`, `http/`, `db/`; becomes the `./kernel` subpath
+ * of `@endora-commerce/platform` in F4 (D-160.1 — one host package, not five
+ * mirroring the five directories).
+ *
+ * **That subpath is the boundary a future `@endora-commerce/kernel` would
+ * take.** D-160.6 answered the meta-package *no* on measurement rather than on
+ * possibility — over the five publishable directories the graph holds one
+ * breakable cycle, and the median module needs four of the five — and it kept
+ * the split available in the direction it is cheap: one package becomes five by
+ * re-pointing a subpath, while five published packages become one only by
+ * breaking every dependent. So this barrel is a package boundary in waiting,
+ * and it carries **this directory's** symbols and nothing else. A symbol from
+ * `http/`, `events/`, `tenancy/` or `commands/` re-exported here to save a
+ * consumer one import line spends that option for a convenience.
+ *
+ * **What is on it is decided by `contracts/host-package.md` §1.3, not by what
+ * happens to be here** (T042c). Until T042c the barrel was an accumulation:
+ * 126 names, of which modules took **six** — `ModuleContext`, `lazyPort`, the
+ * two public-origin readers and two settings errors — while every other module
+ * reach into this directory went by relative path and will become a bare
+ * specifier when its module moves. Publishing the rest of the directory
+ * alongside them would have made `@endora-commerce/platform` owe a major
+ * version for `ManifestReconciler` (§1.3 row 46, **A**, on the barrel since
+ * feature 072), for the container the host builds once, and for
+ * `AuditLogService`, whose class D-160.10 replaced with {@link AuditPort}
+ * precisely so the platform does not freeze into a contract the shape
+ * Principle XIII routes around.
+ *
+ * So the rule is: a symbol is here when §1.3 records a module taking it from a
+ * file it marks **P**, or when it is the argument, return or thrown shape of a
+ * published method — a `@throws` a caller cannot name is a method a caller
+ * cannot call. Everything else is reachable by relative path, which the two
+ * composition roots and the tests have and a packaged module does not.
+ * `test/unit/kernel/published-surface.test.ts` is the two-way ratchet, and it
+ * carries the reason each removed name is not published.
+ *
+ * Three groups deserve naming here because a future author will look for them:
+ *
+ *  - **the composition machinery** — `createRootContainer`, `composeModules`,
+ *    `registerValues`, `createModuleContext`, `registerRequestScopeHook`,
+ *    `requiredModulesFrom` and the errors they raise. D-45 gives a module one
+ *    registration pass and one boot phase, both run by the host; no module
+ *    builds a container or composes a module list.
+ *  - **the seams a `ModuleContext` already exposes** — `registerPort`
+ *    (`ctx.di.providePort`), `defineModuleWorker` / `subscribeForModule` /
+ *    `pauseWorkersFor` / `resumeWorkersFor` (`ctx.worker`, `ctx.subscribe`),
+ *    `moduleLogger` (`ctx.log`). Publishing the function re-opens by bare
+ *    specifier the seam the context closed, which is `check:subscribe-seam`'s
+ *    argument in reverse.
+ *  - **the three classes §1.4d/§1.4e make ports** — `SettingsService`,
+ *    `SalesChannelMembershipService` and `SalesChannelResolverService` are
+ *    reached through `settingsReadPort`, `salesChannelMembershipPort` and
+ *    `salesChannelResolutionPort`; their error and mutation shapes stay,
+ *    because those are what a caller of the port catches and passes.
+ *
+ * Also not here, and classified **A** outright by §1.3: the registry cache,
+ * `ModuleRegistration`, `activationDeclarationsFrom`, and anything under `db/`,
+ * `overlay/` or `packages/`.
+ *
+ * The boundary rule, enforced by `scripts/check-kernel-boundary.ts`: a module
+ * may declare an ORM relation into the kernel, never into another module, and
+ * the kernel never relates into a module.
+ */
+export {} from './module-context.js';
+export { lazyPort } from './lazy-port.js';
+/**
+ * The public origin of this backend, and the error the second one throws when a
+ * production deployment has none (issue #218). The root's boot-time refusal,
+ * `assertPublicApiBaseUrlConfigured`, is not published: it is the host's.
+ */
+export { PublicApiBaseUrlNotConfiguredError, configuredPublicApiBaseUrl, resolvePublicApiBaseUrl, } from './public-api-base-url.js';
+export { effectiveState, toModulePresenceDto } from './lifecycle/effective-state.js';
+/**
+ * The **P** half of `plugin-helpers` (§1.4c). `rethrowIfModuleDisabled` and
+ * `ModuleDisabledError` are mandated by composition-checklist item 7, and
+ * `requireModuleEnabled` is the sanctioned call for an entry point with no port
+ * and no request. The four worker/subscriber wrappers are not here — a composed
+ * module uses `ctx.worker` and `ctx.subscribe`.
+ */
+export { ModuleDisabledError, rethrowIfModuleDisabled, requireModuleEnabled, } from './lifecycle/plugin-helpers.js';
+/**
+ * The platform's structured-logger shape: `ctx.log`, the optional worker
+ * logger, and every `log` a module is handed or holds.
+ *
+ * The **type** is published and the destination machinery around it is not —
+ * `attachPlatformLogger` and `moduleLogger` are the host's, and a module that
+ * could call the second would re-open by bare specifier the attribution seam
+ * `ModuleContext` closed. A module needs the name because it declares fields
+ * and constructor parameters of this shape; it needs none of the rest.
+ *
+ * It was published under the name `WorkerLogger` from
+ * `lifecycle/plugin-helpers.js`, an identical interface declared a second time
+ * because nothing had noticed the first. Naming a consumer rather than a shape
+ * is what made a second declaration look reasonable — `ctx.log` is not a
+ * worker's — and the two spellings then diverged into a third name, an alias
+ * called `ModuleLifecycleLogger`, colliding with the unrelated hook logger
+ * `@endora-commerce/contracts` publishes under exactly that name.
+ */
+export {} from './logging.js';
+/**
+ * The one scope entry a module opens for itself (§1.3 row 13, 27 reaches). The
+ * platform-scope family below it is the host's: a module never asks which scope
+ * it is in, and the balance counter is a harness assertion.
+ */
+export { enterSystemScope } from './scope.js';
+/**
+ * The audit seam (D-160.10). `AuditLogService` is the host's implementation and
+ * is deliberately **not** published: Principle XIII routes a domain write
+ * through `CommandBus.run`, which makes the bus the audit log's caller, and
+ * freezing the writer class into the platform contract would owe third-party
+ * packages a major version to change the shape the principle routes around.
+ */
+export {} from './ports/audit.js';
+export { AuditLogEntry } from './audit/audit-log-entry.entity.js';
+export { InProcessCacheRegistry, inProcessCaches, } from './cache/in-process-cache-registry.js';
+export { hashPassword, verifyPassword } from './crypto/password-hasher.js';
+export { SalesChannel } from './sales-channels/sales-channel.entity.js';
+/**
+ * The channel cache as a module reads it. `toCachedChannel`, `CachedChannel`
+ * and the LRU TTL are how it is *filled*, which is the kernel's own half.
+ */
+export { SalesChannelsCache, SALES_CHANNELS_CACHE_KEY_PREFIX, SALES_CHANNELS_CACHE_NAMESPACE, } from './sales-channels/sales-channels-cache.js';
+// `SalesChannelResolverService` itself is **not** published (§1.4e): a consumer
+// resolves `salesChannelResolutionPort` and types on `SalesChannelResolutionPort`.
+// `parseHostMap` is the host-map parser a composition root calls, and
+// `ResolverError` is the refusal shape the port's `resolveActive` returns.
+export { parseHostMap, } from './sales-channels/sales-channel-resolver.service.js';
+export { NoSystemDefaultChannel } from './sales-channels/no-system-default-channel.error.js';
+// `SalesChannelMembershipService` itself is **not** published (§1.4e): a
+// consumer resolves `salesChannelMembershipPort` and types on
+// `SalesChannelMembershipPort`. The two mutation types stay — they are
+// parameter and return shapes of that port's own methods.
+export {} from './sales-channels/sales-channel-membership.service.js';
+// `registerSalesChannelResolverMiddleware` is the host's: the root registers
+// the middleware, a module reads the channel it resolved.
+export { getResolvedChannel, currentSalesChannel, } from './sales-channels/sales-channel-resolver.middleware.js';
+export { productIdsInRequestChannel, outOfRequestChannel, } from './sales-channels/request-channel-assortment.js';
+export { Setting } from './settings/setting.entity.js';
+export { SettingGroup } from './settings/setting-group.entity.js';
+export { SettingValue } from './settings/setting-value.entity.js';
+// `SettingsService` itself is **not** published (§1.4d): a consumer resolves
+// `settingsReadPort` and types on `SettingsReadPort`. The four errors stay —
+// they are what a caller of that port catches, and the port's doc block names
+// each one in a `@throws`.
+export { SettingNotRegistered, SettingOutOfScopeForChannel, SettingValueShapeMismatch, SettingsChannelIdInvalid, } from './settings/settings.service.js';
+// The settings cache's *invalidation* seam and its key namespace. `SettingsCache`
+// itself is the store the kernel reads through (§1.4d); a module goes through
+// `settingsReadPort`.
+export { SETTINGS_CACHE_KEY_PREFIX, SETTINGS_CACHE_NAMESPACE, } from './settings/settings-cache.js';
+// A module writes a secret and asks whether one is set; decrypting is the
+// store's, and the envelope shape with it.
+export { encryptSecretValue, secretValueIsSet, SecretKeyMissing, SecretKeyInvalid, } from './settings/secret-value-codec.js';
+export {} from './ports/require-admin.js';
+export {} from './ports/organizations.js';
+export {} from './ports/require-customer.js';
+export {} from './ports/settings.js';
+export {} from './ports/sales-channel.js';
+//# sourceMappingURL=index.js.map

package/dist/kernel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/kernel/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAsB,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;GAIG;AACH,OAAO,EACL,kCAAkC,EAClC,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAQrF;;;;;;GAMG;AACH,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAuB,MAAM,cAAc,CAAC;AAEnD;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;GAMG;AACH,OAAO,EAA8D,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAElE,OAAO,EACL,sBAAsB,EACtB,eAAe,GAEhB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE3E,OAAO,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AACxE;;;GAGG;AACH,OAAO,EACL,kBAAkB,EAClB,+BAA+B,EAC/B,8BAA8B,GAE/B,MAAM,0CAA0C,CAAC;AAClD,gFAAgF;AAChF,mFAAmF;AACnF,sEAAsE;AACtE,2EAA2E;AAC3E,OAAO,EACL,YAAY,GAEb,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qDAAqD,CAAC;AAC7F,yEAAyE;AACzE,8DAA8D;AAC9D,uEAAuE;AACvE,0DAA0D;AAC1D,OAAO,EAGN,MAAM,sDAAsD,CAAC;AAC9D,6EAA6E;AAC7E,0DAA0D;AAC1D,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,uDAAuD,CAAC;AAC/D,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,gDAAgD,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,2BAA2B;AAC3B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AACxC,kFAAkF;AAClF,8EAA8E;AAC9E,sBAAsB;AACtB,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GAEzB,MAAM,8BAA8B,CAAC;AACtC,0EAA0E;AAC1E,2CAA2C;AAC3C,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAIN,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAwD,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAA6B,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAkD,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAIN,MAAM,0BAA0B,CAAC"}

package/dist/kernel/lazy-port.d.ts

@@ -0,0 +1,59 @@
+import type { ModuleContext } from './module-context.js';
+/**
+ * A stand-in that resolves `name` from the container on **every method call**
+ * rather than once, when the holder is constructed.
+ *
+ * This exists because feature 072 kept producing the same two failures, and
+ * neither is visible at the call site or caught by `tsc`:
+ *
+ *  1. **Lifetime.** A name registered with `providePort` is a transient gate
+ *     that consults its module's effective state. Awilix's strict mode refuses
+ *     a singleton that captures one — correctly, because a captured gate goes
+ *     on answering after an operator switches the module off.
+ *  2. **Ordering.** A name a composition root registers does not exist yet when
+ *     a module composes — that is the whole shape of a composition since D-45:
+ *     `composeModules(MODULES, …)` runs first and every root contribution lands
+ *     after it. A capture taken during registration therefore captures nothing,
+ *     or, worse, captures the module's own default and never sees the root's
+ *     value. That happened twice.
+ *
+ * The rule `scripts/check-port-dependencies.ts` enforces is therefore blunt: a
+ * module may capture only names it owns and the handful of eagerly-registered
+ * kernel ones. Everything else goes through the cradle at the point of use, and
+ * this is the ergonomic way to spell that when a constructor wants an object
+ * rather than a getter.
+ *
+ * ```ts
+ * new GaConfigService(lazyPort<SettingsService>(ctx, 'settingsReadPort'), …)
+ * ```
+ *
+ * **Methods only.** The proxy forwards calls; it does not forward property
+ * reads, because a property read cannot be deferred — there is nothing to
+ * defer it to. A collaborator exposing data rather than behaviour is not a
+ * candidate for this, and should be read from the cradle explicitly where it
+ * is used.
+ *
+ * **And therefore: never feature-detect through one** (D-97.3). The `get` trap
+ * below answers *every* non-symbol property with a function, so `x.maybe`,
+ * `!x.maybe` and `typeof x.maybe === 'function'` are all truthy whatever is
+ * registered, and `x.maybe?.()` always calls — into a provider that may not
+ * implement it, where the forward throws "is not a function". This is not a
+ * sharp edge to be careful around, it is impossible by construction, and the
+ * trap **cannot be fixed** to answer honestly: making the property read tell
+ * the truth means resolving the name at access time to look at the real object,
+ * and for a gated port that turns a `typeof` probe into a `ModuleDisabledError`
+ * — a presence check that throws when the module is absent, which is worse than
+ * the hazard it repairs. Deferring resolution to the call is the whole reason
+ * this function exists (items 1 and 2 above).
+ *
+ * So the rule is at the type level instead: **no published port, and no
+ * interface extending one, may declare an optional method.** Optional
+ * parameters and optional data properties on record types are untouched. The
+ * one occurrence in the tree — `catalog` widening the custom-field read port
+ * with `publishInvalidate?` — fired its recovery branch on every integrity
+ * error and turned a self-healing cache window into a 500 on the attribute
+ * screens; D-97.1 replaced it with a required method that answers the
+ * consumer's actual question. `check:port-shape` refuses the shape.
+ */
+export declare function lazyPort<T extends object>(ctx: ModuleContext, name: string): T;
+//# sourceMappingURL=lazy-port.d.ts.map

package/dist/kernel/lazy-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-port.d.ts","sourceRoot":"","sources":["../../src/kernel/lazy-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAyB9E"}

package/dist/kernel/lazy-port.js

@@ -0,0 +1,78 @@
+/**
+ * A stand-in that resolves `name` from the container on **every method call**
+ * rather than once, when the holder is constructed.
+ *
+ * This exists because feature 072 kept producing the same two failures, and
+ * neither is visible at the call site or caught by `tsc`:
+ *
+ *  1. **Lifetime.** A name registered with `providePort` is a transient gate
+ *     that consults its module's effective state. Awilix's strict mode refuses
+ *     a singleton that captures one — correctly, because a captured gate goes
+ *     on answering after an operator switches the module off.
+ *  2. **Ordering.** A name a composition root registers does not exist yet when
+ *     a module composes — that is the whole shape of a composition since D-45:
+ *     `composeModules(MODULES, …)` runs first and every root contribution lands
+ *     after it. A capture taken during registration therefore captures nothing,
+ *     or, worse, captures the module's own default and never sees the root's
+ *     value. That happened twice.
+ *
+ * The rule `scripts/check-port-dependencies.ts` enforces is therefore blunt: a
+ * module may capture only names it owns and the handful of eagerly-registered
+ * kernel ones. Everything else goes through the cradle at the point of use, and
+ * this is the ergonomic way to spell that when a constructor wants an object
+ * rather than a getter.
+ *
+ * ```ts
+ * new GaConfigService(lazyPort<SettingsService>(ctx, 'settingsReadPort'), …)
+ * ```
+ *
+ * **Methods only.** The proxy forwards calls; it does not forward property
+ * reads, because a property read cannot be deferred — there is nothing to
+ * defer it to. A collaborator exposing data rather than behaviour is not a
+ * candidate for this, and should be read from the cradle explicitly where it
+ * is used.
+ *
+ * **And therefore: never feature-detect through one** (D-97.3). The `get` trap
+ * below answers *every* non-symbol property with a function, so `x.maybe`,
+ * `!x.maybe` and `typeof x.maybe === 'function'` are all truthy whatever is
+ * registered, and `x.maybe?.()` always calls — into a provider that may not
+ * implement it, where the forward throws "is not a function". This is not a
+ * sharp edge to be careful around, it is impossible by construction, and the
+ * trap **cannot be fixed** to answer honestly: making the property read tell
+ * the truth means resolving the name at access time to look at the real object,
+ * and for a gated port that turns a `typeof` probe into a `ModuleDisabledError`
+ * — a presence check that throws when the module is absent, which is worse than
+ * the hazard it repairs. Deferring resolution to the call is the whole reason
+ * this function exists (items 1 and 2 above).
+ *
+ * So the rule is at the type level instead: **no published port, and no
+ * interface extending one, may declare an optional method.** Optional
+ * parameters and optional data properties on record types are untouched. The
+ * one occurrence in the tree — `catalog` widening the custom-field read port
+ * with `publishInvalidate?` — fired its recovery branch on every integrity
+ * error and turned a self-healing cache window into a 500 on the attribute
+ * screens; D-97.1 replaced it with a required method that answers the
+ * consumer's actual question. `check:port-shape` refuses the shape.
+ */
+export function lazyPort(ctx, name) {
+    return new Proxy({}, {
+        get(_target, property) {
+            if (typeof property === 'symbol')
+                return undefined;
+            return (...args) => {
+                const resolved = ctx.cradle()[name];
+                if (resolved === undefined) {
+                    throw new Error(`[kernel] '${name}' is not registered in this composition — ` +
+                        `${ctx.module.id} resolved it lazily and found nothing.`);
+                }
+                const method = resolved[property];
+                if (typeof method !== 'function') {
+                    throw new Error(`[kernel] '${name}.${property}' is not a function — ` +
+                        `\`lazyPort\` forwards method calls only (see its note on property reads).`);
+                }
+                return method.apply(resolved, args);
+            };
+        },
+    });
+}
+//# sourceMappingURL=lazy-port.js.map

package/dist/kernel/lazy-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-port.js","sourceRoot":"","sources":["../../src/kernel/lazy-port.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,UAAU,QAAQ,CAAmB,GAAkB,EAAE,IAAY;IACzE,OAAO,IAAI,KAAK,CAAC,EAAO,EAAE;QACxB,GAAG,CAAC,OAAO,EAAE,QAAQ;YACnB,IAAI,OAAO,QAAQ,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAC;YACnD,OAAO,CAAC,GAAG,IAAe,EAAW,EAAE;gBACrC,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAA2B,CAAC,IAAI,CAE9C,CAAC;gBACd,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,4CAA4C;wBAC3D,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,wCAAwC,CAC3D,CAAC;gBACJ,CAAC;gBACD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBAClC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;oBACjC,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,IAAI,QAAQ,wBAAwB;wBACnD,2EAA2E,CAC9E,CAAC;gBACJ,CAAC;gBACD,OAAO,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACtC,CAAC,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/kernel/lifecycle/activation-resolver.d.ts

@@ -0,0 +1,63 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { ModuleManifest } from '@endora-commerce/contracts';
+/**
+ * Operator activation — the second presence axis (feature 073, Constitution
+ * XVII, research R-5).
+ *
+ * Platform availability answers "is this module installed and wired in this
+ * deployment?" and lives in `module_registrations`. This file answers "does
+ * this client want this capability?", which lives in an ordinary `Setting`
+ * row the module declares in its manifest.
+ *
+ * Two properties of this read are load-bearing:
+ *
+ *  - **It does not go through `SettingsService`.** Every read path there is
+ *    `async` behind a two-layer cache, while the hot-path gate must stay a
+ *    synchronous in-memory lookup (FR-004). Reading the rows keeps the
+ *    dependency on the settings *schema* — an edge the orchestrator already
+ *    has — rather than on the settings *service graph*, which is the edge
+ *    that would create a bootstrap cycle (FR-070).
+ *  - **It stops at two tiers.** Settings normally resolve per-channel
+ *    (`setting_values`) → `global_value` → `default_value`. Activation is
+ *    platform-wide (FR-009), so the per-channel tier is never joined;
+ *    including it would reintroduce channel dependence through the back door
+ *    (Constitution XII).
+ */
+/**
+ * A module's activation declaration, distilled from its manifest. Keeping it
+ * as plain data rather than passing manifests around means the registry cache
+ * — which lives on the hot path — never imports the manifest graph.
+ */
+export interface ModuleActivationDeclaration {
+    readonly moduleId: string;
+    /** `null` for a module that declared itself non-deactivatable. */
+    readonly settingCode: string | null;
+    /** Applies when the Setting row does not exist yet, or carries no override. */
+    readonly default: boolean;
+    /** Operator-facing reason; non-null exactly when `settingCode` is null. */
+    readonly nonDeactivatableReason: string | null;
+}
+/**
+ * Distil the activation declarations from a manifest list. A module that
+ * declares nothing is omitted: it owns no operator control, so only the
+ * platform axis governs it until its batch converts it.
+ */
+export declare function activationDeclarationsFrom(manifests: readonly ModuleManifest[]): ModuleActivationDeclaration[];
+/**
+ * Resolve each declared module's activation.
+ *
+ * One query, keyed by an explicit code list built from the declarations —
+ * never a `LIKE` scan, because `Setting.code`'s only index is its unique
+ * constraint and the adopted codes make the suffix non-uniform anyway.
+ *
+ * Fail-closed reading (FR-005): a value that is not a JSON boolean resolves
+ * to **off**, because `global_value` is jsonb and its `null` is ambiguous
+ * between "no override" and a literal JSON null. A missing row resolves to
+ * the manifest-declared default — an explicit state, not a fall-open.
+ *
+ * A non-deactivatable module resolves to `true` without being queried at all,
+ * which is what removes the recursion that would otherwise arise from gating
+ * `settings` on a value stored in `settings` (FR-071).
+ */
+export declare function resolveActivation(em: EntityManager, declarations: readonly ModuleActivationDeclaration[]): Promise<Map<string, boolean>>;
+//# sourceMappingURL=activation-resolver.d.ts.map

package/dist/kernel/lifecycle/activation-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-resolver.d.ts","sourceRoot":"","sources":["../../../src/kernel/lifecycle/activation-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,cAAc,EAAE,GACnC,2BAA2B,EAAE,CAsB/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,YAAY,EAAE,SAAS,2BAA2B,EAAE,GACnD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAuB/B"}

package/dist/kernel/lifecycle/activation-resolver.js

@@ -0,0 +1,70 @@
+import { Setting } from '../settings/setting.entity.js';
+/**
+ * Distil the activation declarations from a manifest list. A module that
+ * declares nothing is omitted: it owns no operator control, so only the
+ * platform axis governs it until its batch converts it.
+ */
+export function activationDeclarationsFrom(manifests) {
+    const declarations = [];
+    for (const manifest of manifests) {
+        const activation = manifest.activation;
+        if (!activation)
+            continue;
+        if ('nonDeactivatable' in activation) {
+            declarations.push({
+                moduleId: manifest.id,
+                settingCode: null,
+                default: true,
+                nonDeactivatableReason: activation.reason,
+            });
+            continue;
+        }
+        declarations.push({
+            moduleId: manifest.id,
+            settingCode: activation.settingCode,
+            default: activation.default,
+            nonDeactivatableReason: null,
+        });
+    }
+    return declarations;
+}
+/**
+ * Resolve each declared module's activation.
+ *
+ * One query, keyed by an explicit code list built from the declarations —
+ * never a `LIKE` scan, because `Setting.code`'s only index is its unique
+ * constraint and the adopted codes make the suffix non-uniform anyway.
+ *
+ * Fail-closed reading (FR-005): a value that is not a JSON boolean resolves
+ * to **off**, because `global_value` is jsonb and its `null` is ambiguous
+ * between "no override" and a literal JSON null. A missing row resolves to
+ * the manifest-declared default — an explicit state, not a fall-open.
+ *
+ * A non-deactivatable module resolves to `true` without being queried at all,
+ * which is what removes the recursion that would otherwise arise from gating
+ * `settings` on a value stored in `settings` (FR-071).
+ */
+export async function resolveActivation(em, declarations) {
+    const resolved = new Map();
+    const byCode = new Map();
+    for (const declaration of declarations) {
+        if (declaration.settingCode === null) {
+            resolved.set(declaration.moduleId, true);
+            continue;
+        }
+        byCode.set(declaration.settingCode, declaration);
+        resolved.set(declaration.moduleId, declaration.default);
+    }
+    if (byCode.size === 0)
+        return resolved;
+    const rows = await em.find(Setting, { code: { $in: [...byCode.keys()] } });
+    for (const row of rows) {
+        const declaration = byCode.get(row.code);
+        if (!declaration)
+            continue;
+        const value = row.globalValue ?? row.defaultValue;
+        resolved.set(declaration.moduleId, typeof value === 'boolean' ? value : false);
+    }
+    return resolved;
+}
+//# sourceMappingURL=activation-resolver.js.map

package/dist/kernel/lifecycle/activation-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-resolver.js","sourceRoot":"","sources":["../../../src/kernel/lifecycle/activation-resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAyCxD;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAAoC;IAEpC,MAAM,YAAY,GAAkC,EAAE,CAAC;IACvD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;QACvC,IAAI,CAAC,UAAU;YAAE,SAAS;QAC1B,IAAI,kBAAkB,IAAI,UAAU,EAAE,CAAC;YACrC,YAAY,CAAC,IAAI,CAAC;gBAChB,QAAQ,EAAE,QAAQ,CAAC,EAAE;gBACrB,WAAW,EAAE,IAAI;gBACjB,OAAO,EAAE,IAAI;gBACb,sBAAsB,EAAE,UAAU,CAAC,MAAM;aAC1C,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,YAAY,CAAC,IAAI,CAAC;YAChB,QAAQ,EAAE,QAAQ,CAAC,EAAE;YACrB,WAAW,EAAE,UAAU,CAAC,WAAW;YACnC,OAAO,EAAE,UAAU,CAAC,OAAO;YAC3B,sBAAsB,EAAE,IAAI;SAC7B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAiB,EACjB,YAAoD;IAEpD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuC,CAAC;IAE9D,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,IAAI,WAAW,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;YACrC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACzC,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACjD,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAEvC,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3E,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,WAAW;YAAE,SAAS;QAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,YAAY,CAAC;QAClD,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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

@@ -0,0 +1,145 @@
+import type { ModuleManifest } from '@endora-commerce/contracts';
+/**
+ * The derived capability registry — which modules declare membership of which
+ * named family, and which module owns each family it is mutually exclusive in
+ * (feature 132, `specs/132-connector-family-discovery/contracts/module-capabilities.md`,
+ * `data-model.md` §2).
+ *
+ * ## What it replaces
+ *
+ * Three hand-maintained arrays in `@endora-commerce/contracts` —
+ * `PIM_CONNECTOR_MODULES`, `INVOICE_LEDGER_MODULES`, `ERP_CONNECTOR_MODULES` —
+ * each of which is a copy of a fact the manifests already carry. The copy is
+ * D-100's shape and it had already gone wrong in both directions: two of the four
+ * shipped PIM connectors were not on the list, so exclusivity covered 2 of the 12
+ * ordered pairs; and an **overlay** module had to be written into a core contracts
+ * file to join its family, which is Principle XV failing in the only way it can
+ * fail quietly — the overlay was written correctly and the core edit was made
+ * anyway, because there was no other way in.
+ *
+ * The rule this is an instance of is the one `requiredModulesFrom`'s header
+ * states: derive it on every composition, so a member who joins or withdraws
+ * changes the answer in the same run, with no list to edit.
+ *
+ * ## Why it is a parameter and not an import
+ *
+ * **The platform may not import a module** (D-52/D-53). So the manifests arrive
+ * as an argument, exactly as they do for `activationDeclarationsFrom` and
+ * `requiredModulesFrom`, and the population is whatever the composition root
+ * resolved: core modules, this deployment's overlay modules, and every installed
+ * Endora module package. That is the whole reason the field exists — a connector
+ * living outside this repository can declare membership, and no file in this
+ * repository names it.
+ *
+ * ## Why it is plain data
+ *
+ * Same reason `ModuleActivationDeclaration` is: it is installed into the registry
+ * cache, which is on the hot path, and that cache must never import the manifest
+ * graph.
+ */
+/** One module's capability declarations, distilled from its manifest. */
+export interface ModuleCapabilityDeclaration {
+    readonly moduleId: string;
+    readonly capabilities: readonly string[];
+}
+/** One exclusive capability, and who owns it. */
+export interface ExclusiveCapabilityDeclaration {
+    readonly key: string;
+    readonly ownerModuleId: string;
+    readonly errorCode: string;
+}
+export interface CapabilityRegistry {
+    readonly declarations: readonly ModuleCapabilityDeclaration[];
+    readonly exclusive: readonly ExclusiveCapabilityDeclaration[];
+}
+/** One key claimed by more than one installed module. */
+export interface ContestedCapabilityFinding {
+    readonly key: string;
+    readonly ownerModuleIds: readonly string[];
+}
+/**
+ * Two modules claim to own one capability (R3.4).
+ *
+ * A distinct error type, per D-101's closing rule about the refusals that share a
+ * manifest declaration and share nothing else: this refuses a **deployment that
+ * was assembled wrong**, from the manifests, before the first module registers —
+ * not a transition an operator asked for, and not something to answer with an
+ * HTTP envelope.
+ *
+ * It fails closed rather than picking a claimant, because a contested capability
+ * routes to neither: the refusal code, the lock row and the admin page all belong
+ * to "the owner", and with two of them every one of those three answers is
+ * arbitrary. `check:error-translations` reaches the same verdict about a code with
+ * two declarers, and for the same reason.
+ */
+export declare class ContestedCapabilityError extends Error {
+    readonly findings: readonly ContestedCapabilityFinding[];
+    constructor(findings: readonly ContestedCapabilityFinding[]);
+}
+/** One member of an exclusive key that ships activated. */
+export interface DefaultActivatedMemberFinding {
+    readonly moduleId: string;
+    readonly key: string;
+    /** The activation control whose declared default is the problem. */
+    readonly settingCode: string;
+}
+/**
+ * A member of an **exclusive** capability declares `activation.default: true`
+ * (R3.6, spec FR-016).
+ *
+ * ## Why this is a refusal and not a runtime tolerance
+ *
+ * `resolveActivation` returns `Map<string, boolean>` and carries **no provenance**:
+ * nothing downstream can tell "the operator wrote this row" from "no row exists and
+ * the manifest said `true`". So a mutual exclusion resolved on the activation axis
+ * cannot ask the question it needs to ask, and a default-activated member holds a
+ * claim nobody made — which is what an operator meets as a refusal naming a
+ * connector they never configured.
+ *
+ * The tempting repair is to add provenance and have the exclusion require an
+ * **explicit** choice. It is unsafe, and `research.md` D6 records why: member `A`
+ * default-activated and member `B` explicitly activated would then **both** be
+ * active, because the test that was supposed to refuse `B` now ignores `A`. A mutual
+ * exclusion may not fail open. Refusing the manifest makes the state unreachable
+ * rather than tolerated, which is the difference between a guard and a repair.
+ *
+ * ## Why it is weaker-looking than the defect it prevents, and is not
+ *
+ * The exclusion is a `pre` interceptor on the activation route, so it guards the
+ * **transition** and not the **existing state**: two default-activated members are
+ * both present from the first boot and no transition ever happens to be refused.
+ * Nothing surfaces it. That is not a hypothetical — it was measured on a freshly
+ * migrated database, three connectors deep, before this refusal existed.
+ *
+ * ## Why not `defineModuleManifest`
+ *
+ * Same reason {@link ContestedCapabilityError} is not there: that function sees one
+ * manifest and cannot see whether the key is **exclusive**, which is the owner's
+ * declaration. Both facts are in hand only here. `check:port-dependencies` carries
+ * the same assertion as an earlier instrument for this repository's own modules
+ * (R3.7); the two layers cover what the other cannot — the check sees a member merged
+ * here before anybody boots, and this sees a connector installed from npm, which no
+ * check in this repository walks.
+ */
+export declare class DefaultActivatedMemberError extends Error {
+    readonly findings: readonly DefaultActivatedMemberFinding[];
+    constructor(findings: readonly DefaultActivatedMemberFinding[]);
+}
+/**
+ * Distil the capability registry from a manifest list.
+ *
+ * A module that declares nothing is omitted, and so is one whose `capabilities`
+ * is present but empty: an empty array says nothing a missing field does not, and
+ * carrying it would put a member with no family into every family read.
+ *
+ * **A member of a key that no installed module owns is not an error** (R3.5). The
+ * capability is simply not exclusive in that deployment and the member works.
+ * Refusing would turn a shared layer into an undeclared hard dependency, which is
+ * what `dependencies` is for and which the member already declares if it genuinely
+ * needs it.
+ *
+ * Order is manifest order, deliberately: every message derived from this reads in
+ * the order the deployment composes, which is the order the author is looking at.
+ */
+export declare function capabilityRegistryFrom(manifests: readonly ModuleManifest[]): CapabilityRegistry;
+//# sourceMappingURL=capability-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/lifecycle/capability-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,yEAAyE;AACzE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,iDAAiD;AACjD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC9D,QAAQ,CAAC,SAAS,EAAE,SAAS,8BAA8B,EAAE,CAAC;CAC/D;AAED,yDAAyD;AACzD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;gBAE7C,QAAQ,EAAE,SAAS,0BAA0B,EAAE;CAK5D;AAwBD,2DAA2D;AAC3D,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,6BAA6B,EAAE,CAAC;gBAEhD,QAAQ,EAAE,SAAS,6BAA6B,EAAE;CAK/D;AAiCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,SAAS,cAAc,EAAE,GACnC,kBAAkB,CAwDpB"}