`jsonl-adapter`

Purpose

examples/jsonl-adapter is a worked reference implementation of the storage ports harmos declares — a complete, durable, tested fold with a codec attached, published so an application can read one end to end and copy what it needs.

It is an example to copy, not a supported dependency. Nothing in the workspace promises it will keep its shape, and no application is asked to name it in a manifest. An application that vendors these files owns them, is free to change the on-disk layout, and answers to nobody's compatibility but its own. An application with different durability needs — object storage, a database, a columnar artifact — writes its own adapter against the same ports, and the runtime cannot tell the difference.

Harmos ships storage contracts and never a storage engine. Storage, Source, Series, Vault, the consumer fold, and the encode boundary are declared in harmos, beside the journal they serve.

Public Surface

The crate is jsonl-adapter, reached in Rust as jsonl_adapter.

• Jsonl (src/journal.rs) stores and recovers one ordered journal copy.
• Sidecar (src/journal.rs) coordinates generation-checked document saves with a JSONL recovery journal.
• Wire (src/journal.rs) is what the adapter asks of an application: identify, encode, and restore its own catalog payloads.
• Snapshot (src/snapshot.rs) folds a private state replica and writes it on a declared policy.
• JsonlStreams (src/streams.rs) records selected stream feeds as one JSON line per row, resumable from its own durable cursor and honest about loss.
• jsonl_adapter::streams::read_rows reads one capture back as typed rows.
• EvidenceDirectory (src/evidence.rs) keeps evidence bytes as staged drafts, verified kept evidence, and a quarantine that loses nothing.

Data Flow

Jsonl receives Batch<A> values, encodes each Recorded<A> through Wire, and advances its durable resume position. When designated as the recovery source it returns an origin plus the payloads after it. Snapshot folds the same order into an independent state replica. JsonlStreams receives stream batches by cursor, appends complete lines to one file per selected stream, and advances a checkpoint beside them. EvidenceDirectory implements the Vault port: it stages a draft, makes it durable and recomputes its digest, and renames it only after the journal fact naming it is durable.

Design Rules

• Every adapter here is a checkpointed consumer; none owns or constructs a journal.
• Rust catalog variant names never enter a stored representation.
• A sidecar generation mismatch is not applied to an unrelated document.
• Evidence is claimed only after its fact is durable, and nothing is ever deleted.
• A captured row retains its journal position and carries exact gap evidence after loss.
• Snapshot truth status follows retention: it is a cache only while its prefix remains rebuildable.
• Every durable write follows one sequence — write, sync the file, rename, sync the parent directory.

Known Gaps

The crate implements the journal, snapshot, stream-capture, and evidence ports. It implements no Series, so nothing here serves reads beneath a stream's window; that port is an application's to implement (Serve Beneath the Window). It is not a database or object-store backend, and no vault sweeps its own quarantine. An application provides its Wire crossing explicitly; the core crate cannot choose or infer that format.

The JSON Lines journal format is documented as a contract in its own right, so a reader in another language can meet the same history: see The JSONL Wire Format.