Define Keep's authenticated reconstruction contract

[flyingrobots]

Problem

Keep's core law promises exact named bytes or refusal, but the repository did
not have one governed invariant stating whole-object versus range proof scope,
ordinary Write failure visibility, receipt durability, or the distinction
between evidenced content refusals and operational failures.

Invariant affected

For a requested content identity, Keep returns authenticated exact bytes and a
receipt, returns a precise evidenced content refusal, or returns an operational
failure that makes no content claim. A failed ordinary writer may retain an
untrusted prefix; only a complete success receipt authenticates the emitted
sequence.

Approach

• Add the normative authenticated-reconstruction contract.
• Add its colocated rationale and stable requirement ledger.
• Keep complete-object and exact-range proof scopes separate.
• Require range receipts to use a layout-to-target binding admitted by the
  selected store view and state that ranges verify no profile boundaries.
• Separate success, evidenced refusal, and operational failure.
• Add deterministic whole-object and range writers that accept a nonempty
  prefix and then fail, verifying exact error coordinates and no receipt.
• State durable pinned-view and retained-evidence obligations as planned gaps.
• Link the contract from the public README.

Alternatives rejected

• Treat every typed error as an evidenced refusal.
• Promise that failure leaves an arbitrary Write untouched.
• Combine whole and range reads behind an optional range.
• Trust structural layout admission as a target binding.
• Describe current segment/catalog machinery or planned retention as a
  complete durable logical-read API.

Failure modes

The contract covers untrusted output prefixes, incomplete views, unreadable or
inconsistent evidence, unsupported durable claims, exact-layout unavailability,
and the distinction between content evidence and operational failure.

Tests

• cargo fmt --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all-targets --all-features
• cargo test --test streaming_cas
• cargo test --test range_read_failures
• PATH="scripts/documentation-tools/node_modules/.bin:$PATH" cargo xtask documentation-integrity-check
• git diff --check

Benchmark impact

No production path changes. The new deterministic writer fixtures affect tests
only; the all-target validation benchmark binaries completed successfully.

Format and API compatibility

No durable format, canonical bytes, identity law, or public Rust API changes.

Recovery implications

The contract requires future durable receipts to bind one immutable view and
protect the supporting evidence closure. Retention remains planned; the page
does not promote current lower-level durable machinery into a logical read API.

Security implications

Operational failure, partial proof, stale physical existence, or an uncommitted
caller layout cannot be promoted into a stronger content claim. Authenticated
bytes still do not prove authorship, authorization, provenance, or meaning.

Cross-repository consumer

Echo's experimental boundary is flyingrobots/echo#721; live implementation and
cutover work is flyingrobots/echo#722. Echo vocabulary remains outside Keep
core.

[coderabbitai]

Summary by CodeRabbit

• Documentation
  • Added a normative contract describing authenticated reconstruction behavior.
  • Documented proof scope, exact-byte outputs, identity coordinates, evidence requirements, receipts, and output visibility.
  • Clarified supported complete-object and exact-range reconstruction scenarios.
  • Explained typed refusals, operational failures, receipt validity, and limitations of the current non-durable storage behavior.
  • Linked the correctness-first storage promise to the authenticated reconstruction contract.

Walkthrough

The PR adds a normative authenticated reconstruction contract for Keep. It documents proof scopes, exact-byte output, receipts, refusal and failure behavior, ReferenceStore limits, future durable requirements, and consumer constraints.

Changes

Authenticated reconstruction

Layer / File(s)	Summary
Contract foundations README.md, docs/invariants/authenticated-reconstruction/README.md	The repository links the new contract. The contract defines proof scope, exact-byte results, identity coordinates, and evidence limits.
Reconstruction behavior docs/invariants/authenticated-reconstruction/README.md	The contract specifies complete-object and exact-range reconstruction, sink behavior, and ReferenceStore verification.
Outcomes and durability docs/invariants/authenticated-reconstruction/README.md	The contract defines refusal and failure outcomes, receipt validity, future durable requirements, executable evidence, and consumer constraints.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• flyingrobots/keep#54: Defines the durable physical segment-store protocol for authenticated exact-byte reconstruction.

Poem

Exact bytes wait in a proof-bound frame,
Receipts record the scope and name.
Refusals speak when evidence ends,
ReferenceStore verifies and sends.
Durable futures mark the trail,
While false claims find no avail.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: defining Keep's authenticated reconstruction contract.
Description check	✅ Passed	The description covers the required problem, invariant, approach, failures, compatibility, recovery, security, and validation details, but omits the checklist.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/invariants/authenticated-reconstruction/README.md`:
- Line 203: Update the invariant wording in the authenticated reconstruction
documentation to explicitly guarantee that required supporting evidence is not
garbage-collected, deleted, or otherwise invalidated during the read, replacing
the ambiguous “collected” terminology.
- Around line 10-16: Update the contract section around the “Keep either”
statement to distinguish three outcomes: authenticated success, an evidenced
content-related refusal, and operational failure. Align the wording with
ReferenceStore::reconstruct so output or other I/O errors are classified as
operational failures, do not count as precise refusals, and cannot support a
content conclusion.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d886dc72-4668-44aa-9fda-339cb22ceea2

📥 Commits

Reviewing files that changed from the base of the PR and between 57fa4ee and b0469e0.

📒 Files selected for processing (2)

• README.md
• docs/invariants/authenticated-reconstruction/README.md

📜 Review details

🔇 Additional comments (2)

README.md (1)

8-10: LGTM!

docs/invariants/authenticated-reconstruction/README.md (1)

1-9: LGTM!

Also applies to: 17-202, 204-240

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b0469e05a5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".