The only shipped StateStore is in-memory, for examples and tests. Everyone embedding this library writes the same durable store, and docs/threat-model.md notes that a store returning a no-op transaction silently converts the atomicity guarantee into nothing.
Two reference implementations would fix that:
- File-backed: one JSON document per conversation, atomic replace via write-to-temp + rename.
- SQLite: single file, a real transaction around the state and transcript commit.
Requirements:
- Zero runtime dependencies (stdlib
sqlite3 and json are fine in Python; the TypeScript side may need to stay file-backed only).
- The transaction must actually be a transaction — a pre-commit failure has to leave state and transcript unchanged. Test that with an injected failure, not by inspection.
- Round-trip an
AffectState holding a non-empty occ_carry, a carried_thought with astral-plane characters, and an expectation — see python/tests/test_properties.py for the character set that has caught bugs before.
A well-scoped first contribution with a clear correctness bar.
The only shipped
StateStoreis in-memory, for examples and tests. Everyone embedding this library writes the same durable store, and docs/threat-model.md notes that a store returning a no-op transaction silently converts the atomicity guarantee into nothing.Two reference implementations would fix that:
Requirements:
sqlite3andjsonare fine in Python; the TypeScript side may need to stay file-backed only).AffectStateholding a non-emptyocc_carry, acarried_thoughtwith astral-plane characters, and anexpectation— seepython/tests/test_properties.pyfor the character set that has caught bugs before.A well-scoped first contribution with a clear correctness bar.