feat(audit-trail): filter the per-record history by operation [PRD-1256]

[bexchauveto]

fixes PRD-1256. Stacked on #1909 → #1908.

GET /forest/_audit-trail/{collection}/{recordId} accepts an operation query param.

The contract (Ruby copies this verbatim)

• param name: operation (singular, like search; the store field is operations)
• format: comma-separated — operation=create,delete — consistent with userIds and fields
• set: closed — create, update, delete, action, action_failed
• unknown value: 400, not dropped

That last one departs from userIds, which drops junk tokens. Deliberate: a silently ignored filter returns unfiltered rows into a list the caller believes is filtered — the exact failure the ticket warns about. userIds can afford to be lenient because a partial id list still filters; an ignored operation doesn't filter at all.

Empty or whitespace-only → no filter, same as fields.

Pushed into the query, not applied after

operations lands in the shared filters object, so it reaches listByRecord, countByRecord and listDistinctUsers. meta.count and meta.availableUsers therefore agree with the rows, and paging stays correct — filtering the fetched page would have desynced all three.

SQL side is one clause in buildHistoryWhereClause; the in-memory test store gained the same filter so the double stays honest.

Tests

6 route cases (single, comma-separated, count + author list, 400 on unknown, empty ignored) and a sql-store case covering listByRecord and countByRecord together. 1651 passed, lint clean.

🤖 Generated with Claude Code

Note

Add operation filter to audit-trail history and apply search/fields after permission withholding

• The audit-history route accepts a comma-separated operations filter (create, update, delete, action, action_failed). Unknown values return a validation error; the filter is passed to the store for row, count, and author queries in audit-trail.ts and sql-store.ts.
• For scoped records that are gone (deleted before or during the request), fields and search no longer match captured values. Instead, rows are read in batches of 500, permission withholding is applied, and matching runs in memory against served values, action, and user identity. Pagination, total count, and the first-page author list come from these served-value matches.
• Behavioral Change: gone scoped-record histories with search/fields now return results based on post-withholding values, so search terms present only in withheld values produce no rows; see AuditTrailRoute.listServedMatches in audit-trail.ts.

^{Macroscope summarized d533447.}

[linear-code]

PRD-1256

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (2)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/routes/access/audit-trail.ts	100.0%
	packages/agent/src/audit-trail/sql-store.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.

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 4): handleHistory	1

[bexchauveto]

Rebased. #1908 is closed — its admin gate was scoped wrong and moved to #1911 (project-level timeline only). This PR is unchanged in substance; the inert permissionLevel: 'admin' that its new tests carried has been dropped, since the record route is no longer gated.

[arnaud-moncel]

LGTM