[dinakarjs]

The journal in #144 deliberately leaves lost acknowledgements unresolved. Propose an operator-led authenticated readback flow that can establish matching inclusion without turning timeout or an unsigned negative lookup into permission to resubmit.

This is an informative design-only draft on current main. It specifies conservative unknown states, archival and transactional reconciliation boundaries, and future positive/negative/crash/concurrency cases. It asks maintainers to choose the readback API, identity/key-rotation policy and retry contract before implementation. No runtime files from #144 are included; no witness is contacted, no automatic retry or deployment is enabled, and #144 is not closed.

Validation: manually checked against #144's exact-bytes/trust-policy identity and documented limitations; git diff --check passes. No executable behavior changed, so no runtime test result is claimed. AI-assisted with Codex; DCO signed.

[dinakarjs]

@lywinged Could you review the authenticated readback contract in this design draft and advise on the first supported readback API, key-rotation handling, and the conditions for retry? The journal in #144 retains an unknown state after a lost acknowledgement. This draft proposes a way to resolve it when authenticated evidence is available, with no live witness request or automatic retry enabled.

[dinakarjs]

Design review and recommendation (author follow-up; not independent approval)

Reviewed #156 at b7a0212 against #144 at e70c10c, and the capture/verifier implementation at shared base 555f27a. This recommendation extends the existing proposal; it does not select a deployed protocol or authorize implementation, automatic retry, or deployment. No runtime tests were executed for this assessment.

Recommendation

Use checkpoint-signing-digest readback as the first API candidate:

GET {configured_witness_base}/v1/inclusion/{checkpoint_signing_digest}

The existing capture tool already uses this route shape. Maintainers/witness operators must confirm its supported lookup, response and retention contract before implementation. Retain #144's exact-bytes-plus-policy journal identity and permit inclusion-only reconciliation, with no automatic resubmission.

Existing guarantees and limits

#144 commits a durable claim before network I/O; only pending records are submit-eligible. Failures become unknown and killed workers may leave inflight. Its local identity is SHA256(exact checkpoint bytes || NUL || serialized trust policy), including witness URL, expected log ID, registry key and witness key. A changed serialization or policy creates a different identity, not semantic deduplication across rotation.

Keep three identities distinct:

• Local journal identity: exact bytes plus serialized policy.
• Lookup input: SHA256 of the canonical nine-field checkpoint signing body.
• Existing legacy entry hash: SHA256 of the signing-body digest bytes.

The verifier authenticates the signing-body statement, registry signature, witness receipt signature/inclusion and proof coordinates. It explicitly does not establish full checkpoint-envelope witnessing or registry continuity. Matching readback proves inclusion of the intended content; without an authenticated operation identifier it does not prove that this particular lost-ACK attempt caused inclusion, or that only one submission occurred.

Current capture success also requires successful POST and both GET responses carrying identical receipt bytes. Readback therefore needs a separately identified verification path: never reconstruct a successful POST or imply that the original capture criteria passed.

Contract comparison

Option	Minimum binding/security	Rotation, replay and unresolved behavior	Compatibility
Exact checkpoint bytes	Derive the expected signed statement from frozen bytes and verify inclusion. Full-byte attestation additionally requires an authenticated raw-byte digest; an unsigned echo is insufficient.	Preserve original bytes/policy. Historical matching inclusion does not prove freshness or attempt attribution. Missing data remains unresolved; returned serialization cannot replace frozen bytes.	Requires an agreed read-only lookup. Never reuse the submission POST as lookup. Full-envelope witnessing exceeds the current receipt profile.
Receipt ID	Either authenticate the ID-to-statement/witness binding, or treat the ID only as a locator and independently verify the returned inclusion proof. Scope IDs and prevent reuse/remapping.	Another witness/checkpoint's ID must fail. Unknown ID remains unresolved. A lost ACK may leave no retained ID at all. New-key lookup cannot authorize a new key.	Secondary locator when already archived; unsuitable as the primary lost-ACK recovery mechanism unless known before submission or deterministically recoverable under an agreed contract.
Checkpoint signing digest	Derive from frozen checkpoint; verify expected log/registry identity, signature, legacy entry hash, witness signature/inclusion and coordinates under pinned policy.	Matching historical evidence can prove inclusion. Wrong statement/key fails. Timeout, 404, malformed data and authenticated conflicts cannot authorize retry.	Closest fit to existing route and verifier; preferred candidate, subject to maintainer confirmation.

