refactor: rename daily maintenance workflow (#50)

## Summary

- Rename the misleading retention job subsystem to daily maintenance.
- Keep durable activation-metric and orphan-upload cleanup coordination.
- Preserve existing rows with a guarded in-place database migration.
- Correct runtime contracts, documentation, and dead-code configuration.

## Architecture

The webhooks Worker continues to run a durable two-phase daily workflow.
The public code vocabulary and physical table now describe the actual
work: activation metrics followed by orphan-upload cleanup. Committed
artifacts remain outside this maintenance workflow and persist until
project or account deletion.

## Decisions

| Decision | Choice | Reason |
|---|---|---|
| Lifecycle coordination | Keep durable database jobs | Leases, retries,
cursors, and crash recovery require persisted state |
| Schema cutover | Rename the table in place | Preserves queued jobs and
operational history |
| Active work | Refuse migration while a lease is active | Prevents
changing workflow state beneath a running owner |
| Artifact retention | Exclude committed output expiry | Outputs persist
until explicit project or account deletion |

## Validation

- [x] Skills build
- [x] Typecheck
- [x] Lint
- [x] Production build
- [x] Architecture check
- [x] Dead-code check
- [x] Production migration dry-run

Author: iamjr15

apps/agent-worker/README.md

@@ -153,7 +153,8 @@ admission events carry the planned logical model, while stream-attempt/completio
 the resolved logical model. A failure before any stream attempt keeps planned attribution instead;
 provider-local transport IDs remain structured-log context. R2-backed artifact
 persistence also atomically claims the user's durable first-artifact timestamp before emitting the
-`first_generated_artifact` activation signal, so output retention cannot make it fire twice.
+`first_generated_artifact` activation signal, so later project or account cleanup cannot make it
+fire twice.
 Terminal database status updates are persisted or durably queued in AgentRun's
 SQLite storage; alarms retry transient database failures with bounded exponential delay
 until the database accepts the update. A terminal Postgres status is deliberately held

apps/webhooks-worker/README.md

@@ -22,8 +22,8 @@ fields, and verifies only exact `v1,<base64>` signature tokens (including provid
 sets). Legacy payload versions and field aliases are rejected at ingress.
 Signed `/internal/webhooks/replay` commands also claim a durable envelope identity before changing
 Workflow state, so the same authenticated maintenance request cannot restart or resume twice.
-`OpsMaintenanceWorkflow` runs analytics watchdogs, daily
-retention metrics, generated-output retention, BYOK maintenance inventory,
+`OpsMaintenanceWorkflow` runs analytics watchdogs, daily activation metrics,
+abandoned-upload cleanup, BYOK maintenance inventory,
 and Clerk-driven GDPR deletion lifecycle jobs from Worker cron/webhook triggers. Account deletion
 jobs call the agent Worker through a Service Binding and clear quota state through a direct
 cross-Worker Durable Object binding before removing R2 and Postgres rows. These destructive
@@ -73,8 +73,8 @@ Analytics Engine SQL reads are timeout- and byte-bounded before schema narrowing
 Polar cleanup calls have a 30-second request deadline, a 1 MiB response-stream
 ceiling, and one 100-order page per durable account-deletion action.
 
-Daily activation and generated-output cleanup are one restart-safe state machine in
-`v2_retention_jobs`. The daily trigger registers one UTC-day row; the five-minute reconciler leases
+Daily activation and orphan-upload cleanup are one restart-safe state machine in
+`v2_daily_maintenance_jobs`. The daily trigger registers one UTC-day row; the five-minute reconciler leases
 queued or expired rows and recreates every live reserved continuation for the active Worker release.
 An errored or terminated deterministic instance is restarted, a failed initial creation returns to
 database backoff, and a continuation reserved before its parent exits remains discoverable even if
@@ -88,8 +88,8 @@ and compare-and-swaps the exact lease, phase, and both persisted cursors. A gene
 four pages. Initial and continuation payloads are distinct and bind the UTC day, continuation,
 release UUID, and lease UUID into a deterministic identity below Cloudflare's 100-character limit.
 The chain therefore has no total activation-row cap, while conservative step retries keep each
-generation comfortably inside its two-hour database lease. Cleanup cannot begin until the terminal
-activation page atomically changes the durable phase. Since Analytics Engine is append-only and a
+generation comfortably inside its two-hour database lease. Orphan-upload cleanup cannot begin until
+the terminal activation page atomically changes the durable phase. Since Analytics Engine is append-only and a
 Workflow step may replay, cohort SQL must use `count(DISTINCT blob6)` for those event identities.
 BYOK maintenance dispatches
 every five minutes and claims only ten fingerprints per database step under
@@ -109,28 +109,15 @@ project run tombstones use 25-run pages, and thread jobs complete each run's Dur
 prefix before advancing. The Worker keeps Cloudflare's explicit 10,000-subrequest ceiling;
 continuation boundaries, rather than a total-row cap, bound each execution.
 
-Expired generated outputs are scanned through the expiry/id index in 500-row keyset pages.
-Before the first output cursor advances, cleanup drains only upload intents whose terminal run,
-explicit awaited-artifact quiescence timestamp, and `cleanup_not_before` remote-side-effect grace
-deadline are all at or before the day's fixed cutoff. Each intent page revalidates the exact
-retention lease, deletes its deterministic R2 keys, and removes the matching intent identities
-transactionally while retaining the existing `cleanup` phase. Unquiesced or grace-fenced intents
-remain indexed for recovery. Generated outputs use the same terminal-run requirement in both page
-selection and exact row deletion, so an active run can renew an idempotently replayed output before
-issuing a download capability without racing retention. A database trigger makes terminal run state
-immutable, preserving that maintenance proof across the object-first deletion gap.
-Each page deletes its objects from the `R2_OUTPUTS` binding before conditionally deleting
-the exact matching Postgres rows and advancing the cursor in one database transaction. The R2
-attempt first compare-and-swaps the exact current phase and cursor; the transactional row deletion
-repeats that exact guard, so an earlier cached step cannot regress or destroy work after progress
-moves. R2 deletion is idempotent, so a failed database step safely retries the same page. A
-generation handles at most two pages and hands the fenced lease to another continuation. There is
-no total cleanup-row cap, and the day is terminal only after an empty cleanup page is observed.
-The `cheatcode-outputs` bucket also has a 60-day `expired-output-failsafe` lifecycle rule. It is
-deliberately longer than the application-owned 30-day expiry: the Workflow remains responsible for
-coordinated R2/Postgres deletion, while the native rule bounds storage leakage during a prolonged
-maintenance outage. Every protected backend release verifies the complete lifecycle rule set against
-`infra/cloudflare/production-r2-contract.json` before writers close and again before the gateway opens.
+Orphan-upload cleanup scans only upload intents whose terminal run, explicit awaited-artifact
+quiescence timestamp, and `cleanup_not_before` remote-side-effect grace deadline are all at or before
+the day's fixed cutoff. Each intent page revalidates the exact daily-maintenance lease, deletes its
+deterministic R2 keys, and removes the matching intent identities transactionally while retaining
+the `orphan-upload-cleanup` phase. Unquiesced or grace-fenced intents remain indexed for recovery.
+The external object deletion is idempotent, and the exact row identities are deleted in the same
+transaction that completes the maintenance job only after an empty page is observed. Committed
+generated outputs are outside this state machine and persist until project or account deletion;
+only their signed download capabilities are short lived.
 
 Clerk deletion is a durable Postgres soft-delete, not a sleeping Workflow. After the
 30-day grace deadline, the five-minute reconciler discovers at most 25 new generations

…bhooks-worker/src/retention-admission.ts …orker/src/daily-maintenance-admission.tsapps/webhooks-worker/src/retention-admission.ts renamed to apps/webhooks-worker/src/daily-maintenance-admission.ts apps/webhooks-worker/src/retention-admission.ts renamed to apps/webhooks-worker/src/daily-maintenance-admission.ts

@@ -1,39 +1,40 @@
 import {
-  claimReadyRetentionJobs,
+  claimReadyDailyMaintenanceJobs,
   createDb,
+  type DailyMaintenanceJobLease,
   type Database,
-  deferRetentionJob,
-  listLiveRetentionJobLeases,
-  purgeCompletedRetentionJobs,
-  type RetentionJobLease,
-  registerDailyRetentionJob,
+  deferDailyMaintenanceJob,
+  listLiveDailyMaintenanceJobLeases,
+  purgeCompletedDailyMaintenanceJobs,
+  registerDailyMaintenanceJob,
 } from "@cheatcode/db";
 import { createLogger, emitErrorEvent, safeErrorTelemetry } from "@cheatcode/observability";
 import { z } from "zod";
-import { assertReleaseOpen } from "./release-gate";
 import {
-  activeRetentionReleaseVersion,
-  createRetentionInstance,
+  activeDailyMaintenanceReleaseVersion,
+  createDailyMaintenanceInstance,
+  type DailyMaintenanceEnv,
   previousUtcDay,
-  type RetentionMaintenanceEnv,
-} from "./retention-maintenance";
+} from "./daily-maintenance-workflow";
+import { assertReleaseOpen } from "./release-gate";
 import type { DeterministicWorkflowResult } from "./workflow-instance";
 
