Skip to content

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

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

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

Conversation

@luoye520ww

Copy link
Copy Markdown
Collaborator

Problem

Thread persistence spans metadata JSONL, event JSONL, a rebuildable SQLite index, and attachment files. Before this PR there was no read-only scanner that could distinguish missing, invalid, truncated, or mismatched artifacts.

Root cause

The store's normal read paths intentionally tolerate damaged records, which is useful for serving a session but insufficient for data-integrity diagnostics and later repair tooling.

Scope

This stacked PR adds the read-only scanner on top of #897. It does not repair, rewrite, compact, or migrate any user data.

Changes

  • Scan safe thread directories and validate current or legacy metadata.
  • Classify JSONL artifacts as ok, missing, truncated, or invalid without exposing file contents.
  • Open SQLite read-only and verify indexed paths for each thread.
  • Resolve attachment references from persisted turns and detect missing content or scope mismatches.
  • Bound artifact reads, JSONL record counts, and diagnostic issues.
  • Export the scanner through the Kun services barrel.

Safety

  • All filesystem access is read-only; SQLite is opened with readonly and fileMustExist.
  • No absolute paths, raw log lines, attachment bytes, or secrets are returned in diagnostics.
  • Invalid metadata and missing attachment content fail closed for recoverable.
  • Existing JSONL and SQLite files are verified byte-for-byte unchanged in tests.

Dependency

Depends on #897 (feat(storage): define thread store doctor contract). After #897 merges, this branch should be rebased onto develop and the full test matrix rerun.

Typecheck

npm.cmd --prefix kun run typecheck
npm.cmd run typecheck

Both passed after building the local extension workspace packages.

Tests

npm.cmd --prefix kun test -- tests/thread-store-diagnostics.test.ts tests/thread-store-doctor.test.ts

Result: 2 files, 9 tests passed, including real temporary SQLite and attachment checks.

Actual validation

npm.cmd run lint, npm.cmd run build, and the Kun build all passed. Tests cover healthy JSONL, truncated final records, interior malformed records, invalid metadata, read-only behavior, SQLite path validation, and missing attachment content.

Review performed

  • Functional correctness
  • Concurrency/lifecycle and SQLite close handling
  • Data integrity and read-only guarantees
  • Secret/path exposure
  • Cross-platform path comparison
  • Performance bounds
  • Backward compatibility with legacy thread.json
  • Test quality and stacked PR scope

PR size

Production files: 2
Test files: 1
Production LOC: 414
Total diff: 574 lines

Follow-ups

Thread Store repair, backup, quota, and UI remain separate PRs.

@luoye520ww

Copy link
Copy Markdown
Collaborator Author

This work is consolidated into #942, which combines the Thread Store Doctor, bounded backups, and schema write guard with one tested scope. Closing the duplicate to keep review focused.

@luoye520ww luoye520ww closed this Jul 14, 2026
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