Repository navigation
V-L2-F4: harden JSON sidecar (cross-process locking + atomic writes) and wire provenance/history CLI #150
Description
Follow-up to #146 (JSON-family sidecar backend). Two threads:
1. Harden the JSON store
- Cross-process write locking: serialise concurrent writers to a json sidecar (the SQLite path serialises via the DB write lock; the json path was single-writer-by-assumption). Dependency-free advisory lock file (
<path>.lock) with backoff + stale-lock steal; RAII release. - Atomic writes: formalise the temp-file + same-dir
renamedurability already insave(), held under the write lock across the load→mutate→save cycle.
2. Wire the stub CLI subcommands
provenance <entity>: list the entity's provenance chain and report verification (verify_chain) + any fork points. Both sqlite and json backends.history <entity> [--at T]: list temporal versions (or the point-in-time snapshot atT) for the entity. Both backends.postgresreads remain explicit "not yet implemented".
3. Docs + config
- rustdoc + README section on sidecar backends and the now-working subcommands.
- Example manifest showcasing
storage = "json"/format. - Version bump + CHANGELOG.
.claude/settings.jsonpermission allowlist to reduce harness friction.
Acceptance
-
JsonStorewrites are guarded by a cross-process lock and remain crash-safe (atomic rename); concurrentgc/append don't corrupt or lose data. -
provenanceandhistorywork against both sqlite and json sidecars (tests cover both). - Docs, example, version/CHANGELOG, and settings updated.
- CI (fmt/clippy/test on MSRV+stable) green at source.
Activity
hyperpolymath commentedon May 30, 2026
Closed by #151 (
00fd80f). Delivered:<path>.lock(O_EXCL, retry/backoff, stale-steal, RAII release) viajson::with_locked, held across load→mutate→save;gcapply runs through it. Atomic temp-file +renamedurability documented.provenance/historyCLI wired for sqlite + json (postgres refuses); end-to-end test (tests/sidecar_cli_test.rs) seeds via the locked write path and drives the binary.examples/json-sidecar/, version0.1.0→0.2.0+ CHANGELOG.One item not completed: the
.claude/settings.jsonpermission allowlist was blocked by the agent self-modification guardrail (an agent can't widen its own permissions). It needs to be added by a maintainer directly if desired — everything else in the acceptance is done.Generated by Claude Code
docs(adr): ADR-0013 — json sidecar cross-process locking (V-L2-F4) (#153
hyperpolymath commentedon May 30, 2026
Decision record added: ADR-0013 (
docs/decisions/0013-json-sidecar-cross-process-locking.adoc) now documents this hardening — the cross-process advisory lock, atomic-rename durability, and the wiredprovenance/historyCLI — framed as refining ADR-0012 (the F3 JSON-family backend). ADR-0012's single-writer note was updated to point at it, and aCHANGELOG.mdentry added (#153). No reopen needed — #150 stays closed/completed (implemented in #151).Generated by Claude Code