[kriszyp]

⊙ Problem

Operators need a precise activation and recovery procedure before using schema-defined sharding, particularly when converting existing owners or replacing a lost data root.

🤔 Scope and recovery contract

Document the bounded recovery contract explicitly. Snapshot-only recovery uses a fresh root and new node name. Same-name recovery requires a complete stopped-node backup preserving audit through the last accepted write. Do not imply arbitrary relay recovery or online slot migration.

💡 Solution

Add the @sharded guide, configuration and operations references, conversion assertions, recovery diagnostics, compatibility limits, and release notes. Keep legacy residency APIs separately named.

This documentation PR remains draft and must merge together with Pro #1116.

Refs HarperFast/harper-pro#980.

Companions: core #3527, Pro #1116.

⚖️ Alternatives

Architecture alternatives and framing

Keep the existing residency API reference for applications that use it. The new guide names the declarative activation and recovery restrictions explicitly; it does not promise online slot migration or incarnation-based recovery.

Framing-Verdict: chosen-approach-sound for the original architecture and core closing admission gate (17fab807b032). The final Pro planning reviewer proposed further failed-source inventory optimization (9550f6f252c4, better-alternative-exists). The implementation adopts bounded blob settlement, watchdog renewal and owned-only failure tracking. A capped per-key failure inventory is deferred. Only an actual owned failure invalidates the scan; successful live traffic keeps the completed proof. This author scope ruling is distinct from reviewer clearance. Targeted implementation review and its limitations are recorded below.

Documentation scope decisions

🤔 Supported rollback route

The in-place recipe is explicitly for equivalent legacy by-id conversions. A fresh declarative table has no old placement policy to restore and no promised in-place downgrade. A general migration workflow is outside these companions. The guide URL remains stable; the title and public directive use sharding terminology.

🤔 Local-only placement

Local-only success does not establish a durable owner copy. The guide states that its audit body is not delivered and describes temporary replicas, projections and omitted rows. Attribute-derived sharding is excluded from the guide and refused at schema load. localOnly names the caller's write option; this guide does not introduce a new operations field.

🤔 Supported policy scope

The guide documents primary-key hashing only and points to #1178 for concurrent attribute-move design. It does not document the private test switch, attribute recipes, or a known-gap fallback.

🔧 Changes

Product behavior, admission, and recovery walkthrough

Product and architecture tour

Declare and inspect sharding

The sharding guide shows primary-key hashing, refuses by and slotFrom, and links the concurrent-move design in Pro #1178. Ordinary local-only updates succeed without automatic confirmation. Schema reference links to it. Deployment topology and configuration options separate the local shard from the complete shard list. Map storage explains the immutable database map; confirmation usage covers explicit acknowledgment and post-commit uncertainty. Subscription row payloads limits sharded non-owner filters to indexed projections.

Convert and recover safely

Operator operations distinguish map creation, comparison, and trusted existing-owner assertions. The conversion procedure pauses legacy writers through activation and gives rollback boundaries. Lost-node recovery explains complete-backup restoration, fresh-name co-owner copies, retired-origin retention, and whole-shard loss. Status fields names visible recovery holds and their remedies. Incarnation-based identity is future work tracked in Pro #1123.

Find the new workflow

The replication overview and sidebar point readers to the new guide. Release notes summarize activation, recovery holds, and the new-name recovery restriction.

✅ Verification

Rebased onto current main (f5d1d9cf00ad). Resolved the reference/replication/sharding.md conflict by retaining main's Order programmatic confirmation and unconfirmed-commit error section (#740) alongside this PR's explicit txn binding, @sharded placement note, and LMDB confirmation outcomes. Full-tree and range comparisons preserve the feature content; no other documentation changes were made.

