Clarify confirm/replicatedConfirmation any-N semantics in the sharding docs

[kriszyp]

⊙ Problem

replicatedConfirmation: N / confirm=N was documented, but readers (per the QA report this task is based on) assumed confirm=1 meant a specific peer acknowledged the write — it doesn't. Confirmation counts any N peer acknowledgements, and a peer outside the record's residency counts too even though it may hold only an invalidation entry or nothing at all for that record.

❓ Your call: as specified, yes — but verifying the semantics against the actual replication code (per # Context) surfaced enough additional inaccuracies in the existing text (an unconditional "N full copies" implication, replicateTo placement vs. confirmation-count conflation, a v5.2.1 behavior change with no version note, post-commit failure framing) that this grew from two sentences into a fuller pass over both docs. Each addition below is traced to source, not inferred.

💡 Solution

Added one clarification, stated once per doc and cross-referenced from the other two Replication Control subsections (REST, Operations API, programmatic) instead of being duplicated three times — duplication is what let earlier drafts of this same note drift internally during review (see commit history).

• confirm=N / replicatedConfirmation: N waits until any N peers acknowledge — not N specific peers, and not necessarily N peers holding the full record (a non-resident peer can count via an invalidation entry, or nothing at all). Same note, v4 semantics.
• replicateTo / X-Replicate-To controls where the record is stored (under the default residency — setResidency/setResidencyById take precedence); it does not change which peers' acknowledgements are counted.
• confirm/replicatedConfirmation deduplicates by peer identity as of v5.2.1; earlier v5 releases counted repeated crossings from one peer, the way v4 still does.
• Confirmation can fail two other ways after the write has already committed locally: a 400 if N exceeds this node's actual replication recipients, or a 504 after the server's timeout (900s default, raised to match a longer blob-transfer timeout). v5.2.1 also introduced both of these; v4 has no timeout and checks against total known nodes — and can hang even on a healthy peer if its ack crosses before the wait registers.
• Confirmation waiting is Harper Pro only — without it, confirm/replicatedConfirmation is silently a no-op.
• N must be a positive integer; it isn't validated, and behavior for an invalid value is unspecified (deliberately not promising exact behavior here — see Verification).

🔧 Changes

• reference/replication/sharding.md — current (v5) docs, all three Replication Control subsections under Dynamic Sharding.
• reference_versioned_docs/version-v4/replication/sharding.md — same clarification with v4-specific semantics (no peer dedup, no timeout, server.nodes excludes the local node).

✅ Verification

Semantics verified against harper-pro source (not just read, traced and in several cases executed against extracted waiter code across tagged releases) and harperdb (v4) source, per # Context's instruction to verify before writing:

• Any-N, not specific-N: harper-pro/replication/knownNodes.ts createConfirmationWaiter resolves on confirmed.size === confirmationCount, a Set keyed by peer name — any N peers, independent of residency (countAlreadyConfirmedPeers/getReplicationRecipients).
• Peer dedup is v5.2.1+: git merge-base --is-ancestor 61a1531b <tag> across local tags shows the dedup commit (and the paired timeout/recipient-bound commits, same timestamp) first lands in v5.2.1; v5.0.0/v5.1.x/v5.2.0 use a bare counter like v4 still does today.
• v4 has no dedup, no timeout: harperdb/server/replication/knownNodes.ts increments a plain counter with no per-peer tracking, and its confirmation Promise has no reject/timeout path at all.
• Post-commit framing: both the 400 (over-large count) and 504 (timeout) throw from inside the commit's already-succeeded .then (DatabaseTransaction.ts/LMDBTransaction.ts, both versions) — the write is durable either way.
• Pro-only: OSS core only reads confirmReplication (resources/DatabaseTransaction.ts, resources/LMDBTransaction.ts); only harper-pro/replication/knownNodes.ts calls replicationConfirmation(...) to register a handler.
• Ran npx prettier --check on both changed files — clean.
• Independent review: 10 rounds (1 full baseline, 5 more full passes driven by genuinely new findings each time, delta rounds in between) via the pre-push review CLI (codex + gemini + cursor + Harper-domain adjudication). Converged at round 10 with only pre-existing/out-of-scope findings remaining (below).

Findings deliberately left open (pre-existing or outside this diff)

Per the dispatch Findings section — not fixed here, since none are introduced by this diff:

• reference/replication/sharding.md:33-38 (+ v4) — the top-level replication.replicateTo: N YAML example may never be read by core (only replication.databases[].replicateTo is) — needs verification against a live cluster.
• reference/replication/sharding.md:40 (+ v4) — "stored on three nodes total" is unconditional; doesn't mention setResidency/setResidencyById override, unlike the per-request paths this PR fixed.
• reference/replication/sharding.md:44 (+ v4) — non-super_user callers get a 403 for any replication parameter; undocumented anywhere on this page.
• Product bugs (not doc bugs, filed as findings for the EM to triage into issues): the 400 throw skips transaction cleanup (blob/lock release) in DatabaseTransaction.ts; replicatedConfirmation passed as a string is never coerced and the strict-equality waiter comparison never matches it.

Related PRs: none found

_{Dispatch: task documentation-replicated-confirmation-semantics · queued by unknown · ran by claude/sonnet/high · worker kzyp-xps-1}

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

_{Review-Attention: skim ~2m (decisions: unspecified-vs-product-validation, pro-requirement-placement, publish-timeout-constant, document-v4-defect-as-contract) @ 6d513c8}

[gemini-code-assist]

Code Review

This pull request updates the replication and sharding documentation for both the current version and the v4 versioned docs, clarifying the semantics of replication confirmation (confirm=N), deduplication, timeouts, and residency. The review feedback suggests avoiding the use of the component mid-sentence in running prose, recommending plain text alternatives like (as of v5.2.1) to maintain a consistent reading flow.

[gemini-code-assist]

Avoid using the <VersionBadge> component mid-sentence in running prose. Instead, use plain text such as (as of v5.2.1) to maintain a consistent reading flow.

Suggested change

`confirm=N` (and the operation-body/programmatic `replicatedConfirmation: N` used below) waits until any N peers acknowledge the commit — not N specific peers. N must be a positive integer; it isn't validated, and a non-integer value's behavior is unspecified. <VersionBadge type="changed" version="v5.2.1" /> — acknowledgements are deduplicated by peer identity, so the same peer can't satisfy more than one of the N; earlier releases, like v4 still does, counted repeated replication-position crossings from one peer as satisfying more than one of the N on their own. A peer outside the record's residency still counts, once its replication position passes the write — even though it may hold only an invalidation entry, or nothing at all for that record. So confirmation cannot guarantee that N full copies exist, or that any particular node — even one named in `X-Replicate-To`/`replicateTo` — has the write. Confirmation waiting requires Harper Pro; without it, `confirm`/`replicatedConfirmation` is accepted but has no effect — the write succeeds immediately with no wait and no error.

`confirm=N` (and the operation-body/programmatic `replicatedConfirmation: N` used below) waits until any N peers acknowledge the commit — not N specific peers. N must be a positive integer; it isn't validated, and a non-integer value's behavior is unspecified. Acknowledgements are deduplicated by peer identity (as of v5.2.1), so the same peer can't satisfy more than one of the N; earlier releases, like v4 still does, counted repeated replication-position crossings from one peer as satisfying more than one of the N on their own. A peer outside the record's residency still counts, once its replication position passes the write — even though it may hold only an invalidation entry, or nothing at all for that record. So confirmation cannot guarantee that N full copies exist, or that any particular node — even one named in `X-Replicate-To`/`replicateTo` — has the write. Confirmation waiting requires Harper Pro; without it, `confirm`/`replicatedConfirmation` is accepted but has no effect — the write succeeds immediately with no wait and no error.

References

1. Avoid using the component mid-sentence in prose as it is awkward; use plain text (e.g., (vX.Y.Z)) instead.

[gemini-code-assist]

Avoid using the <VersionBadge> component mid-sentence in running prose. Use plain text such as (as of v5.2.1) instead to keep the text clean and readable.

Suggested change

Confirmation can also end two other ways, both after the write (or delete) has already taken effect locally — only the wait itself fails: a count larger than the peers this node actually replicates the database to is rejected with a 400; otherwise, the request fails with a 504 if confirmation doesn't complete within the server's timeout (900 seconds by default, raised to match a longer configured blob-transfer timeout). <VersionBadge type="changed" version="v5.2.1" /> — earlier releases had no timeout and checked the count against every known node rather than actual recipients, the way v4 still does.

Confirmation can also end two other ways, both after the write (or delete) has already taken effect locally — only the wait itself fails: a count larger than the peers this node actually replicates the database to is rejected with a 400; otherwise, the request fails with a 504 if confirmation doesn't complete within the server's timeout (900 seconds by default, raised to match a longer configured blob-transfer timeout) (as of v5.2.1). Earlier releases had no timeout and checked the count against every known node rather than actual recipients, the way v4 still does.

References

1. Avoid using the component mid-sentence in prose as it is awkward; use plain text (e.g., (vX.Y.Z)) instead.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.