Skip to content

V-L2-F4: harden JSON sidecar (cross-process locking + atomic writes) and wire provenance/history CLI #150

@hyperpolymath

Description

@hyperpolymath

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 rename durability already in save(), 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 at T) for the entity. Both backends.
  • postgres reads 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.json permission allowlist to reduce harness friction.

Acceptance

  • JsonStore writes are guarded by a cross-process lock and remain crash-safe (atomic rename); concurrent gc/append don't corrupt or lose data.
  • provenance and history work 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions