@endora-commerce/platform 0.100.0

package/dist/overlay/deployment-roots.js

@@ -0,0 +1,90 @@
+// Where a deployment's files are, given the directory that holds `apps/`.
+//
+// Every function here takes that directory as its first argument and derives
+// nothing from its own location. That is the whole of
+// `specs/110-instance-repository/contracts/application-root-supplier.md` §1: the
+// root is one value, it is a directory, and it is **supplied** — never derived
+// by the file that uses it.
+//
+// The reason is not tidiness. `backend/src/overlay/overlay-roots.ts` derives it
+// from `import.meta.url` and gets `backend/src` under `tsx` and `backend/dist`
+// under a compiled run; three `dirname`s from a file in this package give
+// `packages/platform/src` in both, which is a directory holding no `apps/` at
+// all. The failure is **silent** in the one mechanism where it matters most —
+// an absent declaration and an empty one are deliberately the same answer, and
+// an overlay module the loader cannot see is skipped with no error and no
+// warning (D115-3; D-165 step C). A derivation here would reproduce that state
+// exactly, in every instance, because in an instance `apps/` is a sibling of
+// the backend member rather than a directory inside it and this package came
+// out of `node_modules`.
+//
+// So the application keeps one expression — R6.1 classifies a root directory as
+// **wiring**, in so many words — and hands it in.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The active deployment name, or `null` for a bare-core build.
+ *
+ * Read from `DEPLOYMENT`; blank/whitespace is treated as unset. It names no
+ * path, which is why it moved whole: the environment is the same environment in
+ * every tree.
+ *
+ * `env` is an argument rather than an ambient read because one process resolves
+ * both answers — a suite proves a module present with the deployment selected
+ * and absent without it, in one run.
+ */
+export function selectedDeployment(env = process.env) {
+    const raw = env['DEPLOYMENT'];
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Absolute path to a deployment's overlay modules root (whether or not it
+ * exists), under the supplied deployment root.
+ */
+export function overlayModulesRootFor(deploymentRoot, deployment) {
+    return join(deploymentRoot, 'apps', deployment, 'modules');
+}
+/**
+ * Every deployment under the supplied root, sorted — one directory under
+ * `<deploymentRoot>/apps/`.
+ *
+ * `DEPLOYMENT` selects which one a *build* composes; this is the whole set, and
+ * it exists so the determinism gate can verify each deployment's committed
+ * artefacts without being run once per deployment (issue #120). An artefact only
+ * a run nobody makes would check is an artefact nothing checks.
+ *
+ * A root with no `apps/` is the empty list rather than a throw: a tree that
+ * ships no deployment is bare core, which is a supported state and not an error.
+ */
+export function deploymentsOnDisk(deploymentRoot) {
+    const appsRoot = join(deploymentRoot, 'apps');
+    if (!existsSync(appsRoot))
+        return [];
+    return readdirSync(appsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name)
+        .sort();
+}
+/**
+ * The active overlay modules root, or `null` when there is no deployment or the
+ * deployment ships no overlay directory. A non-directory path resolves to null
+ * (core-only) rather than raising — a missing overlay is not an error.
+ */
+export function activeOverlayModulesRoot(deploymentRoot, env = process.env) {
+    const deployment = selectedDeployment(env);
+    if (deployment === null)
+        return null;
+    const root = overlayModulesRootFor(deploymentRoot, deployment);
+    if (!existsSync(root))
+        return null;
+    try {
+        return statSync(root).isDirectory() ? root : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=deployment-roots.js.map

package/dist/overlay/deployment-roots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-roots.js","sourceRoot":"","sources":["../../src/overlay/deployment-roots.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,6EAA6E;AAC7E,sDAAsD;AACtD,iFAAiF;AACjF,+EAA+E;AAC/E,4BAA4B;AAC5B,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,0EAA0E;AAC1E,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,yBAAyB;AACzB,EAAE;AACF,gFAAgF;AAChF,kDAAkD;AAElD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IAC9B,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,cAAsB,EAAE,UAAkB;IAC9E,OAAO,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,cAAsB;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,OAAO,WAAW,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAClD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;SACrE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,cAAsB,EACtB,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,UAAU,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,IAAI,GAAG,qBAAqB,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IAC/D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/overlay/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `./overlay` — the overlay loader, and the platform's eleventh subpath
+ * (`specs/110-instance-repository/` T114, FR-013).
+ *
+ * ## What is on it
+ *
+ * The code that turns a directory of client-only modules into things the kernel
+ * container composes: the deterministic listing of an overlay root, the
+ * `.js`/`.ts` unit resolution a compiled tree needs, the id-collision seam both
+ * overlay readers go through, and the two loaders — manifests for the
+ * deployment-resolved registry, `ModuleEntry`s for `composeModules`.
+ *
+ * ## What is *not* on it, and that is the whole shape of this move
+ *
+ * **Every path.** This directory derives none: the deployment root and the
+ * claims already made on a module id both arrive as parameters. The first is a
+ * fact about the application — `backend/src/overlay/overlay-roots.ts` derives it
+ * once from its own `import.meta.url`, in one expression (D115-3;
+ * `specs/110-instance-repository/contracts/application-root-supplier.md` R6.1
+ * classifies a root directory as **wiring**) — and in an instance the
+ * application is a member the CLI scaffolded, which this package cannot see. The
+ * second's core half comes off the generated manifest index, which R7.4 says a
+ * relocated platform file receives rather than reaches for.
+ *
+ * So the application keeps a **binding** at `backend/src/overlay/overlay-runtime.ts`
+ * carrying every name and signature its consumers already write —
+ * `discoverOverlayModuleManifests(env)` and `loadOverlayModuleEntries(env)`
+ * among them — and an instance writes the same twenty lines over its own two
+ * answers. That is `registered-manifests.ts`' split, one directory over.
+ *
+ * `deployment-roots.ts` joined it in T114a and is that split at its purest:
+ * *"which directory holds `apps/`"* is a **parameter** of every function that
+ * composes a path under it, so `overlay-roots.ts` keeps the derivation and
+ * nothing else (R1.3).
+ *
+ * One file stayed behind for a reason of its own, written in place: `types.ts`,
+ * named **by relative path** from every deployment's generated divergence
+ * artefact, deliberately, so that a committed artefact's import does not depend
+ * on the deployment's dependency graph. `divergence-loader.ts` is no longer one
+ * of them: T114a deleted its `RUNNING_FROM_DIST` in favour of
+ * {@link resolveOverlayUnit}, so it derives nothing and is movable (R3).
+ *
+ * **`divergence-report.ts` was named here as a second and is gone** — not to this
+ * package but to `@endora-commerce/cli`, with the derivation that feeds it
+ * (`specs/110-instance-repository/` T138a). The report has two hosts, a client's
+ * instance renders one over its own `apps/` tree, and a build-time renderer has
+ * no runtime reader that would justify a package every instance loads at boot
+ * carrying it. This paragraph said it *"stays with them"*; it did not.
+ *
+ * ## Why no module may name it
+ *
+ * D-160.14's third state. An overlay module is the deployment's answer to
+ * "customise without forking", and the loader that composes one decides which
+ * modules a deployment runs at all — a module that could name this could compose
+ * its siblings, which is `./composition`'s own argument. Declared by the
+ * `exports` map, carried by no published barrel, and answered for a module's
+ * reach with `host-internal-subpath`.
+ */
+export { activeOverlayModulesRoot, deploymentsOnDisk, overlayModulesRootFor, selectedDeployment, } from './deployment-roots.js';
+export { listOverlayModuleDirs, resolveOverlay, type OverlayResolution, } from './resolve-overlay.js';
+export { overlayModuleEntriesUnder, overlayModuleIdsUnder, overlayModuleManifestsUnder, overlayModulesUnder, resolveOverlayUnit, type OverlayModuleManifest, type OverlayModules, } from './overlay-runtime.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/overlay/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/overlay/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAC"}

package/dist/overlay/index.js

@@ -0,0 +1,62 @@
+/**
+ * `./overlay` — the overlay loader, and the platform's eleventh subpath
+ * (`specs/110-instance-repository/` T114, FR-013).
+ *
+ * ## What is on it
+ *
+ * The code that turns a directory of client-only modules into things the kernel
+ * container composes: the deterministic listing of an overlay root, the
+ * `.js`/`.ts` unit resolution a compiled tree needs, the id-collision seam both
+ * overlay readers go through, and the two loaders — manifests for the
+ * deployment-resolved registry, `ModuleEntry`s for `composeModules`.
+ *
+ * ## What is *not* on it, and that is the whole shape of this move
+ *
+ * **Every path.** This directory derives none: the deployment root and the
+ * claims already made on a module id both arrive as parameters. The first is a
+ * fact about the application — `backend/src/overlay/overlay-roots.ts` derives it
+ * once from its own `import.meta.url`, in one expression (D115-3;
+ * `specs/110-instance-repository/contracts/application-root-supplier.md` R6.1
+ * classifies a root directory as **wiring**) — and in an instance the
+ * application is a member the CLI scaffolded, which this package cannot see. The
+ * second's core half comes off the generated manifest index, which R7.4 says a
+ * relocated platform file receives rather than reaches for.
+ *
+ * So the application keeps a **binding** at `backend/src/overlay/overlay-runtime.ts`
+ * carrying every name and signature its consumers already write —
+ * `discoverOverlayModuleManifests(env)` and `loadOverlayModuleEntries(env)`
+ * among them — and an instance writes the same twenty lines over its own two
+ * answers. That is `registered-manifests.ts`' split, one directory over.
+ *
+ * `deployment-roots.ts` joined it in T114a and is that split at its purest:
+ * *"which directory holds `apps/`"* is a **parameter** of every function that
+ * composes a path under it, so `overlay-roots.ts` keeps the derivation and
+ * nothing else (R1.3).
+ *
+ * One file stayed behind for a reason of its own, written in place: `types.ts`,
+ * named **by relative path** from every deployment's generated divergence
+ * artefact, deliberately, so that a committed artefact's import does not depend
+ * on the deployment's dependency graph. `divergence-loader.ts` is no longer one
+ * of them: T114a deleted its `RUNNING_FROM_DIST` in favour of
+ * {@link resolveOverlayUnit}, so it derives nothing and is movable (R3).
+ *
+ * **`divergence-report.ts` was named here as a second and is gone** — not to this
+ * package but to `@endora-commerce/cli`, with the derivation that feeds it
+ * (`specs/110-instance-repository/` T138a). The report has two hosts, a client's
+ * instance renders one over its own `apps/` tree, and a build-time renderer has
+ * no runtime reader that would justify a package every instance loads at boot
+ * carrying it. This paragraph said it *"stays with them"*; it did not.
+ *
+ * ## Why no module may name it
+ *
+ * D-160.14's third state. An overlay module is the deployment's answer to
+ * "customise without forking", and the loader that composes one decides which
+ * modules a deployment runs at all — a module that could name this could compose
+ * its siblings, which is `./composition`'s own argument. Declared by the
+ * `exports` map, carried by no published barrel, and answered for a module's
+ * reach with `host-internal-subpath`.
+ */
+export { activeOverlayModulesRoot, deploymentsOnDisk, overlayModulesRootFor, selectedDeployment, } from './deployment-roots.js';
+export { listOverlayModuleDirs, resolveOverlay, } from './resolve-overlay.js';
+export { overlayModuleEntriesUnder, overlayModuleIdsUnder, overlayModuleManifestsUnder, overlayModulesUnder, resolveOverlayUnit, } from './overlay-runtime.js';
+//# sourceMappingURL=index.js.map

package/dist/overlay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/overlay/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,qBAAqB,EACrB,cAAc,GAEf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,GAGnB,MAAM,sBAAsB,CAAC"}

package/dist/overlay/overlay-runtime.d.ts

@@ -0,0 +1,173 @@
+import type { ModuleManifest, ModuleManifestExports } from '@endora-commerce/contracts';
+import type { ModuleEntry } from '../kernel/compose.js';
+import { type ModuleIdClaim } from '../lifecycle/services/module-id-claims.js';
+/**
+ * The real path of the overlay unit `<dir>/<stem>`, or `null` when the module
+ * ships neither spelling.
+ *
+ * A **resolution**, never a derivation. The path this returns is a file that
+ * exists, so `existsSync` on it is redundant by construction and a caller
+ * cannot end up importing a name the build never emitted.
+ */
+export declare function resolveOverlayUnit(dir: string, stem: string): string | null;
+/** An overlay module's manifest + on-disk location (no registration wiring yet). */
+export interface OverlayModuleManifest {
+    id: string;
+    manifest: ModuleManifest;
+    filePath: string;
+    /** Install-time work lives in `manifest.ts` (D-46), overlay modules included. */
+    installHook?: ModuleManifestExports['installHook'];
+    uninstallHook?: ModuleManifestExports['uninstallHook'];
+    /**
+     * This module's interest in every *other* module's install and hard
+     * uninstall — feature 080, T036a / D-159. Read here for the same reason the
+     * two hooks are: the export travels with the manifest, so an overlay module
+     * and an installed package declare one on exactly core's terms.
+     */
+    lifecycleParticipant?: ModuleManifestExports['lifecycleParticipant'];
+    /**
+     * The operator commands this module declares — feature 080, T042b / D-160.9.
+     * Read here for the same reason the hooks are: the export travels with the
+     * manifest, so an overlay module declares one on exactly core's terms.
+     */
+    cliCommands?: ModuleManifestExports['cliCommands'];
+    /**
+     * The module's recent-activity eligibility — feature 080, T042j / D-163.1.
+     * Read here for the same reason the hooks are: the export travels with the
+     * manifest, so an overlay module declares one on exactly core's terms.
+     */
+    recentActivity?: ModuleManifestExports['recentActivity'];
+}
+/**
+ * The overlay module ids under one overlay modules root, **and the one place
+ * their claim on those ids is checked** (feature 103, FR-004).
+ *
+ * Both overlay seams go through here — `overlayModuleManifestsUnder`, which is
+ * what `resolvedManifestEntries()` reads, and `overlayModuleEntriesUnder`,
+ * which is what a composition root composes — so the two cannot answer
+ * differently, which is exactly what they used to do: one dropped a colliding
+ * manifest with a `continue` while the other composed the module, leaving it
+ * with no registry row, no permission-catalogue entry and its routes gated on
+ * the effective state of somebody else's module of the same id.
+ *
+ * The claimed set is derived from what this instance ships and what is
+ * installed in it, never written down — so a module that arrives, moves or
+ * leaves changes the answer in the same run. It arrives as
+ * {@link claimsOutsideTheOverlay}, a **parameter**: its core half comes off the
+ * generated manifest index, which is a fact about one tree (D-104, D-160.3), and
+ * R7.4 is that a relocated platform file receives such a thing rather than
+ * reaching for it. `backend/src/overlay/overlay-runtime.ts` is the binding that
+ * supplies it, and an instance writes the same one.
+ *
+ * This used to be `scanOverlay(root, indexCore(coreModulesRoot())).newModules`
+ * — a file-shadowing scan whose core index resolved `backend/src/modules`,
+ * which has held no module since F4. With the index empty **every** overlay
+ * directory came back as a new module claiming its id, unchecked (D-201).
+ */
+export declare function overlayModuleIdsUnder(root: string, claimsOutsideTheOverlay: readonly ModuleIdClaim[]): string[];
+/**
+ * Discover overlay MODULE manifests under one root WITHOUT composing them. Used
+ * early in composition to build the deployment-resolved registry the permission
+ * catalogue + lifecycle consume (FR-009, FR-012).
+ *
+ * The **root** is a parameter, not a derivation of this file's own path: which
+ * directory holds `apps/<deployment>/modules` is a fact about the application,
+ * derived once by `backend/src/overlay/overlay-roots.ts` from its own
+ * `import.meta.url` (D115-3), and the platform is not in that tree. The binding
+ * beside that derivation is what answers "the active deployment's" — see
+ * `backend/src/overlay/overlay-runtime.ts`.
+ *
+ * The fixture is therefore a directory on disk, scanned and imported by the code
+ * the deployment path runs, rather than a value handed to the last function in
+ * the chain (issue #130).
+ */
+export declare function overlayModuleManifestsUnder(root: string, ids: readonly string[]): Promise<OverlayModuleManifest[]>;
+/**
+ * One overlay root's converted modules, as composer entries (D-103/D-104).
+ *
+ * The root and the claims are parameters for the reason
+ * {@link overlayModuleManifestsUnder} gives: both are facts about the
+ * application, and `backend/src/overlay/overlay-runtime.ts` is the binding that
+ * answers "the active deployment's" over them.
+ *
+ * This is the **one** composition path for an overlay module: a root appends
+ * these to the core list and passes the single array to `composeModules`, so an
+ * overlay module receives an ordinary `ModuleContext` and reaches every seam a
+ * core module reaches — `ctx.routes` and its lifecycle gate, `ctx.worker`,
+ * `ctx.subscribe`, `ctx.interceptors`, `ctx.onBoot`, ports, and the decoration
+ * exemption. The path it replaces handed a frozen seven-field context to a
+ * `plugin.ts` factory and could gate nothing.
+ *
+ * **Discovered at runtime, not baked into a generated core artefact** (D-104).
+ * A deployment's manifests already resolve this way and for the stated reason:
+ * the answer depends on which deployment the *process* runs as, not on which
+ * tree a generator was run against. Registrations have the identical property
+ * and used to be given the opposite treatment, which made
+ * `composition.generated.ts` and `manifest-index.generated.ts` environment-
+ * dependent — an artefact that is always stale for a deployment is one nobody
+ * can use to detect a genuinely stale one (issue #120, applied to the family it
+ * was missed in).
+ *
+ * `overlay: true` is set **from the root the module was found under**, which is
+ * what `ModuleEntry.overlay`'s own contract requires: it exempts the module
+ * from the rule that a module may decorate only what it registered, so it may
+ * never be a claim a module makes about itself.
+ *
+ * Ordering is deterministic — the entries come back in id order and a root
+ * appends them after a frozen core list — and it decides nothing about
+ * decoration. It used to: this paragraph read "so a deployment's decoration
+ * always wraps a core registration that is already there", which was the
+ * composer's array position doing policy work. Since D-176 every
+ * `ctx.di.decorate` is queued during registration and drained once the last
+ * module has registered, so where a module sits in the array cannot grant or
+ * refuse a wrap; the ownership guard decides, alone.
+ *
+ * A module directory with no backend entry point **in either spelling** is
+ * skipped, not thrown at — a deployment may ship an overlay directory that only
+ * shadows core files. "Either spelling" is the whole of D-165 step C's repair
+ * here: this used to ask `existsSync('backend.ts')`, so a compiled deployment's
+ * every module took the skip and vanished with no error. A `backend.js`/`.ts`
+ * that exports no `registerModule` is a different thing and is refused:
+ * skipping it would compose nothing, and the first symptom would be a 404
+ * nobody connects to this file.
+ */
+export declare function overlayModuleEntriesUnder(root: string, claimsOutsideTheOverlay: readonly ModuleIdClaim[]): Promise<ModuleEntry[]>;
+/**
+ * One deployment's overlay modules, read **once** for both seams
+ * (`specs/124-instance-customisation-gap/` FR-001, FR-002).
+ *
+ * Every composition root that has an overlay root needs the same two answers —
+ * the `ModuleEntry` list it composes and the `OverlayModuleManifest` list
+ * `resolveManifestEntries` resolves the registry from — and needs them over the
+ * **same** ids. Written out at each site that is three lines repeated, and the
+ * repetition is what produced the defect this function exists to close:
+ * `defaultComposition` composed `overlayModuleEntriesUnder(...)` and passed
+ * `overlay: async () => []` four lines below it, so an instance's overlay module
+ * reached the container, the permission gate and the presence projection and
+ * never `lifecycleManifestRegistry` — the state `resolveManifestEntries`' own
+ * doc block calls *"Principle XVII defeated in silence"*, reproduced by
+ * construction on the one path an instance takes.
+ *
+ * `root` is `string | null` on purpose: "this deployment has no overlay root"
+ * is the answer {@link activeOverlayModulesRoot} gives, and taking the ternary
+ * in here is what stops a caller writing the empty case for one seam and
+ * forgetting it for the other.
+ *
+ * The ids are derived **lazily and once**. Lazily, because the claim set is a
+ * `node_modules` scan a root with no overlay must not pay for and because the
+ * collision refusal must stay where it fires today — inside the supplier a
+ * caller hands to `resolveManifestEntries`, not before it. Once, because
+ * `overlayModuleIdsUnder` asserts the claims as it derives them, and asserting
+ * the same set twice is wasteful rather than wrong only for as long as the two
+ * derivations cannot drift.
+ */
+export interface OverlayModules {
+    /** The overlay module ids under this root — `[]` when there is no root. */
+    ids(): readonly string[];
+    /** The manifest half: what the resolved registry is built from. */
+    manifests(): Promise<OverlayModuleManifest[]>;
+    /** The registration half: what a composition root composes. */
+    entries(): Promise<ModuleEntry[]>;
+}
+export declare function overlayModulesUnder(root: string | null, claimsOutsideTheOverlay: () => readonly ModuleIdClaim[]): OverlayModules;
+//# sourceMappingURL=overlay-runtime.d.ts.map

package/dist/overlay/overlay-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-runtime.d.ts","sourceRoot":"","sources":["../../src/overlay/overlay-runtime.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,2CAA2C,CAAC;AAWnD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3E;AAcD,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,WAAW,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACnD,aAAa,CAAC,EAAE,qBAAqB,CAAC,eAAe,CAAC,CAAC;IACvD;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,CAAC,sBAAsB,CAAC,CAAC;IACrE;;;;OAIG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACnD;;;;OAIG;IACH,cAAc,CAAC,EAAE,qBAAqB,CAAC,gBAAgB,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,uBAAuB,EAAE,SAAS,aAAa,EAAE,GAChD,MAAM,EAAE,CAeV;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,OAAO,CAAC,qBAAqB,EAAE,CAAC,CA8ClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,uBAAuB,EAAE,SAAS,aAAa,EAAE,GAChD,OAAO,CAAC,WAAW,EAAE,CAAC,CAExB;AA0DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,GAAG,IAAI,SAAS,MAAM,EAAE,CAAC;IACzB,mEAAmE;IACnE,SAAS,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAC9C,+DAA+D;IAC/D,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CACnC;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,uBAAuB,EAAE,MAAM,SAAS,aAAa,EAAE,GACtD,cAAc,CAahB"}