fix(sqlite): repair fresh schema bootstrap

[yyhhyyyyyy]

Fixes fresh agent.db bootstrap on new DeepChat installs.

Previously, fresh startup could create new_sessions / deepchat_sessions from an empty recorded schema version, then stamp schema_versions to latest via the fresh fast-path. The database looked migrated but was missing latest columns such as new_sessions.is_draft, causing session creation to fail with table new_sessions has no column named is_draft.

Summary by CodeRabbit

• New Features
  • Improved first-launch SQLite schema bootstrap and startup schema diagnosis/repair for supported drift.
• Bug Fixes
  • Fresh session tables now use the latest schema SQL on clean installs.
  • Repair is scoped to fresh-install relevant tables, avoids repeated repair attempts, and surfaces warnings when only manual fixes remain.
• Documentation
  • Added a SQLite “fresh schema bootstrap” plan, specification, and task checklist.
• Tests
  • Updated/added coverage for fresh-install schema creation, startup diagnosis, and repair behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0d595a84-7264-4ed0-9f00-0d53eaeac926

📥 Commits

Reviewing files that changed from the base of the PR and between a6ebaa8 and 989248e.

📒 Files selected for processing (3)

• src/main/presenter/lifecyclePresenter/DatabaseInitializer.ts
• src/main/presenter/sqlitePresenter/index.ts
• test/main/presenter/sqlitePresenter.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• test/main/presenter/sqlitePresenter.test.ts
• src/main/presenter/lifecyclePresenter/DatabaseInitializer.ts

---

📝 Walkthrough

Walkthrough

Adds fresh-install SQLite schema metadata, switches session table creation to latest SQL, scopes diagnosis and repair APIs to an optional startup catalog, and runs advisory startup diagnosis with one guarded repair attempt in DatabaseInitializer.

Changes

SQLite Fresh Schema Bootstrap

