@12-apps/prisma 1.0.0

package/prisma/schema/entity-lifecycle.prisma

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// @12-apps/entity-lifecycle — CANONICAL Prisma model partial (plug-and-play).
+//
+// This file is the single source of truth for the four generic lifecycle
+// tables. A host project does NOT copy these models into its main schema by
+// hand: it uses Prisma's multi-file schema folder and SYNCS this file into it
+// (see packages/shared-helpers/scripts/sync-lifecycle-schema.mjs in this repo
+// for the reference sync step — run before `prisma generate`).
+//
+// Host-agnostic by design:
+//   - The tracked record is named BY VALUE via (entity_type, entity_id) — no
+//     FK to the host's entity tables, so any collection plugs in with zero
+//     schema change here.
+//   - The tenant is a by-value `client_id` scalar — no relation to the host's
+//     tenant model (whose name this package cannot know). The host's SQL
+//     migration may add the FK constraint (recommended: ON DELETE CASCADE).
+//   - `kind` / `status` / `action` are Strings; the host migration adds CHECK
+//     constraints for the closed sets documented on each field.
+// ---------------------------------------------------------------------------
+
+// One row of an entity's version history. Version 1 (and any retention-
+// compaction base) is a FULL snapshot (`is_snapshot`, `data` = whole entity);
+// every other row is a DELTA: `data` holds only the top-level fields that
+// changed (their new values) and `removed_fields` the fields that disappeared.
+// The state at version N is rebuilt by replaying rows 1..N. `kind` is
+// CREATE | UPDATE | RESTORE. `actor_id` is the host's user id (by value);
+// null = system write. Append-only: no `updated_at`.
+model EntityVersion {
+  id            String   @id @default(uuid())
+  clientId      String   @map("client_id")
+  entityType    String   @map("entity_type")
+  entityId      String   @map("entity_id")
+  version       Int
+  kind          String
+  isSnapshot    Boolean  @map("is_snapshot")
+  data          Json
+  removedFields Json     @default("[]") @map("removed_fields")
+  actorId       String?  @map("actor_id")
+  // For kind RESTORE: which version was restored.
+  restoredFrom  Int?     @map("restored_from")
+  createdAt     DateTime @default(now()) @map("created_at")
+
+  @@unique([clientId, entityType, entityId, version])
+  @@index([clientId, entityType, entityId])
+  // Serves the retention sweep ("versions older than N days").
+  @@index([createdAt])
+  @@map("entity_versions")
+}
+
+// One deleted record in a tenant's recycle bin. Deleting an aggregate records
+// a TREE: the root entry plus one child entry per dependent record deleted
+// along with it, linked via `parent_entry_id` — the registry the bin page
+// renders so a restore shows what it brings back. `snapshot` freezes the data
+// needed to preview/restore. `status` is DELETED | RESTORED | PURGED:
+// restore/purge KEEP the row as an audit trail (status flip, never deleted).
+model RecycleBinEntry {
+  id            String   @id @default(uuid())
+  clientId      String   @map("client_id")
+  entityType    String   @map("entity_type")
+  entityId      String   @map("entity_id")
+  parentEntryId String?  @map("parent_entry_id")
+  label         String
+  snapshot      Json
+  status        String   @default("DELETED")
+  deletedBy     String?  @map("deleted_by")
+  deletedAt     DateTime @default(now()) @map("deleted_at")
+  updatedAt     DateTime @updatedAt @map("updated_at")
+
+  parent   RecycleBinEntry?  @relation("RecycleBinTree", fields: [parentEntryId], references: [id], onDelete: Cascade)
+  children RecycleBinEntry[] @relation("RecycleBinTree")
+
+  // The bin page: a tenant's deleted roots, newest first.
+  @@index([clientId, status, deletedAt])
+  @@index([clientId, entityType, entityId])
+  @@index([parentEntryId])
+  @@map("recycle_bin_entries")
+}
+
+// A per-item draft: unpublished edits kept next to the live record.
+// `entity_id` NULL = a draft of a brand-new item that doesn't exist yet. At
+// most one OPEN draft per (tenant, type, entity) — enforce with a partial
+// unique index in the host migration (WHERE status = 'OPEN' AND entity_id IS
+// NOT NULL; Prisma cannot express the filter). `status` is
+// OPEN | PUBLISHED | DISCARDED; publish/discard keep the row as history.
+model EntityDraft {
+  id         String   @id @default(uuid())
+  clientId   String   @map("client_id")
+  entityType String   @map("entity_type")
+  entityId   String?  @map("entity_id")
+  data       Json
+  status     String   @default("OPEN")
+  createdBy  String?  @map("created_by")
+  updatedBy  String?  @map("updated_by")
+  createdAt  DateTime @default(now()) @map("created_at")
+  updatedAt  DateTime @updatedAt @map("updated_at")
+
+  @@index([clientId, entityType, status])
+  @@index([clientId, entityType, entityId])
+  @@map("entity_drafts")
+}
+
+// A pending change awaiting approval. When the approvals feature is active
+// for a tenant+collection, a write by an actor without the approve permission
+// is parked here instead of applied; an approver later applies or rejects it.
+// `payload` is the full desired snapshot for CREATE/UPDATE (empty for
+// DELETE). `action` is CREATE | UPDATE | DELETE; `status` is
+// PENDING | APPROVED | REJECTED. Decided rows are kept as an audit trail.
+model ChangeRequest {
+  id           String    @id @default(uuid())
+  clientId     String    @map("client_id")
+  entityType   String    @map("entity_type")
+  entityId     String?   @map("entity_id")
+  action       String
+  payload      Json
+  status       String    @default("PENDING")
+  requestedBy  String?   @map("requested_by")
+  requestedAt  DateTime  @default(now()) @map("requested_at")
+  decidedBy    String?   @map("decided_by")
+  decidedAt    DateTime? @map("decided_at")
+  decisionNote String?   @map("decision_note")
+
+  // The approvals inbox: a tenant's pending requests, newest first.
+  @@index([clientId, status, requestedAt])
+  @@index([clientId, entityType, entityId])
+  @@map("change_requests")
+}

