@endora-commerce/test-kit 0.100.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Endora sp. z o.o. and the Endora Commerce contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# `@endora-commerce/test-kit`
+
+Composes an Endora Commerce platform for a test, from a composition its caller supplies.
+
+`specs/109-backend-test-kit/` is the feature; `contracts/test-kit-package.md` is normative.
+
+---
+
+## Why it exists
+
+`backend/test/helpers/test-server.ts` is 2993 lines and composes a platform by **finding**
+one: the generated module list, the application's ORM configuration, the resolved manifest
+registry, the overlay loader and the package loader. Every one of those is a fact about
+*this repository's tree*, so a package cannot have any of them — which is why a module
+package's server-bound test had nowhere to run but `backend/test`, and why 211 such files
+are still there.
+
+68 % of a server-bound test file's wall clock is that composition (116.6 s of a 171 s run,
+median 4700 ms). The kit does not make it cheaper. What it makes is **reachable**: the same
+composition, from a package, for a module that this repository has never heard of.
+
+## The inversion
+
+`composeTestServer` takes a `PlatformComposition` and never builds one. Its four members
+are the four things only the caller knows:
+
+| Member | What the caller supplies |
+| --- | --- |
+| `modules` | the module entries to compose — this repository's `MODULES` plus overlay plus discovered packages, or a third party's own set |
+| `orm` | an opener and a closer |
+| `manifests` | the loaded manifest registry the lifecycle needs |
+| `testSupport` | the contributions of exactly the modules in `modules` |
+
+Everything else it does is host-shaped and true of any platform: the container, the ORM
+registrations, the audit writer, the event and command buses, the two Redis clients, the
+registry cache, the settings and sales-channel kernels, one `composeModules` pass, one
+contribution window, the tenancy request-scope hook, one boot phase, `buildServer`, and
+`teardownTestServer`.
+
+It does **not** read `process.env.DEPLOYMENT`, walk `node_modules` or read a generated
+artefact. Each 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.
+
+```ts
+import { composeTestServer, teardownTestServer } from '@endora-commerce/test-kit/server';
+
+const handle = await composeTestServer({
+  composition: { modules, orm: { open, close }, manifests },
+  buildTenantContext: async (request) => resolveTenantContext(actorOf(request)),
+  prepareDatabase: async ({ em }) => { /* truncate, seed */ },
+});
+
+const response = await handle.app.inject({ method: 'GET', url: '/api/v1/…' });
+const service = handle.container.cradle.myService;
+
+await teardownTestServer(handle);
+```
+
+**Nothing on `TestServerHandle` names a module.** The application's own handle carries 29
+module-specific fields today, and every one of them is a container resolution its readers
+can make for themselves: `handle.container.cradle` is how a caller reaches a module's
+service. Draining those fields is Phase 2.
+
+## What it refuses
+
+A composition whose `modules` lacks a module declaring `activation.nonDeactivatable` is
+refused by `composeModules` **before the first module registers** — with
+`RequiredModuleAbsentError`, naming the module, the sentence its own manifest gives and the
+remedy. The kit adds no second check and swallows nothing on that path, because a paraphrase
+written here would be a second answer to a question the platform already answers.
+
+That matters more than it sounds: 23 modules declare `nonDeactivatable`, and the union with
+each module's transitive `dependencies` closure is a median of 23–24 of 70. So "just my
+module" is not a composition anybody can run, and a stranger's first attempt is the one most
+likely to meet this.
+
+## The subpaths
+
+| Subpath | Contents |
+| --- | --- |
+| `./server` | `composeTestServer`, `teardownTestServer`, and the two types they take and return |
+| `./database` | the per-invocation database lease (issue #189), and the naming and selection rules behind it |
+| `./support` | `TestSupportContribution` — what a module publishes at its own `./test-support` |
+
+There is **no root export**: a caller names the seam it wants, so a test that needs only the
+lease does not load the server.
+
+`./off-state` (`expectModuleAbsent`, `withModuleOff`) is in the contract's table and is not
+here yet. `backend/test/helpers/off-state.ts` is `check:off-state-coverage`'s subject and
+that check's caller walk is `backend/test/**`, so moving the file before the walk follows it
+(T074) would take 46 modules' off-state proofs out of the population that judges them.
+
+## Running its tests
+
+```bash
+pnpm --filter @endora-commerce/test-kit run test           # service-free
+pnpm --filter @endora-commerce/test-kit run test:services  # needs PostgreSQL and Redis
+```
+
+Two configurations rather than one with a condition, because a condition is a green that can
+quietly become "not looking" (issue #113). CI's `test:frontend` job runs every non-backend
+member's `test` script in an image with no service containers; `test:kit` runs the second
+half beside the services.
+
+The service-bound tests compose a fixture platform that is **nobody's module** — two
+synthetic modules, one `@OrgScoped` entity, one route — because the kit may name no module
+package (R1.5). That is the point rather than an inconvenience: what those tests have to
+prove is that the seam works for a *stranger's* composition.

package/dist/database/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `./database` — the per-invocation database lease (feature 109, R1.1).
+ *
+ * The cheapest of the kit's subpaths and the one that proves the package
+ * shape: the mechanism (issue #189) never had a module coupling, only an
+ * application one, and that coupling is now two callbacks the caller supplies.
+ *
+ * What is published here is the seam plus the naming and selection rules, both
+ * halves for the same reason: the two things whose correctness protects the dev
+ * database and other people's databases are pure, and a consumer that wants to
+ * assert them — as `backend/test/unit/harness/run-isolation.test.ts` does —
+ * must be able to name them without a service.
+ */
+export { assertTestDatabaseUrl, leaseRunDatabase, type RunDatabaseLease, type RunDatabaseLeaseInput, type TemplateIdentity, } from './lease.js';
+export { BASE_DATABASE_URL_ENV, ISOLATION_ENV, KEEP_DATABASE_ENV, STALE_RUN_DATABASE_MS, STALE_TEMPLATE_MS, SWEEP_LIMIT, TEMPLATE_DATABASE_ENV, TEMPLATE_DIGEST_LENGTH, TEST_DATABASE_NAME_PATTERN, advisoryLockKey, databaseNameOf, formatTemplateProvenance, isolationMode, keepRunDatabase, parseRunDatabaseName, parseTemplateDatabaseName, parseTemplateProvenance, randomRunToken, redisUrlNamesDatabase, redisUrlWithDatabase, runDatabaseName, runIdentity, sharedDatabaseReason, staleTemplates, strandedRunDatabases, templateDatabaseName, templateDigest, templateDrift, templateFamilyName, withDatabase, type IsolationMode, type StaleTemplateSelection, type StrandedSelection, type TemplateDrift, type TemplateInputs, type TemplateProvenance, type TemplateSource, } from './run-isolation.js';
+export { appliedMigrations, cloneTemplateForCaller, dropRunDatabase, leaseRedisDatabase, provisionRunDatabase, sweepStaleTemplates, sweepStrandedRunDatabases, type Log, type ProvisionInput, type RedisLease, type RunDatabase, } from './provision.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/database/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,GAAG,EACR,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAC"}

package/dist/database/index.js

@@ -0,0 +1,17 @@
+/**
+ * `./database` — the per-invocation database lease (feature 109, R1.1).
+ *
+ * The cheapest of the kit's subpaths and the one that proves the package
+ * shape: the mechanism (issue #189) never had a module coupling, only an
+ * application one, and that coupling is now two callbacks the caller supplies.
+ *
+ * What is published here is the seam plus the naming and selection rules, both
+ * halves for the same reason: the two things whose correctness protects the dev
+ * database and other people's databases are pure, and a consumer that wants to
+ * assert them — as `backend/test/unit/harness/run-isolation.test.ts` does —
+ * must be able to name them without a service.
+ */
+export { assertTestDatabaseUrl, leaseRunDatabase, } from './lease.js';
+export { BASE_DATABASE_URL_ENV, ISOLATION_ENV, KEEP_DATABASE_ENV, STALE_RUN_DATABASE_MS, STALE_TEMPLATE_MS, SWEEP_LIMIT, TEMPLATE_DATABASE_ENV, TEMPLATE_DIGEST_LENGTH, TEST_DATABASE_NAME_PATTERN, advisoryLockKey, databaseNameOf, formatTemplateProvenance, isolationMode, keepRunDatabase, parseRunDatabaseName, parseTemplateDatabaseName, parseTemplateProvenance, randomRunToken, redisUrlNamesDatabase, redisUrlWithDatabase, runDatabaseName, runIdentity, sharedDatabaseReason, staleTemplates, strandedRunDatabases, templateDatabaseName, templateDigest, templateDrift, templateFamilyName, withDatabase, } from './run-isolation.js';
+export { appliedMigrations, cloneTemplateForCaller, dropRunDatabase, leaseRedisDatabase, provisionRunDatabase, sweepStaleTemplates, sweepStrandedRunDatabases, } from './provision.js';
+//# sourceMappingURL=index.js.map

package/dist/database/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/database/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GAIjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,YAAY,GAQb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,GAK1B,MAAM,gBAAgB,CAAC"}

package/dist/database/lease.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The per-invocation database lease, as a seam a caller drives (feature 109,
+ * T022; the mechanism is issue #189's).
+ *
+ * ## What it does, unchanged
+ *
+ * One `vitest run` gets its **own** database — `<base>_r_<stamp>_<rand>`, a
+ * `create database … template` clone of the migrated `<base>_tpl_<digest>` —
+ * and its **own** Redis logical database, leased in index 0. Both are released
+ * when the run ends and swept if it crashed. Before that, isolation used to be
+ * per database and per Redis instance and never per invocation, so a second
+ * `vitest run` landed its truncate inside the first one's setup, and every
+ * symptom of that is indistinguishable from a real failure.
+ *
+ * ## What moved, and why this is a seam rather than a script
+ *
+ * It was `backend/test/global-setup.ts`, whose isolated path could not be
+ * reached from outside `backend`. The two things in it that are *this
+ * repository's* — which migrations exist, and what "migrated" means for its
+ * schema — are the two the caller supplies:
+ *
+ *   - **`identity`** is the digest over the caller's whole migration input.
+ *     Two callers whose input differs get two templates and cannot contaminate
+ *     each other; two that agree share one and pay one migration pass between
+ *     them.
+ *   - **`migrateTemplate`** is applied to the template while `DATABASE_URL`
+ *     names it. It is a callback rather than a value for a reason that survives
+ *     the move: an ORM configuration captures `DATABASE_URL` at import, once
+ *     per process, so the import has to happen after this function has pointed
+ *     that variable at the template.
+ *
+ * Nothing here reads a generated artefact, walks `node_modules` or consults
+ * `process.env.DEPLOYMENT`. Every one of those is a fact about the caller's
+ * process (R2.2), and a kit that answered them would answer them differently
+ * from the platform that composes for real.
+ *
+ * ## The two documented overrides behave exactly as they did
+ *
+ * `BACKEND_TEST_ISOLATION=shared` restores the pre-#189 behaviour of every
+ * invocation sharing one database, and `BACKEND_TEST_KEEP_DATABASE=1` keeps the
+ * run's database for a post-mortem instead of dropping it. Both are read here,
+ * from the same two constants the naming rules use — see
+ * `backend/test/README.md` § *One database per invocation*, which is still the
+ * document that describes them.
+ */
+import { type Log, type ProvisionInput } from './provision.js';
+/** The migration set this run's platform is, exactly as `provisionRunDatabase` takes it. */
+export type TemplateIdentity = ProvisionInput['identity'];
+export interface RunDatabaseLeaseInput {
+    /**
+     * The base test DSN. The run database and the template are **named from it**,
+     * and it is never itself what the workers connect to on the isolated path.
+     */
+    readonly baseUrl: string;
+    /** Which migration set this run has — the caller's, because the migrations are. */
+    readonly identity: TemplateIdentity;
+    /**
+     * Apply the caller's schema to the template database at this URL.
+     *
+     * Called with `DATABASE_URL` already pointing at the template, so an ORM
+     * configuration imported inside it captures the right database.
+     */
+    readonly migrateTemplate: (templateUrl: string) => Promise<void>;
+    /**
+     * The migration class names this run applies, in order.
+     *
+     * Used on the **shared** path only, and only to warn: a shared database
+     * accumulates a migration from another branch, and a test that drives the
+     * migrator then reads that as a failure of the code under test. Nothing here
+     * rebuilds a shared database — it is the operator's, named by them.
+     */
+    readonly configuredMigrationNames?: () => Promise<readonly string[]>;
+    /** Defaults to `REDIS_URL`, or `redis://localhost:6379`. */
+    readonly redisUrl?: string;
+    /** Defaults to `process.env`, which is also what the lease writes into. */
+    readonly env?: NodeJS.ProcessEnv;
+    readonly log?: Log;
+}
+export interface RunDatabaseLease {
+    /** Which path this lease took. `shared` means nothing was provisioned. */
+    readonly mode: 'per-invocation' | 'shared';
+    /** The DSN every worker of this invocation will use — also written to `DATABASE_URL`. */
+    readonly databaseUrl: string;
+    /** The run database's name, or `undefined` on the shared path. */
+    readonly databaseName: string | undefined;
+    /** The template this run was cloned from, or `undefined` on the shared path. */
+    readonly templateName: string | undefined;
+    /** The Redis DSN this invocation owns, or `undefined` when the caller's already named one. */
+    readonly redisUrl: string | undefined;
+    /** Drop the run database and release the Redis index. Idempotent. */
+    readonly release: () => Promise<void>;
+}
+/**
+ * The `_test` judgement, applied to the base DSN before anything is created.
+ *
+ * Exported because it is the guard a caller wants **before** it decides to
+ * lease at all, and because a caller that resolves its own DSN should not
+ * reimplement the refusal. `ALLOW_NON_TEST_DATABASE_URL=1` is the documented
+ * override and stands down the isolation with it (see `sharedDatabaseReason`):
+ * a name derived from a base that already breaks the convention would break it
+ * too, and isolation refuses to widen the judgement.
+ */
+export declare function assertTestDatabaseUrl(url: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Give this invocation its own database and its own Redis logical database.
+ *
+ * Writes `DATABASE_URL`, `BACKEND_TEST_BASE_URL`, `BACKEND_TEST_TEMPLATE` and
+ * `REDIS_URL` into `env` (which defaults to `process.env`), because a vitest
+ * worker inherits the parent's environment and that inheritance **is** the
+ * mechanism by which a run's actual DSN reaches the files that use it. A caller
+ * that spawns a CLI from a test reads `DATABASE_URL`, never `TEST_DATABASE_URL`
+ * — the second names the base.
+ */
+export declare function leaseRunDatabase(input: RunDatabaseLeaseInput): Promise<RunDatabaseLease>;
+//# sourceMappingURL=lease.d.ts.map

package/dist/database/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../src/database/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAgBH,OAAO,EAML,KAAK,GAAG,EACR,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAExB,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AAE1D,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;;;;;OAOG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IACrE,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,QAAQ,CAAC;IAC3C,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,gFAAgF;IAChF,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAID;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAU/F;AA6BD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA8G9F"}

package/dist/database/lease.js

@@ -0,0 +1,204 @@
+/**
+ * The per-invocation database lease, as a seam a caller drives (feature 109,
+ * T022; the mechanism is issue #189's).
+ *
+ * ## What it does, unchanged
+ *
+ * One `vitest run` gets its **own** database — `<base>_r_<stamp>_<rand>`, a
+ * `create database … template` clone of the migrated `<base>_tpl_<digest>` —
+ * and its **own** Redis logical database, leased in index 0. Both are released
+ * when the run ends and swept if it crashed. Before that, isolation used to be
+ * per database and per Redis instance and never per invocation, so a second
+ * `vitest run` landed its truncate inside the first one's setup, and every
+ * symptom of that is indistinguishable from a real failure.
+ *
+ * ## What moved, and why this is a seam rather than a script
+ *
+ * It was `backend/test/global-setup.ts`, whose isolated path could not be
+ * reached from outside `backend`. The two things in it that are *this
+ * repository's* — which migrations exist, and what "migrated" means for its
+ * schema — are the two the caller supplies:
+ *
+ *   - **`identity`** is the digest over the caller's whole migration input.
+ *     Two callers whose input differs get two templates and cannot contaminate
+ *     each other; two that agree share one and pay one migration pass between
+ *     them.
+ *   - **`migrateTemplate`** is applied to the template while `DATABASE_URL`
+ *     names it. It is a callback rather than a value for a reason that survives
+ *     the move: an ORM configuration captures `DATABASE_URL` at import, once
+ *     per process, so the import has to happen after this function has pointed
+ *     that variable at the template.
+ *
+ * Nothing here reads a generated artefact, walks `node_modules` or consults
+ * `process.env.DEPLOYMENT`. Every one of those is a fact about the caller's
+ * process (R2.2), and a kit that answered them would answer them differently
+ * from the platform that composes for real.
+ *
+ * ## The two documented overrides behave exactly as they did
+ *
+ * `BACKEND_TEST_ISOLATION=shared` restores the pre-#189 behaviour of every
+ * invocation sharing one database, and `BACKEND_TEST_KEEP_DATABASE=1` keeps the
+ * run's database for a post-mortem instead of dropping it. Both are read here,
+ * from the same two constants the naming rules use — see
+ * `backend/test/README.md` § *One database per invocation*, which is still the
+ * document that describes them.
+ */
+import { BASE_DATABASE_URL_ENV, ISOLATION_ENV, KEEP_DATABASE_ENV, TEMPLATE_DATABASE_ENV, TEST_DATABASE_NAME_PATTERN, databaseNameOf, keepRunDatabase, redisUrlNamesDatabase, runIdentity, sharedDatabaseReason, templateDrift, withDatabase, } from './run-isolation.js';
+import { appliedMigrations, dropRunDatabase, leaseRedisDatabase, provisionRunDatabase, sweepStrandedRunDatabases, } from './provision.js';
+const DEFAULT_REDIS_URL = 'redis://localhost:6379';
+/**
+ * The `_test` judgement, applied to the base DSN before anything is created.
+ *
+ * Exported because it is the guard a caller wants **before** it decides to
+ * lease at all, and because a caller that resolves its own DSN should not
+ * reimplement the refusal. `ALLOW_NON_TEST_DATABASE_URL=1` is the documented
+ * override and stands down the isolation with it (see `sharedDatabaseReason`):
+ * a name derived from a base that already breaks the convention would break it
+ * too, and isolation refuses to widen the judgement.
+ */
+export function assertTestDatabaseUrl(url, env = process.env) {
+    const dbName = databaseNameOf(url);
+    if (!TEST_DATABASE_NAME_PATTERN.test(dbName) && !env['ALLOW_NON_TEST_DATABASE_URL']) {
+        throw new Error(`Refusing to run tests against database "${dbName}" — name must contain "_test" ` +
+            `(e.g. b2b_test). Set ALLOW_NON_TEST_DATABASE_URL=1 to override. ` +
+            `Resolved URL: ${url}`);
+    }
+    return url;
+}
+/** Create the base database if it is not there, so a first run on a fresh cluster works. */
+async function ensureDatabaseExists(testUrl, log) {
+    const dbName = databaseNameOf(testUrl);
+    const { Client: PgClient } = await import('pg');
+    const admin = new PgClient({ connectionString: withDatabase(testUrl, 'postgres') });
+    await admin.connect();
+    try {
+        const { rowCount } = await admin.query('select 1 from pg_database where datname = $1', [
+            dbName,
+        ]);
+        // `pg` types `rowCount` as `number | null`; for this existence probe `0`
+        // and `null` both honestly mean "no such database", and the value reaches
+        // nothing but this comparison.
+        if (rowCount === null || rowCount === 0) {
+            // A `pg_database` name cannot be parameterised in `create database`; the
+            // `_test` judgement above plus URL parsing keeps this from being
+            // injectable, and the re-check refuses anything the two let through.
+            const safeName = dbName.replace(/[^a-zA-Z0-9_]/g, '');
+            if (safeName !== dbName)
+                throw new Error(`Unsafe DB name: "${dbName}"`);
+            await admin.query(`create database "${safeName}"`);
+            log(`[test-kit] created database ${safeName}`);
+        }
+    }
+    finally {
+        await admin.end();
+    }
+}
+/**
+ * Give this invocation its own database and its own Redis logical database.
+ *
+ * Writes `DATABASE_URL`, `BACKEND_TEST_BASE_URL`, `BACKEND_TEST_TEMPLATE` and
+ * `REDIS_URL` into `env` (which defaults to `process.env`), because a vitest
+ * worker inherits the parent's environment and that inheritance **is** the
+ * mechanism by which a run's actual DSN reaches the files that use it. A caller
+ * that spawns a CLI from a test reads `DATABASE_URL`, never `TEST_DATABASE_URL`
+ * — the second names the base.
+ */
+export async function leaseRunDatabase(input) {
+    const env = input.env ?? process.env;
+    const log = input.log ?? ((message) => process.stdout.write(`${message}\n`));
+    const baseUrl = assertTestDatabaseUrl(input.baseUrl, env);
+    // The pre-#189 behaviour, on either of two grounds. The first is an explicit
+    // opt-out, worth having for a post-mortem — the run database is dropped when
+    // the run ends, and sometimes what you want is the database a failing run
+    // left behind, under a name you already know. The second is
+    // ALLOW_NON_TEST_DATABASE_URL: that override is somebody deliberately
+    // pointing the suite at a database whose name breaks the convention, and a
+    // name derived from it would break it too.
+    const shared = sharedDatabaseReason(env, databaseNameOf(baseUrl));
+    if (shared !== undefined) {
+        env['DATABASE_URL'] = baseUrl;
+        await ensureDatabaseExists(baseUrl, log);
+        await input.migrateTemplate(baseUrl);
+        log(`[test-kit] ${shared === 'explicit' ? `${ISOLATION_ENV}=shared` : 'ALLOW_NON_TEST_DATABASE_URL'}` +
+            ` — this invocation shares ${databaseNameOf(baseUrl)} with every other one.`);
+        // The shared database accumulates the same way a template does — a
+        // migration from another branch, or one of ours appended where the order
+        // does not put it — and a test that drives the migrator reads that as a
+        // failure of the code under test. This path only *says* so: the database is
+        // the operator's, named by them or kept by them for a post-mortem, so it is
+        // not this lease's to drop.
+        if (input.configuredMigrationNames !== undefined) {
+            const drift = templateDrift(await appliedMigrations(baseUrl), await input.configuredMigrationNames(), databaseNameOf(baseUrl));
+            if (drift) {
+                log(`[test-kit] WARNING: ${drift.message.replace(' Rebuilding it from empty.', '')} ` +
+                    `Nothing here rebuilds it, because you named it. A test that drives the migrator ` +
+                    `will fail against it for that reason and not for its own — drop it and re-run, ` +
+                    `or drop ${ISOLATION_ENV}=shared and let the isolated path rebuild its template.`);
+            }
+        }
+        return {
+            mode: 'shared',
+            databaseUrl: baseUrl,
+            databaseName: undefined,
+            templateName: undefined,
+            redisUrl: undefined,
+            release: async () => {
+                /* nothing was provisioned, so there is nothing to give back */
+            },
+        };
+    }
+    const run = await provisionRunDatabase({
+        baseUrl,
+        identity: input.identity,
+        migrateTemplate: async (templateUrl) => {
+            env['DATABASE_URL'] = templateUrl;
+            await input.migrateTemplate(templateUrl);
+        },
+        log,
+    });
+    env['DATABASE_URL'] = run.url;
+    // A file that drives the real migrator may not do it to the database its
+    // neighbours share — the run database is this invocation's only copy, so a
+    // migration sequence that dies half-way takes the whole invocation with it.
+    // Exporting the base and the template *name* is what lets such a file clone
+    // the same template this run was cloned from: by name, because by the time it
+    // asks, another invocation may have built a template of its own.
+    env[BASE_DATABASE_URL_ENV] = baseUrl;
+    env[TEMPLATE_DATABASE_ENV] = run.template;
+    // The same defect on the other service: a batch that "passed alone" would
+    // still have collided on Redis keys. An explicit index in REDIS_URL is
+    // somebody's deliberate choice and is left alone.
+    const redisBaseUrl = input.redisUrl ?? env['REDIS_URL'] ?? DEFAULT_REDIS_URL;
+    let lease;
+    if (redisUrlNamesDatabase(redisBaseUrl)) {
+        log(`[test-kit] REDIS_URL already names a logical database — leaving it alone.`);
+    }
+    else {
+        lease = await leaseRedisDatabase(redisBaseUrl, runIdentity(), log);
+        env['REDIS_URL'] = lease.url;
+    }
+    // Runs that crashed before their release. Best-effort, capped, and only ever
+    // over names this mechanism generated.
+    await sweepStrandedRunDatabases(baseUrl, run.name, log);
+    let released = false;
+    return {
+        mode: 'per-invocation',
+        databaseUrl: run.url,
+        databaseName: run.name,
+        templateName: run.template,
+        redisUrl: lease?.url,
+        release: async () => {
+            if (released)
+                return;
+            released = true;
+            await lease?.release();
+            if (keepRunDatabase(env)) {
+                log(`[test-kit] ${KEEP_DATABASE_ENV} is set — keeping ${run.name}. ` +
+                    `Drop it yourself, or leave it for the sweep in ~4 h.`);
+                return;
+            }
+            await dropRunDatabase(baseUrl, run.name, log);
+        },
+    };
+}
+//# sourceMappingURL=lease.js.map

package/dist/database/lease.js.map

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

package/dist/database/provision.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The half of per-invocation isolation (issue #189) that talks to a server.
+ *
+ * Split from `run-isolation.ts` so the naming and selection rules — the two
+ * things whose correctness protects the dev database and other people's
+ * databases — are unit-testable with no service at all, and run in the fast
+ * unit job. Nothing here is imported by a test file: `leaseRunDatabase` in
+ * `./lease.ts` is the only caller, and a vitest `globalSetup` calls that once
+ * per invocation in the parent process.
+ *
+ * `pg` and `ioredis` are imported dynamically for the same reason: a run that
+ * declared `BACKEND_TEST_SERVICES=none` never reaches this module, and should
+ * not pay to load a driver it will not dial.
+ */
+import type { Client } from 'pg';
+export type Log = (message: string) => void;
+/**
+ * The migration names applied to a database, in the order they were applied.
+ *
+ * `mikro_orm_migrations` is missing on a template that has just been created
+ * and on one that has never been migrated; both mean "nothing applied", which
+ * is a prefix of every order and so needs no rebuild.
+ */
+export declare function appliedMigrations(databaseUrl: string): Promise<string[]>;
+export interface RunDatabase {
+    /** The DSN every worker of this invocation will use. */
+    readonly url: string;
+    readonly name: string;
+    readonly template: string;
+}
+export interface ProvisionInput {
+    /** The DSN naming the base database, from TEST_DATABASE_URL or the default. */
+    readonly baseUrl: string;
+    /**
+     * Which migration set this run has — the caller's, because the migrations are.
+     *
+     * A **value**, unlike the callback this used to be, because a caller reads its
+     * own migration order out of whatever module assigns it and hands the answer
+     * over. That reading is what the callback existed to delay: **an ORM
+     * configuration captures `DATABASE_URL` at import**, once per process, and the
+     * parent used to import it while that variable was unset, whose fallback is
+     * the caller's *dev* database. `migrateTemplate` is still a callback for
+     * exactly that reason.
+     */
+    readonly identity: {
+        readonly digest: string;
+        readonly migrations: readonly string[];
+        readonly migrationFiles: number;
+        /**
+         * What each producer contributed and what the walk found of it. Printed
+         * rather than merely floored: a shortfall stops the run by name, but only
+         * this line says an origin was read at all, and "the walk saw 7% of itself"
+         * is the failure a number with no population behind it cannot report.
+         */
+        readonly origins: readonly {
+            readonly origin: string;
+            readonly registered: number;
+            readonly migrationFiles: number;
+        }[];
+    };
+    /** Applies pending migrations to the template and establishes the platform invariants. */
+    readonly migrateTemplate: (templateUrl: string) => Promise<void>;
+    readonly log?: Log;
+}
+/**
+ * Give this invocation its own database.
+ *
+ * Everything between taking the advisory lock and releasing it is serialized
+ * across invocations: identify the template, build it if it is not there or not
+ * what it claims, migrate it, disconnect from it, clone, collect the templates
+ * nobody uses any more. Holding the lock across the clone as well is deliberate
+ * — the clone is a fraction of a second, and it is what guarantees the template
+ * is idle at the moment the next invocation's migration opens a connection to
+ * it.
+ *
+ * The lock is taken on the `postgres` maintenance database: PostgreSQL advisory
+ * locks are scoped to a database, so every waiter has to agree on which, and it
+ * must not be the template — a session holding the lock there is exactly the
+ * session that would make the clone illegal. It is one key for the whole
+ * `<base>_tpl*` family rather than one per digest, because the sweep walks the
+ * templates of other digests (see `templateFamilyName`).
+ *
+ * **Which template, is the question this function exists to answer** (issue
+ * #289). It is `<base>_tpl_<digest>`, the digest being over this run's whole
+ * migration input, so a template is shared only by runs whose platform it
+ * actually is. Two things then have to agree before it is cloned: the
+ * provenance comment the build wrote on it, and the migration names it actually
+ * holds. Either disagreeing rebuilds it from empty — including "it says
+ * nothing", because a template that cannot say what it holds is the defect.
+ */
+export declare function provisionRunDatabase(input: ProvisionInput): Promise<RunDatabase>;
+/**
+ * A database of this run's template, for a caller that is not the invocation.
+ *
+ * The template is named by the caller, not re-derived here, and that is the
+ * point (issue #289): the lease resolved which template this run's
+ * platform is and exported the name, so a file cloning one mid-run gets the
+ * database the run itself was cloned from — not whatever `<base>_tpl` has
+ * become while the run has been going, which with several branches on one
+ * cluster is routinely another branch's schema.
+ *
+ * The advisory lock is the same one provisioning takes, and for the same
+ * reason: it is what keeps the template idle at the moment a clone starts.
+ * `setupMigratorTestDb` is the only caller — a test file that drives the real
+ * migrator and must not do it to the database its neighbours share.
+ */
+export declare function cloneTemplateForCaller(baseUrl: string, template: string): Promise<RunDatabase>;
+/**
+ * Drop the templates of migration sets nobody runs any more.
+ *
+ * Keying a template by its migration set is what stops two branches sharing
+ * one; this is the other half of that bargain, because a branch leaves its
+ * set's template behind the moment it gains a migration or is rebased. Called
+ * under the provisioning lock, so no template can be half-built while it runs.
+ *
+ * Best-effort and never fatal: a sweep that fails is a disk-space problem, not
+ * a reason to fail somebody's test run.
+ */
+export declare function sweepStaleTemplates(admin: Client, base: string, keep: string, log?: Log): Promise<string[]>;
+export declare function dropRunDatabase(baseUrl: string, name: string, log?: Log): Promise<void>;
+/**
+ * Drop the run databases of invocations that crashed before their teardown.
+ *
+ * Best-effort and never fatal: a sweep that fails is a disk-space problem, not
+ * a reason to fail somebody's test run.
+ */
+export declare function sweepStrandedRunDatabases(baseUrl: string, keep: string, log?: Log): Promise<string[]>;
+export interface RedisLease {
+    readonly url: string;
+    readonly index: number;
+    readonly runId: string;
+    readonly release: () => Promise<void>;
+}
+export declare function leaseRedisDatabase(redisUrl: string, runId: string, log?: Log): Promise<RedisLease>;
+//# sourceMappingURL=provision.d.ts.map