@endora-commerce/test-kit 0.100.0

package/dist/server/composition.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `PlatformComposition` — what a caller hands the kit (feature 109, contract
+ * R2.1).
+ *
+ * ## The inversion, and why it is the whole feature
+ *
+ * `backend/test/helpers/test-server.ts` composes a platform by *finding* one:
+ * it imports the generated module list, the application's ORM configuration,
+ * the resolved manifest registry, the overlay loader and the package loader —
+ * seven bindings, every one of them a fact about **this repository's tree**
+ * (§2.1). A package cannot have any of them, so a harness that reaches for them
+ * cannot be a package, and a module's server-bound test therefore had nowhere
+ * to run but `backend/test`.
+ *
+ * So the kit is *handed* its composition and never builds one. That is the same
+ * inversion the platform already applies to every other host value: a
+ * composition root registers `redis`, `eventBus` and `processRunsWorkers`
+ * above the compose call because no module defaults them (AGENTS.md
+ * § Composition item 8), and the composition itself is one more of those.
+ *
+ * ## What the kit deliberately will not do (R2.2)
+ *
+ * It does not read `process.env.DEPLOYMENT`, walk `node_modules` or read a
+ * generated artefact. Every one of those is a fact about the caller's process —
+ * D-104's predicate — and a kit that answered them would answer them
+ * differently from the platform that composes for real. Discovery lives with
+ * the host, which is where `loadOverlayModuleEntries` and
+ * `loadPackageModuleEntries` already are; a second copy in the kit would be a
+ * second answer waiting to disagree.
+ */
+import type { MikroORM } from '@mikro-orm/postgresql';
+import type { ModuleManifest } from '@endora-commerce/contracts';
+import type { composeModules } from '@endora-commerce/platform/composition';
+import type { TestSupportContribution } from '../support/index.js';
+/**
+ * One composed module, named through `composeModules`' own signature.
+ *
+ * `ModuleEntry` is not one of the 27 symbols `./composition` carries and this
+ * feature widens no barrel (R3.1), so the type is taken from the function that
+ * *is* published rather than by publishing a second symbol to spell it. It
+ * stays correct by construction: a field added to the entry is a field here in
+ * the same compile.
+ */
+type ModuleEntry = Parameters<typeof composeModules>[0][number];
+/**
+ * How this composition opens and closes its ORM.
+ *
+ * A pair rather than an instance, for the reason the harness's own
+ * `initOrm`/`closeOrm` are a pair: the ORM configuration captures
+ * `DATABASE_URL` at import, so *when* it is opened is part of what the caller
+ * decides. The application supplies its own; a module package's test supplies
+ * one built over the entity classes its installed set declares.
+ */
+export interface TestOrmLifecycle {
+    open(): Promise<MikroORM>;
+    close(): Promise<void>;
+}
+/**
+ * One entry of the loaded manifest registry, as the kit reads it.
+ *
+ * **Structural on purpose.** The application's own entry type carries a file
+ * path, an origin, install hooks and the operator commands a module declares —
+ * none of which the composition seam needs, and all of which are host-owned
+ * (`backend/src/lifecycle/registered-manifests.ts`, which a package may not
+ * name). Declaring the one member the kit reads keeps the application's array
+ * assignable without the kit knowing what else is on it.
+ */
+export interface ComposedManifestEntry {
+    readonly manifest: ModuleManifest;
+}
+/**
+ * The four things only the caller knows.
+ *
+ * Each member is one of §2.1's rows, and the table there is the normative
+ * statement of what belongs here: a fifth member would have to be something a
+ * *stranger's* test could not answer, and there is nothing left in that class.
+ */
+export interface PlatformComposition {
+    /**
+     * The module entries to compose — this repository's `MODULES` plus its
+     * overlay and its discovered packages, or a third party's own set.
+     *
+     * A composition lacking a module that declares `activation.nonDeactivatable`
+     * is refused by `composeModules` before the first module registers (issue
+     * #258), and the kit adds no second check and swallows no refusal (R2.4): a
+     * stranger composing an incomplete set gets the platform's own sentence,
+     * naming the module, the reason its manifest gives and the remedy.
+     */
+    readonly modules: readonly ModuleEntry[];
+    /** An opener and a closer, per {@link TestOrmLifecycle}. */
+    readonly orm: TestOrmLifecycle;
+    /**
+     * The loaded manifest registry the lifecycle needs.
+     *
+     * It is what the required-module set, the activation declarations and the
+     * seeded enabled set are all derived from — three derivations from one input,
+     * on every composition, so a caller that withdraws a module changes all three
+     * in the same run and there is no list anywhere (D-100).
+     */
+    readonly manifests: readonly ComposedManifestEntry[];
+    /**
+     * The test-support contributions of **exactly the modules in `modules`**,
+     * collected by the caller (contract §4).
+     *
+     * The kit does not discover them for the same reason it does not discover
+     * modules. In Phase 1b only `registrations` is applied; `volatileTables` and
+     * `seed` are declared and not yet collected — see `../support/index.ts`.
+     */
+    readonly testSupport?: readonly TestSupportContribution[];
+}
+export {};
+//# sourceMappingURL=composition.d.ts.map