package/prisma/schema/jobs.prisma

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// @12-apps/jobs — CANONICAL Prisma model partial (plug-and-play).
+//
+// This file is the single source of truth for the sweep-lease table. A host
+// project does NOT copy this model into its main schema by hand: it uses
+// Prisma's multi-file schema folder and SYNCS this file into it (see
+// packages/shared-helpers/scripts/sync-jobs-schema.mjs in this repo for the
+// reference sync step — run before `prisma generate`). The migration ships
+// alongside, in prisma/migrations/, and is COPIED into the host's migrations
+// folder — never symlinked, because Prisma enumerates that folder with lstat
+// and silently skips a linked directory.
+//
+// Host-agnostic by design: the lease names a JOB, not a tenant or a user, so
+// there is no relation to any host table at all.
+// ---------------------------------------------------------------------------
+
+/// Named, time-bounded claims on the scheduled sweeps.
+///
+/// Within one worker the sweeps are single-flight (their own queue at
+/// concurrency 1). Across two workers that guarantee evaporates: both read
+/// the same work list and do the same work twice. Correctness is expected to
+/// survive that (sweeps are idempotent by durable markers in the host's own
+/// tables), but the effort and the user-visible notices double.
+///
+/// A lease row rather than `pg_advisory_lock`, deliberately. A session-level
+/// advisory lock has to be released on the SAME connection that took it, and
+/// Prisma pools connections with no such guarantee — a release that lands on
+/// another connection silently fails and strands the lock, after which that
+/// sweep never runs again until the connection recycles. The transaction-
+/// scoped variant releases correctly but only holds for the transaction, and
+/// sweeps make external HTTP calls that have no business inside one.
+///
+/// `expiresAt` is what makes a dead holder recoverable without anyone
+/// intervening: a worker that is OOM-killed mid-sweep leaves the row behind,
+/// and the next tick past the expiry simply takes it. The claim itself is a
+/// conditional UPDATE, so the database decides the winner — two workers
+/// racing cannot both see it as free.
+model SweepLease {
+  /// The job name, e.g. "billing.tick". One lease per sweep.
+  name       String   @id
+  /// Which worker run holds it — release only ever matches its own holder.
+  holder     String
+  acquiredAt DateTime @default(now()) @map("acquired_at")
+  /// Past this instant the lease is free, whether or not it was released.
+  expiresAt  DateTime @map("expires_at")
+
+  @@map("sweep_leases")
+}

