Skip to content

Implement immutable append-only segment writing and verified reading #15

Closed

Description

@flyingrobots

Outcome

Persist chunk and layout records into bounded append-only segments and read them back only after structural and identity verification.

Dependencies

Blocked by #13 and #14.

Acceptance criteria

  • Staging and sealed segment states are represented by distinct types.
  • Record and segment headers match golden format fixtures exactly.
  • Writes handle short writes, interruptions, full disk, permissions changes, and sync failures.
  • Sealing is explicit, fallible, #[must_use], and follows the ADR's durability order.
  • Readers validate framing, bounds, checksum, record identity, and trailing-state rules before trusting payloads.
  • Sealed segments cannot be mutated through the public API.
  • Partial tails, conflicting duplicate records, unsupported versions, unknown flags, and checksum mismatch return exact typed errors.
  • Memory and allocation remain bounded by configured record and chunk limits.
  • No filesystem enumeration is used as the normal content index.
  • Corruption and crash-injection tests cover every write boundary implemented by this issue.

Non-goals

  • Catalog publication.
  • Retention or garbage collection.
  • Compression, mmap, direct I/O, or unsafe optimization.

Activity

  1. added
    kind:testTest infrastructure or failure-mode evidence
    area:segmentPhysical immutable segment representation
    area:verificationIntegrity verification and corruption posture
    on Jul 20, 2026
  2. added
    area:formatCanonical durable formats and decoding
    area:identityLogical content identity and typed coordinates
    area:readReconstruction, streaming, and byte-range reads
    on Jul 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:formatCanonical durable formats and decodingarea:identityLogical content identity and typed coordinatesarea:readReconstruction, streaming, and byte-range readsarea:segmentPhysical immutable segment representationarea:verificationIntegrity verification and corruption posturekind:implementationProduction implementation workkind:testTest infrastructure or failure-mode evidence

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions