@12-apps/prisma 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# @12-apps/prisma
+
+The repo's **Prisma host**. Everything Prisma-shaped lives here and nowhere
+else: the multi-file schema folder, the migrations folder, the sync scripts that
+pull plugin-owned models and migrations in, and the runtime `PrismaClient`
+singleton with its audit / append-only extensions.
+
+It was carved out of `@12-apps/shared-helpers`, which is a bag of generic
+utilities (S3, caching, requests, money, dates) and had no business owning a
+database schema. Splitting it means a consumer that wants `formatMoney` no
+longer installs `@prisma/client`, PGlite and a WASM Postgres to get it.
+
+```
+packages/prisma/
+  prisma/
+    schema/            # datasource + generator, plus the plugin partials
+    migrations/        # every committed migration, host- and plugin-owned
+    plugin-migrations.json   # generated: which migrations came from a plugin
+    migration-files.ts       # side-effect-free migration discovery
+  prisma.config.ts     # Prisma 7 config (schema/migrations paths, datasource)
+  scripts/             # the sync + verification scripts
+  src/                 # the runtime client and its extensions
+```
+
+## What it exports
+
+```ts
+import {
+  getPrismaClient,
+  setPrismaClient,
+  resetPrismaClient,
+  runWithActor,
+  setActor,
+  getActorUserId,
+  getActorAttribution,
+  normalizeSearchText,
+  AppendOnlyViolationError,
+  type PrismaClient,
+} from '@12-apps/prisma';
+```
+
+`getPrismaClient()` is lazy and memoised on `globalThis`, so Next dev /
+Turbopack hot-reload never spawns a second PGlite instance. It builds a
+PostgreSQL-backed client by default and a PGlite-backed one when `USE_FILE_DB`,
+`PGLITE_DATA_DIR` or a `pglite:` `DATABASE_URL` selects it — never in
+production unless `USE_FILE_DB=1` is explicit.
+
+Server-only. `AsyncLocalStorage` and PGlite are Node APIs, and Prisma is not
+Edge-safe, so nothing here may be imported (directly or transitively) from
+middleware or an Edge-runtime route.
+
+## The plugin seam
+
+Packages that own persisted models keep the model file **and its migrations** in
+their own folder, and this package pulls them in:
+
+| Owner | Partial | Pulled in by |
+|---|---|---|
+| `@12-apps/entity-lifecycle` | `entity-lifecycle.prisma` | `scripts/sync-lifecycle-schema.mjs` |
+| `@12-apps/product-research` | `product-research.prisma` | `scripts/sync-research-schema.mjs` |
+| `@12-apps/shift` | `shift.prisma` | `scripts/sync-shift-schema.mjs` |
+| `@12-apps/jobs` | `jobs.prisma` | `scripts/sync-jobs-schema.mjs` |
+| `@12-apps/payments-backend` | `payments.prisma` | committed symlink |
+| `@12-apps/report-builder` | `report-builder.prisma` | committed symlink |
+
+Migrations travel separately, through `scripts/sync-prisma-plugins.mjs`, which
+discovers every plugin-owned `migrations` directory **structurally** rather than
+from a hardcoded list.
+
+`prisma/schema/schema.prisma` is **datasource + generator only** — this repo
+deliberately owns no domain models, and no seed command either. The consuming
+application supplies both.
+
+Two rules that came from production incidents, gated by `package.test.ts`:
+
+- **Migrations are copied, never symlinked.** Prisma enumerates the migrations
+  folder with `lstat`, so a symlinked migration reports `isDirectory() === false`
+  and is silently skipped — a green deploy that changed no schema.
+- **A partial's owning package must be a declared workspace dependency.**
+  `turbo prune` copies only what the dependency graph reaches; an undeclared
+  owner is dropped from the build context, the committed partial's source
+  vanishes, and its sync script exits 1 during the image build.
+
+## Scripts
+
+```bash
+pnpm --filter @12-apps/prisma prisma:generate        # sync (check mode) + generate
+pnpm --filter @12-apps/prisma prisma:migrate         # prisma migrate dev
+pnpm --filter @12-apps/prisma prisma:sync-plugins    # repair plugin migration copies
+pnpm --filter @12-apps/prisma prisma:sync-lifecycle  # repair one partial
+```
+
+`build` and `prisma:generate` run every sync in `--check` mode: they **verify**
+the committed state and never repair it, so a CI gate can never assert against
+a tree it just fixed. Repair is always explicit.

