Crate blockworx_store 

The durable store: the .bwx container, the rev files that are the document, and the manifest that names them. Rationale: docs/json-format.md; docs/log-vs-snapshot.md.

Commit ──▶ Document ──▶ revs/{rev}.json.gz ──▶ one row of manifest.jsonl

The rev files are authoritative and everything beside them is derived, so this crate is written for one property: what the editor holds and what the files hold agree at every point a call can return. A rev lands and is fsync’d before the row that names it; loads verify every chain link and the head rev’s own bytes before the document is shown; and the container gives up its lock rather than write into a history it has already lost track of.

All of it is target-independent: the container’s layout is written once over a Storage that says only where the bytes go, so the browser reads the same rows and revs out of its origin storage that a desktop reads out of a directory, and a session with no files at all stands its revs in memory.

Modules

assets

Artwork at the container boundary: assets/<hash>.<ext> is the one home for bytes, and everything else keeps only the hash.

atomic

Crash-safe file writes.

container

The .bwx container: a manifest, the revs it names, and the artwork they place.

doc

The editor’s document handle: the two places a document can live, as one enum.

document_file

The document file: JSON is the one document format, and blockworx_doc::document::Document is the single source of truth for it — serde’s derives on the model are the codec, both directions (docs/log-vs-snapshot.md §8). This module is only the two doors: the spanned parse diagnostic, and the pretty-printed write.

dump

blockworx log and blockworx verify: a container’s audit trail on the console, and the fsck that proves it whole.

file

What a path names, and the container doors that take one. The one module here that is still native by nature: a browser has no filesystem to point at, and reaches its containers by name instead. What a path names: whether it is a diagram, and where one is saved or renamed to. A diagram is a container, which is a directory.

handle

The store: a container and the Repo it holds, joined so that every accepted commit reaches the files before the call returns.

history

The audit trail as text: one row per rev, for blockworx log and the editor’s history panel. Rationale: docs/single-author-playbook.md.

lock

The advisory single-writer lock: a lock entry naming the process that holds the container open for writing.

manifest

manifest.jsonl: one row per rev, and one per tag. Rationale: docs/log-vs-snapshot.md §10.1 and §14.2.

migrate

Carrying a container written when revs were zstd over to gzip. Native only, and the last thing in the tree that names zstd. blockworx migrate: a container written when revs were zstd, read by a build that writes them as gzip.

naming

What a new document is called, and where it is born.

prefix

Save-as over a container: a new one holding the source’s manifest up to a rev, line for line, and the rev files those rows name.

recent

The documents to offer reopening, most recent first.

record

The circumstances of a write: who, when, where they were standing, and what they were looking at. Rationale: docs/single-author-playbook.md (the author identity and the hash chain) and docs/log-vs-snapshot.md §10.1 (the camera).

revs

revs/: the whole document at every rev — the document itself (docs/log-vs-snapshot.md).

stamp

The stamp a document carries when it leaves home.

storage

Where one container’s bytes live.

tags

Rev tags: the free-text names a manifest’s tag rows give its revs. A projection of the manifest, not part of the document — the fold never sees one, and Ctrl+Z after tagging still takes back the last edit.

transfer

A container as one file: the .bwx.zip a document travels in.

worked

What an act touched: the scope its author was standing in and the entities its ops named.

Enums

Refusal

Why a write did not happen. Target-independent because the editor’s document handle (doc::Doc) reports refusals in one spelling whether it is holding a container or an in-process session, and the web build has only the latter.