feat(hermes): add acknowledged checkpoint and retry-safe memory delivery contracts

[joshyorko]

Existing-corpus delivery amendment — September 8, 2026

Receipt/checkpoint improvements must interoperate with already-written memories, historical imports, existing mirror/bootstrap acknowledgement state and any supported pre-upgrade pending deliveries. Use #233 identity/receipt semantics and #234's shared previewable legacy reconciliation; do not rebuild delivery or migrate the corpus implicitly.

Core guarantees: legacy records lacking event IDs or durable acknowledgements remain usable as policy-permitted evidence with delivery/provenance gaps visible. Do not fabricate an old commit receipt, caller identity, source time or user adoption. A new reconciliation acknowledgement may confirm what exists now, but is not evidence of when the original event occurred or that a historical delivery succeeded exactly once. Preserve record handles, bundle origins, sources and known corrections independently from delivery bookkeeping.

Adapter behavior: version and validate existing mirror/bootstrap mapping schemas and any outbox formats before reuse. Inventory known-owned IDs, uncertain ownership, completed receipts and unresolved deliveries. A hash/content match alone cannot acquire deletion ownership. Unknown legacy delivery cannot be declared saved, blindly replayed as a fresh conclusion, dropped without a report or folded into another session. Reconciliation preview shows proposed mappings/retries, conflicts and unresolved cases; reviewed apply is bounded/idempotent and protects concurrent updates. Startup, reconnect and initialize() perform no silent history import, acknowledgement manufacture or global re-key.

A checkpoint may reference useful historical/imported/other evidence without recasting it as a newly observed user turn. Preserve source speaker/time and current/uncertain/corrected/withdrawn status; a snapshot's creation date is not all of its contents' observation date. Existing summaries with unknown source ranges remain attributed summaries, not reconstructed verbatim turn coverage. Known withdrawn content must not regain current status via delayed retries, overlap, compaction, old archive import or restored adapter state. Unknown equivalence is reported, not promised away.

Consumer rollout: back up the authoritative store and compatible adapter receipt/mirror state together with their relationship/version manifest where applicable; restore only into isolated targets for drills. Reconcile server-committed/client-unacknowledged writes and post-backup corrections before draining old pending deliveries. Preserve subsequent legitimate writes, known withdrawals and ownership on rollback. No blanket purge or resend-all fallback.

Additional acceptance gates

• Start with a pre-change DB plus legacy mirror/bootstrap mappings, retained Codex/Hermes imports and transferred records. Include missing acknowledgements, dedup hits not owned by this adapter, and absent source timestamps/lineage.
• Preview/cancel makes no durable change. Apply/retry/restart preserves refs/origins and distinguishes confirmed current acknowledgement from uncertain historical delivery.
• Exercise daemon-commit/lost-ack, local receipt failure, concurrent correction, session switch and interrupted reconciliation across the upgrade. Unknown ownership never permits deletion.
• Checkpoint after upgrade references permitted old evidence without promoting it or resetting time; historical usefulness is preserved without replaying the entire corpus into every checkpoint.
• Restore pre/post-change server and adapter snapshots, including mismatched versions and delayed pre-correction deliveries. Known equivalent withdrawn content is not resurrected; unresolvable pairing/lineage produces explicit limits and no unsafe replay.
• Required checkpoints still apply only to supported compaction modes. Legacy uncertainty does not justify blocking all normal conversation or claiming earlier compaction was protected.

---

Outcome

Memory writeback remains fail-open for conversation, while an explicitly requested durable checkpoint can truthfully report committed, pending, rejected or unavailable. Repeated delivery cannot create duplicate evidence, lose mutation ownership, or inflate confidence.

Priority: P1 for checkpoint/delivery conformance after #233 defines stable contribution receipts. Independent existing-turn regression tests may land earlier.

Baseline

At 25d617b5f08593c76d336f90b8ffd1e78f77afbd, the native adapter implements sync_turn, memory mirroring and a bootstrap acknowledgement DB, but not pre-compress checkpoints or delegated-result capture. #229 explicitly documents ambiguity after an unacknowledged server commit. Mirroring correctly owns only newly created IDs, never dedup hits.

Use the native Hermes lifecycle and existing MemoryD checkpoints/evidence store. Do not bolt on another conversation/session manager.

Research and capability gate

Hermes now documents pre-compress checkpoint API v2: a provider can advertise durable checkpoint completion; operator checkpoint_required controls whether a failed checkpoint blocks the lossy rewrite. v2 filters normalized visible user/assistant evidence and excludes prior summaries/tool payloads.

Important: that strict gate changes which compaction mechanisms are allowed and is not compatible with a Codex app-server mode whose compaction Hermes cannot intercept. Inspect the exact deployed Hermes revision and modes. Do not enable it globally or claim unsupported native-server compaction is protected.

Delivery slices

A. Acknowledged writes

• Consume feat(continuity): land one governed observe-to-episodic-recall vertical for #228 #233's principal/scope/event idempotency and receipts rather than inventing client-only exactly-once semantics.
• Test server commit then client timeout, process exit, replay, competing writers, and local mirror DB failure.
• If retries are needed, first reuse Hermes' actual delivery facilities. Any minimal provider-local outbox must be bounded by bytes/age/count, screened before persistence, profile-private, observable, and drained through owned lifecycle; no independent daemon.
• Do not persist raw transcript backups as a side effect of retrying one safe event. Define explicit rejection/drop/dead-letter behavior.
• A saved indicator means server acknowledgement, not successful HTTP dispatch. Ambiguous acknowledgement stays pending/unknown until reconciled.
• Preserve ownership checks across add/remove/replace; never adopt someone else's matching record after a lost response.

B. Checkpoint boundary

• Add the supported pre-compress hook and explicit checkpoint operation behind capability detection.
• Ordinary recall/writeback stays fail-open. Strict pre-compaction durability is a separate opt-in with actionable failure and a safe retry path.
• Bind checkpoint to producer, session/thread, covered event range/digests, temporal basis, requested task and source references. Overlapping retries deduplicate individual events, not merely whole transcript blobs.
• Preserve distinctions between observed user instruction, assistant report, compacted summary and verified tool/action receipt. Only safely normalized, permitted evidence enters the store.
• Session switching, cancellation, shutdown and late delegated results cannot attach work to the wrong session.

Acceptance

Real Hermes MemoryManager tests plus isolated HTTP service fixtures prove:

• failed post-turn write does not fail the conversation;
• commit/lost-ack/retry yields one evidence event and a stable receipt;
• required checkpoint blocks only supported lossy compaction until committed;
• best-effort mode stays responsive and explicitly reports missing durable evidence;
• overlapping pre-compression windows and prior summaries do not amplify evidence;
• crash/restart and profile switching do not leak or duplicate private memory;
• queue bounds and retry age/count limits work under prolonged outage;
• no hidden reasoning/tool scratchpad/credential is captured;
• capabilities report unsupported external compaction honestly.

No automatic recall-triggered execution, no new scheduler, no unbounded outbox, no broad remote auth work. Consumers prove their own running-plugin activation and task-handoff UX separately.