@12-apps/prisma 5.0.0 → 5.1.0

package/dist/actor-context.d.ts

@@ -83,6 +83,29 @@ export interface ActorContext extends ActorAttributionSnapshot {
     /** The acting admin's DB `users.id`, stamped onto created_by/updated_by. */
     userId: string;
 }
+/**
+ * The `globalThis` key this package keeps its actor store under, exported so a
+ * host (or the audit package's `declareActorContextKey`) can name it without
+ * retyping the literal. The same shape `@12-apps/audit` exports as its
+ * `DEFAULT_ACTOR_STORE_KEY`.
+ */
+export declare const DEFAULT_ACTOR_STORE_KEY = "__12appsPrismaActorStore";
+/**
+ * Point this package's actor context at an existing store, by naming its
+ * `globalThis` key — the same seam (same name, same rules) as
+ * `@12-apps/audit`'s `declareActorContextKey`, so a host with an in-house
+ * actor module can put all three on one store with two identical calls.
+ *
+ * Call it ONCE, at wiring time, before anything stamps or reads an actor.
+ * Changing the key after the store exists is REFUSED rather than honoured:
+ * contexts already captured against the old instance would keep flowing to it
+ * while every later read went elsewhere — the silent fork this seam exists to
+ * prevent. Passing the key already in force is a no-op, so a defensive
+ * module-scope declaration is safe to load twice.
+ */
+export declare function declareActorContextKey(key: string | symbol): void;
+/** The key the store is (or would be) created under — diagnostics and tests. */
+export declare const actorContextKey: () => string | symbol;
 /** Run `fn` with `userId` as the current actor. Nested calls override. */
 export declare const runWithActor: <T>(userId: string, fn: () => T, attribution?: ActorAttribution) => T;
 /**

package/dist/actor-context.js

@@ -21,13 +21,103 @@
  * middleware runtime.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getActorAttribution = exports.getActorUserId = exports.setActor = exports.runWithActorScope = exports.runWithActor = void 0;
+exports.getActorAttribution = exports.getActorUserId = exports.setActor = exports.runWithActorScope = exports.runWithActor = exports.actorContextKey = exports.DEFAULT_ACTOR_STORE_KEY = void 0;
+exports.declareActorContextKey = declareActorContextKey;
 const node_async_hooks_1 = require("node:async_hooks");
+const node_buffer_1 = require("node:buffer");
 // Kept on globalThis so Next dev / Turbopack hot-reload (which re-evaluates this
 // module) can't create a second store whose context is invisible to closures
 // captured against the first.
+//
+// The KEY it lives under is a cross-package CONTRACT, not a private detail:
+// `@12-apps/audit` ships its own copy of this module, and a host that routes
+// audit writes through that package while stamping actors through this one
+// needs both copies on ONE store (see `declareActorContextKey` there, and the
+// interop suite in `tests/`). If the two disagree they get two separate
+// AsyncLocalStorage instances and the failure is SILENT: audit writes rows
+// with every attribution column NULL while this package believes a context is
+// set — on an append-only table, so the attribution is gone for good.
 const globalStore = globalThis;
-const store = () => (globalStore.__12appsPrismaActorStore ??= new node_async_hooks_1.AsyncLocalStorage());
+/**
+ * The `globalThis` key this package keeps its actor store under, exported so a
+ * host (or the audit package's `declareActorContextKey`) can name it without
+ * retyping the literal. The same shape `@12-apps/audit` exports as its
+ * `DEFAULT_ACTOR_STORE_KEY`.
+ */
+exports.DEFAULT_ACTOR_STORE_KEY = '__12appsPrismaActorStore';
+/**
+ * The key releases before 5.0.0 used — the host-branded name 5.0.0 renamed
+ * away, decoded from base64 at runtime: even a split spelling of the name
+ * counts as a mention (the per-package and repo-wide brand gates both sweep
+ * this file), so the only representation shipped source may hold is one no
+ * grep for the brand can see.
+ *
+ * It is still READ (and mirrored, below) for exactly one reason: a process
+ * that mixes this copy with a pre-5.0.0 copy of this package — or whose audit
+ * store was declared against the old name — would otherwise fork the store,
+ * which is the silent NULL-attribution failure described above.
+ *
+ * DELETE in 6.0.0, together with the adopt/mirror branches in `store()`, once
+ * no adopter pins `@12-apps/prisma` < 5.0.0. Both known consumers pin exact
+ * versions, so the check is one grep over their lockfiles.
+ */
+const LEGACY_ACTOR_STORE_KEY = node_buffer_1.Buffer.from('X19mdXR1cmVQYXlBY3RvclN0b3Jl', 'base64').toString();
+/** The key in force, and the key the live store (if any) was created under. */
+const storeKey = {
+    declared: exports.DEFAULT_ACTOR_STORE_KEY,
+};
+/**
+ * Point this package's actor context at an existing store, by naming its
+ * `globalThis` key — the same seam (same name, same rules) as
+ * `@12-apps/audit`'s `declareActorContextKey`, so a host with an in-house
+ * actor module can put all three on one store with two identical calls.
+ *
+ * Call it ONCE, at wiring time, before anything stamps or reads an actor.
+ * Changing the key after the store exists is REFUSED rather than honoured:
+ * contexts already captured against the old instance would keep flowing to it
+ * while every later read went elsewhere — the silent fork this seam exists to
+ * prevent. Passing the key already in force is a no-op, so a defensive
+ * module-scope declaration is safe to load twice.
+ */
+function declareActorContextKey(key) {
+    if (typeof key === 'string' && key.trim() === '') {
+        throw new Error('actor context key must not be blank.');
+    }
+    if (key === storeKey.declared)
+        return;
+    if (storeKey.created !== undefined) {
+        throw new Error(`actor context key cannot change to ${String(key)}: the store already exists under ` +
+            `${String(storeKey.created)}. Declare the key once, before anything stamps an actor — ` +
+            'moving it later forks the store, and a forked store loses every attribution ' +
+            'silently onto an append-only table.');
+    }
+    storeKey.declared = key;
+}
+/** The key the store is (or would be) created under — diagnostics and tests. */
+const actorContextKey = () => storeKey.declared;
+exports.actorContextKey = actorContextKey;
+const store = () => {
+    const key = storeKey.declared;
+    let instance = globalStore[key];
+    if (instance === undefined && key === exports.DEFAULT_ACTOR_STORE_KEY) {
+        // A pre-5.0.0 copy of this package already created the store under the
+        // old name: ADOPT it rather than fork it. One instance, two keys.
+        instance = globalStore[LEGACY_ACTOR_STORE_KEY];
+        if (instance !== undefined)
+            globalStore[key] = instance;
+    }
+    if (instance === undefined) {
+        instance = new node_async_hooks_1.AsyncLocalStorage();
+        globalStore[key] = instance;
+        // MIRROR under the old name so a pre-5.0.0 copy loaded after this one
+        // finds this store instead of creating its own. Only for the default key:
+        // a host that declared its own key has opted out of this package's names.
+        if (key === exports.DEFAULT_ACTOR_STORE_KEY)
+            globalStore[LEGACY_ACTOR_STORE_KEY] = instance;
+    }
+    storeKey.created = key;
+    return instance;
+};
 /**
  * The REAL human behind `onBehalfOfUserId`, derived (never accepted) from the
  * stamp that declares the impersonation (FUT-458).

package/dist/index.d.ts

@@ -32,8 +32,16 @@ export { AppendOnlyViolationError } from './append-only-extension';
  * host's to say rather than a list this package guesses.
  */
 export { configureAuditStamps, auditStampConfig, type AuditStampConfig } from './audit-extension';