package/dist/server/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../../src/server/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAE5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE;;;;;;;;GAQG;AACH,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACrD;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC3D"}

package/dist/server/composition.js

@@ -0,0 +1,32 @@
+/**
+ * `PlatformComposition` — what a caller hands the kit (feature 109, contract
+ * R2.1).
+ *
+ * ## The inversion, and why it is the whole feature
+ *
+ * `backend/test/helpers/test-server.ts` composes a platform by *finding* one:
+ * it imports the generated module list, the application's ORM configuration,
+ * the resolved manifest registry, the overlay loader and the package loader —
+ * seven bindings, every one of them a fact about **this repository's tree**
+ * (§2.1). A package cannot have any of them, so a harness that reaches for them
+ * cannot be a package, and a module's server-bound test therefore had nowhere
+ * to run but `backend/test`.
+ *
+ * So the kit is *handed* its composition and never builds one. That is the same
+ * inversion the platform already applies to every other host value: a
+ * composition root registers `redis`, `eventBus` and `processRunsWorkers`
+ * above the compose call because no module defaults them (AGENTS.md
+ * § Composition item 8), and the composition itself is one more of those.
+ *
+ * ## What the kit deliberately will not do (R2.2)
+ *
+ * It does not read `process.env.DEPLOYMENT`, walk `node_modules` or read a
+ * generated artefact. Every one of those is a fact about the caller's process —
+ * D-104's predicate — and a kit that answered them would answer them
+ * differently from the platform that composes for real. Discovery lives with
+ * the host, which is where `loadOverlayModuleEntries` and
+ * `loadPackageModuleEntries` already are; a second copy in the kit would be a
+ * second answer waiting to disagree.
+ */
+export {};
+//# sourceMappingURL=composition.js.map

package/dist/server/composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.js","sourceRoot":"","sources":["../../src/server/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG"}

package/dist/server/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `./server` — compose a platform for a test, and take it down again
+ * (feature 109, R1.1).
+ *
+ * `composeTestServer` and `teardownTestServer`, and the two types they take and
+ * return. Everything the caller supplies is `PlatformComposition`
+ * (`./composition.ts`) plus the four hooks the boot order makes load-bearing;
+ * everything the kit owns is on `TestServerHandle`, and **not one field of it
+ * names a module**.
+ */
+export { composeTestServer, teardownTestServer, type ComposedPlatformContext, type ComposeTestServerOptions, type TestPlatformContext, type TestServerHandle, } from './compose-test-server.js';
+export type { ComposedManifestEntry, PlatformComposition, TestOrmLifecycle, } from './composition.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,12 @@
+/**
+ * `./server` — compose a platform for a test, and take it down again
+ * (feature 109, R1.1).
+ *
+ * `composeTestServer` and `teardownTestServer`, and the two types they take and
+ * return. Everything the caller supplies is `PlatformComposition`
+ * (`./composition.ts`) plus the four hooks the boot order makes load-bearing;
+ * everything the kit owns is on `TestServerHandle`, and **not one field of it
+ * names a module**.
+ */
+export { composeTestServer, teardownTestServer, } from './compose-test-server.js';
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,GAKnB,MAAM,0BAA0B,CAAC"}