Two follow-up commits after the rebase keep one explanation of confirmation failures: residency.md, the API reference and the 5.4 release note now link to the confirmation-failure section from Document super_user-only replication directives and the unconfirmed-commit error (#740, merged) rather than restating it, and the two rowFilter warnings name the id and indexed fields a subscriber can learn. Links and wording only; no line anchors moved.

Executed: npm run format:write, npm run format:check, npm run lint, npm run typecheck, npm run test:examples (13 pass, one optional companion-fixture comparison skipped), npm run test:workflows, and npm run build (426 documents). All passed.

🤔 Rebase scope and review nits

Keep the validated content unchanged; additional cross-links, availability annotations, and prose refinements from Round 22 review are outside this rebase task and recorded for follow-up triage. Claude, Grok, Composer, and domain adjudication reviewed; no rebase regression was found.

The supported schema and recovery procedures were checked against core #3527 and Pro #1116. This PR changes documentation only.

_{🤖 Generated by OpenAI Codex; posted via @kriszyp.}

Release target: v5.4 — companion documentation for the next minor release

Complexity: medium

Related PRs: #733 overlaps, #740 overlaps, #746 overlaps, 7 others independent

Review deferral receipts

Deferred findings

• d7811620857ee1db minor documentation — reference/replication/residency.md — Non-owner local-only writes lack an explicit durability warning — filed State explicitly that non-owner localOnly success does not ensure owner durability #764
• 4fbc3cf1a849bc99 minor documentation — reference/replication/residency.md — Fresh key-sharded tables lack an explicit rollback route — filed Document a supported downgrade path for tables created with sharding #763
• be8a7047ffc8505a minor documentation — reference/replication/residency.md — Local-only writes term undefined; reads as contradicting the line-54 delivery to owners — filed Define the caller surface of the localOnly write option #765
• eca340a371c43c9e nit documentation — reference_versioned_docs/version-v4/replication/sharding.md — Archived confirmation example may set confirmation too late — filed Correct the archived v4 programmatic confirmation example #752
• 1dacd324d46b97cd nit documentation — reference/replication/residency.md — Guide route differs from public sharding terminology — filed Align the sharding guide route with its public terminology #768

Late Grok findings

5 surviving (highest minor) — Grok reviewed fb577b8

• minor — reference/resources/resource-api.md:253 — This sentence warns against using the filter to decide whether a subscriber "may learn an unindexed value". A non-owner's invalidation payload never contains that value. The real leak is the record's id and indexed fields, which is what the sibling page warns about at `reference/replication/residenc
• minor — reference/replication/residency.md:56 — The page never defines "local-only writes". Line 54 says a non-owner write sends the full body to the owners, and line 56 says local-only writes do not deliver to owners. A caller cannot tell which case an ordinary successful put falls into.
• nit — release-notes/v5-lincoln/5.4.md:29 — The link text is "Configuration failures and recovery sources", but it points only to #configuration-failures-and-peer-identity.
• nit — reference/database/api.md:137 — The "Replication confirmation" section does not link to ../replication/sharding.md#confirmation-outcomes, where the LMDB change is documented (LMDB writes now wait for peer acknowledgments).
• nit — release-notes/v5-lincoln/5.4.md:45 — The "Local Replicas" release note describes replicas only for setResidency tables. It omits the fetched replicas and writer replicas that @sharded non-owners keep.

Not standing: 1 separate-issue, 1 merged. Grok ran 2m (2m from launch to report); the fold adjudication (cursor-grok@fb577b8e4b52-a320b300, claude) took 1m.

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,cursor-grok,codex; late=cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=26; full=9 @ cfdf7b2}

_{Review-Attention: read ~3m (decisions: separate-residency-page, do-less-alternative, internal-metadata-rollback-snippet, operator-asserted-completeness) @ cfdf7b2}

[gemini-code-assist]

Code Review

This pull request introduces comprehensive documentation for the new Declarative Residency feature in version 5.4.0, which allows defining table placement policies directly in the schema using the @residency directive. The changes span configuration options, schema directives, system tables, operations APIs, replication/sharding guides, and release notes. The review feedback suggests a minor improvement in reference/replication/residency.md to restructure a paragraph for better readability and to avoid grammatically disjointed phrasing regarding the 503 response.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

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

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

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

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

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

This preview will update automatically when you push new commits.