package/prisma/schema/product-research.prisma

@@ -0,0 +1,217 @@
+// ---------------------------------------------------------------------------
+// @12-apps/product-research — CANONICAL Prisma model partial (plug-and-play).
+//
+// This file is the single source of truth for the four research-to-buy tables.
+// A host project does NOT copy these models into its main schema by hand: it
+// uses Prisma's multi-file schema folder and SYNCS this file into it (see
+// packages/shared-helpers/scripts/sync-research-schema.mjs in this repo for
+// the reference sync step — run before `prisma generate`). Migrations are
+// owned by this package too (prisma/migrations) and reach the host through
+// scripts/sync-prisma-plugins.mjs.
+//
+// Host-agnostic by design (entity-lifecycle / payments-backend doctrine):
+//   - The tenant is a by-value `client_id` scalar — no relation to the host's
+//     tenant model. The host's repository layer scopes every read/write.
+//   - The researched catalog item is named BY VALUE via
+//     (catalog_ref_type, catalog_ref_id) — no FK to host catalog tables, so a
+//     restaurant's MenuItem and a dental system's product plug in identically.
+//   - `type` / `status` are Strings; the migration adds CHECK constraints for
+//     the closed sets documented on each field.
+//   - Money is integer cents with an explicit `currency` (BRL first host).
+// ---------------------------------------------------------------------------
+
+// One configured offer source for a tenant. `type` is the connector key:
+// VTEX | MERCADO_LIVRE | SERP | AMAZON | MANUAL. `config` holds the
+// connector-specific settings (e.g. a VTEX store's baseUrl + sales channel).
+// `status` is ACTIVE | DEGRADED — a connector that keeps failing is marked
+// DEGRADED (with `last_error_at`) so the UI can say "results may be
+// incomplete" instead of silently shrinking.
+//
+// Paid connectors (SERP | AMAZON | MERCADO_LIVRE) are singleton INTEGRATIONS
+// (FUT-434): at most one row per (client_id, type), holding the tenant's own
+// encrypted API credential inside `config`. Enforced by a partial unique
+// index in this package's migrations — like the CHECK constraints, DDL the
+// Prisma schema cannot express (see src/integrations.ts for the config keys).
+model PriceSource {
+  id          String    @id @default(uuid())
+  clientId    String    @map("client_id")
+  type        String
+  name        String
+  config      Json      @default("{}")
+  enabled     Boolean   @default(true)
+  status      String    @default("ACTIVE")
+  lastErrorAt DateTime? @map("last_error_at")
+  // Soft-delete: a non-null timestamp removes the source from the roster and
+  // from every new research run, while its SupplierOffer rows keep their FK so
+  // finished runs stay fully readable. The host filters `archived_at IS NULL`
+  // on every live read; there is no restore path.
+  archivedAt  DateTime? @map("archived_at")
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
+
+  offers        SupplierOffer[]
+  manualEntries ManualPriceEntry[]
+
+  // NO @@unique on (clientId, name): the tenant unique exists in the DB as a
+  // PARTIAL index — `price_sources_client_id_name_key` WHERE `archived_at IS
+  // NULL` (20260729120000_price_source_soft_delete). Prisma cannot express a
+  // filtered unique, and an unconditional `@@unique` would both be a lie the
+  // client acts on (a `clientId_name` findUnique the index cannot serve) and
+  // let a soft-deleted source squat its name forever. Same arrangement as the
+  // host's `discounts_client_id_name_key`.
+  @@index([clientId, enabled])
+  @@map("price_sources")
+}
+
+// What a buyer asked to research: a catalog item (by value) or a free-text
+// term, a quantity and a region code (CEP in Brazil) that selects regional
+// pricing. `requested_by` is the host's user id, by value; null = system.
+// `term_normalized` mirrors normalizeText(term) — accent/case/punctuation
+// folded — the indexed key the widened widget lookup prefilters by (FUT-430);
+// hosts set it on write (no unaccent/pg_trgm, which PGlite lacks), and the
+// owning migration backfills pre-existing rows in plain SQL.
+model ResearchRequest {
+  id             String   @id @default(uuid())
+  clientId       String   @map("client_id")
+  catalogRefType String?  @map("catalog_ref_type")
+  catalogRefId   String?  @map("catalog_ref_id")
+  term           String
+  termNormalized String?  @map("term_normalized")
+  brand          String?
+  ean            String?
+  quantity       Int      @default(1)
+  region         String?
+  requestedBy    String?  @map("requested_by")
+  createdAt      DateTime @default(now()) @map("created_at")
+
+  runs ResearchRun[]
+
+  @@index([clientId, createdAt])
+  @@index([clientId, termNormalized])
+  @@map("research_requests")
+}
+
+// One execution of a request across the enabled sources. `status` is
+// PENDING | RUNNING | COMPLETED | FAILED. `source_stats` records one entry per
+// source ({sourceId, type, name, status, offerCount, ms, error?}) — the data
+// behind the per-source streaming row and the "degraded/cap" banners.
+model ResearchRun {
+  id          String    @id @default(uuid())
+  clientId    String    @map("client_id")
+  requestId   String    @map("request_id")
+  status      String    @default("PENDING")
+  sourceStats Json      @default("[]") @map("source_stats")
+  error       String?
+  startedAt   DateTime? @map("started_at")
+  finishedAt  DateTime? @map("finished_at")
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
+
+  request ResearchRequest @relation(fields: [requestId], references: [id], onDelete: Cascade)
+  offers  SupplierOffer[]
+
+  @@index([clientId, createdAt])
+  @@index([requestId])
+  // Cross-tenant reads by time alone (the host's superadmin diagnostics inbox:
+  // "every failed source in the last 24 h"). `(client_id, created_at)` cannot
+  // serve those — the leading column is unbound and Postgres has no btree skip
+  // scan — so without this index the query degrades to a full sequential scan
+  // of a table that nothing prunes.
+  @@index([createdAt])
+  @@map("research_runs")
+}
+
+// One purchasable offer found by a run. Prices are integer cents;
+// `unit_price_cents` is the pack-normalized comparison key (a 12x350ml fardo
+// and a single can compete on the same axis) and `total_cents` is the cost for
+// the requested quantity plus whatever shipping the source stated — a LOWER
+// BOUND when it stated none (see `shipping_cents`). `relevance_score` is the 0..1
+// no-AI token-match confidence; offers below the threshold are never stored.
+// `expires_at` is the freshness horizon — an expired offer must not be shown
+// as a current price. `purchased_at` closes the loop when the buyer marks the
+// offer they actually bought. `source_id` survives source deletion as NULL so
+// history keeps its offers.
+//
+// `outside_delivery_area` (FUT-491) marks an offer whose price belongs to the
+// STORE'S DEFAULT REGION because the store does not deliver to the researched
+// CEP. A real column rather than a corner of `raw`: `raw` is the verbatim
+// connector payload kept for offline replay, so writing our own field into it
+// would break that contract, and the flag has to survive re-reads, cached runs
+// and the offers API — plus be filterable — which a blob cannot promise.
+//
+// `shipping_cents` is NULLABLE with no default (FUT-518): NULL = the source
+// never stated a shipping cost, 0 = the source stated FREE. It used to be
+// `NOT NULL DEFAULT 0`, which made those two the same value — so every SERP
+// offer (serp.ts states shipping never) was persisted as free shipping and
+// competed on an understated total. Nullable rather than a companion boolean
+// because `eta_days Int?` two lines down is this model's existing way of
+// saying "the source did not say", and a flag beside an Int would be two
+// facts where one suffices. HISTORICAL ROWS ARE UNRECOVERABLE: every row
+// written before the migration holds 0 and stays 0 — see the migration.
+model SupplierOffer {
+  id                  String    @id @default(uuid())
+  clientId            String    @map("client_id")
+  runId               String    @map("run_id")
+  sourceId            String?   @map("source_id")
+  sourceType          String    @map("source_type")
+  supplierName        String    @map("supplier_name")
+  title               String
+  url                 String?
+  imageUrl            String?   @map("image_url")
+  currency            String    @default("BRL")
+  priceCents          Int       @map("price_cents")
+  shippingCents       Int?      @map("shipping_cents")
+  packQuantity        Int       @default(1) @map("pack_quantity")
+  unitPriceCents      Int       @map("unit_price_cents")
+  totalCents          Int       @map("total_cents")
+  availability        String?
+  etaDays             Int?      @map("eta_days")
+  relevanceScore      Float     @map("relevance_score")
+  rank                Int?
+  raw                 Json?
+  expiresAt           DateTime? @map("expires_at")
+  purchasedAt         DateTime? @map("purchased_at")
+  hiddenAt            DateTime? @map("hidden_at")
+  outsideDeliveryArea Boolean   @default(false) @map("outside_delivery_area")
+  createdAt           DateTime  @default(now()) @map("created_at")
+
+  run    ResearchRun  @relation(fields: [runId], references: [id], onDelete: Cascade)
+  source PriceSource? @relation(fields: [sourceId], references: [id], onDelete: SetNull)
+
+  @@index([runId, rank])
+  @@index([clientId, createdAt])
+  @@index([clientId, expiresAt])
+  @@map("supplier_offers")
+}
+
+// One row of a manually imported price list (or a one-off typed quote),
+// belonging to a MANUAL-type PriceSource. This is the standing dataset the
+// manual connector reads DURING research runs — unlike SupplierOffer rows,
+// which are per-run results. `valid_until` is the staleness horizon: expired
+// entries stop appearing in new research results (the host's store filters
+// them), never shown as current prices. `batch_id` groups one import so a
+// re-import replaces the previous list atomically. Tenant is a by-value
+// `client_id` scalar, same doctrine as every other research table.
+model ManualPriceEntry {
+  id           String   @id @default(uuid())
+  clientId     String   @map("client_id")
+  sourceId     String   @map("source_id")
+  batchId      String   @map("batch_id")
+  supplierName String   @map("supplier_name")
+  title        String
+  brand        String?
+  ean          String?
+  packQuantity Int?     @map("pack_quantity")
+  priceCents   Int      @map("price_cents")
+  currency     String   @default("BRL")
+  url          String?
+  availability String?
+  etaDays      Int?     @map("eta_days")
+  validUntil   DateTime @map("valid_until")
+  createdAt    DateTime @default(now()) @map("created_at")
+
+  source PriceSource @relation(fields: [sourceId], references: [id], onDelete: Cascade)
+
+  @@index([clientId, sourceId, validUntil])
+  @@map("manual_price_entries")
+}