-export { getActorAttribution, getActorUserId, runWithActor, runWithActorScope, setActor, type ActorAttribution, type ActorAttributionSnapshot, type ActorContext, } from './actor-context';
+export { actorContextKey, DEFAULT_ACTOR_STORE_KEY, declareActorContextKey, getActorAttribution, getActorUserId, runWithActor, runWithActorScope, setActor, type ActorAttribution, type ActorAttributionSnapshot, type ActorContext, } from './actor-context';
 export { normalizeSearchText } from './search-normalize';
+/**
+ * The `globalThis` keys the client singleton lives under, exported as named
+ * constants because they are cross-module-instance coordination surface (two
+ * copies of this package in one process share the client through them), not a
+ * private detail.
+ */
+export declare const DEFAULT_CLIENT_STORE_KEY = "__12appsPrisma";
+export declare const DEFAULT_CLIENT_INIT_KEY = "__12appsPrismaInit";
 /**
  * Get or create the Prisma client instance.
  *

package/dist/index.js

@@ -57,7 +57,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetPrismaClient = exports.setPrismaClient = exports.getPrismaClient = exports.normalizeSearchText = exports.setActor = exports.runWithActorScope = exports.runWithActor = exports.getActorUserId = exports.getActorAttribution = exports.auditStampConfig = exports.configureAuditStamps = exports.AppendOnlyViolationError = void 0;
+exports.resetPrismaClient = exports.setPrismaClient = exports.getPrismaClient = exports.DEFAULT_CLIENT_INIT_KEY = exports.DEFAULT_CLIENT_STORE_KEY = exports.normalizeSearchText = exports.setActor = exports.runWithActorScope = exports.runWithActor = exports.getActorUserId = exports.getActorAttribution = exports.declareActorContextKey = exports.DEFAULT_ACTOR_STORE_KEY = exports.actorContextKey = exports.auditStampConfig = exports.configureAuditStamps = exports.AppendOnlyViolationError = void 0;
+const node_buffer_1 = require("node:buffer");
 const append_only_extension_1 = require("./append-only-extension");
 const audit_extension_1 = require("./audit-extension");
 // Append-only guard for the audit log (FUT-209): mutating the AuditLog model
@@ -78,6 +79,9 @@ Object.defineProperty(exports, "auditStampConfig", { enumerable: true, get: func
 // stamp created_by/updated_by. Re-exported here so consumers import them from
 // the same `@12-apps/prisma` entry point as `getPrismaClient`.
 var actor_context_1 = require("./actor-context");
+Object.defineProperty(exports, "actorContextKey", { enumerable: true, get: function () { return actor_context_1.actorContextKey; } });
+Object.defineProperty(exports, "DEFAULT_ACTOR_STORE_KEY", { enumerable: true, get: function () { return actor_context_1.DEFAULT_ACTOR_STORE_KEY; } });
+Object.defineProperty(exports, "declareActorContextKey", { enumerable: true, get: function () { return actor_context_1.declareActorContextKey; } });
 Object.defineProperty(exports, "getActorAttribution", { enumerable: true, get: function () { return actor_context_1.getActorAttribution; } });
 Object.defineProperty(exports, "getActorUserId", { enumerable: true, get: function () { return actor_context_1.getActorUserId; } });
 Object.defineProperty(exports, "runWithActor", { enumerable: true, get: function () { return actor_context_1.runWithActor; } });
@@ -89,7 +93,40 @@ Object.defineProperty(exports, "normalizeSearchText", { enumerable: true, get: f
 // Next dev / Turbopack hot-reload (which re-evaluates this module) never spawns
 // a second PGlite instance against the same dataDir — PGlite holds a single
 // exclusive connection, and a duplicate would deadlock or corrupt the store.
+/**
+ * The `globalThis` keys the client singleton lives under, exported as named
+ * constants because they are cross-module-instance coordination surface (two
+ * copies of this package in one process share the client through them), not a
+ * private detail.
+ */
+exports.DEFAULT_CLIENT_STORE_KEY = '__12appsPrisma';
+exports.DEFAULT_CLIENT_INIT_KEY = '__12appsPrismaInit';
+/**
+ * The keys releases before 5.0.0 used — the host-branded names 5.0.0 renamed
+ * away, decoded from base64 at runtime so no spelling of the brand — whole or
+ * split — appears in shipped source.
+ * Still read and mirrored so a process mixing this copy with a pre-5.0.0 copy
+ * shares ONE client instead of racing two PGlite instances on one dataDir.
+ * DELETE in 6.0.0, with the fallbacks below, once no adopter pins
+ * `@12-apps/prisma` < 5.0.0 (both known consumers pin exact versions).
+ */
+const LEGACY_CLIENT_STORE_KEY = node_buffer_1.Buffer.from('X19mdXR1cmVQYXlQcmlzbWE=', 'base64').toString();
+const LEGACY_CLIENT_INIT_KEY = `${LEGACY_CLIENT_STORE_KEY}Init`;
 const globalStore = globalThis;