Different valid receipts for one statement at different tree sizes are not automatically contradictory. Incompatible authenticated roots for the same tree identity and size require investigation. The current verifier does not provide general consistency checking, so do not claim continuity or comprehensive equivocation detection.

Inclusion is not non-inclusion or retry authorization

• A valid inclusion proof establishes membership in the authenticated tree represented by that receipt.
• HTTP 404, empty lookup or unsigned absence only means no acceptable inclusion evidence was obtained.
• A signed “not found” is an assertion, not automatically a complete non-inclusion proof.
• Verifiable non-inclusion requires a defined authenticated snapshot and a data structure/proof scheme capable of proving absence. Even then, the delayed original request might commit after that snapshot.

Idempotent retry requires a separately accepted witness contract: stable operation key bound to payload and witness namespace; atomic deduplication with commit; rejection of key reuse with different content; durability across crash, concurrency, failover and rotation; explicit retention/expiry and result semantics. An absence-based alternative additionally needs finality/fencing that prevents the original operation from subsequently committing.

Existing archived-response/local deduplication tests do not independently establish those server guarantees.

Minimum reconciliation and rotation properties

1. Freeze original bytes, journal identity, policy and evidence location.
2. Retrieve only from an operator-configured endpoint; enforce destination/redirect policy. Evidence-supplied URLs cannot expand network authority.
3. Reuse the cryptographic verifier against frozen inputs and pinned keys. HTTP status, unsigned JSON flags and local manifests are not authentication.
4. Archive response bytes, request observations, verifier version/inputs/result and hashes in a new exclusive directory before promotion. Preserve original submission evidence.
5. Transactionally compare current state, identity, policy and reconciliation snapshot before promotion; record readback as the verification basis.
6. Missing, malformed, wrong-key, mismatched or contradictory evidence remains unresolved; never reset to pending or call submit.

Initially reconcile unknown only. Leave inflight to operator investigation until worker ownership/completion races are specified. #144 currently completes submit using UPDATE by record ID alone: a late worker can overwrite a reconciliation verdict. Conditional updates must cover both submit completion and reconciliation; a transaction on the reconciliation side alone is insufficient.

Default to the original pinned policy. New keys require explicit independent authorization, never discovery from the response. Policy migration must preserve original and replacement policies plus authorization; never re-enqueue under a new policy to bypass uncertainty. Revocation rules remain a maintainer decision. Historical receipts may lack signed issuance time, so local timestamps cannot prove pre-compromise issuance.

Independently testable acceptance cases

Use local signed fixtures with independently pinned keys. Every rejection needs a passing control and a guard-disabled/mutation case that demonstrates the test detects the missing check.

Scope	Cases
Common authentication	Lost ACK plus matching inclusion resolves once; wrong checkpoint/log/registry key/witness key fails; corrupt signature, inclusion proof or coordinates fails; malformed/truncated response remains unresolved.
Missing/negative evidence	Timeout, 404, empty result, unsigned absence and signed assertions without an accepted absence contract never cause POST or pending reset.
Exact bytes	Preserve original bytes; whitespace variants distinguish local byte identity from signed-body identity; altered envelope fields cannot gain a full-byte-attestation claim.
Receipt ID	Missing ID remains unresolved; another witness/checkpoint's ID fails; reused/remapped IDs fail; unsigned locator metadata cannot determine acceptance.
Signing digest	Distinguish signing digest from legacy entry hash; reject response-binding mismatch; serialization variants retain distinct local journal identities.
Rotation/replay	Original authorized key passes; discovered/new key fails by default; policy change during verification prevents promotion; historical receipt does not imply freshness or attempt attribution.
Conflicts	Different tree sizes are not automatically equivocation; genuine authenticated incompatibility is archived and blocks automatic resolution.
Durability/concurrency	Concurrent reconcilers cannot overwrite outcomes; crashes before/after archival and transaction remain recoverable; late submit completion cannot clobber reconciliation; original evidence remains immutable.
Compatibility	Preserve existing identity/state/CLI behavior and database readability; retain capture regression coverage; never fabricate missing POST observations.

Decisions reserved for maintainers

Please select/confirm: the supported endpoint and signed response profile; whether verified encompasses authenticated inclusion via a distinct readback path; rotation/revocation and policy-migration rules; historical lookup/archive retention; conflict handling and inflight ownership; and any separate idempotency/retry and deployment contract.

Until those decisions are accepted, retain #156 as an informative design draft and #144's fail-closed unknown/inflight behavior. No implementation or live witness operation is proposed by this review.

AI-assisted analysis with Codex.