chore: add plan and phase reports for D1 + cron rollout

plans/reports/docs-manager-260415-1304-phase-06-docs.md

@@ -0,0 +1,132 @@
+# Phase 06 Documentation — Completion Report
+
+**Date:** 2026-04-15  
+**Status:** DONE  
+**Plan:** D1 + Cron Infra + JSDoc + Trading History (Phase 06)
+
+## Summary
+
+Executed Phase 06 of the D1+Cron infra plan — created comprehensive documentation for D1 + cron usage and updated all existing docs to reflect current implementation. All module authors now have clear guidance for adopting persistent storage and scheduled jobs without needing to read framework internals.
+
+## Files Created
+
+1. **`docs/using-d1.md`** (~320 LOC)
+   - When to choose D1 vs KV (decision matrix included)
+   - Module initialization pattern: `init({ db, sql, env })`
+   - Table naming convention: `{moduleName}_{table}`
+   - Writing migrations: `src/modules/<name>/migrations/NNNN_*.sql` with lexical sorting
+   - SQL API reference: `run()`, `all()`, `first()`, `prepare()`, `batch()`
+   - Migration execution: `npm run db:migrate` with `--local` and `--dry-run` flags
+   - Testing with `FakeD1` from `tests/fakes/fake-d1.js`
+   - First-time D1 setup: `wrangler d1 create` workflow
+   - Worked example: simple counter with migration + handler
+
+2. **`docs/using-cron.md`** (~300 LOC)
+   - Cron declaration: `crons: [{ schedule, name, handler }]` in module export
+   - Handler signature: `(event, { db, sql, env })` receives module context
+   - Cron expression syntax: 5-field standard with Cloudflare docs reference
+   - Critical: manual `wrangler.toml` registration required (`[triggers] crons`)
+   - Error isolation: one handler failing doesn't block others
+   - Execution limits: 15-minute wall-clock per task
+   - Local testing: `curl "http://localhost:8787/__scheduled?cron=<schedule>"`
+   - Multiple modules can share a schedule (fan-out)
+   - Worked example: trade retention cleanup cron
+   - Worked example: stats recalculation
+
+## Files Updated
+
+1. **`docs/adding-a-module.md`** (+95 LOC)
+   - New section: "Optional: D1 Storage" — init pattern, migrations, npm run db:migrate
+   - New section: "Optional: Scheduled Jobs" — crons array, wrangler.toml requirement
+   - Cross-links to `using-d1.md` and `using-cron.md`
+   - Updated testing section to mention `fake-d1.js`
+   - Referenced trading module as full example (D1 + crons)
+
+2. **`docs/architecture.md`** (+100 LOC)
+   - Module contract code block: added `sql` parameter and `crons` array
+   - Storage section: separate subsections for KVStore and SqlStore
+   - New scheduled event flow diagram (flow from Cloudflare cron to handler dispatch)
+   - Added `dispatchScheduled` and cron isolation details
+
+3. **`docs/codebase-summary.md`** (+30 LOC)
+   - Module table: added Storage + Crons columns
+   - Key data flows: added scheduled job flow diagram
+   - Deploy pipeline: noted `npm run db:migrate` step
+   - Test coverage: updated to mention D1 coverage + fake-d1.js
+
+4. **`docs/code-standards.md`** (+40 LOC)
+   - Module conventions: updated to show `sql` parameter and null-guards
+   - New section: "JSDoc & Type Definitions" — central location `src/types.js`, when to add, validation rules
+   - Noted ESLint (`eslint src`) runs alongside Biome
+
+5. **`CLAUDE.md`** (project root) (+15 LOC)
+   - Commands section: added `npm run db:migrate` with all flags
+   - Module contract: updated to show `sql`, `env`, and `crons`
+   - Cross-linked to `using-d1.md` and `using-cron.md`
+
+6. **`docs/deployment-guide.md`** (+80 LOC)
+   - Prerequisites: added D1 to "Cloudflare account with" checklist
+   - New section: "Cloudflare D1 Database" (optional but recommended) — `wrangler d1 create`, paste UUID, run migrations
+   - Renumbered sections (KV is now section 2, secrets is now section 3, local config is now section 4)
+   - New section in Deploy: "Cron Configuration" — explain wrangler.toml `[triggers] crons` requirement
+   - Updated first-time deploy flow: added D1 setup + migration steps
+
+7. **`README.md`** (+80 LOC)
+   - Why section: added D1 + crons to feature bullets
+   - Architecture snapshot tree: added `types.js`, D1 files (`cf-sql-store.js`, `create-sql-store.js`), cron files (`cron-dispatcher.js`, `validate-cron.js`), migrations example, fake-d1.js, migrate.js
+   - Local dev: added `npm run db:migrate` and noted `/__scheduled` endpoint
+   - Deploy section: added D1 setup and migration steps to first-time flow
+   - Further reading: added links to `using-d1.md` and `using-cron.md`, updated plan references
+
+8. **`plans/260415-1010-d1-cron-infra/phase-06-docs.md`**
+   - Status: Todo → Complete
+   - All todos: checked off
+
+9. **`plans/260415-1010-d1-cron-infra/plan.md`**
+   - Status: Draft → Complete
+   - Phase 06: Todo → Complete
+
+## Verification
+
+All doc references verified against shipped code:
+
+- ✓ `createSqlStore(moduleName, env)` returns `null` when `env.DB` not bound (checked `src/db/create-sql-store.js`)
+- ✓ `sql.run/all/first/prepare/batch` API matches `src/db/sql-store-interface.js` JSDoc
+- ✓ Table prefix pattern `{moduleName}_{table}` enforced by `createSqlStore`
+- ✓ Migration runner at `scripts/migrate.js` walks `src/modules/*/migrations/*.sql`, applies via `wrangler d1 execute`, tracks in `_migrations`
+- ✓ Cron handler signature `(event, { db, sql, env })` matches `src/modules/cron-dispatcher.js`
+- ✓ Trading module exports `crons` with schedule `"0 17 * * *"` (verified `src/modules/trading/index.js`)
+- ✓ `wrangler.toml` has `[triggers] crons = ["0 17 * * *"]` matching module declaration
+- ✓ `src/index.js` exports both `fetch` and `scheduled(event, env, ctx)` handlers
+- ✓ `src/types.js` defines all central typedefs (Env, Module, Command, Cron, ModuleContext, etc.)
+- ✓ `validateCron` enforces name regex and schedule format (verified `src/modules/validate-cron.js`)
+
+## Documentation Quality
+
+- **Tone consistency:** All new docs match existing style (clear, code-first, practical examples)
+- **Cross-linking:** New docs link to each other + existing docs; no orphaned pages
+- **Code examples:** All examples based on actual shipped code (trading module, fake-d1 tests, migration runner)
+- **Completeness:** Covers happy path (module author perspective) + guard clauses (null-safety, error handling)
+- **Searchability:** Docs well-organized by topic (when to use, how to implement, testing, examples, troubleshooting)
+
+## Deliverables Checklist
+
+- [x] `docs/using-d1.md` created
+- [x] `docs/using-cron.md` created
+- [x] `docs/adding-a-module.md` updated with cron + D1 sections
+- [x] `docs/architecture.md` updated with storage details + scheduled flow
+- [x] `docs/codebase-summary.md` updated (module table, flows, coverage)
+- [x] `docs/code-standards.md` updated (JSDoc section, module conventions)
+- [x] `docs/deployment-guide.md` updated (D1 setup, migration steps, cron registration)
+- [x] `CLAUDE.md` updated (module contract, commands)
+- [x] `README.md` updated (feature bullets, architecture tree, deploy flow, further reading)
+- [x] Plan phase 06 marked complete
+- [x] Overall plan marked complete
+
+All 9 deliverable targets from phase-06-docs.md completed.
+
+## Concerns
+
+None. All deliverables shipped to spec. Documentation is current, accurate, and immediately actionable for future module authors. No stale references, broken links, or incomplete examples.
+
+**Status:** DONE