pipework 0.19.1 → 0.21.0

package/dist/test/namespace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../src/test/namespace.ts"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAUrG;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,IAAI,MAAM,CAUzC;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}
+{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../src/test/namespace.ts"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAUrG;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,IAAI,MAAM,CAUzC;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C"}

package/dist/test/namespace.js

@@ -54,6 +54,18 @@ export function testDbPrefix() {
 export function appRolePrefix() {
     return `${projectNamespace()}_app_`;
 }
+/**
+ * Prefix for this project's shared, content-keyed templates: `<project>_tmpl_`.
+ *
+ * Templates sit in their own prefix rather than under `testDbPrefix()` because
+ * they have a different lifecycle and a different reaping rule: a per-run clone
+ * dies with its run, a template deliberately outlives every run that uses it
+ * and is dropped only once no run wants it. Separate prefixes keep the reaper's
+ * two passes from having to tell the names apart by shape. Issue #340.
+ */
+export function templateDbPrefix() {
+    return `${projectNamespace()}_tmpl_`;
+}
 /**
  * `LIKE` pattern matching every per-run test database of THIS project, with the
  * prefix underscores escaped so they match literally. The reaper uses it to
@@ -62,4 +74,8 @@ export function appRolePrefix() {
 export function testDbLikePattern() {
     return `${testDbPrefix().replace(/_/g, '\\_')}%`;
 }
+/** `LIKE` pattern matching every shared template of THIS project. */
+export function templateDbLikePattern() {
+    return `${templateDbPrefix().replace(/_/g, '\\_')}%`;
+}
 //# sourceMappingURL=namespace.js.map

package/dist/test/namespace.js.map

@@ -1 +1 @@
-{"version":3,"file":"namespace.js","sourceRoot":"","sources":["../../src/test/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,gEAAgE;AAChE,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,EAAE;AACF,oBAAoB;AACpB,4EAA4E;AAC5E,oEAAoE;AACpE,gFAAgF;AAChF,wDAAwD;AAExD,IAAI,MAAM,GAAkB,IAAI,CAAA;AAEhC;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAA+B,EAAE,OAA2B;IAC3F,MAAM,GAAG,GAAG,WAAW,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,WAAW;QAC9E,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO;YAC1D,CAAC,CAAC,UAAU,CAAA;IACd,0EAA0E;IAC1E,qEAAqE;IACrE,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;IACnF,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAA;AACpD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,gBAAgB;IAC9B,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,MAAM,CAAA;IAClC,IAAI,OAA2B,CAAA;IAC/B,IAAI,CAAC;QACH,OAAO,GAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAuB,CAAC,IAAI,CAAA;IAC9G,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;IACD,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC,CAAA;IAC1E,OAAO,MAAM,CAAA;AACf,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,YAAY;IAC1B,OAAO,GAAG,gBAAgB,EAAE,QAAQ,CAAA;AACtC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa;IAC3B,OAAO,GAAG,gBAAgB,EAAE,OAAO,CAAA;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAA;AAClD,CAAC"}
+{"version":3,"file":"namespace.js","sourceRoot":"","sources":["../../src/test/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,gEAAgE;AAChE,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,EAAE;AACF,oBAAoB;AACpB,4EAA4E;AAC5E,oEAAoE;AACpE,gFAAgF;AAChF,wDAAwD;AAExD,IAAI,MAAM,GAAkB,IAAI,CAAA;AAEhC;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAA+B,EAAE,OAA2B;IAC3F,MAAM,GAAG,GAAG,WAAW,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,WAAW;QAC9E,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO;YAC1D,CAAC,CAAC,UAAU,CAAA;IACd,0EAA0E;IAC1E,qEAAqE;IACrE,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;IACnF,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAA;AACpD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,gBAAgB;IAC9B,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,MAAM,CAAA;IAClC,IAAI,OAA2B,CAAA;IAC/B,IAAI,CAAC;QACH,OAAO,GAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAuB,CAAC,IAAI,CAAA;IAC9G,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;IACD,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC,CAAA;IAC1E,OAAO,MAAM,CAAA;AACf,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,YAAY;IAC1B,OAAO,GAAG,gBAAgB,EAAE,QAAQ,CAAA;AACtC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa;IAC3B,OAAO,GAAG,gBAAgB,EAAE,OAAO,CAAA;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,GAAG,gBAAgB,EAAE,QAAQ,CAAA;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAA;AAClD,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,qBAAqB;IACnC,OAAO,GAAG,gBAAgB,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAA;AACtD,CAAC"}

package/dist/test/reap.d.ts

@@ -10,6 +10,8 @@ export interface ReapResult {
  * SIGKILL, reboot). The reaper reads "lock is free" as "owning run is dead".
  */
 export declare function runLockKey(nonce: string): bigint;
+export declare function templateUseKey(fingerprint: string): bigint;
+export declare function templateBuildKey(fingerprint: string): bigint;
 /** Admin (`/postgres`) connection URL for a database URL. */
 export declare function getAdminUrl(databaseUrl: string): string;
 /**
@@ -24,7 +26,7 @@ export declare function getAdminUrl(databaseUrl: string): string;
  * Both conditions only ever make the reaper more conservative, so it can
  * never drop a database belonging to a live or still-provisioning run.
  */
-export declare function reapOrphanTestDatabases(admin: postgres.Sql): Promise<ReapResult>;
+export declare function reapOrphanTestDatabases(admin: postgres.Sql, liveTemplates?: ReadonlySet<string>): Promise<ReapResult>;
 /**
  * Reap orphan test databases across every Postgres server referenced by the
  * manifold's database config. Used by `pipework test --reap`.

package/dist/test/reap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reap.d.ts","sourceRoot":"","sources":["../../src/test/reap.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAUnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAIvD;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CA0BtF;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBzF"}
+{"version":3,"file":"reap.d.ts","sourceRoot":"","sources":["../../src/test/reap.ts"],"names":[],"mappings":"AACA,OAAO,QAAQ,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAgBnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AA0BD,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAIvD;AAcD;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,QAAQ,CAAC,GAAG,EACnB,aAAa,GAAE,WAAW,CAAC,MAAM,CAAa,GAC7C,OAAO,CAAC,UAAU,CAAC,CA2BrB;AA4DD;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBzF"}

package/dist/test/reap.js

@@ -1,6 +1,7 @@
+import { createHash } from 'node:crypto';
 import postgres from 'postgres';
 import { quoteIdentifier } from '../data/db/identifiers.js';
-import { testDbPrefix, appRolePrefix, testDbLikePattern } from './namespace.js';
+import { testDbPrefix, appRolePrefix, testDbLikePattern, templateDbPrefix, templateDbLikePattern, } from './namespace.js';
 // Per-run test database and role names end with `_<pid>_<nonce>`, where the
 // nonce is 12 random hex chars. The reaper recovers the nonce from a database
 // name to rebuild that run's advisory-lock key.
@@ -14,6 +15,35 @@ const NONCE_SUFFIX = /_([0-9a-f]{12})$/;
 export function runLockKey(nonce) {
     return BigInt('0x' + nonce);
 }
+/**
+ * Advisory-lock keys for a shared template, derived from its content
+ * fingerprint. Both are salted hashes truncated to 60 bits, which keeps them
+ * inside a signed `bigint` and makes an accidental collision with a 48-bit run
+ * lock key or with each other a non-event.
+ *
+ * Two keys, because the two things being coordinated are different:
+ *
+ *  - the USE key is taken in SHARE mode by every process that intends to clone
+ *    the template, for that process's whole life, and in EXCLUSIVE mode by the
+ *    reaper. That is what stops a reaper from dropping a template between
+ *    another process's readiness check and its `CREATE DATABASE ... WITH
+ *    TEMPLATE`: the reaper simply cannot get the lock while anyone holds it.
+ *  - the BUILD key is taken in EXCLUSIVE mode only while building, so that N
+ *    processes starting at once produce one template and one migration replay
+ *    rather than N. It is separate because advisory locks do not upgrade from
+ *    share to exclusive, and a builder must keep its own pin while it builds.
+ *
+ * Issue #340.
+ */
+function templateLockKey(salt, fingerprint) {
+    return BigInt('0x' + createHash('sha256').update(`${salt}:${fingerprint}`).digest('hex').slice(0, 15));
+}
+export function templateUseKey(fingerprint) {
+    return templateLockKey('pipework-template-use', fingerprint);
+}
+export function templateBuildKey(fingerprint) {
+    return templateLockKey('pipework-template-build', fingerprint);
+}
 /** Admin (`/postgres`) connection URL for a database URL. */
 export function getAdminUrl(databaseUrl) {
     const url = new URL(databaseUrl);
@@ -23,6 +53,12 @@ export function getAdminUrl(databaseUrl) {
 function pairedRoleName(datname) {
     return appRolePrefix() + datname.slice(testDbPrefix().length);
 }
+/** A shared template's app role is content-keyed the same way the template is. */
+function pairedTemplateRoleName(datname) {
+    return appRolePrefix() + datname.slice(templateDbPrefix().length);
+}
+/** Content fingerprint trailing a shared template's name: 16 lowercase hex. */
+const TEMPLATE_FINGERPRINT_SUFFIX = /_([0-9a-f]{16})$/;
 /**
  * Drop test databases left behind by runs that never reached teardown
  * (Ctrl-C, timeout, crash). A database is reaped only when BOTH hold:
@@ -35,7 +71,7 @@ function pairedRoleName(datname) {
  * Both conditions only ever make the reaper more conservative, so it can
  * never drop a database belonging to a live or still-provisioning run.
  */
-export async function reapOrphanTestDatabases(admin) {
+export async function reapOrphanTestDatabases(admin, liveTemplates = new Set()) {
     const rows = await admin `
     SELECT datname, numbackends
     FROM pg_stat_database
@@ -61,6 +97,63 @@ export async function reapOrphanTestDatabases(admin) {
             }
         }
     }
+    droppedDatabases.push(...(await reapStaleTemplates(admin, liveTemplates)).droppedDatabases);
+    return { droppedDatabases };
+}
+/**
+ * Drop shared templates nobody wants any more.
+ *
+ * A template is deliberately long-lived — it survives the run that built it, so
+ * the next run clones instead of replaying migrations (#340) — which means
+ * "left behind by a dead run" is no longer a reason to drop one. The two
+ * reasons that remain:
+ *
+ *   - it is not in `liveTemplates`, the set of content keys the calling run
+ *     actually intends to use. Editing a migration changes the key, so the
+ *     template built from the old migrations is named something nobody will ask
+ *     for again. That is what makes invalidation automatic rather than manual.
+ *   - nobody holds its use lock, in any mode. Every process that intends to
+ *     clone a template holds that lock in SHARE mode for its whole life, so
+ *     failing to take it EXCLUSIVE means no live process is cloning from it —
+ *     including no process sitting between a readiness check and its `CREATE
+ *     DATABASE ... WITH TEMPLATE`.
+ *
+ * `numbackends = 0` is required as well, for the same conservatism as clones.
+ *
+ * An empty `liveTemplates` — what `pipework test --reap` passes — therefore
+ * means "drop every template not currently in use", which is the right reading
+ * of an explicit cleanup command.
+ */
+async function reapStaleTemplates(admin, liveTemplates) {
+    const rows = await admin `
+    SELECT datname, numbackends
+    FROM pg_stat_database
+    WHERE datname LIKE ${templateDbLikePattern()}
+  `;
+    const droppedDatabases = [];
+    for (const { datname, numbackends } of rows) {
+        if (numbackends > 0)
+            continue;
+        if (liveTemplates.has(datname))
+            continue;
+        const fingerprint = TEMPLATE_FINGERPRINT_SUFFIX.exec(datname)?.[1];
+        // A name in the template namespace without a fingerprint was not written by
+        // this scheme. Leave it alone rather than guess at its owner.
+        if (fingerprint === undefined)
+            continue;
+        const key = templateUseKey(fingerprint);
+        if (!(await tryAcquire(admin, key)))
+            continue;
+        try {
+            if (await dropDatabase(admin, datname)) {
+                droppedDatabases.push(datname);
+                await dropRole(admin, pairedTemplateRoleName(datname));
+            }
+        }
+        finally {
+            await admin `SELECT pg_advisory_unlock(${key.toString()}::bigint)`;
+        }
+    }
     return { droppedDatabases };
 }
 /**

package/dist/test/reap.js.map

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

package/dist/test/setup.d.ts

@@ -17,4 +17,12 @@ export declare function withTemplateRetry<T>(attempt: () => Promise<T>, sleep?:
 export declare function teardownTestDatabases(): Promise<void>;
 export declare function getTestDatabase(name: string): TestDatabase | undefined;
 export declare function getTestDatabases(): ReadonlyMap<string, TestDatabase>;
+/**
+ * Forget the in-process template cache, so the next `setupTestDatabases` takes
+ * the same path a freshly-forked worker takes: shared lock, readiness check,
+ * clone. This is how a single process can prove the cross-process claim — that
+ * a second fork reuses the template rather than rebuilding it — without
+ * actually forking. Test-only. Issue #340.
+ */
+export declare function forgetTemplateCacheForTests(): void;
 //# sourceMappingURL=setup.d.ts.map

package/dist/test/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/test/setup.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAUnD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;CACjB;AAyCD,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAiC/F;AAuLD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,KAAK,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAyD,EAC5F,QAAQ,GAAE,SAAS,MAAM,EAA6B,GACrD,OAAO,CAAC,CAAC,CAAC,CASZ;AA4ED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAuB3D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE;AAED,wBAAgB,gBAAgB,IAAI,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAEpE"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/test/setup.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAWnD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;CACjB;AAoED,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAqD/F;AAiSD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,KAAK,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAyD,EAC5F,QAAQ,GAAE,SAAS,MAAM,EAA6B,GACrD,OAAO,CAAC,CAAC,CAAC,CASZ;AA4ED,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAuB3D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE;AAED,wBAAgB,gBAAgB,IAAI,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/test/setup.js

@@ -7,8 +7,13 @@ import { applyMigrations } from '../data/migrate/apply.js';
 import { missingQueueTables, queueTableMessage } from '../core/validation/queue-tables.js';
 import { probeRlsRole, rlsProbeTarget, rlsRoleMessage } from '../core/validation/rls-role.js';
 import { provisionFrameworkTables } from '../data/migrate/provision-framework.js';
-import { getAdminUrl, reapOrphanTestDatabases, runLockKey } from './reap.js';
-import { testDbPrefix, appRolePrefix } from './namespace.js';
+import { getAdminUrl, reapOrphanTestDatabases, runLockKey, templateBuildKey, templateUseKey } from './reap.js';
+import { testDbPrefix, appRolePrefix, templateDbPrefix } from './namespace.js';
+import { templateFingerprint, templateInputs } from './fingerprint.js';
+// Marker table written inside a template as the last act of a successful build.
+// A template database that exists without this row is the wreckage of a builder
+// that died mid-migration: it must be rebuilt, never cloned.
+const TEMPLATE_MARKER_TABLE = 'pipework_test_template';
 const testDatabases = new Map();
 const templates = new Map();
 let adminClient = null;
@@ -19,18 +24,20 @@ const runNonce = randomBytes(6).toString('hex');
 let lockClient = null;
 let reaped = false;
 let workerShutdownArmed = false;
-function templateDbName(baseName) {
-    return `${testDbPrefix()}${baseName}_tmpl_${process.pid}_${runNonce}`;
+function templateDbName(baseName, fingerprint) {
+    return `${templateDbPrefix()}${baseName}_${fingerprint}`;
 }
 function testDbName(baseName) {
     return `${testDbPrefix()}${baseName}_${process.pid}_${runNonce}`;
 }
 // The app role is named to match what the orphan reaper derives from the
-// *template* database name (`reap.ts` `pairedRoleName`): the template outlives
-// every per-file clone, so when the reaper drops a leaked template it drops
-// this role with it. Without the `_tmpl_` segment the role would leak forever.
-function appRoleName(baseName) {
-    return `${appRolePrefix()}${baseName}_tmpl_${process.pid}_${runNonce}`;
+// *template* database name (`reap.ts` `pairedTemplateRoleName`): the template
+// outlives every per-file clone and every run, so when the reaper finally drops
+// a stale template it drops this role with it. The role must be content-keyed
+// too — its grants are baked into the template's catalog by OID, so a template
+// shared across processes needs a role shared across processes.
+function appRoleName(baseName, fingerprint) {
+    return `${appRolePrefix()}${baseName}_${fingerprint}`;
 }
 export async function setupTestDatabases(instance) {
     const databases = [...instance.config.databases()];
@@ -50,25 +57,42 @@ export async function setupTestDatabases(instance) {
             throw new Error(`[pipework] Test bootstrap failed:\n\n  ${rlsRoleMessage(name, probe)}\n`);
         }
     }
+    // Template identities are pure functions of config and migration content, so
+    // they are computed before any connection opens — the reaper needs the set of
+    // templates this run intends to use before it decides which templates are
+    // stale enough to drop.
+    const today = new Date();
+    const defaultName = instance.config.databaseNames()[0];
+    const plans = databases.map(([name, dbConfig]) => {
+        const fingerprint = templateFingerprint(templateInputs(name, dbConfig, instance.config.raw, name === defaultName, today));
+        return {
+            name,
+            dbConfig,
+            fingerprint,
+            templateDb: templateDbName(name, fingerprint),
+            appRole: appRoleName(name, fingerprint),
+            isDefaultDatabase: name === defaultName,
+        };
+    });
     const firstDb = databases[0];
     if (firstDb !== undefined) {
-        await prepareRun(getAdminUrl(firstDb[1].url));
+        await prepareRun(getAdminUrl(firstDb[1].url), new Set(plans.map(plan => plan.templateDb)));
     }
-    for (const [name, dbConfig] of databases) {
-        const template = await ensureTemplate(instance, name, dbConfig);
-        const testDb = await cloneTestDatabase(name, dbConfig, template);
-        testDatabases.set(name, testDb);
+    for (const plan of plans) {
+        const template = await ensureTemplate(instance, plan);
+        const testDb = await cloneTestDatabase(plan.name, plan.dbConfig, template);
+        testDatabases.set(plan.name, testDb);
     }
     return testDatabases;
 }
 // Acquire this run's advisory lock and reap orphans before provisioning. The
 // lock is taken before the first CREATE DATABASE so a concurrent run's reaper
 // can never mistake this run's freshly-created, backend-less databases — the
-// per-process template included — for orphans. It is held on a dedicated
+// per-run clones included — for orphans. It is held on a dedicated
 // connection (idle/lifetime timeouts off) so Postgres releases it only when
 // this process dies, and is never unlocked per file: the template outlives
 // every file's database, so the lock that protects it must outlive them too.
-async function prepareRun(adminUrl) {
+async function prepareRun(adminUrl, liveTemplates) {
     if (adminClient === null) {
         adminClient = postgres(adminUrl, { max: 1, onnotice: () => { } });
     }
@@ -80,23 +104,127 @@ async function prepareRun(adminUrl) {
     if (!reaped) {
         reaped = true;
         try {
-            await reapOrphanTestDatabases(adminClient);
+            await reapOrphanTestDatabases(adminClient, liveTemplates);
         }
         catch {
             // Reaping is best effort — never let stale-orphan cleanup break setup.
         }
     }
 }
-// Build the per-process template for one database, once. Subsequent test files
-// hit the cache and skip straight to cloning. Issue #321.
-async function ensureTemplate(instance, name, dbConfig) {
-    const cached = templates.get(name);
+/**
+ * Get the shared template for one database, building it only if no process has
+ * built it yet.
+ *
+ * The protocol, in order, and the order is the point:
+ *
+ *  1. Take a SHARED advisory lock on the template's content key, on this run's
+ *     lifetime connection. That pins the template: the reaper drops a template
+ *     only under an EXCLUSIVE lock, so from here until this process dies, no
+ *     reaper can pull the template out from under a clone.
+ *  2. Ask whether the template is ready. Because the pin is already held, a
+ *     `yes` cannot go stale.
+ *  3. If not ready, take an EXCLUSIVE lock on the separate BUILD key and ask
+ *     again — a concurrent builder may have finished while we waited — then
+ *     build. Two processes starting together therefore converge on one
+ *     template, and the loser pays a wait rather than a second migration replay.
+ *
+ * There is deliberately no fallback: if the shared template cannot be built or
+ * validated, setup fails loudly. Quietly reverting to a private per-process
+ * build would re-hide exactly the cost this exists to remove. Issue #340.
+ */
+async function ensureTemplate(instance, plan) {
+    const cached = templates.get(plan.name);
     if (cached !== undefined)
         return cached;
-    const templateDb = templateDbName(name);
+    const useKey = templateUseKey(plan.fingerprint).toString();
+    const buildKey = templateBuildKey(plan.fingerprint).toString();
+    await lockClient `SELECT pg_advisory_lock_shared(${useKey}::bigint)`;
+    if (!await templateIsReady(plan)) {
+        await lockClient `SELECT pg_advisory_lock(${buildKey}::bigint)`;
+        try {
+            if (!await templateIsReady(plan)) {
+                await buildTemplate(instance, plan);
+            }
+        }
+        finally {
+            await lockClient `SELECT pg_advisory_unlock(${buildKey}::bigint)`;
+        }
+    }
+    // Checked on every process, not just the one that happened to build. A
+    // template is keyed by the migrations that made it; the QUEUES a manifold
+    // registers are not part of that key, so two instances can legitimately share
+    // one template while disagreeing about which queue tables must exist. Running
+    // this only inside the build would make the check depend on who got there
+    // first — which is to say, it would silently stop running.
+    await assertQueueTables(instance, plan);
+    const template = {
+        templateDb: plan.templateDb,
+        appRole: plan.appRole,
+        fingerprint: plan.fingerprint,
+    };
+    templates.set(plan.name, template);
+    return template;
+}
+// D2 loudness at test bootstrap: a registered queue whose table did not come
+// out of the migrations would otherwise fail at first insert, deep in a test.
+// Checked on the database queue migrations are emitted into — the sole
+// database, or the declared defaultDatabase (same rule as startup validation).
+async function assertQueueTables(instance, plan) {
+    const declaredNames = instance.config.databaseNames();
+    const queueDbName = declaredNames.length === 1 ? declaredNames[0] : instance.config.raw.defaultDatabase;
+    if (plan.name !== queueDbName)
+        return;
+    const missing = await missingQueueTables(siblingUrl(plan.dbConfig, plan.templateDb));
+    if (missing.length > 0) {
+        throw new Error(`[pipework] Test bootstrap failed:\n\n` +
+            missing.map(table => `  ${queueTableMessage(table, plan.name)}`).join('\n') + '\n');
+    }
+}
+/** Connection URL for a database on the same server as `dbConfig.url`. */
+function siblingUrl(dbConfig, database) {
+    const url = new URL(dbConfig.url);
+    url.pathname = `/${database}`;
+    return url.toString();
+}
+/**
+ * Is this template complete and usable?
+ *
+ * A missing database, an unreachable one, or one without the marker row all
+ * answer `false` — the caller then rebuilds it under the exclusive build lock.
+ * That is recovery from a half-built template, not a fallback to per-process
+ * building: the result is still the one shared template every process uses.
+ */
+async function templateIsReady(plan) {
+    const client = postgres(siblingUrl(plan.dbConfig, plan.templateDb), {
+        max: 1,
+        onnotice: () => { },
+        connect_timeout: 10,
+    });
+    try {
+        const rows = await client `
+      SELECT fingerprint FROM ${client(TEMPLATE_MARKER_TABLE)} LIMIT 1
+    `;
+        return rows[0]?.fingerprint === plan.fingerprint;
+    }
+    catch {
+        // Database absent, still being built, or missing its marker table.
+        return false;
+    }
+    finally {
+        await client.end();
+    }
+}
+// Build one shared template from scratch. Runs under the exclusive build lock,
+// with this process's shared use-lock already held. Issue #321, #340.
+async function buildTemplate(instance, plan) {
+    const { dbConfig } = plan;
+    const templateDb = plan.templateDb;
     const templateIdent = quoteIdentifier(templateDb, 'database');
     const admin = drizzle(adminClient);
-    await admin.execute(sql.raw(`DROP DATABASE IF EXISTS ${templateIdent}`));
+    // A template database that exists at this point failed its readiness check —
+    // the leftovers of a builder that died. Drop and start over.
+    await closeTemplateClients(admin, templateDb);
+    await withTemplateRetry(() => admin.execute(sql.raw(`DROP DATABASE IF EXISTS ${templateIdent}`)));
     await admin.execute(sql.raw(`CREATE DATABASE ${templateIdent}`));
     // #325: a test database is dropped or rolled back — durable commits are pure
     // overhead. `synchronous_commit` is a per-database setting and does not copy
@@ -121,21 +249,6 @@ async function ensureTemplate(instance, name, dbConfig) {
             unloggedTables: true,
         });
     }
-    // D2 loudness at test bootstrap: a registered queue whose table did not come
-    // out of the migrations above would otherwise fail at first insert, deep in
-    // a test. Checked on the database queue migrations are emitted into — the
-    // sole database, or the declared defaultDatabase (same rule as startup
-    // validation).
-    const declaredNames = instance.config.databaseNames();
-    const queueDbName = declaredNames.length === 1 ? declaredNames[0] : instance.config.raw.defaultDatabase;
-    if (name === queueDbName) {
-        const missing = await missingQueueTables(templateUrlStr);
-        if (missing.length > 0) {
-            await templateClient.end();
-            throw new Error(`[pipework] Test bootstrap failed:\n\n` +
-                missing.map(table => `  ${queueTableMessage(table, name)}`).join('\n') + '\n');
-        }
-    }
     // Framework-owned partitioned tables (trace family) are kept out of app
     // migrations (#313) — pipework creates them and their day partitions here so
     // a traced test never hits a missing relation or a missing partition.
@@ -144,15 +257,21 @@ async function ensureTemplate(instance, name, dbConfig) {
         errorRetentionDays: instance.config.trace.errorRetentionDays,
         auditRetentionDays: instance.config.audit.retentionDays,
         partitionLeadDays: instance.config.trace.partitionLeadDays,
-    }, name === instance.config.databaseNames()[0]);
+    }, plan.isDefaultDatabase);
+    // The marker is written last, and its presence is what makes this template
+    // clonable by any other process. Everything above must have succeeded first;
+    // a builder that dies before this point leaves a database that every reader
+    // correctly refuses to clone.
+    await templateDbHandle.execute(sql.raw(`CREATE TABLE ${quoteIdentifier(TEMPLATE_MARKER_TABLE, 'table')} (` +
+        `fingerprint text PRIMARY KEY, built_at timestamptz NOT NULL DEFAULT now(), builder_pid integer NOT NULL)`));
+    await templateDbHandle.execute(sql `
+    INSERT INTO ${sql.identifier(TEMPLATE_MARKER_TABLE)} (fingerprint, builder_pid)
+    VALUES (${plan.fingerprint}, ${process.pid})
+  `);
     await templateClient.end();
-    const appRole = appRoleName(name);
-    await provisionTemplateRole(adminClient, templateUrlStr, appRole);
-    const template = { templateDb, appRole };
-    templates.set(name, template);
-    return template;
+    await provisionTemplateRole(adminClient, templateUrlStr, plan.appRole);
 }
-// Clone one test file's database from the per-process template. A clone copies
+// Clone one test file's database from the shared template. A clone copies
 // the template's tables, partitions, and in-database grants; only the cluster
 // catalog's CONNECT privilege has to be re-granted on the new database. Issue #321.
 async function cloneTestDatabase(name, dbConfig, template) {
@@ -182,12 +301,16 @@ async function cloneTestDatabase(name, dbConfig, template) {
         database: dbName,
     };
 }
-// Close our own straggler client connections to the template so the clone can
-// proceed. Two guards keep this from aborting the clone:
+// Close straggler client connections to the template so the clone can proceed.
+// Three guards keep this from aborting the clone — or from sabotaging a peer:
 //   - `backend_type = 'client backend'` excludes background workers. An
 //     autovacuum worker attaches to every database and runs as superuser, and a
 //     non-superuser test role cannot signal it — targeting it would raise
 //     `permission denied to terminate process` (42501) and abort the statement.
+//   - `state = 'idle'` excludes backends doing work. The template is now shared
+//     across processes (#340), so an active backend may be another run's
+//     builder or readiness check rather than a leak of ours; an idle one is
+//     doing nothing and its owner reconnects transparently.
 //   - best-effort: if a client backend is still unkillable (owned by a role we
 //     cannot signal), swallow it. The `CREATE` retry waits out whatever remains.
 async function closeTemplateClients(admin, templateDb) {
@@ -198,6 +321,7 @@ async function closeTemplateClients(admin, templateDb) {
       WHERE datname = ${templateDb}
         AND pid <> pg_backend_pid()
         AND backend_type = 'client backend'
+        AND state = 'idle'
     `);
     }
     catch {
@@ -255,9 +379,9 @@ async function provisionTemplateRole(client, templateUrl, roleName) {
 }
 // Close this run's persistent admin and lock connections. Releasing
 // `lockClient` drops the run's advisory lock — so this runs exactly once, at
-// worker shutdown, never per file: the lock guards the per-process template
-// against a sibling worker's orphan reaper, and the template outlives every
-// file, so the lock must outlive every file too.
+// worker shutdown, never per file: these connections hold the run's advisory
+// lock and this run's shared pin on every template it uses, and both must
+// outlive every file in the worker.
 async function closeRunConnections() {
     if (adminClient !== null) {
         await adminClient.end();
@@ -288,9 +412,9 @@ function armWorkerShutdown() {
         });
     }
 }
-// Drop this file's clones. The per-process template and its app role
-// deliberately outlive teardown — the next file reuses the template, and the
-// next run's reaper eventually drops them. The run's admin and lock
+// Drop this file's clones. The shared template and its app role deliberately
+// outlive teardown — the next file, the next process, and the next run all
+// reuse it, and a reaper drops it only once its content key goes stale (#340). The run's admin and lock
 // connections also survive: `lockClient` holds the advisory lock that protects
 // the live template from a sibling worker's reaper, so it must stay open for
 // the worker's whole life — `armWorkerShutdown` closes both once, at worker
@@ -324,4 +448,14 @@ export function getTestDatabase(name) {
 export function getTestDatabases() {
     return testDatabases;
 }
+/**
+ * Forget the in-process template cache, so the next `setupTestDatabases` takes
+ * the same path a freshly-forked worker takes: shared lock, readiness check,
+ * clone. This is how a single process can prove the cross-process claim — that
+ * a second fork reuses the template rather than rebuilding it — without
+ * actually forking. Test-only. Issue #340.
+ */
+export function forgetTemplateCacheForTests() {
+    templates.clear();
+}
 //# sourceMappingURL=setup.js.map