eventcore-fs: ADR-0046: read-time fsck + dangling-transaction handling #393

New issue

Closed

opened 2026-06-12 21:34:03 -07:00 by jwilger · 0 comments

jwilger commented

2026-06-12 21:34:03 -07:00

Owner

Follow-up to PR #390 (eventcore-fs file backend). Covers the remaining git
robustness from ADR-0046.

Context

PR #390 wrote .gitignore and a defensive .gitattributes events/** merge=union.
Two robustness pieces remain: tamper/edit detection, and tolerating a partial or
aborted git merge.

Scope

Read-time fsck: reject any transaction file whose content does not match a
recorded content-hash anchor in its header. merge=union protects the
additive case but can mask an illegal edit of a JSONL file; the fsck catches
that loudly. (May require adding the anchor to the header — note the format is
immutable, so decide whether this is a v2 header field for new files.)
Dangling-transaction handling: a transaction whose parent_transaction_ids
reference files not present (a half-merged/aborted git merge) must be
reported as a DanglingTransaction via status(), never crash and never
silently drop. Linearization must remain robust to missing parents.

Acceptance

A hand-edited transaction file is rejected at open/read with a clear error.
A store with a transaction referencing an absent parent opens, and status()
reports the dangling transaction; reads do not panic.

References: ADR-0046, PR #390.

Follow-up to PR #390 (eventcore-fs file backend). Covers the remaining git robustness from **ADR-0046**. ## Context PR #390 wrote `.gitignore` and a defensive `.gitattributes events/** merge=union`. Two robustness pieces remain: tamper/edit detection, and tolerating a partial or aborted `git merge`. ## Scope - **Read-time fsck**: reject any transaction file whose content does not match a recorded content-hash anchor in its header. `merge=union` protects the additive case but can mask an illegal *edit* of a JSONL file; the fsck catches that loudly. (May require adding the anchor to the header — note the format is immutable, so decide whether this is a v2 header field for new files.) - **Dangling-transaction handling**: a transaction whose `parent_transaction_ids` reference files not present (a half-merged/aborted `git merge`) must be reported as a `DanglingTransaction` via `status()`, never crash and never silently drop. Linearization must remain robust to missing parents. ## Acceptance - A hand-edited transaction file is rejected at open/read with a clear error. - A store with a transaction referencing an absent parent opens, and `status()` reports the dangling transaction; reads do not panic. References: ADR-0046, PR #390.

jwilger added the

enhancement

P2-medium

labels

2026-06-12 21:34:03 -07:00

jwilger referenced this issue from a commit

2026-06-12 21:43:17 -07:00

docs(eventcore-fs): mark ADRs 0038-0046 as Accepted

jwilger added this to the 1.0.0 milestone

2026-06-13 05:44:58 -07:00

jwilger referenced this issue from a pull request that will close it,

2026-06-13 06:48:49 -07:00