cadrumo.application.journal_repository module

Atomic per-file JSON persistence substrate for operation journals.

A journal repository persists a credential-free typed operation record as an individual JSON file under a dedicated directory outside bucket storage, with an atomic hardened write, restrictive 0700/0600 permissions, symlink and junction refusal, and a storage-root containment check. This is the constraint-shape-agnostic half shared by the reset-operation and profile-export journal repositories: each concrete repository binds its journal directory name, operation model parser, error types, and message subjects, and adds its own divergent lifecycle surface (creation exclusivity and ownership verification for reset; scanning, deletion, and prepared-state selection for profile export) on top of this base.

Atomicity applies to an individual journal-file write or replace, not to an entire multi-step operation. The substrate provides no orchestration and no cryptographic authenticity guarantee.

class JournalOperation(*args, **kwargs)

Bases: Protocol

Structural contract a journal operation model satisfies.

Every journal record carries a 64-hex operation_id (the filename identity) and a started_at timestamp (the primary ordering key), and serializes itself to JSON.

property operation_id: str

Return the filename identity of this journal operation.

property started_at: datetime

Return the timestamp used to order journal operations.

class JournalRepositoryBase(*, journal_dirname, storage_root, parse_operation, error_type, not_found_type, corrupt_type, subject, id_subject)

Bases: Generic

Atomic per-file JSON persistence shared by operation-journal repositories.

Concrete repositories bind the journal directory name, the operation model parser, the error taxonomy, and the message subjects, then layer their own divergent lifecycle methods over the shared read/write substrate this base provides.

Parameters:

• journal_dirname (str)

• storage_root (Path)

• parse_operation (Callable[[str], T])

• error_type (type[CadrumoError])

• not_found_type (type[CadrumoError])

• corrupt_type (type[CadrumoError])

• subject (str)

• id_subject (str)

property root: Path

Return the journal directory under the storage root.

property lock_target: Path

Return the sidecar target guarding every journal write.

Holding it is how a caller (or a crash-window proof) makes a concurrent journal write wait; it is a real coordination point, not an implementation detail.

path_for(operation_id)

Return the journal path for one validated operation identifier.

Return type:

Path

Parameters:

operation_id (str)

save(operation)

Atomically write or replace the complete journal for operation.

Return type:

None

Parameters:

operation (T)

load(operation_id)

Load and validate one operation journal.

Loading refuses missing or unreadable files, malformed JSON, schema-invalid payloads, and mismatches between the filename and payload identifiers. Validation provides no MAC, signature, or other authenticity proof.

Return type:

T

Parameters:

operation_id (str)

list()

Load JSON journals ordered by start time then operation identifier.

Non-JSON files are ignored. Corruption in a selected *.json journal propagates rather than being skipped.

Return type:

tuple[T, …]