package/dist/actor-context.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Per-request "who is acting" context (FUT-168), backed by Node's
+ * AsyncLocalStorage. The auth layer sets the current admin's `users.id` once a
+ * request is authorized; the Prisma audit extension (see `audit-extension.ts`)
+ * reads it to auto-stamp `created_by` / `updated_by` on tracked models — so no
+ * repository signature or call site has to thread the actor through by hand.
+ *
+ * FUT-152 enriches the context with the ROLE and SCOPE the request was
+ * authorized under, so audit entries can record not just who acted but under
+ * which authority — populated by the same guards that stamp the user id.
+ *
+ * FUT-458 adds a SECOND identity: the subject a request is being rendered as
+ * while a super-admin impersonation or a "Ver como" preview is live. It is
+ * stored as a PAIR — the subject plus the real human behind it — and the
+ * second half of that pair is written by this module alone. See
+ * {@link ActorAttributionSnapshot.realUserId} for why the real human cannot
+ * simply be read back out of {@link ActorContext.userId}.
+ *
+ * Server-only: AsyncLocalStorage is a Node API. Never import from the Edge
+ * middleware runtime.
+ */
+/** Role/scope authority attribution a caller may STAMP (FUT-152). */
+export interface ActorAttribution {
+    /** The role name the request was authorized under (e.g. `ADMIN`), if known. */
+    role?: string;
+    /** The scope the authorization decision was made in (tenant id / `GLOBAL`). */
+    scope?: string;
+    /**
+     * The DB `users.id` this request is being rendered AS (FUT-458) — a
+     * super-admin impersonation target, or a "Ver como" previewed member.
+     *
+     * NEVER the actor: {@link ActorContext.userId} stays the real human whose
+     * credentials authorized the request, and this is recorded ALONGSIDE it. The
+     * audit trail must be able to answer "who really did this" and "who did the
+     * screen claim to be" independently, and a single field cannot.
+     *
+     * `undefined` leaves an existing value untouched (see {@link setActor}'s merge
+     * rule); pass `null` to CLEAR it explicitly. Merge semantics make the
+     * distinction load-bearing here — an impersonation that cannot be cleared
+     * would leak onto every later write in the same request.
+     */
+    onBehalfOfUserId?: string | null;
+}
+/**
+ * What {@link getActorAttribution} hands back: everything a caller may stamp,
+ * plus the one field only this module ever writes.
+ */
+export interface ActorAttributionSnapshot extends ActorAttribution {
+    /**
+     * The REAL human behind a live impersonation (FUT-458) — captured from the
+     * same stamp that declared it, and absent/`null` when no impersonation is
+     * live. Deliberately NOT part of {@link ActorAttribution}: a caller cannot
+     * pass it, only this module derives it.
+     *
+     * Why it exists rather than "just read {@link ActorContext.userId}": that
+     * field is LAST-WRITE-WINS, and about sixty route bodies (plus
+     * `apps/web/lib/api/tenant.ts`) call `setActor(grant.userId, …)` themselves
+     * instead of going through the impersonation-aware stamp in
+     * `apps/web/lib/rbac/guards.ts`. While a session is impersonated the tenant
+     * guard resolves that grant for the EFFECTIVE subject, so those calls
+     * re-stamp `userId` with the person being impersonated — and an audit row
+     * derived from it then reads as though the impersonated person did the thing
+     * themselves. That is precisely the mis-attribution the epic calls
+     * unrecoverable, and `audit_logs` is append-only, so nothing can put it
+     * right afterwards.
+     *
+     * Editing those sixty call sites would fix today's tree and rot the moment
+     * someone writes the sixty-first, so the invariant is enforced HERE instead:
+     * the real human is recorded ONCE, by the stamp that knows both halves, and
+     * an unaware `setActor(someId)` has no way to reach it — it moves only when
+     * the impersonation itself is re-declared or cleared. The audit writer
+     * (`apps/web/lib/audit/audit.ts`) prefers it over `userId` whenever a live
+     * impersonation is present, which is what makes a plain re-stamp harmless.
+     *
+     * `userId` is left alone on purpose: it also feeds `created_by`/`updated_by`
+     * via the audit extension, where "the id this request is acting under" is a
+     * different (and mutable, therefore correctable) question from "who is
+     * answerable for this append-only row".
+     */
+    realUserId?: string | null;
+}
+export interface ActorContext extends ActorAttributionSnapshot {
+    /** The acting admin's DB `users.id`, stamped onto created_by/updated_by. */
+    userId: string;
+}
+/** Run `fn` with `userId` as the current actor. Nested calls override. */
+export declare const runWithActor: <T>(userId: string, fn: () => T, attribution?: ActorAttribution) => T;
+/**
+ * Establish an EMPTY actor scope for one request and run `fn` inside it — the
+ * request-boundary bootstrap (`createRouteHandler` wraps every handler in it).
+ *
+ * Why it must exist: {@link setActor} inside an AWAITED guard uses `enterWith`,
+ * which only applies to the guard's own async continuation — the CALLER resumes
+ * with the context it captured before the call, so the stamp silently vanishes
+ * and every audit entry reads "system". With a scope established here,
+ * `setActor` MUTATES the shared context object instead, which every frame of
+ * the request's async tree observes — stamps from arbitrarily deep guards
+ * survive back into the handler and its repositories.
+ */
+export declare const runWithActorScope: <T>(fn: () => T) => T;
+/**
+ * Stamp the current actor for the rest of this request. A falsy id (e.g. the
+ * superadmin env-grant carries no DB user id) is ignored so nothing is ever
+ * stamped with an empty string. Attribution fields MERGE — only the fields
+ * passed are updated — so a guard that knows just the scope doesn't erase a
+ * role a caller stamped (or vice versa). Inside a {@link runWithActorScope}
+ * boundary the stamp mutates the shared context (survives caller awaits);
+ * without one it falls back to `enterWith` (same-context callers only).
+ */
+export declare const setActor: (userId: string, attribution?: ActorAttribution) => void;
+/** The current actor's `users.id`, or undefined when no actor is set. */
+export declare const getActorUserId: () => string | undefined;
+/**
+ * The current actor's role/scope attribution (FUT-152) plus the impersonation
+ * PAIR (FUT-458) — the subject the request is rendered as, and the real human
+ * behind it — if stamped. Every field is `undefined` when nothing stamped it:
+ * the audit writer normalizes that to NULL at the row, so the distinction
+ * between "never stamped" and "explicitly cleared" stays here, where
+ * {@link setActor}'s merge rule needs it, and never leaks into a column.
+ *
+ * Both halves of the pair are returned together, and consumers must read them
+ * together: `onBehalfOfUserId` alone says an impersonation was *declared*,
+ * `realUserId` says who is answerable for it. A consumer that sees one without
+ * the other is looking at a context nothing in production can produce, and
+ * should treat the session as NOT impersonated rather than guess.
+ */
+export declare const getActorAttribution: () => ActorAttributionSnapshot;