package/dist/support/entity-index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The entity index — its **type** and its **lookup**, and no module's name
+ * (feature 109, T065; contract R2.2, FR-001).
+ *
+ * ## The one fact this file is built around not knowing
+ *
+ * A server-bound test writes rows, and to write a row it needs the entity
+ * **class the ORM registered** — not a structurally identical copy read out of a
+ * package's source, which is a class the ORM never discovered (D-160.6.1). A
+ * module package publishes one `entities` array and **no entity class by name**
+ * (D-168), so the class is picked out of that array by name, and the array comes
+ * off the package's own `./backend`.
+ *
+ * Which packages are there is where this stops being a package's business.
+ * *Which modules one deployment installed* is the single fact a kit that may
+ * name no module is forbidden to know (R2.2, FR-001), and it is why
+ * `backend/test/helpers/package-entities.ts` is permanently host-owned and may
+ * not move here — `specs/084-small-f4-package-layout/contracts/module-package-layout.md`
+ * R10's closing paragraph, which asks in as many words that this not be
+ * re-opened on import volume.
+ *
+ * So the population arrives as an **argument**, exactly as
+ * `PlatformComposition.modules` does, and it is rendered by the host's own
+ * generator — `@endora-commerce/cli/lib/entity-index-artefact.js`, run by
+ * `endora generate` in an instance and by `composer:generate` in this
+ * repository. One derivation, two populations
+ * (`contracts/instance-repository.md` R3.5).
+ *
+ * ## Why the lookup delegates rather than re-implements
+ *
+ * `entityNamed` is `@endora-commerce/platform/packages`', and two
+ * implementations of one lookup are two answers waiting to disagree about what a
+ * missing name does. What this file adds is the **module** dimension the
+ * platform's lookup has no opinion about: the index is keyed by module id, so a
+ * name that is absent has two different causes — the module is not installed, or
+ * the module publishes no such class — and they have different remedies. A host
+ * that gets `Cannot read properties of undefined` for the first has been told
+ * nothing.
+ */
+import type { EntityClass } from '@mikro-orm/core';
+import { type EntityRowTypeIsRequired } from '@endora-commerce/platform/packages';
+/**
+ * What a published `entities` array holds.
+ *
+ * A construct signature rather than `unknown`, for the platform lookup's own
+ * reason: it refuses an argument that is not an array of classes at all, which
+ * is the shape a package that lost its array answers with — the host reads a
+ * missing `entities` export as `[]` and reports nothing.
+ */
+type PublishedEntityClass = abstract new (...args: never[]) => object;
+/**
+ * The index's type, and the whole of what the kit may say about its content.
+ *
+ * Keyed by **module id** — `endora.id`, the identity of record (D-142) — and
+ * never by package name: a test names the module it is testing, and the package
+ * name is a fact about how that module was delivered.
+ *
+ * The kit declares this shape and never a member of it. A union of the module
+ * ids that happen to exist today would be the list R2.2 forbids, and it would
+ * make a stranger's own module unnameable in the index their own host rendered.
+ */
+export type InstalledEntityIndex = Readonly<Record<string, readonly PublishedEntityClass[]>>;
+/**
+ * One entity class out of an installed module's published array, with the row
+ * type the caller supplies.
+ *
+ * The row type is **required** and its default is unsatisfiable, which is the
+ * platform lookup's decision and is inherited here rather than restated: with
+ * `T` free, `em.create` checks the payload against `object` and accepts
+ * everything, which is worse than the constructor-union collapse the mechanism
+ * exists for. A caller takes it from an `import type` of the module's own
+ * `./test-support`, which publishes the row types `export type`-only for exactly
+ * this (R10 property 3).
+ */
+export declare function entityNamedIn<T extends object = EntityRowTypeIsRequired>(index: InstalledEntityIndex, moduleId: string, name: string): EntityClass<T>;
+/**
+ * A module id the index does not carry.
+ *
+ * Its own class rather than a bare `Error` because the two causes of "no such
+ * entity" have different remedies and a caller may legitimately branch on which
+ * it got: this one means *this host composed a different set of modules*, and
+ * the platform lookup's means *that module publishes no such class*.
+ */
+export declare class ModuleNotInstalledError extends Error {
+    readonly moduleId: string;
+    readonly installed: readonly string[];
+    readonly name = "ModuleNotInstalledError";
+    constructor(moduleId: string, installed: readonly string[]);
+}
+export {};
+//# sourceMappingURL=entity-index.d.ts.map

