docs: propose Rainier × NoKV workspace continuity

[wchwawa]

TL;DR

Propose a high-level, post-v0 collaboration boundary for portable workspace continuity. Rainier and Postgres retain lifecycle authority; the runtime driver owns workspace export/install; NoKV remains an optional checkpoint and provenance provider evaluated shadow-first.

This PR is intentionally RFC-only. An exploratory local prototype was excluded after review against current main showed that the first implementation must integrate through Rainier's opaque driver and existing /workspace rules, rather than accept host filesystem paths.

Problem

Rainier already preserves /workspace across container crash and cold park on one runner. Its v0 design still accepts losing unpushed work when that runner VM is lost, while the v1 roadmap calls for object-storage checkpoints and cross-runner recovery.

Consequences

Without an explicit boundary, Rainier would need to assemble and qualify workspace identity, recovery, history, provenance, retention, and cleanup across Postgres, object storage, and runtime-specific volumes. Coupling that work directly to NoKV would instead introduce a second authority and a premature v0 dependency.

Example

A runner disappears with uncommitted code, generated files, and multi-repository work in /workspace. Rainier recreates those files on another runner, then lets the agent continue through its native resume mechanism. Process memory, PTY, sockets, and GPU state are explicitly outside this proposal.

Solution

• keep Postgres as Rainier's sole control-state authority;
• let the runtime driver safely export and install workspace data;
• place a replaceable checkpoint/history provider behind that boundary;
• prove local cross-runner continuity first;
• evaluate NoKV asynchronously in shadow mode before any opt-in restore.

Gain

NoKV can reduce the consistency machinery Rainier would otherwise build around versioned workspace history, retries, recovery, provenance, references, and garbage collection. The claim is not that any storage primitive is unique; the harder-to-replace value is the integrated agent-workspace lifecycle.

Tradeoffs

• NoKV adds metadata and object-storage operations beside Postgres;
• the Go integration surface and real driver seam still need design;
• checkpointing adds I/O, latency, and storage cost;
• NoKV HA and long-horizon recovery require further qualification;
• this belongs to an optional post-v0 path, not Rainier's current critical path.

Verification

• reviewed against main@c44d65322f832deb3c70e093957b9c3ebcb14769;
• git diff --check;
• go test -race -count=1 ./...;
• go vet ./...;
• go build ./....

No real cross-runner restore or production NoKV integration is claimed.

Decision requested

@jiashuoz, would you please review the direction and share your opinion, especially on:

1. the runtime-driver versus checkpoint-provider boundary;
2. keeping NoKV optional and shadow-first after v0;
3. whether the next contribution should be a small local export/install design and E2E before any NoKV adapter.

[wchwawa]

@jiashuoz, could you please review this high-level direction and share your opinion? In particular, I would value your guidance on the driver/provider boundary and whether a local cross-runner E2E should be the next contribution before any NoKV shadow adapter.

[jiashuoz]

Quick summary after comparing this RFC with the existing checkpointing plan and reviewing NoKV source at main@58ecc0f:

• NoKV has useful immutable-publication, operation-ID-bound retry, reference-tracking, and GC machinery. However, production recovery, HA, and GC behavior still need qualification.
• A NoKV snapshot is a leased MVCC read version of its path namespace and requires a sealed commit head; it is not a capture of a live runtime volume. A durable Rainier checkpoint would need to publish and seal the intended state, then retain the NoKV commit ID.
• NoKV deliberately does not preserve several filesystem properties Rainier may need: modes, symlinks, hardlinks, empty directories, xattrs/ACLs, sparse files, and special nodes. Rainier therefore still needs a driver-owned export/install format with an explicit filesystem-fidelity contract.
• The existing local-first plan remains the safer initial path: driver export/install plus shared round-trip tests, followed in rainier-cloud by a Postgres catalog and immutable archives/manifests in GCS.
• NoKV is best evaluated initially as a non-authoritative shadow sink consuming that same sealed export. Promotion should require cross-runner restore tests, changed/deleted-state coverage, archive-size and streaming limits, restore-latency targets, and a durable metadata-recovery story beyond the default local Holt store.

Overall: NoKV looks promising as an immutable checkpoint substrate, but it should not yet replace the provider-neutral checkpoint boundary or become a runtime dependency. The two approaches can be complementary if NoKV sits behind Rainier's export/install contract.