@12-apps/prisma 4.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.__futurePayActorStore ??= 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.__futurePayPrisma)
-        return globalStore.__futurePayPrisma;
-    if (globalStore.__futurePayPrismaInit)
-        return globalStore.__futurePayPrismaInit;
+    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.__futurePayPrisma = client;
-        globalStore.__futurePayPrismaInit = undefined;
+        storeClient(client);
+        storeInit(undefined);
         return client;
     })
         .catch((error) => {
-        globalStore.__futurePayPrismaInit = 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.__futurePayPrismaInit = 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.__futurePayPrisma = client;
-    globalStore.__futurePayPrismaInit = undefined;
+    storeClient(client);
+    storeInit(undefined);
 };
 exports.setPrismaClient = setPrismaClient;
 /**
  * Reset the Prisma client instance (for testing).
  */
 const resetPrismaClient = () => {
-    globalStore.__futurePayPrisma = undefined;
-    globalStore.__futurePayPrismaInit = undefined;
+    storeClient(undefined);
+    storeInit(undefined);
 };
 exports.resetPrismaClient = resetPrismaClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/prisma",
-  "version": "4.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,20 +59,20 @@
     "pglite-prisma-adapter": "0.7.2"
   },
   "devDependencies": {
-    "@12-apps/audit": "^3.0.0",
-    "@12-apps/entitlements": "^2.0.0",
-    "@12-apps/entity-lifecycle": "^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": "^3.0.0",
-    "@12-apps/mcp": "^2.0.0",
-    "@12-apps/notifications": "^2.0.0",
-    "@12-apps/onboarding": "^1.20.0",
-    "@12-apps/payments-backend": "^3.0.0",
+    "@12-apps/jobs": "^4.1.0",
+    "@12-apps/mcp": "^3.0.0",
+    "@12-apps/notifications": "^4.1.0",
+    "@12-apps/onboarding": "^2.0.0",
+    "@12-apps/payments-backend": "^4.1.0",
     "@12-apps/product-research": "^2.0.0",
-    "@12-apps/rbac": "^3.0.0",
-    "@12-apps/realtime": "^1.19.0",
-    "@12-apps/report-builder": "^4.0.0",
-    "@12-apps/shift": "^2.0.0",
+    "@12-apps/rbac": "^4.0.0",
+    "@12-apps/realtime": "^2.0.0",
+    "@12-apps/report-builder": "^5.0.0",
+    "@12-apps/shift": "^3.0.0",
     "@12-apps/typescript-config": "^1.20.0",
     "@types/node": "^22.10.6",
     "@vitest/coverage-v8": "^3.2.4",

package/prisma/migrations/20260731210000_shift_delete_guard/migration.sql

@@ -5,7 +5,7 @@
 -- with no foreign key (that is what keeps the package host-agnostic), so a host
 -- that deletes its tenant row and then sweeps the remaining by-value tables by
 -- `client_id` could never remove a shift: the RAISE aborted the whole
--- transaction. Future Pay's demo-store reset does exactly that on EVERY deploy,
+-- transaction. The origin host's demo-store reset does exactly that on EVERY deploy,
 -- so a single shift row would have wedged the deploy step.
 --
 -- Deletability is host policy, not a package invariant. What the guard actually

package/prisma/migrations/20260812150000_add_mcp_oauth_tables/migration.sql

@@ -18,13 +18,13 @@
 -- Authorization codes are deliberately absent: they are STATELESS signed blobs,
 -- so there is no table to create and nothing to sweep.
 --
--- The columns, defaults, indexes and CHECK are future-pay's
+-- The columns, defaults, indexes and CHECK are the origin host's
 -- `20260713120000_add_oauth_client_refresh`,
 -- `20260715180000_add_onboarding_state_mcp_connection` (the mcp_connections half
 -- — the onboarding half belongs to @12-apps/onboarding) and
 -- `20260720120000_add_mcp_connection_host` verbatim, minus the FK to `users`:
 -- this package cannot know the name of a host's user table, and a host that has
--- one keeps its own constraint (future-pay's is ON DELETE CASCADE).
+-- one keeps its own constraint (the origin host's is ON DELETE CASCADE).
 --
 -- EVERY statement is guarded (`IF NOT EXISTS`, and a conrelid-scoped DO block for
 -- the CHECK, which has no IF NOT EXISTS form). That is what makes adoption by a
@@ -35,7 +35,7 @@
 -- the difference bites exactly the host this file is written for: `CREATE TABLE IF
 -- NOT EXISTS` skips the whole table, columns included, so a host holding an OLDER
 -- shape of one of these tables silently keeps it. Each table below is therefore
--- followed by a guarded `ADD COLUMN` for every column that reached future-pay in a
+-- followed by a guarded `ADD COLUMN` for every column that reached the origin host in a
 -- LATER migration than its own CREATE. The full audit: `oauth_refresh_tokens
 -- .user_sub` (`20260713150000_add_oauth_refresh_user_sub`) and `mcp_connections
 -- .host` (`20260720120000_add_mcp_connection_host`). `oauth_clients` needs none —
@@ -112,10 +112,10 @@ CREATE INDEX IF NOT EXISTS "oauth_refresh_tokens_user_email_client_id_idx"
 -- `CREATE TABLE IF NOT EXISTS` skips the WHOLE table, so a host that already holds
 -- `oauth_refresh_tokens` in an OLDER SHAPE gets none of the columns declared above
 -- — statement-level guarding is not the same as column-level guarding. That is
--- precisely how future-pay's own history ran: `user_sub` arrived in a SECOND
+-- precisely how the origin host's own history ran: `user_sub` arrived in a SECOND
 -- migration (FUT-105, `20260713150000_add_oauth_refresh_user_sub`), so a host
 -- frozen before it would adopt this file, skip the CREATE, never get the column,
--- and then fail on every refresh the package serves. Mirror future-pay's pair
+-- and then fail on every refresh the package serves. Mirror the origin host's pair
 -- verbatim — guarded add with a backfill default to satisfy NOT NULL, then drop
 -- the default so the column matches the Prisma schema (`String`, no default).
 -- Both statements are no-ops on a fresh host and on a replay.
@@ -147,6 +147,6 @@ CREATE INDEX IF NOT EXISTS "mcp_connections_last_active_at_idx"
   ON "mcp_connections"("last_active_at");
 
 -- A host adopting this migration where `mcp_connections` predates the `host`
--- column (future-pay added it in a later migration) gets it here; a fresh host
+-- column (the origin host added it in a later migration) gets it here; a fresh host
 -- already has it from the CREATE above, so the guard makes both cases a no-op.
 ALTER TABLE "mcp_connections" ADD COLUMN IF NOT EXISTS "host" TEXT;

package/prisma/migrations/20260812150000_add_onboarding_states/migration.sql

@@ -2,13 +2,13 @@
 -- the package and copied into a host's migrations folder by its
 -- plugin-migration sync.
 --
--- The columns, defaults, indexes and the status CHECK are future-pay's
+-- The columns, defaults, indexes and the status CHECK are the origin host's
 -- `20260715180000_add_onboarding_state_mcp_connection` verbatim, minus two
 -- things that are the HOST's vocabulary rather than the package's:
 --
 --   * the FKs to `users` / `clients` — this package cannot know the name of a
 --     host's user or tenant table. A host that has them keeps its own
---     constraints (future-pay's are ON DELETE CASCADE) and they stay
+--     constraints (the origin host's are ON DELETE CASCADE) and they stay
 --     compatible with everything the package writes;
 --   * the `mcp_connections` half of that migration, which belongs to
 --     @12-apps/mcp and ships in ITS folder.
@@ -16,7 +16,7 @@
 -- EVERY statement is guarded (`IF NOT EXISTS`, and a conrelid-scoped DO block
 -- for the CHECK, which has no IF NOT EXISTS form). That is what makes adoption
 -- by a host that ALREADY has the table a no-op instead of a failed deploy —
--- future-pay applies this and nothing changes, no `prisma migrate resolve`
+-- the origin host applies this and nothing changes, no `prisma migrate resolve`
 -- dance required. It is also what lets the PGlite provisioner replay it into an
 -- existing schema, which is how the harness and the integration suites run.
 

package/prisma/migrations/20260813140000_add_notification_tables/migration.sql

@@ -24,7 +24,7 @@
 --
 -- ============================ REPLAY SAFETY ================================
 -- Every statement is guarded, because the first adopters ALREADY HAVE these
--- tables: future-pay created them by hand before the package existed, so this
+-- tables: the origin host created them by hand before the package existed, so this
 -- migration must be a no-op there and correct on an empty database.
 --
 -- The guards are per COLUMN, not per table. `CREATE TABLE IF NOT EXISTS` alone

package/prisma/schema/mcp.prisma

@@ -11,7 +11,7 @@
 //
 // Host-agnostic by design (the entity-lifecycle / rbac doctrine): `user_id` is a
 // by-value scalar with NO relation, because this package cannot know the name of
-// the host's user model. The host's own migration may add the FK (future-pay's
+// the host's user model. The host's own migration may add the FK (the origin host's
 // is ON DELETE CASCADE). Note there is deliberately no `oauth_codes` table:
 // authorization codes are STATELESS signed blobs, so there is nothing to store
 // and nothing to sweep.

package/prisma/schema/notifications.prisma

@@ -22,7 +22,7 @@
 // and for a stronger reason: the category set is HOST vocabulary (`categories`
 // on the server config), so a closed set in the schema would be wrong for every
 // adopter but the first. A host that wants its own taxonomy enforced adds the
-// CHECK in a migration of its own — future-pay does. Only `channel` and `status`
+// CHECK in a migration of its own — the origin host does. Only `channel` and `status`
 // on the delivery row are closed here, because those two are the LIBRARY's.
 model Notification {
   id        String    @id @default(uuid())

package/prisma/schema/onboarding.prisma

@@ -12,7 +12,7 @@
 // Host-agnostic by design (the entity-lifecycle / report-builder doctrine):
 //   - `user_id` and `client_id` are by-value scalars, NOT relations — this
 //     package cannot know the name of the host's user or tenant model. The
-//     host's own migration may add the FK constraints (future-pay has both,
+//     host's own migration may add the FK constraints (the origin host has both,
 //     ON DELETE CASCADE).
 //   - `status` is a String with a DB CHECK rather than a Prisma enum (the
 //     house String+CHECK pattern); the four values are the package's own

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 {
-  __futurePayActorStore?: 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.__futurePayActorStore ??= 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 {
-  __futurePayPrisma?: PrismaClient;
-  __futurePayPrismaInit?: 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.__futurePayPrisma) return globalStore.__futurePayPrisma;
-  if (globalStore.__futurePayPrismaInit) return globalStore.__futurePayPrismaInit;
+  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.__futurePayPrisma = client;
-      globalStore.__futurePayPrismaInit = undefined;
+      storeClient(client);
+      storeInit(undefined);
       return client;
     })
     .catch((error: unknown) => {
-      globalStore.__futurePayPrismaInit = 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.__futurePayPrismaInit = 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.__futurePayPrisma = client;
-  globalStore.__futurePayPrismaInit = undefined;
+  storeClient(client);
+  storeInit(undefined);
 };
 
 /**
  * Reset the Prisma client instance (for testing).
  */
 export const resetPrismaClient = (): void => {
-  globalStore.__futurePayPrisma = undefined;
-  globalStore.__futurePayPrismaInit = undefined;
+  storeClient(undefined);
+  storeInit(undefined);
 };