Skip to content

feat(history): persist temporal perspectives and idempotent receipts - #48

Open
DivyamTalwar wants to merge 7 commits into
codex/jitmind-j07-reviewed-20260928from
codex/jitmind-j09-reviewed-20260928
Open

DivyamTalwar wants to merge 7 commits into
codex/jitmind-j07-reviewed-20260928from
codex/jitmind-j09-reviewed-20260928

Conversation

@DivyamTalwar

Copy link
Copy Markdown
Owner

Follow-up and scope

Implements J-09, the follow-up tracked in #40. Stacked on #47 for review order. The history API uses JITMIND's scope/temporal contracts; it does not require another product or make optional conversation checkpoints mandatory.

Why this follow-up was necessary

An in-memory seven-query temporal oracle does not prove that earlier knowledge perspectives survive restart. Mutable current facts and an ID-only projection outbox cannot reconstruct the original validity intervals after retroactive corrections.

Implementation

  • Add SQLiteTemporalHistory with immutable complete perspectives, namespace-scoped revisions, compare-and-swap publication, monotonic recorded times and validated interval models.
  • Add DurableTemporalOracle and frozen idempotent publication receipts. Exact same-key retries reconcile an earlier commit after response loss; different bodies conflict.
  • Bound full-history and paginated acquisition before loading payloads; reject schema/corruption/overflow explicitly instead of truncating evidence into a false answer.
  • Recheck authoritative scope at write/read/response boundaries and keep accepted-commit uncertainty distinct from a rollback.
  • Provide consistent backup/restore, runtime diagnostics and explicit historical retention semantics.

Review and tests

The independent review found no blocking defect within its bounded SQLite/scope/temporal checks. The supervisor then assembled the final dependency owners and reran:

PYTHONPATH=$PWD python -m pytest -q -p no:cacheprovider
# 755 passed, 3 expected optional-provider warnings
python -m compileall -q jitmind tests
python -m ruff check --no-cache --isolated --select E9,F <owned Python files>
python -m pip check
git diff --check
# all passed

Candidate 3dadfee445d82d45816a21c68fe6d741a75159ad, parent 75574aef663b25f48619fcf2179e59492ddbe49b.
Includes 37 new real SQLite cases: all seven temporal queries after reopen/spawned-process restart, concurrent CAS/idempotency, invalid scopes/models, bounded acquisition, commit-error reconciliation, response loss, corruption protection and backup during publication. Counts include inherited tests and are not independent performance samples.

Important boundaries

History uses an explicitly separate database because the current fact store rejects foreign schema objects. There is no atomic transaction across those independent stores. Generic text updates do not automatically create structured temporal perspectives: the host must use the documented structured writer. Legacy historical perspectives are not invented during migration.

DELETE/FULL local SQLite is the supported mode here. TTL affects eligibility, not physical erasure of retained history/backups. Revocation after an accepted COMMIT cannot undo it. Full-history reads fail visibly above configured bounds. Other platforms, hardware power loss, live model quality and donor superiority remain outside these tests.

See docs/durable-temporal-history.md for APIs, retention, migration and backup/restore. Merge prerequisites first, then retarget and rerun CI. No automatic merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant