create-ailk 0.24.0 → 0.25.1

package/templates/apps/api/src/services/audit-log.ts

@@ -1,961 +0,0 @@
-/**
- * @file audit-log.ts
- * @description The audit writer (#6040, REL-017 row 5 / FEAT-084 SUB-096;
- * reshaped by #3591 D8) — `recordAuditAction`, the one production write site
- * for `ops.AuditLog`. Writes exactly one row per audited action: tenant,
- * actor, action, and outcome, with personal data redacted before it can
- * reach the stored row.
- *
- * ## WHO ACTED
- *
- * The caller names the actor: a person (`actorType: "user"`, `actorId` their
- * user id), or an agent acting on behalf of a person (`actorType: "agent"`,
- * `actorId` the agent's id, `metadata.onBehalfOf` the person's user id). The
- * `action` column is `<domain>.<tool>` — `inbox.accept_message`,
- * `magnets.magnet.create` — and never says who acted; that is the
- * `actorType` column's job.
- *
- * ## AUDIT FAILURE DOES NOT BLOCK THE AUDITED ACTION
- *
- * A failed write is reported to the caller and logged at `error`; it never
- * throws and never aborts the caller's action. At MVP the audited action is
- * frequently already irreversible by the time this writer runs — a Stripe
- * refund has been issued, a price has changed — so aborting the caller's
- * request after the money moved would make the site lie to its operator
- * about what happened. The compensating control is that the failure is
- * loud: a typed `{ ok: false }` the caller can branch on, plus a
- * `logger.error` line. Nothing in TypeScript FORCES a caller to read the
- * result — `await recordAuditAction(input)` as a bare statement compiles
- * and lints clean — so the caller issue (#6041 or SUB-097) owns branching on
- * `ok` and raising its own alert; a lint/metric enforcing that belongs to
- * whichever issue adds the first caller.
- *
- * ## WHY THIS FILE CARRIES NO `architecture.yaml` EXCEPTION
- *
- * `architecture.yaml`'s tenant-scope `forbidden_pattern` protects against ONE
- * failure mode: an UN-SCOPED read of a listed tenancy/domain model — this
- * one included — that could enumerate or leak another tenant's rows. This
- * file does not have that failure mode, by construction rather than by
- * convention: its write delegate (`AuditWriteClient`, below) declares only
- * `create` — no `find*`/`update`/`delete`/`count` — so a read of this model
- * is a COMPILE ERROR here, not a review catch. Every write goes through that
- * delegate (`db.auditLog.create`), never the raw singleton directly, which
- * is WHY it also satisfies the rule MECHANICALLY (the pattern is a raw-text
- * scan over the whole file, comments included — so this paragraph is
- * deliberately worded to describe the shape without ever writing the literal
- * banned call adjacency itself) — the mechanical pass is a consequence of
- * meeting the rule's intent, not a way around it. No `paths_excluded` entry
- * was added for it (a draft of this design proposed one; it was withdrawn):
- * that list is a capability allow-list under the `security_settings` hard
- * floor, and this file does not need to widen it. If a later change ever
- * inlines a direct singleton call for this model, the lint goes red on this
- * file and a human looks — which is the intended outcome, since that change
- * would be the first one actually capable of the failure mode the rule
- * guards against.
- *
- * ## THE WRITER CANNOT VERIFY TENANT OWNERSHIP
- *
- * `tenant` is the full `TenantContext` (never a `Pick`) so a caller must at
- * least have *constructed* a resolved-context-shaped value, and
- * `workspaceId` is format-validated against `zWorkspaceId` at runtime. But
- * an `Id<E>`'s brand is compile-time only — at runtime an id is a plain
- * string — so this writer cannot and does not verify that the actor
- * genuinely belongs to the workspace it is told. `tenant` MUST come from
- * `resolveActiveTenant` (multi-tenant) or `resolveDefaultTenant` /
- * `resolveDefaultTenantForOperator` (base) — never assembled from request
- * input. That is a caller obligation this file cannot enforce.
- *
- * ## NOT GATED ON THE `commerce` LICENSE CLAIM
- *
- * An audit writer a license read can switch off is not an audit writer:
- * there is no state in which the right answer to "should this write
- * happen?" is "no." Gating stays upstream, at the caller's own
- * `require-commerce-claim.ts` check.
- *
- * External dependency boundaries: `@working-theory/observability` (logger +
- * `redactHighEntropy`); `@working-theory/ids` (id format validation +
- * the entity registry); `node:crypto` (the id digest); `../lib/prisma.js`
- * (the default write delegate, structurally satisfied via `AuditWriteClient`
- * — a caller may inject its own, e.g. an interactive `$transaction` client).
- */
-
-import { createHash, randomUUID } from "node:crypto";
-
-import type { Prisma } from "@working-theory/database";
-import {
-  ENTITIES,
-  idRegex,
-  zAuditLogId,
-  zWorkspaceId,
-  type Entity,
-  type Id,
-} from "@working-theory/ids";
-import { logger, redactHighEntropy } from "@working-theory/observability";
-
-import { prisma } from "../lib/prisma.js";
-
-import { isUniqueViolation, type TenantContext } from "./default-tenant.js";
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-/** The full actor-kind vocabulary the model comments (not a DB CHECK). This
- * file writes `"user"` and `"agent"` (#3591 D8), and `"system"` for Stripe's
- * payment outcome (#8516 D14, `recordWorkspaceAuditAction`). */
-export type AuditActorType = "user" | "agent" | "system";
-
-/**
- * Who acted (#3591 D8) — the same shape as `request.actor`
- * (`middleware/auth.ts`'s `RequestActor`), so a route passes it through.
- */
-export type AuditActor =
-  | { type: "user"; userId: Id<"user"> }
-  | { type: "agent"; agentId: Id<"agent">; onBehalfOfUserId: Id<"user"> };
-
-export type AuditActionOutcome =
-  "succeeded" | "failed" | "refused" | "awaiting_approval";
-
-/** One row as this writer assembles it — never re-exported; a caller sees
- * only the input/output shapes below. */
-/** `metadata`'s closed, versioned shape (D9) — declared with concrete scalar
- * value types (never `Record<string, unknown>`) so it structurally satisfies
- * Prisma's `InputJsonValue` under `exactOptionalPropertyTypes` — an
- * `unknown`-valued record does not. */
-interface AuditLogMetadata {
-  v: 2;
-  outcome: AuditActionOutcome;
-  tool: string;
-  idempotencyKey: string;
-  /** The person an agent acted for (#3591 D8) — present only on an agent row. */
-  onBehalfOf?: string;
-  summary?: string;
-  failureReason?: string;
-}
-
-interface AuditLogRow {
-  id: string;
-  workspaceId: string;
-  actorId: string;
-  actorType: AuditActorType;
-  action: string;
-  targetType?: string;
-  targetId?: string;
-  /** `AuditLogMetadata`'s shape, cast at the call site — Prisma's generated
-   * `InputJsonObject` requires a `[key: string]: InputJsonValue` index
-   * signature a named interface does not structurally carry. */
-  metadata: Prisma.InputJsonValue;
-}
-
-/**
- * The one delegate this module writes through — deliberately narrower than
- * `PrismaClient["auditLog"]`: it declares ONLY `create`, so a read (which
- * would defeat the "cannot leak one tenant's rows to another" property) is a
- * compile error, not a review catch. The real `prisma` singleton satisfies
- * this structurally (checked by `pnpm type-check`); a caller running inside
- * an interactive `$transaction` may pass its `tx` client instead, so the
- * audit row can land in the SAME transaction as the action it records.
- */
-export interface AuditWriteClient {
-  auditLog: {
-    create(args: { data: AuditLogRow }): Promise<{ id: string }>;
-  };
-}
-
-/**
- * Every string member is charset- and length-constrained. A value outside
- * its constraint is an `invalid_input` refusal, never a truncation or a
- * silent coercion — a coerced audit row is a wrong audit row.
- */
-export interface RecordAuditActionInput {
-  /** MUST come from `resolveActiveTenant` / `resolveDefaultTenant` — never
-   * assembled from request input. See the file docblock. */
-  tenant: TenantContext;
-  /** Who acted — `request.actor`. Each id it carries is <=128 chars,
-   * `/^[A-Za-z0-9_:.-]+$/`, then personal-data-scanned unless it is a
-   * registry-minted `user_` or `agent_` id. */
-  actor: AuditActor;
-  /** <=32 chars, `/^[a-z][a-z0-9_]*$/` — the area the action belongs to
-   * (`"inbox"`, `"magnets"`, `"scheduling"`), the first segment of
-   * `action`. */
-  domain: string;
-  /** <=64 chars, `/^[a-z0-9_.-]+$/` — an identifier, so `action` cannot
-   * carry prose. */
-  tool: string;
-  outcome: AuditActionOutcome;
-  /** <=256 chars, `/^[A-Za-z0-9_:.-]+$/`, then personal-data-scanned.
-   * REQUIRED — an optional key would silently degrade to "no dedup" for a
-   * caller who forgets it. Stable across a replay of the same logical
-   * action (the MCP request/tool-call id, or the provider event id).
-   *
-   * MUST be process-INDEPENDENT (#6231): a value unique to one logical
-   * action across every instance, such as a client-supplied idempotency
-   * header, a provider event id, or a fresh `crypto.randomUUID()`. Never
-   * Fastify's default `request.id` — `req-<base36>` is a per-process
-   * counter that restarts at `req-1` on every fresh serverless instance,
-   * so two genuine actions on two instances can share a key. Since
-   * `deriveAuditRowId` digests every field the row carries and a caller's
-   * other digest inputs are typically constant, a shared key makes the
-   * SECOND genuine action collide on the primary key and be reported
-   * `duplicate` — a real action left unaudited. */
-  idempotencyKey: string;
-  /** <=2000 chars, NFKC-normalised, entropy- and personal-data-scanned. */
-  summary?: string;
-  /** <=2000 chars, same treatment. Provider error text lands here — hence
-   * the entropy scan (a live secret is more likely to arrive here than in
-   * `summary`). */
-  failureReason?: string;
-  /** <=32 chars, `/^[a-z][a-z0-9_]*$/`. */
-  targetType?: string;
-  /** <=128 chars; `zId`-validated against the entity registry when
-   * `targetType` names a known entity, else a generic identifier charset. */
-  targetId?: string;
-}
-
-/** Every member of a row's input but who and where — shared by both writers. */
-type AuditRowInput = Omit<RecordAuditActionInput, "tenant" | "actor">;
-
-/** Every actor a row can name: a tenant caller's, or a tenant-less one's (D14). */
-type WriterActor = AuditActor | { type: "system"; systemId: "stripe" };
-
-export type RecordAuditActionResult =
-  | { ok: true; outcome: "recorded" | "duplicate"; id: Id<"auditLog"> }
-  | {
-      ok: false;
-      error: {
-        kind: "invalid_input" | "write_failed";
-        message: string;
-        /** ALWAYS false — one insert, no transaction, nothing partial to
-         * leave behind. */
-        persisted: false;
-      };
-    };
-
-/**
- * The fields `deriveAuditRowId` digests, in the ONE fixed order used by
- * every caller — every field the row will carry, so pre-empting a row
- * requires writing a byte-identical one (D8). `summary` / `failureReason`
- * here are the POST-REDACTION values (what will actually be stored);
- * `idempotencyKey` is the RAW caller-supplied value, so a replay under the
- * same key always digests identically regardless of any future redaction
- * change.
- */
-export interface AuditRowDigestInput {
-  workspaceId: string;
-  actorId: string;
-  actorType: AuditActorType;
-  onBehalfOf: string | undefined;
-  action: string;
-  targetType: string | undefined;
-  targetId: string | undefined;
-  outcome: AuditActionOutcome;
-  summary: string | undefined;
-  failureReason: string | undefined;
-  idempotencyKey: string;
-}
-
-// ─── Constants ──────────────────────────────────────────────────────────────
-
-/** The free-text cap (`summary` / `failureReason`) — bounds both the stored
- * row and the redaction scan's regex work. Rejected above it, not
- * truncated. */
-const MAX_TEXT = 2_000;
-
-/** An MCP tool name is an identifier — this charset cannot express an `@`,
- * and it bounds the `action` column (`domain + "." + tool`). */
-const TOOL_RE = /^[a-z0-9_.-]{1,64}$/;
-
-/** The action's first segment — `"inbox"`, `"magnets"`, `"scheduling"`. */
-const DOMAIN_RE = /^[a-z][a-z0-9_]{0,31}$/;
-
-/** The schema's own examples are `"workspace"`, `"lead"`, `"user"`. */
-const TARGET_TYPE_RE = /^[a-z][a-z0-9_]{0,31}$/;
-
-/** An actor id's shape is open (Q2) — any identifier, registry-minted or not. */
-const ACTOR_ID_RE = /^[A-Za-z0-9_:.-]{1,128}$/;
-
-/** `targetId` when `targetType` does not name a known registry entity. */
-const TARGET_ID_FALLBACK_RE = /^[A-Za-z0-9_:-]{1,128}$/;
-
-/** The MCP request/tool-call id or provider event id — an identifier, not
- * prose. */
-const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9_:.-]{1,256}$/;
-
-/** NUL and the rest of the C0 control range. Postgres `text` cannot store
- * U+0000 — an unvalidated NUL anywhere in a free-text member is a
- * repeatable audit-disable switch under the fail-open policy above. */
-// eslint-disable-next-line no-control-regex -- the control-character range is exactly what F9 must detect and refuse (a NUL in `text` fails every Postgres insert).
-const C0_CONTROL_RE = /[\x00-\x1f]/;
-
-/**
- * Email — RFC-ish local + domain, no nested quantifier. The domain segment
- * is a negated class (`[^\s@]`, not `[A-Za-z0-9.-]`) so an
- * internationalised/homoglyph domain is still bounded and redacted rather
- * than silently admitted past the pattern.
- */
-const EMAIL_RE = /[^\s@]{1,64}@[^\s@]{1,255}\.[A-Za-z]{2,24}/g;
-
-/**
- * International phone — an optional leading `+`, then 7-15 digits with
- * optional space/dot/dash separators between them. No separator is also
- * accepted (a bare digit run), which is deliberate belt-and-braces: it also
- * catches a phone number typed with no separators at all.
- */
-const PHONE_RE = /\+?\d(?:[ .-]?\d){6,14}/g;
-
-/** Long digit runs (9+) — account- and card-shaped numbers not already
- * caught by the phone pattern (its separators are optional, so most digit
- * runs are already consumed above; this is the residual). */
-const LONG_DIGIT_RUN_RE = /\d{9,}/g;
-
-/**
- * Where free text splits into tokens for the registry-id exemption below:
- * whitespace and `=` (so `responsibleUserId=<id>` holds the id as a token).
- */
-const FREE_TEXT_TOKEN_SEPARATOR_RE = /(\s+|=)/;
-
-/**
- * Whether a free-text token is EXACTLY a registry-minted `user_` or `agent_`
- * id (#3591 D8) — the same anchored pattern `actorIdRefusal` exempts. Such an
- * id's hex can hold a digit run the phone pattern flags (about one id in
- * three), which would turn a `summary` that names a person by id — the agent
- * lifecycle rows' "for whom" — into `[REDACTED:phone]`. A token that merely
- * contains one, or only looks like one, is scanned like any other text.
- */
-function isRegistryActorId(token: string): boolean {
-  return idRegex("user").test(token) || idRegex("agent").test(token);
-}
-
-const EMAIL_MARKER = "[REDACTED:email]";
-const PHONE_MARKER = "[REDACTED:phone]";
-const NUMBER_MARKER = "[REDACTED:number]";
-
-// ─── Pure helpers (D1 — directly unit-testable, no database) ───────────────
-
-/** True when `value` names a registered `packages/ids` entity — the branch
- * that lets `targetId` be validated against the entity's own id grammar
- * rather than the generic fallback. */
-function isKnownEntity(value: string): value is Entity {
-  return (ENTITIES as readonly string[]).includes(value);
-}
-
-/**
- * Redacts personal data from a free-text value: caps (the CALLER enforces
- * the cap as a rejection — this function assumes an already-capped input),
- * NFKC-normalises (so a full-width or other compatibility form does not
- * walk past a pattern that would catch its canonical twin), runs
- * `redactHighEntropy` first (catches a live secret pasted into
- * `failureReason` — the natural home for provider error text), then applies
- * the three anchored, bounded personal-data patterns. Exported — directly
- * unit-testable, and reused (as a detection predicate) for the actor's ids
- * and `idempotencyKey` below.
- *
- * What this does NOT catch, stated rather than implied: a postal address or
- * a personal name in free text (no achievable regex exists across locales),
- * an obfuscated address ("jane dot doe at example dot com"), a date of
- * birth, or a national identifier. The allow-list (this file's input type
- * has no member whose purpose is a buyer's identity) and the charset
- * constraints below are the guarantee; this scan is defence-in-depth over
- * the two members that must stay free text.
- */
-export function redactPersonalData(text: string): string {
-  let out = text.normalize("NFKC");
-  out = redactHighEntropy(out);
-  out = out.replace(EMAIL_RE, EMAIL_MARKER);
-  // Long-digit-run BEFORE phone, deliberately: its unbounded `{9,}` consumes
-  // an arbitrarily-long unseparated digit run (a card/account number) in ONE
-  // match, whereas the phone pattern's bounded `{6,14}` would otherwise eat
-  // only the first 15 digits of a longer run and leave a ragged remainder.
-  // A phone number written WITH separators (spaces/dots/dashes) has no
-  // contiguous 9+ digit substring, so this pass never touches it.
-  out = out.replace(LONG_DIGIT_RUN_RE, NUMBER_MARKER);
-  out = out.replace(PHONE_RE, PHONE_MARKER);
-  return out;
-}
-
-/**
- * `summary` / `failureReason`'s redaction: `redactPersonalData`, except that a
- * token which is exactly a registry `user_` / `agent_` id is kept whole (see
- * `isRegistryActorId`). The text between such tokens is scanned as ONE run,
- * separators included, so a phone number written with spaces is still caught.
- * Identifier fields are not routed here — an actor id has its own exemption,
- * and `idempotencyKey` stays scanned.
- */
-function redactFreeText(text: string): string {
-  let out = "";
-  let run = "";
-  for (const part of text.normalize("NFKC").split(FREE_TEXT_TOKEN_SEPARATOR_RE)) {
-    if (isRegistryActorId(part)) {
-      out += redactPersonalData(run) + part;
-      run = "";
-    } else {
-      run += part;
-    }
-  }
-  return out + redactPersonalData(run);
-}
-
-/** True when `redactPersonalData` would change `text` — used to REFUSE
- * (never silently rewrite) an identifier-shaped field that happens to
- * contain a personal-data-shaped substring (an actor id, `idempotencyKey`). */
-function personalDataDetected(text: string): boolean {
-  // Checked by MARKER PRESENCE, not by inequality against the input — an
-  // inequality check is a call-order-dependent accident: NFKC alone can
-  // change a string with no personal data present (a full-width form
-  // folding to its ASCII twin) with nothing to redact, and that must never
-  // read as "detected" regardless of what charset check a future caller
-  // does or doesn't run first (code review, #6040).
-  const redacted = redactPersonalData(text);
-  return (
-    redacted.includes(EMAIL_MARKER) ||
-    redacted.includes(PHONE_MARKER) ||
-    redacted.includes(NUMBER_MARKER)
-  );
-}
-
-/**
- * Derives the row's primary key deterministically from every field the row
- * will carry (D8) — the mechanism that makes AC-4 (replay produces no
- * duplicate) hold on a table whose only unique constraint is its primary
- * key. Each field is encoded as a 1-byte presence flag, then (when present)
- * a 4-byte big-endian UTF-8 byte length, then the UTF-8 bytes themselves —
- * length-PREFIXED, not separator-delimited, so no component boundary is
- * expressible inside a component (a `tool`/`idempotencyKey` pair that
- * shifts content across the two fields' boundary digests differently,
- * because the length prefixes differ).
- *
- * The sha256 digest's first 16 bytes become a uuid with the version nibble
- * forced to `7` and the variant nibble forced to `8`, satisfying the
- * `audit_logs_id_format` DB CHECK constraint
- * (`database/migrations/20260713192429_prefixed_uuid_entity_ids/migration.sql:158`)
- * and `zAuditLogId`. `createdAt` is deliberately NOT a digest input (nor an
- * insert column — the database clock supplies it) — including it would make
- * every call mint a fresh id and destroy replay detection entirely.
- *
- * Widening the digest to the WHOLE row (rather than a caller-controlled
- * subset) is what defeats an agent pre-writing a harmless decoy to suppress
- * its real action's record: pre-empting a row now requires writing one with
- * byte-identical content, which means the correct record already exists.
- */
-export function deriveAuditRowId(input: AuditRowDigestInput): string {
-  const parts: Array<string | undefined> = [
-    input.workspaceId,
-    input.actorId,
-    input.actorType,
-    input.onBehalfOf,
-    input.action,
-    input.targetType,
-    input.targetId,
-    input.outcome,
-    input.summary,
-    input.failureReason,
-    input.idempotencyKey,
-  ];
-  const encoded = Buffer.concat(parts.map(encodeDigestField));
-  const digest = createHash("sha256").update(encoded).digest();
-  const bytes = Buffer.from(digest.subarray(0, 16));
-  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x70; // version 7
-  bytes[8] = ((bytes[8] ?? 0) & 0x0f) | 0x80; // variant 8 (satisfies the [89ab] CHECK)
-  const hex = bytes.toString("hex");
-  const uuid = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-  return `audit_${uuid}`;
-}
-
-/** One digest component: a 1-byte presence flag, then (when present) a
- * fixed-width 4-byte length prefix plus the UTF-8 bytes. `undefined` is
- * encoded distinctly from an empty string. */
-function encodeDigestField(value: string | undefined): Buffer {
-  if (value === undefined) {
-    return Buffer.from([0]);
-  }
-  const bytes = Buffer.from(value, "utf8");
-  const length = Buffer.alloc(4);
-  length.writeUInt32BE(bytes.length, 0);
-  return Buffer.concat([Buffer.from([1]), length, bytes]);
-}
-
-/** `error.code` / `error.constructor.name` only — never the message, which
- * on this writer embeds the audit row itself (`summary`, `actorId`,
- * `targetId`, `idempotencyKey`) via Prisma's validation-error `data`
- * argument (N7, D10). */
-function classifyError(error: unknown): { code: string; name: string } {
-  const code =
-    typeof error === "object" &&
-    error !== null &&
-    "code" in error &&
-    typeof (error as { code?: unknown }).code === "string"
-      ? (error as { code: string }).code
-      : "unknown";
-  const name = error instanceof Error ? error.constructor.name : typeof error;
-  return { code, name };
-}
-
-// ─── Input validation ───────────────────────────────────────────────────────
-
-interface ValidatedFields {
-  workspaceId: string;
-  actorId: string;
-  actorType: AuditActorType;
-  onBehalfOf: string | undefined;
-  tool: string;
-  targetType: string | undefined;
-  targetId: string | undefined;
-  redactedSummary: string | undefined;
-  redactedFailureReason: string | undefined;
-}
-
-type ValidationResult =
-  { ok: true; value: ValidatedFields } | { ok: false; message: string };
-
-/** Caps first (rejected, not truncated), then rejects a NUL or other C0
- * control character (F9 — Postgres `text` cannot store U+0000), then
- * redacts. Absent input passes through as `undefined`. */
-function validateFreeText(
-  text: string | undefined,
-): { ok: true; value: string | undefined } | { ok: false; message: string } {
-  if (text === undefined) {
-    return { ok: true, value: undefined };
-  }
-  if (text.length > MAX_TEXT) {
-    return { ok: false, message: `exceeds the ${MAX_TEXT}-character cap` };
-  }
-  if (C0_CONTROL_RE.test(text)) {
-    return {
-      ok: false,
-      message: "contains a NUL or other C0 control character",
-    };
-  }
-  return { ok: true, value: redactFreeText(text) };
-}
-
-/**
- * An actor's id: the identifier grammar, then the personal-data scan — except
- * for a registry-minted `user_` or `agent_` id, which is an identifier, not
- * personal data. Its hex can still hold a digit run the phone pattern flags
- * (about one id in three), which silently dropped real actors' rows (#7636
- * D7, security review finding 1; #3591 D8). Every other id is still scanned.
- * Returns the refusal message, or `undefined` when the id is admitted.
- */
-function actorIdRefusal(id: string, field: string): string | undefined {
-  if (!ACTOR_ID_RE.test(id)) {
-    return `${field} does not match the required identifier grammar`;
-  }
-  const registryId = idRegex("user").test(id) || idRegex("agent").test(id);
-  if (!registryId && personalDataDetected(id)) {
-    return `${field} appears to carry personal data`;
-  }
-  return undefined;
-}
-
-/**
- * Validates every string member before it is digested or written (F9).
- * Identifier-shaped members are REFUSED on a constraint violation, never
- * coerced — a coerced audit row is a wrong audit row (D5). The actor's ids
- * and `idempotencyKey` additionally fail the personal-data scan as a REFUSAL
- * (never a silent rewrite of an identifier field) rather than as a
- * redaction, unlike `summary` / `failureReason`.
- */
-function validateInput(
-  workspaceId: string,
-  workspaceField: string,
-  actor: WriterActor,
-  input: AuditRowInput,
-): ValidationResult {
-  if (!zWorkspaceId.safeParse(workspaceId).success) {
-    return {
-      ok: false,
-      message: `${workspaceField} is not a valid workspace id`,
-    };
-  }
-  const actorId =
-    actor.type === "agent"
-      ? actor.agentId
-      : actor.type === "system"
-        ? actor.systemId
-        : actor.userId;
-  const actorRefusal = actorIdRefusal(actorId, "actorId");
-  if (actorRefusal !== undefined) {
-    return { ok: false, message: actorRefusal };
-  }
-  const onBehalfOf = actor.type === "agent" ? actor.onBehalfOfUserId : undefined;
-  if (onBehalfOf !== undefined) {
-    const onBehalfOfRefusal = actorIdRefusal(onBehalfOf, "onBehalfOf");
-    if (onBehalfOfRefusal !== undefined) {
-      return { ok: false, message: onBehalfOfRefusal };
-    }
-  }
-  if (!DOMAIN_RE.test(input.domain)) {
-    return {
-      ok: false,
-      message: "domain does not match the required identifier grammar",
-    };
-  }
-  if (!TOOL_RE.test(input.tool)) {
-    return {
-      ok: false,
-      message: "tool does not match the required identifier grammar",
-    };
-  }
-  if (!IDEMPOTENCY_KEY_RE.test(input.idempotencyKey)) {
-    return {
-      ok: false,
-      message: "idempotencyKey does not match the required identifier grammar",
-    };
-  }
-  if (personalDataDetected(input.idempotencyKey)) {
-    return {
-      ok: false,
-      message: "idempotencyKey appears to carry personal data",
-    };
-  }
-  if (
-    input.targetType !== undefined &&
-    !TARGET_TYPE_RE.test(input.targetType)
-  ) {
-    return {
-      ok: false,
-      message: "targetType does not match the required identifier grammar",
-    };
-  }
-  if (input.targetId !== undefined) {
-    const targetIdRe =
-      input.targetType !== undefined && isKnownEntity(input.targetType)
-        ? idRegex(input.targetType)
-        : TARGET_ID_FALLBACK_RE;
-    if (!targetIdRe.test(input.targetId)) {
-      return {
-        ok: false,
-        message:
-          "targetId does not match the required grammar for its targetType",
-      };
-    }
-  }
-  const summaryCheck = validateFreeText(input.summary);
-  if (!summaryCheck.ok) {
-    return { ok: false, message: `summary ${summaryCheck.message}` };
-  }
-  const failureReasonCheck = validateFreeText(input.failureReason);
-  if (!failureReasonCheck.ok) {
-    return {
-      ok: false,
-      message: `failureReason ${failureReasonCheck.message}`,
-    };
-  }
-
-  return {
-    ok: true,
-    value: {
-      workspaceId,
-      actorId,
-      actorType: actor.type,
-      onBehalfOf,
-      tool: input.tool,
-      targetType: input.targetType,
-      targetId: input.targetId,
-      redactedSummary: summaryCheck.value,
-      redactedFailureReason: failureReasonCheck.value,
-    },
-  };
-}
-
-/**
- * One fresh, process-independent audit idempotency key (#6231; moved here
- * from `routes/magnets/index.ts` so every route writer shares it, #7636): a
- * `crypto.randomUUID()` with its dashes removed and its 32 hex characters
- * regrouped into runs of six joined by `_` (e.g.
- * `e4a940_bf8d33_4c2281_4b1b27_4461cd_19`).
- *
- * The regrouping is load-bearing, not cosmetic. `recordAuditAction` REFUSES
- * an `idempotencyKey` its personal-data scan flags — a refusal writes no row
- * at all — and that scan's phone pattern treats `-` as a digit separator,
- * so a raw dashed uuid whose hex happens to be digit-heavy reads as a phone
- * number: measured over 200k uuids, 37% are refused. `_` is not one of that
- * pattern's separators (and is inside the key's allowed charset), so
- * grouping caps every digit run at six — under the phone pattern's 7-digit
- * floor and the long-digit-run pattern's 9 — and no generated key can be
- * refused. Entropy is untouched: the same 128 bits, re-spelled.
- */
-export function freshAuditIdempotencyKey(): string {
-  return randomUUID().replace(/-/g, "").replace(/(.{6})(?=.)/g, "$1_");
-}
-
-// ─── The writer ─────────────────────────────────────────────────────────────
-
-/**
- * Writes exactly one `audit_logs` row for one audited action. Never throws;
- * never blocks the caller's action (see the file docblock heading). Not
- * gated on the `commerce` license claim (see the file docblock) — gating
- * stays upstream, at the caller's own claim check.
- */
-export async function recordAuditAction(
-  input: RecordAuditActionInput,
-  db: AuditWriteClient = prisma,
-): Promise<RecordAuditActionResult> {
-  const { tenant, actor, ...row } = input;
-  return writeAuditRow(tenant.workspaceId, "tenant.workspaceId", actor, row, db);
-}
-
-/**
- * Who acted on a tenant-less row (#8516 D14): a client — a signed-in person
- * with no membership — or Stripe itself, reporting a payment outcome.
- */
-export type WorkspaceAuditActor =
-  | { type: "user"; userId: Id<"user"> }
-  | { type: "system"; systemId: "stripe" };
-
-/** `recordWorkspaceAuditAction`'s input: a workspace id in place of a tenant. */
-export type RecordWorkspaceAuditActionInput = AuditRowInput & {
-  workspaceId: string;
-  actor: WorkspaceAuditActor;
-};
-
-/**
- * One `audit_logs` row for a caller that holds no `TenantContext` (#8516
- * D14): a client acting in the member area, or a Stripe webhook. Writes the
- * row `recordAuditAction` would for the same workspace and user actor; the
- * system actor stores `actor_type` `system` and `actor_id` `stripe`. Never
- * throws; never blocks the caller's action.
- *
- * CALLER OBLIGATION — `workspaceId` MUST come from `resolveMember`'s
- * resolved workspace, or from a Stripe-signed event's server-written
- * metadata matched to a stored row — NEVER from request input. A client
- * actor's row says so in its `tool` and summary (`by: "client"`), so it is
- * never read as a staff member's action.
- */
-export async function recordWorkspaceAuditAction(
-  input: RecordWorkspaceAuditActionInput,
-  db: AuditWriteClient = prisma,
-): Promise<RecordAuditActionResult> {
-  const { workspaceId, actor, ...row } = input;
-  return writeAuditRow(workspaceId, "workspaceId", actor, row, db);
-}
-
-/** The body of both writers: one validated, digested, idempotent insert. */
-async function writeAuditRow(
-  workspaceIdInput: string,
-  workspaceField: string,
-  actor: WriterActor,
-  input: AuditRowInput,
-  db: AuditWriteClient,
-): Promise<RecordAuditActionResult> {
-  const validated = validateInput(workspaceIdInput, workspaceField, actor, input);
-  if (!validated.ok) {
-    return {
-      ok: false,
-      error: {
-        kind: "invalid_input",
-        message: validated.message,
-        persisted: false,
-      },
-    };
-  }
-
-  const {
-    workspaceId,
-    actorId,
-    actorType,
-    onBehalfOf,
-    tool,
-    targetType,
-    targetId,
-    redactedSummary,
-    redactedFailureReason,
-  } = validated.value;
-  const action = `${input.domain}.${tool}`;
-
-  const id = deriveAuditRowId({
-    workspaceId,
-    actorId,
-    actorType,
-    onBehalfOf,
-    action,
-    targetType,
-    targetId,
-    outcome: input.outcome,
-    summary: redactedSummary,
-    failureReason: redactedFailureReason,
-    idempotencyKey: input.idempotencyKey,
-  });
-
-  if (!zAuditLogId.safeParse(id).success) {
-    // Structurally unreachable given the derivation above (sha256 digest,
-    // version/variant nibbles forced) — a defensive guard, never observed
-    // to fire, kept because the format authority stays in `packages/ids`
-    // even though the derivation lives here (D8).
-    logger.error(
-      { workspaceId, action, actorType },
-      "[audit-log] derived id failed format validation",
-    );
-    return {
-      ok: false,
-      error: {
-        kind: "write_failed",
-        message: "audit row write failed",
-        persisted: false,
-      },
-    };
-  }
-
-  const metadata: AuditLogMetadata = {
-    v: 2,
-    outcome: input.outcome,
-    tool,
-    idempotencyKey: input.idempotencyKey,
-    ...(onBehalfOf !== undefined && { onBehalfOf }),
-    ...(redactedSummary !== undefined && { summary: redactedSummary }),
-    ...(redactedFailureReason !== undefined && {
-      failureReason: redactedFailureReason,
-    }),
-  };
-
-  const row: AuditLogRow = {
-    id,
-    workspaceId,
-    actorId,
-    actorType,
-    action,
-    ...(targetType !== undefined && { targetType }),
-    ...(targetId !== undefined && { targetId }),
-
-    metadata: metadata as unknown as Prisma.InputJsonValue,
-  };
-
-  try {
-    // The delegate's resolved `{ id }` is discarded deliberately — the row's
-    // id is `id` above (the digest this writer derived), never a value the
-    // database could have generated differently (code review, #6040).
-    await db.auditLog.create({ data: row });
-    return { ok: true, outcome: "recorded", id: id as Id<"auditLog"> };
-  } catch (error) {
-    if (isUniqueViolation(error)) {
-      // F10 — a replay is reported, not silent. The colliding id IS the
-      // stored row's id (that is the whole point of a deterministic PK), so
-      // no read is needed to report it.
-      logger.warn(
-        { workspaceId, action, actorType, auditLogId: id },
-        "[audit-log] duplicate audit row suppressed by primary key",
-      );
-      return { ok: true, outcome: "duplicate", id: id as Id<"auditLog"> };
-    }
-    const { code, name } = classifyError(error);
-    // Never `error.message` — on this writer the Prisma validation `data`
-    // argument IS the audit row (N7, D10).
-    logger.error(
-      { workspaceId, action, actorType, errorCode: code, errorName: name },
-      "[audit-log] audit row write failed",
-    );
-    return {
-      ok: false,
-      error: {
-        kind: "write_failed",
-        message: "audit row write failed",
-        persisted: false,
-      },
-    };
-  }
-}
-
-// ─── Route helpers (#3591 D8) ───────────────────────────────────────────────
-
-/**
- * The actor a route records: `request.actor`, which the auth preHandler sets
- * on every authenticated request. A route reached without it (a harness that
- * seats `request.tenant` directly) is filed as the tenant's own person, with a
- * `warn` — an auth path that forgot to bind the actor must not pass silently.
- */
-export function auditActorFor(
-  actor: AuditActor | undefined,
-  tenant: TenantContext,
-): AuditActor {
-  if (actor) return actor;
-  logger.warn(
-    { workspaceId: tenant.workspaceId },
-    "[audit-log] no request actor; filing the tenant's person",
-  );
-  return { type: "user", userId: tenant.userId };
-}
-
-/** A service call's result, as far as the audit row needs it. */
-export type AuditedResult = { ok: true } | { ok: false; error: { kind: string } };
-
-/**
- * Who a route says acted, as far as `recordAgentWrite` reads it: the request
- * itself (`request.actor`, and `request.agent` on the agent path), or — the
- * older call shape — `request.actor` alone.
- */
-export type AgentWriteCaller =
-  | AuditActor
-  | undefined
-  | { actor?: AuditActor; agent?: { agentId: Id<"agent"> } };
-
-/**
- * #3591 D8 — one row for an agent's inbox write, recorded after the write
- * returns: `succeeded` when it did, else `failed` with the service's error
- * kind. A person's write records nothing (spec § 2.3: a person's inbox
- * actions are not audited). A failed audit write is logged at `error` once —
- * by the writer for a failed insert, here for a refused row — and returns
- * normally, so it never changes the caller's response.
- *
- * Pass the request, not `request.actor` alone, so an agent write cannot go
- * unrecorded in silence: a request with `request.agent` but no
- * `request.actor` (an auth path that forgot to bind the actor) is logged at
- * `error` and still recorded, from `request.agent`. Its person is
- * `tenant.userId`: on the agent path the tenant guard grants the workspace
- * through the agent's responsible membership, so the tenant's person IS the
- * person the agent acts for — read from the grant, not guessed.
- */
-export async function recordAgentWrite(
-  caller: AgentWriteCaller,
-  input: Omit<
-    RecordAuditActionInput,
-    "actor" | "outcome" | "failureReason" | "idempotencyKey"
-  >,
-  result: AuditedResult,
-  db: AuditWriteClient = prisma,
-): Promise<void> {
-  const actor = agentWriteActor(caller, input);
-  if (actor?.type !== "agent") return;
-  const audit = await recordAuditAction(
-    {
-      ...input,
-      actor,
-      idempotencyKey: freshAuditIdempotencyKey(),
-      ...(result.ok
-        ? { outcome: "succeeded" as const }
-        : { outcome: "failed" as const, failureReason: result.error.kind }),
-    },
-    db,
-  );
-  if (!audit.ok && audit.error.kind === "invalid_input") {
-    logger.error(
-      {
-        workspaceId: input.tenant.workspaceId,
-        action: `${input.domain}.${input.tool}`,
-        actorId: actor.agentId,
-        error: audit.error,
-      },
-      "[audit-log] agent write audit refused",
-    );
-  }
-}
-
-/** The actor `recordAgentWrite` files — see its docblock for the fallback. */
-function agentWriteActor(
-  caller: AgentWriteCaller,
-  input: { tenant: TenantContext; domain: string; tool: string },
-): AuditActor | undefined {
-  if (caller === undefined || "type" in caller) return caller;
-  if (caller.actor) return caller.actor;
-  if (!caller.agent) return undefined;
-  logger.error(
-    {
-      workspaceId: input.tenant.workspaceId,
-      action: `${input.domain}.${input.tool}`,
-      actorId: caller.agent.agentId,
-    },
-    "[audit-log] agent write without request.actor; recording from request.agent",
-  );
-  return {
-    type: "agent",
-    agentId: caller.agent.agentId,
-    onBehalfOfUserId: input.tenant.userId,
-  };
-}