Document super_user-only replication directives and the unconfirmed-commit error

[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. A caller that retries a 5xx must know the write already landed.

🤔 Is a docs PR warranted before the harper PRs merge?

Yes, as a draft. Depends-on holds the merge until both harper PRs land, so the page changes only with the code. If either harper PR changes behavior first, the claims here need a recheck. A 5.4 release-notes entry is not included; the task limited this PR to the sharding page.

💡 Solution

In reference/replication/sharding.md (all tagged v5.4.0):

• REST: X-Replicate-To needs super_user; others get 403, including on reads.
• 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. ⚠️ 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.

🤔 Should the page warn that copying request input into the context undoes the 403?

The page only says application code can still set these options on a trusted context. A resource method that copies request input into context.replicateTo gives that caller control again. I left the approved text alone. Adding one sentence says it outright, and costs nothing to reverse.

🤔 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.
• Not run against a live Harper: v5.4.0 is untagged and 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)
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=codex,gemini; adjudicated=domain; declined=cursor-grok,cursor-composer,cursor-kimi,cursor-muse,muse; rounds=2; full=1 @ 4a55c34}

_{Review-Attention: skim ~2m (decisions: ops-403-scope-wording, in-page-trust-boundary-wording, outcome-section-placement, badge-before-core-merge) @ 4a55c34}

[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.