create-ailk 0.5.0 → 0.6.0

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

@@ -0,0 +1,668 @@
+/**
+ * @file audit-log.ts
+ * @description The agent-action audit writer (#6040, REL-017 row 5 / FEAT-084
+ * SUB-096) — `recordAgentAction`, the first production write site for
+ * `ops.AuditLog`. Writes exactly one row per agent action: tenant, actor,
+ * tool, and outcome, with personal data redacted before it can reach the
+ * stored row.
+ *
+ * ## 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 recordAgentAction(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 } 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). Only
+ * `"agent"` is ever written by this file — `"user"`/`"system"` are exported
+ * so a future writer for those actors (#3591) shares one union. */
+export type AuditActorType = "user" | "agent" | "system";
+
+export type AgentActionOutcome =
+  "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: 1;
+  outcome: AgentActionOutcome;
+  tool: string;
+  idempotencyKey: 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 RecordAgentActionInput {
+  /** MUST come from `resolveActiveTenant` / `resolveDefaultTenant` — never
+   * assembled from request input. See the file docblock. */
+  tenant: TenantContext;
+  /** <=128 chars, `/^[A-Za-z0-9_:.-]+$/`, then personal-data-scanned. */
+  actorId: string;
+  /** <=64 chars, `/^[a-z0-9_.-]+$/` — an identifier, so `action` cannot
+   * carry prose. */
+  tool: string;
+  outcome: AgentActionOutcome;
+  /** <=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;
+}
+
+export type RecordAgentActionResult =
+  | { 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;
+  action: string;
+  targetType: string | undefined;
+  targetId: string | undefined;
+  outcome: AgentActionOutcome;
+  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 (`"agent.commerce." + tool`). */
+const TOOL_RE = /^[a-z0-9_.-]{1,64}$/;
+
+/** The schema's own examples are `"workspace"`, `"lead"`, `"user"`. */
+const TARGET_TYPE_RE = /^[a-z][a-z0-9_]{0,31}$/;
+
+/** `actorId`'s shape is open (Q2) — an opaque, non-registry identifier. */
+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;
+
+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 `actorId` 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;
+}
+
+/** 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 (`actorId`, `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.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;
+  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: redactPersonalData(text) };
+}
+
+/**
+ * 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). `actorId` 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(input: RecordAgentActionInput): ValidationResult {
+  if (!zWorkspaceId.safeParse(input.tenant.workspaceId).success) {
+    return {
+      ok: false,
+      message: "tenant.workspaceId is not a valid workspace id",
+    };
+  }
+  if (!ACTOR_ID_RE.test(input.actorId)) {
+    return {
+      ok: false,
+      message: "actorId does not match the required identifier grammar",
+    };
+  }
+  if (personalDataDetected(input.actorId)) {
+    return {
+      ok: false,
+      message: "actorId appears to carry personal data",
+    };
+  }
+  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: input.tenant.workspaceId,
+      actorId: input.actorId,
+      tool: input.tool,
+      targetType: input.targetType,
+      targetId: input.targetId,
+      redactedSummary: summaryCheck.value,
+      redactedFailureReason: failureReasonCheck.value,
+    },
+  };
+}
+
+// ─── The writer ─────────────────────────────────────────────────────────────
+
+/**
+ * Writes exactly one `audit_logs` row for one agent 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 recordAgentAction(
+  input: RecordAgentActionInput,
+  db: AuditWriteClient = prisma,
+): Promise<RecordAgentActionResult> {
+  const validated = validateInput(input);
+  if (!validated.ok) {
+    return {
+      ok: false,
+      error: {
+        kind: "invalid_input",
+        message: validated.message,
+        persisted: false,
+      },
+    };
+  }
+
+  const {
+    workspaceId,
+    actorId,
+    tool,
+    targetType,
+    targetId,
+    redactedSummary,
+    redactedFailureReason,
+  } = validated.value;
+  const actorType: AuditActorType = "agent";
+  const action = `agent.commerce.${tool}`;
+
+  const id = deriveAuditRowId({
+    workspaceId,
+    actorId,
+    actorType,
+    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: "agent action row write failed",
+        persisted: false,
+      },
+    };
+  }
+
+  const metadata: AuditLogMetadata = {
+    v: 1,
+    outcome: input.outcome,
+    tool,
+    idempotencyKey: input.idempotencyKey,
+    ...(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 agent action 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] agent action row write failed",
+    );
+    return {
+      ok: false,
+      error: {
+        kind: "write_failed",
+        message: "agent action row write failed",
+        persisted: false,
+      },
+    };
+  }
+}