Layer / File(s)	Summary
Schema metadata and startup catalog src/main/presenter/sqlitePresenter/schemaTypes.ts, src/main/presenter/sqlitePresenter/schemaCatalogMetadata.ts, src/main/presenter/sqlitePresenter/schemaCatalog.ts	Adds createdOnFreshInstall to SchemaTableSpec, introduces metadata for legacy tables excluded from fresh-install creation, and exports getStartupSchemaCatalog().
Session tables use latest-schema SQL src/main/presenter/sqlitePresenter/tables/newSessions.ts, src/main/presenter/sqlitePresenter/tables/deepchatSessions.ts	NewSessionsTable drops its version-specific createTable() override, and DeepChatSessionsTable.createTable() now uses latest-schema SQL instead of recorded-version SQL.
Catalog-scoped repair and diagnosis APIs src/main/presenter/sqlitePresenter/index.ts	repairSQLiteDatabaseFile accepts an optional catalog option, diagnoseSchema accepts an optional catalog, and migration setup now uses getMigrationTables() plus getLatestSchemaVersion().
DatabaseInitializer startup diagnosis and guarded repair src/main/presenter/lifecyclePresenter/DatabaseInitializer.ts	Adds startup diagnosis with catalog-scoped repair retry, scopes the constructor-time repair path to the startup catalog, and adds helpers for issue formatting and manual schema warnings.
Bootstrap and catalog behavior tests test/main/presenter/lifecyclePresenter/DatabaseInitializer.test.ts, test/main/presenter/sqlitePresenter.test.ts, test/main/presenter/sqlitePresenter/schemaCatalogMetadata.test.ts, test/main/presenter/sqlitePresenter/schemaRepair.test.ts	Refactors initializer tests with shared fixtures, updates SQLitePresenter integration tests for startup catalog diagnosis, adds metadata exclusion tests, and updates repair fixtures with createdOnFreshInstall.
Design spec, plan, and task checklist docs/issues/sqlite-fresh-schema-bootstrap/*	Adds the bootstrap spec, implementation plan, and task checklist documents.

Sequence Diagram(s)

sequenceDiagram
  participant DatabaseInitializer
  participant SQLitePresenter
  participant SchemaInspector
  participant DatabaseRepairService

  DatabaseInitializer->>SQLitePresenter: construct presenter
  DatabaseInitializer->>SQLitePresenter: diagnoseSchema(getStartupSchemaCatalog())
  SQLitePresenter->>SchemaInspector: inspect startup catalog
  SchemaInspector-->>SQLitePresenter: diagnosis
  SQLitePresenter-->>DatabaseInitializer: diagnosis result

  alt repairable issues and no prior repair
    DatabaseInitializer->>SQLitePresenter: close()
    DatabaseInitializer->>DatabaseRepairService: repair with startup catalog
    DatabaseInitializer->>DatabaseInitializer: retry initialization
  else manual issues or diagnosis failure
    DatabaseInitializer->>DatabaseInitializer: log warnings and continue
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• ThinkInAIXYZ/deepchat#1360: Both PRs modify the newSessions.ts and deepchatSessions.ts table-creation path.
• ThinkInAIXYZ/deepchat#1490: Both PRs touch deepchatSessions.ts schema creation and recovery behavior.
• ThinkInAIXYZ/deepchat#1669: Both PRs change schemaCatalog.ts and the SQLite schema bootstrapping path.

Suggested reviewers

• zerob13

Poem

🐇 I bounced through tables, bright and new,
With startup checks and repairs too.
Fresh schema paths now hop ճիշտ? no—clean and neat,
And old tables stay off the fresh-install seat.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: fixing SQLite fresh-schema bootstrap and repair behavior on new installs.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/sqlite-fresh-schema-bootstrap

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/main/presenter/lifecyclePresenter/DatabaseInitializer.ts`:
- Around line 66-75: The startup path in DatabaseInitializer should not claim
success when repairable schema issues still remain after a failed repair
attempt. Update the repair branch in DatabaseInitializer so that, when
repairAttempted is true and diagnosis.repairableIssues is still non-empty, it
does not log initialization success or return this.database; instead, continue
to fail startup or propagate the unresolved schema problem using the existing
diagnosis/formatSchemaIssues flow so the remaining missing table/column issues
are not masked.

In `@test/main/presenter/sqlitePresenter.test.ts`:
- Around line 159-163: The test is calling presenter.diagnoseSchema() without
the startup catalog and then filtering issues afterward, which can hide
regressions in startup-scoped diagnosis. Update the sqlitePresenter test to pass
getStartupSchemaCatalog!() directly into diagnoseSchema() and assert against
that scoped diagnosis result using the existing presenter.diagnoseSchema and
getStartupSchemaCatalog! symbols.
- Around line 202-206: The assertion in the sqlitePresenter bootstrap test is
too weak because it only checks that the recorded schema version is positive;
update the test to compare the stored value against the same latest schema
version source used by the production bootstrap logic. Use the existing schema
version helper or constant referenced by the presenter/bootstrap path, and
verify the single row returned from schema_versions matches that latest version
exactly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dc3c06e9-9dd8-47d1-b1a7-9c5965c84ae1

📥 Commits

Reviewing files that changed from the base of the PR and between 3d10913 and a6ebaa8.

📒 Files selected for processing (14)

• docs/issues/sqlite-fresh-schema-bootstrap/plan.md
• docs/issues/sqlite-fresh-schema-bootstrap/spec.md
• docs/issues/sqlite-fresh-schema-bootstrap/tasks.md
• src/main/presenter/lifecyclePresenter/DatabaseInitializer.ts
• src/main/presenter/sqlitePresenter/index.ts
• src/main/presenter/sqlitePresenter/schemaCatalog.ts
• src/main/presenter/sqlitePresenter/schemaCatalogMetadata.ts
• src/main/presenter/sqlitePresenter/schemaTypes.ts
• src/main/presenter/sqlitePresenter/tables/deepchatSessions.ts
• src/main/presenter/sqlitePresenter/tables/newSessions.ts
• test/main/presenter/lifecyclePresenter/DatabaseInitializer.test.ts
• test/main/presenter/sqlitePresenter.test.ts
• test/main/presenter/sqlitePresenter/schemaCatalogMetadata.test.ts
• test/main/presenter/sqlitePresenter/schemaRepair.test.ts

💤 Files with no reviewable changes (1)

• src/main/presenter/sqlitePresenter/tables/newSessions.ts

[nexoracontrol-ops]

_{Approved in CodeRabbit Change Stack}

[nexoracontrol-ops]

_{Approved in CodeRabbit Change Stack}