[kriszyp]

⊙ Problem

Stop forcing base copies that never finish (harper-pro#1249) changes three undocumented replication behaviors for 5.4. cluster_status gains a stuckCopy field with no schema here. The overview and Learn pages still say any position older than a peer's retained history forces a base copy, which 5.4 no longer does for idle databases.

🤔 Should this land here, while the pages may move?

Yes, for now. The 5.4 replication and cluster_status pages are still in this repo. Move the Harper Pro reference pages into docs/ (harper-pro#1237) and Assemble the v5 reference from harper and harper-pro (#788) are open. Whichever merges first, this text must reach harper-pro's docs/ too.

💡 Solution

• Stuck Copies documents stuckCopy: its fields, the retrying, held and refused states, the fixed hold schedule, how it clears and what it logs.
• When a Peer Forces a Base Copy states when purged history forces a copy, including the exceptions.
• Rows From Unnamed Origins documents unnamed-origin-<id>@<node name>.
• The release notes and related pages link to these.

🔧 Changes

• reference/replication/clustering.md: new Stuck Copies section with an example, field table, states, clearing rules and log lines.
• reference/replication/overview.md: the resync paragraph now says "purged history the node would need to replay"; new When a Peer Forces a Base Copy and Rows From Unnamed Origins sections.
• release-notes/v5-lincoln/5.4.md: one Replication entry covering all three changes, with the upgrade impact.
• reference/operations-api/operations.md: the cluster_status summary links to Stuck Copies.
• reference/database/transaction.md: the delete_transaction_logs_before warning states when the purge forces a copy.
• learn/administration/operating-replication.mdx: the returning-node row and retention paragraph link to the 5.4 rule; new stuckCopy bullet.
• learn/administration/backup-and-recovery.mdx: the restore warning uses the 5.4 wording.
• learn/administration/health-checks-and-traffic-admission.mdx: the returning-node note links to the 5.4 rule.

🤔 Exact numbers and name format are published

The page states the 5 attempts, 60-second first hold, 15-minute ceiling, 60-second quiet period, 64-name cap and the name escaping. Operators can alert on them. Any later tuning in harper-pro then needs a docs change.

✅ Verification

• Each claim checked against harper-pro fix/base-copy-liveness @ cd77935 (copyStall.ts, clusterStatus.ts, unnamedOrigins.ts, replicationConnection.ts) and harper fix/base-copy-liveness-core @ 2e99e52 (auditStore.ts, audit-retention.md). stuckCopy reporting matches harper-pro's unnamedOriginCopy and shardedIdleRetention integration tests.
• npm run build (broken links fail it), format:check, lint, typecheck and test:examples pass.
• PR QA: skipped @ 33a9412 — documentation repo, prose only.

Refs HarperFast/harper-pro#1249

Depends-on: HarperFast/harper-pro#1249
Depends-on: HarperFast/harper#3958

🤖 Generated with Claude Code

— Claude Opus 5.5

Related PRs: #788 overlaps (removes these pages and assembles them from harper and harper-pro)
Complexity: easy

Origin — the dispatch brief this PR was written from

Companion docs PR for HarperFast/harper-pro#1249 (draft, milestone v5.4). Update the Harper Pro 5.4 replication reference and the cluster_status reference for the behavior below. Read the harper-pro PR description and its replication/DESIGN.md notes 26, 34 and 35 to verify each claim against the code before writing.

Document the replication behavior changes in harper-pro PR HarperFast/harper-pro#1249 (milestone v5.4), for the 5.4 replication / cluster_status reference pages.

1. cluster_status gains a per-database-socket field stuckCopy, present only while a base copy from that peer is stuck, omitted otherwise:
   { state: 'retrying' | 'held' | 'refused', reason: string, count: number, since: ISO time, retryAt?: ISO time }.
   • retrying: the copy restarted from the same position at least twice without durable progress.
   • held: after 5 such attempts (fixed; no setting) the receiver stops reconnecting to that peer for a hold that starts at 60 s and doubles per failed attempt up to 15 minutes; retryAt is when it tries again.
   • refused: this node owns sharding slots and refused a full copy from a peer that is not a complete co-owner ("Owned sharding slots require a complete co-owner or backup restore"); reconnects are held the same way. It clears once a later connection stays open a minute without a refusal.
     Each state change logs one line (warn for retrying/refused, error for held, info when it clears).
2. Retention-forced base copies: a node no longer forces a full copy on a peer whose resume point is older than logging.auditRetention when the node simply wrote nothing to that database since (an idle or never-written transaction log). A copy is still forced when a prune removed history the peer had not received. After upgrading, a log that was already empty may force one more copy per stale peer.
3. Rows written by an origin with no node name (data migrated from v4, or a removed node) now copy and replicate: the sending node names that origin unnamed-origin-<id>@<node name> on the wire. Operators may see such names in logs and in a receiver's node id mapping.

Public-safe: no customer names. Link the harper-pro PR.

Acceptance

A draft PR on HarperFast/documentation that documents the stuckCopy cluster_status field, the retention-copy behavior change and unnamed-origin naming, cross-linked to harper-pro#1249; cross-model reviewed per the engineering guidelines; no customer names; no settings that do not exist in the code.

_{Dispatch: task docs-harper-pro-1249-base-copy-liveness · queued by task:harper-pro-base-copy-liveness · ran by claude/opus/xhigh · worker kzyp-xps-1}

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

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

_{Review-Attention: skim ~2m (decisions: fixed-constants-as-contract, origin-name-encoding-public, purge-bound-detail-level) @ 33a9412}

[gemini-code-assist]

Code Review

This pull request updates the documentation for version 5.4.0, detailing changes to replication behavior such as when a peer forces a base copy, handling rows from unnamed origins, and the introduction of the stuckCopy status in cluster_status. The review feedback suggests several improvements to readability and clarity, including splitting a long warning sentence in transaction.md into distinct sentences, correcting awkward phrasing in the replication guides, and replacing mid-sentence <VersionBadge> components with plain text as per the repository's guidelines.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

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

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

This preview will update automatically when you push new commits.