@endora-commerce/platform 0.100.0

package/dist/kernel/module-context.d.ts

@@ -0,0 +1,563 @@
+import { type BuildResolver, type Constructor, type DisposableResolver, type Resolver } from 'awilix';
+import type { FastifyInstance } from 'fastify';
+import type { Worker } from 'bullmq';
+import type { ModulePlugin } from '../http/server.js';
+import type { EventBus } from '../events/bus.js';
+import type { ApiInterceptorRegistry } from '../http/interceptors/index.js';
+import type { InterceptorRegistration } from '../http/interceptors/types.js';
+import { type DefineModuleWorkerOptions } from './lifecycle/plugin-helpers.js';
+import type { KernelContainer, KernelCradle } from './container.js';
+import { type PlatformLogger } from './logging.js';
+/**
+ * `ModuleContext` — the only kernel surface a module sees (feature 072).
+ *
+ * A module's backend entry exports one `registerModule(ctx)` and its entity
+ * list, and nothing about it appears anywhere else. Every surface it can
+ * contribute goes through this object, which means the lifecycle gating of
+ * Constitution XVII holds **by construction**: `routes`, `worker` and
+ * `subscribe` are wrapped in the `_lifecycle` helpers here, so a module cannot
+ * forget to wrap and cannot gate per handler.
+ *
+ * Modules never import `awilix`; `scripts/check-container-imports.ts` enforces
+ * it, so the container stays swappable behind this seam.
+ */
+/**
+ * What `ctx.asClass` / `ctx.asFunction` / `ctx.asValue` produce.
+ *
+ * These are awilix's own types, re-exported under kernel names so a module
+ * spells the container's vocabulary without importing `awilix` — that import is
+ * forbidden by a static check (T041), which is what keeps the container
+ * swappable behind `ModuleContext`.
+ */
+export type Registration<T = unknown> = Resolver<T>;
+/** The lifetime-selecting builder returned by `ctx.asClass` / `ctx.asFunction`. */
+export type RegistrationBuilder<T> = BuildResolver<T> & DisposableResolver<T>;
+/**
+ * A module's explicit boot phase (FR-021).
+ *
+ * Registration is lazy: a service nothing resolves is never constructed. Some
+ * work genuinely has to run at boot anyway — pushing a descriptor into another
+ * module's registry, seeding a system row, validating a cipher key — and it
+ * needs to resolve things, which registration may not do. So it is a named
+ * phase that runs **after every module has registered**, each hook inside its
+ * own `enterSystemScope`, rather than a side effect smuggled into a factory or
+ * into route attachment (where a `BACKEND_ROLE=worker` process would never
+ * reach it).
+ */
+export type ModuleBootHook = () => void | Promise<void>;
+/**
+ * Which module owns which registration name (T042).
+ *
+ * A name is owned by exactly one module. Two modules registering the same name
+ * is not "the later one wins" — it is a platform whose behaviour depends on
+ * registration order, and the bug it produces is unfindable because both
+ * modules look correct in isolation. Changing another module's registration is
+ * `ctx.di.decorate`, which is a different, deliberate act and is not routed
+ * through this ledger.
+ */
+export interface RegistrationOwnership {
+    /** @throws {DuplicateRegistrationError} when another module already owns `name`. */
+    claim(name: string, moduleId: string): void;
+    ownerOf(name: string): string | undefined;
+}
+/** Two modules registered the same name. Names both, never just the loser. */
+export declare class DuplicateRegistrationError extends Error {
+    readonly registrationName: string;
+    readonly owner: string;
+    readonly claimant: string;
+    constructor(registrationName: string, owner: string, claimant: string);
+}
+/**
+ * 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 declare class ForeignRegistrationError extends Error {
+    readonly registrationName: string;
+    readonly moduleId: string;
+    constructor(registrationName: string, moduleId: string);
+}
+/** A module resolved something while it was still registering (T043). */
+export declare class EagerResolutionError extends Error {
+    readonly moduleId: string;
+    readonly registrationName: string;
+    constructor(moduleId: string, registrationName: string);
+}
+/**
+ * One applied decoration, as the override report lists it (T065).
+ *
+ * "Who is overriding what" is two questions, so the record answers both: the
+ * module that wrote the wrap, and the module that owns the registration being
+ * wrapped. A report that answers only the first sends its reader back to grep
+ * for the second, which is the state this replaces — a client override was
+ * discoverable by noticing a file existed under `apps/<deployment>/`.
+ */
+export interface DecorationRecord {
+    readonly name: string;
+    readonly moduleId: string;
+    /** The module that registered `name`; `undefined` if a composition root did. */
+    readonly owner: string | undefined;
+    /** 1-based position in the wrapping chain for this name; innermost first. */
+    readonly depth: number;
+}
+/**
+ * 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 declare class AmbiguousDecorationError extends Error {
+    readonly registrationName: string;
+    readonly modules: readonly string[];
+    constructor(registrationName: string, modules: readonly string[], detail: string);
+}
+/**
+ * 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 declare class ForeignDecorationError extends Error {
+    readonly registrationName: string;
+    readonly moduleId: string;
+    /** The registering module, or `undefined` when a composition root registered it. */
+    readonly owner: string | undefined;
+    constructor(registrationName: string, moduleId: string, 
+    /** The registering module, or `undefined` when a composition root registered it. */
+    owner: string | undefined);
+}
+/**
+ * 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 declare class PackageDecorationNotOfferedError extends Error {
+    readonly registrationName: string;
+    readonly moduleId: string;
+    /** The installed package's module id. */
+    readonly owner: string;
+    constructor(registrationName: string, moduleId: string, 
+    /** The installed package's module id. */
+    owner: string);
+}
+/**
+ * One decoration, queued while the modules register and applied at the drain
+ * (D-176).
+ *
+ * `apply` is a closure over the deciding module's context — its id, its overlay
+ * marking, the container it registered into — so the guards run at the drain
+ * with everything they had at the call site. The `moduleId` beside it is what
+ * the composer attributes a failure to: the refusal no longer happens inside
+ * the decorating module's `registerModule`, so the entry has to carry it or the
+ * message loses the one fact an operator needs.
+ */
+export interface PendingDecoration {
+    readonly moduleId: string;
+    readonly name: string;
+    apply(): void;
+}
+/**
+ * The composition's decoration queue — a **queue**, and the shape is the point.
+ *
+ * `ctx.di.decorate` enqueues and {@link composeModules} drains after the last
+ * module has registered, which is what makes registration order stop deciding
+ * whether a decoration is possible at all (D-45's sentence: registration
+ * resolves nothing, so its order is meaningless — true of every other seam, and
+ * `decorate` was the one that read and rewrote the container without resolving,
+ * so the `registering` guard never saw it).
+ *
+ * Call order is preserved because a queue preserves it. That is not incidental:
+ * {@link AmbiguousDecorationError} exempts a module decorating one name twice
+ * *because it wrote both wraps in the order it wrote them*, and a `Map` keyed by
+ * name would have to reconstruct that order rather than keep it.
+ */
+export interface DecorationQueue {
+    enqueue(pending: PendingDecoration): void;
+    readonly pending: readonly PendingDecoration[];
+}
+export declare function createDecorationQueue(): DecorationQueue;
+/**
+ * The composition-wide record of decorations, shared by every module context of
+ * one composition.
+ *
+ * It is shared for two reasons and both are defects if it is not. The private
+ * name a decoration parks its inner resolver under must be unique **per
+ * container**: a per-context counter gives the first decoration of two
+ * different modules the same private name, so the second overwrites the first's
+ * inner registration with the first's own wrapper and the chain resolves into
+ * itself. And the ambiguity check is by definition cross-module, so it cannot
+ * live in anything a single module owns.
+ */
+export interface DecorationLedger {
+    /** @throws {AmbiguousDecorationError} when two modules decorate `name` unordered. */
+    record(name: string, moduleId: string, owner: string | undefined): DecorationRecord;
+    /** A private name for the resolver being wrapped, unique across the container. */
+    innerNameFor(name: string): string;
+    readonly entries: readonly DecorationRecord[];
+}
+export declare function createDecorationLedger(decorationOrder?: Readonly<Record<string, readonly string[]>>): DecorationLedger;
+export declare function createRegistrationOwnership(): RegistrationOwnership;
+export interface ModuleContext {
+    readonly module: {
+        readonly id: string;
+        readonly version: string;
+    };
+    readonly di: {
+        register(registrations: Record<string, Registration>): void;
+        /**
+         * Register a name **other modules resolve** — a port (FR-040).
+         *
+         * The difference from `register` is fail-closed cross-module resolution:
+         * resolving a port while this module is not effectively present throws
+         * `ModuleDisabledError` (503 `MODULE_DISABLED`, with `Retry-After`) rather
+         * than handing a consumer a live service belonging to a module the
+         * operator switched off (Constitution XVII).
+         *
+         * A module's *internal* registrations stay on `register`: gating those
+         * would break the one surface that must answer while its module is
+         * absent — `ctx.ungatedRoutes`, i.e. the liveness probe.
+         */
+        providePort<T>(name: string, registration: Registration<T>): void;
+        /**
+         * Wrap an existing registration (D-28: decoration, never replacement), so a
+         * client override keeps delegating to core and core fixes keep flowing
+         * through it.
+         */
+        decorate<T>(name: string, wrap: (inner: T, cradle: KernelCradle) => T): void;
+    };
+    asClass<T>(ctor: Constructor<T>): RegistrationBuilder<T>;
+    /**
+     * `C` is the cradle shape **this factory needs**, declared by the module and
+     * defaulted to the kernel's. Annotate the parameter and it is inferred:
+     *
+     * ```ts
+     * ctx.asFunction(({ emFactory, blogCacheService }: BlogCradle) => …)
+     * ```
+     *
+     * Widening it to `KernelCradle` would make every dependency `unknown` at the
+     * one place where naming the dependency is the point of the exercise.
+     */
+    asFunction<T, C = KernelCradle>(fn: (cradle: C) => T): RegistrationBuilder<T>;
+    asValue<T>(value: T): Registration<T>;
+    /**
+     * The resolution surface, for **deferred** use only — inside a route
+     * registrar, a worker processor, a subscriber or an `onBoot` hook. Reading a
+     * name from it while `registerModule` is still running throws
+     * {@link EagerResolutionError} (T043).
+     *
+     * Two things about it are load-bearing:
+     *
+     *  - **It resolves through the container this module registered into**, and
+     *    never through the ambient request scope. That makes what a name resolves
+     *    to a property of the composition rather than of where the call happens,
+     *    and it is why the module's registrations must be `singleton()` or
+     *    `transient()`. Per-request state is read through its own accessor —
+     *    `getResolvedChannel()` for the sales channel, `getTenantContext()` for
+     *    tenancy — not through this cradle. Resolving `scoped()` registrations
+     *    from a module belongs to Phase 5, where the generated composer owns the
+     *    whole boot and one container is unambiguously *the* root.
+     *  - **`C` is asserted by the caller**, because the container is the runtime
+     *    authority and an unknown name throws rather than yielding `undefined`.
+     *    Declaring the narrow shape a module needs is the port rule of
+     *    `contracts/module-context.md` spelled in types.
+     */
+    cradle<C extends object = KernelCradle>(): C;
+    /** Wrapped in `defineModuleRoutes(module.id, …)` — gating holds at the registration seam. */
+    routes(register: (app: FastifyInstance) => Promise<void> | void): void;
+    /**
+     * Routes registered **outside** the module gate (D-36b). The exemption is
+     * narrow and structural: a surface that *reports on the platform* cannot be
+     * gated on a part of the platform without becoming circular. `_lifecycle`
+     * already registers its presence projection this way by hand
+     * (`routes.admin.ts:102-107`); a liveness or readiness probe is the same
+     * shape, and the failure it prevents is unrecoverable — a probe answering
+     * 503 because its module is off makes the orchestrator restart the
+     * container, get 503 again, and repeat, so nothing stays up long enough to
+     * serve the surface that would switch the module back on.
+     *
+     * `reason` is required and non-empty because that is the whole difference
+     * between an exemption and a way around the gate: it appears in the code
+     * next to the routes it covers, so the next reader can judge it.
+     */
+    ungatedRoutes(reason: string, register: (app: FastifyInstance) => Promise<void> | void): void;
+    /**
+     * A plugin registered on the **root** Fastify instance, uncapsulated (T078).
+     *
+     * `ctx.routes` and `ctx.ungatedRoutes` both register into an encapsulated
+     * child context, which is right for routes and wrong for a decoration every
+     * other module reads: a `decorateRequest` applied inside a child context is
+     * invisible to that context's siblings, so `auth` decorating `request.actor`
+     * through either of them would leave every other module's guards with no
+     * actor to read.
+     *
+     * The difference from `ungatedRoutes` is not one of degree. That one is about
+     * **the gate** — a surface that must answer while its module is off. This one
+     * is about **encapsulation** — a contribution that must apply to the whole
+     * application. A module can need either without the other.
+     *
+     * `reason` is required and non-empty: this is the one seam that can affect
+     * every module in a deployment, so its justification lives beside it.
+     */
+    rootPlugin(reason: string, plugin: ModulePlugin): void;
+    /** Wrapped in `defineModuleWorker(module.id, …)`. Takes a **constructed** `Worker`. */
+    worker<W extends Worker>(worker: W, options?: DefineModuleWorkerOptions): W;
+    /**
+     * Wrapped in `subscribeForModule(module.id, bus, …)`.
+     *
+     * The payload is `unknown` because that is what the `EventBus` hands a
+     * subscriber: its `Events` map defaults to `Record<string, EventBase>`, so no
+     * name-to-payload mapping exists to narrow from. Every subscriber in the tree
+     * already takes `(p: unknown)` and parses — see `ksef/plugin.ts`. A typed
+     * subscription needs the event catalogue that F3 introduces, not a cast here.
+     */
+    subscribe(event: string, handler: (payload: unknown) => void | Promise<void>): void;
+    /** API interceptors owned by this module; `module` is stamped from `module.id`. */
+    interceptors(entries: readonly Omit<InterceptorRegistration, 'module'>[]): void;
+    /**
+     * The explicit boot phase (FR-021). Runs once every module has registered,
+     * inside `enterSystemScope('boot: <module id>')`, so it may resolve.
+     *
+     * This is the only lifecycle hook a `ModuleContext` carries, and it runs on
+     * every boot of every process, including `BACKEND_ROLE=worker`. Install-time
+     * work belongs to the **other** lifecycle: a module that needs it exports
+     * `installHook` / `uninstallHook` from its `manifest.ts`, which the composer
+     * generator wires into the generated manifest index and the lifecycle
+     * orchestrator runs. There is deliberately no container-side equivalent
+     * (D-46) — `module:install` runs in a process that composes nothing, so a
+     * hook collected by the composition sink would never fire.
+     */
+    onBoot(hook: ModuleBootHook): void;
+    /**
+     * The platform's logger, bound to this module (issue #269).
+     *
+     * Every line it writes carries `module: '<this module's id>'`, and carries
+     * `reqId` when it is written during a request — neither of which the author
+     * names. The destination is whatever the composition root passed, which for
+     * every root that builds a server is the application's own pino instance from
+     * the moment `buildServer` returns; see `kernel/logging.ts` for what a line
+     * emitted before that, or from a process that builds no server, reaches.
+     *
+     * It is safe to keep: four modules hand it to a service that holds it for the
+     * life of the process, and both the destination and the request correlation
+     * are read per line rather than captured.
+     */
+    readonly log: PlatformLogger;
+}
+/**
+ * What one module contributed. The composer owns the sink and decides when to
+ * attach the plugins, so `registerModule` stays a pure declaration.
+ */
+export interface ModuleRegistrationSink {
+    readonly plugins: ModulePlugin[];
+    /**
+     * Plugins a composition root registers on the **root** Fastify instance,
+     * uncapsulated (T078). Kept apart from `plugins` because a root places them
+     * at a different point: a module's routes go with its own surface, a root
+     * plugin goes where the whole application needs decorating.
+     */
+    readonly rootPlugins: ModulePlugin[];
+    readonly workers: Worker[];
+    readonly unsubscribes: Array<() => void>;
+    readonly bootHooks: ModuleBootHook[];
+}
+export declare function createModuleRegistrationSink(): ModuleRegistrationSink;
+export interface ModuleContextOptions {
+    readonly module: {
+        readonly id: string;
+        readonly version: string;
+    };
+    readonly container: KernelContainer;
+    readonly eventBus: EventBus;
+    readonly sink: ModuleRegistrationSink;
+    readonly log: PlatformLogger;
+    /** Absent in composition roots that mount no interceptor surface (unit tests). */
+    readonly interceptorRegistry?: ApiInterceptorRegistry;
+    /**
+     * Shared across every module of one composition, so a name registered twice
+     * is caught naming both modules (T042). Absent for a hand-built context — a
+     * single module cannot collide with itself.
+     */
+    readonly ownership?: RegistrationOwnership;
+    /**
+     * Shared across every module of one composition, so the private name a
+     * decoration parks its inner resolver under is unique per container and the
+     * cross-module ambiguity check can see every decoration (T064/T065). Absent
+     * for a hand-built context — one module's decorations are ordered by the
+     * order it wrote them.
+     */
+    readonly decorations?: DecorationLedger;
+    /**
+     * Whether `registerModule` is still running for this composition. While it
+     * is, `ctx.cradle()` refuses to resolve (T043). Defaults to "no", so a
+     * context built by hand in a unit test resolves freely.
+     */
+    readonly isRegistering?: () => boolean;
+    /**
+     * This module belongs to the active **deployment**, not to core — it was
+     * discovered under `backend/src/apps/<deployment>/modules/` (issue #203).
+     *
+     * The one thing it buys is the exemption from the ownership rule on
+     * `ctx.di.decorate`: a deployment may wrap a core registration, because that
+     * is the customisation seam feature 072 put in place of file shadowing. It
+     * is set by the generated composer from the module's location, never by the
+     * module, so core cannot assert it.
+     */
+    readonly overlay?: boolean;
+    /**
+     * Where `ctx.di.decorate` puts its wraps until the registration pass is over
+     * (D-176). Passed by {@link composeModules}, which owns the drain.
+     *
+     * Absent for a hand-built context and for the post-registration context
+     * `contextFor` returns, and in both cases a decoration applies **at the
+     * call**, which is what it has always done: neither has a drain behind it, so
+     * queueing there would be a wrap nobody ever applies.
+     */
+    readonly decorationQueue?: DecorationQueue;
+    /**
+     * The module ids this composition took from **installed extension packages**
+     * (D-176 Q3).
+     *
+     * It answers one question — is the *owner* of the name being decorated a
+     * stranger's package — and it is passed by the composer from the entries it
+     * was handed, so a package cannot put itself in or out of it. It is
+     * deliberately not the `overlay` flag re-typed to an origin (D-156.4): that
+     * flag *grants*, this set *refuses*, and merging the two is how a grant
+     * mechanism acquires a member nobody meant to add.
+     */
+    readonly installedPackageModuleIds?: ReadonlySet<string>;
+}
+export declare function createModuleContext(options: ModuleContextOptions): ModuleContext;
+//# sourceMappingURL=module-context.d.ts.map

package/dist/kernel/module-context.d.ts.map

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