package/dist/actor-context.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Per-request "who is acting" context (FUT-168), backed by Node's
+ * AsyncLocalStorage. The auth layer sets the current admin's `users.id` once a
+ * request is authorized; the Prisma audit extension (see `audit-extension.ts`)
+ * reads it to auto-stamp `created_by` / `updated_by` on tracked models — so no
+ * repository signature or call site has to thread the actor through by hand.
+ *
+ * FUT-152 enriches the context with the ROLE and SCOPE the request was
+ * authorized under, so audit entries can record not just who acted but under
+ * which authority — populated by the same guards that stamp the user id.
+ *
+ * FUT-458 adds a SECOND identity: the subject a request is being rendered as
+ * while a super-admin impersonation or a "Ver como" preview is live. It is
+ * stored as a PAIR — the subject plus the real human behind it — and the
+ * second half of that pair is written by this module alone. See
+ * {@link ActorAttributionSnapshot.realUserId} for why the real human cannot
+ * simply be read back out of {@link ActorContext.userId}.
+ *
+ * Server-only: AsyncLocalStorage is a Node API. Never import from the Edge
+ * middleware runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getActorAttribution = exports.getActorUserId = exports.setActor = exports.runWithActorScope = exports.runWithActor = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+// 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;
+const store = () => (globalStore.__futurePayActorStore ??= new node_async_hooks_1.AsyncLocalStorage());
+/**
+ * The REAL human behind `onBehalfOfUserId`, derived (never accepted) from the
+ * stamp that declares the impersonation (FUT-458).
+ *
+ * `userId` is that human by construction: the only stamp in the codebase that
+ * passes a non-null `onBehalfOfUserId` is `stampActor` in
+ * `apps/web/lib/rbac/guards.ts`, which hands over the real id and the subject
+ * in the SAME call. That co-location is the whole reason the pair can be
+ * trusted — nothing else knows both halves at once, so nothing else can forge
+ * one.
+ *
+ * Clearing is symmetric: ending an impersonation drops BOTH halves. A stale
+ * real id left behind would make every later write in the request look as
+ * though it still carried a hidden second identity.
+ */
+const realActorFor = (userId, onBehalfOfUserId) => onBehalfOfUserId === null ? null : userId;
+/**
+ * A fresh context for `userId`. The impersonation pair is derived only when
+ * the stamp expressed an opinion — `undefined` means "no opinion" everywhere
+ * in this module, and must not be written as a value.
+ */
+const freshContext = (userId, attribution) => ({
+    userId,
+    ...attribution,
+    ...(attribution.onBehalfOfUserId !== undefined
+        ? { realUserId: realActorFor(userId, attribution.onBehalfOfUserId) }
+        : {}),
+});
+/** Run `fn` with `userId` as the current actor. Nested calls override. */
+const runWithActor = (userId, fn, attribution = {}) => store().run(freshContext(userId, attribution), fn);
+exports.runWithActor = runWithActor;
+/**
+ * Establish an EMPTY actor scope for one request and run `fn` inside it — the
+ * request-boundary bootstrap (`createRouteHandler` wraps every handler in it).
+ *
+ * Why it must exist: {@link setActor} inside an AWAITED guard uses `enterWith`,
+ * which only applies to the guard's own async continuation — the CALLER resumes
+ * with the context it captured before the call, so the stamp silently vanishes
+ * and every audit entry reads "system". With a scope established here,
+ * `setActor` MUTATES the shared context object instead, which every frame of
+ * the request's async tree observes — stamps from arbitrarily deep guards
+ * survive back into the handler and its repositories.
+ */
+const runWithActorScope = (fn) => store().run({ userId: "" }, fn);
+exports.runWithActorScope = runWithActorScope;
+/**
+ * Stamp the current actor for the rest of this request. A falsy id (e.g. the
+ * superadmin env-grant carries no DB user id) is ignored so nothing is ever
+ * stamped with an empty string. Attribution fields MERGE — only the fields
+ * passed are updated — so a guard that knows just the scope doesn't erase a
+ * role a caller stamped (or vice versa). Inside a {@link runWithActorScope}
+ * boundary the stamp mutates the shared context (survives caller awaits);
+ * without one it falls back to `enterWith` (same-context callers only).
+ */
+const setActor = (userId, attribution = {}) => {
+    if (!userId)
+        return;
+    const current = store().getStore();
+    if (current) {
+        current.userId = userId;
+        if (attribution.role !== undefined)
+            current.role = attribution.role;
+        if (attribution.scope !== undefined)
+            current.scope = attribution.scope;
+        // FUT-458 — same merge rule, and the reason it has to be `!== undefined`
+        // rather than a truthiness check: ENDING an impersonation is expressed as
+        // `null`, and a truthy guard would treat that clear as "no opinion" and
+        // leave the previous target standing for the rest of the request.
+        //
+        // Note what this branch does NOT do: an unaware stamp — one that passes no
+        // `onBehalfOfUserId` at all — moves `userId` and nothing else. The
+        // impersonation pair survives it untouched, which is the property the
+        // audit trail is built on (see `ActorAttributionSnapshot.realUserId`).
+        if (attribution.onBehalfOfUserId !== undefined) {
+            current.onBehalfOfUserId = attribution.onBehalfOfUserId;
+            current.realUserId = realActorFor(userId, attribution.onBehalfOfUserId);
+        }
+        return;
+    }
+    store().enterWith(freshContext(userId, attribution));
+};
+exports.setActor = setActor;
+/** The current actor's `users.id`, or undefined when no actor is set. */
+const getActorUserId = () => store().getStore()?.userId || undefined;
+exports.getActorUserId = getActorUserId;
+/**
+ * The current actor's role/scope attribution (FUT-152) plus the impersonation
+ * PAIR (FUT-458) — the subject the request is rendered as, and the real human
+ * behind it — if stamped. Every field is `undefined` when nothing stamped it:
+ * the audit writer normalizes that to NULL at the row, so the distinction
+ * between "never stamped" and "explicitly cleared" stays here, where
+ * {@link setActor}'s merge rule needs it, and never leaks into a column.
+ *
+ * Both halves of the pair are returned together, and consumers must read them
+ * together: `onBehalfOfUserId` alone says an impersonation was *declared*,
+ * `realUserId` says who is answerable for it. A consumer that sees one without
+ * the other is looking at a context nothing in production can produce, and
+ * should treat the session as NOT impersonated rather than guess.
+ */
+const getActorAttribution = () => {
+    const context = store().getStore();
+    return {
+        role: context?.role,
+        scope: context?.scope,
+        onBehalfOfUserId: context?.onBehalfOfUserId,
+        realUserId: context?.realUserId,
+    };
+};
+exports.getActorAttribution = getActorAttribution;

