Skip to content

fix: Coalesce engine maintenance behind owned workers - #808

Draft
buildingjoshbetter wants to merge 4 commits into
fix/canonical-source-fts-publish-753from
fix/maintenance-engine-routing-publish-753
Draft

buildingjoshbetter wants to merge 4 commits into
fix/canonical-source-fts-publish-753from
fix/maintenance-engine-routing-publish-753

Conversation

@buildingjoshbetter

@buildingjoshbetter buildingjoshbetter commented Oct 8, 2026 •

Copy link
Copy Markdown
Owner

Scope

Engine scheduling checkpoint for #753, stacked on #807 with #806 included by a normal prerequisite merge. This activates the existing eight-layer planner; it preserves each builder algorithm and the threshold of 25 committed appends.

Changes

  • Route startup, committed mutations and safe API boundaries through durable source/dependency checkpoints. Initial input attempts once; 24 appends stay below the threshold and the 25th qualifies across instances and reopen. Corrections use their separate eligibility rules.
  • Coalesce notifications per canonical database into one active owner and one pending generation. Pending work carries no engine, connection or source text. A local owner's release services an existing pending notification, including after the last engine closes.
  • Workers own and close their file connections. Foreground close neither joins nor cancels a shared worker. Cancellation/start failure/fork teardown retain exact ownership; active work releases its descriptor only when its own cleanup finishes.
  • Keep foreground probes bounded to eight layer checkpoints, source counters and small dependency metadata. They acquire the engine lock nonblocking and perform no model load, model-lock wait, corpus scan or native-framework import.
  • Bind cached package/extension evidence to versions and actual model/table identity. A late worker cannot overwrite newer capability evidence. Busy model probes cannot erase an unavailable-extension baseline.
  • Explicit consolidate forces the same eight layers plus the existing preference result. Busy returns nine explicit BUSY entries without a queued forced retry. File calls use a dedicated connection; borrowed and in-memory calls preserve their original connection and transaction ownership.
  • Restore summary/cluster capability flags only after successful manual publication. Expose bounded per-layer outcomes, freshness, coverage and categorical errors in stats.

Validation

  • 33 new stdlib/SQLite tests cover cross-instance thresholds, repeated opens, corrections, capability evidence, borrowed transactions, coalescing, lifecycle and event-controlled ownership. Independent focused verification passed 125 methods across scheduler/admission/foreground/streaming suites, plus the legacy style-lock assertion.
  • The initial full suite had 13 failures. A real foreground lock-order defect was reproduced independently and corrected in fix: Prevent maintenance from rejecting foreground writes #806 before this scheduler was retested. Failed-run evidence is retained.
  • Two explicit rebuild fixtures now disable automatic consolidation before seeding so the test owns its requested rebuild. Their operation/output assertions remain unchanged. Production scheduling remains enabled.
  • Legacy tests now assert durable planner outcomes and worker ownership instead of removed scheduling internals. The new scheduler loader explicitly decodes UTF-8; decoding the actual engine source as CP1252 reproduces the Windows portability risk.
  • Integration-based author candidate with actual sqlite-vec: 2,689 passed, 22 skipped, 3 deselected; 1,209 subtests passed. Log SHA256: 568f990ae81981f96843b0be056d173fe8dbac7873d23b3db973f6f50c2ae6d3.
  • Isolated publication branch, including fix: Track exact source edits and hidden replacements #807 and fix: Prevent maintenance from rejecting foreground writes #806 and the UTF-8 loader correction, with actual sqlite-vec: 2,626 passed, 22 skipped, 3 deselected; 1,249 subtests passed. Log SHA256: c9395a6a479d429db534cb9c99bc23b046a3d4a6057a5a22c7ce8db091dc294d.
  • Configured Ruff, Python 3.10 syntax, whitespace, new-content privacy and commit-identity checks passed. Hosted checks are pending.

Fixture isolation follow-up

A later integration run exposed one failure in the 24/25 threshold test. The raw log did not record bootstrap state, so its specific interloping worker is unknown. A controlled in-memory reproduction executes the actual engine, coordinator worker and dependency resolver: an unrelated worker can discover the fixture's process-wide replacement of the vector module and hold its fake model lock. This defers initial clustering, leaving no attempt baseline. Scheduling that unfinished initial work at 24 inserts is correct production behavior.

The follow-up changes tests only. The adapter fixture now supplies its own maintenance module registry instead of publishing its fake vector module process-wide. Both threshold scenarios explicitly require all eight successful empty bootstrap baselines before counting appends. The original no-request-at-24 and request-at-25 assertions remain intact. A separate control intentionally defers bootstrap and verifies that recovery still runs only the missing cluster attempt at 24.

The old fixture fails two intended assertions with zero setup errors; the corrected three new regressions pass. All original issue 498 method bodies also passed in the in-memory harness. Production bytes are unchanged. Exact publication head 4431787bfe18ece1f3609ef4d827917976b8095b passed 2,629 tests, 22 skips, 3 deselections and 1,249 subtests, with actual sqlite-vec. Log SHA256: 10ecb7513ff4be7e8ad8268b181982ec8d68edd0107c1319c90af62d9c689603. Range privacy, Python 3.10 grammar, Ruff and whitespace checks passed. The preceding production head passed all 34 hosted checks; the new test-only head awaits its own hosted matrix. No production-fix or native-performance claim is made for this follow-up.

Limits

Cross-process busy work needs a later API boundary; there is no idle polling or automatic external-process release signal. Deferred/failed attempts do not create self-retry loops. Daemon workers may be interrupted by process exit and still require durable abandoned-attempt recovery.

Automatic in-memory maintenance stays pending; manual maintenance uses the original handle. Borrowed publication is pending until the caller commits. Ingestion database replacement and getter freshness are separate checkpoints. Unverified vector/contact coverage remains visible. Existing entity-less preference extraction behavior is unchanged and remains #746.

This does not establish native latency, throughput, whole-process memory, MPS or thermal improvement. The separate numerical/performance release gates remain held. Models, rerankers, precision, dimensions and retrieval caps are unchanged. Only generated synthetic data was used; no personal memories, transcripts or credentials. No issue closure, main merge or release.

This branch has not been deployed

No deployments
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