Document replicaExpiration and replicaRefreshFraction for residency tables by kriszyp · Pull Request #746 · HarperFast/documentation

kriszyp · 2026-10-21T18:30:11Z

📝 Summary

Documents the two @table arguments the local replica tier adds for tables sharded with setResidency: replicaExpiration (seconds a record fetched from a resident node is kept locally; default 3600; 0 keeps remote reads) and replicaRefreshFraction (the share of that lifetime after which a read renews it; default 0.5; 1 is fixed). The sharding page says what a replica is and is not, that setResidencyById tables keep none, and that replicateFrom: false returns a replica the node holds; the 5.4 release notes get an entry; the argument section explains the lifetime, the sweep and the renewal.

Companion to HarperFast/harper#3375 and HarperFast/harper-pro#1101 (the feature; this page should merge with them). Open PR #691 adds a row to the same @table table; whichever merges second keeps both rows.

_{🤖 Generated by Claude Fable 5.1; posted via @kriszyp.}

Release target: main — documentation for the 5.4 replica tier

Related PRs: #691 overlaps
Complexity: simple

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

_{Review-Attention: skim ~2m (decisions: default-on-replicas, ship-docs-before-feature-tag) @ 5b20880}

…ables Dispatch-Task: hp-residency-replica-tier Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxKx7SjhcDpWXLNcydYC7g

…hor, and note the 5.4 change Dispatch-Task: hp-residency-replica-tier Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxKx7SjhcDpWXLNcydYC7g

Dispatch-Task: hp-residency-replica-tier Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxKx7SjhcDpWXLNcydYC7g

github-actions · 2026-10-21T18:34:42Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

gemini-code-assist

Code Review

This pull request adds documentation and release notes for local replicas of records fetched from other nodes in v5.4.0, introducing the new @table arguments replicaExpiration and replicaRefreshFraction. The feedback suggests avoiding the use of the <VersionBadge> component at the start of a paragraph in running prose within reference/replication/sharding.md, recommending plain text instead.

gemini-code-assist · 2026-10-21T18:39:14Z

