F FourIA staging 2026.10.29 GitHub ↗

Persistent workspace policy — Phase 1 (capture on eviction)

On this page

Date: 2026-10-31 Status: Implemented, flag-gated off (runtime prerequisite below) Parent: docs/plans/persistent-workspace-phase0.md (measurement)


1. Scope

Phase 1 adds Tier 1 capture: immediately before an idle container is evicted, take a platform filesystem snapshot and commit its handle. Boot still uses the archive, so this cannot reduce recoverability — it only starts producing the artifact that Phase 2 will boot from.

Explicitly out of scope:

  • Booting from the snapshot (Phase 2). The recovery ladder is unchanged.
  • Retention/GC beyond overwriting the single head handle.
  • Any change to the archive cadence, lease, or restore path.
  • An encryption envelope for the snapshot (platform-managed storage; the F4E1 archive remains the compliance artifact — see the Phase 0 design, decision 01).

2. Runtime prerequisite (hard)

Cloudflare only supports snapshots for a container application that uses scheduling_policy: "durable_object". The tenant container (containers[].class_name: "Sandbox" in wrangler.jsonc) uses the default policy: the legacy SDK calls container.start(startConfig) with no image, which is exactly what the default policy provides and the DO policy forbids.

A policy flip is not available. Verified against Cloudflare’s docs (2026-10-31):

  • The scheduling policy is immutable: “To use a different policy, create a new Container application.” The replacement also needs a new Durable Object class and namespace; the old and new applications cannot attach to the same namespace, and the existing entry must stay untouched so traffic can be routed back.
  • The legacy Sandbox class extends the Containers Container class, which does not support the durable_object policy. The replacement class must drive ctx.container directly and rebuild the helpers the tenant runtime relies on (exec/processes, port readiness, HTTP/WS proxying, sleep timeout).
  • instance_type: "basic" has no equivalent: instance accepts lite or standard-1..4, and custom instance types require at least 1 vCPU, so basic’s 1/4 vCPU cannot be expressed. A replacement must choose lite (smaller) or standard-1 (4 GiB) — a per-tenant cost/behaviour decision.
  • Named images must be a Dockerfile or a digest-pinned Cloudflare-registry reference; max_instances, placement constraints and application-wide image rollouts are unsupported. Deploys stop rolling the image; application code stops and starts each container.

Consequences:

  • There is no snapshot-only migration. Tier 1 needs the Sandbox 1.0 workload adapter (exec/processes, files, HTTP/WS, readiness/recovery) plus the .sqsh → DirectoryBackup bridge — the S2–S4 slices of #380.
  • SandboxV1 already provides the new class, the durable_object app, DirectoryBackup + F4E1 and snapshotWorkspace(); it has no fetch(), exec/files/process surface and no routing.
  • On today’s tenant runtime ctx.container.snapshotContainer() is unavailable. Capture is classified unsupported, logged, and eviction continues to the archive/stop path. WORKSPACE_SNAPSHOT stays false in every environment.

3. What ships

PieceLocationBehaviour
Handle record + catalogsrc/workspace-snapshot.tsworkspace/snapshot.json in BACKUP_BUCKET; versioned, image-pinned, parsed defensively
CapturecaptureWorkspaceSnapshot()never throws; captured / unsupported / failed / skipped
Eviction hookTenantSandbox.onActivityExpired()runs after the idle verdict, before the archive/stop branch, only when WORKSPACE_SNAPSHOT=true
Legacy capabilityTenantSandbox.snapshotWorkspace()ctx.container.snapshotContainer({ name: 'workspace' })
1.0 capabilitySandboxV1.snapshotWorkspace()same, on a durable_object container
Telemetryworkspace-snapshotdurationMs, bytes, trigger=evict, outcome, classified detail

Handle shape

{
  "format": 1,
  "id": "<platform snapshot id>",
  "size": 123456789,
  "image": "<image the container ran>",
  "committedAt": 1761900000000,
  "trigger": "evict"
}
  • One live handle. Snapshots cannot be deleted through the API, so the only retention lever is creation rate; the head is overwritten and unreferenced handles expire after the platform’s 30-day TTL.
  • Image-pinned. isWorkspaceSnapshotUsable(record, currentImage) is false for an empty or mismatched image, so Phase 2 falls back to the archive rather than restoring an incompatible filesystem.

4. Rollout

Tier 1 is only reachable through the v1 cutover, so the rollout follows #380’s slices rather than a policy flip:

  1. S2 — v1 workload adapter + serving foundation (convertToV1, HTTP, readiness, recovery) for an explicitly opted-in, non-production instance.
  2. S3 — WebSocket + forwarded-header parity.
  3. S4 — v1 owner operations: freeze, backup/checkpoint, restore-settled latch, and the .sqsh → DirectoryBackup conversion (existing tenants keep their recovery points).
  4. Enable WORKSPACE_SNAPSHOT=true on that instance and verify workspace-snapshot rows: outcome=captured, bytes > 0, zero unsupported for a full idle cycle.
  5. Only then widen to staging tenants, dev, and production.

None of this is a prerequisite for merging Phase 1: the capture code is inert while the flag is off, and the flag is off everywhere.

Gate (from the Phase 0 plan)

Every eviction produces a handle: captured for 100% of idle evictions over a week, with unsupported/failed at zero. Only then does Phase 2 (boot from the snapshot when the image matches) start.

5. Failure behaviour

  • Flag off → no call, no row.
  • No BACKUP_BUCKET → skipped (no-bucket).
  • Runtime rejects the API → unsupported, warning, eviction continues.
  • Capture or catalog write fails → failed, warning, eviction continues.
  • The archive/stop path is unchanged in every case, so Phase 1 has no fail-closed obligation: the recovery point is still the archive.

5b. Snapshot and archive must restore the same tree

The two tiers are only interchangeable if they hold the same content. The archive is a complete image today: SNAPSHOT_EXCLUDES (.npm, *.log, *.tmp, .cache, workspace/*node_modules*) is gated behind BACKUP_ARCHIVE_EXCLUDES, which is off by default precisely so an archive restore cannot diverge from a snapshot restore.

Phase 2 must not weaken that. If an instance opts into the excludes, an archive-restored tenant is missing those paths while a snapshot-restored one has them, so the fallback in the boot ladder is not byte-equivalent and a tenant that depends on the excluded paths would behave differently after a snapshot miss. Before booting from snapshots anywhere the excludes are enabled, either keep the archive complete for that instance or make the fallback regenerate the excluded paths explicitly.

6. Tests

  • src/workspace-snapshot.test.ts — flag parsing, record parsing, catalog round-trip, image validity, error classification, every capture outcome.
  • src/sandbox-do.test.ts — capture before eviction, flag off, unsupported still enqueues the archive-then-stop job, failure does not block eviction.
  • src/sandbox-v1.test.ts — snapshotWorkspace() on a durable_object container.
  • src/metrics.test.ts — workspace-snapshot row layout.
  • Corpus: test/business-rules/cost-tracking.txt.