Phase 3: make ordinary workspace mutations record-bounded #37

New issue

Open

opened 2026-08-17 23:45:17 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-17 23:45:17 +00:00

(Migrated from github.com)

Parent

Follow-up to #24 after #35 Phase 2 durable reads/import staging.

Why this remains

Phase 2 removes corpus-sized heap requirements from direct document reads, snapshot paging, and staged imports. The ordinary mutation engine is still broader than that boundary:

run-operation calls workspace-for, which may restore the full workspace, then copy-workspace before one operation;
handle-transaction likewise makes a full copy-workspace candidate before applying a transaction.

On a large document corpus, that means a normal single-record mutation can still require a corpus-sized authoritative workspace plus another corpus-sized candidate. Therefore #24 must remain open even after #35 is complete.

Acceptance criteria

single document mutations do not restore/copy the complete document corpus;
bounded transactions do not duplicate unrelated corpus state;
graph/document referential-integrity validation uses direct Tek9 lookups/range reads rather than requiring all documents resident;
revision/journal/event ordering remains exactly atomic;
persistence failure still leaves no live replacement, revision advance, journal entry, event, or partial canonical records;
graph topology/metadata/sidecars and document mutations remain one atomic Tek9 transaction;
large-corpus tests prove retained SBCL heap for one bounded mutation does not grow with unrelated corpus size;
structural tests fail if run-operation or transaction handling regains a whole-workspace copy;
existing Phase 1/2 restart, failure-injection, graph integrity, and frontend gates remain green.

Design boundary

Prefer a record-level mutation context / overlay backed by Tek9 direct reads and the existing typed persistence plan. Do not weaken transactional semantics merely to avoid copy-workspace, and do not move LMDB internals into Quasar.

This issue is the remaining bounded-mutation phase required before #24 can honestly close.

## Parent Follow-up to #24 after #35 Phase 2 durable reads/import staging. ## Why this remains Phase 2 removes corpus-sized heap requirements from direct document reads, snapshot paging, and staged imports. The ordinary mutation engine is still broader than that boundary: - `run-operation` calls `workspace-for`, which may restore the full workspace, then `copy-workspace` before one operation; - `handle-transaction` likewise makes a full `copy-workspace` candidate before applying a transaction. On a large document corpus, that means a normal single-record mutation can still require a corpus-sized authoritative workspace plus another corpus-sized candidate. Therefore #24 must remain open even after #35 is complete. ## Acceptance criteria - single document mutations do not restore/copy the complete document corpus; - bounded transactions do not duplicate unrelated corpus state; - graph/document referential-integrity validation uses direct Tek9 lookups/range reads rather than requiring all documents resident; - revision/journal/event ordering remains exactly atomic; - persistence failure still leaves no live replacement, revision advance, journal entry, event, or partial canonical records; - graph topology/metadata/sidecars and document mutations remain one atomic Tek9 transaction; - large-corpus tests prove retained SBCL heap for one bounded mutation does not grow with unrelated corpus size; - structural tests fail if `run-operation` or transaction handling regains a whole-workspace copy; - existing Phase 1/2 restart, failure-injection, graph integrity, and frontend gates remain green. ## Design boundary Prefer a record-level mutation context / overlay backed by Tek9 direct reads and the existing typed persistence plan. Do not weaken transactional semantics merely to avoid `copy-workspace`, and do not move LMDB internals into Quasar. This issue is the remaining bounded-mutation phase required before #24 can honestly close.