liminis-context-graph v0.12.2 — the WAL as a source of truth

[verveguy]

v0.12.2 is out — a patch release making the WAL usable as a source of truth.

Both changes come from #351, a field report from a deployment moving to a "WAL is authoritative, DB is a derived cache" model: every node rebuilds its local graph from a distributed WAL on boot, and needs to answer one question cheaply — does my DB already reflect this WAL?

Boot-time consistency is now one call and one comparison

knowledge_status returns two new fields in its wal object:

• wal.applied_seq — the highest WAL seq whose mutations are committed in this graph, persisted in the DB and surviving restart
• wal.max_seq — the highest seq present across the WAL files

Which makes the reconcile decision a pure integer comparison:

Condition	Action
applied_seq == max_seq	up to date — skip rebuild
applied_seq < max_seq	incremental: rebuild_from_wal {from_seq: applied_seq + 1}
applied_seq > max_seq, or diverged	full: rebuild_from_wal {from_seq: 0, force_clear: true}

Previously there was no way to link DB content to a WAL position at all. The reported workaround — hashing WAL file bytes — broke across a publish round-trip, because a Python republisher re-serializes {"seq":1596,...} as {"seq": 1596, ...}. Identical semantics, different bytes, so every boot looked "changed" and forced a full rebuild.

No upgrade cliff. An existing DB has content but no recorded position. Rather than reporting that as unknown and making every deployment do one forced rebuild, lcg backfills the position on first open using ADR-0026's episode cursor, which was built to be retroactive. null now means only "backfill genuinely failed", and the documented action there is a full rebuild.

Duplicate WAL sequence numbers fixed

WalWriter's global_seq was derived once at process start and never re-derived. A WAL directory populated after startup — external seed, backup restore, distributed-WAL pull — followed by a rebuild left the writer re-emitting sequence numbers already on disk. In a published WAL consumed by other nodes, that means seq stops being a unique identifier.

It now re-derives after every rebuild and clear, combining the replay's last_committed_seq with a fresh on-disk scan, and only ever raises the counter. The undocumented "seed the WAL before starting lcg" ordering constraint is gone.

This one had to land first: the applied_seq comparison above is only sound if seq is unique.

Upgrading

Drop-in from 0.12.x. Both wal fields are additive. The WalPosition table is created on open, and the position backfills itself.

Consumer semantics are in docs/operations.md — including a null < 5 coercion note for JavaScript consumers, where null silently coerces rather than breaking arithmetic as it does in Rust and Python.

---

Community reports have now driven four consecutive releases. Bugs and questions welcome in Issues or Q&A.