@xemahq/biome-database-nest 1.0.0 → 1.1.0

package/README.md

@@ -1,120 +1,16 @@
-<p align="center">
-<svg width="680" height="120" viewBox="0 0 680 120" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="@xemahq/biome-database-nest">
-  <rect width="680" height="120" rx="14" fill="#0B1020"/>
-  <g transform="translate(28,34)">
-    <path d="M26 0 L52 15 L52 45 L26 60 L0 45 L0 15 Z" fill="#8B5CF6" opacity="0.18"/>
-    <path d="M26 12 L41 21 L41 39 L26 48 L11 39 L11 21 Z" fill="#8B5CF6"/>
-  </g>
-  <text x="92" y="52" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="22" fill="#F8FAFC" font-weight="700">@xemahq/biome-database-nest</text>
-  <text x="92" y="80" font-family="ui-sans-serif,system-ui,sans-serif" font-size="15" fill="#94A3B8">Explicit database ownership and runtime wiring for Xema biomes</text>
-  <text x="652" y="105" text-anchor="end" font-family="ui-sans-serif,system-ui,sans-serif" font-size="12" fill="#475569">xema.dev</text>
-</svg>
-</p>
-
-<p align="center">
-  <a href="https://xema.dev">Website</a> &middot;
-  <a href="https://www.npmjs.com/package/@xemahq/biome-database-nest">npm</a>
-</p>
-
-<p align="center">
-  <img alt="npm" src="https://img.shields.io/npm/v/%40xemahq%2Fbiome-database-nest?color=2563eb&label=npm">
-  <img alt="license" src="https://img.shields.io/npm/l/%40xemahq%2Fbiome-database-nest?color=10b981">
-  <img alt="types" src="https://img.shields.io/npm/types/%40xemahq%2Fbiome-database-nest?color=3178c6">
-</p>
-
 # @xemahq/biome-database-nest
 
 > Explicit database ownership and runtime wiring for Xema biomes
 
 ## Overview
 
-Gives a Xema biome service explicit database ownership without coupling it to a
-deployment environment. It supplies schema-qualified Prisma wiring, validates
-image/schema compatibility, and provides a governed lifecycle for data
-cutovers that require an operator between expansion and contraction.
+Gives a biome service its own Postgres schema with schema-qualified Prisma wiring. It runs the service's migrations at boot, verifies the schema matches the image, and renews the short-lived runtime credential before it expires. It also provides an operator lifecycle for data cutovers where a destructive contraction must wait for a verified backfill.
 
 ## When to use it
 
 - Use it when a NestJS biome service stores data or owns database migrations.
-  The service names only its resource; the database pool issues a short-lived
-  migration credential (schema owner, direct connection) and a separate
-  DML-only runtime credential that the module renews before it expires.
-  An expired runtime credential refuses new connections and fails readiness.
-- A local `DB_*` override is a development path and is refused when
-  `NODE_ENV=production`.
-- Every Postgres session must run in UTC. The database or role default must be
-  `ALTER DATABASE … SET timezone TO 'UTC'`; the package only verifies it
-  (`SHOW TimeZone`) on the app pool, the bootstrap and operator migrations, and
-  refuses to start with `DatabaseSessionTimeZoneError` otherwise. It never sets
-  the zone itself.
-- Use its operator lifecycle when a destructive contraction must wait for a
-  verified backfill instead of running automatically at application startup.
-- Wrap the complete operator command with `withOperatorMigrationLock` so apply,
-  verification, and contraction cannot overlap across replicas.
-- Use `ExpiringLeaseStore` to elect one replica for a recurring sweep whose work
-  makes network calls. It coordinates through a lease row with an expiry rather
-  than a session advisory lock, so nothing depends on which pooled connection
-  served a call and no transaction is held open across the work.
-- Declare the Postgres extensions a service needs (`requiredExtensions`) and
-  the bootstrap VERIFIES they are installed in `public` before migrating. It
-  never creates one: an extension is a database-level prerequisite created by
-  the deployment's privileged bootstrap, and an absent one refuses the boot
-  with a message naming the extension, the database and the remedy.
-
-## Tables this SDK owns
-
-This SDK owns `xema_operator_migrations`, the ledger of the migration runner
-(the way Prisma owns `_prisma_migrations`). It is the table's only creator, and
-the ledger records its own creation. Consumers never declare it in
-`schema.prisma` or in a migration.
-
-Other SDKs' persistent tables (for example the authorization-facts outbox) are
-created by **SDK-owned versioned migrations**. The owning SDK declares a
-`SdkOwnedMigrationSet` (`owner`, versioned `migrations`, each naming the tables
-it `creates`, and the `tables` shapes), and its Nest module lists
-`contributeSdkOwnedMigrations(set)` in its `providers`. `BiomeDatabaseModule`
-collects every contribution in the graph (one set per owner, ordered by owner)
-and applies them in the migration phase. That is the only way a set reaches the
-phase: a biome wires nothing by hand.
-
-`runBiomeMigrations` is the one migration phase (the bootstrap runs it, and so
-does `pg-test-harness`). Under a per-schema lock it:
-
-1. reads the service's own migrations and refuses one that names an SDK-owned
-   table outside a PL/pgSQL function body;
-2. runs `prisma migrate deploy` (first, so a fresh schema is still empty for
-   Prisma);
-3. creates the ledger, or verifies that this SDK created it;
-4. applies each SDK-owned migration once, records it in the ledger with the
-   sha256 of its SQL, and verifies every owned table's shape.
-
-A table is never adopted. Every refusal below fails the boot with a coded error:
-
-| Code | When |
-| --- | --- |
-| `SDK_OWNED_TABLE_NOT_CREATED_BY_OWNER` | An owned table exists and the ledger has no record of its owner creating it (a service migration, a `schema.prisma` model or manual DDL created it). |
-| `SDK_OWNED_TABLE_SHAPE_MISMATCH` | An owned table differs from the shape its SDK declares. |
-| `SDK_OWNED_MIGRATION_CHANGED` | An applied migration's SQL is not the SQL this image ships. |
-| `SDK_OWNED_MIGRATIONS_UNKNOWN_TO_IMAGE` | The ledger records an SDK-owned migration this image does not ship (the database is newer, or the image dropped an SDK). |
-| `SERVICE_MIGRATION_TOUCHES_SDK_OWNED_TABLE` | A service migration names an SDK-owned table at migration time. |
-| `SDK_OWNED_MIGRATION_SET_INVALID` | A set is malformed (for example its SQL uses `IF NOT EXISTS`, or two owners claim one table). |
-| `SDK_OWNED_MIGRATIONS_NOT_APPLIED` | A module that owns tables is mounted in a graph with no migration phase. |
-| `SDK_OWNED_MIGRATIONS_CONFLICT` | Two different sets are contributed for one owner. |
-
-The remedy for the first three is a reset of the database schema, so the owning
-SDK creates and records its tables. The ledger is never edited by hand.
-
-The shape check compares each column's name, type, nullability and default, the
-primary key, every CHECK constraint (name and expression) and every index (name,
-uniqueness, key columns, predicate), and refuses a foreign key, exclusion
-constraint or constraint trigger on an owned table. It does not compare an
-index's access method, operator classes, collations or INCLUDE columns, ordinary
-triggers, row-security policies, privileges, the table owner or storage
-parameters.
-
-A released migration is immutable; a change is a new version. The package that
-owns a set pins `sdkOwnedMigrationDigests(set)` in a spec, so an edit fails
-there rather than at the boot of every deployed schema.
+- Use `withOperatorMigrationLock` around an operator migration command so replicas cannot overlap.
+- Use `ExpiringLeaseStore` to elect one replica for a recurring sweep without holding a transaction open.
 
 ## Installation
 
@@ -130,14 +26,6 @@ import {
   BiomeDatabaseModule,
 } from '@xemahq/biome-database-nest';
 
-// Mounted beside `XemaServiceModule.forBiome(<SERVICE>_BOOTSTRAP)` (a service)
-// or `XemaServiceModule.forWorker(<WORKER_KEY>_DESCRIPTOR)` (a worker, e.g.
-// `ORG_DATABASE_POOL_WORKER_DESCRIPTOR`),
-// which publish the manifest's `maximumPerInstance` the pool is sized from.
-// Without one the boot is refused; the number is never typed here.
-// The pool is exactly requests + activities + nexus + 2 (the SDK's own connections).
-// `DB_POOL_MAX_<KEY>` / `DB_POOL_MAX` is a feasibility ceiling only: below that
-// size the boot is refused with a `BiomeDatabasePoolOptionsError`, never shrunk.
 BiomeDatabaseModule.forRoot({
   biomeId: 'example',
   migrationMode: BiomeDatabaseMigrationMode.ApplicationManaged,
@@ -148,10 +36,48 @@ BiomeDatabaseModule.forRoot({
 });
 ```
 
+Mount it beside `XemaServiceModule.forBiome(...)`, which publishes the connection count the pool is sized from.
+
+## Configuration
+
+| Option | Purpose |
+| --- | --- |
+| `biomeId` | The biome the database belongs to. |
+| `migrationMode` | `BiomeDatabaseMigrationMode.ApplicationManaged`. |
+| `databases` | The databases the service owns. |
+| `requiredExtensions` | Postgres extensions verified as installed in `public` before migrating; never created. |
+
+| Environment | Purpose |
+| --- | --- |
+| `DB_POOL_MAX`, `DB_POOL_MAX_<KEY>` | Feasibility ceiling for the pool. Below the derived size the boot is refused. |
+| `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_SCHEMA`, `DB_SSL_PARAMS`, `DB_POOLER_HOST`, `DB_POOLER_PORT`, `DB_POOLER_SSL_PARAMS` | Local development connection override; refused when `NODE_ENV=production`. |
+| `DATABASE_URL` | Connection string for operator migrations when none is passed. |
+
+Every Postgres session must run in UTC. The package verifies this and refuses to start otherwise; it never sets the zone.
+
+## Testing
+
+`@xemahq/pg-test-harness` (0.5 and later) provisions a scratch database but does not know how to migrate it. `createTestMigrator` from the `/testing` subpath returns the `migrate` callback it needs: the same migration phase a service runs at boot (`runBiomeMigrations`). It applies the service's Prisma migrations from `<rootDir>/prisma`, then the operator-migration ledger and the SDK-owned migrations you list, and verifies every owned table's shape. Running it again on the same schema changes nothing.
+
+```ts
+// tests/global-setup.ts
+import { createTestMigrator } from '@xemahq/biome-database-nest/testing';
+import { provisionTestDatabase } from '@xemahq/pg-test-harness';
+
+export default async function globalSetup(): Promise<void> {
+  await provisionTestDatabase({
+    serviceName: 'example',
+    rootDir: process.cwd(),
+    migrate: createTestMigrator({ sdkOwnedMigrations: [/* each SDK's migration set */] }),
+  });
+}
+```
+
+`createTestMigrator(options?)` takes `sdkOwnedMigrations?: readonly SdkOwnedMigrationSet[]` and returns `(target: { serviceName, rootDir, url, schema }) => Promise<void>`. It reads no environment variables.
+
 ## Peer requirements
 
-- NestJS 10 or 11 and Prisma 7.
-- Compatible Xema identity, kernel-contract, service-registry, and decorator packages.
+NestJS 10 or 11, Prisma 7 (`@prisma/client`, `@prisma/adapter-pg`), `@xemahq/identity-client`, `@xemahq/contracts`, `@xemahq/service-registry-nest`, `@xemahq/platform-common`.
 
 ## License
 

package/dist/testing/index.d.ts

@@ -0,0 +1,12 @@
+import type { SdkOwnedMigrationSet } from '../lib/sdk-owned-migration-set';
+export interface TestMigrationTarget {
+    readonly serviceName: string;
+    readonly rootDir: string;
+    readonly url: string;
+    readonly schema: string;
+}
+export interface CreateTestMigratorOptions {
+    readonly sdkOwnedMigrations?: readonly SdkOwnedMigrationSet[];
+}
+export declare function createTestMigrator(options?: CreateTestMigratorOptions): (target: TestMigrationTarget) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAM3E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IAExC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC/D;AAWD,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,CAAC,MAAM,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CA6BhD"}

package/dist/testing/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTestMigrator = createTestMigrator;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const biome_migrations_1 = require("../lib/biome-migrations");
+const operator_migration_1 = require("../lib/operator-migration");
+const SQL_IDENTIFIER = /^[a-z_][a-z0-9_]*$/iu;
+function createTestMigrator(options = {}) {
+    return async (target) => {
+        const schemaPath = (0, node_path_1.join)(target.rootDir, 'prisma', 'schema.prisma');
+        if (!(0, node_fs_1.existsSync)(schemaPath)) {
+            throw new Error(`${target.serviceName}: no Prisma schema at ${schemaPath}. Pass the service root as \`rootDir\` to provisionTestDatabase.`);
+        }
+        if (!SQL_IDENTIFIER.test(target.schema)) {
+            throw new Error(`${target.serviceName}: refusing scratch schema ${JSON.stringify(target.schema)}; it must match ${SQL_IDENTIFIER.source} before it is interpolated into CREATE SCHEMA.`);
+        }
+        const database = await (0, operator_migration_1.openOperatorMigrationClient)({
+            connectionString: target.url,
+        });
+        try {
+            await database.query(`CREATE SCHEMA IF NOT EXISTS "${target.schema}"`);
+            await (0, biome_migrations_1.runBiomeMigrations)({
+                database,
+                workspaceDir: target.rootDir,
+                connectionUrl: target.url,
+                label: target.serviceName,
+                sdkOwnedMigrations: options.sdkOwnedMigrations ?? [],
+            });
+        }
+        finally {
+            await database.end();
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";;AAmCA,gDA+BC;AAlED,qCAAqC;AACrC,yCAAiC;AAEjC,8DAA6D;AAC7D,kEAAwE;AAsBxE,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAS9C,SAAgB,kBAAkB,CAChC,UAAqC,EAAE;IAEvC,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE;QACtB,MAAM,UAAU,GAAG,IAAA,gBAAI,EAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC;QACnE,IAAI,CAAC,IAAA,oBAAU,EAAC,UAAU,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,CAAC,WAAW,yBAAyB,UAAU,kEAAkE,CAC3H,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,CAAC,WAAW,6BAA6B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,mBAAmB,cAAc,CAAC,MAAM,gDAAgD,CACxK,CAAC;QACJ,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAA,gDAA2B,EAAC;YACjD,gBAAgB,EAAE,MAAM,CAAC,GAAG;SAC7B,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,KAAK,CAAC,gCAAgC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;YACvE,MAAM,IAAA,qCAAkB,EAAC;gBACvB,QAAQ;gBACR,YAAY,EAAE,MAAM,CAAC,OAAO;gBAC5B,aAAa,EAAE,MAAM,CAAC,GAAG;gBACzB,KAAK,EAAE,MAAM,CAAC,WAAW;gBACzB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,IAAI,EAAE;aACrD,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC;QACvB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/biome-database-nest",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Explicit database migration ownership, least-privilege runtime verification, and schema-qualified Prisma wiring for Xema biome services.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -30,7 +30,7 @@
     "@types/node": "25.2.3",
     "@types/pg": "^8.16.0",
     "@xemahq/identity-client": "^0.15.5",
-    "@xemahq/contracts": "^0.78.0",
+    "@xemahq/contracts": "^0.79.0",
     "@xemahq/pg-test-harness": "^0.3.1",
     "@xemahq/platform-common": ">=0.77.0",
     "eslint": "^9.39.4",
@@ -40,8 +40,8 @@
     "ts-jest": "^29.4.9",
     "typescript": "5.9.3",
     "@xemahq/eslint-config": "0.14.0",
-    "@xemahq/service-registry-nest": "1.0.0",
-    "@xemahq/xema-decorators": "1.0.0"
+    "@xemahq/xema-decorators": "1.0.1",
+    "@xemahq/service-registry-nest": "1.1.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^10 || ^11",
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@xemahq/migration-runner-prisma": "^0.3.1",
-    "@xemahq/org-erasure-nest": "^2.0.0",
+    "@xemahq/org-erasure-nest": "^2.0.1",
     "pg": "^8.16.3"
   },
   "exports": {
@@ -64,6 +64,11 @@
       "xema-source": "./src/index.ts",
       "default": "./dist/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "xema-source": "./src/testing/index.ts",
+      "default": "./dist/testing/index.js"
+    },
     "./dist/lib/*": {
       "types": "./dist/lib/*.d.ts",
       "default": "./dist/lib/*.js"
@@ -78,6 +83,6 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:b40aff384ba4436e8abd374a3ed50e2a666892722608e2b27633890b91da374e"
+    "sourceDigest": "sha256:6a5dd5acb427f3601ffafd9f7f634024b4504d3968dd6508b0b4794998130f71"
   }
 }