@endora-commerce/platform 0.100.0

package/dist/kernel/module-context.js

@@ -0,0 +1,670 @@
+import { asClass, asFunction, asValue, Lifetime, } from 'awilix';
+import { defineModuleRoutes, defineModuleWorker, subscribeForModule, } from './lifecycle/plugin-helpers.js';
+import { moduleLogger } from './logging.js';
+import { registerPort } from './ports/provide.js';
+import { DROPPED_CONTRIBUTION_SINK, isDeclaredContribution, } from './contribution-sinks.js';
+/**
+ * Is this resolver a **root-resolved constant** — awilix's `asValue`?
+ *
+ * The signature is the pair `{ resolve, isLeakSafe: true }` with no `lifetime`,
+ * and both halves are asked for, deliberately. `lifetime === undefined` alone
+ * would also match a hand-built resolver object that is *not* leak-safe, whose
+ * author meant something by leaving the field off that this function has no way
+ * to read; `isLeakSafe` alone would match a future builder that opts out of the
+ * leak check while still declaring a lifetime. Only the pair means the thing
+ * this predicate is used for in `decorate`: a constant the root registered,
+ * whose contract is one object for every resolution.
+ */
+function isRootResolvedConstant(resolver) {
+    return resolver.lifetime === undefined && resolver.isLeakSafe === true;
+}
+/** Two modules registered the same name. Names both, never just the loser. */
+export class DuplicateRegistrationError extends Error {
+    registrationName;
+    owner;
+    claimant;
+    constructor(registrationName, owner, claimant) {
+        super(`[kernel] modules '${owner}' and '${claimant}' both register '${registrationName}'. ` +
+            `A registration name is owned by exactly one module — otherwise which ` +
+            `implementation the platform runs depends on registration order. One of them ` +
+            `owns it and the other resolves it. If '${claimant}' meant to supply an ` +
+            `implementation behind a name '${owner}' published, note that rung 3 is the ` +
+            `**owner's to publish, not the claimant's to take**: ctx.di.providePort claims the ` +
+            `name, and there is no overlay exemption on the claim. A deployment that needs to ` +
+            `change what '${owner}' registers has rung 4a instead — wrap it from its own overlay ` +
+            `module with ctx.di.decorate('${registrationName}', …), which keeps '${owner}' ` +
+            `delegating through it. See docs/docs/architecture/customisation-ladder.md.`);
+        this.registrationName = registrationName;
+        this.owner = owner;
+        this.claimant = claimant;
+        this.name = 'DuplicateRegistrationError';
+    }
+}
+/**
+ * A module registered over a name a composition root supplies (D-156.6).
+ *
+ * This is the door beside the one {@link ForeignDecorationError} guards, and it
+ * stood open while that one was locked. `registerValues` claims no ownership,
+ * and `claim` threw only when a *different module* already owned the name — so for a
+ * root-registered name there was no prior owner, the claim succeeded, and
+ * awilix's `register` overwrote the entry. Any module could take `commandBus`,
+ * become its owner, and thereafter decorate it legally, because
+ * `ForeignDecorationError` fires only for a name someone else owns.
+ *
+ * Refusing the **wrap** while permitting the **replacement** is not a boundary:
+ * it reads as one and is not, and D-28 is explicit that replacement must be *a
+ * distinct, more explicit act* than decoration. Today it is the less explicit
+ * one, which is what this closes.
+ *
+ * The refused set is derived, never listed (D-100, D-156.5): a name the
+ * container already holds that no module claimed is exactly a name a
+ * composition root supplied — `registerValues` above the compose call, or
+ * `contribute()` in D-45's window. A root that starts or stops supplying a name
+ * changes the answer in the same run, and nothing has to be kept true by hand.
+ *
+ * There is no overlay exemption here, and that is not an oversight. A
+ * deployment's way to change what a root-supplied name resolves to is
+ * `ctx.di.decorate`, which it may do and which keeps core delegating; taking
+ * the name outright severs that, for every consumer at once, with nothing
+ * declared and nothing reported.
+ */
+export class ForeignRegistrationError extends Error {
+    registrationName;
+    moduleId;
+    constructor(registrationName, moduleId) {
+        super(`[kernel] module '${moduleId}' cannot register '${registrationName}': a composition ` +
+            `root supplies it, so no module owns it. Registering over it replaces what every ` +
+            `consumer of that name resolves — for the platform's own names that is the audit ` +
+            `path, the transaction boundary, the event bus and the tenant-scoped EntityManager ` +
+            `factory — and it does so with nothing declared in any manifest and nothing in the ` +
+            `override report. Reach for a seam that exists instead: subscribe to the events the ` +
+            `owner emits (ctx.subscribe), run before or after another module's endpoint ` +
+            `(ctx.interceptors), or ask the owner to publish a strategy port with a default and ` +
+            `register your implementation behind it (ctx.di.providePort, resolved through ` +
+            `lazyPort). If this is a per-deployment customisation, write it as an overlay module ` +
+            `under backend/src/apps/<deployment>/modules/ and wrap the registration with ` +
+            `ctx.di.decorate('${registrationName}', …), which keeps core delegating through it.`);
+        this.registrationName = registrationName;
+        this.moduleId = moduleId;
+        this.name = 'ForeignRegistrationError';
+    }
+}
+/** A module resolved something while it was still registering (T043). */
+export class EagerResolutionError extends Error {
+    moduleId;
+    registrationName;
+    constructor(moduleId, registrationName) {
+        super(`[kernel] module '${moduleId}' resolved '${registrationName}' while registering. ` +
+            `Registration declares; it never resolves — at registration time the modules ` +
+            `after this one have not registered yet, so an eager resolution silently depends ` +
+            `on registration order. Move the resolution into the closure that uses it: a ` +
+            `route registrar, a worker processor, a subscriber, or ctx.onBoot().`);
+        this.moduleId = moduleId;
+        this.registrationName = registrationName;
+        this.name = 'EagerResolutionError';
+    }
+}
+/**
+ * Two modules decorate one name and nothing says which wraps which (T064).
+ *
+ * Decoration order is not a formatting question: `beta(acme(core))` and
+ * `acme(beta(core))` are different implementations, and a platform that picks
+ * between them by package load order picks by accident. The failure is loud at
+ * composition rather than deferred to whichever behaviour shows up in
+ * production.
+ *
+ * A module decorating the same name twice is *not* ambiguous — it wrote both
+ * wraps, in the order it wrote them — so this fires only across modules.
+ *
+ * **The remedy is the one that exists today** (D-156.7, D-156.11 item 2;
+ * feature 107 FR-042), and as of feature 107's P3 that is the field. This
+ * message sent its reader to `decorationOrder` once before and was corrected,
+ * because the field was passed by no composition root and its declared source
+ * — `endora.config.ts` — was an F11 artefact that never existed: an author
+ * could satisfy the instruction only by editing core's own `composition.ts`,
+ * which is the one thing an overlay is built to avoid.
+ *
+ * Both roots now read it from the deployment's own
+ * `backend/src/apps/<deployment>/divergence.ts`, which is a file in the
+ * deployment's own tree. That is the coupling `compose.ts`'
+ * `decorationOrder` doc block recorded — *"the day a root starts passing this,
+ * that message is what has to change with it"* — and this is that change. The
+ * old workaround (merge the two wraps into one overlay module) is withdrawn
+ * rather than kept beside it: two remedies for one refusal is an author
+ * choosing, and the declaration is the one that keeps the two modules apart.
+ */
+export class AmbiguousDecorationError extends Error {
+    registrationName;
+    modules;
+    constructor(registrationName, modules, detail) {
+        super(`[kernel] modules ${modules.map((m) => `'${m}'`).join(' and ')} both decorate ` +
+            `'${registrationName}', and ${detail} Which override wraps which decides what the ` +
+            `platform runs, so it cannot be left to the order the modules happen to compose in. ` +
+            `Declare it in this deployment's own file — backend/src/apps/<deployment>/` +
+            `divergence.ts, the \`decorationOrder\` field, innermost first:\n` +
+            `    decorationOrder: { '${registrationName}': [` +
+            `${modules.map((m) => `'${m}'`).join(', ')}] }\n` +
+            `It is checked, never applied: the composer keeps emitting in its own order and this ` +
+            `asserts that order was the intended one, so a declaration that stops matching ` +
+            `refuses here rather than silently reordering anything. ` +
+            `This is rung 4a — decoration — and it is the most invasive seam short of a fork. ` +
+            `If the two wraps genuinely belong to different owners, one of them is asking for a ` +
+            `seam rather than a wrap: rung 3, ask that owner to publish a strategy port ` +
+            `(ctx.di.providePort) you resolve with lazyPort. See ` +
+            `docs/docs/architecture/customisation-ladder.md.`);
+        this.registrationName = registrationName;
+        this.modules = modules;
+        this.name = 'AmbiguousDecorationError';
+    }
+}
+/**
+ * A module decorated a registration it does not own (issue #203).
+ *
+ * `decorate` used to check only that *something* was registered under the name.
+ * Both halves of the answer were already in hand at the call site — the
+ * decorating module's id, and the owner from the ownership ledger — and the
+ * record kept both while comparing neither, so any module could wrap any entry
+ * in the container: `commandBus` to observe every audited write,
+ * `auditLogService` to change what the audit records, another module's read
+ * port to sit between a consumer and its owner with nothing declared anywhere.
+ *
+ * Refused rather than ledgered. A ledger makes the platform's answer "we will
+ * notice", and what is at stake here is not a coupling to drain but the
+ * integrity of the audit path.
+ *
+ * The exemption is the **deployment's own** overlay module, which is a
+ * different act: core wrapping core is a coupling nothing declares, while a
+ * deployment wrapping core is the sanctioned per-deployment customisation seam
+ * (feature 072 replaced file shadowing with it). It is not a claim a module can
+ * make about itself — the generated composer sets it from the root the module
+ * was discovered under, `backend/src/apps/<deployment>/modules/`.
+ *
+ * **The exemption is total, and this paragraph is here because the one above it
+ * reads as though it were not** (D-156.4, D-156.11 item 3). `overlay` is a
+ * per-module boolean and the check below is name-unscoped, so an overlay module
+ * may wrap *anything the container holds* — not merely "core", but the
+ * root-registered set no module owns: `commandBus`, `auditLogService`,
+ * `eventBus`, `emFactory`. Those are precisely the names this error was
+ * introduced to defend — `commandBus` to observe every audited write,
+ * `auditLogService` to change what the audit records — so the rule as stated
+ * and the code as written disagree, and the code is the one that runs.
+ *
+ * **That is deliberate and it stays.** A deployment owns its instance outright:
+ * it edits its own `apps/<deployment>/` tree, it builds the image, and it
+ * answers to nobody but itself — so refusing it `commandBus` would defend the
+ * audit path against the one party entitled to change it, while a deployment
+ * that wanted to could simply do it another way. The defended set is a boundary
+ * against *strangers*, and a deployment is not one.
+ *
+ * This paragraph used to rest part of that argument on a second mechanism — a
+ * file under `backend/src/apps/<deployment>/decorations/` that could wrap any
+ * registration. That seam is retired: it was wired for one hard-coded name, and
+ * D-103 had already made an overlay module's `ctx.di.decorate` do the same job
+ * with none of its costs. The argument stands on the sentence above it, which
+ * never needed the second mechanism.
+ *
+ * **An installed extension package is** (D-156.1–D-156.9). `loadPackageModuleEntries`
+ * therefore sets no `overlay` flag, and that is the ruled behaviour rather than
+ * a placeholder: if a grant is ever built it is keyed per
+ * `(package, registration name)`, read from an artefact the instance owns and
+ * the package cannot write, and refused outright for any name whose owner is
+ * `undefined`. This flag is not the mechanism — widening it, re-typing it to an
+ * origin enum or setting it from a declaration hands a stranger the audit path
+ * along with whatever it asked for. Do not narrow the check below to match the
+ * older prose; the prose was what was wrong.
+ */
+export class ForeignDecorationError extends Error {
+    registrationName;
+    moduleId;
+    owner;
+    constructor(registrationName, moduleId, 
+    /** The registering module, or `undefined` when a composition root registered it. */
+    owner) {
+        const owned = owner === undefined
+            ? `a composition root registers it, so no module owns it`
+            : `'${owner}' registers it`;
+        super(`[kernel] module '${moduleId}' cannot decorate '${registrationName}': ${owned}. ` +
+            `That is rung 4a — decoration — and it is not offered to a core module: it ` +
+            `rewrites what every consumer of that name resolves, so it is the owner's to do, ` +
+            `and reaching into another module's registration is a coupling nothing declares ` +
+            `and nothing reports. Drop to the highest rung that works for you, in order:\n` +
+            `  rung 3 — ask ${owner === undefined ? 'the composition root' : `'${owner}'`} to ` +
+            `publish a strategy port (ctx.di.providePort) and resolve it with ` +
+            `lazyPort<T>(ctx, '<name>'), declaring the edge in your manifest;\n` +
+            `  rung 2 — if what you need is around an endpoint that module already serves, ` +
+            `ctx.interceptors([{ target: '<METHOD> <route>', phase, handler }]);\n` +
+            `  rung 1 — if the work is additive and something already happened, ` +
+            `ctx.subscribe('<event>', handler).\n` +
+            `If this is a per-deployment customisation, rung 4a is yours: write it as an ` +
+            `overlay module under backend/src/apps/<deployment>/modules/ — that is the one ` +
+            `decoration across owners the platform sanctions. See ` +
+            `docs/docs/architecture/customisation-ladder.md.`);
+        this.registrationName = registrationName;
+        this.moduleId = moduleId;
+        this.owner = owner;
+        this.name = 'ForeignDecorationError';
+    }
+}
+/**
+ * The registration being wrapped belongs to an **installed extension package**
+ * (D-176 Q3, ruled by the owner on 2026-08-25).
+ *
+ * A per-deployment overlay may decorate anything core or another of the
+ * deployment's own modules registers — that seam is unchanged and is the whole
+ * of feature 072's answer to file shadowing. It may **not** decorate a
+ * registration an installed package owns, and until the drain landed it could
+ * not: `composition.ts` composes overlays before packages, so the name was not
+ * in the container yet and `hasRegistration` refused for a reason that had
+ * nothing to do with the wrap. The drain removes that accident, so the refusal
+ * has to be stated here or the same change would silently grant the capability
+ * the owner declined.
+ *
+ * **Why it is refused today.** The mechanism that would make it safe does not
+ * exist. A package's `exports` map publishes `registerModule`, its entities, its
+ * migrations and `./ports`; a container name it registers internally is
+ * published by none of them, so a deployment wrapping one is writing against a
+ * name the package never offered and can rename in a patch release.
+ * `check:port-shape` signal 3 already refuses a *module* resolving an
+ * unpublished container name — this is the same violation one level out. And
+ * feature 057's `tsc` contract gate does not transfer: there is no
+ * `*.interface.ts` here, so the compiler would hold the wrap to a `dist/*.d.ts`
+ * that moves under `pnpm update`, authored by someone the deployment does not
+ * employ.
+ *
+ * **Why it does not say "never".** D-106.2 has already committed the platform to
+ * third-party modules being first-class in schema; refusing decoration outright
+ * would make them second-class in behaviour with forking as the only recourse.
+ * The exit the owner named is a package **declaring** which of its registrations
+ * are decoratable — `./ports` is the natural home for it, where changing the
+ * shape costs a major bump — so the message says *not offered yet* rather than
+ * *forbidden*, and names it.
+ *
+ * **It also answers for a decorator that is not an overlay**, and that rules
+ * nothing D-176 left open. A core module or a second package wrapping a
+ * package's registration was refused before this error existed
+ * ({@link ForeignDecorationError}) and is refused after it; what moves is the
+ * reason the author is given, because `ForeignDecorationError`'s remedy is
+ * *"write it as an overlay module"* — advice that, for a package owner, leads
+ * straight back to this refusal.
+ */
+export class PackageDecorationNotOfferedError extends Error {
+    registrationName;
+    moduleId;
+    owner;
+    constructor(registrationName, moduleId, 
+    /** The installed package's module id. */
+    owner) {
+        super(`[kernel] module '${moduleId}' cannot decorate '${registrationName}': '${owner}' is an ` +
+            `installed extension package, and wrapping a registration a package owns is not ` +
+            `offered yet. A deployment's overlay module may still wrap anything core or its own ` +
+            `overlay modules register — that seam is unchanged. What is missing for a package is ` +
+            `the declaration: its exports map publishes registerModule, its entities, its ` +
+            `migrations and './ports', and a container name it registers internally is published ` +
+            `by none of them — so this wrap would be written against a name '${owner}' never ` +
+            `offered and may rename in a patch release. The way this opens is for the package to ` +
+            `declare which of its registrations are decoratable, './ports' being the natural home ` +
+            `for it, where changing the shape costs a major version bump: ask its author for that ` +
+            `declaration. Until then, drop to the highest rung that works, in order: ` +
+            `rung 3, a strategy port '${owner}' publishes and you resolve with ` +
+            `lazyPort<T>(ctx, '<name>'); rung 2, ctx.interceptors around an endpoint it already ` +
+            `serves; rung 1, ctx.subscribe on an event it already emits. See ` +
+            `docs/docs/architecture/customisation-ladder.md.`);
+        this.registrationName = registrationName;
+        this.moduleId = moduleId;
+        this.owner = owner;
+        this.name = 'PackageDecorationNotOfferedError';
+    }
+}
+export function createDecorationQueue() {
+    const pending = [];
+    return {
+        pending,
+        enqueue(entry) {
+            pending.push(entry);
+        },
+    };
+}
+export function createDecorationLedger(decorationOrder = {}) {
+    const entries = [];
+    let counter = 0;
+    return {
+        entries,
+        innerNameFor(name) {
+            counter += 1;
+            return `${name}$undecorated$${counter}`;
+        },
+        record(name, moduleId, owner) {
+            const prior = entries.filter((entry) => entry.name === name);
+            const priorModules = [...new Set(prior.map((entry) => entry.moduleId))];
+            if (priorModules.some((id) => id !== moduleId)) {
+                const applied = [...new Set([...priorModules, moduleId])];
+                const declared = decorationOrder[name];
+                if (declared === undefined) {
+                    throw new AmbiguousDecorationError(name, applied, 'no order is declared for it.');
+                }
+                const missing = applied.filter((id) => !declared.includes(id));
+                if (missing.length > 0) {
+                    throw new AmbiguousDecorationError(name, applied, `the declared order omits ${missing.map((id) => `'${id}'`).join(', ')}.`);
+                }
+                // A declaration that does not bind is worse than none: it reads as a
+                // decision and behaves as a comment.
+                for (let i = 1; i < applied.length; i += 1) {
+                    if (declared.indexOf(applied[i]) < declared.indexOf(applied[i - 1])) {
+                        throw new AmbiguousDecorationError(name, applied, `they compose in the order ${applied.map((id) => `'${id}'`).join(' → ')}, which ` +
+                            `contradicts the declared ${declared.map((id) => `'${id}'`).join(' → ')}.`);
+                    }
+                }
+            }
+            const entry = { name, moduleId, owner, depth: prior.length + 1 };
+            entries.push(entry);
+            return entry;
+        },
+    };
+}
+export function createRegistrationOwnership() {
+    const owners = new Map();
+    return {
+        claim(name, moduleId) {
+            const owner = owners.get(name);
+            if (owner !== undefined && owner !== moduleId) {
+                throw new DuplicateRegistrationError(name, owner, moduleId);
+            }
+            owners.set(name, moduleId);
+        },
+        ownerOf: (name) => owners.get(name),
+    };
+}
+export function createModuleRegistrationSink() {
+    return {
+        plugins: [],
+        rootPlugins: [],
+        workers: [],
+        unsubscribes: [],
+        bootHooks: [],
+    };
+}
+export function createModuleContext(options) {
+    const { module, container, eventBus, sink, log, interceptorRegistry, ownership } = options;
+    const isRegistering = options.isRegistering ?? (() => false);
+    const isDeploymentOverlay = options.overlay === true;
+    const decorationQueue = options.decorationQueue;
+    const installedPackageModuleIds = options.installedPackageModuleIds ?? new Set();
+    /**
+     * Every name **this context** registered (issue #203).
+     *
+     * The ownership ledger is the composition's record and the authority
+     * wherever there is one, but a context built by hand carries none — and
+     * "no ledger" must not read as "no owner to compare", which would make the
+     * decoration rule off by construction for exactly the contexts a test
+     * builds. This answers the same question locally, and it cannot drift from
+     * the ledger: with a ledger present, every name in here is already claimed
+     * in it, so the fallback is unreachable.
+     */
+    const ownRegistrations = new Set();
+    const decorations = options.decorations ?? createDecorationLedger();
+    /**
+     * Who owns `name` right now, as `decorate` has always asked it.
+     *
+     * `undefined` has two readings and only one of them is a hole: the name is
+     * not in the container at all (nobody owns it, and registering it is the
+     * ordinary case), or the container holds it and no module claimed it — which
+     * happens exactly when a composition root registered it. The callers below
+     * discriminate; this function does not, because the two questions share this
+     * one answer and duplicating it is how they would drift.
+     */
+    const ownerOf = (name) => ownership?.ownerOf(name) ?? (ownRegistrations.has(name) ? module.id : undefined);
+    /**
+     * The registration half of the ownership rule (D-156.6).
+     *
+     * Three outcomes, and the order is the point:
+     *
+     *  - another **module** owns the name — untouched, `claim` still throws
+     *    `DuplicateRegistrationError`, which names both modules and tells the
+     *    loser to decorate. That error can say things this one cannot;
+     *  - a composition **root** supplies it — refused here, because there is no
+     *    owner to ask for a seam and the names in that set are the platform's own;
+     *  - nobody holds it — the ordinary case, and the one every registration in a
+     *    bare-core composition takes: all 291 of them, against 17 root-supplied
+     *    names, with an empty intersection measured in both roots.
+     *
+     * Asked before anything is claimed or written, so a refused batch leaves the
+     * container and the ownership ledger exactly as they were.
+     */
+    const assertRegistrable = (name) => {
+        if (ownerOf(name) === undefined && container.hasRegistration(name)) {
+            throw new ForeignRegistrationError(name, module.id);
+        }
+    };
+    /**
+     * One proxy per context, over this module's own container. It is stable
+     * across calls so a module that captures `ctx.cradle()` during registration
+     * still hits the phase guard when it later reads a name off the captured
+     * object.
+     */
+    const cradleProxy = new Proxy(Object.create(null), {
+        get(_target, property) {
+            // A symbol here is the runtime probing the object (`Symbol.toPrimitive`,
+            // `then` on an accidental await); no registration can carry that name.
+            if (typeof property === 'symbol')
+                return undefined;
+            if (isRegistering())
+                throw new EagerResolutionError(module.id, property);
+            // **A contribution to a registry that was never registered is dropped**
+            // (owner ruling, 2026-09-12; feature 117, A4). Asked here, at the
+            // container resolution, because this is where the throw comes from and
+            // because it is the only layer that needs no cooperation from the module:
+            // a contributor pushes without knowing whether the registry exists in
+            // this composition, which is the whole of the ruling.
+            //
+            // The conjunction is what keeps it from being "an unregistered name
+            // resolves to something": this module's **own** manifest must declare
+            // this exact name as `contributes-to`, and nothing in this composition
+            // may register it. A name nobody registers anywhere is still
+            // `check:port-dependencies`' `unowned-name` and still fails the build.
+            // See `contribution-sinks.ts` for the full reasoning and its bound.
+            if (isDeclaredContribution(module.id, property) &&
+                !container.hasRegistration(property)) {
+                return DROPPED_CONTRIBUTION_SINK;
+            }
+            return container.cradle[property];
+        },
+        has(_target, property) {
+            return typeof property === 'string' && container.hasRegistration(property);
+        },
+    });
+    return {
+        module,
+        di: {
+            register(registrations) {
+                // Two passes: every name is checked before any is claimed, so a batch
+                // holding one refused name registers none of the others.
+                for (const name of Object.keys(registrations))
+                    assertRegistrable(name);
+                for (const name of Object.keys(registrations)) {
+                    ownership?.claim(name, module.id);
+                    ownRegistrations.add(name);
+                }
+                container.register(registrations);
+            },
+            providePort(name, registration) {
+                // The same claim, so the same guard: a port registration that skipped
+                // it would be the side door beside the side door.
+                assertRegistrable(name);
+                ownership?.claim(name, module.id);
+                ownRegistrations.add(name);
+                registerPort(container, module.id, name, registration);
+            },
+            /**
+             * **Enqueued here, applied at the drain** (D-176).
+             *
+             * This used to write the container while the registration pass was still
+             * running, and that made array order decide whether a decoration was
+             * possible at all: `composition.ts` passes overlays before packages, so a
+             * deployment's overlay wrapping an installed package's registration was
+             * refused because the name was not there *yet* — measured as T053(c)
+             * (!967). D-45 says registration order is meaningless because registration
+             * resolves nothing, which is true of every other seam and was not true of
+             * this one: `decorate` read and rewrote the container **without**
+             * resolving, so the `registering` guard never saw it.
+             *
+             * `AmbiguousDecorationError` in this same file already states the
+             * principle — *"it cannot be left to the order the modules happen to
+             * compose in"* — and the drain applies it here. One registration pass,
+             * then one drain: no sort, no dependency graph, and `hasRegistration`
+             * keeps its real job, which after the drain is the only thing it can
+             * mean — a decoration of a name nothing in the composition ever
+             * registers.
+             *
+             * A context with no queue (hand-built, or the post-registration one
+             * `contextFor` returns) applies at the call, exactly as before: there is
+             * no drain behind either, so queueing would be a wrap nobody applies.
+             */
+            decorate(name, wrap) {
+                const apply = () => {
+                    if (!container.hasRegistration(name)) {
+                        throw new Error(`[kernel] module '${module.id}' cannot decorate '${name}': nothing is registered ` +
+                            `under that name, by any module in this composition. Decoration wraps an ` +
+                            `existing registration and is applied after every module has registered, so ` +
+                            `this is not a question of order — check the spelling of the name, and that ` +
+                            `the module that owns it is composed at all.`);
+                    }
+                    // Whose registration is this? Asked before anything is written, for
+                    // the same reason the ambiguity check is: a refused decoration must
+                    // leave the container as it was rather than half-wrapped.
+                    //
+                    // An owner of `undefined` means nobody claimed the name — a
+                    // composition root registered it (`commandBus`, `auditLogService`,
+                    // `redis`) — and for a module that is refused like any other foreign
+                    // registration. Reading "unowned" as "fair game" would leave the
+                    // highest-value targets in the platform the only undefended ones.
+                    //
+                    // `isDeploymentOverlay` is exempt from **both** halves, not just the
+                    // core-owned one, and the condition says so by being name-unscoped: a
+                    // deployment's overlay module may wrap `commandBus` too. That is the
+                    // ruled behaviour (D-156.4) — a deployment owns its instance and is
+                    // not the stranger this guard defends against — and it is why the flag
+                    // is never the mechanism by which an installed *package* would be
+                    // granted decoration. See `ForeignDecorationError`'s doc block; it is
+                    // written out there rather than here because the older prose said
+                    // otherwise and the next reader's instinct is to "fix" this line.
+                    const owner = ownerOf(name);
+                    if (owner !== module.id) {
+                        // D-176 Q3, and it is asked **before** the overlay exemption
+                        // because that exemption is exactly what it narrows: an installed
+                        // package's registration is the one thing a deployment may not
+                        // wrap. For every other decorator the answer was already "no" and
+                        // stays "no" — only the reason improves, since
+                        // `ForeignDecorationError` would send its reader to write an
+                        // overlay module, which lands back here.
+                        if (owner !== undefined && installedPackageModuleIds.has(owner)) {
+                            throw new PackageDecorationNotOfferedError(name, module.id, owner);
+                        }
+                        if (!isDeploymentOverlay) {
+                            throw new ForeignDecorationError(name, module.id, owner);
+                        }
+                    }
+                    decorations.record(name, module.id, owner);
+                    const inner = container.getRegistration(name);
+                    // Re-registering the previous resolver under a private name keeps the
+                    // inner instance resolving through the SAME container or scope, so its
+                    // lifetime is preserved and a chain of decorations composes cleanly.
+                    // The name comes from the composition-wide ledger: a per-context
+                    // counter would hand two modules' first decorations the same private
+                    // name, and the second would overwrite the first's inner registration
+                    // with the first's own wrapper — a chain that resolves into itself.
+                    const innerName = decorations.innerNameFor(name);
+                    container.register({ [innerName]: inner });
+                    container.register({
+                        // Preserve the inner registration's lifetime, so decorating does
+                        // not silently turn a singleton into a per-resolution instance.
+                        //
+                        // An `asValue` resolver carries no `lifetime`, and reading that
+                        // field alone is what used to kill the boot: `asValue` is the
+                        // **pair** `{ resolve, isLeakSafe: true }`, and `isLeakSafe` is
+                        // what `throwIfLifetimeLeakage` short-circuits on. A wrapper
+                        // registered TRANSIENT drops the partner and asserts the one
+                        // lifetime the pair never meant, so the first SINGLETON ancestor to
+                        // resolve the name raised `AwilixResolutionError: … has a shorter
+                        // lifetime than its ancestor` — measured on `commandBus` behind
+                        // `catalog`, which is a name D-156.4 sanctions a deployment overlay
+                        // wrapping by name (`specs/124-instance-customisation-gap/` FR-003).
+                        //
+                        // The pair means "root-resolved constant", which is SINGLETON: two
+                        // resolutions give the same object, which is the whole contract of
+                        // the name being wrapped, and a singleton is never a lifetime leak,
+                        // so the strict check passes by construction rather than by being
+                        // switched off. Every other inner keeps exactly what it had, and a
+                        // wrap reaching for a genuinely scoped registration still throws.
+                        [name]: isRootResolvedConstant(inner)
+                            ? asFunction((cradle) => wrap(cradle[innerName], cradle)).singleton()
+                            : asFunction((cradle) => wrap(cradle[innerName], cradle)).setLifetime(inner.lifetime ?? Lifetime.TRANSIENT),
+                    });
+                };
+                if (decorationQueue === undefined) {
+                    apply();
+                    return;
+                }
+                decorationQueue.enqueue({ moduleId: module.id, name, apply });
+            },
+        },
+        asClass: (ctor) => asClass(ctor),
+        asFunction: (fn) => asFunction(fn),
+        asValue: (value) => asValue(value),
+        cradle: () => cradleProxy,
+        routes(register) {
+            sink.plugins.push(defineModuleRoutes(module.id, register));
+        },
+        ungatedRoutes(reason, register) {
+            if (reason.trim().length === 0) {
+                throw new Error(`[kernel] module '${module.id}' registered ungated routes without a reason. ` +
+                    `Gating is the default; the exemption exists for surfaces that report on the ` +
+                    `platform itself (liveness and readiness probes, module presence), which cannot ` +
+                    `be gated on a part of the platform without becoming circular. State which one ` +
+                    `this is, or use ctx.routes().`);
+            }
+            // The same encapsulated child context `defineModuleRoutes` uses, minus
+            // the `onRequest` gate — so the only difference between the two seams is
+            // the one this exemption is about.
+            sink.plugins.push(async (app) => {
+                await app.register(async (scoped) => {
+                    await register(scoped);
+                });
+            });
+        },
+        rootPlugin(reason, plugin) {
+            if (reason.trim().length === 0) {
+                throw new Error(`[kernel] module '${module.id}' registered a root plugin without a reason. ` +
+                    `This is the one seam that reaches every other module, so it states what it ` +
+                    `decorates and why that cannot live inside the module's own context.`);
+            }
+            sink.rootPlugins.push(plugin);
+        },
+        worker(worker, workerOptions) {
+            const registered = defineModuleWorker(module.id, worker, workerOptions);
+            sink.workers.push(registered);
+            return registered;
+        },
+        subscribe(event, handler) {
+            sink.unsubscribes.push(subscribeForModule(module.id, eventBus, event, handler));
+        },
+        interceptors(entries) {
+            if (!interceptorRegistry) {
+                throw new Error(`[kernel] module '${module.id}' registered an API interceptor, but this composition ` +
+                    `root mounts no interceptor registry.`);
+            }
+            for (const entry of entries) {
+                interceptorRegistry.register({ ...entry, module: module.id });
+            }
+        },
+        onBoot(hook) {
+            sink.bootHooks.push(hook);
+        },
+        // Issue #269 — attribution and request correlation are applied here, over
+        // whatever destination the root passed, so they hold for every root and for
+        // a context built by hand in a test. The composer's own lines (the
+        // decoration report) are the composition's, not a module's, and go to the
+        // unwrapped `log`.
+        log: moduleLogger(module.id, log),
+    };
+}
+//# sourceMappingURL=module-context.js.map