fix(ai): lazily seed the usage DB on first AI use (fix #113 first-run e2e regression)

[eliotlim]

Problem

C1 (#113) eager-seeded the admin-only "AI usage" database at server startup, so every workspace — including a freshly-wiped one — gained an "AI usage" page. That broke the freshWorkspace → lands on Home invariant: the Playwright P1 gate failed on database-views.spec.ts + onboarding.spec.ts ([data-home-screen] never visible). It reached main because that gate isn't a required check — fixing forward.

Solution

Seed the usage DB lazily, on the first AI use, instead of at startup:

• startServer now calls AiUsageLog.load() — which only adopts an already-created DB recorded in settings (from a prior run), creating nothing.
• The DB is created on the first attribution write, via ensureSeeded() called from log().
• A workspace that never uses AI has no usage page → a fresh workspace stays empty → lands on Home. The managed write-gate + restricted read still apply once the DB exists; on restart a prior DB is re-adopted so the gates resolve immediately (no wait for the next AI call).

Key files: packages/server/src/ai/usage.ts (load/tryAdopt/ensureSeeded), server.ts (load not ensureSeeded), store.ts, packages/server/src/aiUsage.test.ts. New deps: none.

Before / After

No visual change (backend).

Behavior	Before	After
Fresh workspace (no AI used)	had an "AI usage" page → didn't land on Home (P1 gate red)	empty → lands on Home (P1 gate green)
Usage DB creation	at every server startup	on the first AI attribution write
Restart with prior usage	re-created/looked-up eagerly	re-adopts the existing DB (managed gates resolve immediately)

Test procedure

• pnpm verify → green.
• Web e2e (the regressed specs): pnpm --filter @book.dev/web exec playwright test e2e/database-views.spec.ts e2e/onboarding.spec.ts → pass; full test:e2e:core (P1 gate) on CI.
• aiUsage.test.ts: existing C1 acceptance retained (adjusted to log-first so the lazily-created DB exists) + a new "no AI use → no usage DB/page is created" test.

Operational notes

• No migration, no env, no deps. Behavior change: the admin-only restricted "AI usage" page now appears only after the first AI call (not in AI-less workspaces) — this is the intended cleaner behavior.
• Fix-forward to already-reviewed C1 (feat(ai): usage + cost attribution to an admin-only, tamper-locked database #113); changes when the usage DB is created, not the managed write-gate / restricted-read / attribution properties. Based on main f449e68 (post-feat(ai): usage + cost attribution to an admin-only, tamper-locked database #113).

---

Verify: green. Gates: fix-forward to reviewed C1 — no new security surface (same managed gates + attribution; isManagedPage correctly returns false when no usage DB exists yet).

🤖 Generated with Claude Code

https://claude.ai/code/session_01X78XTAemKrFw1uJpDpCEaG

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app.book.pub	Ready	Preview, Comment	Jul 6, 2026 2:14pm