Merge pull request #22 from ProofOfTechOrg/dev

release: promote unattended rollout runbook and Phase 1 ledger

Author: gcharang

README.md

@@ -78,7 +78,7 @@ The Release workflow publishes the promoted versions with npm provenance. It rej
 
 Do not merge `master` back into `dev`. `NPM_TOKEN` needs publish access to the `@understudy` scope.
 
-Backend deployment remains a separate Wrangler operation. Keep `UNATTENDED_ENABLED_TENANTS=[]` until the canary extension passes the production acceptance suite.
+Backend deployment remains a separate Wrangler operation. Keep `UNATTENDED_ENABLED_TENANTS=[]` until the canary extension passes the production acceptance suite. Follow the [unattended production rollout runbook](docs/unattended-production-rollout.md) for deployment order, evidence gates, and rollback.
 
 ## Preserve attended proof history
 

apps/backend/README.md

@@ -162,19 +162,22 @@ The Miniflare test suite needs permission to bind a loopback port.
 
 ## Deploy safely
 
-Deploy the dual-protocol backend with unattended creation disabled:
+Use the [unattended production rollout runbook](../../docs/unattended-production-rollout.md) as the canonical deployment, evidence, and rollback procedure. Deploy the dual-protocol backend with unattended creation disabled:
 
 ```bash
 pnpm --filter @understudy/backend exec wrangler deploy
 ```
 
-After one canary extension reports protocol 2, enable only its tenant. Complete the production Chromium acceptance suite and 24-hour soak before broad enablement.
+After deployment, record the exact migration-`v2`, flags-off version as the rollback baseline. After one canary extension reports protocol 2, enable only its tenant. Complete the production Chromium acceptance suite and 24-hour soak before broad enablement.
 
 A rollback must:
 
-1. Disable new unattended leases
-2. Drain or terminalize active leases and granted commands
-3. Roll back application code
-4. Retain the additive Durable Object migrations
+1. Return the consumer to attended mode
+2. Roll back to the recorded migration-`v2`, flags-off version
+3. Confirm new unattended leases are disabled
+4. Delete and poll active leases while the durable sweeper retains unresolved cleanup
+5. Retain the additive Durable Object migrations and coordinator data
 
-Do not deploy protocol-1-only code while protocol-2 leases exist.
+Migration `v2` is additive and irreversible. Cloudflare blocks rollback across incompatible Durable Object class lifecycle changes, so the active migration-`v1` version cannot be assumed to remain a valid rollback target after `v2`. See [Cloudflare Worker rollback constraints](https://developers.cloudflare.com/workers/versions-and-deployments/rollbacks/).
+
+Do not remove migration `v2` or deploy protocol-1-only code while protocol-2 leases exist.

docs/technical-plan.md

@@ -214,18 +214,19 @@ Analytics Engine receives content-free events for authentication, allocation, li
 
 ## Rollout gates
 
-Production configuration starts with `UNATTENDED_ENABLED_TENANTS=[]`. Deploy the additive Durable Object migration and dual-protocol backend before enabling any tenant.
+Production configuration starts with `UNATTENDED_ENABLED_TENANTS=[]`. Deploy the additive Durable Object migration and dual-protocol backend before enabling any tenant. The [unattended production rollout runbook](unattended-production-rollout.md) is the canonical execution procedure and status ledger.
 
-Rollout order:
+The conceptual rollout order is:
 
-1. Build and load the production extension in a tenant-dedicated profile
-2. Enroll one canary device and confirm protocol 2
-3. Enable one tenant
-4. Complete the real-Chromium acceptance suite
-5. Run a 24-hour read-only soak
-6. Enable remaining tenants after zero unexpected unknown writes and correct expiry behavior
+1. Make the governed Metamind consumer compatible and recoverable while it remains attended
+2. Establish a migration-`v2`, flags-off Understudy rollback baseline
+3. Accept one canary device and complete the real-Chromium suite
+4. Run a 24-hour read-only soak
+5. Prove one unattended Metamind workflow with correlated audit and durable cleanup
+6. Ramp allowlisted traffic through `1 → 5 → all`
+7. Complete the final 24-hour operational soak
 
-Rollback disables new leases first, drains or terminalizes active leases and granted commands, then rolls back application code. Never remove the additive migration or deploy protocol-1-only code while protocol-2 leases exist.
+Rollback returns Metamind to attended mode, returns Understudy to the recorded migration-`v2`, flags-off version, confirms new leases are disabled, and drains active leases. Never remove the additive migration, target the earlier migration-`v1` version, or deploy protocol-1-only code while protocol-2 leases exist.
 
 ## Historical attended proof