Document consistent subscription catch-up and live delivery

[kriszyp]

Document the v5.3 subscription default: catch-up suppresses record mutations whose version does not match the current stored primary entry, consistently with live delivery. Explain the includeSuperseded opt-in, retained-history limits, and the explicit opt-in that preserves intermediate publications for durable MQTT QoS 1/2 subscriptions.

Companion implementation: Skip superseded subscription updates during catch-up.

For the human reviewer

1. Requirements and compatibility: the requested default unifies live and catch-up version comparison. This compares primary metadata, which publications also advance; it is not a separate last-record-mutation clock. Missing records and removed tombstones cannot establish a matching current version. Consumers requiring retained mutation history must opt in, while raw-event consumers retain their existing default.
2. Durable publications: durable MQTT QoS 1/2 subscriptions opt into superseded versions for both live delivery and catch-up. This preserves intermediate retained publications and permits older updates in delivered history without changing the winning stored record. No new MQTT parameter is required.
3. Replay boundaries: the existing exclusive transaction cursor can be shared by multiple events. The docs warn against treating each event as a safe checkpoint; cursor/acknowledgment crash recovery is not redesigned here. previousCount retains its bounded scan and does not promise a complete history.
4. Position-checked resume landed on main underneath this branch: rebasing merged databaseGeneration/resumeVerified (Resuming from a position) with this PR's includeSuperseded table rows and section, in version order (5.3.0 before 5.4.0). > ❓ Your call: the includeSuperseded migration example sits directly above the new position-check section but doesn't wait on resumeVerified or pass databaseGeneration — left as-is since it demonstrates a different, independent option (version filtering, not position verification); flagged by review as a nit, not wrong.

Post-review delta: four changed lines in the MQTT reference and release notes, not re-reviewed; these narrowly resolve the reviewed ordering contradiction and migration-warning omissions. Further delta after the rebase above: two lines in release-notes/v5-lincoln/5.3.md narrowed an overclaim ("durable MQTT QoS 1/2 still receive every retained publication") that a newly-merged 5.4 release note (documenting a same-transaction acknowledgement fix) revealed as no longer accurate for 5.3.x, plus a link-label fix.

Changes

• reference/resources/resource-api.md documents option defaults and explicit overrides; matching tombstones, missing-primary and publication-version behavior; and historical reconstruction and the awaited opt-in example. Shared cursors and accepted-event history limits are described above.
• reference/mqtt/overview.md distinguishes durable QoS 1/2 historical delivery from ordinary version-filtered subscriptions, including distributed ordering and audit retention.
• release-notes/v5-lincoln/5.3.md adds the migration warning covering superseded updates, publication-advanced metadata, and removed records/tombstones, plus the durable MQTT exception — now scoped to exclude the 5.3 same-transaction ack gap fixed in 5.4.

Verification

• End-to-end documentation route: npm run build passed, generating the static site with the new links and version badges. Later corrections change prose only.
• Final npm run format:write, npm run format:check, and git diff --check passed.
• One full outside review and two delta reviews completed before the rebase below; the latest reviewed cc5524841259.
• Rebased onto main after it added position-checked resume (databaseGeneration/resumeVerified) to the same two reference files; resolved three real conflicts by merging both features rather than picking a side (see item 4 above), then ran a fresh full outside review plus two delta rounds, converging with no remaining in-scope actionable findings. The companion core change tracks runtime behavior and MQTT regression tests.

Related PRs: #683 overlaps, #691 overlaps, #704 overlaps, #688 independent, #700 independent, #701 independent, #699 independent, #693 independent, #686 independent, #696 independent, #692 independent, #685 independent, #682 independent
Complexity: medium

Origin — the dispatch brief this PR was written from

Document consistent subscription catch-up and live delivery

Maintain #679 (Document consistent subscription catch-up and live delivery) on branch kris/subscription-superseded. Read the current PR head, mergeability, and latest check runs before acting; the dispatch observation may be stale. First read the remote head for refs/heads/kris/subscription-superseded without updating local refs and require it to equal this task's observed head d0ffcb1; if it differs, stop with needs-input because remote history changed after dispatch. Then fetch only refs/heads/main from origin into refs/remotes/origin/main. If Git reports a paused rebase for this task's exact generation branch, require that rebase's recorded original head to equal d0ffcb1 and its recorded onto commit to equal the fetched origin/main tip; stop with needs-input on either mismatch. Only then resume it without repeating the local-HEAD ancestry check or starting another rebase. Otherwise record the remote SHA, verify it is an ancestor of local HEAD, and rebase onto the fetched base. If Context carries companion instructions, follow them exactly for every named gitlink; they override ordinary conflict handling. Preserve both sides' intent for every other conflict. Stop with needs-input on semantic conflicts. Force-with-lease is authorized only for this rebase. Immediately before pushing, re-read the PR's base ref and body plus every companion PR head/state named in Context. The base must still be main, and the declarations and submodule bindings must still match Context. If an open companion advanced, update its named gitlink to the new exact head and rerun relevant tests. If it merged, point the named gitlink at the companion repository's current default-branch tip after verifying that tip contains the merge, then rerun relevant tests. If it closed without merging, stop with needs-input and do not publish its abandoned head. If the base, declaration, binding or any other companion state changed ambiguously, stop with needs-input. Then push the rebased head with git push --force-with-lease=refs/heads/kris/subscription-superseded:EXPECTED_HEAD_SHA origin HEAD:refs/heads/kris/subscription-superseded, substituting the recorded SHA. If the remote head changes, stop with needs-input; never overwrite intervening remote work. Do this before evaluating CI. Then inspect CI for the resulting current PR head, not old-head failures. Wait for relevant pending checks, diagnose remaining failures, fix them, run relevant tests, and push in THIS task. Do not create a separate CI-fix task. Stop with needs-input for judgment calls or an unavailable CI result; report exactly what was verified. No merge is authorized.

_{Dispatch: task pr-maint-92e4b54bf5b8178a01b68ecdd48dc2b0 · queued by automation · ran by claude/sonnet/high · worker kzyp-xps-1}

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

_{Review-Attention: skim ~2m (decisions: publication-suppression-as-documented-rule, carve-out-placement) @ d0464bd}

[gemini-code-assist]

Code Review

This pull request updates the documentation and release notes for Harper v5.3.0 to reflect changes in subscription catch-up behavior, where table subscriptions and MQTT durable-session reconnects now skip superseded record updates by default. It documents the new includeSuperseded and rawEvents subscription options. The review feedback recommends avoiding the use of the <VersionBadge> component inline within table cells, suggesting plain text instead to maintain consistent formatting.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

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

This preview will update automatically when you push new commits.

[dawsontoth]

Cool!

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

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

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

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

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

This preview will update automatically when you push new commits.