ADR: define segment format, publication order, and crash states #14

Outcome

Define the first durable physical protocol as one inseparable triple: forward write protocol, possible crash states, and recovery behavior.

Dependencies

Blocked by #3, #10, and #13.

Decision scope

The ADR must define:

• immutable segment framing, headers, records, seals, checksums, and bounds;
• append and sealing state transitions;
• catalog generation format and publication head;
• exact flush, sync, rename, and directory-sync ordering;
• one-writer/many-reader lock scope and stale-lock handling;
• visibility rules for staged, sealed, published, orphaned, and retired material;
• stable crash-point identifiers;
• recovery outcomes for every interruption boundary;
• platform assumptions and unsupported filesystem behavior.

Acceptance criteria

• Segment and catalog formats have magic, versions, canonical encoding, explicit endianness, checksums, bounds, and golden fixtures.
• Sealed segments are immutable.
• File existence alone never proves completeness, identity, publication, retention, or durability.
• Publication uses an explicit method and never relies on Drop.
• Every write step has enumerated pre-step and post-step crash states.
• Recovery classifications distinguish reusable staged material, valid orphan, truncated tail, corrupt sealed state, stale generation, and unrecoverable ambiguity.
• Readers have a documented view while publication occurs.
• Alternatives including one-file-per-chunk, embedded databases, Git objects, and monolithic append logs are evaluated.
• No application or Echo policy enters the physical protocol.

Non-goals

• Implementing the protocol.
• Retention-root semantics.
• Garbage collection or encryption.