docs(storage): freeze acknowledged durability and isolation guarantees

[DecisionNerd]

Problem

ADR 0013 specifies a strong file/directory flush protocol, and current concurrency docs describe three write modes, but the public contract does not consolidate exactly when a write is acknowledged, what survives which crash boundary, or which isolation level each mode provides. The absence invites both underclaims and false serializability claims.

Objective

Freeze one versioned durability/isolation contract against current behavior before adding new recovery, delta, transaction, or maintenance surfaces.

Debt / regime

• Debt type: documentation, architecture, and test/proof.
• Quality regime: A — deterministic storage correctness.

Requirements

• Define acknowledgement relative to participant/manifest flushes, CURRENT replacement, and project-root directory flush.
• Define supported filesystem preflight and explicitly exclude unproven filesystems.
• State recovery authority: exact valid CURRENT only; journals and directory scans are advisory.
• State reader snapshot isolation and writer semantics for all three write modes.
• Include a minimal write-skew witness showing why optimistic mode is not SSI/serializable.
• Define idempotency, retry, cancellation, unknown-outcome, and post-linearization error behavior.
• Reconcile ADR 0013, ADR 0014, concurrency/recovery architecture, API docs, and machine-readable contracts.
• Require an ADR amendment for any semantic change rather than silently changing the contract.

Acceptance Criteria

• One normative contract names the acknowledged-durable boundary and platform/filesystem scope.
• Every public write mode has an explicit isolation/conflict table.
• Documentation neither claims generic ACID/serializability nor understates the existing immutable snapshot guarantees.
• A machine-readable matrix maps crash phases and transaction anomalies to required outcomes.
• Existing tests are mapped to covered cells; uncovered cells become requirements of later M6 issues.
• M5 import/export issues reference the same publication vocabulary where applicable.

BDD Completion Scenarios

• Given a caller receives success, when the contract is consulted, then the durable state and supported crash assumptions are unambiguous.
• Given two optimistic transactions form a write-skew history, when isolation is evaluated, then the docs classify it honestly rather than claiming serializability.
• Given an unsupported filesystem, when a durable project is opened or created, then the contract requires fail-closed preflight rather than best effort.

Implementation Notes

Likely surfaces: docs/adr/0013-project-generation-protocol.md, docs/adr/0014-workspace-checkpoints.md, docs/book/architecture/concurrency-recovery.md, docs/reference/api.md, and tests/contracts/concurrency-recovery-matrix.json.

Observability

Define safe phase, commit-state, recovery, and maintenance fields without graph contents, UUID payload data, or sensitive paths.

Security And Privacy

Integrity failures must fail closed; diagnostics may expose machine-owned IDs and safe phase classes, never participant contents.

Testing

Contract-schema validation and documentation link/build checks. Map each BDD scenario to a machine-readable matrix assertion.

Non-Goals

Implementing SSI, a new journal, or changing CURRENT authority.

Related Issues

Canonical tracker: #747. Foundations: #190, #211, #212, #369. Adjacent M5 work: #738, #742, #745.