## Problem/Motivation Found in the third release audit of 1.x at `6522bd8`. One merge request covers all of it. ### Part 1: three defects 1. **Archiving a large existing chain in one command runs out of memory.** `drush audit_trail:archive --chain=X --from=1 --to=N` first calls `ChainArchiver::ensureSegmentCoverage()` over the whole range the operator gave. For every uncovered gap, `findLinkedRuns()` loads the id, hash and previous hash of every row in it with `fetchAll()`. On a site that turns retention on for a chain that already holds millions of rows, the command holds all of them in memory at once (about 400 bytes a row, so 5 million rows take 2 GB) and dies before writing anything. Cron goes through the same code but caps each run at 20,000 rows. The command has no cap. 2. **`drush audit_trail:archive-verify` dies with a stack trace when the archive directory is refused.** The command catches `\RuntimeException` only. Without `--path`, `SegmentReader::verifyArchivedSegment()` resolves the configured directory, and `ArchiveLocation::resolve()` throws `\InvalidArgumentException` when that directory is blank or web-accessible. The exception escapes and the command crashes instead of printing the reason and exiting with 2, as every other command does. 3. **The checkpoint lock notice says something that did not happen.** When `AuditTrailVerifier::mintCheckpoint()` cannot take the checkpoint lock, it logs "could not acquire @lock within 5s". The `5.0` it passes to `acquire()` is the lock's lifetime (`LockBackendInterface::acquire()`), not a wait: the call returns at once. An operator reading the notice looks for a 5-second stall that never occurred. ### Part 2: code shape, naming, texts ### Duplication and layering - `AuditTrailChainWriter::acquireChainLockOrThrow()` restates the acquire, deadline and wait loop that `ChainWriteLock::acquireNamedLock()` already provides. - `ChainArchiver::acquireChainWriteLock()` is a private one-line forward to `ChainWriteLock::acquireWithDeadline()`. - The TSA bridge reads chain rows itself, beside an injected `ChainRepository`. `ChainTimestamper::verifyAnchorBinding()` re-implements `ChainRepository::getRowHash()`. `AutoTimestamp::stampDueChains()` reads the head row's action through its own `Connection`, which it holds for that one query. - The status report says the chain-write lock "could not be acquired within 5 seconds", restating `ChainWriteLock::CHAIN_WRITE_LOCK_REQUEST_DEADLINE_S` as a literal. - The five retention stage keys (`transient_purge_after` … `compact_after`) are spelled out ten times across `AuditTrailChainForm` and `AuditTrailSettingsForm`. Both forms parse the same ISO 8601 durations under the same "zero only where the stage can be switched off" rule. The chain form also refreshes its delay preview when *Compact segment rows after* changes, though the preview does not show compaction. - "An event missing from the settings is recorded" is coded three times: `AuditTrailFileRecorder::isEventEnabled()`, `AuditTrailUserAuthHooks::isEventEnabled()` and `EventOptInSettingsFormBase::buildForm()`. - `SegmentOperationFormBase` is an abstract template base with one subclass, `AuditTrailSegmentArchiveForm`. - Smaller items: `AuditTrailEntriesFilterForm` copies `RfcLogLevel::getLevels()` key by key in a loop, `AuditTrailSegmentsController::buildLifecycleCell()` formats one date four times, `TsaProviderUsage` has two single-use private wrappers, and `AuditTrailChain::getCompactAfter()` applies `?? NULL` to a nullable property. ### Accessibility - On the chain form, every contributor and filter row has a button named "Remove". A screen reader's button list shows several identical "Remove" entries and does not say which plugin each one removes. ### Naming - Five test methods end in a preposition or a particle: `testTheIndexCarriesEveryColumnTheCountsFilterOn`, `testEveryVarcharColumnIsAccountedFor`, `testTheBreakNoticeIsNotChainedIntoTheChainItReportsOn`, `testVerifyWalksAtTheDepthTheOperatorAsksFor`, `testStagingFailureIsReportedAndTheTransactionCarriesOn`. - A TSA provider is pending, active or inactive, and it is *deactivated*. The deactivate form, the delete form, the providers help and the schema description of `deactivated` call it *retired*, which is the signing secret's word for a different lifecycle. ### Texts and help - The schema description of `audit_trail.context_permanent` says it holds "every key emitted by contributors under the `safe` tier, plus the PSR-3 placeholder substitutions". No `safe` tier exists, and placeholders are written to `context_transient`. - The audit_trail_entity settings help names a *Permanent fields* list, but the field is called *Fields kept permanently*. The help also describes per-bundle setup first, while the form starts from one rule shared by every bundle. - The TSA settings form shows Markdown backticks literally inside an HTML description. - `ChainTimestamper::timestampChain()` writes the providers page as a hard-coded path, which is wrong under a base path or a language prefix. The stale-verification entry on the status report tells its reader to "check `/admin/reports/status`", the page they are already on. - Several test docblocks tell the story of a past defect ("until now the docblock told them the wrong ones", "the regression that started this file") instead of saying what they pin. ## Proposed resolution ### Part 1 1. Detect linked runs from a stream: `ChainRepository::streamRows()` reads the gap in batches of 1,000, and only the three columns the run detection compares. Memory then depends on the batch, not the range. 2. Catch `\Throwable` in `archive-verify`, like the other commands, so the refusal is printed and the command exits with 2. 3. State what the notice means: another verification is minting this chain's checkpoint right now, and the next run advances it. Tests, each failing on 1.x: - Coverage over 30,000 rows of one chain keeps peak memory growth under a few megabytes; on 1.x it grows by about 20 MB. - `archive-verify` on a segment with a blank archive directory exits with 2 and names the refusal; on 1.x it throws. - With the checkpoint lock held elsewhere, the notice no longer claims a 5-second wait. ### Part 2 - Call `ChainWriteLock::acquireNamedLock()` from the writer, and call `ChainWriteLock::acquireWithDeadline()` directly in the archiver. - Add `ChainRepository::getRowAction()`. The TSA bridge reads through `getRowHash()` and `getRowAction()`, and `AutoTimestamp` no longer needs a database connection. - Fill the status-report seconds in from the constant. - Add `RetentionThresholds::STAGE_KEYS`, plus one parser in `RetentionOrderTrait` used by both forms. Refresh the preview only for the fields it shows. - One `EventOptIn::isEnabled()` reader in the base module, used by both bridges and by the opt-in form. - Fold `SegmentOperationFormBase` into the archive form, and remove the smaller duplicates. - Name each remove button after its plugin. - Rename the five test methods. Say *deactivated* and *inactive* for TSA providers. - Correct the schema description, the entity help and the TSA description. Name the providers page instead of writing its path, and point the status-report line at the cron entry of that report. - Rewrite the history docblocks to describe what each test pins. ## Remaining tasks None. ## User interface changes Corrected texts and help. Each remove button on the chain form is named after its plugin. ## API changes - `ChainRepository::streamRows()` takes an optional list of columns to read. - `SegmentOperationFormBase` is removed. - `ChainRepository::getRowAction()`, `EventOptIn`, `RetentionThresholds::STAGE_KEYS` and `RetentionThresholds::OPTIONAL_STAGE_KEYS` are added; `EffectiveDelays::OPTIONAL_THRESHOLD_KEYS` is removed. - `AutoTimestamp`'s constructor loses its `Connection` argument. ## Data model changes None. ## AI disclosure AI-Generated: Yes (Claude Code was used to help draft this issue summary and to write the fixes and their tests during a release audit. I reviewed both, and each new test was confirmed to fail against 1.x and to pass with the change.)