package/dist/support/entity-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-index.d.ts","sourceRoot":"","sources":["../../src/support/entity-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAe,KAAK,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAE/F;;;;;;;GAOG;AACH,KAAK,oBAAoB,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,MAAM,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC,CAAC,CAAC;AAE7F;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,uBAAuB,EACtE,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,WAAW,CAAC,CAAC,CAAC,CAiBhB;AASD;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAI9C,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE;IAJvC,SAAkB,IAAI,6BAA6B;gBAGxC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,MAAM,EAAE;CAUxC"}

package/dist/support/entity-index.js

@@ -0,0 +1,56 @@
+import { entityNamed } from '@endora-commerce/platform/packages';
+/**
+ * One entity class out of an installed module's published array, with the row
+ * type the caller supplies.
+ *
+ * The row type is **required** and its default is unsatisfiable, which is the
+ * platform lookup's decision and is inherited here rather than restated: with
+ * `T` free, `em.create` checks the payload against `object` and accepts
+ * everything, which is worse than the constructor-union collapse the mechanism
+ * exists for. A caller takes it from an `import type` of the module's own
+ * `./test-support`, which publishes the row types `export type`-only for exactly
+ * this (R10 property 3).
+ */
+export function entityNamedIn(index, moduleId, name) {
+    // `Object.hasOwn`, not a truthiness test: the index is a plain object a
+    // generator rendered, so `index['toString']` answers with a function off
+    // `Object.prototype` — a truthy value where an array belongs, and on
+    // `constructor` a value that would reach the lookup and fail somewhere else.
+    if (!Object.hasOwn(index, moduleId)) {
+        throw new ModuleNotInstalledError(moduleId, installedModuleIds(index));
+    }
+    const published = index[moduleId];
+    if (!Array.isArray(published)) {
+        throw new ModuleNotInstalledError(moduleId, installedModuleIds(index));
+    }
+    return entityNamed(published, name, `the installed module '${moduleId}'`);
+}
+/** Every module id the index carries, sorted, so a refusal reads the same way twice. */
+function installedModuleIds(index) {
+    return Object.keys(index)
+        .filter((key) => Object.hasOwn(index, key))
+        .sort();
+}
+/**
+ * A module id the index does not carry.
+ *
+ * Its own class rather than a bare `Error` because the two causes of "no such
+ * entity" have different remedies and a caller may legitimately branch on which
+ * it got: this one means *this host composed a different set of modules*, and
+ * the platform lookup's means *that module publishes no such class*.
+ */
+export class ModuleNotInstalledError extends Error {
+    moduleId;
+    installed;
+    name = 'ModuleNotInstalledError';
+    constructor(moduleId, installed) {
+        super(`the entity index carries no module '${moduleId}', so no entity class of it can be ` +
+            `named. This host installed: ${installed.length === 0 ? '(no module at all)' : installed.join(', ')}. ` +
+            `The index is rendered from the packages this host installed, so either install ` +
+            `'${moduleId}' and re-run the generator, or name a module that is in the list — a ` +
+            `stale index is a test asking the ORM about a table nothing mapped.`);
+        this.moduleId = moduleId;
+        this.installed = installed;
+    }
+}
+//# sourceMappingURL=entity-index.js.map

