@geonosis/testbed 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,437 @@
+# @geonosis/testbed
+
+An integration harness is not its engine. It is the **arrangement around one engine call**: where
+fixtures live and that nothing outside them is readable, what a database is called and how long it
+lives, what the network may reach, and who boots it. Two shipping repos wrote that arrangement
+separately — dielime around `medusaIntegrationTestRunner`, during.day around workerd and a Postgres
+cell — and neither one's arrangement needs its engine in order to be expressed. This package is the
+arrangement; the engines stay peer dependencies of the repo that runs them.
+
+What the two harnesses really do, measured file by file, is in
+[`docs/testbed-inventory-2026-08-30.md`](../../docs/testbed-inventory-2026-08-30.md).
+
+```bash
+pnpm add -D @geonosis/testbed
+```
+
+## The fixtures law
+
+```ts
+import { fixturesOnly } from '@geonosis/testbed'
+
+const fixture = fixturesOnly(new URL('./__fixtures__', import.meta.url).pathname)
+
+fixture('invoices', 'march.yaml') // -> /…/__fixtures__/invoices/march.yaml
+fixture('..', 'Purchase Orders & Specs') // throws
+```
+
+during.day's §4.3 — "a test reads and writes ONLY `apps/web/__tests__/__fixtures__/`" — exists
+because the directory next door in that repo holds real customers' documents. Its own guard compares
+strings, which three shapes get past, and all three are refused here:
+
+| shape | what a string-prefix guard does |
+|---|---|
+| `fixture('/etc/passwd')` | `resolve` reads /etc/passwd; `join` quietly reads `<root>/etc/passwd` |
+| a sibling named `<root>-production` | `resolved.startsWith(root)` is true, and it is a different directory |
+| a symlink inside the root pointing out | every character of the path is inside the root |
+
+The first is refused for naming an absolute path rather than reinterpreted; the second by comparing
+against `root + path.sep`; the third by resolving through `realpath`. A path that does not exist yet
+— a fixture about to be written — is judged as if it had been.
+
+## Defining a testbed
+
+```ts
+import { createHash } from 'node:crypto'
+import { defineTestbed } from '@geonosis/testbed'
+
+export const testbed = defineTestbed({
+  adapter: myAdapter,
+  database: {
+    name: (suite) => createHash('sha1').update(suite).digest('hex').slice(0, 12),
+    per: 'suite',
+  },
+  fixtures: new URL('./__fixtures__', import.meta.url).pathname,
+  network: 'none',
+})
+```
+
+`per` is `'suite'` (dielime: one database per `describe`), `'file'`, or `'run'` (during.day: one
+cell for the whole run, tables emptied per test).
+
+Everything it can refuse, it refuses **when it is defined**, not at the first boot:
+
+- an adapter with no `id` — every diagnostic names it
+- an adapter declaring `snapshot` without `restore`, or the reverse: half of per-test isolation is
+  not isolation
+- a `per` it does not know — a config read from JSON has whatever spelling someone typed
+- `network: { allow: [] }` — an allow list of nothing is `'none'` spelt so it reads as permission
+- no fixtures directory
+
+And when a database name is derived:
+
+- an empty name
+- a name over **63 bytes** — Postgres truncates there, and the truncation is a NOTICE nobody reads
+- a name a **different key already took**. `sha1(description).slice(0, 12)` is 48 bits; two suites
+  that collide share a database, and the second one's reset empties the first one's rows with both
+  green. Neither source repo notices this; this refuses it.
+
+## The adapter contract
+
+```ts
+type TestbedAdapter<Db> = {
+  id: string
+  boot: (ctx: BootContext) => Promise<{ db: Db; teardown: () => Promise<void> }>
+  snapshot?: () => Promise<void>
+  restore?: () => Promise<void>
+  waitFor?: (kind: string, predicate: () => boolean | Promise<boolean>) => Promise<void>
+}
+```
+
+`boot` is all that is required. The rest is what a particular engine can do: Medusa snapshots to a
+Postgres TEMPLATE database and restores from it before every test; during.day's cell cannot, and
+truncates instead. The `BootContext` is **frozen**, including its allow-list array — an adapter that
+wrote its own state onto it would carry it into the next boot.
+
+## The conformance suite
+
+```ts
+import { runAdapterConformance } from '@geonosis/testbed'
+
+it('conforms', async () => {
+  const report = await runAdapterConformance(myAdapter, {
+    probe: { read: (db) => db.rows(), write: (db) => db.insert(…) },
+  })
+
+  expect(report.passed, JSON.stringify(report.checks, null, 2)).toBe(true)
+})
+```
+
+Exported because consumers write adapters this repo never sees, and an adapter that has not been
+through this is a claim. Each check is a property one of the two harnesses really depends on:
+
+| check | why |
+|---|---|
+| `boot returns a handle` | a boot that resolves with `db: undefined` fails later, somewhere else |
+| `restore before a snapshot is refused` | Medusa spends a `databaseTemplateReady` flag on exactly this; restoring a template nobody took returns whatever the database happened to hold |
+| `restore returns the snapshot` | a no-op `restore` is invisible without writing a row — see the probe below |
+| `waitFor rejects when it never comes true` | a `waitFor` that resolves on timeout is worse than none |
+| `waitFor resolves when it comes true` | and one that never resolves is a hung suite |
+| `teardown is idempotent` | dielime wires cleanup to `afterAll` **and** to SIGTERM/SIGINT; on a cancelled run both fire |
+| `boots again after teardown` | a run-lifetime adapter has to survive re-entry |
+
+It never throws for the adapter's sake — a broken adapter is a failed check carrying its own message
+in `detail`, because a conformance run that dies tells the reader less than one that reports.
+
+**The probe.** This package cannot write a row through someone else's handle, and without writing
+one a no-op `restore()` is indistinguishable from a real one. So `restore returns the snapshot` is
+**skipped by name** when no probe is given — `report.skipped` is a separate list from
+`report.checks`, because a check that did not run is not a check that passed. Adapters with no
+`snapshot`/`restore` and no `waitFor` skip those checks and still pass; they are optional, not
+absent.
+
+## `@geonosis/testbed/medusa-built`
+
+dielime's `runIntegrationTest` — 26 lines that 106 integration suites go through — generalised, and
+carrying the refusals its own comments describe but its code does not make.
+
+```ts
+import { medusaIntegrationTestRunner } from '@medusajs/test-utils'
+import { createMedusaIntegrationTest } from '@geonosis/testbed/medusa-built'
+import { describe } from 'vitest'
+
+export const { adapterFor, runIntegrationTest } = createMedusaIntegrationTest({
+  describe,
+  root: resolve(import.meta.dirname, '../..'),
+  runner: medusaIntegrationTestRunner,
+})
+```
+
+**The engine is injected, never imported.** `@medusajs/test-utils` is a peer of the repo that runs
+it — a package that reached for it could not be installed by a repo on another runtime, and could
+not be tested without a database. `MedusaSuiteLike` is a structural type over what the runner really
+hands a suite.
+
+| option | default | why |
+|---|---|---|
+| `root` | required | the app directory |
+| `builtDir` | `.medusa/server` | Medusa's own output; the loaders and migrations must run as in production |
+| `databaseName` | `sha1(description).slice(0, 12)` | dielime's derivation, kept exactly — the engine appends `-integration-<worker>` and lowercases |
+| `connectionEnv` | `['DB_HOST', 'DB_PORT', 'DB_USERNAME']` | Medusa's own `getDatabaseURL` keys; `[]` to take its defaults deliberately |
+| `nodeEnv` | `'test'` | `false` when the repo checks it itself |
+| `requireBuilt` | `true` | |
+| `env`, `fixtures`, `waitForMs` | — | `fixtures` is optional: dielime's suites build their world through the booted app |
+
+### What it refuses, and why each one is worth a refusal
+
+- **an unbuilt server.** "`.medusa/server` must be rebuilt before integration tests" is a law in
+  dielime's docs enforced by nothing. Unbuilt, the run dies inside a Medusa loader *after* the
+  database has been created.
+- **`NODE_ENV` that is not `test`.** It selects the in-memory cache, event bus and workflow engine,
+  and it is read while the app loads — setting it afterwards is too late.
+- **a connection variable that is unset.** This is the sharp one. Medusa **defaults every one** of
+  `DB_HOST`/`DB_PORT`/`DB_USERNAME`, so an unset variable is not an error: the suite quietly
+  connects to whatever is on the default host and port. dielime's Postgres moved from 5433 to 5434
+  because another project's embedded cell took 5433; with the defaults, a stale environment reaches
+  the other project's database and the suite goes green against it.
+- **two suites that derive one database name.** 48 bits of sha1. They share a database, and each
+  one's reset empties the other's rows, with both green.
+
+### The adapter
+
+`adapterFor(suiteOptions)` wraps what the runner hands a suite. It **attaches** rather than boots —
+the runner owns the application's lifecycle, creating the database, migrating, snapshotting to a
+Postgres TEMPLATE and restoring from it before every test. Two things it adds:
+
+- **`restore()` refuses when this adapter took no `snapshot()`.** The runner keeps a
+  `databaseTemplateReady` flag for its own `beforeEach`; the `dbUtils` object it hands the suite
+  carries no such guard, so a direct `restore()` returns whichever template was last written.
+- **`waitFor('workflows', predicate)`** drains `utils.waitWorkflowExecutions()` and then reads the
+  predicate, on a deadline, rejecting when it never comes true. The engine calls
+  `waitWorkflowExecutions` in every `afterEach`; a test that asserts on a workflow's side effect
+  needs it *before* the assertion. dielime never names it — `grep` over its tree returns nothing.
+
+### The real-engine smoke is the consumer's step
+
+This package is proven against a **stub** of `medusaIntegrationTestRunner`, because the contract is
+what it owns. Booting a Medusa app needs a Postgres, a built server and about two minutes, and none
+of those belong in a kit's suite. The consumer's adoption step is: point one existing integration
+suite at `createMedusaIntegrationTest`, run `pnpm test:integration`, and confirm the same pass line
+and the same database name as before.
+
+## `@geonosis/testbed/workerd`
+
+during.day's harness, in three pieces. Each one is a mechanism its repo built after a specific
+failure, and each is proven here against stubs of the engine — the real workerd pool and a real
+Postgres are the consumer's.
+
+### 1. The runner whose exit code lies
+
+```ts
+import { runStrict, verdictOf } from '@geonosis/testbed/workerd'
+
+const { code, verdict } = await runStrict({ args: ['vitest', 'run', ...process.argv.slice(2)] })
+if (!verdict.ok) {
+  process.stderr.write(`\n${verdict.why}\n`)
+  process.exit(1)
+}
+process.exit(code)
+```
+
+`@cloudflare/vitest-pool-workers` **exits 0 with failing tests**. Every workerd green in the repo
+this comes from was hollow until something read the report instead of the exit code. `verdictOf`
+refuses three things:
+
+| report | verdict |
+|---|---|
+| absent | a crash before the reporter is not a pass |
+| `{ success: false, numFailedTests: 0 }` | the run did not finish; **checked first**, because anything counting failures reads this as a pass |
+| `{ success: true, numFailedTests: n > 0 }` | `n` test(s) failed |
+
+A clean report does **not** launder a non-zero exit: `code` is returned unchanged and the caller
+exits with it.
+
+This judgement is deliberately **not** shared with `@geonosis/ratchet`'s `testFailures` counter,
+which reads the same field. They answer different questions — "should this process fail" versus "how
+much debt is there" — and they are installed for different reasons; coupling them would put a
+ratchet in every repo that only wanted a harness. The contract is written down here, and each
+package holds it independently. The proof is a real spawned process that lies in each of the three
+ways above, not a mocked one.
+
+### 2. The config that has no remote binding to call
+
+```ts
+import { deriveLocalOnlyConfig } from '@geonosis/testbed/workerd'
+
+const configPath = deriveLocalOnlyConfig({
+  dropVars: ['LOCAL_AI_URL'],
+  source: new URL('./wrangler.jsonc', import.meta.url).pathname,
+})
+```
+
+An `ai` binding is **always** remote: the pool resolves the account against `api.cloudflare.com` the
+moment it sees one, before a single test runs — a network call, a credential and a bill in the
+middle of the suite. So the test worker gets the real config with those bindings removed.
+
+- **Derived, not duplicated.** Read from the real `wrangler.jsonc` on every start, so a binding added
+  there is in the suites the same day. This is what makes "tests never call a model" a property of
+  the runtime rather than a promise about the code: in the test worker there is no `env.AI` to call.
+- **Every named environment too.** They inherit nothing per binding, so each repeats it, and a block
+  missed is a network call nobody expected.
+- **Written BESIDE the source**, and a `target` containing a path separator is **refused**: every
+  relative path in a wrangler config (`main`, `migrations_dir`) resolves against the directory the
+  config sits in, so a copy one level deeper resolves `src/index.ts` to a file that is not there.
+- JSONC's line comments and trailing commas are stripped, since `JSON.parse` refuses both.
+
+`remoteOnly` defaults to `['ai']` — a platform fact, not a repo's — and is overridable.
+
+### 3. One cell for the run
+
+```ts
+import EmbeddedPostgres from 'embedded-postgres'
+import { createCellServer, workerdAdapter } from '@geonosis/testbed/workerd'
+
+const cell = await createCellServer({
+  cluster: ({ databaseDir, port }) =>
+    new EmbeddedPostgres({ databaseDir, password: 'postgres', persistent: false, port, user: 'postgres' }),
+  prepare: async (connectionString) => {
+    await migrateCell(connectionString)
+    return appConnectionStringOf(connectionString, 'app-password')
+  },
+})
+```
+
+`embedded-postgres` is a **peer**, injected as a factory. `CELL_CONNECTION_STRING` (rename it with
+`connectionStringEnv`) takes an externally-owned cell instead — which is how the same suite runs
+against every Postgres major a deployment might use — and that one is prepared and **never
+stopped**: in CI the container is thrown away, and a managed instance is not the suite's to stop.
+Otherwise a throwaway cluster starts on a port found by binding `:0`, in a fresh temp directory.
+
+Two things this adds to the shape it came from: `stop()` is idempotent, and **a cluster whose
+`prepare` throws is stopped rather than leaked** — a failed migration in that repo leaves a Postgres
+and its data directory up for the rest of the session.
+
+`workerdAdapter({ cell, execute, tables, before })` is the adapter. There is no template database,
+so `restore()` is a `TRUNCATE`, and **empty is the only state a truncate can return to**:
+`snapshot()` therefore does not record the current rows, it *empties* the tables and marks that
+point. That is exactly the split the source repo already has between its two setup files — the
+truncate-per-test suites are the unseeded ones. A suite that seeds re-seeds after each restore.
+
+`truncateAllStatement(tables)` is one statement for any number of tables, because a `DELETE` per
+table inside a transaction cost twenty-eight round trips before every test. It refuses an empty
+table list (a reset that resets nothing reads as isolation) and any name that is not a plain
+identifier, since the list is usually derived from a schema object.
+
+**No `waitFor`.** The source repo has none — its raised timeouts carry the waiting — so this adapter
+declares none, and the conformance suite reports those checks as `skipped` rather than passed.
+
+## The database matrix, and `geonosis-testbed`
+
+```jsonc
+// geonosis.json
+{
+  "testbed": {
+    "matrix": {
+      "command": "bun run --cwd packages/db test",
+      "connectionEnv": "CELL_CONNECTION_STRING",
+      "connectionString": "postgres://postgres:postgres@127.0.0.1:5432/postgres",
+      "majors": ["17", "18"],
+      "name": "cells",
+      "setup": ["bun install --frozen-lockfile"]
+    }
+  }
+}
+```
+
+```bash
+geonosis-testbed matrix --out .github/workflows/cells.yml
+geonosis-testbed strict -- packages/db      # judge the report, not the exit code
+```
+
+The rendered workflow is `templates/ci/db-matrix.yml`, which is checked in **as the renderer's own
+output for the documented example** and tested to still equal it — a template committed beside a
+generator drifts from it the first time either is touched, and then the thing people copy is not the
+thing the code produces.
+
+**Two jobs, not one, and that is the point.** The source repo runs its data layer against Postgres
+17 and 18 in a matrix, and against an *embedded* cluster in every other job — because the connection
+variable is unset there. The embedded leg is real, it is tested, and it is invisible: nothing in
+that workflow says the suite has a second backend. Here it is `<name>-embedded`, with a name.
+
+What the renderer refuses: a matrix with no legs (`embedded: false` and no majors), no command, a
+job name that is not a name, and — the one that matters — **majors with an empty connection string**,
+which would run the embedded cell under a container's name and go green twice against the same
+database while claiming to have tested two.
+
+`fail-fast: false` and the `pg_isready` health check are not decoration: one major failing must not
+hide whether the other passes, and without the health check the first connection races the container
+and the suite fails for a reason that is not in the code.
+
+## The rule: `no-mock-db-in-integration`
+
+Preset **`testbed`**, in `@geonosis/oxlint-plugin-biological-architecture`.
+
+```jsonc
+"biological-architecture/no-mock-db-in-integration": ["error", {
+  "dbModules": ["@repo/db"],
+  "integrationDirs": ["__tests__/integration"],
+  "mockNames": []
+}]
+```
+
+An integration suite that mocks its database proves that a procedure calls what it says it calls,
+and nothing about what comes back — which is what an integration test exists to check.
+
+**Both consumers of this kit pass it today**, measured: dielime's 106 integration files contain zero
+`vi.mock` calls, and during.day's whole tree contains zero. The landmine is a third repo's, where 35
+of 43 test files share one context helper carrying `db: mockDb`, and they are the gate. That is why
+`integrationDirs` and `dbModules` are required with no defaults — a default drawn from two repos
+that do not have the pattern would match nothing and report a clean tree it never looked at.
+
+`mockNames` is for the shape no mock call can be seen in: a handle built in a setup file and threaded
+through a helper. It is empty by default; a repo that has one names it.
+
+## Adoption status — **NOT adopted** (D-027)
+
+Neither consumer depends on this package yet. `grep @geonosis/testbed` in dielime and in during.day
+finds nothing. What follows is what each migration is, written from what each repo measurably has
+today — see [`docs/testbed-inventory-2026-08-30.md`](../../docs/testbed-inventory-2026-08-30.md)
+for the numbers.
+
+### dielime
+
+Replace `apps/backend/integration-tests/utils/runner.ts` (26 lines, the entry point of all 106
+integration suites) with:
+
+```ts
+import { medusaIntegrationTestRunner } from '@medusajs/test-utils'
+import { createMedusaIntegrationTest } from '@geonosis/testbed/medusa-built'
+import { describe } from 'vitest'
+
+export const { adapterFor, runIntegrationTest } = createMedusaIntegrationTest({
+  describe,
+  root: resolve(import.meta.dirname, '../..'),
+  runner: medusaIntegrationTestRunner,
+})
+```
+
+Nothing else changes: the default `builtDir` is `.medusa/server`, the default derivation is the
+`sha1(description).slice(0, 12)` it already uses, and the default `connectionEnv` is the `DB_*` set
+its `setup.ts` already fills in. **The same 106 suites must produce the same database names**, which
+is the equivalence check — `moduleName` is printed by the engine's own `Creating database …` line.
+
+What it gains on the day it lands: a refusal instead of a loader crash when `.medusa/server` is
+stale, a refusal instead of a silent connection to port 5432 when the `DB_*` environment is not
+set — the failure that moving Postgres from 5433 to 5434 made possible, and which lands on another
+project's database — and a refusal instead of a shared database when two suite descriptions collide
+in 48 bits of sha1.
+
+Then `.github/workflows/`: dielime's CI is 26 lines and **has no integration job at all**. 106
+suites exist, none runs on a push. `geonosis-testbed matrix` renders one; `majors` for a Medusa
+backend is the Postgres versions it supports, and the embedded leg does not apply, so
+`embedded: false`.
+
+`no-mock-db-in-integration` costs nothing to enable — 0 findings today, proven not silent in
+`proofs/022-W9-consumers/`.
+
+### during.day
+
+Four replacements, none of which changes what runs:
+
+| today | becomes |
+|---|---|
+| `scripts/vitest-strict.ts` (57 lines, the `test` script of 3 packages) | `geonosis-testbed strict`, or `runStrict`/`verdictOf` |
+| `apps/api/testing/local-only-config.ts` (98 lines) | `deriveLocalOnlyConfig({ dropVars: ['LOCAL_AI_URL'], source })` |
+| `packages/db/testing/cell-server.ts` (72 lines) | `createCellServer({ cluster, prepare })` with `EmbeddedPostgres` injected |
+| `packages/db/testing/reset.ts` | `workerdAdapter({ before: ['drop trigger …'], tables })`, or `truncateAllStatement` |
+
+Its `.github/workflows/ci.yml` `cells` job becomes `geonosis-testbed matrix` output, with one
+difference that is the reason to do it: the **embedded leg becomes a named job**. Today it is real
+and tested and invisible, running in every job where `CELL_CONNECTION_STRING` happens to be unset.
+
+Two behaviour changes it gets for free: `stop()` becomes idempotent, and a cluster whose `prepare`
+throws is **stopped** instead of left running with its data directory for the rest of the session.
+
+Nothing its `CLAUDE.md` names is proposed for deletion here, per the 2026-08-30 boundary: `§4.3`'s
+fixtures law stays its law — `fixturesOnly` is that law with three more refusals in it, not a
+replacement for the sentence.

package/bin/geonosis-testbed.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
+// produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
+import '../dist/cli.js'