@endora-commerce/contracts 0.100.0

package/dist/modules.d.ts

@@ -0,0 +1,1706 @@
+import { z } from 'zod';
+import { type ModuleSettingsManifest } from './settings.js';
+/**
+ * Module identifier — must equal the manifest file's parent folder name.
+ * Two-character ids are allowed (e.g. `_lifecycle` after underscore allowance).
+ * Underscore-prefixed ids are reserved for platform-internal modules
+ * (constitutional exemption alongside `auth` and `example`).
+ */
+export declare const moduleIdRe: RegExp;
+/** Semver-lite — `MAJOR.MINOR.PATCH` plus an optional `-prerelease` suffix. */
+export declare const moduleVersionRe: RegExp;
+/**
+ * Per-module Admin UI translation declaration (feature 019).
+ * When present, the lifecycle install hook reads
+ * `<modulePath>/<bundlesDir>/<lang>.json` for every supported Admin UI
+ * language and registers the bundle into `translation_bundles`. Default
+ * `bundlesDir` is `'i18n'` — every module that ships translations is
+ * expected to follow this convention.
+ */
+export declare const ModuleI18nManifestSchema: z.ZodObject<{
+    bundlesDir: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type ModuleI18nManifest = z.infer<typeof ModuleI18nManifestSchema>;
+/**
+ * Per-module documentation declaration (feature 100 / roadmap F12).
+ *
+ * The same shape as {@link ModuleI18nManifestSchema} and for the same reason: a
+ * directory at the **package root**, in the package's `files` list, with no
+ * `exports` subpath, located by joining `dir` to `dirname(manifestPath)`. The
+ * anchor is the platform's, so nothing in the module names a package, a
+ * repository root or a build directory in order to find its own pages
+ * (`specs/100-module-owned-documentation/contracts/module-documentation-layer.md`
+ * R2.1–R2.3).
+ *
+ * A declared directory that is not on disk is a **refusal**, naming the module —
+ * never "this module ships no documentation". That distinction is the whole of
+ * the repair `backend/src/manifest-locations.ts` was written for: the `_i18n`
+ * boot reconciler logs and skips an absent bundles directory, so a packaged
+ * module rendered every palette entry as a raw key with no error anywhere.
+ */
+export declare const ModuleDocsManifestSchema: z.ZodObject<{
+    dir: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type ModuleDocsManifest = z.infer<typeof ModuleDocsManifestSchema>;
+/**
+ * `docs: false` — this module ships no documentation, deliberately.
+ *
+ * **Absent and `false` are not the same state**, and the documentation check
+ * distinguishes them: absent is a module nobody has decided about, `false` is a
+ * decision. The argument is `check:bundle-pairing`'s, one population over — a
+ * universal obligation over a population where some members legitimately owe
+ * nothing is repaired by empty files whose only effect is to make a check pass.
+ * Some modules are infrastructure other modules consume and may honestly
+ * document nothing.
+ */
+export declare const ModuleDocsDeclarationSchema: z.ZodUnion<readonly [z.ZodObject<{
+    dir: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodLiteral<false>]>;
+export type ModuleDocsDeclaration = z.infer<typeof ModuleDocsDeclarationSchema>;
+/**
+ * What a module's demo body is handed.
+ *
+ * One field, deliberately. The body gets its module's own composed
+ * `ModuleContext` and nothing else: everything it wants an operator to read
+ * comes back in {@link DemoSeedResult}, which the runner formats once (§3.7),
+ * so there is no `out`/`err` pair here and a body must not reach for
+ * `process.stdout`. That is the difference from {@link ModuleCliCommandContext},
+ * which injects both because a command's output *is* its result.
+ *
+ * `Ctx` is a type parameter for the reason {@link ModuleCliCommand}'s is: a
+ * module names `ModuleContext` from `@endora-commerce/platform/kernel`, and the
+ * contracts package may not. A declaration reaching the host is typed
+ * `ModuleDemoManifest<never>` — the schema's inference — and every module's
+ * `ModuleDemoManifest<ModuleContext>` is assignable to it, so the host casts
+ * once at the invocation, exactly as `collectModuleCommands` does.
+ */
+export interface ModuleDemoContext<Ctx = unknown> {
+    /** The module's own composed `ModuleContext`. */
+    ctx: Ctx;
+}
+/**
+ * One line of a module's per-module accounting.
+ *
+ * `entity` is the class name the module wrote, in the module's own words; the
+ * runner neither derives nor validates it. Structured rather than free text
+ * because it is the only way SC-007's idempotence is assertable without
+ * diffing a database: seeding twice must report the same counts.
+ */
+export interface DemoEntityCount {
+    readonly entity: string;
+    readonly count: number;
+}
+/**
+ * A sign-in detail the demo created, printed by the runner at the end of a run.
+ *
+ * Structured rather than a sentence in `notes` so the runner formats it once
+ * and a client's scaffolded composition does not have to know how the platform
+ * lays credentials out.
+ */
+export interface DemoCredential {
+    readonly label: string;
+    readonly value: string;
+}
+/** What a module's `seed` reports. Never a throw-or-succeed (§3.7). */
+export interface DemoSeedResult {
+    readonly created: readonly DemoEntityCount[];
+    readonly credentials?: readonly DemoCredential[];
+    /** What this module chose not to do, and why. */
+    readonly notes?: readonly string[];
+}
+/** What a module's `reset` reports. */
+export interface DemoResetResult {
+    readonly removed: readonly DemoEntityCount[];
+    readonly notes?: readonly string[];
+}
+/**
+ * The demo declaration a module carries in its `manifest.ts` (§1.3).
+ *
+ * ## The body is reached by a relative `await import()`, never a top-level one
+ *
+ * §1.4, and it is `cliCommands`' rule for `cliCommands`' reason: a manifest is
+ * loaded by every process that composes the platform — and by the check scripts
+ * and `src/db/configured-migrations.ts`, which import the generated index — so a
+ * demo body imported at the top of `manifest.ts` is a service graph pulled into
+ * all of them. Write it as
+ *
+ * ```ts
+ * const demo: ModuleDemoManifest<ModuleContext> = {
+ *   summary: 'A demo warehouse and stock for the seeded products.',
+ *   seed: async (context) => (await import('./backend/demo/seed.js')).seedDemo(context),
+ *   reset: async (context) => (await import('./backend/demo/reset.js')).resetDemo(context),
+ * };
+ * ```
+ *
+ * and pass it to `defineModuleManifest`. The typed `const` is what gives the
+ * author `context.ctx: ModuleContext`; declared inline the parameter infers
+ * from the schema and is `never`.
+ *
+ * A relative import inside the package lands in `dist` through the existing
+ * emit, so this declaration needs **no `exports` subpath, no `files` entry and
+ * no change to the manifest generator** (§1.5).
+ *
+ * ## What a body may do
+ *
+ * §2.1–§2.2: write only tables its own module owns, read no other module's
+ * table, resolve no other module's port, import from no other module's package.
+ * Wiring that spans modules is a composition and belongs to the instance
+ * (§5, D-209) — `megamenu`'s demo menu mirroring `catalog`'s demo categories is
+ * the measured case, and `megamenu` does not declare `catalog`.
+ */
+export interface ModuleDemoManifest<Ctx = unknown> {
+    /**
+     * One line of English prose: what this module contributes to the demo. The
+     * runner prints it per module (§3.7).
+     */
+    summary: string;
+    /** Create this module's demo rows. Idempotent by contract (§2.4). */
+    seed(context: ModuleDemoContext<Ctx>): Promise<DemoSeedResult>;
+    /**
+     * Withdraw exactly what {@link ModuleDemoManifest.seed} created, and nothing
+     * an operator created (§2.5).
+     *
+     * Separate from `seed` rather than a flag on it, because FR-007's guarantee
+     * is per module and a flag makes one function answer two questions.
+     */
+    reset(context: ModuleDemoContext<Ctx>): Promise<DemoResetResult>;
+    /**
+     * Module ids this module's demo prefers to run after — **advisory** (§4.3).
+     *
+     * `permissions[].requires`' shape under D-175, chosen for the same reason:
+     * the field carries a coupling the dependency graph cannot express and the
+     * graph must not be widened to express it. Nothing else reads it, it puts no
+     * module in `dependencies`, it creates no lifecycle edge, it does not stand
+     * in the way of an operator switching the named module off, and it changes no
+     * migration order. An entry naming a module that is not installed orders
+     * nothing and is not a finding (§4.4).
+     *
+     * It is deliberately not spelled `dependsOn`, `requires` or `dependencies`:
+     * the name has to be unmistakably not the lifecycle one.
+     */
+    after?: readonly string[] | undefined;
+    /**
+     * The package this module's demo data lives in — **the escape hatch** (§6,
+     * D-5), and a package **name as a string**, never an `import` specifier.
+     *
+     * ## Why a string, and it is measured rather than stylistic
+     *
+     * A module package's `package.json` is generated
+     * (`backend/scripts/lib/module-package-manifest.ts`), and `peerNamesOf`
+     * records every specifier `namedSpecifiers` yields **with no filter on kind**
+     * — a walk that recognises `dynamic-import`
+     * (`packages/cli/src/lib/specifiers.ts`, `callee.kind ===
+     * ts.SyntaxKind.ImportKeyword`). So a literal
+     * `await import('@endora-commerce/mod-<id>-demo')` written anywhere in the
+     * module's sources is emitted as a **required** peer, and pnpm then installs
+     * the demo package for every client — the exact opposite of what this field
+     * is for. Both halves re-verified against those two files on 2026-09-09.
+     *
+     * The name is therefore resolved by the **runner**, whose resolution the
+     * specifier walk does not read. It is the same reason `cliCommands` keeps its
+     * body behind a relative `await import()` rather than a top-level one.
+     *
+     * ## What a runner owes it
+     *
+     * §6.3 requires three answers and forbids collapsing the second into the
+     * third: *resolvable and loads* — this module's demo data is the package's;
+     * *not resolvable* — reported by name as **not installed**, the module
+     * contributes nothing and the run continues; *resolvable and fails to load* —
+     * a failure, per §3.8. §6.4 requires the probe to happen **before** the
+     * import, because a bare `catch` around both turns a broken demo package into
+     * a silent "not installed", which is the fail-open shape
+     * `check:port-catches` refuses one seam over.
+     *
+     * `packages/platform/src/demo/{packages,runner}.ts` answer all three
+     * (feature 113, T235). The probe is `require.resolve`, which does not
+     * evaluate; the import is a separate call, in the one `try` whose `catch`
+     * re-throws unconditionally as `DemoRunFailedError`.
+     *
+     * ## What the package owes back
+     *
+     * It exports **`demo`**: an object with a `summary` string and `seed` and
+     * `reset` functions — the shape declared here, minus the two fields that stay
+     * the module's. When it loads it *replaces* this declaration's `summary`,
+     * `seed` and `reset`, which it must, because §6.2 bars the module's own
+     * sources from naming the package at all and a declared body therefore could
+     * not reach the data. `after` is **not** read from the package: ordering is
+     * decided from the declarations before anything is loaded, so a package's own
+     * would arrive after the sequence it wants to change.
+     */
+    package?: string | undefined;
+}
+export declare const ModuleDemoManifestSchema: z.ZodObject<{
+    summary: z.ZodString;
+    seed: z.ZodType<(context: ModuleDemoContext<never>) => Promise<DemoSeedResult>, unknown, z.core.$ZodTypeInternals<(context: ModuleDemoContext<never>) => Promise<DemoSeedResult>, unknown>>;
+    reset: z.ZodType<(context: ModuleDemoContext<never>) => Promise<DemoResetResult>, unknown, z.core.$ZodTypeInternals<(context: ModuleDemoContext<never>) => Promise<DemoResetResult>, unknown>>;
+    after: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    package: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * `demo: false` — this module has nothing to demonstrate, deliberately.
+ *
+ * **Absent and `false` are not the same state** (§1.2). It is
+ * {@link ModuleDocsDeclarationSchema}'s rule and it exists for the same reason:
+ * a universal obligation over a population where some members legitimately owe
+ * nothing is repaired by empty files whose only effect is to make a check pass.
+ * `pim_connector` and `email` genuinely have nothing to show.
+ */
+export declare const ModuleDemoDeclarationSchema: z.ZodUnion<readonly [z.ZodObject<{
+    summary: z.ZodString;
+    seed: z.ZodType<(context: ModuleDemoContext<never>) => Promise<DemoSeedResult>, unknown, z.core.$ZodTypeInternals<(context: ModuleDemoContext<never>) => Promise<DemoSeedResult>, unknown>>;
+    reset: z.ZodType<(context: ModuleDemoContext<never>) => Promise<DemoResetResult>, unknown, z.core.$ZodTypeInternals<(context: ModuleDemoContext<never>) => Promise<DemoResetResult>, unknown>>;
+    after: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    package: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodLiteral<false>]>;
+export type ModuleDemoDeclaration = z.infer<typeof ModuleDemoDeclarationSchema>;
+/**
+ * Operator-activation declaration — feature 073, Constitution XVII.
+ *
+ * The second of the two orthogonal presence axes. Platform availability lives
+ * in `module_registrations` and is owned by whoever operates the deployment;
+ * this block declares the *business* operator's control, which is an ordinary
+ * `Setting` row reconciled from the manifest.
+ *
+ * It used to sit beside a `license` tier, and the two were kept apart because
+ * conflating a build-time entitlement with a runtime toggle would make an
+ * operator's switch look like a licensing decision. That tier is gone (D-194
+ * removed the edition meta-packages it existed for), so activation is now the
+ * only presence declaration a manifest carries.
+ *
+ * Exactly one of the two forms is valid — enforced in `defineModuleManifest`
+ * rather than by the schema, because a Zod union of two non-strict objects
+ * accepts a value carrying both.
+ */
+export declare const ModuleActivationSchema: z.ZodUnion<readonly [z.ZodObject<{
+    settingCode: z.ZodString;
+    default: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    nonDeactivatable: z.ZodLiteral<true>;
+    reason: z.ZodString;
+}, z.core.$strip>]>;
+export type ModuleActivation = z.infer<typeof ModuleActivationSchema>;
+/**
+ * A runtime dependency the declaring module deliberately keeps out of
+ * `dependencies` — feature 073, Amendment A1.
+ *
+ * The two are not two spellings of one thing. `dependencies` is read by the
+ * **topological install order** (`db/migration-order.ts`, the lifecycle's
+ * `ModuleDepGraph`), and a mutual pair declared there closes a cycle that fails
+ * the build: `addresses` must install after `organizations` because every
+ * stored address is organization-scoped, so `organizations` cannot also declare
+ * `addresses`, however real the port edge is. Withholding the declaration used
+ * to make the edge invisible to everything else too — the flip-time refusals
+ * saw no reason to stop an operator switching the owner off underneath a live
+ * resolver.
+ *
+ * So the edge is declared here instead: **read by the gating and refusal
+ * graph, ignored by the install order.** That is the whole trade, stated in the
+ * manifest that makes it rather than in a build script's constant, so a
+ * refusal and a CI check cannot drift apart on which edges exist.
+ */
+export declare const ModuleAcknowledgedDependencySchema: z.ZodObject<{
+    moduleId: z.ZodString;
+    port: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type ModuleAcknowledgedDependency = z.infer<typeof ModuleAcknowledgedDependencySchema>;
+/**
+ * An edge that is real to the container but does not bind the operator — D-44.
+ *
+ * `dependencies` is read as three claims at once: install-and-migration order,
+ * "the container resolution is declared", and "an operator may not switch the
+ * owner off underneath me". `acknowledgedDependencies` withdraws the first.
+ * This withdraws the third, and only the third: a module declares here that it
+ * reads a name `moduleId` owns and that it has a defined behaviour when
+ * `moduleId` is not there, so the flip-time refusal has nothing to protect.
+ *
+ * Read by `check-port-dependencies.ts`, which needs the ownership claim and
+ * nothing else, and — when the deactivation-consequence dialog ships — by
+ * `/platform/modules`, which renders {@link whenAbsent}. Read by **nothing
+ * else**: not `ModuleDepGraph`, not `db/migration-order.ts`, and not
+ * `ModuleGatingGraph` in either direction. A cross-module foreign key therefore
+ * still forces a `dependencies` entry, and `fk-dependency-drift.test.ts` still
+ * fails for one declared here instead.
+ *
+ * The three kinds are the three ways an edge can exist without the bind bit:
+ *
+ *  - **`contributes-to`** — the declaring module pushes an inert descriptor
+ *    into `moduleId`'s ungated registry at boot. It has no failure mode in
+ *    either direction: an absent contributor's descriptor is filtered by the
+ *    host at enumeration, and an absent host's registry is a table nobody
+ *    walks. `whenAbsent` is forbidden, because nothing degrades.
+ *  - **`degrades-without`** — the declaring module reads an answer from
+ *    `moduleId`, checks presence before it does, and keeps working with less.
+ *    `whenAbsent` is required and states that behaviour, which is what an
+ *    off-state test for the edge is held to.
+ *  - **`refuses-without`** — the declaring module reads a **gated port**, has
+ *    no fallback for it, and lets the 503 `MODULE_DISABLED` refusal reach the
+ *    caller. The operation stops; the rest of the declaring module keeps
+ *    working; the owner's activation control keeps working. `whenAbsent` is
+ *    required and names **what** refuses, because that is the whole payload:
+ *    the deactivation-consequence ledger classifies the edge `fails-closed`
+ *    and the operator's confirmation dialog renders this sentence.
+ *
+ * The third kind was an omission rather than a narrowing, and it is worth
+ * saying why, because the gap is invisible from the manifest side. A read with
+ * no fallback had only one spelling — `dependencies` (or
+ * `acknowledgedDependencies`) — and both carry the bind, so a dependent that
+ * cannot itself be switched off turned the *owner's* activation control into a
+ * dead switch: the operator flips it, the flip-time refusal names a module
+ * that will never go away, and nothing happens. That is a worse answer than
+ * either alternative, since a control that lies is not a control. So the
+ * missing spelling is "refuse, and do not bind", which is what this kind is;
+ * the outcome it produces (`fails-closed`) has been in the ledger's vocabulary
+ * since feature 074 and was reachable only for edges that also bound.
+ *
+ * **The half of the claim about the owner's control is already unspellable**,
+ * and it is worth knowing where: rule 2 of `assertNonBindingRules` refuses any
+ * non-binding edge whose target the same manifest also names in
+ * `dependencies` or `acknowledgedDependencies` — one edge, one claim, in one
+ * place. So a `refuses-without` entry cannot sit beside the bind it denies;
+ * a module that wants both is telling the operator two things at once and is
+ * refused before the ledger ever sees it. `check-port-dependencies.ts` re-
+ * derives the same fact from the manifests as a second net, for a manifest
+ * built without this helper.
+ *
+ * The other two halves are the check's alone, because both are properties of
+ * the *tree* rather than of the manifest: the name is registered with
+ * `di.providePort` (an ungated registration has no refusal to propagate), and
+ * the resolution happens at call time (a gated port resolved at boot stops the
+ * next start rather than one request — the ledger's
+ * `gated-port-before-first-request`, which is assigned before any declaration
+ * is consulted and which no entry can therefore rescue).
+ *
+ * The fourth quadrant — order without bind — stays deliberately unspellable
+ * (Constitution IV). An edge that needs both goes back to `dependencies`, and
+ * the bind comes back with it.
+ */
+export declare const ModuleNonBindingDependencySchema: z.ZodObject<{
+    moduleId: z.ZodString;
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        "contributes-to": "contributes-to";
+        "degrades-without": "degrades-without";
+        "refuses-without": "refuses-without";
+    }>;
+    whenAbsent: z.ZodOptional<z.ZodString>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type ModuleNonBindingDependency = z.infer<typeof ModuleNonBindingDependencySchema>;
+/**
+ * One module a deployment knowingly does not ship — D-101's declared escape.
+ *
+ * A deployment may compose fewer modules than its manifests declare; what it may
+ * not do is arrive there silently, so the omission is declared in a committed,
+ * reviewed file (`backend/src/apps/<deployment>/divergence.ts`) and the boot
+ * refuses an omission that is not in it — or an entry for a module the
+ * deployment does ship, which is the same ledger read the other way.
+ *
+ * This is `ReducedDeploymentDeclaration` under its own name (D-205), and it is
+ * unchanged in substance: a module id, and a reason long enough to be an
+ * argument. What changed is where it sits — inside
+ * {@link DeploymentDivergenceDeclarationSchema}'s `omittedModules`, beside the
+ * other two things a deployment declares about itself.
+ */
+export declare const OmittedModuleSchema: z.ZodObject<{
+    moduleId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type OmittedModule = z.infer<typeof OmittedModuleSchema>;
+/**
+ * Everything a deployment declares about how it means to differ from core.
+ *
+ * `backend/src/apps/<deployment>/divergence.ts`, exporting `divergence`. The
+ * file was `reduced-deployment.ts` until it grew past omissions (D-205):
+ * *reduced* encodes a direction that is wrong for an addition, wrong for a
+ * substitution and wrong for an ordering, while `divergence` is already the
+ * word the generator's own header uses for the derived artefact beside it.
+ *
+ * The shape lives here rather than in `_lifecycle` because the file carrying it
+ * belongs to a **deployment**, and a deployment naming a module's internals is
+ * the coupling that outlives the module.
+ *
+ * **It holds judgement, ordering and prose — never population.** The single test
+ * for a field is whether the platform can derive it: the deployment's module
+ * list is the overlay walk's answer and the divergences themselves are the
+ * report's, so neither belongs here
+ * (`specs/107-override-report-and-ladder/contracts/deployment-declaration.md` §5).
+ *
+ * Every field defaults to empty, so a declaration that leaves one out means
+ * "none of these" rather than "unparseable" — the reading an absent file already
+ * gets. A deployment that diverges by nothing still ships the file with all
+ * three written out, because the mechanism is easier to find than to remember.
+ */
+export declare const DeploymentDivergenceDeclarationSchema: z.ZodObject<{
+    omittedModules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        moduleId: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    decorationOrder: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    reasons: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type DeploymentDivergenceDeclaration = z.infer<typeof DeploymentDivergenceDeclarationSchema>;
+/**
+ * One kind of divergence a deployment's tree can hold
+ * (`specs/107-override-report-and-ladder/data-model.md` §2.3).
+ *
+ * Nine, and every one of them is one seam of `ModuleContext` — seven read off
+ * the members themselves, plus `port-consumed` (which is `lazyPort` over the
+ * cradle rather than a member) and `omission` (which comes from the declaration
+ * and from no seam at all). `routes`, `ungatedRoutes`, `onBoot` and the manifest
+ * declarations are deliberately absent for one uniform reason: each is a module
+ * acting on its **own** surface, which is not a divergence from core. They are
+ * named in {@link DivergenceBoundary.notRecorded} so a reader can tell "not a
+ * divergence" from "not looked at".
+ */
+export type DivergenceKind = 'omission' | 'registration' | 'port-provided' | 'port-consumed' | 'subscription' | 'interceptor' | 'decoration' | 'root-plugin' | 'worker';
+/**
+ * `<kind>:<module>:<subject>` — the three facts that identify a divergence
+ * independently of where it is written.
+ *
+ * **Never a file path and never a line.** A path-keyed ledger goes stale on
+ * every move and a line-keyed one reds on any insertion above the site; the
+ * subject is the string the platform itself uses to identify the thing — a
+ * registration name, an endpoint identity, a module id. An interceptor's key
+ * carries `#<phase>`, because one module may register a `pre` and a `post`
+ * against one endpoint and they are two divergences with two reasons.
+ */
+export type DivergenceKey = string;
+/** Kind-specific facts, and only the ones the derivation actually has. */
+export type DivergenceDetail = {
+    readonly kind: 'decoration';
+    /**
+     * 1-based position in the wrapping chain, innermost first — and `null` in
+     * the committed artefact, deliberately rather than by omission.
+     *
+     * **Depth is a fact about a composition, not about a tree.** A static walk
+     * knows that two overlay modules decorate one name; it does not know which
+     * wrapped which, because that is what `decorationOrder` and the composer's
+     * emission order decide together. The runtime half of the report
+     * (`contracts/divergence-report.md` §7) fills it in from
+     * `ComposedModules.decorations`; recording a guess here would be the
+     * report asserting something it cannot know.
+     */
+    readonly depth: number | null;
+} | {
+    readonly kind: 'interceptor';
+    readonly phase: 'pre' | 'post';
+    readonly order: number;
+    readonly id: string;
+    /** Does any route registration in the composition match this identity? */
+    readonly targetMatched: boolean;
+} | {
+    readonly kind: 'subscription';
+} | {
+    readonly kind: 'port-provided';
+} | {
+    readonly kind: 'port-consumed';
+} | {
+    readonly kind: 'registration';
+} | {
+    readonly kind: 'worker';
+} | {
+    readonly kind: 'root-plugin';
+    readonly declaredReason: string;
+} | {
+    readonly kind: 'omission';
+};
+/** One divergence: what, who wrote it, who owns it, at what cost, and why. */
+export interface DivergenceEntry {
+    readonly key: DivergenceKey;
+    readonly kind: DivergenceKind;
+    /** The overlay module that wrote it; `'core'` for an omission. */
+    readonly module: string;
+    /** Registration name, endpoint identity, event name, queue name, module id. */
+    readonly subject: string;
+    /**
+     * The module that owns `subject`; `null` when a composition root registered
+     * it. A name nobody registers is a **finding**, not an entry, so `null` here
+     * always means "root-supplied" and never "unknown".
+     */
+    readonly owner: string | null;
+    /**
+     * Which rung of the escalation ladder this seam is
+     * (`specs/107-override-report-and-ladder/contracts/escalation-ladder.md` §2),
+     * or `null` for a kind that sits on no rung.
+     *
+     * `null` is three kinds and they are the three the ladder's own table marks
+     * `—`: `registration` and `worker` are a module contributing its **own**
+     * surface, and `omission` comes from the declaration rather than from a seam.
+     * The ladder ranks ways of changing what *core* does, so a rung number on
+     * those would be a cost this repository does not claim they have. A
+     * `ModuleContext` member that the rung table classifies **not at all** is a
+     * different state and is the `unclassified-seam` finding.
+     */
+    readonly rung: number | null;
+    /** Kind-specific facts. Never free-form. */
+    readonly detail: DivergenceDetail;
+    /** The deployment's own sentence, from its declaration's `reasons` map. */
+    readonly reason: string;
+}
+/**
+ * What the artefact does not cover, stated rather than implied (FR-018).
+ *
+ * A report that lists nine seams and says nothing about the rest is
+ * indistinguishable from a complete one. This is the difference between a
+ * boundary statement and a silence, and it is why the two hand-written lists
+ * below are hand-written: they carry a *reason* each, which no walk can produce.
+ */
+export interface DivergenceBoundary {
+    /** Seams this artefact records. Derived — the kinds above. */
+    readonly recorded: readonly DivergenceKind[];
+    /** Seams that exist and are a module's own business, with why. */
+    readonly notRecorded: ReadonlyArray<{
+        readonly seam: string;
+        readonly why: string;
+    }>;
+    /** Facts only a running process can answer, with why. */
+    readonly runtimeOnly: ReadonlyArray<{
+        readonly fact: string;
+        readonly why: string;
+    }>;
+}
+/**
+ * The derived record of how one deployment's tree diverges from core (D-30).
+ *
+ * Committed, per deployment, in two renderings from one derivation: a `.ts` a
+ * program reads and a `.md` a human reads. Deterministic — repo-relative paths,
+ * sorted arrays, no timestamps — so identical inputs produce byte-identical
+ * output and `overlay:check` can byte-compare both.
+ *
+ * The shape is published here rather than in `backend/src/overlay/` for the
+ * reason {@link DeploymentDivergenceDeclarationSchema} is: it is a deployment's
+ * artefact, and the runtime half of the report
+ * (`specs/107-override-report-and-ladder/contracts/divergence-report.md` §7)
+ * shares it. No Zod schema, deliberately: nothing parses this at a boundary —
+ * it is generated by one program and byte-compared by another, both of which
+ * have the type.
+ */
+export interface DivergenceReport {
+    /** Deployment name, or `'core'` for the bare-core build. */
+    readonly deployment: string;
+    /**
+     * The overlay root read, repo-relative; `null` for bare core.
+     *
+     * Still an object rather than a bare `overlayRoot`, for v2's stated reason: a
+     * deployment build has one input path and recording it is what makes the
+     * artefact reproducible.
+     */
+    readonly generatedFrom: {
+        readonly overlayRoot: string | null;
+    };
+    /**
+     * Overlay-only module ids this deployment adds, sorted. (v2's `newModules`.)
+     *
+     * A field of its own rather than entries of kind `overlay-module`, because an
+     * overlay module is the *container* of the other divergences rather than one
+     * of them — and every entry names the overlay module it came from anyway.
+     */
+    readonly overlayModules: readonly string[];
+    /** Every divergence found, sorted by key. */
+    readonly entries: readonly DivergenceEntry[];
+    /** What this artefact does not cover, stated rather than implied. FR-018. */
+    readonly boundary: DivergenceBoundary;
+}
+/**
+ * Refusal-token grammar for {@link ModuleErrorCodeDeclarationSchema}.
+ *
+ * One code, several reasons — `specs/082-error-code-ownership/contracts/error-code-ownership.md`
+ * §1.4. The envelope reads `details.code` and looks up `errors.<CODE>.<token>`,
+ * or `errors.<CODE>` when the raise carries no token.
+ *
+ * **It is a choice between two keys and not a fall-back**, which this note said
+ * it was until D-190 (`specs/080-f4-real-scope/rulings.md`) measured it:
+ * `localizeErrorEnvelope` composes one key, asks for it once and never re-asks.
+ * So a code every raise of which carries a token has no reader for its
+ * `errors.<CODE>` sentence — the operator never sees it, and deleting it is
+ * still wrong, because `check:error-translations` asks its P1 question at that
+ * key and at no other.
+ */
+export declare const errorCodeTokenRe: RegExp;
+/**
+ * One error code a module claims as its own
+ * (`specs/090-module-owned-error-codes/contracts/error-code-declaration.md` §1.1).
+ *
+ * **No `message` field, and that is a decision.** The English sentence a caller
+ * sees when nothing is translated is the one the raising code wrote: it already
+ * exists, it is written where the condition is known, and it can interpolate.
+ * A manifest message would be a third English sentence for one condition, and
+ * the two would drift exactly as a permission's `label` and its
+ * `adminRoles.permission.<code>` bundle key already do. The translated
+ * sentences live in the declaring module's own `i18n/<language>.json` under
+ * `errors.<CODE>`, which is where the envelope already looks.
+ *
+ * **`tokens` is declared rather than inferred** because a static reader that
+ * does not know the token set cannot tell `errors.CART_COUPON_REJECTED.expired`
+ * from a key whose tail is not a code at all — which is a finding. Fourteen keys
+ * in `invoices` and `carts` have this shape today.
+ */
+export declare const ModuleErrorCodeDeclarationSchema: z.ZodObject<{
+    code: z.ZodString;
+    tokens: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ModuleErrorCodeDeclaration = z.infer<typeof ModuleErrorCodeDeclarationSchema>;
+/**
+ * One capability this module **owns** and declares mutually exclusive
+ * (`specs/132-connector-family-discovery/contracts/module-capabilities.md` R3.1).
+ *
+ * The owner declares exclusivity, never the member, and three things follow that
+ * are otherwise loose ends. The refusal code stays on the semantic owner, which
+ * is what D-95.2 requires — a member raises it and must **not** declare it. A
+ * member cannot make a capability exclusive by accident, and cannot un-make it.
+ * And if the owner module is not installed in a deployment, the capability is
+ * simply not exclusive there, which is the honest answer rather than a refusal:
+ * without the shared layer there is no lock row and nothing to enforce with
+ * (R3.5).
+ */
+export declare const ExclusiveCapabilitySchema: z.ZodObject<{
+    key: z.ZodString;
+    errorCode: z.ZodString;
+}, z.core.$strip>;
+export type ExclusiveCapability = z.infer<typeof ExclusiveCapabilitySchema>;
+export declare const ModuleManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    version: z.ZodString;
+    dependencies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acknowledgedDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        moduleId: z.ZodString;
+        port: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    nonBindingDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        moduleId: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            "contributes-to": "contributes-to";
+            "degrades-without": "degrades-without";
+            "refuses-without": "refuses-without";
+        }>;
+        whenAbsent: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    activation: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        settingCode: z.ZodString;
+        default: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        nonDeactivatable: z.ZodLiteral<true>;
+        reason: z.ZodString;
+    }, z.core.$strip>]>>;
+    settings: z.ZodOptional<z.ZodObject<{
+        moduleCode: z.ZodString;
+        groups: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            name: z.ZodString;
+            salesChannelCodes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            isSystemProtected: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        settings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            groupCode: z.ZodOptional<z.ZodString>;
+            valueType: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                json: "json";
+                string_list: "string_list";
+                secret: "secret";
+                credential_ref: "credential_ref";
+            }>;
+            defaultValue: z.ZodUnknown;
+            previousDefaultValues: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+            salesChannelCodes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            enumOptions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            configurationType: z.ZodOptional<z.ZodString>;
+            hidden: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    i18n: z.ZodOptional<z.ZodObject<{
+        bundlesDir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    docs: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>, z.ZodLiteral<false>]>>;
+    demo: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        summary: z.ZodString;
+        seed: z.ZodType<(context: ModuleDemoContext<never>) => Promise<DemoSeedResult>, unknown, z.core.$ZodTypeInternals<(context: ModuleDemoContext<never>) => Promise<DemoSeedResult>, unknown>>;
+        reset: z.ZodType<(context: ModuleDemoContext<never>) => Promise<DemoResetResult>, unknown, z.core.$ZodTypeInternals<(context: ModuleDemoContext<never>) => Promise<DemoResetResult>, unknown>>;
+        after: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        package: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodLiteral<false>]>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        labelKey: z.ZodString;
+        descriptionKey: z.ZodOptional<z.ZodString>;
+        icon: z.ZodEnum<{
+            Plus: "Plus";
+            Sparkles: "Sparkles";
+            Settings: "Settings";
+            Search: "Search";
+            Boxes: "Boxes";
+            Layers: "Layers";
+            Menu: "Menu";
+            PlusCircle: "PlusCircle";
+            PlusSquare: "PlusSquare";
+            FilePlus: "FilePlus";
+            FolderPlus: "FolderPlus";
+            Upload: "Upload";
+            FileUp: "FileUp";
+            CloudUpload: "CloudUpload";
+            Download: "Download";
+            FileDown: "FileDown";
+            FileText: "FileText";
+            BookOpen: "BookOpen";
+            Rss: "Rss";
+            Package: "Package";
+            Tag: "Tag";
+            ShoppingCart: "ShoppingCart";
+            Receipt: "Receipt";
+            CreditCard: "CreditCard";
+            Users: "Users";
+            UserPlus: "UserPlus";
+            Inbox: "Inbox";
+            ListChecks: "ListChecks";
+            ClipboardList: "ClipboardList";
+            Image: "Image";
+            Video: "Video";
+            LayoutDashboard: "LayoutDashboard";
+            PanelLeft: "PanelLeft";
+            KeyRound: "KeyRound";
+            ShieldCheck: "ShieldCheck";
+            Edit: "Edit";
+            Archive: "Archive";
+            Box: "Box";
+            Truck: "Truck";
+            CircleDollarSign: "CircleDollarSign";
+            Activity: "Activity";
+            LineChart: "LineChart";
+            Smartphone: "Smartphone";
+            Webhook: "Webhook";
+            Scale: "Scale";
+            PlugZap: "PlugZap";
+            PercentDiamond: "PercentDiamond";
+            Newspaper: "Newspaper";
+            Languages: "Languages";
+            Eraser: "Eraser";
+            Warehouse: "Warehouse";
+            TrendingDown: "TrendingDown";
+            Bell: "Bell";
+            PackageOpen: "PackageOpen";
+            Building2: "Building2";
+            Store: "Store";
+            ClipboardCheck: "ClipboardCheck";
+        }>;
+        targetRoute: z.ZodString;
+        requiredPermission: z.ZodOptional<z.ZodString>;
+        keywords: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        weight: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        module: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    transactionalEmails: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        group: z.ZodOptional<z.ZodString>;
+        variables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            sampleValue: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclusiveCapabilities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        errorCode: z.ZodString;
+    }, z.core.$strip>>>;
+    errorCodes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        tokens: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    blocks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        labelKey: z.ZodString;
+        descriptionKey: z.ZodOptional<z.ZodString>;
+        category: z.ZodString;
+        contexts: z.ZodArray<z.ZodEnum<{
+            invoice: "invoice";
+            email: "email";
+            cms: "cms";
+            newsletter: "newsletter";
+        }>>;
+        fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                number: "number";
+                object: "object";
+                array: "array";
+                text: "text";
+                textarea: "textarea";
+                select: "select";
+                radio: "radio";
+                external: "external";
+                uuid: "uuid";
+                richtext: "richtext";
+            }>;
+            label: z.ZodOptional<z.ZodString>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            }, z.core.$strip>>>;
+            refKind: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        defaultProps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        responsiveFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        previewIcon: z.ZodOptional<z.ZodString>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    blockCategories: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        titleKey: z.ZodString;
+        contexts: z.ZodArray<z.ZodEnum<{
+            invoice: "invoice";
+            email: "email";
+            cms: "cms";
+            newsletter: "newsletter";
+        }>>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        visible: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    env: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        describes: z.ZodObject<{
+            en: z.ZodString;
+            pl: z.ZodString;
+        }, z.core.$strip>;
+        requirement: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"required">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"requiredWhen">;
+            input: z.ZodString;
+            equals: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"optional">;
+            without: z.ZodObject<{
+                en: z.ZodString;
+                pl: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>], "kind">;
+        secret: z.ZodBoolean;
+        generable: z.ZodBoolean;
+        owner: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"platform">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"application">;
+            application: z.ZodEnum<{
+                admin: "admin";
+                backend: "backend";
+                storefront: "storefront";
+            }>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"module">;
+            moduleId: z.ZodString;
+        }, z.core.$strip>], "kind">;
+        consumers: z.ZodArray<z.ZodEnum<{
+            admin: "admin";
+            backend: "backend";
+            storefront: "storefront";
+        }>>;
+        addressOf: z.ZodNullable<z.ZodEnum<{
+            admin: "admin";
+            backend: "backend";
+            storefront: "storefront";
+        }>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ModuleManifest = z.infer<typeof ModuleManifestSchema>;
+/**
+ * Identity-with-validation helper for module authors. Modules export a
+ * single `manifest` constant via this helper so TypeScript inference is
+ * preserved and the loader can ingest the validated payload directly.
+ */
+export declare function defineModuleManifest(m: ModuleManifest): ModuleManifest;
+/**
+ * Logger surface a hook may use. Implementations attach the module id as a
+ * tag at the orchestrator level so the hook author writes plain messages.
+ *
+ * **This is not `ctx.log`.** It is the logger of the three surfaces below — the
+ * install/uninstall hook context and the two lifecycle-participant events — all
+ * of which the orchestrator calls, and it takes a message and nothing else.
+ * `ModuleContext.log`, which a module writes to from `registerModule`, is a
+ * `PlatformLogger` (`@endora-commerce/platform/kernel`) and takes a bound object
+ * first: `ctx.log.info({ orderId }, 'message')`.
+ *
+ * The two used to share this name, which is how a scaffolded module came to
+ * call `ctx.log.info('…')` with one argument against a two-argument type. Keep
+ * the shapes' names apart; they are not interchangeable in either direction.
+ */
+export interface ModuleLifecycleLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/**
+ * Context passed to install/uninstall hooks. The orchestrator owns the
+ * lifetime of every field — hooks MUST use the provided `em` rather than
+ * forking their own, so writes participate in the same transaction.
+ */
+export interface ModuleLifecycleContext<EM = unknown, Redis = unknown> {
+    em: EM;
+    redis: Redis;
+    log: ModuleLifecycleLogger;
+    module: {
+        id: string;
+        version: string;
+    };
+}
+export type ModuleInstallHook<EM = unknown, Redis = unknown> = (ctx: ModuleLifecycleContext<EM, Redis>) => Promise<void>;
+export type ModuleUninstallHook<EM = unknown, Redis = unknown> = (ctx: ModuleLifecycleContext<EM, Redis> & {
+    hard: boolean;
+}) => Promise<void>;
+/**
+ * What a participant is told when **another** module is installed.
+ *
+ * `moduleId` is the module the operator asked to install, never the
+ * participant's own — that is the whole difference between this and an install
+ * hook, and it is why a participant could not be one. An install hook answers
+ * *"my module is arriving"*; a participant answers *"a module is arriving and I
+ * keep a projection of every module".*
+ */
+export interface ModuleInstalledEvent<EM = unknown> {
+    /** The module being installed. */
+    moduleId: string;
+    /** That module's manifest, already validated. */
+    manifest: ModuleManifest;
+    /**
+     * The directory holding that module's manifest file — what a participant
+     * that reads the module's own files off disk (bundles, templates) joins its
+     * relative directory onto.
+     */
+    modulePath: string;
+    /**
+     * The orchestrator's EntityManager. A participant MUST write through it
+     * rather than forking its own, so its rows join the operation the orchestrator
+     * is performing instead of committing beside it.
+     */
+    em: EM;
+    log: ModuleLifecycleLogger;
+}
+/**
+ * What a participant is told when another module is **hard**-uninstalled.
+ *
+ * A soft uninstall never reaches a participant: soft preserves the module's
+ * data so a re-install picks it up unchanged, and a projection of the manifest
+ * is data on those terms.
+ */
+export interface ModuleHardUninstalledEvent<EM = unknown> {
+    /** The module being removed. */
+    moduleId: string;
+    /**
+     * That module's manifest, or `null` when the registry holds a row for a
+     * module whose manifest is no longer on this instance — an orphan. Removing a
+     * projection is exactly the case that must still work then, so the manifest
+     * is nullable here and not on the install side.
+     */
+    manifest: ModuleManifest | null;
+    /** The orchestrator's EntityManager — see {@link ModuleInstalledEvent.em}. */
+    em: EM;
+    log: ModuleLifecycleLogger;
+}
+/**
+ * A module's declared interest in **every other module's** lifecycle.
+ *
+ * Two modules keep a table that projects what the manifests declare — `_i18n`
+ * projects `manifest.i18n` into `translation_bundles`, `admin_actions` projects
+ * `manifest.actions` into `module_actions` — and both projections have to move
+ * when *any* module is installed or hard-uninstalled. That is not an install
+ * hook (which fires for its own module) and it cannot be a port (the lifecycle
+ * orchestrator serves a platform command, which composes no container to
+ * resolve one from). It is a third export of `manifest.ts`, walked by the same
+ * generator, so it reaches core, overlay and an installed package on identical
+ * terms.
+ *
+ * **Both methods are required**, deliberately. Feature detection through an
+ * optional method is what D-97.3 refuses on a published port, and the reason
+ * carries here: a participant with nothing to do on one edge writes an empty
+ * body, which is a decision a reader can see, while an omitted method is
+ * indistinguishable from one somebody forgot.
+ *
+ * Keep the implementation in `manifest.ts` **light** — `await import()` the
+ * service the body needs. The generated manifest index is imported by the check
+ * scripts and by `src/db/configured-migrations.ts`, so a participant that
+ * statically imported an ORM-dependent service graph would pull it into every
+ * one of them.
+ */
+export interface ModuleLifecycleParticipant<EM = unknown> {
+    /**
+     * Runs after the installed module's settings are reconciled and before its
+     * own install hook. A throw aborts the install and reverts its migrations,
+     * which is the property FR-016 rests on: an operator installing a module with
+     * an unreadable bundle is told while they can still choose not to install it.
+     */
+    onModuleInstalled(event: ModuleInstalledEvent<EM>): Promise<void>;
+    /** Runs on `uninstall --hard` only. */
+    onModuleHardUninstalled(event: ModuleHardUninstalledEvent<EM>): Promise<void>;
+}
+/**
+ * The shape a command's name has to take: lowercase, hyphen-separated.
+ *
+ * A command is addressed as `<module id> <command name>` on the host's argv, so
+ * the name shares the module id's alphabet minus the underscore — an operator
+ * types `carts abandonment-sweep`, and `check:naming`'s route-segment rule is
+ * the same shape for the same reason. The host validates against this rather
+ * than accepting whatever a package declared: a name with a space in it is
+ * unaddressable, and a name that differs from the one printed by `--list` is
+ * worse than one that is refused.
+ */
+export declare const MODULE_CLI_COMMAND_NAME_RE: RegExp;
+/**
+ * What a command handler is given.
+ *
+ * `ctx` is the module's own `ModuleContext` — a kernel type this package
+ * deliberately does not import, so it arrives through the generic exactly as an
+ * `EntityManager` does on the lifecycle hooks above. A handler resolves what it
+ * needs from it with
+ * `lazyPort<T>(ctx, 'literalName')`, character-for-character what `backend.ts`
+ * writes, which is what keeps `check:port-dependencies` able to see the edge. A
+ * cradle read would be invisible to it.
+ *
+ * `out` and `err` are the command's interface, injected rather than reached for:
+ * a handler that writes to `process.stdout` directly cannot be driven from a
+ * test without capturing the process's streams, and the host is the one place
+ * that knows whether this invocation has a terminal.
+ */
+export interface ModuleCliCommandContext<Ctx = unknown> {
+    /** The module's own composed `ModuleContext`. */
+    ctx: Ctx;
+    /** Everything the operator typed after `<module id> <command name>`. */
+    argv: readonly string[];
+    /** One line of human-readable output. The host adds the newline. */
+    out(line: string): void;
+    /** One line of diagnostics. The host adds the newline. */
+    err(line: string): void;
+}
+/**
+ * An operator command a module declares and **the host runs** (D-160.9).
+ *
+ * Checked against Magento 2, which is this repository's module benchmark: a
+ * Magento module ships a command class plus a declaration in its `di.xml` under
+ * `CommandListInterface`, and `bin/magento` — the host binary — bootstraps the
+ * application and constructs each command with its dependencies injected. The
+ * module never bootstraps the host. That is one-to-one with what D-157.8 had
+ * already ruled here: the command is declared where `installHook` is declared,
+ * an export of the module's `manifest.ts`, picked up by the same tree walk, and
+ * one shape covers core, overlay and package.
+ *
+ * A package could not do it any other way. A file under `node_modules` can name
+ * no specifier that resolves to the instance's `backend/src/composition.ts`, and
+ * a core script that names it creates a module → root → module cycle. So the
+ * invocation inverts: the host composes once and calls the module.
+ *
+ * **It is not a Command Bus Command** (Constitution XIII), and the field is
+ * spelled `cliCommands` rather than `commands` so that the two cannot be read
+ * for one another — `backend/src/commands/` and every module's own `commands/`
+ * directory already hold the audited domain writes. A CLI command that performs
+ * a domain write runs one of those, resolved from `ctx`, exactly as a route
+ * handler does.
+ *
+ * Keep the declaration in `manifest.ts` **light**, for the reason
+ * {@link ModuleLifecycleParticipant} gives: the generated manifest index is
+ * imported by the check scripts and by `src/db/configured-migrations.ts`, so
+ * `run` should `await import()` the file that holds the body rather than
+ * pulling a service graph into all of them.
+ */
+export interface ModuleCliCommand<Ctx = unknown> {
+    /** Unique within the module. Must match {@link MODULE_CLI_COMMAND_NAME_RE}. */
+    name: string;
+    /** One line, printed by the host's `--list`. Written for an operator. */
+    summary: string;
+    /**
+     * The full usage text, printed by the host for `--help`.
+     *
+     * A **data property**, not a method, and answered by the host **before it
+     * composes**: `--list` and `--help` are questions about the declaration, and
+     * a tool has to be able to say what it does before it can do it. D-102 made
+     * that a condition rather than a nicety for `audit_logs read` — its credential
+     * is host access, not a working connection string — and the same property is
+     * why D-157.8 rejected path-convention dispatch, which *"nothing can list …
+     * for `--help`"*.
+     *
+     * Omit it and the host prints {@link summary}. An optional *data* property is
+     * outside what D-97.3 refuses: that rule is about optional **methods** on a
+     * published port, where `lazyPort`'s proxy makes feature detection impossible
+     * by construction.
+     */
+    help?: string;
+    /**
+     * The body. Returns the process exit code — `0` for success, non-zero for a
+     * failure the command itself detected (bad argv, a strict-mode violation).
+     *
+     * Required to return one rather than `void`: a command that means "1" and
+     * returns nothing is indistinguishable from one that succeeded, and the shell
+     * that runs it in a deploy hook reads only the code.
+     *
+     * A throw is the other failure channel and needs no handling here: the host
+     * reports it and exits non-zero. In particular a command must **not** wrap a
+     * port call in a `catch` — that swallows `ModuleDisabledError` and turns
+     * fail-closed into fail-open (`check:port-catches`).
+     */
+    run(context: ModuleCliCommandContext<Ctx>): Promise<number>;
+}
+/**
+ * The shape an audit action token has: `<object>.<verb>`, both snake_case.
+ *
+ * `product.create`, `stock_level.bulk_import`, `prompt_action.execute`. It is
+ * the value stored in `audit_log_entries.action`, and it is matched here rather
+ * than accepted as any string because the declaration is the *only* thing that
+ * puts a token into the dashboard query's `$in` — a typo used to be caught by a
+ * reviewer reading a hand-written array, and there is no array to read now.
+ *
+ * naming:allow-snake-case — the token is persisted verbatim in
+ * `audit_log_entries.action` and is written by `Command.action`, so this is the
+ * existing wire value rather than a new API field.
+ */
+export declare const auditActionRe: RegExp;
+/**
+ * One audit action a module offers to the admin home dashboard's
+ * recent-activity card.
+ *
+ * `labelKey` is **relative to the declaring module's i18n namespace**, exactly
+ * as a command-palette action's `labelKey` is: the module ships
+ * `activity.verb.product.create` in its own `i18n/en.json` and `pl.json`, the
+ * card resolves it as `t('<moduleId>', '<labelKey>')`. That is what lets a
+ * third-party package render a verb in the operator's language without the host
+ * shipping a string for it.
+ *
+ * `icon` comes from {@link KnownIconNameSchema}, so the admin maps it through
+ * the one `icon-map.ts` it already has and a package cannot name a component
+ * the SPA does not bundle.
+ */
+export declare const RecentActivityEntrySchema: z.ZodObject<{
+    action: z.ZodString;
+    icon: z.ZodEnum<{
+        Plus: "Plus";
+        Sparkles: "Sparkles";
+        Settings: "Settings";
+        Search: "Search";
+        Boxes: "Boxes";
+        Layers: "Layers";
+        Menu: "Menu";
+        PlusCircle: "PlusCircle";
+        PlusSquare: "PlusSquare";
+        FilePlus: "FilePlus";
+        FolderPlus: "FolderPlus";
+        Upload: "Upload";
+        FileUp: "FileUp";
+        CloudUpload: "CloudUpload";
+        Download: "Download";
+        FileDown: "FileDown";
+        FileText: "FileText";
+        BookOpen: "BookOpen";
+        Rss: "Rss";
+        Package: "Package";
+        Tag: "Tag";
+        ShoppingCart: "ShoppingCart";
+        Receipt: "Receipt";
+        CreditCard: "CreditCard";
+        Users: "Users";
+        UserPlus: "UserPlus";
+        Inbox: "Inbox";
+        ListChecks: "ListChecks";
+        ClipboardList: "ClipboardList";
+        Image: "Image";
+        Video: "Video";
+        LayoutDashboard: "LayoutDashboard";
+        PanelLeft: "PanelLeft";
+        KeyRound: "KeyRound";
+        ShieldCheck: "ShieldCheck";
+        Edit: "Edit";
+        Archive: "Archive";
+        Box: "Box";
+        Truck: "Truck";
+        CircleDollarSign: "CircleDollarSign";
+        Activity: "Activity";
+        LineChart: "LineChart";
+        Smartphone: "Smartphone";
+        Webhook: "Webhook";
+        Scale: "Scale";
+        PlugZap: "PlugZap";
+        PercentDiamond: "PercentDiamond";
+        Newspaper: "Newspaper";
+        Languages: "Languages";
+        Eraser: "Eraser";
+        Warehouse: "Warehouse";
+        TrendingDown: "TrendingDown";
+        Bell: "Bell";
+        PackageOpen: "PackageOpen";
+        Building2: "Building2";
+        Store: "Store";
+        ClipboardCheck: "ClipboardCheck";
+    }>;
+    labelKey: z.ZodString;
+}, z.core.$strip>;
+export type RecentActivityEntry = z.infer<typeof RecentActivityEntrySchema>;
+/**
+ * A module's declaration that its activity is **eligible** for the dashboard's
+ * recent-activity card — D-163.1, the first of the ruling's two axes.
+ *
+ * It is a declaration and not a decision. Whether a declared module's rows
+ * actually appear is the operator's, held in
+ * {@link recentActivityVisibilitySettingCode}'s Setting and defaulting to
+ * visible — Constitution XVII's two-axis shape applied to a narrower object.
+ * Neither axis overwrites the other: a module author cannot put entries on
+ * somebody's home screen by fiat, and an operator cannot be surprised by a card
+ * they did not configure.
+ *
+ * It replaces four hand-maintained tables that had already drifted apart inside
+ * core (D-163): the server allow-list that filtered the dashboard query, the
+ * action → module prefix map, the route's `module` enum and the admin's
+ * `ACTIVITY_RENDERING`. Every one of them is derived from this now, so a
+ * package's row reaches the card and a fifth hand-written entry has nowhere to
+ * be written.
+ *
+ * Declared as an export of `manifest.ts` beside `installHook`,
+ * `lifecycleParticipant` and `cliCommands`, walked by the same generator, so
+ * core, overlay and an installed package declare one on identical terms.
+ */
+export declare const ModuleRecentActivitySchema: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        action: z.ZodString;
+        icon: z.ZodEnum<{
+            Plus: "Plus";
+            Sparkles: "Sparkles";
+            Settings: "Settings";
+            Search: "Search";
+            Boxes: "Boxes";
+            Layers: "Layers";
+            Menu: "Menu";
+            PlusCircle: "PlusCircle";
+            PlusSquare: "PlusSquare";
+            FilePlus: "FilePlus";
+            FolderPlus: "FolderPlus";
+            Upload: "Upload";
+            FileUp: "FileUp";
+            CloudUpload: "CloudUpload";
+            Download: "Download";
+            FileDown: "FileDown";
+            FileText: "FileText";
+            BookOpen: "BookOpen";
+            Rss: "Rss";
+            Package: "Package";
+            Tag: "Tag";
+            ShoppingCart: "ShoppingCart";
+            Receipt: "Receipt";
+            CreditCard: "CreditCard";
+            Users: "Users";
+            UserPlus: "UserPlus";
+            Inbox: "Inbox";
+            ListChecks: "ListChecks";
+            ClipboardList: "ClipboardList";
+            Image: "Image";
+            Video: "Video";
+            LayoutDashboard: "LayoutDashboard";
+            PanelLeft: "PanelLeft";
+            KeyRound: "KeyRound";
+            ShieldCheck: "ShieldCheck";
+            Edit: "Edit";
+            Archive: "Archive";
+            Box: "Box";
+            Truck: "Truck";
+            CircleDollarSign: "CircleDollarSign";
+            Activity: "Activity";
+            LineChart: "LineChart";
+            Smartphone: "Smartphone";
+            Webhook: "Webhook";
+            Scale: "Scale";
+            PlugZap: "PlugZap";
+            PercentDiamond: "PercentDiamond";
+            Newspaper: "Newspaper";
+            Languages: "Languages";
+            Eraser: "Eraser";
+            Warehouse: "Warehouse";
+            TrendingDown: "TrendingDown";
+            Bell: "Bell";
+            PackageOpen: "PackageOpen";
+            Building2: "Building2";
+            Store: "Store";
+            ClipboardCheck: "ClipboardCheck";
+        }>;
+        labelKey: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ModuleRecentActivity = z.infer<typeof ModuleRecentActivitySchema>;
+/**
+ * Identity-with-validation helper for module authors, the twin of
+ * {@link defineModuleManifest}.
+ */
+export declare function defineModuleRecentActivity(declaration: ModuleRecentActivity): ModuleRecentActivity;
+/** The suffix every recent-activity visibility Setting code ends in. */
+export declare const RECENT_ACTIVITY_VISIBILITY_SETTING_SUFFIX = "recent_activity_visible";
+/**
+ * Raised when a module's id cannot carry a Setting code — see
+ * {@link recentActivityVisibilitySettingCode}.
+ */
+export declare class RecentActivitySettingCodeInvalid extends Error {
+    readonly name = "RecentActivitySettingCodeInvalid";
+}
+/**
+ * The Setting that holds the operator's choice for one declaring module.
+ *
+ * **Derived, never declared.** `activation.settingCode` is declared because a
+ * module that already shipped an ad-hoc control had to be able to adopt it;
+ * there is no such history here, and a declared code would be a fifth place a
+ * module could disagree with the platform about its own name. D-163.1 also
+ * fixes the default — visible — so there is nothing else for a declaration to
+ * carry.
+ */
+export declare function recentActivityVisibilitySettingCode(moduleId: string): string;
+/**
+ * The settings manifest the platform reconciles for a module, which is the
+ * module's own declaration plus the one Setting its recent-activity eligibility
+ * implies.
+ *
+ * Two callers and one derivation, deliberately (D-100): the boot reconcile
+ * walks every shipped module's settings, and the lifecycle orchestrator's
+ * `install` reconciles exactly the arriving module's. A package has only the
+ * second — since D-157.6(b) `install` is its sole author — so a second copy of
+ * this merge would mean a packaged module's control existing on one path and
+ * not the other.
+ *
+ * Returns `undefined` when the module declares neither, so a caller can keep
+ * treating "no settings" as an absent value.
+ */
+export declare function settingsManifestWithRecentActivity(manifest: ModuleManifest, recentActivity: ModuleRecentActivity | undefined): ModuleSettingsManifest | undefined;
+/**
+ * The two properties of a module-registry entry the boot settings reconcile
+ * reads — see {@link SettingsManifestCollectionPort}.
+ */
+export interface SettingsManifestSource {
+    readonly manifest: ModuleManifest;
+    /**
+     * The module's recent-activity eligibility (feature 080, T042j / D-163.1).
+     * It implies one Setting — the operator's choice of whether this module's
+     * entries reach the dashboard card — which is derived rather than declared,
+     * so a module that adds the eligibility export gets the control with it.
+     */
+    readonly recentActivity?: ModuleRecentActivity | undefined;
+}
+/**
+ * Container name: `settingsManifestCollectionPort`. Owner: `settings`.
+ *
+ * The boot-time reconcile's input list, assembled from the module registry the
+ * caller hands in.
+ *
+ * **Two owners, one list, and that is why this is a port.** Which modules a
+ * deployment ships is a composition-root input — core plus this deployment's
+ * overlay modules, never an installed package — so the registry arrives as an
+ * argument. How that registry becomes a reconcile list is `settings`' own rule:
+ * the settings module's manifest goes first, because every other manifest's
+ * entries fall back to its `general` group and the group has to exist before
+ * they are inserted, and each module code appears exactly once. A root that
+ * imported the derivation would be a root that has to be edited when the rule
+ * changes, and there are two of them.
+ *
+ * Nothing is gated on the module axis here on purpose: a module that is
+ * switched off keeps its settings rows and keeps its group on `/settings`,
+ * because a deactivation is not an uninstall (Constitution XVII) and the
+ * operator has to be able to switch it back on.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError`. It is resolved once, at boot, where a throw ends the
+ * process rather than answering a request, which is the ruled-correct
+ * behaviour for a composition that cannot be what the code says it is. Whether
+ * `settings` has an off state at all is its manifest's `activation` to say, not
+ * this line's: a module declaring `nonDeactivatable` never enters one.
+ */
+export interface SettingsManifestCollectionPort {
+    collect(registry: ReadonlyArray<SettingsManifestSource>): ModuleSettingsManifest[];
+}
+/** Aggregate of what a module's `manifest.ts` may export at runtime. */
+export interface ModuleManifestExports<EM = unknown, Redis = unknown, Ctx = unknown> {
+    manifest: ModuleManifest;
+    installHook?: ModuleInstallHook<EM, Redis>;
+    uninstallHook?: ModuleUninstallHook<EM, Redis>;
+    /**
+     * This module's interest in every *other* module's lifecycle — see
+     * {@link ModuleLifecycleParticipant}. Additive and optional: the modules that
+     * declare one are the two that keep a projection of the manifest set, and
+     * every other module's `manifest.ts` is unchanged.
+     */
+    lifecycleParticipant?: ModuleLifecycleParticipant<EM>;
+    /**
+     * The operator commands this module declares — see {@link ModuleCliCommand}.
+     * Additive and optional: a module with no operator command exports nothing
+     * and is unchanged.
+     */
+    cliCommands?: readonly ModuleCliCommand<Ctx>[];
+    /**
+     * This module's declaration that its activity is eligible for the admin home
+     * dashboard's recent-activity card — see {@link ModuleRecentActivitySchema}.
+     * Additive and optional: a module that declares none contributes no token,
+     * owns no visibility Setting and is unchanged.
+     */
+    recentActivity?: ModuleRecentActivity;
+}
+export declare const RegistryStateSchema: z.ZodEnum<{
+    installing: "installing";
+    installed: "installed";
+    disabled: "disabled";
+    uninstalled: "uninstalled";
+}>;
+export type RegistryState = z.infer<typeof RegistryStateSchema>;
+/** Persisted shape of a row in `module_registrations` (admin HTTP DTO). */
+export declare const ModuleRegistryRecordSchema: z.ZodObject<{
+    moduleId: z.ZodString;
+    state: z.ZodEnum<{
+        installing: "installing";
+        installed: "installed";
+        disabled: "disabled";
+        uninstalled: "uninstalled";
+    }>;
+    version: z.ZodString;
+    installedAt: z.ZodISODateTime;
+    lastStateChangeAt: z.ZodISODateTime;
+    lastInstallFailedAt: z.ZodNullable<z.ZodISODateTime>;
+    lastInstallError: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ModuleRegistryRecord = z.infer<typeof ModuleRegistryRecordSchema>;
+export declare const ModuleListItemFlagSchema: z.ZodEnum<{
+    orphan: "orphan";
+    "pending-upgrade": "pending-upgrade";
+    "dep-missing": "dep-missing";
+    "dep-disabled": "dep-disabled";
+}>;
+export type ModuleListItemFlag = z.infer<typeof ModuleListItemFlagSchema>;
+export declare const ModuleListItemStateSchema: z.ZodEnum<{
+    installing: "installing";
+    installed: "installed";
+    disabled: "disabled";
+    uninstalled: "uninstalled";
+    "not-installed": "not-installed";
+}>;
+export declare const ModuleListItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    version: z.ZodObject<{
+        registered: z.ZodNullable<z.ZodString>;
+        onDisk: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    state: z.ZodEnum<{
+        installing: "installing";
+        installed: "installed";
+        disabled: "disabled";
+        uninstalled: "uninstalled";
+        "not-installed": "not-installed";
+    }>;
+    dependencies: z.ZodArray<z.ZodString>;
+    flags: z.ZodArray<z.ZodEnum<{
+        orphan: "orphan";
+        "pending-upgrade": "pending-upgrade";
+        "dep-missing": "dep-missing";
+        "dep-disabled": "dep-disabled";
+    }>>;
+    installedAt: z.ZodNullable<z.ZodISODateTime>;
+    lastStateChangeAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type ModuleListItem = z.infer<typeof ModuleListItemSchema>;
+export declare const ModuleListResponseSchema: z.ZodObject<{
+    modules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        version: z.ZodObject<{
+            registered: z.ZodNullable<z.ZodString>;
+            onDisk: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        state: z.ZodEnum<{
+            installing: "installing";
+            installed: "installed";
+            disabled: "disabled";
+            uninstalled: "uninstalled";
+            "not-installed": "not-installed";
+        }>;
+        dependencies: z.ZodArray<z.ZodString>;
+        flags: z.ZodArray<z.ZodEnum<{
+            orphan: "orphan";
+            "pending-upgrade": "pending-upgrade";
+            "dep-missing": "dep-missing";
+            "dep-disabled": "dep-disabled";
+        }>>;
+        installedAt: z.ZodNullable<z.ZodISODateTime>;
+        lastStateChangeAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ModuleListResponse = z.infer<typeof ModuleListResponseSchema>;
+export declare const ModuleListQuerySchema: z.ZodObject<{
+    state: z.ZodOptional<z.ZodEnum<{
+        installing: "installing";
+        installed: "installed";
+        disabled: "disabled";
+        uninstalled: "uninstalled";
+    }>>;
+    flag: z.ZodOptional<z.ZodEnum<{
+        orphan: "orphan";
+        "pending-upgrade": "pending-upgrade";
+    }>>;
+}, z.core.$strip>;
+export type ModuleListQuery = z.infer<typeof ModuleListQuerySchema>;
+/**
+ * One module's presence as the server computed it. `present` is the
+ * conjunction of the two axes, precomputed server-side: neither frontend
+ * recombines them, which is what makes "off means absent" one decision rather
+ * than two implementations that can disagree.
+ *
+ * The axes stay separately visible because Constitution XVII requires the
+ * Admin UI to render them differently — *installed but switched off* shows an
+ * actionable control, *not available at platform level* shows absent or
+ * blocked-with-a-reason.
+ */
+export declare const ModulePresenceSchema: z.ZodObject<{
+    id: z.ZodString;
+    present: z.ZodBoolean;
+    platformState: z.ZodUnion<[z.ZodEnum<{
+        installing: "installing";
+        installed: "installed";
+        disabled: "disabled";
+        uninstalled: "uninstalled";
+    }>, z.ZodLiteral<"not-installed">]>;
+    activated: z.ZodBoolean;
+    deactivatable: z.ZodBoolean;
+    nonDeactivatableReason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ModulePresence = z.infer<typeof ModulePresenceSchema>;
+/** `GET /api/v1/admin/module-presence` — every admin, no permission code. */
+export declare const AdminModulePresenceResponseSchema: z.ZodObject<{
+    modules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        present: z.ZodBoolean;
+        platformState: z.ZodUnion<[z.ZodEnum<{
+            installing: "installing";
+            installed: "installed";
+            disabled: "disabled";
+            uninstalled: "uninstalled";
+        }>, z.ZodLiteral<"not-installed">]>;
+        activated: z.ZodBoolean;
+        deactivatable: z.ZodBoolean;
+        nonDeactivatableReason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    degraded: z.ZodBoolean;
+}, z.core.$strip>;
+export type AdminModulePresenceResponse = z.infer<typeof AdminModulePresenceResponseSchema>;
+/** The storefront needs no axis detail — only whether to render at all. */
+export declare const StorefrontModulePresenceSchema: z.ZodObject<{
+    id: z.ZodString;
+    present: z.ZodBoolean;
+}, z.core.$strip>;
+export type StorefrontModulePresence = z.infer<typeof StorefrontModulePresenceSchema>;
+/** `GET /api/v1/storefront/module-presence` — public, tag `modules:presence`. */
+export declare const StorefrontModulePresenceResponseSchema: z.ZodObject<{
+    modules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        present: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StorefrontModulePresenceResponse = z.infer<typeof StorefrontModulePresenceResponseSchema>;
+/**
+ * `POST /api/v1/admin/modules/:id/activation` — the operator axis, and the
+ * only door to it. The ordinary settings write path refuses an activation
+ * code, so this endpoint's audited Command is where every flip is recorded.
+ */
+export declare const ModuleActivationRequestSchema: z.ZodObject<{
+    active: z.ZodBoolean;
+}, z.core.$strip>;
+export type ModuleActivationRequest = z.infer<typeof ModuleActivationRequestSchema>;
+/** The module's presence *after* the flip, so no client recomputes it. */
+export declare const ModuleActivationResponseSchema: z.ZodObject<{
+    module: z.ZodObject<{
+        id: z.ZodString;
+        present: z.ZodBoolean;
+        platformState: z.ZodUnion<[z.ZodEnum<{
+            installing: "installing";
+            installed: "installed";
+            disabled: "disabled";
+            uninstalled: "uninstalled";
+        }>, z.ZodLiteral<"not-installed">]>;
+        activated: z.ZodBoolean;
+        deactivatable: z.ZodBoolean;
+        nonDeactivatableReason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ModuleActivationResponse = z.infer<typeof ModuleActivationResponseSchema>;
+/**
+ * `GET /api/v1/admin/modules/:id/deactivation-impact` — the live half of the
+ * confirmation an operator is shown before switching a module off.
+ *
+ * Feature 074's consequence rows are **static**: one sentence per present
+ * dependent, taken from that dependent's `whenAbsent` declaration, so the
+ * dialog can be rendered from the ledger with no database read. This response
+ * carries the facts that only a live read can answer, and today there is
+ * exactly one — how many people hold a second factor (the owner's ruling on
+ * D-96.5).
+ *
+ * Three properties of the shape, each deliberate:
+ *
+ *  - **Named after the fact, not after the module.** `mfa` owns the table and
+ *    answers the question through a port; the wire shape says what the number
+ *    means. When a second module needs a live datum this becomes a list — one
+ *    entry per fact — which is a change to make when there are two, not now
+ *    (Constitution IV).
+ *  - **Nullable, always.** `null` means "not available", not "zero": the module
+ *    is already off, or the read failed. A count that cannot be fetched must
+ *    never stop an operator switching a module off, so the caller renders the
+ *    rest of the dialog and says the number is unavailable.
+ *  - **Read while the module is still on.** The dialog precedes the flip, so
+ *    the gate on the owning port is open when the question is asked. That is
+ *    what makes a live count implementable at all — see `MfaEnrolmentCountPort`.
+ */
+export declare const ModuleDeactivationImpactSchema: z.ZodObject<{
+    moduleId: z.ZodString;
+    activeSecondFactorUsers: z.ZodNullable<z.ZodObject<{
+        admins: z.ZodNumber;
+        customers: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ModuleDeactivationImpact = z.infer<typeof ModuleDeactivationImpactSchema>;
+/**
+ * One row of the interceptor execution plan served by
+ * `GET /api/v1/admin/api-interceptors`. Items are sorted in execution order:
+ * target, then phase (pre before post), then order + (module, id) tie-break.
+ */
+export declare const apiInterceptorEntrySchema: z.ZodObject<{
+    target: z.ZodString;
+    phase: z.ZodEnum<{
+        pre: "pre";
+        post: "post";
+    }>;
+    order: z.ZodNumber;
+    module: z.ZodString;
+    id: z.ZodString;
+    moduleEnabled: z.ZodBoolean;
+}, z.core.$strip>;
+export type ApiInterceptorEntry = z.infer<typeof apiInterceptorEntrySchema>;
+export declare const apiInterceptorListSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        target: z.ZodString;
+        phase: z.ZodEnum<{
+            pre: "pre";
+            post: "post";
+        }>;
+        order: z.ZodNumber;
+        module: z.ZodString;
+        id: z.ZodString;
+        moduleEnabled: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ApiInterceptorList = z.infer<typeof apiInterceptorListSchema>;
+//# sourceMappingURL=modules.d.ts.map