package/prisma/schema/schema.prisma

@@ -0,0 +1,19 @@
+// Host schema root for @12-apps/shared-helpers.
+//
+// Datasource + generator ONLY — this package deliberately owns no domain
+// models. The app's models live in the consuming application's own schema
+// folder; what lands here besides this file are the model PARTIALS owned by the
+// plugin packages in this repo, copied in by scripts/sync-*-schema.mjs.
+//
+// That is the whole plug-and-play contract: a host adopts a plugin by running
+// the same sync step against its own schema folder, and generates a client that
+// knows the plugin's models without hand-copying them. Generating here with no
+// domain models is what a fresh consumer gets before adding their own.
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+}

package/prisma/schema/shift.prisma

@@ -0,0 +1,34 @@
+// @12-apps/shift — canonical host-agnostic Prisma partial.
+//
+// Tenant, user and resource-assignment identifiers are stored by value so the
+// package does not depend on host model names. The package migration adds the
+// host's PostgreSQL CHECK/partial-index guarantees that Prisma cannot express.
+model Shift {
+  id                   String    @id @default(uuid())
+  clientId             String    @map("client_id")
+  userId               String    @map("user_id")
+  kind                 String
+  startedAt            DateTime  @default(now()) @map("started_at")
+  endedAt              DateTime? @map("ended_at")
+  endedReason          String?   @map("ended_reason")
+  endedByUserId        String?   @map("ended_by_user_id")
+  resourceAssignmentId String?   @unique @map("resource_assignment_id")
+  // Immutable snapshots retain the resource identity even if a generic
+  // ResourceAssignment is later removed with its host user or tenant.
+  resourceType         String?   @map("resource_type")
+  resourceId           String?   @map("resource_id")
+
+  @@index([clientId, endedAt])
+  @@index([clientId, userId, startedAt])
+  @@map("shifts")
+}
+
+// Optional per-tenant override. No row means the package default (16 hours);
+// materialising a row also defaults to 16, keeping host reads simple.
+model ShiftTenantConfig {
+  clientId      String   @id @map("client_id")
+  autoCloseHours Int     @default(16) @map("auto_close_hours")
+  updatedAt     DateTime @updatedAt @map("updated_at")
+
+  @@map("shift_tenant_configs")
+}