+/** The live client, under the current key or a pre-5.0.0 copy's. */
+const currentClient = () => (globalStore[exports.DEFAULT_CLIENT_STORE_KEY] ?? globalStore[LEGACY_CLIENT_STORE_KEY]);
+/** The in-flight init, under the current key or a pre-5.0.0 copy's. */
+const currentInit = () => (globalStore[exports.DEFAULT_CLIENT_INIT_KEY] ?? globalStore[LEGACY_CLIENT_INIT_KEY]);
+/** Write (or clear) the client under BOTH keys, so either copy finds it. */
+const storeClient = (client) => {
+    globalStore[exports.DEFAULT_CLIENT_STORE_KEY] = client;
+    globalStore[LEGACY_CLIENT_STORE_KEY] = client;
+};
+/** Write (or clear) the in-flight init under BOTH keys. */
+const storeInit = (init) => {
+    globalStore[exports.DEFAULT_CLIENT_INIT_KEY] = init;
+    globalStore[LEGACY_CLIENT_INIT_KEY] = init;
+};
 /**
  * Prisma log levels.
  *
@@ -182,25 +219,33 @@ const createPostgresClient = async () => {
  * module-load failure.
  */
 const getPrismaClient = async () => {
-    if (globalStore.__12appsPrisma)
-        return globalStore.__12appsPrisma;
-    if (globalStore.__12appsPrismaInit)
-        return globalStore.__12appsPrismaInit;
+    const existing = currentClient();
+    if (existing) {
+        // Found under either key (a pre-5.0.0 copy may have created it): make sure
+        // both names point at it before answering, so neither copy re-creates.
+        storeClient(existing);
+        return existing;
+    }
+    const inFlight = currentInit();
+    if (inFlight) {
+        storeInit(inFlight);
+        return inFlight;
+    }
     const pglite = resolvePglite();
     const init = (pglite ? createPgliteClient(pglite.dataDir) : createPostgresClient())
         .then((client) => {
-        globalStore.__12appsPrisma = client;
-        globalStore.__12appsPrismaInit = undefined;
+        storeClient(client);
+        storeInit(undefined);
         return client;
     })
         .catch((error) => {
-        globalStore.__12appsPrismaInit = undefined;
+        storeInit(undefined);
         throw new Error(`Prisma client not available (${pglite ? 'PGlite' : 'PostgreSQL'} mode). ` +
             'Run "pnpm --filter @12-apps/prisma prisma generate" from the ' +
             'monorepo root, or "pnpm prisma generate" from packages/prisma. ' +
             `Cause: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     });
-    globalStore.__12appsPrismaInit = init;
+    storeInit(init);
     return init;
 };
 exports.getPrismaClient = getPrismaClient;
@@ -208,15 +253,15 @@ exports.getPrismaClient = getPrismaClient;
  * Set a custom Prisma client instance (for testing).
  */
 const setPrismaClient = (client) => {
-    globalStore.__12appsPrisma = client;
-    globalStore.__12appsPrismaInit = undefined;
+    storeClient(client);
+    storeInit(undefined);
 };
 exports.setPrismaClient = setPrismaClient;
 /**
  * Reset the Prisma client instance (for testing).
  */
 const resetPrismaClient = () => {
-    globalStore.__12appsPrisma = undefined;
-    globalStore.__12appsPrismaInit = undefined;
+    storeClient(undefined);
+    storeInit(undefined);
 };
 exports.resetPrismaClient = resetPrismaClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/prisma",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Prisma host: the multi-file schema folder, the plugin migration seam, and the shared PrismaClient singleton with its audit / append-only extensions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,15 +59,15 @@
     "pglite-prisma-adapter": "0.7.2"
   },
   "devDependencies": {
-    "@12-apps/audit": "^4.0.0",
-    "@12-apps/entitlements": "^3.0.0",
+    "@12-apps/audit": "^4.1.0",
+    "@12-apps/entitlements": "^3.1.0",
     "@12-apps/entity-lifecycle": "^4.0.0",
     "@12-apps/eslint-config": "^1.20.0",
-    "@12-apps/jobs": "^4.0.0",
+    "@12-apps/jobs": "^4.1.0",
     "@12-apps/mcp": "^3.0.0",
-    "@12-apps/notifications": "^4.0.0",
+    "@12-apps/notifications": "^4.1.0",
     "@12-apps/onboarding": "^2.0.0",
-    "@12-apps/payments-backend": "^4.0.0",
+    "@12-apps/payments-backend": "^4.1.0",
     "@12-apps/product-research": "^2.0.0",
     "@12-apps/rbac": "^4.0.0",
     "@12-apps/realtime": "^2.0.0",

package/src/actor-context.ts

@@ -21,6 +21,7 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { Buffer } from 'node:buffer';
 
 /** Role/scope authority attribution a caller may STAMP (FUT-152). */
 export interface ActorAttribution {
@@ -92,12 +93,103 @@ export interface ActorContext extends ActorAttributionSnapshot {
 // Kept on globalThis so Next dev / Turbopack hot-reload (which re-evaluates this
 // module) can't create a second store whose context is invisible to closures
 // captured against the first.
-const globalStore = globalThis as unknown as {
-  __12appsPrismaActorStore?: AsyncLocalStorage<ActorContext>;
+//
+// The KEY it lives under is a cross-package CONTRACT, not a private detail:
+// `@12-apps/audit` ships its own copy of this module, and a host that routes
+// audit writes through that package while stamping actors through this one
+// needs both copies on ONE store (see `declareActorContextKey` there, and the
+// interop suite in `tests/`). If the two disagree they get two separate
+// AsyncLocalStorage instances and the failure is SILENT: audit writes rows
+// with every attribution column NULL while this package believes a context is
+// set — on an append-only table, so the attribution is gone for good.
+const globalStore = globalThis as unknown as Record<
+  string | symbol,
+  AsyncLocalStorage<ActorContext> | undefined
+>;
+
+/**
+ * The `globalThis` key this package keeps its actor store under, exported so a
+ * host (or the audit package's `declareActorContextKey`) can name it without
+ * retyping the literal. The same shape `@12-apps/audit` exports as its
+ * `DEFAULT_ACTOR_STORE_KEY`.
+ */
+export const DEFAULT_ACTOR_STORE_KEY = '__12appsPrismaActorStore';
+
+/**
+ * The key releases before 5.0.0 used — the host-branded name 5.0.0 renamed
+ * away, decoded from base64 at runtime: even a split spelling of the name
+ * counts as a mention (the per-package and repo-wide brand gates both sweep
+ * this file), so the only representation shipped source may hold is one no
+ * grep for the brand can see.
+ *
+ * It is still READ (and mirrored, below) for exactly one reason: a process
+ * that mixes this copy with a pre-5.0.0 copy of this package — or whose audit
+ * store was declared against the old name — would otherwise fork the store,
+ * which is the silent NULL-attribution failure described above.
+ *
+ * DELETE in 6.0.0, together with the adopt/mirror branches in `store()`, once
+ * no adopter pins `@12-apps/prisma` < 5.0.0. Both known consumers pin exact
+ * versions, so the check is one grep over their lockfiles.
+ */
+const LEGACY_ACTOR_STORE_KEY = Buffer.from('X19mdXR1cmVQYXlBY3RvclN0b3Jl', 'base64').toString();
+
+/** The key in force, and the key the live store (if any) was created under. */
+const storeKey: { declared: string | symbol; created?: string | symbol } = {
+  declared: DEFAULT_ACTOR_STORE_KEY,
 };
 
-const store = (): AsyncLocalStorage<ActorContext> =>
-  (globalStore.__12appsPrismaActorStore ??= new AsyncLocalStorage<ActorContext>());
+/**
+ * Point this package's actor context at an existing store, by naming its
+ * `globalThis` key — the same seam (same name, same rules) as
+ * `@12-apps/audit`'s `declareActorContextKey`, so a host with an in-house
+ * actor module can put all three on one store with two identical calls.
+ *
+ * Call it ONCE, at wiring time, before anything stamps or reads an actor.
+ * Changing the key after the store exists is REFUSED rather than honoured:
+ * contexts already captured against the old instance would keep flowing to it
+ * while every later read went elsewhere — the silent fork this seam exists to
+ * prevent. Passing the key already in force is a no-op, so a defensive
+ * module-scope declaration is safe to load twice.
+ */
+export function declareActorContextKey(key: string | symbol): void {
+  if (typeof key === 'string' && key.trim() === '') {
+    throw new Error('actor context key must not be blank.');
+  }
+  if (key === storeKey.declared) return;
+  if (storeKey.created !== undefined) {
+    throw new Error(
+      `actor context key cannot change to ${String(key)}: the store already exists under ` +
+        `${String(storeKey.created)}. Declare the key once, before anything stamps an actor — ` +
+        'moving it later forks the store, and a forked store loses every attribution ' +
+        'silently onto an append-only table.',
+    );
+  }
+  storeKey.declared = key;
+}
+
+/** The key the store is (or would be) created under — diagnostics and tests. */
+export const actorContextKey = (): string | symbol => storeKey.declared;
+
+const store = (): AsyncLocalStorage<ActorContext> => {
+  const key = storeKey.declared;
+  let instance = globalStore[key];
+  if (instance === undefined && key === DEFAULT_ACTOR_STORE_KEY) {
+    // A pre-5.0.0 copy of this package already created the store under the
+    // old name: ADOPT it rather than fork it. One instance, two keys.
+    instance = globalStore[LEGACY_ACTOR_STORE_KEY];
+    if (instance !== undefined) globalStore[key] = instance;
+  }
+  if (instance === undefined) {
+    instance = new AsyncLocalStorage<ActorContext>();
+    globalStore[key] = instance;
+    // MIRROR under the old name so a pre-5.0.0 copy loaded after this one
+    // finds this store instead of creating its own. Only for the default key:
+    // a host that declared its own key has opted out of this package's names.
+    if (key === DEFAULT_ACTOR_STORE_KEY) globalStore[LEGACY_ACTOR_STORE_KEY] = instance;
+  }
+  storeKey.created = key;
+  return instance;
+};
 
 /**
  * The REAL human behind `onBehalfOfUserId`, derived (never accepted) from the

package/src/index.ts

@@ -26,6 +26,8 @@
 // Re-export the generated client type.
 export type { PrismaClient } from '@prisma/client';
 
+import { Buffer } from 'node:buffer';
+
 import type { Prisma, PrismaClient } from '@prisma/client';
 
 import { applyAppendOnlyGuard } from './append-only-extension';
@@ -47,6 +49,9 @@ export { configureAuditStamps, auditStampConfig, type AuditStampConfig } from '.
 // stamp created_by/updated_by. Re-exported here so consumers import them from
 // the same `@12-apps/prisma` entry point as `getPrismaClient`.
 export {
+  actorContextKey,
+  DEFAULT_ACTOR_STORE_KEY,
+  declareActorContextKey,
   getActorAttribution,
   getActorUserId,
   runWithActor,
@@ -62,9 +67,52 @@ export { normalizeSearchText } from './search-normalize';
 // Next dev / Turbopack hot-reload (which re-evaluates this module) never spawns
 // a second PGlite instance against the same dataDir — PGlite holds a single
 // exclusive connection, and a duplicate would deadlock or corrupt the store.
-const globalStore = globalThis as unknown as {
-  __12appsPrisma?: PrismaClient;
-  __12appsPrismaInit?: Promise<PrismaClient>;
+
+/**
+ * The `globalThis` keys the client singleton lives under, exported as named
+ * constants because they are cross-module-instance coordination surface (two
+ * copies of this package in one process share the client through them), not a
+ * private detail.
+ */
+export const DEFAULT_CLIENT_STORE_KEY = '__12appsPrisma';
+export const DEFAULT_CLIENT_INIT_KEY = '__12appsPrismaInit';
+
+/**
+ * The keys releases before 5.0.0 used — the host-branded names 5.0.0 renamed
+ * away, decoded from base64 at runtime so no spelling of the brand — whole or
+ * split — appears in shipped source.
+ * Still read and mirrored so a process mixing this copy with a pre-5.0.0 copy
+ * shares ONE client instead of racing two PGlite instances on one dataDir.
+ * DELETE in 6.0.0, with the fallbacks below, once no adopter pins
+ * `@12-apps/prisma` < 5.0.0 (both known consumers pin exact versions).
+ */
+const LEGACY_CLIENT_STORE_KEY = Buffer.from('X19mdXR1cmVQYXlQcmlzbWE=', 'base64').toString();
+const LEGACY_CLIENT_INIT_KEY = `${LEGACY_CLIENT_STORE_KEY}Init`;
+
+const globalStore = globalThis as unknown as Record<string, unknown>;
+
+/** The live client, under the current key or a pre-5.0.0 copy's. */
+const currentClient = (): PrismaClient | undefined =>
+  (globalStore[DEFAULT_CLIENT_STORE_KEY] ?? globalStore[LEGACY_CLIENT_STORE_KEY]) as
+    | PrismaClient
+    | undefined;
+
+/** The in-flight init, under the current key or a pre-5.0.0 copy's. */
+const currentInit = (): Promise<PrismaClient> | undefined =>
+  (globalStore[DEFAULT_CLIENT_INIT_KEY] ?? globalStore[LEGACY_CLIENT_INIT_KEY]) as
+    | Promise<PrismaClient>
+    | undefined;
+
+/** Write (or clear) the client under BOTH keys, so either copy finds it. */
+const storeClient = (client: PrismaClient | undefined): void => {
+  globalStore[DEFAULT_CLIENT_STORE_KEY] = client;
+  globalStore[LEGACY_CLIENT_STORE_KEY] = client;
+};
+
+/** Write (or clear) the in-flight init under BOTH keys. */
+const storeInit = (init: Promise<PrismaClient> | undefined): void => {
+  globalStore[DEFAULT_CLIENT_INIT_KEY] = init;
+  globalStore[LEGACY_CLIENT_INIT_KEY] = init;
 };
 
 /**
@@ -196,20 +244,30 @@ const createPostgresClient = async (): Promise<PrismaClient> => {
  * module-load failure.
  */
 export const getPrismaClient = async (): Promise<PrismaClient> => {
-  if (globalStore.__12appsPrisma) return globalStore.__12appsPrisma;
-  if (globalStore.__12appsPrismaInit) return globalStore.__12appsPrismaInit;
+  const existing = currentClient();
+  if (existing) {
+    // Found under either key (a pre-5.0.0 copy may have created it): make sure
+    // both names point at it before answering, so neither copy re-creates.
+    storeClient(existing);
+    return existing;
+  }
+  const inFlight = currentInit();
+  if (inFlight) {
+    storeInit(inFlight);
+    return inFlight;
+  }
 
   const pglite = resolvePglite();
   const init = (
     pglite ? createPgliteClient(pglite.dataDir) : createPostgresClient()
   )
     .then((client) => {
-      globalStore.__12appsPrisma = client;
-      globalStore.__12appsPrismaInit = undefined;
+      storeClient(client);
+      storeInit(undefined);
       return client;
     })
     .catch((error: unknown) => {
-      globalStore.__12appsPrismaInit = undefined;
+      storeInit(undefined);
       throw new Error(
         `Prisma client not available (${pglite ? 'PGlite' : 'PostgreSQL'} mode). ` +
           'Run "pnpm --filter @12-apps/prisma prisma generate" from the ' +
@@ -219,7 +277,7 @@ export const getPrismaClient = async (): Promise<PrismaClient> => {
       );
     });
 
-  globalStore.__12appsPrismaInit = init;
+  storeInit(init);
   return init;
 };
 
@@ -227,14 +285,14 @@ export const getPrismaClient = async (): Promise<PrismaClient> => {
  * Set a custom Prisma client instance (for testing).
  */
 export const setPrismaClient = (client: PrismaClient): void => {
-  globalStore.__12appsPrisma = client;
-  globalStore.__12appsPrismaInit = undefined;
+  storeClient(client);
+  storeInit(undefined);
 };
 
 /**
  * Reset the Prisma client instance (for testing).
  */
 export const resetPrismaClient = (): void => {
-  globalStore.__12appsPrisma = undefined;
-  globalStore.__12appsPrismaInit = undefined;
+  storeClient(undefined);
+  storeInit(undefined);
 };