durable-commit — trusted persistence semantics

Use this skill whenever a design crosses a persistence boundary.

Mandatory model

Keep these states distinct:

proposal
!= CPU/program visibility
!= coherent/DMA visibility
!= device acceptance
!= device completion
!= durable persistence
!= trusted visible completion

Never use one as evidence for another unless the underlying device/OS contract explicitly guarantees it.

Canonical identities

Keep these concepts separate:

run_id       logical execution identity
request_id   idempotency identity
object_id    durable object identity
tid          durable order/version
content_hash content identity
epoch        reset/trust domain
timestamp    observation only
path         presentation only

A useful evidence tuple is:

(epoch, tid, object_id, content_hash)

Higher layers may attach run/request identity.

Commit rule

A completion may become visible only after its declared durability predicate is true.

TrustedComplete(N) => Persistent(N)

For ordered commits:

TrustedComplete(N) => required predecessors are also persistent

Immutability

Committed facts are append-only.

Corrections and supersession create new committed facts; they do not rewrite history.

Prefer a minimal trusted head:

(epoch, last_tid, root_hash)

with immutable history stored outside the trusted block.

Retry rule

Retries reuse the same logical request_id.

The authoritative persistence layer decides whether that request has already committed.

Do not turn transport retries into new logical mutations.

Recovery review

For every state variable classify:

• volatile
• durable
• reconstructable
• forbidden to reconstruct

Recovery must never invent a commit.

Hardware boundary

FPGA/ASIC logic should own only invariants that earn dedicated hardware.

Good candidates:

• completion gating
• monotonic durable sequence
• epoch / anti-replay
• tiny integrity root
• independent progress/error state

Keep on CPU/BSD unless measurement proves otherwise:

• filesystem
• policy
• recovery strategy
• networking
• agent runtime
• PQC protocol
• generic DMA/SHA/ring implementations

Storage-background questions

Before accepting a design, ask:

1. What does the media/controller call "complete"?
2. Is volatile controller cache involved?
3. What do FUA/flush/barrier semantics actually guarantee?
4. What happens across power loss?
5. What is the authoritative persistence acknowledgement?
6. Can stale completions or old epochs be replayed?
7. Can a compromised host forge the claimed completion?

TEE / trusted-boundary rule

Treat the lower block as a root of durable truth, not merely an accelerator.

The host may propose a mutation. It must not be able to fabricate a trusted committed result the lower boundary did not observe.

Do not build

Reject by default:

• duplicate lineage/state databases
• hardware filesystem/path semantics
• general-purpose async I/O APIs
• queue/ring semantics baked into the persistence contract
• Linux as a target architecture
• PQC in the per-commit hot path
• a RISC-V softcore before pure RTL earns the need

Canonical references

Read before changing the architecture:

• docs/CONSTRAINTS.md
• docs/RESEARCH-INDEX.md
• scaffolds/durable-tid/docs/DESIGN.md
• scaffolds/durable-tid/docs/FORMAL.md
• rfcs/0004-three-superstation-pre-asic-lab.md
• rfcs/0005-formal-verification-before-rtl.md