package/dist/append-only-extension.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Prisma client extension that makes the audit log physically append-only at
+ * the client layer (FUT-209).
+ *
+ * The audit trail's value rests on immutability: an entry that can be edited
+ * or deleted after the fact proves nothing. There is no code path that should
+ * ever mutate `audit_logs`, so every update/upsert/delete delegate on the
+ * model throws — including the batch variants — before reaching the database.
+ * The house pattern for append-only tables (entity_versions) relies on code
+ * discipline alone; the audit log gets the harder guard because it exists
+ * precisely for the cases where discipline failed.
+ *
+ * The ONLY sanctioned removal is the retention sweep (12-month policy), which
+ * runs raw SQL over `created_at` — `$executeRaw` bypasses model delegates and
+ * is untouched by this extension. Test truncation uses raw SQL for the same
+ * reason.
+ */
+import type { PrismaClient } from '@prisma/client';
+/** Thrown when code attempts to mutate an append-only model. */
+export declare class AppendOnlyViolationError extends Error {
+    constructor(model: string, operation: string);
+}
+/**
+ * Wrap a client so mutating operations on append-only models throw.
+ * Returns the client typed as {@link PrismaClient}: the extension only adds
+ * query middleware (no new delegates), so every existing call site stays valid.
+ */
+export declare function applyAppendOnlyGuard(client: PrismaClient): PrismaClient;

