# Persistent workspace policy — Phase 1 (capture on eviction)

**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](https://github.com/0xCAB0/fouria/issues/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

| Piece                   | Location                            | Behaviour                                                                                        |
| ----------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| Handle record + catalog | `src/workspace-snapshot.ts`         | `workspace/snapshot.json` in `BACKUP_BUCKET`; versioned, image-pinned, parsed defensively        |
| Capture                 | `captureWorkspaceSnapshot()`        | never throws; `captured` / `unsupported` / `failed` / `skipped`                                  |
| Eviction hook           | `TenantSandbox.onActivityExpired()` | runs after the idle verdict, before the archive/stop branch, only when `WORKSPACE_SNAPSHOT=true` |
| Legacy capability       | `TenantSandbox.snapshotWorkspace()` | `ctx.container.snapshotContainer({ name: 'workspace' })`                                         |
| 1.0 capability          | `SandboxV1.snapshotWorkspace()`     | same, on a `durable_object` container                                                            |
| Telemetry               | `workspace-snapshot`                | `durationMs`, `bytes`, `trigger=evict`, outcome, classified detail                               |

### Handle shape

```json
{
  "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`.
