@endora-commerce/contracts 0.100.0

package/dist/modules.js

@@ -0,0 +1,1390 @@
+// Module Lifecycle — feature 018 contract surface.
+//
+// Defines the on-disk-data shape every module's `manifest.ts` exports plus
+// the registry-record shape persisted in `module_registrations`. The settings
+// portion (per-module groups + settings) is delegated to feature 004's
+// existing `ModuleSettingsManifestSchema`; this module wraps it with the
+// outer module-level metadata (id, name, version, dependencies) and the
+// lifecycle-hook type aliases.
+//
+// Hooks themselves are NOT validated by Zod (functions don't serialise
+// through schemas); the loader attaches them from the manifest module's
+// runtime exports as a separate step.
+import { z } from 'zod';
+import { ModuleSettingsManifestSchema, settingCodeRe, } from './settings.js';
+import { KnownIconNameSchema, ModuleActionsManifestSchema } from './admin-actions.js';
+import { modulePermissionDeclarationSchema } from './admin.js';
+import { errorCodeRe } from './errors.js';
+import { capabilityKeyRe } from './capabilities.js';
+import { transactionalEmailManifestEntrySchema } from './transactional-emails.js';
+import { BlockCategorySchema, BlockDefinitionSchema, blockNameRe } from './cms.js';
+import { EnvironmentInputSchema } from './environment-inputs.js';
+// ---------------------------------------------------------------------------
+// Identifier / version regexes
+// ---------------------------------------------------------------------------
+/**
+ * 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 const moduleIdRe = /^_?[a-z][a-z0-9_]*$/;
+/** Semver-lite — `MAJOR.MINOR.PATCH` plus an optional `-prerelease` suffix. */
+export const moduleVersionRe = /^\d+\.\d+\.\d+(?:-[a-z0-9.]+)?$/;
+// ---------------------------------------------------------------------------
+// Module manifest
+// ---------------------------------------------------------------------------
+/**
+ * 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 const ModuleI18nManifestSchema = z.object({
+    bundlesDir: z.string().min(1).default('i18n'),
+});
+/**
+ * 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 const ModuleDocsManifestSchema = z.object({
+    /** The directory, relative to the module's own root. */
+    dir: z.string().min(1).default('docs'),
+});
+/**
+ * `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 const ModuleDocsDeclarationSchema = z.union([ModuleDocsManifestSchema, z.literal(false)]);
+/**
+ * A function value the schema accepts by kind.
+ *
+ * `z.custom` rather than `z.function()`: Zod v4's function schema builds a
+ * validating *wrapper*, and this field must pass the author's own closure
+ * through by reference — the runner calls it, and a copy would be a second
+ * function nothing else in the tree holds.
+ */
+function demoBodySchema(field) {
+    return z.custom((value) => typeof value === 'function', {
+        message: `demo.${field} must be a function. The body is reached by a relative ` +
+            `\`await import()\` from the declaration (contract §1.4), never by a path ` +
+            'the platform is expected to guess.',
+    });
+}
+export const ModuleDemoManifestSchema = z.object({
+    summary: z.string().min(1).max(200),
+    seed: demoBodySchema('seed'),
+    reset: demoBodySchema('reset'),
+    after: z.array(z.string().regex(moduleIdRe)).readonly().optional(),
+    // §6.1. A **name**, so the schema is `z.string()` and deliberately carries no
+    // scope or prefix rule: `@endora-commerce/mod-<id>-demo` is this repository's
+    // convention and a third-party module's demo package is named by its author.
+    // A pattern here would be a derived fact written down (D-100) that answers
+    // wrongly for the first package that is not ours.
+    package: z.string().min(1).optional(),
+});
+/**
+ * `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 const ModuleDemoDeclarationSchema = z.union([
+    ModuleDemoManifestSchema,
+    z.literal(false),
+]);
+/**
+ * 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 const ModuleActivationSchema = z.union([
+    z.object({
+        /**
+         * The Setting that holds the operator's choice. Declared rather than
+         * derived so a module that already ships an ad-hoc control (`blog.enabled`
+         * and friends) can adopt it instead of growing a second switch.
+         */
+        settingCode: z.string().regex(settingCodeRe),
+        /** Applies when the operator has never chosen. Asserted, never assumed. */
+        default: z.boolean(),
+    }),
+    z.object({
+        /** The platform cannot run without this module. */
+        nonDeactivatable: z.literal(true),
+        /** Operator-facing sentence rendered next to the locked control. */
+        reason: z.string().min(1).max(200),
+    }),
+]);
+/**
+ * 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 const ModuleAcknowledgedDependencySchema = z.object({
+    /** The module that owns the port. */
+    moduleId: z.string().regex(moduleIdRe),
+    /** The container registration name this module resolves, e.g. `addressService`. */
+    port: z.string().min(1),
+    /** Why the edge cannot be declared in `dependencies` — the cycle, spelled out. */
+    reason: z.string().min(1).max(800),
+});
+/**
+ * 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 const ModuleNonBindingDependencySchema = z.object({
+    /** The module that owns the registration. */
+    moduleId: z.string().regex(moduleIdRe),
+    /** The container registration name, e.g. `promptActionToolRegistry`. */
+    name: z.string().min(1),
+    kind: z.enum(['contributes-to', 'degrades-without', 'refuses-without']),
+    /**
+     * `degrades-without` and `refuses-without` only: what stops working, and for
+     * the second, what refuses. Rendered beside the control.
+     */
+    whenAbsent: z.string().min(1).max(200).optional(),
+    reason: z.string().min(1).max(800),
+});
+/**
+ * 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 const OmittedModuleSchema = z.object({
+    /** The module this deployment does not ship. */
+    moduleId: z.string().regex(moduleIdRe),
+    /**
+     * Why — in prose, and long enough to be an argument. "We do not need it" is
+     * not a reason; what the deployment does instead of the capability is.
+     */
+    reason: z.string().min(20).max(800),
+});
+/**
+ * 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 const DeploymentDivergenceDeclarationSchema = z.object({
+    /** The modules this deployment does not ship. D-101, unchanged in substance. */
+    omittedModules: z.array(OmittedModuleSchema).default([]),
+    /**
+     * Wrapping order, per registration name, for a name more than one of this
+     * deployment's overlay modules decorates — innermost first.
+     *
+     * **Checked, never applied.** The composer emits modules in its own order and
+     * drains decorations once; this declares that the resulting order was the
+     * intended one, and a composition that disagrees refuses. Making the
+     * declaration authoritative would put a hand-written array in front of the
+     * composer's topological emission, which is two orderings of one thing waiting
+     * to disagree.
+     *
+     * Only a deployment's own overlay modules can appear here: a core module and
+     * an installed package may not decorate a name they do not own (D-156.4), so
+     * every ambiguity this can resolve is between two of them.
+     *
+     * Nothing reads it yet — the supply is P4 of
+     * `specs/107-override-report-and-ladder/`.
+     */
+    decorationOrder: z
+        .record(z.string().min(1), z.array(z.string().regex(moduleIdRe)).min(1))
+        .default({}),
+    /**
+     * One sentence per divergence the platform derives, keyed by the derived
+     * entry's own key — `<kind>:<module>:<subject>`, never a path and never a
+     * line.
+     *
+     * A flat map rather than a reason field on a per-kind array, and the
+     * difference is structural rather than stylistic: a map can only ever
+     * *answer*. So the declaration cannot add a divergence the derivation did not
+     * find, nor hide one it did — the population is the report's and the judgement
+     * is this.
+     *
+     * The key's grammar is checked where the population it keys into exists;
+     * nothing reads this yet — the report is P2 of
+     * `specs/107-override-report-and-ladder/`.
+     */
+    reasons: z.record(z.string().min(1), z.string().min(20).max(800)).default({}),
+})
+    // Three fields are the whole vocabulary, so a fourth is a typo — and a
+    // mistyped field name under a lenient object is silently stripped, which
+    // reads as "this deployment declares nothing" for a file whose author wrote
+    // a declaration. Refusing it names the key.
+    .strict();
+/**
+ * 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 const errorCodeTokenRe = /^[a-z][a-z0-9_]*$/;
+/**
+ * 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 const ModuleErrorCodeDeclarationSchema = z.object({
+    code: z.string().regex(errorCodeRe),
+    tokens: z.array(z.string().regex(errorCodeTokenRe)).optional(),
+});
+/**
+ * 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 const ExclusiveCapabilitySchema = z.object({
+    /** The capability this module owns and declares mutually exclusive. */
+    key: z.string().regex(capabilityKeyRe),
+    /** The code raised when a second member is activated. Owned by this module. */
+    errorCode: z.string().regex(errorCodeRe),
+});
+export const ModuleManifestSchema = z.object({
+    id: z.string().regex(moduleIdRe),
+    name: z.string().min(1).max(120),
+    description: z.string().max(2000).optional(),
+    version: z.string().regex(moduleVersionRe),
+    dependencies: z.array(z.string().regex(moduleIdRe)).default([]),
+    /**
+     * Real port edges withheld from `dependencies` for install-ordering reasons
+     * (feature 073, Amendment A1). Consumed by `check-port-dependencies.ts` and
+     * by the lifecycle's flip-time dependency refusals; never by the install
+     * order or the migration order.
+     */
+    acknowledgedDependencies: z.array(ModuleAcknowledgedDependencySchema).optional(),
+    /**
+     * Real container edges that deliberately do **not** bind the operator (D-44).
+     * Consumed by `check-port-dependencies.ts` for the ownership claim; read by
+     * no graph and by no ordering. See {@link ModuleNonBindingDependencySchema}.
+     */
+    nonBindingDependencies: z.array(ModuleNonBindingDependencySchema).optional(),
+    /**
+     * Operator-activation control (feature 073). Optional only while the
+     * conversion sweep is in flight: `check-module-gating` requires it as soon
+     * as a module's seams are converted, so a converted module without it fails
+     * CI rather than resolving to an implicit "on".
+     */
+    activation: ModuleActivationSchema.optional(),
+    /**
+     * Per-module settings declaration consumed by the existing feature 004
+     * `ManifestReconciler`. When present, its `moduleCode` MUST equal the
+     * outer `id` — the loader enforces this at boot.
+     */
+    settings: ModuleSettingsManifestSchema.optional(),
+    /**
+     * Per-module Admin UI translation declaration (feature 019).
+     * When present, the lifecycle install hook ingests bundle JSON files
+     * from `<bundlesDir>` into the platform's `translation_bundles` store.
+     */
+    i18n: ModuleI18nManifestSchema.optional(),
+    /**
+     * Per-module documentation declaration (feature 100 / roadmap F12).
+     *
+     * `{ dir }` — the module ships its pages at that directory under its own
+     * root; `false` — it ships none, deliberately; **absent** — nobody has
+     * decided, which is where every module stands in Phase 1 while the pages are
+     * still in the site's own tree. See {@link ModuleDocsDeclarationSchema} for
+     * why the last two are not one state.
+     */
+    docs: ModuleDocsDeclarationSchema.optional(),
+    /**
+     * Per-module demo data declaration (feature 113, D-209).
+     *
+     * `{ summary, seed, reset, after? }` — the module ships demo rows for its own
+     * tables; `false` — it has nothing to demonstrate, deliberately; **absent** —
+     * nobody has decided. See {@link ModuleDemoDeclarationSchema} for why the last
+     * two are not one state, and {@link ModuleDemoManifest} for what a body may
+     * do.
+     *
+     * Declaring it creates **no** lifecycle edge: it puts no module in
+     * `dependencies`, changes no migration order and does not stand in the way of
+     * an operator switching another module off (§2.3, FR-005).
+     */
+    demo: ModuleDemoDeclarationSchema.optional(),
+    /**
+     * Per-module Admin Command Palette action declarations (feature 020).
+     * Each entry becomes a row in `module_actions` at install time and is
+     * surfaced in the admin's command palette under the Actions group.
+     * Within-module id uniqueness is enforced by the schema.
+     */
+    actions: ModuleActionsManifestSchema.optional(),
+    /**
+     * Per-module admin permission codes merged into the assignable catalogue
+     * when the module is enabled (feature 026).
+     */
+    permissions: z.array(modulePermissionDeclarationSchema).optional(),
+    /**
+     * Per-module transactional email declarations (feature 047). Each entry is
+     * reconciled into `transactional_emails` at boot; default subject/content are
+     * supplied separately at runtime via the EmailDefaultsRegistry.
+     */
+    transactionalEmails: z.array(transactionalEmailManifestEntrySchema).optional(),
+    /**
+     * The capability families this module declares itself a **member** of
+     * (feature 132, `contracts/module-capabilities.md` R1).
+     *
+     * A key is a kebab-case string, not an enum: `CAPABILITY_KEYS` spells the
+     * three this repository mints, and a capability owned by a package this
+     * repository does not contain is spelled by its owner and needs no entry
+     * anywhere here. That openness is the point — it is what lets a connector
+     * installed from npm and a per-deployment overlay module join a family on the
+     * same terms as a core module, which the three arrays below cannot (R2.1).
+     *
+     * It carries **membership only** (R1.4). The activation setting code is
+     * `activation.settingCode`, which every member already declares and which the
+     * registry cache already indexes by module; the three arrays this field
+     * replaces each carried a second field byte-identical to it in every entry
+     * that could be checked, which is D-100 written into a schema.
+     *
+     * Declaring it creates **no** lifecycle edge (R1.5): no `dependencies` entry,
+     * no migration ordering, no install ordering, and no obstacle to an operator
+     * switching the capability's owner off. The same sentence `demo` carries, and
+     * enforced the same way — no graph reads this field.
+     *
+     * Absent means "this module declares no capability", which is true of most
+     * modules and is not a finding.
+     */
+    capabilities: z.array(z.string().regex(capabilityKeyRe)).optional(),
+    /**
+     * The capabilities this module **owns** and declares mutually exclusive
+     * (feature 132, R3.1). See {@link ExclusiveCapabilitySchema}.
+     */
+    exclusiveCapabilities: z.array(ExclusiveCapabilitySchema).optional(),
+    // Feature 132 — `pimConnector`, `invoiceLedger` and `erpConnector` are **gone**.
+    //
+    // Three `z.literal(true).optional()` flags, one per family, each declared by one or
+    // two modules and each read by **nothing**: every exclusion answered from a
+    // hand-written array in this package instead. The doc comment on `invoiceLedger`
+    // asked for this removal by name, and put the question it could not answer alone —
+    // *"is the flag the source, or the table?"* The answer is neither: the manifest is
+    // the source, in one field for all families (`capabilities` above), and both the
+    // flags and the tables go.
+    //
+    // This is a **breaking** manifest-schema change for any consumer that declared one,
+    // which is three modules in this tree and potentially a package outside it; the
+    // replacement is one line and is additive.
+    /**
+     * The operator-visible error codes this module owns (feature 090, D-182).
+     *
+     * The declaration is what routes the code's sentence to this module's bundle:
+     * `errors.<CODE>` in `<module>/i18n/<language>.json`. Which module owns a code
+     * is `specs/082-error-code-ownership/contracts/error-code-ownership.md` §1 —
+     * the domain noun decides, never the thrower, so `orders` raising `CART_EMPTY`
+     * leaves the code owned by `carts`.
+     *
+     * Absent means "this module owns no operator-visible error code", which is
+     * true of most modules and is not a finding.
+     */
+    errorCodes: z.array(ModuleErrorCodeDeclarationSchema).optional(),
+    /**
+     * The Page Builder blocks this module owns (feature 096, FR-001/FR-006).
+     *
+     * A block's `name` is `<this module's id>.<LocalName>` and is **persisted**:
+     * it is written into the `type` position of a Puck node in a `jsonb` column
+     * and is the only link between a stored node and the module that can render
+     * it. Which module owns a block is the domain noun its fields and data belong
+     * to — the rule `specs/082-error-code-ownership/contracts/error-code-ownership.md`
+     * §1 already applies to error codes — never the package the renderer file
+     * currently sits in.
+     *
+     * Absent means "this module owns no Page Builder block", which is true of
+     * most modules and is not a finding.
+     */
+    blocks: z.array(BlockDefinitionSchema).optional(),
+    /**
+     * The palette sections this module declares (feature 096, FR-009).
+     *
+     * Declared rather than hard-coded so that contributing a block into a section
+     * costs no edit to a shared `categories` map in a package the contributor
+     * does not own. Two modules declaring the same key for the same context is
+     * expected and merges; a category exists per context, so `layout` for `cms`
+     * and `layout` for `email` are two entries.
+     */
+    blockCategories: z.array(BlockCategorySchema).optional(),
+    /**
+     * The environment inputs this module owns (`specs/117-instance-bring-up/`
+     * FR-002; `contracts/environment-inputs.md` §R2.2).
+     *
+     * **This is the only way a module's requirements can reach a client.** A
+     * module package ships `dist`, `i18n` and `docs`; `.env.example` is a file in
+     * *this* repository. So a client who scaffolds an instance, installs thirty
+     * modules and copies the example gets a file that does not mention the
+     * variables those modules read — and meets each one as a boot that failed for
+     * a reason nothing named. Declared here, the same tree walk that picks up
+     * `permissions`, `actions` and `errorCodes` carries them into the generated
+     * manifest index, so a core module, a per-deployment overlay module and an
+     * installed package all declare on identical terms.
+     *
+     * **A module declares only what it *owns*.** Most of what a module reads is
+     * not its own: `NODE_ENV`, `BACKEND_ROLE`, `STOREFRONT_BASE_URL`,
+     * `REVALIDATE_SECRET` and `SETTINGS_SECRET_ENCRYPTION_KEY` are the platform's,
+     * declared once in `packages/platform/src/env/index.ts`, and a module's read
+     * of one is satisfied by that declaration. Declaring them again would be one
+     * fact with thirty homes and thirty `describes` (D-100), so
+     * {@link defineModuleManifest} refuses an entry whose `owner` is not this
+     * module — and `check:env-inputs` refuses one whose name the platform already
+     * owns.
+     *
+     * Absent means "this module reads no environment variable of its own", which
+     * is true of most modules and is not a finding.
+     */
+    env: z.array(EnvironmentInputSchema).optional(),
+});
+/**
+ * The three cross-field activation rules (feature 073,
+ * `contracts/module-activation-manifest.md`). They live here rather than in
+ * the schema because a Zod union of two non-strict objects accepts a value
+ * carrying both forms, and because the resulting message has to name the
+ * module the author is looking at.
+ */
+function assertActivationRules(id, activation) {
+    const block = activation;
+    const declaresControl = typeof block['settingCode'] === 'string' && typeof block['default'] === 'boolean';
+    const declaresNonDeactivatable = block['nonDeactivatable'] === true &&
+        typeof block['reason'] === 'string' &&
+        block['reason'].length > 0;
+    // 1. Exactly one form.
+    if (declaresControl === declaresNonDeactivatable) {
+        throw new Error(`[contracts/modules] manifest "${id}" must declare exactly one activation ` +
+            `form: either { settingCode, default } or { nonDeactivatable: true, reason }.`);
+    }
+    // 2. An `_`-prefixed id is platform-internal by convention (`moduleIdRe`);
+    //    this makes the convention enforceable.
+    if (id.startsWith('_') && !declaresNonDeactivatable) {
+        throw new Error(`[contracts/modules] manifest "${id}" is platform-internal (leading "_") ` +
+            `and MUST declare activation as { nonDeactivatable: true, reason }.`);
+    }
+    // 3. The control belongs to the declaring module. Adopting an existing
+    //    ad-hoc control (FR-014) is allowed precisely because every such code
+    //    — `blog.enabled`, `prompt_actions.enabled`, `ksef.integration.enabled` —
+    //    already sits under its own module's namespace.
+    if (declaresControl) {
+        const code = block['settingCode'];
+        if (code !== id && !code.startsWith(`${id}.`)) {
+            throw new Error(`[contracts/modules] manifest "${id}" declares activation setting ` +
+                `"${code}", which is outside the module's own namespace ` +
+                `("${id}" or "${id}.*").`);
+        }
+    }
+}
+/**
+ * The four cross-field capability rules (feature 132,
+ * `contracts/module-capabilities.md` R4).
+ *
+ * They sit beside the activation rules for the reason `assertActivationRules`
+ * states about itself: they are cross-field, a non-strict object schema accepts
+ * a value carrying both arms, and the message has to name the module the author
+ * is looking at — and the key, since a manifest may declare several.
+ *
+ * **Two rules are deliberately not here**, and both for the same reason:
+ * this function sees **one** manifest and cannot see a family. "Exactly one
+ * installed module may own a key" (R3.4) and "a member of an *exclusive* key may
+ * not declare `activation.default: true`" (R3.6) are refused at derivation, in
+ * `capabilityRegistryFrom`, where both facts are in hand.
+ */
+function assertCapabilityRules(m) {
+    const memberships = m.capabilities ?? [];
+    const owned = m.exclusiveCapabilities ?? [];
+    // R4.1 — a member with no activation control cannot participate in an
+    // exclusion that is resolved on the activation axis, so the declaration would
+    // be a claim nothing could ever check. Asked of members only: an owner is not
+    // resolved on that axis, its members are.
+    if (memberships.length > 0 && m.activation === undefined) {
+        throw new Error(`[contracts/modules] manifest "${m.id}" declares capability membership ` +
+            `(${memberships.join(', ')}) but no \`activation\` block. A member with no ` +
+            `activation control cannot participate in an exclusion that is resolved on ` +
+            `the activation axis, so the membership could never be enforced or released.`);
+    }
+    // R4.2 — a duplicate says nothing the single entry does not, and a family read
+    // that counts entries rather than modules would count this member twice.
+    const seenMembership = new Set();
+    for (const key of memberships) {
+        if (seenMembership.has(key)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares capability "${key}" twice ` +
+                `in \`capabilities\`. Membership is a set; drop the duplicate.`);
+        }
+        seenMembership.add(key);
+    }
+    // R4.3 — two entries for one key are two refusal codes for one condition, and
+    // nothing decides which of them an operator meets.
+    const seenOwned = new Set();
+    for (const entry of owned) {
+        if (seenOwned.has(entry.key)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares capability "${entry.key}" ` +
+                `twice in \`exclusiveCapabilities\`. A key has one owner and one refusal ` +
+                `code; two entries leave nothing to decide which an operator meets.`);
+        }
+        seenOwned.add(entry.key);
+    }
+    // R4.4 / R3.3 — an owner that is also a member would exclude itself from its
+    // own family. Two *different* keys in the two arrays are fine and expected:
+    // keys never exclude each other (`capability-exclusivity.md` R2.5).
+    for (const key of seenOwned) {
+        if (seenMembership.has(key)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares capability "${key}" as both ` +
+                `a membership and an exclusive capability it owns. An owner that is also a ` +
+                `member would exclude itself from its own family.`);
+        }
+    }
+}
+/**
+ * The three `nonBindingDependencies` rules (D-44 §5).
+ *
+ * They sit beside the activation rules for the same reason: two of the three
+ * are cross-field — one reads `dependencies` and `acknowledgedDependencies`,
+ * one reads `kind` against `whenAbsent` — and the message has to name the
+ * module the author is looking at.
+ */
+function assertNonBindingRules(m) {
+    const acknowledged = new Set((m.acknowledgedDependencies ?? []).map((edge) => edge.moduleId));
+    for (const edge of m.nonBindingDependencies ?? []) {
+        // 1. No self-edges. The array's element regex applies per element and
+        //    cannot see the outer id, exactly as with `dependencies`.
+        if (edge.moduleId === m.id) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares a non-binding dependency on ` +
+                `itself (forbidden).`);
+        }
+        // 2. One edge, one claim, in one place — the mirror of the
+        //    `acknowledgedDependencies` rule above. A target declared in either of
+        //    the other two arrays already carries the bind, so a withdrawal beside
+        //    it is a second record of the same edge that nothing keeps in step.
+        if (m.dependencies.includes(edge.moduleId)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares a non-binding dependency on ` +
+                `"${edge.moduleId}", which it already declares in \`dependencies\` — that ` +
+                `declaration already binds the operator, so drop one of the two.`);
+        }
+        if (acknowledged.has(edge.moduleId)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares a non-binding dependency on ` +
+                `"${edge.moduleId}", which it already acknowledges — an acknowledged edge is ` +
+                `read by the refusal graph, so the two claims contradict each other.`);
+        }
+        // 3. `whenAbsent` is the `degrades-without` kind's entire content: the
+        //    behaviour the module promises and the sentence the platform screen
+        //    renders. A `contributes-to` edge has no degradation to describe.
+        if (edge.kind === 'degrades-without' && edge.whenAbsent === undefined) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares "${edge.moduleId}:${edge.name}" ` +
+                `as \`degrades-without\` with no \`whenAbsent\` — the kind is a promise about ` +
+                `behaviour and the sentence is what a reviewer and an off-state test hold it to.`);
+        }
+        // 3a. And it is the whole of `refuses-without`, for a sharper reason: the
+        //     outcome that kind produces is the one an undeclared gated port
+        //     produces anyway, so the sentence is the only thing the declaration
+        //     adds. Without it the entry classifies identically to no entry at
+        //     all, and the operator's dialog falls back to a translated default
+        //     that names no capability.
+        if (edge.kind === 'refuses-without' && edge.whenAbsent === undefined) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares "${edge.moduleId}:${edge.name}" ` +
+                `as \`refuses-without\` with no \`whenAbsent\` — the ledger classifies such an ` +
+                `edge exactly as it classifies an undeclared one, so the sentence is the whole ` +
+                `of what the declaration buys. Name what refuses, in the operator's words.`);
+        }
+        if (edge.kind === 'contributes-to' && edge.whenAbsent !== undefined) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares "${edge.moduleId}:${edge.name}" ` +
+                `as \`contributes-to\` with a \`whenAbsent\` — a push into an ungated registry ` +
+                `degrades nothing, so either drop the sentence or the edge is a pull and the ` +
+                `kind is \`degrades-without\`.`);
+        }
+    }
+}
+/**
+ * The `errorCodes` refusals (feature 090,
+ * `contracts/error-code-declaration.md` §2, first layer).
+ *
+ * They live here rather than in the schema for the reason the activation rules
+ * do: two of them are cross-element — a duplicate is a relationship between two
+ * entries, which an element schema cannot see — and every message has to name
+ * the module the author is looking at. All four fire on import, on the author's
+ * machine, with no instance and no database.
+ *
+ * What this layer deliberately does **not** refuse is a code **another** module
+ * declares. It sees one manifest and cannot see a second, so a partial refusal
+ * here called "the collision rule" would be a green that means "not looking".
+ * The collision rule is composition's (§3), and an in-repository collision is
+ * refused before that, in CI.
+ *
+ * Nor does it refuse a code that is a member of `ERROR_CODES`. After feature
+ * 090's migration every core module's declarations are members of it, so such a
+ * rule would refuse the platform's own manifests; there is no origin field to
+ * condition it on, and adding one would be a self-certified exemption issued by
+ * the measured party.
+ */
+function assertErrorCodeRules(m) {
+    const seenCodes = new Set();
+    for (const declaration of m.errorCodes ?? []) {
+        if (!errorCodeRe.test(declaration.code)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares error code ` +
+                `"${declaration.code}", which is not SCREAMING_SNAKE_CASE ` +
+                `(${String(errorCodeRe)}) — the code travels verbatim on the wire and ` +
+                'is the tail of the `errors.<CODE>` key its sentence is written under.');
+        }
+        if (seenCodes.has(declaration.code)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares error code ` +
+                `"${declaration.code}" twice — one code has one owner and one sentence, ` +
+                'so the second entry can only disagree with the first.');
+        }
+        seenCodes.add(declaration.code);
+        const seenTokens = new Set();
+        for (const token of declaration.tokens ?? []) {
+            if (!errorCodeTokenRe.test(token)) {
+                throw new Error(`[contracts/modules] manifest "${m.id}" declares refusal token "${token}" ` +
+                    `under "${declaration.code}", which does not match ${String(errorCodeTokenRe)} — ` +
+                    'the token is the tail of `errors.<CODE>.<token>` and a key that does not ' +
+                    'parse is a key nothing reads.');
+            }
+            if (seenTokens.has(token)) {
+                throw new Error(`[contracts/modules] manifest "${m.id}" declares refusal token "${token}" ` +
+                    `twice under "${declaration.code}" — one token is one sentence.`);
+            }
+            seenTokens.add(token);
+        }
+    }
+}
+/**
+ * The four block-declaration rules (feature 096,
+ * `specs/096-page-builder-block-ownership/contracts/block-definition.md` §1).
+ *
+ * They live here rather than in the schema for the reason the activation rules
+ * do: each is cross-field — one reads a block's `name` against the outer `id`,
+ * one reads its `category` against the manifest's own `blockCategories`, one
+ * reads those declarations against each other — and every message has to name
+ * the module the author is looking at. They fire on
+ * import, on the author's machine, with no instance and no database, which
+ * matters more here than anywhere else in this file: a block name is written
+ * into `jsonb` and never rewritten, so a wrong one caught in CI has already
+ * been typed into a manifest, and one caught after a release is permanent.
+ *
+ * `check:block-names` re-derives rules 1–3 for a manifest built without this
+ * helper — the same belt-and-braces `check-port-dependencies.ts` applies to
+ * `nonBindingDependencies`.
+ *
+ * **What this layer cannot decide is anything about a second manifest**, and
+ * the limit is the one `assertErrorCodeRules` states for itself. Two modules
+ * declaring one block name is composition's question and the check's; two
+ * modules declaring one `(key, context)` category is neither, because it is
+ * **normal and merges** — `contracts/block-definition.md` §1.1 is the ruling,
+ * the total order the merge resolves by and the two CI signals that hold
+ * in-tree modules to agreeing. Nothing here restates it.
+ *
+ * Rule 2 is therefore enforced **within the declaring manifest**, and per
+ * **context**: a block's category must be declared beside it, for every one of
+ * the block's `contexts`. That is what FR-009 asks for — a contributor declares
+ * the section in its own manifest instead of editing a shared map — and the
+ * per-context reading is T107's correction to Phase 1, which shipped "at least
+ * one". Under the weaker reading a block declared for `cms` and `email` whose
+ * section exists only in `cms` is uninsertable in the e-mail palette with no
+ * error anywhere, which is FR-009's silent-loss shape one level down.
+ */
+function assertBlockRules(m) {
+    // 4. One author, one section, one record. Judged first, and before any block
+    //    is read: a block is judged *against* `blockCategories`, so measuring it
+    //    against a set that contradicts itself reports the wrong defect. Unlike a
+    //    cross-module duplicate — which is normal and merges (§1.1) — this one
+    //    has a single author and is decidable where it is written.
+    const declaredSections = new Set();
+    for (const category of m.blockCategories ?? []) {
+        for (const context of category.contexts) {
+            const pair = `${category.key}\u0000${context}`;
+            if (declaredSections.has(pair)) {
+                throw new Error(`[contracts/modules] manifest "${m.id}" declares the palette section ` +
+                    `"${category.key}" twice for context "${context}" — a section is one record, ` +
+                    'resolved as one record, so a manifest that states it twice has stated a ' +
+                    'title, a weight and a visibility for nobody to reconcile.');
+            }
+            declaredSections.add(pair);
+        }
+    }
+    for (const block of m.blocks ?? []) {
+        // 0. The grammar, before anything reads a segment of it. A name with no
+        //    separator has no owner segment to compare against `id`, so a message
+        //    about ownership would be a message about the wrong thing. The schema
+        //    refuses it too (`BlockDefinitionSchema`), and parses last; this is the
+        //    copy that names the module, exactly as `assertErrorCodeRules` re-tests
+        //    `errorCodeRe`.
+        if (!blockNameRe.test(block.name)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares block "${block.name}", which is ` +
+                `not a namespaced block name (${String(blockNameRe)}) — the name is persisted ` +
+                'into `jsonb` and its owner segment is the only link between a stored node and ' +
+                'the module that can render it.');
+        }
+        // 1. One block, one owner, stated once. The owner is the name's first
+        //    segment and there is no `ownerModule` field to disagree with it.
+        const owner = block.name.slice(0, block.name.indexOf('.'));
+        if (owner !== m.id) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares block "${block.name}", whose ` +
+                `owner segment "${owner}" is not this module's id — a block has exactly one ` +
+                'owner and the name is where that owner is stated, so declaring it here would ' +
+                `make "${owner}" unable to own its own block.`);
+        }
+        // 2. A block offered on no surface. Refused before the category, which
+        //    cannot be judged without the contexts to judge it against.
+        if (block.contexts.length === 0) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares block "${block.name}" with an ` +
+                'empty `contexts` — a block offered on no surface appears in no palette, which ' +
+                'is a declaration with no reader.');
+        }
+        // 3. The category is a declared key, not free text, and it is declared for
+        //    **every** one of the block's contexts (T107). The block's own order is
+        //    what the message names, so an author fixing two missing contexts is
+        //    sent to the first of them rather than to whichever the set iterated.
+        const missingContext = block.contexts.find((context) => !(m.blockCategories ?? []).some((category) => category.key === block.category && category.contexts.includes(context)));
+        if (missingContext !== undefined) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares block "${block.name}" in ` +
+                `category "${block.category}", which this manifest does not declare in ` +
+                `\`blockCategories\` for context "${missingContext}" — a block's section is ` +
+                'declared beside it for every context the block is offered in, or the block ' +
+                'is uninsertable in that palette with no error anywhere.');
+        }
+    }
+}
+/**
+ * The two `demo.after` refusals (feature 113,
+ * `contracts/module-demo-data-layer.md` §4.3–§4.4).
+ *
+ * They sit beside the rules above for the reason those give: both are
+ * cross-field — one reads an entry against the outer `id`, one reads the
+ * entries against each other — and the message has to name the module the
+ * author is looking at. The element regex applies per element and can see
+ * neither.
+ *
+ * What this layer deliberately does **not** refuse is an `after` naming a
+ * module that is not installed. §4.4 rules that such an entry orders nothing
+ * and is not a finding, and this layer sees one manifest, so a rule keyed on
+ * "is that module here" would be a green that means "not looking" in a client's
+ * instance and a false red in a partial one.
+ */
+function assertDemoRules(m) {
+    if (m.demo === undefined || m.demo === false)
+        return;
+    const seen = new Set();
+    for (const after of m.demo.after ?? []) {
+        if (after === m.id) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares \`demo.after\` on itself ` +
+                `(forbidden) — the list orders this module's demo against *other* modules', ` +
+                'and a self-entry orders nothing.');
+        }
+        if (seen.has(after)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" declares \`demo.after\` "${after}" ` +
+                'twice — one ordering preference is stated once, so the second entry can ' +
+                'only agree with the first.');
+        }
+        seen.add(after);
+    }
+}
+/**
+ * A module declares only the environment inputs it **owns**
+ * (`specs/117-instance-bring-up/` FR-002, `contracts/environment-inputs.md`
+ * §R2.2).
+ *
+ * The rule this refuses is the one an author gets wrong by being helpful. Of
+ * the 28 variables the module tree reads, 7 are the platform's — `NODE_ENV`,
+ * `BACKEND_ROLE`, `STOREFRONT_BASE_URL`, `PUBLIC_API_BASE_URL`,
+ * `BACKEND_PUBLIC_URL`, `REVALIDATE_SECRET` and
+ * `SETTINGS_SECRET_ENCRYPTION_KEY` — read by thirty modules between them, and an
+ * author declaring what their module reads rather than what it owns writes the
+ * same fact into thirty manifests with thirty `describes`. Whichever a reader
+ * reaches first wins, and the other twenty-nine drift.
+ *
+ * It is refused **here**, in one manifest, at import time, because that is
+ * everything this layer can decide on its own: an `owner` naming another module
+ * or the platform is wrong whatever the rest of the estate holds. What it
+ * cannot decide — whether the name is one the *platform* already declares — is
+ * `check:env-inputs`' `module-declares-a-platform-input`, which needs the
+ * platform's declaration to answer.
+ */
+function assertEnvironmentInputRules(m) {
+    for (const input of m.env ?? []) {
+        const owner = input.owner;
+        if (owner.kind === 'module' && owner.moduleId === m.id)
+            continue;
+        const declared = owner.kind === 'module'
+            ? `the module "${owner.moduleId}"`
+            : owner.kind === 'application'
+                ? `the ${owner.application} application`
+                : 'the platform';
+        throw new Error(`[contracts/modules] manifest "${m.id}" declares the environment input ` +
+            `"${input.name}" as owned by ${declared} — a module declares only what it owns. ` +
+            `A read of somebody else's input is satisfied by *their* declaration; declaring ` +
+            `it here would be one fact with two homes and two descriptions.`);
+    }
+}
+/**
+ * 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 function defineModuleManifest(m) {
+    // Reject self-dependencies up front — Zod's array regex doesn't catch
+    // this because the id field's regex applies independently per element.
+    if (m.dependencies.includes(m.id)) {
+        throw new Error(`[contracts/modules] manifest "${m.id}" depends on itself (forbidden).`);
+    }
+    // Settings manifest's moduleCode must equal the outer id.
+    if (m.settings && m.settings.moduleCode !== m.id) {
+        throw new Error(`[contracts/modules] manifest "${m.id}" carries a settings ` +
+            `manifest with moduleCode "${m.settings.moduleCode}" (must match).`);
+    }
+    if (m.activation !== undefined) {
+        assertActivationRules(m.id, m.activation);
+    }
+    for (const edge of m.acknowledgedDependencies ?? []) {
+        if (edge.moduleId === m.id) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" acknowledges a dependency on ` +
+                `itself (forbidden).`);
+        }
+        // An acknowledged edge is a declaration that the ordinary one is
+        // impossible. Where both are present the ordinary one already carries the
+        // install order *and* the refusal, and the acknowledgement is a second
+        // record of the same edge that nothing keeps in step.
+        if (m.dependencies.includes(edge.moduleId)) {
+            throw new Error(`[contracts/modules] manifest "${m.id}" acknowledges "${edge.moduleId}", ` +
+                `which it already declares in \`dependencies\` — the acknowledgement is ` +
+                `for edges that cannot be declared, so drop one of the two.`);
+        }
+    }
+    assertNonBindingRules(m);
+    assertCapabilityRules(m);
+    assertErrorCodeRules(m);
+    assertBlockRules(m);
+    assertDemoRules(m);
+    assertEnvironmentInputRules(m);
+    return ModuleManifestSchema.parse(m);
+}
+// ---------------------------------------------------------------------------
+// Module CLI commands (feature 080, T042b / D-160.9)
+// ---------------------------------------------------------------------------
+/**
+ * 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 const MODULE_CLI_COMMAND_NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+// ---------------------------------------------------------------------------
+// Recent-activity eligibility (feature 080, T042j / D-163.1)
+// ---------------------------------------------------------------------------
+/**
+ * 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 const auditActionRe = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/;
+/**
+ * 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 const RecentActivityEntrySchema = z.object({
+    /** The `audit_log_entries.action` token, e.g. `product.create`. */
+    action: z.string().regex(auditActionRe),
+    icon: KnownIconNameSchema,
+    /** Module-namespace-relative i18n key for the verb, e.g. `activity.verb.product.create`. */
+    labelKey: z.string().min(1).max(255),
+});
+/**
+ * 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 const ModuleRecentActivitySchema = z.object({
+    entries: z.array(RecentActivityEntrySchema).min(1),
+});
+/**
+ * Identity-with-validation helper for module authors, the twin of
+ * {@link defineModuleManifest}.
+ */
+export function defineModuleRecentActivity(declaration) {
+    return ModuleRecentActivitySchema.parse(declaration);
+}
+/** The suffix every recent-activity visibility Setting code ends in. */
+export const RECENT_ACTIVITY_VISIBILITY_SETTING_SUFFIX = 'recent_activity_visible';
+/**
+ * Raised when a module's id cannot carry a Setting code — see
+ * {@link recentActivityVisibilitySettingCode}.
+ */
+export class RecentActivitySettingCodeInvalid extends Error {
+    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 function recentActivityVisibilitySettingCode(moduleId) {
+    const code = `${moduleId}.${RECENT_ACTIVITY_VISIBILITY_SETTING_SUFFIX}`;
+    if (!settingCodeRe.test(code)) {
+        throw new RecentActivitySettingCodeInvalid(`[contracts/modules] module "${moduleId}" declares recent-activity eligibility, but ` +
+            `"${code}" is not a valid setting code. A platform-internal module id (leading ` +
+            `underscore) cannot own one; the card is for a domain module's activity.`);
+    }
+    return code;
+}
+/**
+ * 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 function settingsManifestWithRecentActivity(manifest, recentActivity) {
+    if (!recentActivity)
+        return manifest.settings;
+    const entry = {
+        code: recentActivityVisibilitySettingCode(manifest.id),
+        name: `${manifest.name}: show activity on the dashboard`,
+        description: `Whether ${manifest.name}'s entries appear on the admin home dashboard's Recent ` +
+            'Activity card. Switching it off hides them from that card only — the audit trail ' +
+            'itself is unchanged and the entries stay on the audit-log screen.',
+        valueType: 'boolean',
+        defaultValue: true,
+        // Managed on /platform/modules beside the module's activation control, the
+        // surface an operator already uses for exactly this kind of choice. A
+        // second control on the generic Settings screen would be two doors onto one
+        // decision.
+        hidden: true,
+        ...(manifest.settings?.groups[0]?.code
+            ? { groupCode: manifest.settings.groups[0].code }
+            : {}),
+    };
+    if (!manifest.settings) {
+        return {
+            moduleCode: manifest.id,
+            groups: [{ code: manifest.id, name: manifest.name }],
+            settings: [{ ...entry, groupCode: manifest.id }],
+        };
+    }
+    if (manifest.settings.settings.some((s) => s.code === entry.code)) {
+        return manifest.settings;
+    }
+    return {
+        ...manifest.settings,
+        settings: [...manifest.settings.settings, entry],
+    };
+}
+// ---------------------------------------------------------------------------
+// Registry record
+// ---------------------------------------------------------------------------
+export const RegistryStateSchema = z.enum([
+    'installing',
+    'installed',
+    'disabled',
+    'uninstalled',
+]);
+/** Persisted shape of a row in `module_registrations` (admin HTTP DTO). */
+export const ModuleRegistryRecordSchema = z.object({
+    moduleId: z.string().regex(moduleIdRe),
+    state: RegistryStateSchema,
+    version: z.string(),
+    installedAt: z.iso.datetime(),
+    lastStateChangeAt: z.iso.datetime(),
+    lastInstallFailedAt: z.iso.datetime().nullable(),
+    lastInstallError: z.string().nullable(),
+});
+// ---------------------------------------------------------------------------
+// Admin HTTP — `GET /api/v1/admin/modules` response shape
+// ---------------------------------------------------------------------------
+export const ModuleListItemFlagSchema = z.enum([
+    'orphan',
+    'pending-upgrade',
+    'dep-missing',
+    'dep-disabled',
+]);
+export const ModuleListItemStateSchema = z.enum([
+    'installing',
+    'installed',
+    'disabled',
+    'uninstalled',
+    'not-installed',
+]);
+export const ModuleListItemSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    version: z.object({
+        registered: z.string().nullable(),
+        onDisk: z.string().nullable(),
+    }),
+    state: ModuleListItemStateSchema,
+    dependencies: z.array(z.string()),
+    flags: z.array(ModuleListItemFlagSchema),
+    installedAt: z.iso.datetime().nullable(),
+    lastStateChangeAt: z.iso.datetime().nullable(),
+});
+export const ModuleListResponseSchema = z.object({
+    modules: z.array(ModuleListItemSchema),
+});
+export const ModuleListQuerySchema = z.object({
+    state: z
+        .enum(['installing', 'installed', 'disabled', 'uninstalled'])
+        .optional(),
+    flag: z.enum(['orphan', 'pending-upgrade']).optional(),
+});
+// ---------------------------------------------------------------------------
+// Feature 073 — module presence projections
+// ---------------------------------------------------------------------------
+/**
+ * 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 const ModulePresenceSchema = z.object({
+    id: z.string().regex(moduleIdRe),
+    /** platformAvailable && operatorActivated. */
+    present: z.boolean(),
+    platformState: RegistryStateSchema.or(z.literal('not-installed')),
+    /** The operator axis alone. */
+    activated: z.boolean(),
+    deactivatable: z.boolean(),
+    /** The module's own declared reason, rendered next to the locked control. */
+    nonDeactivatableReason: z.string().nullable(),
+});
+/** `GET /api/v1/admin/module-presence` — every admin, no permission code. */
+export const AdminModulePresenceResponseSchema = z.object({
+    modules: z.array(ModulePresenceSchema),
+    /**
+     * The serving process is TTL-refreshing from PostgreSQL because its pub/sub
+     * link is unhealthy, so this projection may lag a flip made elsewhere by up
+     * to `FALLBACK_TTL_MS`. Reported rather than hidden: the platform screen has
+     * to be able to say "this is stale" instead of quietly showing an operator a
+     * state that is no longer true.
+     */
+    degraded: z.boolean(),
+});
+/** The storefront needs no axis detail — only whether to render at all. */
+export const StorefrontModulePresenceSchema = z.object({
+    id: z.string().regex(moduleIdRe),
+    present: z.boolean(),
+});
+/** `GET /api/v1/storefront/module-presence` — public, tag `modules:presence`. */
+export const StorefrontModulePresenceResponseSchema = z.object({
+    modules: z.array(StorefrontModulePresenceSchema),
+});
+/**
+ * `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 const ModuleActivationRequestSchema = z.object({
+    active: z.boolean(),
+});
+/** The module's presence *after* the flip, so no client recomputes it. */
+export const ModuleActivationResponseSchema = z.object({
+    module: ModulePresenceSchema,
+});
+/**
+ * `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 const ModuleDeactivationImpactSchema = z.object({
+    moduleId: z.string().regex(moduleIdRe),
+    /** Subjects with an active second factor; `null` when unavailable. */
+    activeSecondFactorUsers: z
+        .object({
+        admins: z.number().int().nonnegative(),
+        customers: z.number().int().nonnegative(),
+    })
+        .nullable(),
+});
+// ---- Feature 060 — API interceptor diagnostics (read-only admin) ----------
+/**
+ * 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 const apiInterceptorEntrySchema = z.object({
+    /** Endpoint identity, e.g. `POST /api/v1/orders`. */
+    target: z.string(),
+    phase: z.enum(['pre', 'post']),
+    order: z.number().int(),
+    /** Owning module id — execution is lifecycle-gated on this module. */
+    module: z.string(),
+    /** Interceptor id, unique within the module. */
+    id: z.string(),
+    /** Live enabled state of the owning module at request time. */
+    moduleEnabled: z.boolean(),
+});
+export const apiInterceptorListSchema = z.object({
+    items: z.array(apiInterceptorEntrySchema),
+});
+// ---------------------------------------------------------------------------
+// --- no port over the module manifests -------------------------------------
+//
+// **Which modules a deployment ships is a composition-root input, not a
+// module's port** (D-98.5). `ModuleManifestReadPort` stood here unprovided and
+// is deleted: the root builds the resolved registry and passes it *into* the
+// lifecycle orchestrator, so a `_lifecycle`-owned port over that value would
+// make the orchestrator's own input come out of the orchestrator. `_lifecycle`
+// owns what it adds — the dependency graph, the install hooks, the registry
+// rows, the operator surface — not the list. The gate could not close either:
+// `_lifecycle` is non-deactivatable, and a `providePort`'s one distinguishing
+// property over a plain registration is the 503 at the seam.
+//
+// The four modules that read manifests — `_i18n`, `admin_actions`,
+// `admin_roles`, `settings` — take `resolvedModuleRegistry` as a root-supplied
+// value and each declares the narrow view it needs. That is the rule this
+// settles: **aggregate reads build catalogues; targeted reads are refused.** A
+// `get(moduleId)` would let any module read any other module's permissions,
+// settings, palette actions and `activation` declaration and branch on them —
+// a question with no declared edge, no gate and no ledger row. Presence
+// questions go through `effectiveState`; capability questions go through a
+// port the neighbour publishes.
+// ---------------------------------------------------------------------------
+//# sourceMappingURL=modules.js.map