-const RETENTION_RECONCILIATION_LIMIT = 25;
-const RETENTION_CREATION_CONCURRENCY = 5;
-const RETENTION_TOMBSTONE_MS = 32 * 24 * 60 * 60 * 1000;
-const CREATION_ERROR_CODE = "retention_instance_creation_failed";
-const ORPHANED_COMPLETION_ERROR_CODE = "retention_instance_completed_without_job_completion";
+const MAINTENANCE_RECONCILIATION_LIMIT = 25;
+const MAINTENANCE_CREATION_CONCURRENCY = 5;
+const MAINTENANCE_TOMBSTONE_MS = 32 * 24 * 60 * 60 * 1000;
+const CREATION_ERROR_CODE = "daily_maintenance_instance_creation_failed";
+const ORPHANED_COMPLETION_ERROR_CODE =
+  "daily_maintenance_instance_completed_without_job_completion";
 const ScheduledTimeSchema = z.number().int().nonnegative().max(8_640_000_000_000_000);
 
 type ReconciliationSource = "claimed" | "live";
 
 interface ReconciliationCandidate {
-  lease: RetentionJobLease;
+  lease: DailyMaintenanceJobLease;
   source: ReconciliationSource;
 }
 
-export interface RetentionReconciliationSummary {
+export interface DailyMaintenanceReconciliationSummary {
   claimed: number;
   created: number;
   deferred: number;
@@ -44,24 +45,24 @@ export interface RetentionReconciliationSummary {
 }
 
 /** Register a daily job, then use the same recovery path as the five-minute reconciler. */
-export async function enqueueDailyRetentionMetrics(
-  env: RetentionMaintenanceEnv,
+export async function enqueueDailyMaintenance(
+  env: DailyMaintenanceEnv,
   scheduledTimeInput: number,
-): Promise<RetentionReconciliationSummary> {
+): Promise<DailyMaintenanceReconciliationSummary> {
   assertReleaseOpen(env);
   const scheduledAt = new Date(ScheduledTimeSchema.parse(scheduledTimeInput));
   await withDatabase(env, (db) =>
-    registerDailyRetentionJob(db, { day: previousUtcDay(scheduledAt), scheduledAt }),
+    registerDailyMaintenanceJob(db, { day: previousUtcDay(scheduledAt), scheduledAt }),
   );
-  return reconcileDailyRetentionWorkflows(env);
+  return reconcileDailyMaintenanceWorkflows(env);
 }
 
 /** Recreate live reserved generations and lease every due/expired day in bounded batches. */
-export async function reconcileDailyRetentionWorkflows(
-  env: RetentionMaintenanceEnv,
-): Promise<RetentionReconciliationSummary> {
+export async function reconcileDailyMaintenanceWorkflows(
+  env: DailyMaintenanceEnv,
+): Promise<DailyMaintenanceReconciliationSummary> {
   assertReleaseOpen(env);
-  const releaseVersionId = activeRetentionReleaseVersion(env);
+  const releaseVersionId = activeDailyMaintenanceReleaseVersion(env);
   const now = new Date();
   const state = await loadReconciliationState(env, now, releaseVersionId);
   const eligibleLive = state.live.filter((lease) => lease.releaseVersionId === releaseVersionId);
@@ -79,22 +80,26 @@ export async function reconcileDailyRetentionWorkflows(
 }
 
 async function loadReconciliationState(
-  env: RetentionMaintenanceEnv,
+  env: DailyMaintenanceEnv,
   now: Date,
   releaseVersionId: string,
-): Promise<{ claimed: RetentionJobLease[]; live: RetentionJobLease[]; purged: number }> {
+): Promise<{
+  claimed: DailyMaintenanceJobLease[];
+  live: DailyMaintenanceJobLease[];
+  purged: number;
+}> {
   return withDatabase(env, async (db) => {
-    const purged = await purgeCompletedRetentionJobs(
+    const purged = await purgeCompletedDailyMaintenanceJobs(
       db,
-      new Date(now.getTime() - RETENTION_TOMBSTONE_MS),
+      new Date(now.getTime() - MAINTENANCE_TOMBSTONE_MS),
     );
-    const live = await listLiveRetentionJobLeases(db, {
-      limit: RETENTION_RECONCILIATION_LIMIT,
+    const live = await listLiveDailyMaintenanceJobLeases(db, {
+      limit: MAINTENANCE_RECONCILIATION_LIMIT,
       now,
     });
-    const claimed = await claimReadyRetentionJobs(db, {
+    const claimed = await claimReadyDailyMaintenanceJobs(db, {
       leaseToken: crypto.randomUUID(),
-      limit: RETENTION_RECONCILIATION_LIMIT,
+      limit: MAINTENANCE_RECONCILIATION_LIMIT,
       now,
       releaseVersionId,
     });
@@ -103,30 +108,30 @@ async function loadReconciliationState(
 }
 
 async function createReconciledInstances(
-  env: RetentionMaintenanceEnv,
+  env: DailyMaintenanceEnv,
   candidates: ReconciliationCandidate[],
-): Promise<Omit<RetentionReconciliationSummary, "claimed" | "purged" | "staleRelease">> {
+): Promise<Omit<DailyMaintenanceReconciliationSummary, "claimed" | "purged" | "staleRelease">> {
   const summary = { created: 0, deferred: 0, restarted: 0, reused: 0 };
-  for (let offset = 0; offset < candidates.length; offset += RETENTION_CREATION_CONCURRENCY) {
-    const batch = candidates.slice(offset, offset + RETENTION_CREATION_CONCURRENCY);
+  for (let offset = 0; offset < candidates.length; offset += MAINTENANCE_CREATION_CONCURRENCY) {
+    const batch = candidates.slice(offset, offset + MAINTENANCE_CREATION_CONCURRENCY);
     const settled = await Promise.allSettled(
-      batch.map(({ lease }) => createRetentionInstance(env, lease)),
+      batch.map(({ lease }) => createDailyMaintenanceInstance(env, lease)),
     );
     await accountForReconciliationBatch(env, batch, settled, summary);
   }
   return summary;
 }
 
 async function accountForReconciliationBatch(
-  env: RetentionMaintenanceEnv,
+  env: DailyMaintenanceEnv,
   candidates: ReconciliationCandidate[],
   settled: PromiseSettledResult<DeterministicWorkflowResult>[],
   summary: { created: number; deferred: number; restarted: number; reused: number },
 ): Promise<void> {
   for (const [index, result] of settled.entries()) {
     const candidate = candidates[index];
     if (!candidate) {
-      throw new Error("Retention reconciliation lost a lease identity");
+      throw new Error("Daily maintenance reconciliation lost a lease identity");
     }
     if (result.status === "rejected") {
       await accountForCreationFailure(env, candidate, result.reason, summary);
@@ -137,7 +142,7 @@ async function accountForReconciliationBatch(
 }
 
 async function accountForCreationFailure(
-  env: RetentionMaintenanceEnv,
+  env: DailyMaintenanceEnv,
   candidate: ReconciliationCandidate,
   error: unknown,
   summary: { deferred: number },
@@ -146,7 +151,7 @@ async function accountForCreationFailure(
     const deferred = await tryDeferLease(env, candidate.lease, CREATION_ERROR_CODE);
     summary.deferred += deferred ? 1 : 0;
   }
-  createLogger().error("retention_instance_reconciliation_failed", {
+  createLogger().error("daily_maintenance_instance_reconciliation_failed", {
     continuation: candidate.lease.continuation,
     day: candidate.lease.day,
     source: candidate.source,
@@ -155,13 +160,13 @@ async function accountForCreationFailure(
   emitErrorEvent(env, {
     errorCategory: "workflow",
     errorCode: CREATION_ERROR_CODE,
-    route: "retention-admission",
+    route: "daily-maintenance-admission",
     workerName: "webhooks",
   });
 }
 
 async function accountForCreationResult(
-  env: RetentionMaintenanceEnv,
+  env: DailyMaintenanceEnv,
   candidate: ReconciliationCandidate,
   result: DeterministicWorkflowResult,
   summary: { created: number; deferred: number; restarted: number; reused: number },
@@ -176,17 +181,17 @@ async function accountForCreationResult(
 }
 
 async function tryDeferLease(
-  env: RetentionMaintenanceEnv,
-  lease: RetentionJobLease,
+  env: DailyMaintenanceEnv,
+  lease: DailyMaintenanceJobLease,
   errorCode: string,
 ): Promise<boolean> {
   try {
     const deferred = await withDatabase(env, (db) =>
-      deferRetentionJob(db, { ...lease, errorCode }),
+      deferDailyMaintenanceJob(db, { ...lease, errorCode }),
     );
     return deferred !== null;
   } catch (error) {
-    createLogger().error("retention_reconciliation_defer_failed", {
+    createLogger().error("daily_maintenance_reconciliation_defer_failed", {
       continuation: lease.continuation,
       day: lease.day,
       errorCode,
@@ -197,7 +202,7 @@ async function tryDeferLease(
 }
 
 async function withDatabase<T>(
-  env: RetentionMaintenanceEnv,
+  env: DailyMaintenanceEnv,
   operation: (db: Database) => Promise<T>,
 ): Promise<T> {
   const { db, close } = createDb(env.HYPERDRIVE, {