-With this approach, record metadata (including residency information) and indexed properties are replicated to all nodes, but the full record is only stored on the specified nodes.
+With this approach, record metadata (including residency information) and indexed properties are replicated to all nodes, but the full record is only stored on the specified nodes, apart from the short-lived replicas described next.
+
+<VersionBadge type="changed" version="v5.4.0" /> A node outside a record's residency that reads the record fetches it from a resident node and keeps the result as a local replica for `replicaExpiration` seconds (default one hour), renewed by reads after `replicaRefreshFraction` of that time. The record stays where the residency function placed it: a replica is never written back, replicated onward or counted as a resident, and a resident's write turns it back into a stub so the next read fetches the new version. See the [`@table` arguments](../database/schema.md#replicaexpiration-and-replicarefreshfraction).


Avoid using the <VersionBadge> component at the start of a paragraph in running prose. Use plain text (e.g., 'As of vX.Y.Z') instead, reserving <VersionBadge> for standalone placement after headings.

Suggested change

<VersionBadge type="changed" version="v5.4.0" /> A node outside a record's residency that reads the record fetches it from a resident node and keeps the result as a local replica for `replicaExpiration` seconds (default one hour), renewed by reads after `replicaRefreshFraction` of that time. The record stays where the residency function placed it: a replica is never written back, replicated onward or counted as a resident, and a resident's write turns it back into a stub so the next read fetches the new version. See the [`@table` arguments](../database/schema.md#replicaexpiration-and-replicarefreshfraction).

As of v5.4.0, a node outside a record's residency that reads the record fetches it from a resident node and keeps the result as a local replica for `replicaExpiration` seconds (default one hour), renewed by reads after `replicaRefreshFraction` of that time. The record stays where the residency function placed it: a replica is never written back, replicated onward or counted as a resident, and a resident's write turns it back into a stub so the next read fetches the new version. See the [`@table` arguments](../database/schema.md#replicaexpiration-and-replicarefreshfraction).

References

Avoid using the component at the start of a paragraph in running prose. Use plain text (e.g., 'As of vX.Y.Z') instead, reserving for standalone placement after headings.

LMDB remote reads remain proxy reads and never arm replica maintenance. Match the Float schema argument and explain the sweep interval floor. Dispatch-Task: harper-3375-audit-refs-regression Co-Authored-By: GPT-5 Codex <noreply@openai.com>

kriszyp · 2026-10-23T21:19:45Z

Updated this companion in fa903ea for the RocksDB-only contract in harper#3375.

Local replicas are RocksDB-only. LMDB continues proxying remote reads, stores no replica and never arms the replica sweep; option validation still applies.
replicaExpiration is a GraphQL Float. The sweep interval is a quarter of the configured lifetime with a one-second minimum.
Updated schema reference, sharding guidance and the v5.4 release note. Full-tree format:write and format:check pass with this repository’s pinned Prettier 3.8.1/code-guidelines 0.1.2. A site build was not run locally; this prose update adds no new links or code examples.

Keep this PR draft and coordinate publication with core #3375 and harper-pro#1101. The previous review footer covers the prior docs revision; this update has not had a separate outside-model docs review.

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

github-actions · 2026-10-23T21:23:14Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

Reload RocksDB workers after changing replica settings; existing classes can retain their previous values. Disabling admission does not purge old replicas. Dispatch-Task: harper-3375-audit-refs-regression Co-Authored-By: GPT-5 Codex <noreply@openai.com>

github-actions · 2026-10-23T21:48:33Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

Dispatch-Task: harper-3375-audit-refs-regression Co-Authored-By: GPT-5 Codex <noreply@openai.com>

kriszyp · 2026-10-23T22:08:41Z

Updated the schema reference in 75abed5 to match the live option-propagation repair in harper#3375.

Schema rescans apply replica options to already-loaded worker classes. New lifetimes apply to subsequent admissions and renewals; existing deadlines are not rewritten. Lifetime zero stops new admissions and the sweep without purging existing replicas. The obsolete worker-reload warning is removed. Replicas remain RocksDB-only; LMDB remains proxy-only after every update.

Full-tree format:write/check passes with the pinned docs formatter. Core’s real two-worker tests pass on Node 22/24/26 and both engines. No local docs site build or separate outside-model review of this prose revision was run. Keep this companion draft and merge it with core #3375 and harper-pro#1101.

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

github-actions · 2026-10-23T22:11:28Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

Dispatch-Task: harper-3375-audit-refs-regression Co-Authored-By: GPT-5 Codex <noreply@openai.com>

github-actions · 2026-10-23T23:09:45Z

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

kriszyp and others added 3 commits October 21, 2026 07:19

Document replicaExpiration and replicaRefreshFraction for residency t…

245a185

…ables Dispatch-Task: hp-residency-replica-tier Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxKx7SjhcDpWXLNcydYC7g

State how a replica is invalidated and swept, give the section an anc…

88b76b3

…hor, and note the 5.4 change Dispatch-Task: hp-residency-replica-tier Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxKx7SjhcDpWXLNcydYC7g

Note the one-second floor of the replica sweep

5b20880

Dispatch-Task: hp-residency-replica-tier Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxKx7SjhcDpWXLNcydYC7g

This was referenced Oct 21, 2026

Keep a record fetched from a resident as a local replica instead of relocating it on read HarperFast/harper-pro#1101

Merged

Keep a record fetched from a resident as a local replica instead of relocating it HarperFast/harper#3375

Merged

github-actions Bot temporarily deployed to pr-746 October 21, 2026 18:34 Inactive

gemini-code-assist Bot reviewed Oct 21, 2026

View reviewed changes

Document local replicas as RocksDB-only

fa903ea

LMDB remote reads remain proxy reads and never arm replica maintenance. Match the Float schema argument and explain the sweep interval floor. Dispatch-Task: harper-3375-audit-refs-regression Co-Authored-By: GPT-5 Codex <noreply@openai.com>

github-actions Bot temporarily deployed to pr-746 October 23, 2026 21:23 Inactive

github-actions Bot temporarily deployed to pr-746 October 23, 2026 21:48 Inactive

Document live replica option propagation on schema rescan

75abed5

Dispatch-Task: harper-3375-audit-refs-regression Co-Authored-By: GPT-5 Codex <noreply@openai.com>

github-actions Bot temporarily deployed to pr-746 October 23, 2026 22:11 Inactive

Clarify that zero replica lifetime stops new admissions

77e6526

Dispatch-Task: harper-3375-audit-refs-regression Co-Authored-By: GPT-5 Codex <noreply@openai.com>

github-actions Bot deployed to pr-746 October 23, 2026 23:09

View deployment

kriszyp mentioned this pull request Oct 24, 2026

Document declarative slot residency and shard configuration #753

Draft

kriszyp marked this pull request as ready for review October 24, 2026 15:35

kriszyp requested a review from a team as a code owner October 24, 2026 15:35

kriszyp merged commit 34b029d into main Oct 24, 2026
14 checks passed

kriszyp deleted the docs/replica-expiration branch October 24, 2026 15:36

Navigation Menu

Repository navigation

Document replicaExpiration and replicaRefreshFraction for residency tables - #746

Document replicaExpiration and replicaRefreshFraction for residency tables#746
kriszyp merged 7 commits into
mainfrom
docs/replica-expiration

kriszyp commented Oct 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 21, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Oct 21, 2026

Uh oh!

kriszyp commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026

Uh oh!

kriszyp commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

kriszyp commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Summary

Uh oh!

github-actions Bot commented Oct 21, 2026

🚀 Preview Deployment

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Oct 21, 2026

Choose a reason for hiding this comment

Uh oh!

kriszyp commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 23, 2026

🚀 Preview Deployment

Uh oh!

kriszyp commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 23, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

kriszyp commented Oct 21, 2026 •

edited

Loading