Skip to content

feat(storage): add read-only thread store doctor#949

Closed
luoye520ww wants to merge 3 commits into
KunAgent:developfrom
luoye520ww:codex/thread-store-doctor
Closed

feat(storage): add read-only thread store doctor#949
luoye520ww wants to merge 3 commits into
KunAgent:developfrom
luoye520ww:codex/thread-store-doctor

Conversation

@luoye520ww

Copy link
Copy Markdown
Collaborator

Problem\n\nThe thread store has no read-only health report that can distinguish missing, malformed, truncated, or mismatched persisted artifacts before a repair operation is attempted.\n\n## Root cause\n\nMetadata, event JSONL, the SQLite index, and attachment references were validated only by their individual consumers. There was no bounded, side-effect-free scanner that reported their combined state.\n\n## Scope\n\nThis PR adds the contract and scanner only. Repair, backup, downgrade handling, and UI are intentionally separate follow-up work.\n\n## Changes\n\n- Add a versioned thread-store diagnostic contract.\n- Scan thread metadata, event JSONL, the SQLite index, and attachment references independently.\n- Open SQLite read-only and report path/index mismatches without writing.\n- Detect incomplete final JSONL records separately from interior corruption.\n- Bound artifact reads to 16 MiB and JSONL records to 100,000, with a post-read byte check for concurrent growth.\n- Cap per-thread issues at 64 and keep diagnostic messages safe to render.\n\n## Safety\n\n- The scanner performs no writes, migrations, repairs, deletes, or renames.\n- SQLite is opened with

eadonly: true and ileMustExist: true.\n- Damaged artifacts are reported rather than rewritten.\n- Paths and raw file contents are not included in the public diagnostic contract.\n\n## Typecheck\n\n ext\nnpm.cmd run typecheck\nnpm.cmd --prefix kun run typecheck\n\n\nBoth passed.\n\n## Tests\n\n ext\nnpm.cmd --prefix kun test -- tests/thread-store-diagnostics.test.ts tests/thread-store-doctor.test.ts\nnpm.cmd run lint\nnpm.cmd run build\ngit diff --check upstream/develop...HEAD\n\n\nResults: 2 files, 9 tests passed; lint, build, and diff checks passed.\n\n## Actual validation\n\nThe tests use real temporary directories, JSONL files, a real read-only �etter-sqlite3 database, and attachment metadata/content checks. They cover healthy stores, truncated tails, malformed metadata, interior malformed records, SQLite index verification, attachment mismatches, contract bounds, and read-only behavior.\n\n## Non-goals\n\n- Automatic repair or backup.\n- Schema downgrade handling.\n- Renderer/UI integration.\n\n## Issue\n\nPart of the thread-store integrity work.

@XingYu-Zhong

Copy link
Copy Markdown
Collaborator

Thank you for the read-only doctor proposal. I am closing this conflicting branch in favor of #981.

The replacement was rebuilt on current develop after addressing merge-blocking correctness issues: all directory/file/record/byte dimensions are bounded; JSONL is scanned without line-array amplification; SQLite is inspected and write-probed only through a rollback-only private buffer; active WAL fails closed; unexpected tables/inbound foreign keys, schema defaults, constraints, triggers, generated/hidden columns, index semantics, case-distinct IDs, and same-timestamp usage writes are verified without unbounded candidate scans; attachments are content-hash checked; incomplete scans cannot be hidden by aggregate severity; and every inspected file/non-file/unreadable artifact identity is rechecked before the report returns. Invalid/orphan index rows are reported even when no thread directory exists, while normal activity in unrelated runtime directories is not treated as thread-store instability.

Your original diagnostic direction is credited in the replacement PR.

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.

2 participants