package/src/actor-context.ts

@@ -0,0 +1,218 @@
+/**
+ * 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.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/** 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;
+}
+
+// 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>;
+};
+
+const store = (): AsyncLocalStorage<ActorContext> =>
+  (globalStore.__futurePayActorStore ??= new AsyncLocalStorage<ActorContext>());
+
+/**
+ * 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: string, onBehalfOfUserId: string | null): string | null =>
+  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: string, attribution: ActorAttribution): ActorContext => ({
+  userId,
+  ...attribution,
+  ...(attribution.onBehalfOfUserId !== undefined
+    ? { realUserId: realActorFor(userId, attribution.onBehalfOfUserId) }
+    : {}),
+});
+
+/** Run `fn` with `userId` as the current actor. Nested calls override. */
+export const runWithActor = <T>(
+  userId: string,
+  fn: () => T,
+  attribution: ActorAttribution = {},
+): T => store().run(freshContext(userId, attribution), fn);
+
+/**
+ * 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 const runWithActorScope = <T>(fn: () => T): T =>
+  store().run({ userId: "" }, fn);
+
+/**
+ * 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 const setActor = (
+  userId: string,
+  attribution: ActorAttribution = {},
+): void => {
+  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));
+};
+
+/** The current actor's `users.id`, or undefined when no actor is set. */
+export const getActorUserId = (): string | undefined =>
+  store().getStore()?.userId || 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 const getActorAttribution = (): ActorAttributionSnapshot => {
+  const context = store().getStore();
+  return {
+    role: context?.role,
+    scope: context?.scope,
+    onBehalfOfUserId: context?.onBehalfOfUserId,
+    realUserId: context?.realUserId,
+  };
+};