feat(audit-trail): cross-collection timeline route [PRD-1257]

[bexchauveto]

fixes PRD-1257. Stacked on #1910 → #1909.

GET /forest/_audit-trail serves every collection at once, newest first, so the project-level activity page can show before/after values rather than activity logs alone. Rows already carry collection and recordId, so the front can render "…on the Customer joe@ex.ample" and link it.

{ "data": [ /* rows */ ], "meta": { "cursor": { "before": "2026-01-05T00:00:00.000Z", "excludeIds": [12, 11] } } }

Values: no admin gate (changed on 8 October)

This PR first carried an admin gate on the timeline's values (restrictsProjectAuditValuesToAdmins, moved here from the withdrawn #1908). Commit 4bf169f7a drops it: a caller who can read a collection gets its rows with previousValues / newValues, whatever their permission level.

Why that holds: someone who can read the collection can already read each record's history one at a time, so the feed serves the same values in aggregate (the "aggregation boundary, not a data barrier" framing of PRD-1259). Who can open the project's Activity Logs page at all is decided per team by Forest (featuresDeactivated / TeamDeactivatableFeature.activityLogs, enforced by the front and private-api). This route does not see that team setting; it only returns what the caller can read anyway.

The capability changes with it: canUseAuditTrailTimeline, true only when the store implements listTimeline. It replaces restrictsProjectAuditValuesToAdmins, which the front was using as a proxy for "this agent mounts the route". Nothing has shipped with the old flag, so there is no compatibility to keep.

Permissions

This is the first audit route with no single record to authorize against:

• only collections the caller can read are queried;
• a collection the caller sees only through a record-level scope is left out entirely — a scope can't be evaluated across a whole timeline without fetching every record it names, and the row alone would reveal that a record the caller cannot read exists and was touched.

Cost of that second rule: a caller scoped on every collection gets an empty timeline. Say the word if you'd rather have the rows with values blanked instead.

Cursor contract (Ruby implements against this)

Offset paging is wrong here: a project-wide feed grows at the head, so skip shifts rows across pages. page[size] still applies (default 20, cap 100).

param	format	effect
before	ISO instant	inclusive upper bound on timestamp
excludeIds	comma-separated integers	row ids already served at that boundary

Inclusive on purpose: rows sharing the boundary timestamp must not fall between two pages, so they come back and excludeIds drops the ones already sent. Ties order by descending id. A timestamp holding more rows than fit on one page accumulates its exclusions across pages. meta.cursor is null on the last page, and also when the walk cannot move past the current timestamp — see the nextCursor comment for the ceiling that guards (ids past 2^53, which fromRow rounds) and its upgrade path.

Filters

The record route's, minus fields (a column name means nothing across collections): userIds, operation, startDate/endDate/timezone, search — parsed by the same code, now in src/audit-trail/query-params.ts so the two routes cannot drift.

Store

listTimeline is optional on AuditStore: adding a required method would break anyone with their own store. A store that doesn't implement it doesn't get the route mounted.

Tests

16 route cases (permission sweep, scope exclusion, empty-without-store-call, filter forwarding, five cursor cases incl. the no-progress guard, a non-admin served the values, conditional mounting), 7 sql-store cases, capability-payload cases including canUseAuditTrailTimeline with and without listTimeline. 1675 passed, lint clean.

🤖 Generated with Claude Code

Note

Add cross-collection audit-trail timeline route with permission gate

• Adds a project-level GET /_audit-trail route (audit-trail-timeline.ts) that returns audit rows across collections the caller can read without a record-level scope, with cursor pagination that handles timestamp ties by excluding already-served ids
• Adds listTimeline as an optional AuditStore method with a SQL implementation in sql-store.ts, plus a new timestamp/id index migration (002) for existing audit tables
• Moves user, operation, field, search, and date parsing into a shared module (query-params.ts) so per-record routes and the timeline route use the same rules
• The route and the canUseAuditTrailTimeline capability flag are only exposed when the store implements listTimeline; stores without it keep working and skip mounting
• Behavioral Change: audit migrations now include a tracked migration 002 that creates the timestamp/id index on existing tables, including tables that already applied migration 001

^{Macroscope summarized 6c72f5a.}

[linear-code]

PRD-1257

[qltysh]

2 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 5): toLocalInstant	2

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (6)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/audit-trail/migrations.ts	100.0%
	packages/agent/src/routes/index.ts	100.0%
	packages/agent/src/routes/access/audit-trail.ts	100.0%
	packages/agent/src/audit-trail/sql-store.ts	100.0%
	packages/agent/src/routes/access/audit-trail-timeline.ts	100.0%
	packages/agent/src/audit-trail/query-params.ts	100.0%
	Total	100.0%

🚦 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.

[arnaud-moncel]

LGTM