feat(audit): support optional audit records for entity record views

[KofTwentyTwo]

Summary

Add opt-in support for creating audit records when a user views entity records. Currently audits only cover insert, update, and delete operations. Some use cases require tracking read access for compliance, security, or usage analytics.

Proposed Behavior

• Opt-in at the same level that all audits are currently opted into (not a separate table-level flag)
• When enabled, a GET/view of a single record creates an audit entry
• Explore adding "table-level audits" that would cover both individual record views and list/query views on a table
• Audit detail level should be configurable (e.g., just the fact of the view vs. which fields were accessed)

Considerations

• Performance impact of auditing reads (far more frequent than writes)
• Should integrate with the existing pluggable audit handler system (PR feat(audit): add pluggable audit handler system #356)
• Table-level audit scope: individual record views vs. list/query views may warrant different audit granularity
• May want to support additional optional audit types in the future beyond just "view"

---

ADR: Design and Approach

Decision: Separate readAuditLevel field on QAuditRules

Read vs write audit granularity are independent dimensions. A table may want FIELD-level write auditing but only GET-level read auditing. Mixing these into a single enum creates combinatorial explosion. Adding a separate readAuditLevel field keeps them orthogonal.

Rejected alternatives:

• Adding to AuditLevel enum -- conflates two dimensions, breaks single-responsibility
• Separate QReadAuditRules class -- fragments configuration, users expect one place for audit config

New Enum: ReadAuditLevel

NONE          -- No read auditing (default)
GET           -- Audit single-record views only
GET_AND_QUERY -- Audit both individual views and table queries

Extend QAuditRules

Add private ReadAuditLevel readAuditLevel; field. Defaults to null (treated as NONE).

new QAuditRules()
   .withAuditLevel(AuditLevel.FIELD)
   .withReadAuditLevel(ReadAuditLevel.GET)

New Action: ReadAuditAction

Static convenience method executeAsync() called from GetAction/QueryAction. Captures QContext, submits to AuditHandlerExecutor thread pool. Never blocks or fails the read operation.

For GET (single record view):

• One audit record per viewed record
• audit.message = "Record was Viewed"
• audit.recordId = primary key of viewed record
• No auditDetail records

For QUERY (table/list view):

• One audit record per returned record
• audit.message = "Record was included in Query result"
• audit.recordId = primary key of each returned record
• No auditDetail records

Performance (critical for queries):

• executeAsync() is fire-and-forget: captures only primary keys + QContext, submits to thread pool, returns immediately. Query response goes back to UI before any audit I/O occurs.
• Background thread builds all audit records in memory, then does a single bulk InsertAction (1 DB call, not N).
• For piped/streaming queries: collect primary keys during pipe flow, audit once after pipe flushes.
• Only primary keys are captured, not full QRecord objects, keeping memory footprint small.

New Handler Type: AuditHandlerType.READ

Add READ to the existing AuditHandlerType enum. New ReadAuditHandlerInterface with handleReadAudit(ReadAuditHandlerInput). Allows custom read audit processing (e.g., streaming to external compliance systems).

Integration Points

GetAction -- after postRecordActions(), fire async read audit if record found.

QueryAction -- after postRecordActions(), fire async read audit. For piped queries, audit fires once after pipe flushes.

InputSource guard: Read audits only fire when InputSource == QInputSource.USER. System/process reads are not audited. This prevents audit cascading and ensures only user-facing operations are tracked.

Recursion Prevention

Two layers: (1) InputSource guard -- system reads during audit processing have SYSTEM input source, (2) audit system tables have no readAuditLevel configured.

Storage

Reuses existing audit/auditDetail tables. No schema changes. Read vs write audits distinguished by message text ("Viewed" / "included in Query result" vs "Inserted/Edited/Deleted").

Files to Create

File	Description
ReadAuditLevel.java	Enum: NONE, GET, GET_AND_QUERY
ReadAuditAction.java	Core action: checks rules, builds audit records, fires async
ReadAuditInput.java	Input model for ReadAuditAction
ReadAuditHandlerInterface.java	Handler interface for custom read audit processing
ReadAuditHandlerInput.java	Input passed to read audit handlers
ReadAuditActionTest.java	Unit tests

Files to Modify

File	Change
QAuditRules.java	Add readAuditLevel field
AuditHandlerType.java	Add READ value
AuditHandlerExecutor.java	Add executeReadHandlers()
GetAction.java	Add async read audit call
QueryAction.java	Add async read audit call
QInstanceValidator.java	Validate READ handlers + readAuditLevel consistency

Backwards Compatibility

Fully backwards compatible. readAuditLevel defaults to null/NONE. No schema changes. No new dependencies.

[darinkelkhoff]

.withReadAuditLevel(ReadAuditLevel.GET) is the same thing i first thought of, so yes.

for queries, my first thought was, that any record which was included in a query (from a user, not any query, e.g., one from a process) would get an audit itself, e.g., "Record 123 as included in a query result".

To the point of "a user did this query" vs. "the system did this query" - that feels like these audits should only happy based on InputSource (in the QueryInput or GetInput) being USER, not SYSTEM). I didn't see that mentioned in here. So that probably belongs in the "Integration Points" section (e.g., only if inputSource == USER)