package/dist/append-only-extension.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Prisma client extension that makes the audit log physically append-only at
+ * the client layer (FUT-209).
+ *
+ * The audit trail's value rests on immutability: an entry that can be edited
+ * or deleted after the fact proves nothing. There is no code path that should
+ * ever mutate `audit_logs`, so every update/upsert/delete delegate on the
+ * model throws — including the batch variants — before reaching the database.
+ * The house pattern for append-only tables (entity_versions) relies on code
+ * discipline alone; the audit log gets the harder guard because it exists
+ * precisely for the cases where discipline failed.
+ *
+ * The ONLY sanctioned removal is the retention sweep (12-month policy), which
+ * runs raw SQL over `created_at` — `$executeRaw` bypasses model delegates and
+ * is untouched by this extension. Test truncation uses raw SQL for the same
+ * reason.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppendOnlyViolationError = void 0;
+exports.applyAppendOnlyGuard = applyAppendOnlyGuard;
+/** Prisma model names that must never be updated or deleted via the model API. */
+const APPEND_ONLY_MODELS = new Set(['AuditLog']);
+/** Thrown when code attempts to mutate an append-only model. */
+class AppendOnlyViolationError extends Error {
+    constructor(model, operation) {
+        super(`${model} is append-only: "${operation}" is not allowed. ` +
+            'Audit entries are immutable; retention sweeps use raw SQL.');
+        this.name = 'AppendOnlyViolationError';
+    }
+}
+exports.AppendOnlyViolationError = AppendOnlyViolationError;
+/** Throw for an append-only model, else pass the call through untouched. */
+function guard(model, operation, args, query) {
+    if (APPEND_ONLY_MODELS.has(model)) {
+        throw new AppendOnlyViolationError(model, operation);
+    }
+    return query(args);
+}
+/**
+ * Wrap a client so mutating operations on append-only models throw.
+ * Returns the client typed as {@link PrismaClient}: the extension only adds
+ * query middleware (no new delegates), so every existing call site stays valid.
+ */
+function applyAppendOnlyGuard(client) {
+    const extended = client.$extends({
+        name: 'appendOnlyGuard',
+        query: {
+            $allModels: {
+                update({ model, args, query }) {
+                    return guard(model, 'update', args, query);
+                },
+                updateMany({ model, args, query }) {
+                    return guard(model, 'updateMany', args, query);
+                },
+                updateManyAndReturn({ model, args, query }) {
+                    return guard(model, 'updateManyAndReturn', args, query);
+                },
+                upsert({ model, args, query }) {
+                    return guard(model, 'upsert', args, query);
+                },
+                delete({ model, args, query }) {
+                    return guard(model, 'delete', args, query);
+                },
+                deleteMany({ model, args, query }) {
+                    return guard(model, 'deleteMany', args, query);
+                },
+            },
+        },
+    });
+    return extended;
+}

