DO NOT MERGE: ProjectData DO sharding infrastructure

[simple-agent-manager]

Summary

• Add Phase 1 ProjectData same-class DO sharding metadata and runtime infrastructure.
• Route session/message reads internally through session_shards and fan out all-history search across registered shards.
• Add alarm-driven bounded migration of stopped sessions, PRAGMA-based storage estimation, env-configurable thresholds, and docs.
• Add worker/unit coverage for migration correctness, read routing, fan-out search, storage estimation, alarm behavior, active/sleeping exclusion, and cascade-safety.
• Stabilize two existing route test harnesses by moving expensive dynamic imports out of per-test beforeEach hooks; this removes full-suite hook timeouts without changing product behavior.

Agent Preflight

• Preflight completed before code changes

Classifications

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

Reviewed SAM idea 01M0F88EEQPGR32E08R1EXC2VR, the project library research doc /engineering/research/do-10gb-storage-ceiling-research.md, and PoC coverage in apps/api/tests/workers/do-sharding-poc.test.ts before implementing Phase 1.

Codebase Impact Analysis

Primary impact is in apps/api/src/durable-objects/project-data/ for migrations, routing, storage estimation, and alarm-driven migration. Supporting changes touch apps/api/src/env.ts, apps/api/tests/, apps/www/src/content/docs/docs/reference/configuration.md, .claude/skills/env-reference/SKILL.md, CLAUDE.md, and tasks/backlog/.

Documentation & Specs

Updated apps/api/.env.example, apps/www/src/content/docs/docs/reference/configuration.md, .claude/skills/env-reference/SKILL.md, and CLAUDE.md to document the new ProjectData sharding controls and behavior.

Constitution & Risk Check

Checked Principle XI no hardcoded values: thresholds are exposed through env vars with DEFAULT_* constants. Scope stays internal to ProjectData, with no API route, MCP tool, UI, wrangler binding, or new DO class changes.

Validation

• pnpm test
• pnpm lint
• pnpm typecheck
• pnpm format:check
• pnpm build
• pnpm quality:file-sizes
• pnpm quality:do-migration-safety
• pnpm quality:migration-safety

Constraints

• DO NOT MERGE.
• Draft PR by request.
• Staging deployment intentionally skipped by explicit task instruction.
• Phase 1 only: no API route, MCP tool, UI, new DO class, or wrangler binding changes.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/do-sharding-implementation (cb45364) with main (a453839)}

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud