[kriszyp]

⊙ Problem

harper#3928 (milestone v5.4) turns storage.rocks.transactionLogAbortMarkers on by default. The docs never mention the setting. Operators would not learn that failed transactions now disappear from log readers, that conflicting writes now fail with a 500 or 503 instead of retrying forever, that false brings back 5.3 behavior, or that 5.3.4 and earlier must not read logs a 5.4 node wrote. It also adds an opt-in storage.rocks.transactionLogWriteIntents.

🤔 Is the requirement right?

Yes. A changed default with a one-way downgrade boundary has to be in the configuration reference and the 5.4 upgrade notes.

💡 Solution

• A new storage.rocks.transactionLogAbortMarkers entry in Storage Tuning: what readers skip, the 500/503 bounds and their exceptions, how to turn it off and the process restart, and the downgrade boundary.
• A transactionLogWriteIntents entry after it: what it does, its cost, restart.
• A one-line entry in the storage options list, and a cross-link from the transaction-log page.
• Both settings added to the "needs a full restart, not restart_service" lists in both set_configuration pages.
• A 5.4 upgrade note (downgrade) and a release-note section.

🤔 New setting, not a changed default

The release note calls it new and on by default. No 5.3 release has the setting, so for a 5.3 user it is new. It was opt-in only in the 5.4.0 alphas, so it gets an "added" badge. The transaction-log paragraph gets "changed", since it describes existing log behavior.

🤔 Write intents in this PR

Write intents do nothing with markers off, and both settings ship in harper#3928, so they share this PR. Easy to split out if preferred.

🤔 What is left out

The 503 deadline is longer for Harper's internal component-deploy writes. The docs do not mention it because no client request can set that budget. Retry and deduplication details are left out, as the brief asked. Both deferred nits below are tracked in Recheck the transactionLogAbortMarkers docs when harper#3928 merges (#782).

🔧 Changes

• reference/database/storage-tuning.md: new ## RocksDB Transaction Log section with the setting's entry, then the transactionLogWriteIntents entry. One sentence under storage.maxTransactionQueueTime says the same duration limits conflict retries, which fail with a different 503.
• reference/configuration/options.md: the new rocks.transactionLogAbortMarkers bullet and rocks.transactionLogWriteIntents bullet; the maxTransactionQueueTime bullet names the second 503.
• reference/database/transaction.md: one paragraph saying failed transactions are left out of the log by default.
• reference/configuration/operations.md (intro, cluster restart note) and reference/operations-api/operations.md (set_configuration): both settings join threads.v8Flags in the process-restart lists.
• reference/analytics/overview.md: one sentence telling the TRANSACTION_COMMIT_CONFLICT_TIMEOUT 503 apart from the overload 503.
• release-notes/v5-lincoln/5.4.md: an Upgrade Notes paragraph and a ## Transactions section, whose last paragraph introduces write intents.

✅ Verification

• Facts checked against harper#3928's head c8dfa03: resources/transactionLogAbortMarkers.ts (default, off values, read once per process), resources/DatabaseTransaction.ts (40-conflict cap, deadline from storage.maxTransactionQueueTime, the exceptions, retryable), and server/REST.ts (retryable: false in the error body).
• Write intents: default false and read once per process (latchWriteIntents, in a harper#3928 commit not yet on its head 1564a87); markers-only per rocksdb-js v2.13.0 transaction_handle.cpp.
• Downgrade boundary: harper and harper-pro v5.3.4 pin rocksdb-js 2.11.0 and v5.3.5 pins 2.13.0, with tags checked against ls-remote. rocksdb-js has the abort flag at v2.13.0, not at v2.11.0 or v2.12.0.
• npm run build passes, and every new anchor shows up in the built HTML. format:check, lint, typecheck, test:examples and test:workflows pass.
• Not run against a live Harper: harper#3928 is unreleased.

Docs for HarperFast/harper#3928. This PR must merge after it:

Depends-on: harper#3928

PR QA: skipped @ c60518a — documentation-only PR; PR QA covers harper and harper-pro

Signed: Claude Opus 5.5

🤖 Generated with Claude Code

Related PRs: #762 overlaps (adjacent storage-tuning paragraph), #772 overlaps (end of RocksDB Memory and the rocks.* bullets), #777 overlaps (same restart-exception sentence in operations.md), 1 others independent

Complexity: easy

Deferred findings

• a69043af6e3feeee nit documentation — reference/database/storage-tuning.md — Retry bounds omit refusal-count scope and larger explicit timeoutBudget — filed Recheck the transactionLogAbortMarkers docs when harper#3928 merges #782
• 3169e1b09af269e1 nit documentation — reference/database/storage-tuning.md — Documented default true and false/0/no/off parsing depend on harper#3928 merging — filed Recheck the transactionLogAbortMarkers docs when harper#3928 merges #782

Origin — the dispatch brief this PR was written from

Document the transactionLogAbortMarkers default change in 5.4

Document the Harper 5.4 change to storage.rocks.transactionLogAbortMarkers (Harper PR HarperFast/harper#3928).

What changed:

• storage.rocks.transactionLogAbortMarkers now defaults to on (it was off). With it on, when a transaction fails after writing its transaction-log batch, the batch is marked aborted, and every log reader (replication, subscriptions, audit log reads, crash replay) skips it.
• To keep the old behavior, set it to false. The value is read once at process start, so changing it needs a full restart.
• With it on, a write that keeps conflicting is now always bounded. It fails with a 500 after 40 conflicts, or a 503 (TransactionCommitConflictTimeoutError) when the commit-conflict time limit passes. Before, a write whose log entry was already written could retry without limit. Replicated writes are still never given up.
• Upgrade and downgrade: a 5.3 build older than the one that pinned rocksdb-js 2.13.0 cannot tell aborted batches apart, so it must not read transaction logs that a 5.4 node wrote with markers on. 5.3 releases that carry the rocksdb-js 2.13.0 pin are safe.

Where: the configuration reference entry for storage.rocks.transactionLogAbortMarkers (add one if missing), and the 5.4 release notes or upgrade notes (default change, downgrade requirement). Keep it short and user-facing. Do not describe internal retry or dedup mechanics.

_{Dispatch: task docs-harper-3928 · queued by task:harper-abort-marker-adoption · ran by claude/opus/xhigh · worker kzyp-xps-1}

_{Ready-For-Promotion: e6211c1 urgency=normal late=none}

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex; adjudicated=domain; declined=cursor-grok,muse; rounds=6; full=1 @ e6211c1}

_{Review-Attention: skim ~2m (decisions: write-intents-scope-creep, summary-precision) @ e6211c1}

[gemini-code-assist]

Code Review

This pull request updates the documentation across several files to introduce and explain the new storage.rocks.transactionLogAbortMarkers configuration setting in Harper v5.4.0. This setting ensures that failed transactions are marked as aborted in the RocksDB transaction log, preventing infinite retries on conflicts and ensuring they are skipped during replication, subscriptions, and audit logs. The review feedback focuses on improving the clarity and style of the documentation. Key suggestions include avoiding the use of the <VersionBadge> component mid-sentence, splitting critical limitations and downgrade warnings into separate sentences instead of using semicolons, and grouping related behaviors together to avoid grammatically disjointed phrasing.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-780

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-780

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-780

This preview will update automatically when you push new commits.

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.