[kriszyp]

⊙ Problem

Harper v5.4.0 changes two replication behaviors the sharding page does not describe. Require a super user for X-Replicate-To and the operations API replicateTo/replicatedConfirmation fields returns HTTP 403 to other callers. Distinguish replication confirmation failure from a local write failure marks a failed confirmation after a local commit with replicationUnconfirmed: true and retryable: false. Retrying callers must know the write landed.

🤔 Is the page ready now that both harper PRs have merged?

Yes. Both merged to main with milestone v5.4, and the newest harper tag is v5.3.3, so the v5.4.0 badges hold. A 5.4 release-notes entry is not included, because the task limited this PR to the sharding page.

💡 Solution

In reference/replication/sharding.md, tagged v5.4.0:

• REST: X-Replicate-To needs super_user; others get 403.
• Operations API: the same for replicateTo and replicatedConfirmation, for the operations that accept them.
• New section: what replicationUnconfirmed means, an example error, and why not to retry blindly.
• Programmatic control: replicateTo set in a resource method, replicatedConfirmation through a new transaction() context, and a warning against copying request input. The old example's count inside put() did nothing.
• ⚠️ Look hardest: the limits on which database is confirmed and what a missing flag does not prove.

🤔 Which wording wins where this PR and #723 disagree?

Clarify confirm/replicatedConfirmation any-N semantics in the sharding docs edits the same file. Its text says a too-large confirmation count is rejected after the write took effect locally. Harper main refuses it before the write lands, and this PR says so. Whichever merges second needs a small rebase and one corrected sentence.

🤔 Badge at the start of a paragraph, or plain "As of v5.4.0"?

Gemini suggested plain text for the two "changed" notes. I kept the badge: the approved patch used it, and 21 other reference paragraphs open the same way. The new section's badge sits on its own line under its heading, as CONTRIBUTING.md describes. Switching is a two-line edit.

✅ Verification

• npm run build passes and prettier --check is clean.
• Each claim was checked against the code of harper#3084 and harper#3187. The example error's message and 504 status come from the confirmation timeout in harper-pro replication/knownNodes.ts.
• The programmatic claims were traced in harper main: resources/transaction.ts copies replicatedConfirmation only when a transaction starts, and Table.getResidency reads context.replicateTo at write time. The transaction() example follows harper's replicationConfirmationOutcome tests.
• The first-database limit applies to LMDB too: Make replicatedConfirmation wait for peers on LMDB sends LMDB commits through the same confirmReplicationAfterCommit path (resources/LMDBTransaction.ts).
• The merge commits of harper#3084, #3187 and #3392 are all in v5.4.0-alpha.1.
• Not run against a live Harper: replication needs Harper Pro. Both harper PRs carry their own tests for these paths.

Depends-on: harper#3084, harper#3187

_{🤖 Generated by Claude Sonnet 5.5 via Claude Code (session); posted via @kriszyp.}

Related PRs: #723 overlaps (same page; adjacent insertions after the programmatic example), #753 overlaps (same page; edits the programmatic example and adds its own replicationUnconfirmed paragraph, so whichever merges second keeps one copy)
Complexity: medium

Origin — the dispatch brief this PR was written from

Open a draft PR in HarperFast/documentation that documents two Harper v5.4.0 replication changes in reference/replication/sharding.md: (1) X-Replicate-To and the operations API replicateTo/replicatedConfirmation fields now require super_user (HarperFast/harper#3084), and (2) a confirmation failure after a local commit is reported with replicationUnconfirmed: true and retryable: false (HarperFast/harper#3187). Apply the approved patch below, adjusting only what is needed to fit the current file and the repo's doc conventions.

Acceptance

Draft PR on HarperFast/documentation changing only reference/replication/sharding.md (plus any index/sidebar change the repo requires), using the repo's VersionBadge convention, building cleanly with the repo's docs build/lint. PR body links harper#3084 and harper#3187 and states the merge order.

_{Dispatch: task documentation-replicate-to-superuser-and-unconfirmed · queued by kriszyp-session · ran by claude/sonnet/xhigh · worker kzyp-xps-1}

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

_{Review-Attention: skim ~2m (decisions: count-only-resource-example) @ a0c95c0}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

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-740

This preview will update automatically when you push new commits.

[Ethan-Arrowood]

Pre-approving, but one necessary change and then this can merge.

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.