Define the echo-cas adapter and transaction boundary #22

Outcome

Define how Echo consumes Keep as a physical content engine while preserving the boundary that Echo owns causal meaning and Keep owns exact physical bytes.

Dependencies

Blocked by #13, #16, #19, and #20.

Contract scope

The design must specify:

• conversion between Keep BlobId and Echo content identity;
• mapping from Echo semantic retention decisions to Keep retention namespaces and generations;
• stage, verify, retain, and Echo admission ordering;
• idempotency and reconciliation after interruption at every cross-system boundary;
• receipt fields binding logical identity, representation evidence, generation, and verification posture;
• error translation without erasing Keep's precise causes;
• sync versus async adapter posture;
• test/reference backends versus durable production backend;
• version and feature compatibility.

Acceptance criteria

• Keep's core API imports no Echo, Graft, Git, WARP, or application-policy type.
• Echo never commits a causal reference to content that lacks required verified physical retention.
• Physical material staged but not causally admitted has a documented orphan/reconciliation path.
• Rechunking, compaction, encryption, and storage migration cannot move Echo's logical content identity.
• Keep retention evidence is not described as proof of Echo lawfulness.
• Failure and retry behavior is specified for every cross-system step.
• The design includes a sequence diagram and crash-state table.
• Alternatives including embedding Keep directly into Graft and replacing Echo identity are evaluated.
• No subprocess or Node sidecar is required in the production storage path.

Non-goals

• Implementing the adapter.
• Defining Graft workspace policy.
• Migrating existing git-cas stores.