From fb33dad859e9c57da68b89ff4ed5d9c91b6c4aeb Mon Sep 17 00:00:00 2001
From: os-zhuang <steve@objectstack.ai>
Date: Mon, 10 Aug 2026 05:04:47 +0000
Subject: [PATCH] fix(plugin-audit): localize tracked-change labels and render
 lookup titles (#7230)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`sys_activity.summary`'s tracked-change branch (ADR-0052 §5b) shipped strings
like `Rating Owner: ∅ → oBK25…` onto every feed surface at once. Two causes,
both fixed here:

- `renderTrackedChangeSummary` was the one summary branch never handed the
  locale-bound `translate` its three siblings resolve through (ADR-0053 /
  #3039). The field label now resolves through it on the bundles' own key
  shape, falling back to the authored label and then the machine key.
- `displayFieldValue` resolved select option labels only, so a lookup /
  master_detail / user value printed its raw id. It now renders the referenced
  record's title via ADR-0079's `resolveDisplayField`, falling back to the raw
  id when unresolvable.

The resolution is batched: 0 added reads unless a tracked reference field
actually moved, then exactly one `id: { $in: [...] }` per distinct target
object — so #6656 / PR #6977's retirement of the redundant pre-image read from
this write path is not handed back. Read counts are pinned with the same
counting driver that measured that retirement.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BM1tNf5U3nEbHKR4fo5qVQ
---
 ...racked-change-summary-locale-and-lookup.md |  48 ++
 .../src/audit-lookup-summary.test.ts          | 522 ++++++++++++++++++
 .../plugins/plugin-audit/src/audit-writers.ts | 228 +++++++-
 3 files changed, 790 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/audit-tracked-change-summary-locale-and-lookup.md
 create mode 100644 packages/plugins/plugin-audit/src/audit-lookup-summary.test.ts

diff --git a/.changeset/audit-tracked-change-summary-locale-and-lookup.md b/.changeset/audit-tracked-change-summary-locale-and-lookup.md
new file mode 100644
index 0000000000..030aa0c546
--- /dev/null
+++ b/.changeset/audit-tracked-change-summary-locale-and-lookup.md
@@ -0,0 +1,48 @@
+---
+"@objectstack/plugin-audit": patch
+---
+
+fix(plugin-audit): localize the tracked-change activity label and render lookup titles instead of raw ids (#7230)
+
+`sys_activity.summary` is composed at write time and shipped verbatim to every
+feed surface at once — the record discussion feed, console home activity, the
+header inbox, the Setup `sys_activity` list, and mobile/REST/SDUI. Its
+tracked-change branch (ADR-0052 §5b, `"<label>: <old> → <new>"`) was producing
+strings like `Rating Owner: ∅ → oBK25…` at the bottom of an otherwise
+fully-localized page. Two independent causes, both fixed here:
+
+- **The label was never localized.** `renderTrackedChangeSummary` was the one
+  summary branch never handed the locale-bound `translate` its three siblings
+  (`messages.activityCreated` / `messages.activityDeleted` /
+  `messages.activityUpdated`, plus the object label via `displayLabelFor`) all
+  resolve through — an oversight against ADR-0053 / #3039 write-time
+  localization. The field label now resolves through the same translator, on the
+  bundles' own key shape (`objects.<object>.fields.<field>.label`), and falls
+  back to the authored `label`, then the machine key, exactly as before.
+- **A reference value printed its raw id.** `displayFieldValue` resolved
+  select/picklist option labels only, so a `lookup` / `master_detail` / `user`
+  value fell through to `String(value)` — the stored 32-char id. It now renders
+  the referenced record's title, resolved through ADR-0079's
+  `resolveDisplayField` (`nameField` → deprecated `displayNameField` alias →
+  derivation) rather than a local name-guessing heuristic.
+
+The `∅ →` notation is unchanged, and so is every other summary branch. The
+change is restore-invariant: an id that cannot be resolved — a target removed
+out of band, an unregistered object, a failing read — renders exactly as it did
+before.
+
+**Read cost, measured with a counting driver** (the same technique that measured
+#6656 / PR #6977's retirement of the redundant pre-image read from this write
+path, and pinned as cases in `audit-lookup-summary.test.ts`):
+
+- **0 added reads** on every create, every delete, every update that moves no
+  tracked reference field, and every update that moves an *untracked* one —
+  including on rows that do carry references. #6977's counts (1 `findOne` per
+  single-id write, 0 per predicate write) are untouched.
+- **1 read per distinct target object** on an update that does move a tracked
+  reference: both sides of the change are answered by a single
+  `id: { $in: [...] }` selecting only the id and title columns, however many
+  tracked reference fields point at that object.
+
+Historical `sys_activity` rows keep their original write-time composition — only
+new writes improve.
diff --git a/packages/plugins/plugin-audit/src/audit-lookup-summary.test.ts b/packages/plugins/plugin-audit/src/audit-lookup-summary.test.ts
new file mode 100644
index 0000000000..46fd3ddd1c
--- /dev/null
+++ b/packages/plugins/plugin-audit/src/audit-lookup-summary.test.ts
@@ -0,0 +1,522 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#7230] `sys_activity.summary`'s tracked-change branch — the field LABEL is
+ * localized, and a reference VALUE renders the referenced record's title
+ * instead of its raw id.
+ *
+ * ## The two halves, pinned separately on purpose
+ *
+ * The measured symptom was one string — `Rating Owner: ∅ → oBK25…` at the
+ * bottom of an otherwise fully-localized zh-CN page — but it had two
+ * independent causes, and a test that only asserted the finished string could
+ * be satisfied by fixing either one:
+ *
+ *  - **Label half.** `renderTrackedChangeSummary` was the ONE summary branch
+ *    never handed the locale-bound `translate` its three siblings
+ *    (`messages.activityCreated` / `Deleted` / `Updated`, plus `displayLabelFor`)
+ *    all resolve through — an oversight against ADR-0053 / framework#3039
+ *    write-time localization. Pinned against a REAL locale: `createMemoryI18n`
+ *    loaded with real `objects.<object>.fields.<field>.label` data, which is
+ *    the key shape the shipped bundles use. A stub translator returning a
+ *    marker would pass whether or not the real key shape were right.
+ *  - **Value half.** `displayFieldValue` resolved select/picklist option labels
+ *    only, so a `lookup` / `master_detail` / `user` value fell through to
+ *    `String(value)` — the raw 32-char id.
+ *
+ * ## Why the read counts are measured here at all
+ *
+ * The value half needs a read, and this file is the write hot path: one day
+ * before this change #6656 / PR #6977 retired `captureBefore`'s redundant
+ * pre-image read from it (2 → 1 per single-id write, 3 → 0 per predicate
+ * write) under maintainer ruling Option A+. So the reads this change ADDS are
+ * measured with the same copy-returning counting driver that measured that
+ * retirement, and the three properties that keep it off the hot path are
+ * pinned as cases rather than asserted in prose:
+ *
+ *   0 reads   when no tracked REFERENCE field changed (every create, every
+ *             delete, and every update that does not move a reference)
+ *   1 read    per distinct target object, however many tracked reference
+ *             fields point at it
+ *   N reads   for N distinct target objects — one each, never one per value
+ *
+ * ⚠️ The read-count cases do NOT pin the rendering, and the rendering cases do
+ * not pin the read counts: the read lives in `resolveTrackedLookupTitles` and
+ * the rendering in `displayFieldValue`. Deleting the render branch leaves every
+ * count green. Both sets are therefore required, and each was mutated
+ * separately to confirm it goes red on its own defect.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { ObjectQL } from '@objectstack/objectql';
+import { createMemoryI18n } from '@objectstack/core';
+import { installAuditWriters } from './audit-writers.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const f = (name: string, type: string, extra: Record<string, unknown> = {}) =>
+  ({ name, label: name, type, ...extra }) as any;
+
+const sysAuditLog = {
+  name: 'sys_audit_log', label: 'Audit Log',
+  fields: {
+    id: f('id', 'text', { primaryKey: true }), action: f('action', 'text'),
+    user_id: f('user_id', 'text'), object_name: f('object_name', 'text'),
+    record_id: f('record_id', 'text'), old_value: f('old_value', 'textarea'),
+    new_value: f('new_value', 'textarea'), tenant_id: f('tenant_id', 'text'),
+  },
+};
+
+const sysActivity = {
+  name: 'sys_activity', label: 'Activity',
+  fields: {
+    id: f('id', 'text', { primaryKey: true }), type: f('type', 'text'),
+    timestamp: f('timestamp', 'datetime'), summary: f('summary', 'text'),
+    actor_id: f('actor_id', 'text'), object_name: f('object_name', 'text'),
+    record_id: f('record_id', 'text'), record_label: f('record_label', 'text'),
+    metadata: f('metadata', 'textarea'),
+  },
+};
+
+/** Target objects. Their title fields are DERIVED (ADR-0079), not declared. */
+const crmAccount = {
+  name: 'crm_account', label: 'Account',
+  fields: { id: f('id', 'text', { primaryKey: true }), name: f('name', 'text') },
+};
+
+const crmRegion = {
+  name: 'crm_region', label: 'Region',
+  fields: { id: f('id', 'text', { primaryKey: true }), title: f('title', 'text') },
+};
+
+const sysUserObj = {
+  name: 'sys_user', label: 'User',
+  fields: {
+    id: f('id', 'text', { primaryKey: true }), name: f('name', 'text'),
+    email: f('email', 'email'),
+  },
+};
+
+/**
+ * The audited object. Two tracked lookups point at the SAME target
+ * (`account_id`, `partner_id`) so batching is measurable; `region_id` gives a
+ * second distinct target; `owner` is the `user` specialization the symptom was
+ * actually reported on; `stage` is a tracked NON-reference field, which is what
+ * makes the zero-read case a real tracked-change write rather than a no-op.
+ */
+const bizDeal = {
+  name: 'biz_deal', label: 'Deal',
+  fields: {
+    id: f('id', 'text', { primaryKey: true }),
+    title: f('title', 'text'),
+    stage: f('stage', 'text', { label: 'Stage', trackHistory: true }),
+    account_id: f('account_id', 'lookup', {
+      label: 'Account', reference: 'crm_account', trackHistory: true,
+    }),
+    partner_id: f('partner_id', 'lookup', {
+      label: 'Partner', reference: 'crm_account', trackHistory: true,
+    }),
+    region_id: f('region_id', 'lookup', {
+      label: 'Region', reference: 'crm_region', trackHistory: true,
+    }),
+    owner: f('owner', 'user', {
+      label: 'Owner', reference: 'sys_user', trackHistory: true,
+    }),
+    // An UNTRACKED reference: it must never cost a read, whatever it holds.
+    referrer_id: f('referrer_id', 'lookup', { label: 'Referrer', reference: 'crm_account' }),
+  },
+};
+
+// ---------------------------------------------------------------------------
+// A driver that COUNTS reads and returns COPIES
+// ---------------------------------------------------------------------------
+
+/**
+ * Lifted from `audit-bound-previous.test.ts`, deliberately including its
+ * copy-returning rule: a driver that hands back live store references lets the
+ * engine's read path rewrite the store in place, after which measurements taken
+ * around a write describe a store that moved under them. Real drivers
+ * serialise; so does this one.
+ */
+function makeCountingDriver() {
+  const stores = new Map<string, Map<string, Record<string, unknown>>>();
+  const reads = { findOneOn: {} as Record<string, number>, findOn: {} as Record<string, number> };
+  const storeFor = (o: string) => {
+    let s = stores.get(o);
+    if (!s) { s = new Map(); stores.set(o, s); }
+    return s;
+  };
+  let nextId = 0;
+  const copy = <T,>(r: T): T => (r == null ? r : JSON.parse(JSON.stringify(r)));
+  const matches = (row: Record<string, unknown>, where: any): boolean => {
+    if (!where || typeof where !== 'object') return true;
+    for (const [k, v] of Object.entries<any>(where)) {
+      if (k === '$and' && Array.isArray(v)) {
+        if (!v.every((sub) => matches(row, sub))) return false;
+        continue;
+      }
+      if (k.startsWith('$')) continue;
+      if (v && typeof v === 'object' && '$in' in v) {
+        if (!(v.$in as unknown[]).includes(row[k])) return false;
+        continue;
+      }
+      const expected = (v && typeof v === 'object' && '$eq' in v) ? v.$eq : v;
+      if ((row[k] ?? null) !== (expected ?? null)) return false;
+    }
+    return true;
+  };
+  const driver: any = {
+    name: 'memory', version: '0.0.0', supports: {} as any,
+    async connect() {}, async disconnect() {}, async checkHealth() { return true; },
+    async execute() { return null; },
+    async find(object: string, ast: any) {
+      reads.findOn[object] = (reads.findOn[object] ?? 0) + 1;
+      return Array.from(storeFor(object).values()).filter((r) => matches(r, ast?.where)).map(copy);
+    },
+    async findOne(object: string, ast: any) {
+      reads.findOneOn[object] = (reads.findOneOn[object] ?? 0) + 1;
+      for (const r of storeFor(object).values()) if (matches(r, ast?.where)) return copy(r);
+      return null;
+    },
+    async create(object: string, data: Record<string, unknown>) {
+      nextId += 1;
+      const id = (data.id as string) ?? `r_${nextId}`;
+      const row = { ...data, id };
+      storeFor(object).set(id, row);
+      return copy(row);
+    },
+    async update(object: string, id: string, data: Record<string, unknown>) {
+      const s = storeFor(object);
+      const cur = s.get(id);
+      if (!cur) return null;
+      const updated = { ...cur, ...data, id };
+      s.set(id, updated);
+      return copy(updated);
+    },
+    async upsert(object: string, data: Record<string, unknown>) {
+      const id = data.id as string | undefined;
+      return id && storeFor(object).has(id) ? this.update(object, id, data) : this.create(object, data);
+    },
+    async delete(object: string, id: string) { return storeFor(object).delete(id); },
+    async count(object: string, ast: any) { return (await this.find(object, ast)).length; },
+    async bulkCreate(object: string, rows: Record<string, unknown>[]) {
+      return Promise.all(rows.map((r) => this.create(object, r)));
+    },
+    async bulkUpdate() { return []; },
+    async bulkDelete() {},
+    async updateMany(object: string, ast: any, data: Record<string, unknown>) {
+      const rows = await this.find(object, ast);
+      const s = storeFor(object);
+      for (const r of rows) s.set(r.id as string, { ...s.get(r.id as string), ...data, id: r.id });
+      return rows.length;
+    },
+    async deleteMany(object: string, ast: any) {
+      const rows = await this.find(object, ast);
+      for (const r of rows) storeFor(object).delete(r.id as string);
+      return rows.length;
+    },
+    async beginTransaction() { return { commit: async () => {}, rollback: async () => {} }; },
+    async commit() {}, async rollback() {},
+  };
+  return { driver, reads, storeFor };
+}
+
+const OWNER_PACKAGE = 'com.objectstack.test.audit-lookup-summary';
+
+/**
+ * Real `objects.<object>.fields.<field>.label` data for zh-CN — the shape the
+ * shipped bundles carry and `i18n.t` resolves. `partner_id` is deliberately
+ * ABSENT so the authored-def-label fallback has a case in the same locale.
+ */
+function makeI18n() {
+  const i18n = createMemoryI18n();
+  i18n.loadTranslations('zh-CN', {
+    objects: {
+      biz_deal: {
+        label: '商机',
+        fields: {
+          stage: { label: '阶段' },
+          account_id: { label: '客户' },
+          region_id: { label: '大区' },
+          owner: { label: '负责人' },
+        },
+      },
+    },
+  });
+  return i18n;
+}
+
+async function boot(opts: { locale?: string; i18n?: unknown } = {}) {
+  const engine = new ObjectQL();
+  const stub = makeCountingDriver();
+  engine.registerDriver(stub.driver, true);
+  await engine.init();
+  for (const o of [sysAuditLog, sysActivity, crmAccount, crmRegion, sysUserObj, bizDeal]) {
+    engine.registry.registerObject(o as any, OWNER_PACKAGE);
+  }
+  installAuditWriters(engine as any, 'test.audit', {
+    getI18n: () => opts.i18n as any,
+    getLocale: async () => opts.locale,
+  });
+  return { engine, ...stub };
+}
+
+const summariesOf = (storeFor: (o: string) => Map<string, Record<string, unknown>>) =>
+  Array.from(storeFor('sys_activity').values()).map((r) => String(r.summary));
+
+/** The one activity summary produced by the write under test. */
+const lastSummary = (storeFor: (o: string) => Map<string, Record<string, unknown>>) => {
+  const all = summariesOf(storeFor);
+  return all.length > 0 ? all[all.length - 1] : undefined;
+};
+
+/**
+ * Seed the two accounts, the region, the user, and TWO deals:
+ *
+ *  - `deal_1` holds NO references — the rendering cases move them from `∅`.
+ *  - `deal_2` already holds `account_id` AND `owner` — and that is load-bearing
+ *    rather than incidental. The zero-read guard is only a guard on a row that
+ *    HAS references to resolve: measured, the first draft of this file ran its
+ *    hot-path cases against `deal_1`, where a naive "resolve from the written
+ *    row instead of from the diff" implementation ALSO reads nothing, because
+ *    there is nothing on the row to read. That mutation passed 160/160 — the
+ *    guard was green for the wrong reason. Against `deal_2` it goes red, which
+ *    is what makes these cases pin the #6656 / PR #6977 hot path at all.
+ */
+async function seed(engine: any) {
+  await engine.insert('crm_account', { id: 'acc_1', name: 'Acme Corp' });
+  await engine.insert('crm_account', { id: 'acc_2', name: 'Globex' });
+  await engine.insert('crm_region', { id: 'reg_1', title: 'APAC' });
+  await engine.insert('sys_user', { id: 'usr_1', name: '张伟', email: 'z@example.com' });
+  await engine.insert('biz_deal', {
+    id: 'deal_2', title: 'Already linked', stage: 'open',
+    account_id: 'acc_1', owner: 'usr_1',
+  });
+  return engine.insert('biz_deal', { id: 'deal_1', title: 'Ship it', stage: 'open' });
+}
+
+// ---------------------------------------------------------------------------
+// 1. Value half — a reference renders the referenced record's title
+// ---------------------------------------------------------------------------
+
+describe('[#7230] value half — a tracked reference renders a title, not a raw id', () => {
+  it('renders the referenced record title where the raw id used to appear', async () => {
+    const { engine, storeFor } = await boot();
+    await seed(engine);
+
+    await engine.update('biz_deal', { account_id: 'acc_1' }, { where: { id: 'deal_1' } } as any);
+
+    // Before this change: `Account: ∅ → acc_1`.
+    expect(lastSummary(storeFor)).toBe('Account: ∅ → Acme Corp');
+  });
+
+  it('renders BOTH sides of a reference change as titles', async () => {
+    const { engine, storeFor } = await boot();
+    await seed(engine);
+    await engine.update('biz_deal', { account_id: 'acc_1' }, { where: { id: 'deal_1' } } as any);
+
+    await engine.update('biz_deal', { account_id: 'acc_2' }, { where: { id: 'deal_1' } } as any);
+
+    expect(lastSummary(storeFor)).toBe('Account: Acme Corp → Globex');
+  });
+
+  it('resolves a `user` field the same way — the field class the symptom was reported on', async () => {
+    const { engine, storeFor } = await boot();
+    await seed(engine);
+
+    await engine.update('biz_deal', { owner: 'usr_1' }, { where: { id: 'deal_1' } } as any);
+
+    expect(lastSummary(storeFor)).toBe('Owner: ∅ → 张伟');
+  });
+
+  it('falls back to the RAW ID when the referenced record cannot be resolved', async () => {
+    const { engine, storeFor } = await boot();
+    await seed(engine);
+    await engine.update('biz_deal', { account_id: 'acc_2' }, { where: { id: 'deal_1' } } as any);
+
+    // A DANGLING reference cannot be authored: the engine's
+    // `assertReferencesResolve` refuses `account_id: 'acc_missing'` on write
+    // (measured — the first draft of this case tried it and got
+    // `ValidationError: Account: no crm_account record has id "acc_missing"`).
+    // So the real unresolvable case is a reference that WAS valid when it was
+    // written and whose target has since gone away — reproduced here by
+    // removing the row out-of-band, which is also what a hard delete, a
+    // restore-from-backup skew or an unregistered target object looks like
+    // from this function.
+    storeFor('crm_account').delete('acc_2');
+
+    await engine.update('biz_deal', { account_id: 'acc_1' }, { where: { id: 'deal_1' } } as any);
+
+    // Exactly the pre-change rendering on the unresolvable side, and a title on
+    // the resolvable one: the branch can only replace an id with a title, never
+    // a title with an id.
+    expect(lastSummary(storeFor)).toBe('Account: acc_2 → Acme Corp');
+  });
+
+  it('leaves the `∅ →` notation and non-reference rendering untouched', async () => {
+    const { engine, storeFor } = await boot();
+    await seed(engine);
+
+    await engine.update('biz_deal', { stage: 'won' }, { where: { id: 'deal_1' } } as any);
+
+    expect(lastSummary(storeFor)).toBe('Stage: open → won');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Label half — against a REAL locale bundle, not a stub translator
+// ---------------------------------------------------------------------------
+
+describe('[#7230] label half — the tracked-change branch gets the locale-bound translator', () => {
+  it('localizes the tracked field label to the workspace locale (zh-CN)', async () => {
+    const { engine, storeFor } = await boot({ locale: 'zh-CN', i18n: makeI18n() });
+    await seed(engine);
+
+    await engine.update('biz_deal', { owner: 'usr_1' }, { where: { id: 'deal_1' } } as any);
+
+    // Both halves at once, which is the reported string's actual shape:
+    // localized label + resolved title, where it read `Owner: ∅ → usr_1`.
+    expect(lastSummary(storeFor)).toBe('负责人: ∅ → 张伟');
+  });
+
+  it('localizes a non-reference tracked label too (the label half is not lookup-only)', async () => {
+    const { engine, storeFor } = await boot({ locale: 'zh-CN', i18n: makeI18n() });
+    await seed(engine);
+
+    await engine.update('biz_deal', { stage: 'won' }, { where: { id: 'deal_1' } } as any);
+
+    expect(lastSummary(storeFor)).toBe('阶段: open → won');
+  });
+
+  it('falls back to the authored field label when the bundle has no entry for it', async () => {
+    const { engine, storeFor } = await boot({ locale: 'zh-CN', i18n: makeI18n() });
+    await seed(engine);
+
+    // `partner_id` is absent from the zh-CN bundle above.
+    await engine.update('biz_deal', { partner_id: 'acc_2' }, { where: { id: 'deal_1' } } as any);
+
+    expect(lastSummary(storeFor)).toBe('Partner: ∅ → Globex');
+  });
+
+  it('keeps the authored label when no i18n service is resolvable (status quo)', async () => {
+    const { engine, storeFor } = await boot({ locale: 'zh-CN', i18n: undefined });
+    await seed(engine);
+
+    await engine.update('biz_deal', { owner: 'usr_1' }, { where: { id: 'deal_1' } } as any);
+
+    expect(lastSummary(storeFor)).toBe('Owner: ∅ → 张伟');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Read cost — the #6656 / PR #6977 hot path must not get its reads back
+// ---------------------------------------------------------------------------
+
+describe('[#7230] the resolution is batched per target object, and free when unused', () => {
+  it('a tracked change with NO reference field pays ZERO extra reads, on a row that HAS references', async () => {
+    const { engine, reads, storeFor } = await boot();
+    await seed(engine);
+
+    const beforeAccount = reads.findOn['crm_account'] ?? 0;
+    const beforeUser = reads.findOn['sys_user'] ?? 0;
+    const beforeSelf = reads.findOneOn['biz_deal'] ?? 0;
+    // `deal_2` carries `account_id` and `owner`; only `stage` moves.
+    await engine.update('biz_deal', { stage: 'won' }, { where: { id: 'deal_2' } } as any);
+
+    expect((reads.findOn['crm_account'] ?? 0) - beforeAccount).toBe(0);
+    expect((reads.findOn['sys_user'] ?? 0) - beforeUser).toBe(0);
+    // #6977's single-id count, unchanged by this card: the engine's ONE
+    // pre-image read and no plugin read of its own.
+    expect((reads.findOneOn['biz_deal'] ?? 0) - beforeSelf).toBe(1);
+    expect(lastSummary(storeFor)).toBe('Stage: open → won');
+  });
+
+  it('an UNTRACKED reference field changing pays ZERO reads', async () => {
+    const { engine, reads } = await boot();
+    await seed(engine);
+
+    const before = reads.findOn['crm_account'] ?? 0;
+    await engine.update('biz_deal', { referrer_id: 'acc_2' }, { where: { id: 'deal_2' } } as any);
+
+    expect((reads.findOn['crm_account'] ?? 0) - before).toBe(0);
+  });
+
+  it('a create pays ZERO reads (the branch is update-only)', async () => {
+    const { engine, reads } = await boot();
+    await seed(engine);
+
+    const before = reads.findOn['crm_account'] ?? 0;
+    await engine.insert('biz_deal', { id: 'deal_3', title: 'Third', account_id: 'acc_1' });
+
+    expect((reads.findOn['crm_account'] ?? 0) - before).toBe(0);
+  });
+
+  it('a delete pays ZERO reads (the branch is update-only)', async () => {
+    const { engine, reads } = await boot();
+    await seed(engine);
+
+    const before = reads.findOn['crm_account'] ?? 0;
+    await engine.delete('biz_deal', { where: { id: 'deal_2' } } as any);
+
+    expect((reads.findOn['crm_account'] ?? 0) - before).toBe(0);
+  });
+
+  it('ONE tracked reference change costs exactly ONE read', async () => {
+    const { engine, reads } = await boot();
+    await seed(engine);
+
+    const before = reads.findOn['crm_account'] ?? 0;
+    await engine.update('biz_deal', { account_id: 'acc_1' }, { where: { id: 'deal_1' } } as any);
+
+    expect((reads.findOn['crm_account'] ?? 0) - before).toBe(1);
+  });
+
+  it('TWO tracked references onto the SAME object still cost ONE read (batched, not per field)', async () => {
+    const { engine, reads, storeFor } = await boot();
+    await seed(engine);
+
+    const before = reads.findOn['crm_account'] ?? 0;
+    await engine.update(
+      'biz_deal',
+      { account_id: 'acc_1', partner_id: 'acc_2' },
+      { where: { id: 'deal_1' } } as any,
+    );
+
+    // Per-field resolution would measure 2 here; per-VALUE resolution 2 as well
+    // (and 4 once both sides are non-empty).
+    expect((reads.findOn['crm_account'] ?? 0) - before).toBe(1);
+    expect(lastSummary(storeFor)).toBe('Account: ∅ → Acme Corp; Partner: ∅ → Globex');
+  });
+
+  it('TWO distinct target objects cost exactly ONE read each', async () => {
+    const { engine, reads, storeFor } = await boot();
+    await seed(engine);
+
+    const beforeAccount = reads.findOn['crm_account'] ?? 0;
+    const beforeRegion = reads.findOn['crm_region'] ?? 0;
+    await engine.update(
+      'biz_deal',
+      { account_id: 'acc_1', region_id: 'reg_1' },
+      { where: { id: 'deal_1' } } as any,
+    );
+
+    expect((reads.findOn['crm_account'] ?? 0) - beforeAccount).toBe(1);
+    expect((reads.findOn['crm_region'] ?? 0) - beforeRegion).toBe(1);
+    expect(lastSummary(storeFor)).toBe('Account: ∅ → Acme Corp; Region: ∅ → APAC');
+  });
+
+  it('BOTH sides of one reference change are answered by the SAME read', async () => {
+    const { engine, reads, storeFor } = await boot();
+    await seed(engine);
+    await engine.update('biz_deal', { account_id: 'acc_1' }, { where: { id: 'deal_1' } } as any);
+
+    const before = reads.findOn['crm_account'] ?? 0;
+    await engine.update('biz_deal', { account_id: 'acc_2' }, { where: { id: 'deal_1' } } as any);
+
+    // Old id and new id are one `id: { $in: [...] }`, not two point reads.
+    expect((reads.findOn['crm_account'] ?? 0) - before).toBe(1);
+    expect(lastSummary(storeFor)).toBe('Account: Acme Corp → Globex');
+  });
+});
diff --git a/packages/plugins/plugin-audit/src/audit-writers.ts b/packages/plugins/plugin-audit/src/audit-writers.ts
index d980d2ea51..aad1380fca 100644
--- a/packages/plugins/plugin-audit/src/audit-writers.ts
+++ b/packages/plugins/plugin-audit/src/audit-writers.ts
@@ -12,6 +12,14 @@ import type { IDataEngine } from '@objectstack/spec/contracts';
 // argument for its own single definition. The `/core` subpath is the
 // engine-free surface of the same package.
 import { SECRET_MASK, collectMaskedReadFields } from '@objectstack/objectql/core';
+// [#7230] ADR-0079's record display-name contract, imported rather than
+// re-derived. `resolveDisplayField` IS the definition of "which field is this
+// object's human title" (`nameField` → deprecated `displayNameField` alias →
+// deterministic derivation). A local "try name, then title, then subject"
+// heuristic here would be a second de-facto contract that disagrees with the
+// picker, the search companion and the approval inbox the day an author sets
+// `nameField` — the same argument the SECRET_MASK import above makes.
+import { resolveDisplayField } from '@objectstack/spec/data';
 
 /**
  * Minimal structural view of `NotificationService.emit` (ADR-0030). Declared
@@ -301,12 +309,68 @@ function safeStringify(v: any): string {
   try { return JSON.stringify(v); } catch { return String(v); }
 }
 
+/**
+ * [#7230] Field types whose stored value is a FOREIGN RECORD ID rather than
+ * something a human can read. `user` is on the list because it is "a lookup
+ * specialized to the `sys_user` system object — stored IDENTICALLY (FK string
+ * column → sys_user.id)" (`field.zod.ts`), which is exactly the field class the
+ * measured symptom came from (`Rating Owner: ∅ → oBK25…`). `tree` is NOT on the
+ * list: it carries no `reference`, so there is no target object to read.
+ *
+ * The same three types, for the same reason, are what `plugin-approvals`
+ * resolves for its inbox display (`resolveLookupFields`) — one vocabulary for
+ * "this value is a reference", not two.
+ */
+const REFERENCE_FIELD_TYPES: ReadonlySet<string> = new Set(['lookup', 'master_detail', 'user']);
+
+/**
+ * [#7230] The referenced record ids carried by one lookup-field value.
+ *
+ * A single-value lookup stores one id; a `multiple: true` one stores an ARRAY
+ * (`field.zod.ts`: "Stores as Array/JSON"). Only the in-memory array shape is
+ * unpacked — a driver that hands the column back as an unparsed JSON string is
+ * left to the raw fallback rather than guessed at here, since parsing it would
+ * be this file inventing a storage contract it does not own.
+ *
+ * Objects are deliberately skipped: since #6656 both sides of the diff are raw
+ * driver rows, so an already-expanded `{id, name}` cannot reach here, and
+ * writing a limb for it would be consumer-side tolerance for a producer that
+ * does not exist (PD #12).
+ */
+function referenceIdsOf(value: any): string[] {
+  const one = (v: any): string | null => {
+    if (v === null || v === undefined || v === '') return null;
+    if (typeof v === 'string') return v.trim() ? v : null;
+    if (typeof v === 'number' || typeof v === 'bigint') return String(v);
+    return null;
+  };
+  if (Array.isArray(value)) return value.map(one).filter((v): v is string => v !== null);
+  const single = one(value);
+  return single === null ? [] : [single];
+}
+
 /**
  * Resolve a field value to its display string, preferring a select/picklist
- * option label over the raw stored value. Empty/missing → "∅".
+ * option label — or, for a reference field, the referenced record's title —
+ * over the raw stored value. Empty/missing → "∅".
+ *
+ * [#7230] `titlesFor` is the pre-resolved id → title map for THIS field's
+ * target object (see `resolveTrackedLookupTitles`). It is a lookup into an
+ * already-batched result, never a read: this function stays synchronous, and
+ * the callers that have no reference to resolve (`matchMilestone`'s `{token}`
+ * interpolation) pass nothing and keep today's behaviour exactly.
+ *
+ * An id with no entry in the map — record deleted, object unregistered, title
+ * field unresolvable — falls back to the raw id, which is what this function
+ * returned before the branch existed. The change is therefore restore-invariant:
+ * it can only replace an id with a title, never a title with an id.
  */
-function displayFieldValue(field: any, value: any): string {
+function displayFieldValue(field: any, value: any, titlesFor?: Map<string, string>): string {
   if (value === null || value === undefined || value === '') return '∅';
+  if (titlesFor && typeof field?.type === 'string' && REFERENCE_FIELD_TYPES.has(field.type)) {
+    const ids = referenceIdsOf(value);
+    if (ids.length > 0) return ids.map((id) => titlesFor.get(id) ?? id).join(', ');
+  }
   const options = field?.options;
   if (Array.isArray(options)) {
     for (const o of options) {
@@ -320,26 +384,77 @@ function displayFieldValue(field: any, value: any): string {
   return String(value);
 }
 
+/**
+ * [#7230] Every tracked-change field of `fields` that is a reference, grouped
+ * by TARGET OBJECT — the read plan for {@link resolveTrackedLookupTitles}.
+ *
+ * Grouping by target object (not by field, and emphatically not by row) is what
+ * keeps this off the write hot path: N tracked reference fields pointing at one
+ * object cost ONE read, and a write that changes no tracked reference field
+ * produces an empty plan and therefore no read at all.
+ */
+function planTrackedLookupReads(
+  fields: Record<string, any> | undefined | null,
+  oldVals: Record<string, any> | null,
+  newVals: Record<string, any> | null,
+): Map<string, Set<string>> {
+  const byObject = new Map<string, Set<string>>();
+  if (!fields || !newVals) return byObject;
+  for (const key of Object.keys(newVals)) {
+    const field = fields[key];
+    if (!field || field.trackHistory !== true) continue;
+    if (typeof field.type !== 'string' || !REFERENCE_FIELD_TYPES.has(field.type)) continue;
+    const reference = typeof field.reference === 'string' ? field.reference.trim() : '';
+    if (!reference) continue;
+    for (const raw of [oldVals ? oldVals[key] : undefined, newVals[key]]) {
+      for (const id of referenceIdsOf(raw)) {
+        let set = byObject.get(reference);
+        if (!set) { set = new Set<string>(); byObject.set(reference, set); }
+        set.add(id);
+      }
+    }
+  }
+  return byObject;
+}
+
 /**
  * ADR-0052 §5b — declarative activity. For fields declared `trackHistory: true`,
  * render the diff the writer already captured as a human-readable timeline
  * summary ("Stage: Proposal → Closed Won"; multiple changes joined by "; "),
- * using the field label and select option labels. Returns null when no tracked
- * field changed, so the caller falls back to the generic "Updated <object>".
+ * using the field label, select option labels and referenced record titles.
+ * Returns null when no tracked field changed, so the caller falls back to the
+ * generic "Updated <object>".
+ *
+ * [#7230] `translate` is the SAME locale-bound translator the three sibling
+ * summary branches already resolve through (`messages.activityCreated` /
+ * `messages.activityDeleted` / `messages.activityUpdated`, and `displayLabelFor`
+ * for the object name). This branch was the one never handed it, so a
+ * fully-localized page ended with an English field label — ADR-0053 /
+ * framework#3039 write-time localization, applied where it was missed. The key
+ * shape is the bundle's own (`objects.<object>.fields.<field>.label`), and a
+ * miss returns `undefined` so the authored def label, then the machine key,
+ * still answer exactly as before.
  */
 function renderTrackedChangeSummary(
+  objectName: string,
   fields: Record<string, any> | undefined | null,
   oldVals: Record<string, any> | null,
   newVals: Record<string, any> | null,
+  translate: (key: string, params?: Record<string, unknown>) => string | undefined,
+  lookupTitles?: Map<string, Map<string, string>>,
 ): string | null {
   if (!fields || !newVals) return null;
   const parts: string[] = [];
   for (const key of Object.keys(newVals)) {
     const field = fields[key];
     if (!field || field.trackHistory !== true) continue;
-    const label = (typeof field.label === 'string' && field.label) || key;
-    const from = displayFieldValue(field, oldVals ? oldVals[key] : undefined);
-    const to = displayFieldValue(field, newVals[key]);
+    const label =
+      translate(`objects.${objectName}.fields.${key}.label`) ??
+      (typeof field.label === 'string' && field.label.length > 0 ? field.label : key);
+    const reference = typeof field.reference === 'string' ? field.reference : undefined;
+    const titlesFor = reference ? lookupTitles?.get(reference) : undefined;
+    const from = displayFieldValue(field, oldVals ? oldVals[key] : undefined, titlesFor);
+    const to = displayFieldValue(field, newVals[key], titlesFor);
     parts.push(`${label}: ${from} → ${to}`);
   }
   return parts.length > 0 ? parts.join('; ') : null;
@@ -577,6 +692,91 @@ export function installAuditWriters(
     );
   };
 
+  /**
+   * [#7230] Referenced record TITLES for the tracked-change summary — id →
+   * title, per target object.
+   *
+   * ## Why this is shaped as a plan + one read per target object
+   *
+   * `sys_activity.summary` is composed at WRITE time, so anything this function
+   * does lands on the write hot path. One day before this change, #6656 / PR
+   * #6977 retired `captureBefore`'s redundant pre-image read from this exact
+   * path under maintainer ruling Option A+ — measured 2 → 1 reads per single-id
+   * write and 3 → 0 per predicate write. A per-row (or worse, per-value) title
+   * read here would hand that saving straight back, in the same file. So:
+   *
+   *  - **Zero reads is the default.** `planTrackedLookupReads` produces an empty
+   *    plan unless a field that is BOTH `trackHistory: true` AND a reference
+   *    type actually changed in this write. Every other write — the overwhelming
+   *    majority, including every create and delete — pays nothing, and
+   *    `#6977`'s counts are untouched. Pinned in `audit-lookup-summary.test.ts`.
+   *  - **One read per distinct target object**, never per field and never per
+   *    value: N tracked reference fields pointing at one object are answered by
+   *    a single `id: { $in: [...] }`. Same batching shape `plugin-approvals`
+   *    uses for its inbox display enrichment.
+   *  - **Only the id and the title column are selected**, so resolving a title
+   *    cannot drag a wide row (or a blob) through the write path.
+   *
+   * What it cannot batch away: `writeAudit` is dispatched PER ROW, so a
+   * predicate update over N rows that changes a tracked reference field on each
+   * pays N reads (one per row per distinct target object). That is inherent to
+   * per-row summary composition, not to this batching — and it is bounded by
+   * "the object declares a tracked reference field", which the audited-object
+   * pre-image read #6977 removed was not.
+   *
+   * ## Masking (#6656 non-regression)
+   *
+   * An explicit `nameField` pointer is honoured by `resolveDisplayField` even
+   * when it points at a title-INELIGIBLE type, so an object could in principle
+   * designate a credential field as its title. The read is skipped in that case
+   * rather than trusted to mask downstream: `collectMaskedReadFields` is the
+   * same contract predicate `ledgerView` masks with, so "no credential value
+   * reaches a user-facing activity summary" holds on this path by the same
+   * definition, not by a second one.
+   *
+   * Best-effort throughout: an unregistered object, an unreadable row or a
+   * failing driver leaves the id unresolved, and `displayFieldValue` renders the
+   * raw id exactly as it did before this branch existed.
+   */
+  const resolveTrackedLookupTitles = async (
+    api: any,
+    fields: Record<string, any> | null,
+    oldVals: Record<string, any> | null,
+    newVals: Record<string, any> | null,
+  ): Promise<Map<string, Map<string, string>> | undefined> => {
+    const plan = planTrackedLookupReads(fields, oldVals, newVals);
+    if (plan.size === 0) return undefined;
+    const sys = api.sudo();
+    const out = new Map<string, Map<string, string>>();
+    for (const [objectName, idSet] of plan) {
+      const def = getObjectDef(objectName);
+      const titleField = resolveDisplayField(def as any);
+      if (!titleField || titleField === 'id') continue;
+      if (collectMaskedReadFields(def).includes(titleField)) continue;
+      const ids = Array.from(idSet);
+      try {
+        const rows: any[] = await sys.object(objectName).find({
+          where: { id: { $in: ids } },
+          fields: ['id', titleField],
+          limit: ids.length,
+        });
+        const titles = new Map<string, string>();
+        for (const row of rows ?? []) {
+          const id = row?.id;
+          const title = row?.[titleField];
+          if (id === null || id === undefined) continue;
+          if (title === null || title === undefined) continue;
+          const text = String(title).trim();
+          if (text) titles.set(String(id), text);
+        }
+        if (titles.size > 0) out.set(objectName, titles);
+      } catch {
+        /* best-effort — an unresolvable reference renders as its raw id */
+      }
+    }
+    return out.size > 0 ? out : undefined;
+  };
+
   /**
    * [#6656, Option A+] The view the ledger records for one record.
    *
@@ -878,8 +1078,20 @@ export function installAuditWriters(
         summary = milestone.summary;
         if (milestone.type) activityType = milestone.type;
       } else {
+        // [#7230] The read plan is built from the SAME masked views the summary
+        // renders, and only reached once a milestone has declined — a write
+        // that changes no tracked reference field issues no read at all.
+        const trackedFields = getFieldDefs(ctx.object);
+        const lookupTitles = await resolveTrackedLookupTitles(api, trackedFields, oldValue, newValue);
         summary =
-          renderTrackedChangeSummary(getFieldDefs(ctx.object), oldValue, newValue) ??
+          renderTrackedChangeSummary(
+            ctx.object,
+            trackedFields,
+            oldValue,
+            newValue,
+            translate,
+            lookupTitles,
+          ) ??
           translate('messages.activityUpdated', { object: objectDisplay, label }) ??
           `Updated ${objectDisplay} "${label}"`;
       }