Document the native recovery rollback reader contract

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
DottaandPaperclip committed 2026-10-30 15:29:51 -05:00
1 parent eaef0d5655
commit ec86ad4aa8
3 files changed
+30 -3

No files matched your search

+10 -2
View File
@@ -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.
@@ -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.
+8
View File
@@ -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