package/dist/support/entity-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-index.js","sourceRoot":"","sources":["../../src/support/entity-index.ts"],"names":[],"mappings":"AAyCA,OAAO,EAAE,WAAW,EAAgC,MAAM,oCAAoC,CAAC;AAyB/F;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAC3B,KAA2B,EAC3B,QAAgB,EAChB,IAAY;IAEZ,wEAAwE;IACxE,yEAAyE;IACzE,qEAAqE;IACrE,6EAA6E;IAC7E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,uBAAuB,CAAC,QAAQ,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,uBAAuB,CAAC,QAAQ,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,WAAW,CAChB,SAA4C,EAC5C,IAAI,EACJ,yBAAyB,QAAQ,GAAG,CACrC,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,SAAS,kBAAkB,CAAC,KAA2B;IACrD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;SACtB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SAC1C,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAIrC;IACA;IAJO,IAAI,GAAG,yBAAyB,CAAC;IAEnD,YACW,QAAgB,EAChB,SAA4B;QAErC,KAAK,CACH,uCAAuC,QAAQ,qCAAqC;YAClF,+BAA+B,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACvG,iFAAiF;YACjF,IAAI,QAAQ,uEAAuE;YACnF,oEAAoE,CACvE,CAAC;QATO,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAmB;IASvC,CAAC;CACF"}

