---
created: 2026-09-11
status: complete
requirements:
  - REQ-PLATFORM-STARTUP-LIFECYCLE-001
system_design:
  - ../../specs/platform/system-design/startup-lifecycle.md
legacy_specs: []
---

# Large database startup implementation plan

## Root cause

`provideRepositories` performs the upgrade backup and migrations before
`startGatewayAndServe` binds the bootstrap listener. The reported 42.5-second
backup consumes almost all of the 45-second listener budget.

## Scope and approach

Move shared bootstrap ownership before initialization. Add typed phase reporting
and cancellation-aware backup execution. Preserve version gates, retention,
health identity, binding semantics, and background recovery ordering.

## Work orders

- [x] [01: Startup lifecycle](task-01-lifecycle.md)
- [x] [02: Startup measurements and documentation](task-02-evidence.md)
- [x] [03: Plugin session-event mirror startup batching](task-03-plugin-mirror-batching.md)

## Verification

Backend commands run from `apps/backend`; script and diff commands run from root.

- `rtk go test -race ./internal/backendapp ./internal/persistence ./internal/launcher ./internal/common/config ./internal/db`
- `rtk go test ./internal/task/repository/sqlite -run 'Test(StartupMigrationCosts|StartupMigrationCostsPopulated|NewWithDBContextStopsActiveMigration|BackfillPromptSeqStopsOnCanceledContext)' -v`
- `rtk proxy python3 scripts/lint-spec-files.py --all`
- `rtk proxy node --test scripts/validate-public-docs.test.mjs`
- `rtk proxy node scripts/validate-public-docs.mjs`
- `rtk git diff --check`

## End-to-end evidence

Use real HTTP listeners with controlled initialization and short launcher health
deadlines. Cover success, failure, route isolation, cancellation, and bind failure.
No browser UI changes or live database access are needed.

## Risks

Legacy constructors include non-context SQL. Shutdown must not race cleanup with
those constructors. Retry retention can discard the original snapshot; no reuse
or retention changes are authorized in this package.

## Results

Implemented early bootstrap ownership, typed startup phases, cancellation-aware
SQLite backup and task migration execution, worker-only restore quiescing,
launcher phase diagnostics, populated startup measurements, and public
troubleshooting documentation.

Validation passed:

- `env -u KANDEV_INTERNAL_CONFIG_FILE -u KANDEV_INTERNAL_CONFIG_HOME_FILE -u KANDEV_INTERNAL_AGENTCTL_STARTUP_CONFIG -u KANDEV_HEALTH_TIMEOUT_MS go test -race ./internal/backendapp ./internal/persistence ./internal/launcher ./internal/common/config ./internal/db -count=1`
- `go test -race ./internal/startup -count=1`
- `go test -race ./internal/persistence/storeconformance -count=1`
- `go test ./internal/task/repository/sqlite -run 'Test(StartupMigrationCosts|StartupMigrationCostsPopulated|NewWithDBContextStopsActiveMigration|BackfillPromptSeqStopsOnCanceledContext)$' -v -count=1`
- `make -C apps/backend build`
- `make -C apps/backend lint` (0 issues)
- `go run ./cmd/sqlguard ./internal`
- `python3 scripts/lint-spec-files.py --all`
- `node --test scripts/validate-public-docs.test.mjs` (62 passed)
- `node scripts/validate-public-docs.mjs` (46 published pages)
- `git diff --check`

The populated isolated SQLite evidence is recorded in
[task-02-evidence](task-02-evidence.md). It covers a 929,792-byte database,
6,000 messages, a 2,252,800-byte `VACUUM INTO` snapshot, 285.06 ms replay,
and separate recurring backfill timings on Linux amd64 with Go 1.26.0. The
measurement remains synthetic and does not predict production startup time.

Deferred risks remain outside this package: backup retry retention and the
backup-registry redesign are unchanged. Constructors for non-task stores still
have bounded admission barriers rather than a new shared context API; an
already admitted statement can finish according to its driver's cancellation
behavior before the next store is rejected.

[Task 03](task-03-plugin-mirror-batching.md) closed a related gap found on a
2026-09-17 upgrade: the plugins provider's one-time conversation-journal mirror
sync did not conform to AC-001.4/AC-001.6 (silent, ~4 minutes, non-cancellable
on a 669k-event journal). Batched mirrored-event commits by a fixed event count
across sessions (~40x per-event cost reduction) and threaded a cancellable
startup context through the boot sync path. See that work order for full
verification receipts.