feat(audit-trail): record the id a primary key moved from [PRD-1321]

[bexchauveto]

Stacked on #1911 (PRD-1257): its base retargets to main once #1911 merges.

Closes PRD-1321. The Ruby twin is agent-ruby#394, already merged.

What was lossy

An update carries two states but is filed under one id. When a primary key is both writable (so the capture records it) and redacted, both sides hold the placeholder, the packed id is the only value left — and it speaks for the side the row was filed under, not the other one.

#1909 chose to withhold rather than answer the previous side from the id the record ended up with. That is correct, and it costs a caller squarely in scope the values they should have seen: /state loses the most, since it rebuilds from a delete row carrying the whole writable column set.

What this does

previous_record_id on the audit row, written on every confirmed update, and withhold.ts judges the previous side against it.

Written whether or not the key moved — this is the one place it departs from agent-ruby#394. That table had never shipped, so a null there can only mean the key held still. This one has: a null has to keep meaning written before this column existed, or a row from an older agent whose key did move would be judged by the id it moved to, which is exactly the leak #1909 closed. For the same reason the column arrives as 002-add-previous-record-id rather than an edit to 001, which deployed databases have already recorded as applied.

Ported from Ruby unchanged:

• a pending update's new side answers only with what it captured — the row is filed under the id the record had before the write, which says nothing about the state it was moving to;
• the column never reaches a client. Both response paths strip it.

Tests

• the previous side of a moved key is now released to a scope that covers the id it came from, and the new side withheld — the case that was lost;
• a pending update's new side stays withheld;
• the capture records the previous id on a move and on a no-move alike;
• the column is absent from the served payload;
• migration 002 applies, is idempotent, and the schema assertions cover the new column.

442 tests pass across test/audit-trail and test/routes/access.

Two things the existing tests caught while I wrote this, both worth knowing: an absent column read as known until I normalised undefined to null (which released a previous side it should have withheld), and decoding per side rather than per row made a bad id warn twice.

Also in this PR: the timeline's authors

Second commit, here because it needs #1911's timeline route.

The project-level author filter could only offer activity-log authors: GET /forest/_audit-trail answered no meta.availableUsers. It now does, on the first page only (no before), like the per-record route; later pages omit the key rather than send [].

• New optional store method listTimelineUsers (optional like listTimeline): the distinct authors under the timeline's filters and readable collections, ignoring the cursor. The SQL store shares the MAX()/GROUP BY query with listDistinctUsers. A store without it serves the rows with no availableUsers.
• Stacking fix: rows from listTimeline now carry previousRecordId too, so the timeline route strips it like the per-record paths do.
• Rebase conflict: feat(audit-trail): cross-collection timeline route [PRD-1257] #1911 changed scanServedValues to return { page, count, authors } and build the body in its caller. I kept that shape and strip previousRecordId where the caller builds the response.

Front reader: ForestAdmin/forestadmin#10033. Ruby contract added to PRD-1258.

Tests: route (first page announces with the filters and collections, later page omits, store without the method omits, previousRecordId absent) and SQL store (filters and collections honoured, empty collections match nothing). 484 tests pass across test/audit-trail and test/routes/access; lint clean.

🤖 Generated with Claude Code

Note

Record previous primary-key id in audit trail and add timeline route

• Confirmed update audit rows now store the pre-update packed record id as previousRecordId in instrument.ts, even when the key did not change
• Adds a nullable previous_record_id column and a (timestamp, id) index via new migrations in migrations.ts, with retry handling for concurrent startup races
• Adds a cross-collection GET /_audit-trail timeline route in audit-trail-timeline.ts with newest-first paging, shared filters, and author metadata. It is mounted only when the store exposes listTimeline
• Adds canUseAuditTrailTimeline to the capabilities response in capabilities.ts, set from whether the audit-trail store has listTimeline
• Permission-scope withholding in withhold.ts now evaluates update snapshots against their pre- and post-update ids
• Behavioral Change: previousRecordId is internal and stripped from all client responses in both the timeline and history handlers in audit-trail-timeline.ts and audit-trail.ts; existing audit tables get the new column via migration 003

^{Macroscope summarized 0e91320.}

[linear-code]

PRD-1321

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 16): buildMigrations	1

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (5)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/audit-trail/withhold.ts	100.0%
	packages/agent/src/audit-trail/migrations.ts	90.9%	273
	packages/agent/src/routes/access/audit-trail-timeline.ts	100.0%
	packages/agent/src/routes/access/audit-trail.ts	100.0%
	packages/agent/src/audit-trail/sql-store.ts	100.0%
	Total	96.3%

🤖 Increase coverage with AI coding...

In the `feature/prd-1321-agent-nodejs-carry-the-id-a-primary-key-move-came-from` branch, add test coverage for this new code:

- `packages/agent/src/audit-trail/migrations.ts` -- Line 273

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.