## Problem Both write ingresses read three keys out of the PSR-3 `$context` array under names no module owns: `chain`, `action` and `resource`. - `src/Logger/AuditTrailLogger.php:84` and `:254` - `$context['chain']` - `src/Logger/AuditTrailLogger.php:149` - `$context['action']` - `src/Logger/AuditTrailLogger.php:150` - `$context['resource']` - `src/AuditTrail.php:117` - `$context['chain']` `$context` is a namespace shared with every other logger and every other module that logs. A caller that uses one of those three words for its own purposes is not doing anything wrong: `chain` is what a queue worker calls the chain of jobs it ran, `action` is what a form or a plugin calls the operation it just performed, and `resource` is what half of Drupal calls the thing being acted on. None of those callers knows this module exists, which is precisely the situation `mode: auto` is documented for. ## What a collision does `chain` is a control key, read before anything else and honored on both ingresses, and it decides in both directions. - `chain === FALSE` in the logger is an unconditional early `return` at line 85: no row, no dropped-event report, nothing in the other loggers to say the audit trail declined the entry. On the structured path the key defaults to `TRUE`, so any falsy foreign value suppresses there too. A foreign key silently removes entries from a chain whose whole purpose is to be complete. - A truthy foreign value does the opposite. `shouldChain()` at line 254 treats `chain: TRUE` or any non-empty string as an unconditional opt-in, ahead of the chain entity's mode. So a foreign key can inject rows into a chain the operator deliberately set to `mode: flag`, which is the mode that exists to record only what the structured API sends. `action` and `resource` are content keys, and they do more than label a row: - Both are written to the row's `action` and `resource` columns, and `Chain/ChainPayload.php:49-60` lists both among the ten signed columns. So a foreign value is covered by the SHA-256 hash and the HMAC, and the row verifies intact. Tamper-evidence is evidence about what happened to a row *after* it was written; it cannot see a value that was already wrong at signing time. - Both are then handed to `ChainFilters::decide()` at line 162 - `$action` as the action, `$resource` wrapped in the `AuditTrailSubject`. A chain's filters are the operator's statement about what that chain records, evaluated against exactly those two values. A foreign value can therefore make a chain drop a row the operator configured it to keep, or keep one it configured it to drop. - `action` is a dispatch key elsewhere too: `audit_trail_tsa` selects anchor rows by `action = 'tsa_timestamp'` (`modules/audit_trail_tsa/src/Tsa/ChainTimestamper.php:670`) and refuses to verify a row whose action is not that (`:283`). Read together: a foreign log context can suppress part of an audit row, or forge part of one, and the result is signed and verifies clean. ## The module already has the convention Metadata threaded between this module's own parts carries an `_audit_trail_` prefix, and every other context key it reads follows it: `_audit_trail_permanent` (`src/AuditTrail.php:244`), `_audit_trail_correlation_id` (`Logger/AuditTrailLogger.php:208`), `_audit_trail_already_chained` (`:124`), and `_audit_trail_entity_permanent_fields` / `_audit_trail_entity_selected_fields` in `audit_trail_entity`. Those cannot collide with anything. The three keys that decide whether a row exists and what it says are the three that do not follow the convention. ## Proposed resolution Claim one key, and nest under it: ```php $context['audit_trail'] = [ 'chain' => 'orchestra', 'action' => 'instance.start', 'resource' => 'orchestra_instance:41', ]; ``` With the shorthands the current `chain` key already carries, so the common cases stay one line: ```php $context['audit_trail'] = FALSE; // never chain this $context['audit_trail'] = 'orchestra'; // chain, into this chain ``` One key to document, one key to grep for, one name a third party has to the flat, prefixed form they already are. ## Cost This is the module's integration surface, so the change is wide even though it is shallow: the logger, the structured API's `chain` read, `docs/consumers.md` (the context-key table and every example), and the existing tests that build a context array. Downstream, every consumer that names a chain or sets an action through the PSR-3 path has to move to the nested key. ## Not in scope `audit_trail_tsa` reads `tsr_b64`, `anchored_hash` and `tsa_id` as bare keys out of a row's stored `context_permanent` (`Tsa/ChainTimestamper.php:303-305`). That is a different namespace from the incoming PSR-3 context: those keys are written by the module into rows it minted itself, so nothing collides with them by accident. Any module can already write any action and any permanent payload through `event()`, which is an authorization question about the structured API, not a naming one, and does not belong here. Folding the five `_audit_trail_` context keys into the nested key as well would give one convention instead of two, but those keys are already collision-safe, so it would churn consumers for no integrity gain. --- AI-Generated: Yes (Claude Code was used to read both write ingresses and draft this issue summary. Every claim above was checked against the code: the four bare `chain` / `action` / `resource` reads, the early `return` at `AuditTrailLogger.php:85`, the mode bypass in `shouldChain()`, the `ChainFilters::decide()` arguments, the ten signed columns in `ChainPayload::COLUMNS`, the two `action = 'tsa_timestamp'` gates in `audit_trail_tsa`, and the five prefixed context keys. No code has been written for it yet.)