DRAFT: ProjectData storage safety firebreak

[simple-agent-manager]

• Preflight completed before code changes

Classification

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

External References

Official documentation consulted before implementation:

• Cloudflare Durable Object limits: https://developers.cloudflare.com/durable-objects/platform/limits/
• Cloudflare SQLite storage API (databaseSize): https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/
• Cloudflare Durable Object alarms: https://developers.cloudflare.com/durable-objects/api/alarms/
• Cloudflare Durable Object testing examples: https://developers.cloudflare.com/durable-objects/examples/testing-with-durable-objects/
• Cloudflare/workerd SQLite source for databaseSize: https://github.com/cloudflare/workerd/blob/main/src/workerd/api/sql.c%2B%2B

Codebase Impact Analysis

Changed apps/api/src/durable-objects/project-data/* for measurement/alarm/purge/metadata cap, apps/api/src/services/project-data* for storage-full classification and admin service calls, apps/api/src/routes/admin.ts plus schemas for superadmin diagnostics, apps/api/src/db/* for additive D1 telemetry, and apps/api/wrangler.toml/docs/reference files for config visibility.

Documentation & Specs

Updated .env.example, apps/www/src/content/docs/docs/reference/configuration.md, .claude/skills/api-reference/SKILL.md, .claude/skills/env-reference/SKILL.md, and task evidence in tasks/active/2026-08-21-projectdata-storage-safety-firebreak.md.

Constitution & Risk Check

Checked Principle XI/no hardcoded values: limits, thresholds, intervals, and purge bounds are environment-backed defaults. Security-sensitive recovery endpoints use existing auth/approval/superadmin middleware and the purge deletes only bounded low-value event logs.

Summary

Adds the narrow ProjectData storage-safety firebreak requested from current main:

• direct per-object ctx.storage.sql.databaseSize measurement from ProjectData Durable Objects;
• D1 telemetry table plus superadmin diagnostics/force-measure/emergency-purge endpoints;
• isolated ProjectData alarm measurement/rescheduling;
• explicit SQLITE_FULL / storage-full classification as non-transient, surfaced as PROJECT_DATA_STORAGE_FULL;
• bounded superadmin recovery that deletes only oldest activity_events and acp_session_events rows;
• write-path cap for oversized tool_metadata, preserving valid JSON and useful identity/status fields.

This does not implement session sharding and does not modify, supersede, close, merge, or otherwise disturb PR #1873 (DO NOT MERGE: ProjectData DO sharding infrastructure).

Local validation

• pnpm --filter @simple-agent-manager/api typecheck
• pnpm --filter @simple-agent-manager/api lint
• pnpm --filter @simple-agent-manager/api test -- tests/unit/durable-objects/project-data-messages.test.ts tests/unit/services/durable-object-retry.test.ts
• pnpm vitest run --config vitest.workers.config.ts tests/workers/project-data-storage-safety.test.ts --reporter verbose
• pnpm vitest run --config vitest.workers.config.ts tests/workers/project-data-service.test.ts
• pnpm tsx scripts/quality/ast-checks.ts --file apps/api/src/durable-objects/project-data/storage-safety.ts --rule sql-injection
• git diff --check main...HEAD

Miniflare/workerd experiment evidence

Recorded in tasks/active/2026-08-21-projectdata-storage-safety-firebreak.md:

• databaseSize increases on inserts and drops after deletes in SQLite-backed Durable Object runtime;
• exact SQLITE_FULL could not be locally forced because PRAGMA page_count is rejected and setMaxPageCountForTest is not exposed to JS Worker tests;
• a caught SqlStorage write-limit error still allows reads and deletes afterward;
• ProjectData alarm writes D1 telemetry and reschedules;
• emergency purge deletes only bounded event-log rows and preserves chat messages.

Deployment/staging

No staging deploy or staging mutation has been performed. Keep this PR draft until the parent grants the single staging slot.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/implement-narrow-projectdata-storage-f3f5s3 (2bb4b5b) with main (35e74d8)}

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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