re: "Never blocks or fails the read operation." - can we imagine some use-case where auditing is so critical that if the insert of the audit fails, that it should fail the GET operation? i can imagine it... but, then again, then you get into some double-commit situation, where you wouldn't want to audit the fact that there was a read until you could garuntee that the result was actually shown to the user... :headmelt: just food for thought i guess.

[KofTwentyTwo]

@darinkelkhoff Good feedback -- incorporating all three points:

1. Per-record query audits -- agreed. Changing from "one audit per query" to "one audit per returned record" with message "Record was included in Query result" and recordId = the PK of each returned record. This gives full traceability of who saw which records.

2. InputSource guard -- agreed, adding this. ReadAuditAction.executeAsync() will check inputSource == QInputSource.USER before submitting any work. System/process reads are not audited. This is the first layer of recursion prevention (second layer: audit system tables have no readAuditLevel).

3. Failure behavior -- leaving as fire-and-forget for now. The double-commit problem you raised is real -- you can't guarantee the user actually saw the data if the audit insert succeeds but the response fails. Keeping it async/non-blocking for v1. Could revisit with a FAIL_OPERATION policy on read audit handlers in the future if a compliance use case demands it.

Performance approach for per-record query audits:

• executeAsync() is fire-and-forget: captures only primary keys + QContext, submits to thread pool, returns immediately
• Query response goes back to UI before any audit I/O occurs
• Background thread builds all audit records in memory, then does a single bulk InsertAction (1 DB call, not N)
• For piped/streaming queries: collect primary keys during pipe flow, audit once after pipe flushes
• Only primary keys are captured, not full QRecord objects

Updated the ADR in the issue description accordingly.

[darinkelkhoff]

Mmm, piped/streaming queries… ugh… the whole point of those is, they don't ever collect "all the things"... it makes me sad to think that they might now collect "all the ids"... esp. if it were to happen by-default (e.g., in instances where read-audits aren't happening). "hmm". If your intent is to only capture query screen & get/view screen, then i'd say, streamed/piped queries don't apply - as those aren't piped use-cases. But - Export or Reports… would one want/need to audit reads for those? I can’t recall if inputSource will be USER for those or not. There might be cases where this gets tricky, to know if a Query is exactly what you're looking to audit or not here. An additional tool to help identify if a particular Get or Query is or isn’t one that should be audited as this kind of “read" is the QContext.actionStack (which would have to be captured before an async fire-and-forget).

[KofTwentyTwo]

@darinkelkhoff Good call on piped/streaming queries. Exports and reports aren't really "user viewed this record" in the compliance sense, and auditing every record in a 100k-row export would generate noise without real value.

For v1 we're intentionally skipping piped queries -- GET_AND_QUERY audits non-piped queries only. The QueryAction integration guards on recordPipe == null before firing the read audit.

The actionStack idea is solid as a future refinement. If we ever need to distinguish "user browsing a table" from "process-driven query that happens to have USER input source", the stack gives us that signal. We'd capture it before the async handoff. Noting it here for when/if we need finer-grained filtering beyond InputSource.