package/dist/audit-extension.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Prisma client extension that auto-stamps change attribution (FUT-168).
+ *
+ * For the tracked models it fills `createdBy` on create and `updatedBy` on
+ * create/update from the current actor (see `actor-context.ts`), so repositories
+ * and actions never pass an actor id explicitly. A write with no actor in scope
+ * (system/seed/unauthenticated) is left untouched — the columns stay NULL.
+ *
+ * Only fields the caller did not already set are filled, so an explicit override
+ * always wins.
+ */
+import type { PrismaClient } from '@prisma/client';
+/**
+ * Wrap a client so tracked-model writes are attributed to the current actor.
+ * Returns the client typed as {@link PrismaClient}: the extension only adds query
+ * middleware (no new delegates), so every existing call site stays valid.
+ */
+export declare function applyAuditStamps(client: PrismaClient): PrismaClient;

package/dist/audit-extension.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Prisma client extension that auto-stamps change attribution (FUT-168).
+ *
+ * For the tracked models it fills `createdBy` on create and `updatedBy` on
+ * create/update from the current actor (see `actor-context.ts`), so repositories
+ * and actions never pass an actor id explicitly. A write with no actor in scope
+ * (system/seed/unauthenticated) is left untouched — the columns stay NULL.
+ *
+ * Only fields the caller did not already set are filled, so an explicit override
+ * always wins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyAuditStamps = applyAuditStamps;
+const actor_context_1 = require("./actor-context");
+const search_normalize_1 = require("./search-normalize");
+/** Prisma model names that carry `created_by`/`updated_by` + `search_name`. */
+const TRACKED_MODELS = new Set([
+    'MenuItem',
+    'InventoryItem',
+    'ProductCategory',
+    'Supplier',
+    'Discount',
+]);
+/** Fill created_by + updated_by on a create payload (without clobbering overrides). */
+function stampCreate(data, userId) {
+    if (data.createdBy === undefined)
+        data.createdBy = userId;
+    if (data.updatedBy === undefined)
+        data.updatedBy = userId;
+}
+/** Fill updated_by on an update payload. */
+function stampUpdate(data, userId) {
+    if (data.updatedBy === undefined)
+        data.updatedBy = userId;
+}
+/**
+ * Keep `search_name` in sync with `name` for accent/case-insensitive search
+ * (FUT-168). Applied on every tracked write that sets `name` — including
+ * system/seed writes with no actor — so the column never drifts. A caller that
+ * sets `searchName` explicitly wins.
+ */
+function stampSearchName(data) {
+    if (typeof data.name === 'string' && data.searchName === undefined) {
+        data.searchName = (0, search_normalize_1.normalizeSearchText)(data.name);
+    }
+}
+/**
+ * Wrap a client so tracked-model writes are attributed to the current actor.
+ * Returns the client typed as {@link PrismaClient}: the extension only adds query
+ * middleware (no new delegates), so every existing call site stays valid.
+ */
+function applyAuditStamps(client) {
+    const extended = client.$extends({
+        name: 'auditStamps',
+        query: {
+            $allModels: {
+                create({ model, args, query }) {
+                    if (TRACKED_MODELS.has(model) && args.data) {
+                        const data = args.data;
+                        stampSearchName(data);
+                        const userId = (0, actor_context_1.getActorUserId)();
+                        if (userId)
+                            stampCreate(data, userId);
+                    }
+                    return query(args);
+                },
+                createMany({ model, args, query }) {
+                    if (TRACKED_MODELS.has(model) && args.data) {
+                        const userId = (0, actor_context_1.getActorUserId)();
+                        const rows = Array.isArray(args.data) ? args.data : [args.data];
+                        rows.forEach((row) => {
+                            const data = row;
+                            stampSearchName(data);
+                            if (userId)
+                                stampCreate(data, userId);
+                        });
+                    }
+                    return query(args);
+                },
+                update({ model, args, query }) {
+                    if (TRACKED_MODELS.has(model) && args.data) {
+                        const data = args.data;
+                        stampSearchName(data);
+                        const userId = (0, actor_context_1.getActorUserId)();
+                        if (userId)
+                            stampUpdate(data, userId);
+                    }
+                    return query(args);
+                },
+                updateMany({ model, args, query }) {
+                    if (TRACKED_MODELS.has(model) && args.data) {
+                        const data = args.data;
+                        stampSearchName(data);
+                        const userId = (0, actor_context_1.getActorUserId)();
+                        if (userId)
+                            stampUpdate(data, userId);
+                    }
+                    return query(args);
+                },
+                upsert({ model, args, query }) {
+                    if (TRACKED_MODELS.has(model)) {
+                        const userId = (0, actor_context_1.getActorUserId)();
+                        if (args.create) {
+                            const data = args.create;
+                            stampSearchName(data);
+                            if (userId)
+                                stampCreate(data, userId);
+                        }
+                        if (args.update) {
+                            const data = args.update;
+                            stampSearchName(data);
+                            if (userId)
+                                stampUpdate(data, userId);
+                        }
+                    }
+                    return query(args);
+                },
+            },
+        },
+    });
+    return extended;
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Prisma client singleton.
+ *
+ * Default mode builds a PostgreSQL-backed `PrismaClient` (the real / production
+ * database, driven by `DATABASE_URL`). When a PGlite flag is present in the
+ * environment the same client is built on the community `pglite-prisma-adapter`
+ * so PGlite (WASM Postgres) becomes the app runtime database for local dev and
+ * Playwright e2e — no Docker Postgres required.
+ *
+ * PGlite mode is selected by ANY of:
+ *   - `USE_FILE_DB=1` (or `true`)            → in-memory, unless a dir is also set
+ *   - `PGLITE_DATA_DIR=<dir>`                → file-backed at <dir>
+ *   - `DATABASE_URL` starting with `pglite:` → `pglite:memory` or `pglite:<dir>`
+ *
+ * Production safety: when `NODE_ENV=production` the database is ALWAYS real
+ * PostgreSQL unless `USE_FILE_DB=1` is set explicitly — so a stray
+ * `PGLITE_DATA_DIR` / `pglite:` URL can never silently point prod at a throwaway
+ * WASM DB. `USE_FILE_DB=0` forces real PostgreSQL everywhere (dev/e2e opt-out).
+ *
+ * The generated `PrismaClient` type is re-exported below so consumers stay fully
+ * typed without any hand-written stub interfaces. Server-only: never import this
+ * (directly or transitively) from middleware or an Edge-runtime route — PGlite
+ * needs Node's filesystem/WASM and Prisma is not Edge-safe.
+ */
+export type { PrismaClient } from '@prisma/client';
+import type { PrismaClient } from '@prisma/client';
+export { AppendOnlyViolationError } from './append-only-extension';
+export { getActorAttribution, getActorUserId, runWithActor, runWithActorScope, setActor, type ActorAttribution, type ActorAttributionSnapshot, type ActorContext, } from './actor-context';
+export { normalizeSearchText } from './search-normalize';
+/**
+ * Get or create the Prisma client instance.
+ *
+ * Lazy and memoised: concurrent callers share a single in-flight init promise,
+ * so only one client (and at most one PGlite instance) is ever created. A
+ * missing generated client surfaces an actionable error rather than a hard
+ * module-load failure.
+ */
+export declare const getPrismaClient: () => Promise<PrismaClient>;
+/**
+ * Set a custom Prisma client instance (for testing).
+ */
+export declare const setPrismaClient: (client: PrismaClient) => void;
+/**
+ * Reset the Prisma client instance (for testing).
+ */
+export declare const resetPrismaClient: () => void;