OpenProgram Docs

Session Index Consistency Task Brief and Ledger#

Contract#

  • Approved design: docs/reference/design/runtime/session/index-consistency.html.
  • Base commit: e831d0f0.
  • Production files: openprogram/store/session/session_store.py, openprogram/store/session/session_node_writer.py.
  • Public tests: metadata-only updates preserve updated_at and ordering; append advances meta/index together; list rows are snapshots; an update during an older disk write remains dirty and reaches the next flush; concurrent update/list/flush leaves parseable, current JSON.
  • Concurrency: registry dict, dirty state, and timer share one state lock; physical writes are ordered separately; no registry file I/O while holding the state lock.
  • Compatibility: index schema, list filters/order, caller-supplied creation timestamps, and atomic file replacement stay unchanged.
  • Exclusions: DAG node concurrency, mark_merged transaction redesign, project locations, Windows, credential stores, orphan files, auth work, and unrelated audit findings.

Full gate manifest#

pytest -q tests/unit/test_session_index_consistency.py tests/unit/test_session_cache_lru.py tests/unit/test_session_branch_consistency.py tests/unit/test_archive_agent.py tests/unit/test_memory_written_marker.py tests/unit/test_list_agents.py
ruff check openprogram/store/session/session_store.py openprogram/store/session/session_node_writer.py tests/unit/test_session_index_consistency.py
python -m tools.docs_site.build
python -m tools.docs_site.checklinks
git diff --check
git status --short

Ledger#

Evidence Result
Base e831d0f0
Design 0a66a3cc (docs(session): define index consistency contract)
RED tests/unit/test_session_index_consistency.py: 3 failed; meta timestamp overwritten, returned row mutated registry, and an in-flight old save cleared newer dirty state
GREEN Final contract coverage: 9 passed, including set-head, non-head node append, side-branch append, deferred and direct writes
Affected verification 107 passed in independent quality review; scoped Ruff passed; git diff --check passed
Specification review PASS after 09480e0f; set-head and non-head node findings repaired
Quality review PASS at c50b5180; write-failure retry, 6-writer concurrency, deadlock, reload and final JSON probes passed
Full gate 107 passed; Ruff passed; docs 459 pages; 0 broken links; git diff --check passed
Final implementation 9fef648c, 09480e0f, c50b5180
Last updated · 2026-08-13
PreviousSend Queue Reliability Implementation PlanNextSessionStore Lock Scope Task Brief and Ledger