create-ailk 0.12.0 → 0.13.0

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

@@ -1,12 +1,14 @@
 /**
  * @file audit-log.test.ts
- * @description Unit tests for the agent-action audit writer (#6040,
- * REL-017 row 5 / FEAT-084 SUB-096), scored against docs/specs/6040-one-auditlog-row-per-agent-spec.md §5.1.
+ * @description Unit tests for the audit writer (#6040, REL-017 row 5 /
+ * FEAT-084 SUB-096), scored against docs/specs/6040-one-auditlog-row-per-agent-spec.md §5.1,
+ * and its actor-and-domain reshape (#3591 D8,
+ * docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md).
  *
  * External dependency boundaries mocked:
  *   - apps/api/src/lib/prisma — the repo-standard `__mocks__/prisma.ts`
  *     manual mock (`jest.mock("../../lib/prisma.js")`). Not read directly by
- *     any case below — `recordAgentAction`'s injectable `AuditWriteClient`
+ *     any case below — `recordAuditAction`'s injectable `AuditWriteClient`
  *     (D1) means every case supplies its own stub delegate — this mock is
  *     kept only so importing `audit-log.ts` never constructs a real
  *     `PrismaPg` adapter (the repo-standard reason every sibling service
@@ -44,12 +46,16 @@ import { sanitizePII } from "@working-theory/observability";
 
 import type { TenantContext } from "../default-tenant.js";
 import {
+  auditActorFor,
   deriveAuditRowId,
-  recordAgentAction,
+  freshAuditIdempotencyKey,
+  recordAgentWrite,
+  recordAuditAction,
   redactPersonalData,
+  type AuditActor,
   type AuditRowDigestInput,
   type AuditWriteClient,
-  type RecordAgentActionInput,
+  type RecordAuditActionInput,
 } from "../audit-log.js";
 
 // ─── Fixtures ───────────────────────────────────────────────────────────────
@@ -68,9 +74,24 @@ const TENANT: TenantContext = {
   role: "owner",
 };
 
-const BASE_INPUT: RecordAgentActionInput = {
+/** An agent actor with the given id, acting for `USER_ID`. */
+function agentActor(agentId: string): AuditActor {
+  return {
+    type: "agent",
+    agentId: agentId as Id<"agent">,
+    onBehalfOfUserId: USER_ID as Id<"user">,
+  };
+}
+
+/** A person actor with the given id. */
+function userActor(userId: string): AuditActor {
+  return { type: "user", userId: userId as Id<"user"> };
+}
+
+const BASE_INPUT: RecordAuditActionInput = {
   tenant: TENANT,
-  actorId: "agent_abc123",
+  actor: agentActor("agent_abc123"),
+  domain: "commerce",
   tool: "refund",
   outcome: "succeeded",
   idempotencyKey: "req_abc123",
@@ -111,51 +132,72 @@ beforeEach(() => {
 // ─── AC-1 — exactly one row, carrying the five facts ───────────────────────
 
 describe("AC-1 — exactly one row, carrying the five facts", () => {
-  it("calls create exactly once for one recordAgentAction call", async () => {
+  it("calls create exactly once for one recordAuditAction call", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction(BASE_INPUT, db);
+    await recordAuditAction(BASE_INPUT, db);
     expect(create).toHaveBeenCalledTimes(1);
   });
 
   it("writes workspaceId from the resolved tenant, satisfying zWorkspaceId", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction(BASE_INPUT, db);
+    await recordAuditAction(BASE_INPUT, db);
     const row = firstWrittenRow(create);
     expect(row.workspaceId).toBe(TENANT.workspaceId);
     expect(zWorkspaceId.safeParse(row.workspaceId).success).toBe(true);
   });
 
-  it("writes actorType 'agent' unconditionally — a regression guard, not caller-influenced", async () => {
+  it("writes an agent actor as actorType 'agent', actorId the agent's id, and metadata.onBehalfOf its person (#3591 D8)", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction({ ...BASE_INPUT, outcome: "refused" }, db);
+    await recordAuditAction({ ...BASE_INPUT, outcome: "refused" }, db);
     const row = firstWrittenRow(create);
     expect(row.actorType).toBe("agent");
+    expect(row.actorId).toBe("agent_abc123");
+    expect(row.metadata.onBehalfOf).toBe(USER_ID);
   });
 
-  it("writes actorId verbatim", async () => {
+  it("writes a person actor as actorType 'user', actorId their user id, and no onBehalfOf (#3591 D8)", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction(BASE_INPUT, db);
+    await recordAuditAction({ ...BASE_INPUT, actor: userActor(USER_ID) }, db);
     const row = firstWrittenRow(create);
-    expect(row.actorId).toBe(BASE_INPUT.actorId);
+    expect(row.actorType).toBe("user");
+    expect(row.actorId).toBe(USER_ID);
+    expect(row.metadata).not.toHaveProperty("onBehalfOf");
   });
 
-  it("writes action as 'agent.commerce.' + tool — the tool name in the column, not only metadata", async () => {
+  it("writes action as domain + '.' + tool — never the retired 'agent.commerce.' prefix (#3591 D8)", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction({ ...BASE_INPUT, tool: "start_purchase" }, db);
+    await recordAuditAction({ ...BASE_INPUT, domain: "inbox", tool: "accept_message" }, db);
     const row = firstWrittenRow(create);
-    expect(row.action).toBe("agent.commerce.start_purchase");
+    expect(row.action).toBe("inbox.accept_message");
+    expect(row.action).not.toMatch(/^agent\.commerce\./);
+  });
+
+  it("writes metadata at v: 2 (#3591 D8)", async () => {
+    const { db, create } = stubDb();
+    await recordAuditAction(BASE_INPUT, db);
+    expect(firstWrittenRow(create).metadata.v).toBe(2);
   });
 
+  it.each(["", "Inbox", "in box", "inbox.accept", "a".repeat(33)])(
+    "refuses a domain outside the identifier grammar (%j)",
+    async (domain) => {
+      const { db, create } = stubDb();
+      const result = await recordAuditAction({ ...BASE_INPUT, domain }, db);
+      expect(result.ok).toBe(false);
+      expect(create).not.toHaveBeenCalled();
+    },
+  );
+
   it.each([
     "succeeded",
     "failed",
     "refused",
     "awaiting_approval",
-  ] satisfies RecordAgentActionInput["outcome"][])(
-    "writes metadata.outcome = %s for every AgentActionOutcome member",
+  ] satisfies RecordAuditActionInput["outcome"][])(
+    "writes metadata.outcome = %s for every AuditActionOutcome member",
     async (outcome) => {
       const { db, create } = stubDb();
-      await recordAgentAction({ ...BASE_INPUT, outcome }, db);
+      await recordAuditAction({ ...BASE_INPUT, outcome }, db);
       const row = firstWrittenRow(create);
       expect(row.metadata.outcome).toBe(outcome);
     },
@@ -163,14 +205,14 @@ describe("AC-1 — exactly one row, carrying the five facts", () => {
 
   it("omits createdAt so the database clock supplies it — an agent cannot backdate its own row", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction(BASE_INPUT, db);
+    await recordAuditAction(BASE_INPUT, db);
     const row = firstWrittenRow(create) as WrittenRow & { createdAt?: unknown };
     expect(row.createdAt).toBeUndefined();
   });
 
   it("writes an id satisfying zAuditLogId and the migration's literal CHECK regex", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction(BASE_INPUT, db);
+    await recordAuditAction(BASE_INPUT, db);
     const row = firstWrittenRow(create);
     // database/migrations/20260713192429_prefixed_uuid_entity_ids/migration.sql:158
     expect(row.id).toMatch(
@@ -185,7 +227,7 @@ describe("AC-1 — exactly one row, carrying the five facts", () => {
 describe("AC-2 — personal data never reaches the stored row in clear form", () => {
   it("redacts an email and phone number from summary/failureReason on the serialized row", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction(
+    await recordAuditAction(
       {
         ...BASE_INPUT,
         outcome: "failed",
@@ -206,7 +248,7 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
     const fullWidthAt = "＠";
     const cyrillicA = "а"; // homoglyph for latin "a" — NOT folded by NFKC
     const summary = `contact jane.doe${fullWidthAt}ex${cyrillicA}mple.com`;
-    await recordAgentAction({ ...BASE_INPUT, summary }, db);
+    await recordAuditAction({ ...BASE_INPUT, summary }, db);
     const row = firstWrittenRow(create);
     const serialized = JSON.stringify(row);
     expect(serialized).not.toContain(summary);
@@ -217,12 +259,13 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
     ["tool", { tool: "refund_jane.doe@example.com" }],
     ["targetType", { targetType: "jane@example.com" }],
     ["targetId", { targetId: "jane@example.com" }],
-    ["actorId", { actorId: "agent jane@example.com" }],
-  ] as [string, Partial<RecordAgentActionInput>][])(
+    ["actorId", { actor: agentActor("agent jane@example.com") }],
+    ["onBehalfOf", { actor: { ...agentActor("agent_abc123"), onBehalfOfUserId: "jane@example.com" as Id<"user"> } }],
+  ] as [string, Partial<RecordAuditActionInput>][])(
     "refuses a personal-data-shaped %s rather than writing it verbatim",
     async (_name, override) => {
       const { db, create } = stubDb();
-      const result = await recordAgentAction(
+      const result = await recordAuditAction(
         { ...BASE_INPUT, ...override },
         db,
       );
@@ -241,11 +284,11 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
   it.each([
     ["summary", { summary: "a".repeat(2001) }],
     ["failureReason", { failureReason: "a".repeat(2001) }],
-  ] as [string, Partial<RecordAgentActionInput>][])(
+  ] as [string, Partial<RecordAuditActionInput>][])(
     "refuses a %s over the 2000-character cap rather than truncating it",
     async (_name, override) => {
       const { db, create } = stubDb();
-      const result = await recordAgentAction(
+      const result = await recordAuditAction(
         { ...BASE_INPUT, ...override },
         db,
       );
@@ -257,7 +300,7 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
 
   it("refuses an idempotencyKey outside the required identifier grammar (a space)", async () => {
     const { db, create } = stubDb();
-    const result = await recordAgentAction(
+    const result = await recordAuditAction(
       { ...BASE_INPUT, idempotencyKey: "req 1" },
       db,
     );
@@ -266,13 +309,14 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
   });
 
   it.each([
-    ["actorId", { actorId: "4155550134" }],
+    ["actorId", { actor: userActor("4155550134") }],
+    ["onBehalfOf", { actor: { ...agentActor("agent_abc123"), onBehalfOfUserId: "4155550134" as Id<"user"> } }],
     ["idempotencyKey", { idempotencyKey: "4155550134" }],
-  ] as [string, Partial<RecordAgentActionInput>][])(
+  ] as [string, Partial<RecordAuditActionInput>][])(
     "refuses a charset-valid but personal-data-shaped %s (a bare digit run) rather than silently rewriting an identifier",
     async (_name, override) => {
       const { db, create } = stubDb();
-      const result = await recordAgentAction(
+      const result = await recordAuditAction(
         { ...BASE_INPUT, ...override },
         db,
       );
@@ -284,11 +328,11 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
   it.each([
     ["tool", { tool: "refund" }],
     ["summary", { summary: "notehere" }],
-  ] as [string, Partial<RecordAgentActionInput>][])(
+  ] as [string, Partial<RecordAuditActionInput>][])(
     "refuses a %s containing a NUL character — a reliable audit-disable switch if it reached Postgres",
     async (_name, override) => {
       const { db, create } = stubDb();
-      const result = await recordAgentAction(
+      const result = await recordAuditAction(
         { ...BASE_INPUT, ...override },
         db,
       );
@@ -299,7 +343,7 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
 
   it("never stores a hash or pseudonym of the redacted value", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction(
+    await recordAuditAction(
       { ...BASE_INPUT, summary: "contact jane.doe@example.com" },
       db,
     );
@@ -309,30 +353,30 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
 
   it("writes exactly the allow-listed metadata keys on the success path", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction({ ...BASE_INPUT, summary: "ok" }, db);
+    await recordAuditAction({ ...BASE_INPUT, summary: "ok" }, db);
     const row = firstWrittenRow(create);
     expect(Object.keys(row.metadata).sort()).toEqual(
-      ["idempotencyKey", "outcome", "summary", "tool", "v"].sort(),
+      ["idempotencyKey", "onBehalfOf", "outcome", "summary", "tool", "v"].sort(),
     );
   });
 
   it("adds failureReason to the allow-listed metadata keys on the failure path", async () => {
     const { db, create } = stubDb();
-    await recordAgentAction(
+    await recordAuditAction(
       { ...BASE_INPUT, outcome: "failed", failureReason: "declined" },
       db,
     );
     const row = firstWrittenRow(create);
     expect(Object.keys(row.metadata).sort()).toEqual(
-      ["failureReason", "idempotencyKey", "outcome", "tool", "v"].sort(),
+      ["failureReason", "idempotencyKey", "onBehalfOf", "outcome", "tool", "v"].sort(),
     );
   });
 
   it("declares no member whose purpose is a buyer's identity", () => {
-    void recordAgentAction({
+    void recordAuditAction({
       ...BASE_INPUT,
       // @ts-expect-error — `buyerEmail` is not a declared member of
-      // RecordAgentActionInput (D5(a), D11). This proves the member is
+      // RecordAuditActionInput (D5(a), D11). This proves the member is
       // UNDECLARED, not that no declared member can carry personal data —
       // `summary` can (D5 concedes this; § 9 SEC-12).
       buyerEmail: "buyer@example.com",
@@ -351,7 +395,7 @@ describe("AC-2 — personal data never reaches the stored row in clear form", ()
 describe("AC-3 — a write failure is surfaced, and the block decision is explicit in the code", () => {
   it("resolves with ok:false rather than throwing on a write failure", async () => {
     const { db } = stubDb(jest.fn().mockRejectedValue(new Error("boom")));
-    const result = await recordAgentAction(BASE_INPUT, db);
+    const result = await recordAuditAction(BASE_INPUT, db);
     expect(result).toEqual({
       ok: false,
       error: {
@@ -365,7 +409,7 @@ describe("AC-3 — a write failure is surfaced, and the block decision is explic
   it("never returns or logs the raw error message — Prisma's data argument IS the audit row", async () => {
     const sentinel = "SENTINEL-jane.doe@example.com";
     const { db } = stubDb(jest.fn().mockRejectedValue(new Error(sentinel)));
-    const result = await recordAgentAction(BASE_INPUT, db);
+    const result = await recordAuditAction(BASE_INPUT, db);
     expect(result.ok).toBe(false);
     if (!result.ok) expect(result.error.message).not.toContain(sentinel);
     expect(JSON.stringify(mockLoggerError.mock.calls[0])).not.toContain(
@@ -375,7 +419,7 @@ describe("AC-3 — a write failure is surfaced, and the block decision is explic
 
   it("logs exactly once at error, with a code but no personal data", async () => {
     const { db } = stubDb(jest.fn().mockRejectedValue({ code: "P2025" }));
-    await recordAgentAction(
+    await recordAuditAction(
       { ...BASE_INPUT, summary: "contact jane.doe@example.com" },
       db,
     );
@@ -399,7 +443,8 @@ describe("AC-4 — a replay produces no duplicate row", () => {
     workspaceId: TENANT.workspaceId,
     actorId: "agent_abc123",
     actorType: "agent",
-    action: "agent.commerce.refund",
+    onBehalfOf: USER_ID,
+    action: "commerce.refund",
     targetType: "lead",
     targetId: "lead_xyz",
     outcome: "succeeded",
@@ -452,11 +497,11 @@ describe("AC-4 — a replay produces no duplicate row", () => {
       tool: "refund",
       idempotencyKey: "req_shared",
     };
-    const first = await recordAgentAction(
+    const first = await recordAuditAction(
       { ...shared, outcome: "refused", summary: "decoy" },
       db,
     );
-    const second = await recordAgentAction(
+    const second = await recordAuditAction(
       { ...shared, outcome: "succeeded", summary: "real refund" },
       db,
     );
@@ -482,8 +527,8 @@ describe("AC-4 — a replay produces no duplicate row", () => {
       .mockResolvedValueOnce({ id: "ignored" })
       .mockRejectedValueOnce({ code: "P2002" });
     const { db } = stubDb(create);
-    const first = await recordAgentAction(BASE_INPUT, db);
-    const second = await recordAgentAction(BASE_INPUT, db);
+    const first = await recordAuditAction(BASE_INPUT, db);
+    const second = await recordAuditAction(BASE_INPUT, db);
     expect(first).toEqual({
       ok: true,
       outcome: "recorded",
@@ -499,7 +544,7 @@ describe("AC-4 — a replay produces no duplicate row", () => {
 
   it("refuses a digit-heavy dashed uuid as an idempotencyKey — the personal-data scan reads it as a phone number, so a caller must re-spell its entropy (#6231)", async () => {
     const { db, create } = stubDb();
-    const result = await recordAgentAction(
+    const result = await recordAuditAction(
       { ...BASE_INPUT, idempotencyKey: "01234567-8901-4234-8567-890123456789" },
       db,
     );
@@ -518,7 +563,7 @@ describe("AC-4 — a replay produces no duplicate row", () => {
 
   it("logs the duplicate outcome at warn, naming the colliding row — a collision is never silent regardless of caller (#6231)", async () => {
     const { db } = stubDb(jest.fn().mockRejectedValue({ code: "P2002" }));
-    const result = await recordAgentAction(BASE_INPUT, db);
+    const result = await recordAuditAction(BASE_INPUT, db);
     expect(result).toEqual({
       ok: true,
       outcome: "duplicate",
@@ -545,7 +590,7 @@ describe("AC-4 — a replay produces no duplicate row", () => {
 
   it("classifies a non-P2002 rejection as write_failed, never as duplicate", async () => {
     const { db } = stubDb(jest.fn().mockRejectedValue({ code: "P2025" }));
-    const result = await recordAgentAction(BASE_INPUT, db);
+    const result = await recordAuditAction(BASE_INPUT, db);
     expect(result).toEqual({
       ok: false,
       error: {
@@ -562,7 +607,7 @@ describe("AC-4 — a replay produces no duplicate row", () => {
 describe("targetType/targetId pass-through", () => {
   it("validates targetId against its named entity's own id grammar when targetType names a registered entity", async () => {
     const { db, create } = stubDb();
-    const result = await recordAgentAction(
+    const result = await recordAuditAction(
       { ...BASE_INPUT, targetType: "workspace", targetId: TENANT.workspaceId },
       db,
     );
@@ -574,7 +619,7 @@ describe("targetType/targetId pass-through", () => {
 
   it("refuses a targetId that does not match its named entity's id grammar", async () => {
     const { db, create } = stubDb();
-    const result = await recordAgentAction(
+    const result = await recordAuditAction(
       {
         ...BASE_INPUT,
         targetType: "workspace",
@@ -588,7 +633,7 @@ describe("targetType/targetId pass-through", () => {
 
   it("refuses a malformed tenant.workspaceId", async () => {
     const { db, create } = stubDb();
-    const result = await recordAgentAction(
+    const result = await recordAuditAction(
       {
         ...BASE_INPUT,
         tenant: {
@@ -618,3 +663,275 @@ describe("redactPersonalData (exported pure helper)", () => {
     );
   });
 });
+
+// ─── #7636 D7, #3591 D8 — a registry user or agent id is never "personal data"
+
+describe("actor ids — a well-formed user or agent id (#7636 D7, #3591 D8)", () => {
+  // Real DB-minted shapes whose hex happens to contain a long digit run: the
+  // phone pattern reads `-` as a digit separator, so the bare scan flagged
+  // about a third of real ids and dropped their audit rows.
+  const DIGIT_HEAVY_USER = "user_01a1081d-15ec-7fcf-a280-4cb63886627f";
+  const DIGIT_HEAVY_SPEC_USER = "user_01923456-7890-7abc-8def-0123456789ab";
+  const DIGIT_HEAVY_AGENT = "agent_01923456-7890-7abc-8def-0123456789ab";
+
+  it("writes the row for a digit-heavy user_<uuidv7> actor", async () => {
+    const { db, create } = stubDb();
+    const result = await recordAuditAction({ ...BASE_INPUT, actor: userActor(DIGIT_HEAVY_USER) }, db);
+    expect(result.ok).toBe(true);
+    expect(firstWrittenRow(create).actorId).toBe(DIGIT_HEAVY_USER);
+  });
+
+  it("the ids really are phone-shaped to the scan — the exemption, not the id, is what admits them", () => {
+    for (const id of [DIGIT_HEAVY_SPEC_USER, DIGIT_HEAVY_AGENT]) {
+      expect(redactPersonalData(id)).toContain("[REDACTED:");
+    }
+  });
+
+  it("records a digit-heavy user id as a person actor", async () => {
+    const { db, create } = stubDb();
+    const result = await recordAuditAction({ ...BASE_INPUT, actor: userActor(DIGIT_HEAVY_SPEC_USER) }, db);
+    expect(result.ok).toBe(true);
+    expect(firstWrittenRow(create)).toMatchObject({ actorType: "user", actorId: DIGIT_HEAVY_SPEC_USER });
+  });
+
+  it("records a digit-heavy agent id acting for a digit-heavy user id", async () => {
+    const { db, create } = stubDb();
+    const result = await recordAuditAction(
+      {
+        ...BASE_INPUT,
+        actor: {
+          type: "agent",
+          agentId: DIGIT_HEAVY_AGENT as Id<"agent">,
+          onBehalfOfUserId: DIGIT_HEAVY_SPEC_USER as Id<"user">,
+        },
+      },
+      db,
+    );
+    expect(result.ok).toBe(true);
+    const row = firstWrittenRow(create);
+    expect(row).toMatchObject({ actorType: "agent", actorId: DIGIT_HEAVY_AGENT });
+    expect(row.metadata.onBehalfOf).toBe(DIGIT_HEAVY_SPEC_USER);
+  });
+
+  it("still refuses a phone-shaped actor id that is not a registry id", async () => {
+    const { db, create } = stubDb();
+    const result = await recordAuditAction({ ...BASE_INPUT, actor: agentActor("agent-555-867-5309") }, db);
+    expect(result.ok).toBe(false);
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it("still scans every other identifier — a registry-shaped idempotencyKey is not exempt", async () => {
+    const { db, create } = stubDb();
+    const result = await recordAuditAction({ ...BASE_INPUT, idempotencyKey: DIGIT_HEAVY_SPEC_USER }, db);
+    expect(result.ok).toBe(false);
+    expect(create).not.toHaveBeenCalled();
+  });
+});
+
+// ─── #3591 D8 — the route helpers ───────────────────────────────────────────
+
+describe("freshAuditIdempotencyKey (#3591 D8)", () => {
+  it("is 32 hex characters in `_`-joined runs of at most six, fresh per call", () => {
+    const first = freshAuditIdempotencyKey();
+    expect(first).toMatch(/^[0-9a-f]{6}(?:_[0-9a-f]{1,6})*$/);
+    expect(first.replace(/_/g, "")).toHaveLength(32);
+    expect(freshAuditIdempotencyKey()).not.toBe(first);
+  });
+});
+
+describe("auditActorFor (#3591 D8)", () => {
+  it("passes request.actor through, and falls back to the tenant's own person with a warning", () => {
+    const agent = agentActor("agent_abc123");
+    expect(auditActorFor(agent, TENANT)).toBe(agent);
+    expect(mockLoggerWarn).not.toHaveBeenCalled();
+    expect(auditActorFor(undefined, TENANT)).toEqual({ type: "user", userId: USER_ID });
+    expect(mockLoggerWarn).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("recordAgentWrite (#3591 D8)", () => {
+  const WRITE = {
+    tenant: TENANT,
+    domain: "inbox",
+    tool: "mark_message_done",
+    targetType: "lead",
+    targetId: "lead_0190f3a2-7c1d-7e4a-9b2c-000000000004",
+  };
+
+  it("writes nothing for a person or an unknown actor", async () => {
+    const { db, create } = stubDb();
+    await recordAgentWrite(userActor(USER_ID), WRITE, { ok: true }, db);
+    await recordAgentWrite(undefined, WRITE, { ok: true }, db);
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it("writes one succeeded row for an agent's write that succeeded", async () => {
+    const { db, create } = stubDb();
+    await recordAgentWrite(agentActor("agent_abc123"), WRITE, { ok: true }, db);
+    expect(create).toHaveBeenCalledTimes(1);
+    const row = firstWrittenRow(create);
+    expect(row).toMatchObject({
+      actorType: "agent",
+      actorId: "agent_abc123",
+      action: "inbox.mark_message_done",
+      targetType: "lead",
+    });
+    expect(row.metadata).toMatchObject({ outcome: "succeeded", onBehalfOf: USER_ID });
+    expect(row.metadata).not.toHaveProperty("failureReason");
+  });
+
+  it("writes one failed row carrying the service's error kind for an agent's write that failed", async () => {
+    const { db, create } = stubDb();
+    await recordAgentWrite(
+      agentActor("agent_abc123"),
+      WRITE,
+      { ok: false, error: { kind: "not_found" } },
+      db,
+    );
+    const row = firstWrittenRow(create);
+    expect(row.metadata).toMatchObject({ outcome: "failed", failureReason: "not_found" });
+  });
+
+  it("logs a failed audit write once at error and resolves, so the caller's response is unchanged", async () => {
+    const { db } = stubDb(jest.fn().mockRejectedValue(new Error("boom")));
+    await expect(
+      recordAgentWrite(agentActor("agent_abc123"), WRITE, { ok: true }, db),
+    ).resolves.toBeUndefined();
+    const messages = mockLoggerError.mock.calls.map((call) => call[1] as string);
+    expect(messages).toEqual(["[audit-log] audit row write failed"]);
+  });
+
+  it("logs a refused audit row once at error and resolves", async () => {
+    const { db, create } = stubDb();
+    await expect(
+      recordAgentWrite(agentActor("agent_abc123"), { ...WRITE, domain: "In Box" }, { ok: true }, db),
+    ).resolves.toBeUndefined();
+    expect(create).not.toHaveBeenCalled();
+    const messages = mockLoggerError.mock.calls.map((call) => call[1] as string);
+    expect(messages).toEqual(["[audit-log] agent write audit refused"]);
+  });
+});
+
+// #3591 PR-B — a registry id is an identifier, not personal data, in free
+// text too: the agent lifecycle rows name the person they were made for by
+// user id in `summary`, and a digit-heavy id must survive the scan.
+describe("summary and failureReason keep a registry user_ or agent_ id whole (#3591 D8)", () => {
+  const DIGIT_HEAVY_USER = "user_01923456-7890-7abc-8def-0123456789ab";
+  const DIGIT_HEAVY_AGENT = "agent_01923456-7890-7abc-8def-0123456789ab";
+
+  async function storedSummary(summary: string): Promise<unknown> {
+    const { db, create } = stubDb();
+    const result = await recordAuditAction({ ...BASE_INPUT, summary }, db);
+    expect(result.ok).toBe(true);
+    return firstWrittenRow(create).metadata.summary;
+  }
+
+  it("the fixture id really is phone-shaped to the bare scan", () => {
+    expect(redactPersonalData(DIGIT_HEAVY_USER)).toContain("[REDACTED:");
+  });
+
+  it("a summary naming a digit-heavy user id is stored as written", async () => {
+    expect(await storedSummary(`responsibleUserId=${DIGIT_HEAVY_USER}`)).toBe(
+      `responsibleUserId=${DIGIT_HEAVY_USER}`,
+    );
+  });
+
+  it("keeps the ids and still redacts the personal data around them", async () => {
+    const out = (await storedSummary(
+      `responsibleUserId=${DIGIT_HEAVY_USER} agent=${DIGIT_HEAVY_AGENT} call +1 415 555 0100 or jane@example.com`,
+    )) as string;
+    expect(out).toContain(`responsibleUserId=${DIGIT_HEAVY_USER}`);
+    expect(out).toContain(`agent=${DIGIT_HEAVY_AGENT}`);
+    expect(out).toContain("[REDACTED:phone]");
+    expect(out).toContain("[REDACTED:email]");
+    expect(out).not.toContain("jane@example.com");
+  });
+
+  it("still scans a digit run glued onto an id, and an id of another entity", async () => {
+    expect(await storedSummary(`${DIGIT_HEAVY_USER}5550100`)).toContain("[REDACTED:");
+    expect(await storedSummary("lead_01923456-7890-7abc-8def-0123456789ab")).toContain("[REDACTED:");
+  });
+
+  it("does not exempt a phone number dressed up as an id, nor an id inside a longer token", async () => {
+    for (const disguised of [
+      "user_+1-415-555-0100",
+      "user_4155550100-7abc-8def-0123456789ab",
+      `x${DIGIT_HEAVY_USER}`,
+      `${DIGIT_HEAVY_USER}.`,
+    ]) {
+      expect(await storedSummary(`responsibleUserId=${disguised}`)).toContain("[REDACTED:");
+    }
+  });
+
+  it("still catches a phone number written with spaces between exempt ids", async () => {
+    const out = (await storedSummary(`${DIGIT_HEAVY_USER} +1 415 555 0100 ${DIGIT_HEAVY_AGENT}`)) as string;
+    expect(out).toBe(`${DIGIT_HEAVY_USER} [REDACTED:phone] ${DIGIT_HEAVY_AGENT}`);
+  });
+
+  it("applies to failureReason the same way", async () => {
+    const { db, create } = stubDb();
+    await recordAuditAction(
+      { ...BASE_INPUT, outcome: "failed", failureReason: `not a member: ${DIGIT_HEAVY_USER}` },
+      db,
+    );
+    expect(firstWrittenRow(create).metadata.failureReason).toBe(`not a member: ${DIGIT_HEAVY_USER}`);
+  });
+});
+
+describe("recordAgentWrite given the request (#3591 PR-B)", () => {
+  const AGENT_ID = "agent_0190f3a2-7c1d-7e4a-9b2c-000000000005";
+  const WRITE = {
+    tenant: TENANT,
+    domain: "inbox",
+    tool: "set_application_featured",
+    targetType: "project_listing",
+    targetId: "listing_abc123",
+  };
+
+  it("reads request.actor when it is set", async () => {
+    const { db, create } = stubDb();
+    await recordAgentWrite(
+      { actor: agentActor(AGENT_ID), agent: { agentId: AGENT_ID as Id<"agent"> } },
+      WRITE,
+      { ok: true },
+      db,
+    );
+    expect(firstWrittenRow(create)).toMatchObject({ actorType: "agent", actorId: AGENT_ID });
+    expect(mockLoggerError).not.toHaveBeenCalled();
+  });
+
+  it("an agent request with no request.actor is logged at error and still recorded, from request.agent", async () => {
+    const { db, create } = stubDb();
+    await recordAgentWrite({ agent: { agentId: AGENT_ID as Id<"agent"> } }, WRITE, { ok: true }, db);
+
+    expect(create).toHaveBeenCalledTimes(1);
+    const row = firstWrittenRow(create);
+    expect(row).toMatchObject({
+      actorType: "agent",
+      actorId: AGENT_ID,
+      action: "inbox.set_application_featured",
+    });
+    expect(row.metadata).toMatchObject({ onBehalfOf: USER_ID, outcome: "succeeded" });
+    expect(mockLoggerError).toHaveBeenCalledTimes(1);
+    expect(mockLoggerError.mock.calls[0]![0]).toMatchObject({ actorId: AGENT_ID });
+    expect(mockLoggerError.mock.calls[0]![1]).toBe(
+      "[audit-log] agent write without request.actor; recording from request.agent",
+    );
+  });
+
+  it("a request with neither, or a person's request, records nothing and logs nothing", async () => {
+    const { db, create } = stubDb();
+    await recordAgentWrite({}, WRITE, { ok: true }, db);
+    await recordAgentWrite({ actor: userActor(USER_ID) }, WRITE, { ok: true }, db);
+    expect(create).not.toHaveBeenCalled();
+    expect(mockLoggerError).not.toHaveBeenCalled();
+  });
+
+  it("the refused-row error line names the actor id", async () => {
+    const { db } = stubDb();
+    await recordAgentWrite({ actor: agentActor(AGENT_ID) }, { ...WRITE, domain: "In Box" }, { ok: true }, db);
+    expect(mockLoggerError).toHaveBeenCalledTimes(1);
+    expect(mockLoggerError.mock.calls[0]![0]).toMatchObject({ actorId: AGENT_ID });
+    expect(mockLoggerError.mock.calls[0]![1]).toBe("[audit-log] agent write audit refused");
+  });
+});