From ec86ad4aa839bce02cb93e1696de00c9736c0a30 Mon Sep 17 00:00:00 2001 From: Dotta Date: Fri, 30 Oct 2026 15:29:51 -0500 Subject: [PATCH] Document the native recovery rollback reader contract Co-Authored-By: Paperclip --- doc/execution-semantics.md | 12 ++++++++++-- .../2026-10-30-native-controller-checkpoints.md | 13 ++++++++++++- doc/testing-native-remote-continuity.md | 8 ++++++++ 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/doc/execution-semantics.md b/doc/execution-semantics.md index dc516274f72..e44d4da8e00 100644 --- a/doc/execution-semantics.md +++ b/doc/execution-semantics.md @@ -2660,6 +2660,13 @@ mixed evidence holds the continuation; it does not authorize fresh execution. The 32-candidate boundary and newer-progress barriers remain in force. Exhausted history and current-run progress cannot establish fresh-bootstrap proof. +A settled warm journal may contain an authenticated idle goal-read snapshot +after `run.terminal`. Recovery accepts only the supported PRP event v1/v2 +envelopes with the same complete attachment identity, a null goal and +`workingNow: false`. All commands must already be complete. Active goals, new +work, unknown versions and mixed bindings remain holds. This check adds no +streaming persistence or database work. + If admission finds a live retained controller owner, it preserves the unstarted business run and records the owner's actual deadline through the existing native resumption path. This does not consume a provider attempt or stop the retained @@ -2699,5 +2706,6 @@ admitted configuration digest and exact supervisor snapshot, locks the issue, coordinator and run in order, rejects live or unsettled ownership, and publishes only missing metadata. Repeating the same import is a no-op. Normal lifecycle checkpoints publish the metadata without a separate migration write. Disk-free -rollback requires a server that reads this envelope; earlier local-only readers -remain outside that rollback contract. +rollback requires a server that reads this envelope and the supported settled +warm journal, including its PRP v2 idle goal suffix. Earlier local-only readers +and readers lacking that suffix handling remain outside that rollback contract. diff --git a/doc/plans/2026-10-30-native-controller-checkpoints.md b/doc/plans/2026-10-30-native-controller-checkpoints.md index a1178fa340c..8c4780f08aa 100644 --- a/doc/plans/2026-10-30-native-controller-checkpoints.md +++ b/doc/plans/2026-10-30-native-controller-checkpoints.md @@ -1,6 +1,7 @@ # Native-controller recovery during webserver upgrades -Date: 2026-10-30. Status: implementation authorized; qualification pending. +Date: 2026-10-30. Status: implementation delivered; final qualification is tracked +in [PR #18343](https://github.com/paperclipai/paperclip/pull/18343). Source inspected: `0c70cedce9a803bdc201324528abb35e423e7cd0` in the current task worktree. ## Goal and finish line @@ -358,6 +359,16 @@ volume dependencies and concurrent-server behavior are qualified. Sources checke ## Current state and next action +The observations below retain earlier qualification attempts and their limits. +The PR's Verification section is the current acceptance record. The final native +runtime candidate is `eaef0d56552c087aaa4fa68a8655282ffbd12667`; documentation-only +updates do not change those runtime bytes. Its CI and fresh 5/5 review passed. +The corrected source-process test has completed active adoption and a fresh +retained follow-up. Distinct compatible rollback, installed-application and live +Daytona gates remain under verification as of 2026-10-30 20:28 UTC. Preserve failed +attempts when adding later passes. The rollback floor must include the idle-goal +reader fix; an envelope-only reader is insufficient. + Implementation is underway on `codex/native-controller-disk-independent-recovery`. The related Cloud policy work merged as paperclip-cloud PR #1048; it retains compatibility checks and drain fallback and does not implement this component. diff --git a/doc/testing-native-remote-continuity.md b/doc/testing-native-remote-continuity.md index b34b87ce9fa..5a5a0ea9f7c 100644 --- a/doc/testing-native-remote-continuity.md +++ b/doc/testing-native-remote-continuity.md @@ -308,6 +308,14 @@ The general everyday suite retains its 125-second default. These intervals are fault tests, not permitted HTTP deployment downtime. Both fixtures retain the workspace and remote sandbox; they do not prove whole-webserver disk loss. +The rollback reader must support both the recovery envelope and the settled PRP +v2 idle goal suffix. Record its actual source commit and installed tree hash. +An older reader rejecting that journal is an unsupported rollback, not a pass. +A backported compatibility build is a development fixture until it is released; +do not describe it as a previously published version. Distinct source-controller +tests, compiled native-module tests, installed CLI startup and the full Product +E2E journey provide different evidence and must retain those scope labels. + ## Database cost qualification `scripts/benchmark-native-controller-recovery.ts` compares a pinned source