package/dist/support/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * `./support` — what a module contributes to a test composition (feature 109,
+ * contract §4).
+ *
+ * A module package that needs test support declares it at
+ * `src/test-support/index.ts` and publishes it as `./test-support`; the caller
+ * collects the declarations of **the modules it composed** and hands them to
+ * `composeTestServer` as `PlatformComposition.testSupport`. The kit never
+ * discovers them: discovery walks `node_modules`, which is a fact about the
+ * caller's process (R2.2).
+ *
+ * ## What is here in Phase 1b, and what is not
+ *
+ * The **declaration shape** and the **registration** member, because
+ * `PlatformComposition` takes contributions and a type it could not name would
+ * make that member `unknown`. The three collectors — the truncate ordering
+ * derived from the foreign-key graph (R4.2), the per-module seed decomposition
+ * (R4.6) and the fixture re-export — are Phase 3, and the members they read are
+ * declared here now so that a module author writing a `./test-support` layer
+ * writes one declaration rather than two.
+ *
+ * `volatileTables` and `seed` are therefore **declared and not yet collected**,
+ * which is stated rather than left to be discovered: `composeTestServer`
+ * applies `registrations` and reads neither, and a module that declares tables
+ * today gets no truncate from them. The alternative — leaving them out of the
+ * type until the collector exists — would make every module that ships a
+ * contribution in Phase 3 edit a declaration it had already written.
+ *
+ * ## The entity index is here too, and it is the same inversion
+ *
+ * `./entity-index.js` carries the **type** of a host's entity index and the
+ * **lookup** over it, and no module's name (T065). It is on this subpath rather
+ * than a new one because it is the same kind of thing as everything above: a
+ * shape the kit declares and a population the caller supplies. Its own header
+ * is where the reasoning is.
+ */
+export { entityNamedIn, ModuleNotInstalledError, type InstalledEntityIndex, } from './entity-index.js';
+/**
+ * One module's test support.
+ *
+ * Four optional members and nothing else (R4.1). Every one of them is that
+ * module's own policy: the taxonomy fetcher that refuses and the PIM client
+ * that throws exist to make a test which reaches the network fail loudly, and
+ * that is `product_feeds`' and `pim_ergonode`' decision rather than a harness's.
+ */
+export interface TestSupportContribution {
+    /**
+     * The module this contribution belongs to. It is the module's own manifest
+     * id, and the kit uses it for one thing: naming the module in a refusal.
+     */
+    readonly moduleId: string;
+    /**
+     * Container registrations this module's tests substitute by default, keyed by
+     * the **registration name its owner registers** — the same key
+     * `composedModules.contribute` takes.
+     *
+     * A module may not contribute over a name it does not own (R4.4), for the
+     * reason D-176 and issue #203 give about decoration: a substitution rewrites
+     * what every consumer of that name resolves. A test that needs to substitute
+     * *another* module's collaborator does it at the call site, in its own file,
+     * through `composeTestServer`'s own `contribute` option — where the coupling
+     * is visible in the test that wanted it.
+     */
+    readonly registrations?: Readonly<Record<string, unknown>>;
+    /**
+     * The tables this module owns whose rows must not survive between tests.
+     *
+     * A **set, not a sequence** (R4.2): the order they are emptied in is derived
+     * from the foreign-key graph, and a set the derivation cannot order is a
+     * failure naming the cycle. A hand-written order is a fact about the schema
+     * that the schema can state for itself.
+     */
+    readonly volatileTables?: readonly string[];
+    /**
+     * Rows this module contributes to a named seed.
+     *
+     * Additive and order-independent (R4.6): a seed whose result depends on the
+     * order two modules contributed in is a defect, not a configuration.
+     */
+    readonly seed?: Readonly<Record<string, (em: unknown) => Promise<void>>>;
+    /** Anything else this module's tests build, re-exported for its own use. */
+    readonly fixtures?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Every registration the given contributions substitute, merged.
+ *
+ * Refuses two modules claiming one name rather than letting the last one win:
+ * a substitution the reader cannot attribute is the shape D-176 refuses for
+ * decoration, and "whichever was collected last" is not an answer anybody can
+ * act on.
+ */
+export declare function mergeTestSupportRegistrations(contributions: readonly TestSupportContribution[]): Readonly<Record<string, unknown>>;
+/** Two modules substituting one registration name. */
+export declare class ConflictingTestSupportError extends Error {
+    readonly registrationName: string;
+    readonly firstModuleId: string;
+    readonly secondModuleId: string;
+    constructor(registrationName: string, firstModuleId: string, secondModuleId: string);
+}
+/**
+ * Every table the given contributions declare volatile, deduped and sorted.
+ *
+ * **Sorted rather than ordered** (R4.2). The declaration is a set, and the
+ * ordering the contract asks the foreign-key graph to derive is not needed by
+ * the one consumer there is: the caller empties them with a single
+ * `truncate table … cascade`, which is one statement over the whole set and
+ * takes no order — PostgreSQL resolves the dependencies itself, which is why the
+ * harness's hand-written children-first list has always been a comment rather
+ * than a mechanism. A sorted set makes the result a function of the composition
+ * and not of the order the contributions were collected in, which is the
+ * property R4.2 is actually protecting. The day a consumer empties them one
+ * statement at a time, the derivation the contract describes is what it has to
+ * take, and this function is where it goes.
+ *
+ * Two refusals, both about a declaration rather than about a statement: two
+ * modules claiming one table, and a name that is not an identifier. The second
+ * matters because the collected set is interpolated into SQL by its caller, so a
+ * quote or a semicolon has to be refused where it is written down.
+ */
+export declare function collectVolatileTables(contributions: readonly TestSupportContribution[]): readonly string[];
+/** Two modules declaring one table volatile. */
+export declare class ConflictingVolatileTableError extends Error {
+    readonly tableName: string;
+    readonly firstModuleId: string;
+    readonly secondModuleId: string;
+    constructor(tableName: string, firstModuleId: string, secondModuleId: string);
+}
+/** A declared volatile table whose name is not an identifier. */
+export declare class UndeclarableVolatileTableError extends Error {
+    readonly moduleId: string;
+    readonly tableName: string;
+    constructor(moduleId: string, tableName: string);
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/support/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzE,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,SAAS,uBAAuB,EAAE,GAChD,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAcnC;AAED,sDAAsD;AACtD,qBAAa,2BAA4B,SAAQ,KAAK;IAElD,QAAQ,CAAC,gBAAgB,EAAE,MAAM;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM;gBAFtB,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM;CAWlC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,SAAS,uBAAuB,EAAE,GAChD,SAAS,MAAM,EAAE,CAiBnB;AAQD,gDAAgD;AAChD,qBAAa,6BAA8B,SAAQ,KAAK;IAEpD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM;gBAFtB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM;CAWlC;AAED,iEAAiE;AACjE,qBAAa,8BAA+B,SAAQ,KAAK;IAErD,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM;gBADjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM;CAW7B"}

package/dist/support/index.js

@@ -0,0 +1,153 @@
+/**
+ * `./support` — what a module contributes to a test composition (feature 109,
+ * contract §4).
+ *
+ * A module package that needs test support declares it at
+ * `src/test-support/index.ts` and publishes it as `./test-support`; the caller
+ * collects the declarations of **the modules it composed** and hands them to
+ * `composeTestServer` as `PlatformComposition.testSupport`. The kit never
+ * discovers them: discovery walks `node_modules`, which is a fact about the
+ * caller's process (R2.2).
+ *
+ * ## What is here in Phase 1b, and what is not
+ *
+ * The **declaration shape** and the **registration** member, because
+ * `PlatformComposition` takes contributions and a type it could not name would
+ * make that member `unknown`. The three collectors — the truncate ordering
+ * derived from the foreign-key graph (R4.2), the per-module seed decomposition
+ * (R4.6) and the fixture re-export — are Phase 3, and the members they read are
+ * declared here now so that a module author writing a `./test-support` layer
+ * writes one declaration rather than two.
+ *
+ * `volatileTables` and `seed` are therefore **declared and not yet collected**,
+ * which is stated rather than left to be discovered: `composeTestServer`
+ * applies `registrations` and reads neither, and a module that declares tables
+ * today gets no truncate from them. The alternative — leaving them out of the
+ * type until the collector exists — would make every module that ships a
+ * contribution in Phase 3 edit a declaration it had already written.
+ *
+ * ## The entity index is here too, and it is the same inversion
+ *
+ * `./entity-index.js` carries the **type** of a host's entity index and the
+ * **lookup** over it, and no module's name (T065). It is on this subpath rather
+ * than a new one because it is the same kind of thing as everything above: a
+ * shape the kit declares and a population the caller supplies. Its own header
+ * is where the reasoning is.
+ */
+export { entityNamedIn, ModuleNotInstalledError, } from './entity-index.js';
+/**
+ * Every registration the given contributions substitute, merged.
+ *
+ * Refuses two modules claiming one name rather than letting the last one win:
+ * a substitution the reader cannot attribute is the shape D-176 refuses for
+ * decoration, and "whichever was collected last" is not an answer anybody can
+ * act on.
+ */
+export function mergeTestSupportRegistrations(contributions) {
+    const merged = {};
+    const claimedBy = new Map();
+    for (const contribution of contributions) {
+        for (const [name, value] of Object.entries(contribution.registrations ?? {})) {
+            const owner = claimedBy.get(name);
+            if (owner !== undefined) {
+                throw new ConflictingTestSupportError(name, owner, contribution.moduleId);
+            }
+            claimedBy.set(name, contribution.moduleId);
+            merged[name] = value;
+        }
+    }
+    return merged;
+}
+/** Two modules substituting one registration name. */
+export class ConflictingTestSupportError extends Error {
+    registrationName;
+    firstModuleId;
+    secondModuleId;
+    constructor(registrationName, firstModuleId, secondModuleId) {
+        super(`test support for '${registrationName}' is contributed by both '${firstModuleId}' and ` +
+            `'${secondModuleId}'. A registration has one owner, and a substitution rewrites what ` +
+            `every consumer of that name resolves — so only the module that registers it may ` +
+            `substitute it by default. A test that needs the other module's substitution asks for ` +
+            `it at its own call site.`);
+        this.registrationName = registrationName;
+        this.firstModuleId = firstModuleId;
+        this.secondModuleId = secondModuleId;
+        this.name = 'ConflictingTestSupportError';
+    }
+}
+/**
+ * Every table the given contributions declare volatile, deduped and sorted.
+ *
+ * **Sorted rather than ordered** (R4.2). The declaration is a set, and the
+ * ordering the contract asks the foreign-key graph to derive is not needed by
+ * the one consumer there is: the caller empties them with a single
+ * `truncate table … cascade`, which is one statement over the whole set and
+ * takes no order — PostgreSQL resolves the dependencies itself, which is why the
+ * harness's hand-written children-first list has always been a comment rather
+ * than a mechanism. A sorted set makes the result a function of the composition
+ * and not of the order the contributions were collected in, which is the
+ * property R4.2 is actually protecting. The day a consumer empties them one
+ * statement at a time, the derivation the contract describes is what it has to
+ * take, and this function is where it goes.
+ *
+ * Two refusals, both about a declaration rather than about a statement: two
+ * modules claiming one table, and a name that is not an identifier. The second
+ * matters because the collected set is interpolated into SQL by its caller, so a
+ * quote or a semicolon has to be refused where it is written down.
+ */
+export function collectVolatileTables(contributions) {
+    const claimedBy = new Map();
+    for (const contribution of contributions) {
+        for (const table of contribution.volatileTables ?? []) {
+            if (!VALID_TABLE_NAME.test(table)) {
+                throw new UndeclarableVolatileTableError(contribution.moduleId, table);
+            }
+            const owner = claimedBy.get(table);
+            // One module naming its own table twice has made no claim it had not
+            // already made; only a *second* module is a conflict.
+            if (owner !== undefined && owner !== contribution.moduleId) {
+                throw new ConflictingVolatileTableError(table, owner, contribution.moduleId);
+            }
+            claimedBy.set(table, contribution.moduleId);
+        }
+    }
+    return [...claimedBy.keys()].sort();
+}
+/**
+ * What a table name may be: the unquoted PostgreSQL identifier every migration
+ * in this repository writes. Anything else is refused rather than quoted around.
+ */
+const VALID_TABLE_NAME = /^[a-z_][a-z0-9_]*$/;
+/** Two modules declaring one table volatile. */
+export class ConflictingVolatileTableError extends Error {
+    tableName;
+    firstModuleId;
+    secondModuleId;
+    constructor(tableName, firstModuleId, secondModuleId) {
+        super(`the table '${tableName}' is declared volatile by both '${firstModuleId}' and ` +
+            `'${secondModuleId}'. A table has one owner (R4.3), and emptying another module's ` +
+            `table between tests deletes rows that module's own tests rely on — so only the ` +
+            `module that owns it may declare it. A test that needs a neighbour's table emptied ` +
+            `does it in its own file, where the coupling is visible.`);
+        this.tableName = tableName;
+        this.firstModuleId = firstModuleId;
+        this.secondModuleId = secondModuleId;
+        this.name = 'ConflictingVolatileTableError';
+    }
+}
+/** A declared volatile table whose name is not an identifier. */
+export class UndeclarableVolatileTableError extends Error {
+    moduleId;
+    tableName;
+    constructor(moduleId, tableName) {
+        super(`'${moduleId}' declares the volatile table '${tableName}', which is not an unquoted ` +
+            `PostgreSQL identifier${tableName.trim() === '' ? ' (it is empty)' : ''}. The collected ` +
+            `set is interpolated into a \`truncate table … cascade\` statement, so a name carrying ` +
+            `a quote, a semicolon or nothing at all is refused where it is written down rather ` +
+            `than where it would run.`);
+        this.moduleId = moduleId;
+        this.tableName = tableName;
+        this.name = 'UndeclarableVolatileTableError';
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/support/index.js.map

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