Skip to content

docs: explain durable append delivery and recovery - #523

Open
wchwawa wants to merge 2 commits into
mainfrom
docs/durable-append-guide
Open

wchwawa wants to merge 2 commits into
mainfrom
docs/durable-append-guide

Conversation

@wchwawa

@wchwawa wchwawa commented Sep 26, 2026

Copy link
Copy Markdown
Member

Related Issue

Relates to #520. Depends on #522.

This draft is stacked on #522 to keep its diff limited to documentation and preserve the feature PR's reviewed head. Merge #522 first, then retarget this PR to main and run its normal checks before merging.

Summary

Explain how a replacement queue worker reuses a saved append identity and intent, recovers the original receipt, and acknowledges delivery safely. Add a complete CLI/Python guide and a dated qualification record; align README, SDK, storage, recovery, deployment and release documentation.

Clarify cleanup acceptance versus completion, historical receipts versus body retention, permanent failed-key seals, and the absence of an old-format migration. Separate the fixed 18-tool facade from the durable append APIs.

Scope

  • One logical boundary: documentation for durable append and recovery.
  • No runtime, schema, dependency, CI or benchmark implementation changes. The two Rust files change only crate documentation comments.
  • The linked issue describes the user-visible problem.
  • Existing breaking-format boundaries are documented; no new compatibility path.

Change Size And Review

  • Checked additions plus deletions: 1,598 lines across 23 files, below 5,000.
  • Three independent agent cross-reviews completed; reported wording issues corrected.

Code Contract (Code Changes Only)

  • Not applicable; documentation only.

Claims and Evidence

  • Distinguishes source availability, releases, local fault qualification, remote CI and unqualified scopes.
  • No new authentication or performance claims; private demo evidence is explicitly labeled.

Validation

  • Local links/assets/routes: 168 passed; Markdown anchors: 10 passed.
  • All examples parsed: 31 shell blocks (bash -n), two Python blocks (ast.parse), one JSON block.
  • cargo fmt --all -- --check and git diff --check: passed.
  • Runtime CLI usage and retained test receipts/hashes checked against the qualified feature revision.
  • No checked-in documentation build exists. Runtime suites were not rerun for prose changes. Existing workflows target main, so this stacked draft does not claim a new remote CI run.

Contributor Sign-off

  • The documentation commit includes a DCO sign-off using the author's GitHub account email.

Signed-off-by: wchwawa <wch19961116@gmail.com>
@feichai0017 feichai0017 moved this to In Progress in NoKV Delivery Sep 26, 2026
Base automatically changed from fix/append-replay-identity to main October 16, 2026 00:43
@wchwawa
wchwawa marked this pull request as ready for review October 16, 2026 00:44
@wchwawa
wchwawa requested a review from feichai0017 as a code owner October 16, 2026 00:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants