@runeditrun/rer 0.2.0 → 0.2.2

package/global/cli/uninstall.mjs

@@ -4,7 +4,8 @@
 // root. An npm global rer leaves other channels' installs alone.
 import { lstat, readlink, rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { launcherOwner, layout } from './layout.mjs';
+import { installRecord, launcherOwner, layout } from './layout.mjs';
+import { ownedPathLink } from './path-link.mjs';
 import { channelOf } from './status.mjs';
 
 // A folder `rer cli install` made: a versions/ directory and a `current` link into it.
@@ -26,6 +27,9 @@ export async function uninstall() {
   process.stdout.write(lines.join('\n') + '\n');
   return 0;
  }
+ for (const link of (await installRecord(paths))?.links ?? []) {
+  if (await ownedPathLink(link, paths.launcher)) { await rm(link); lines.push(`Removed ${link}.`); }
+ }
  if (launcher.state === 'ours') { await rm(paths.launcher); lines.push(`Removed ${paths.launcher}.`); }
  else if (launcher.state === 'foreign') lines.push(`Left ${paths.launcher} in place: rer cli install did not write it.`);
  if (await installRoot(root)) { await rm(root, { recursive: true, force: true }); lines.push(`Removed ${root}.`); }

package/global/launch/install-pinned.mjs

@@ -5,10 +5,14 @@
 import { spawn } from 'node:child_process';
 import { pinnedPackage } from '../checkout.mjs';
 import { packageName } from '../package-info.mjs';
+import { ensureProjectPnpm } from '../../cli/project-pnpm.mjs';
+import { RerError } from '../../cli/errors.mjs';
 import { LaunchFailure } from './failure.mjs';
 
 export async function installPinned(root, { env = process.env, output = text => process.stderr.write(text), children, signal } = {}) {
  signal?.throwIfAborted();
+ try { await ensureProjectPnpm(root, { env, signal, report: text => output(text + '\n') }); }
+ catch (error) { if (error instanceof RerError) throw new LaunchFailure(error.exitCode, error.message); throw error; }
  const child = spawn('pnpm', ['install', '--frozen-lockfile'], { cwd: root, env: { ...env, CI: 'true' }, stdio: ['ignore', 'pipe', 'pipe'] });
  children?.add(child);
  if (signal?.aborted) child.kill('SIGTERM');

package/global/main.mjs

@@ -1,13 +1,14 @@
 import { dispatcher, locate, pinnedPackage, unsupportedMessage } from './checkout.mjs';
 import { delegate } from './delegate.mjs';
 import { localDefaults } from './launch/local-defaults.mjs';
+import { handleBrokenPipes } from './output.mjs';
 import { packageName as pinnedName } from './package-info.mjs';
 
 const help = `Usage: rer VERB [FLAGS]
 
 Inside a project (the nearest OPERATIONS.json at or above this folder, or --cwd DIR),
 every verb runs that checkout's own pinned rer: the @runeditrun/rer version its package.json
-pins (installed first by rer install or rer dev), else its vendored scripts/rer.mjs.
+pins (installed first by rer install, rer setup or rer dev), else its vendored scripts/rer.mjs.
 
   rer dev              Launch a first-party checkout with no setup steps: installs dependencies,
                        sets up a local owner and a free port when needed, starts the app and prints
@@ -34,11 +35,16 @@ outbox, doctor, describe, check, release. Run rer VERB --help in a checkout for
 `;
 
 // The verbs that install an uninstalled pinned package before they run.
-const installsFirst = new Set(['install', 'check', 'describe']);
+const installsFirst = new Set(['install', 'setup', 'check', 'describe']);
 
 export async function main(argv) {
+ handleBrokenPipes();
  const [verb] = argv;
  if (verb === '--version' || verb === '-v') return (await import('./version.mjs')).versionCommand(argv);
+ if (verb === 'queue' && argv.length === 2 && argv[1] === '--help') {
+  process.stdout.write('Usage: rer queue NAME -- COMMAND [ARGS]\nRun COMMAND once this computer\'s job queue admits it.\n');
+  return 0;
+ }
  // Only the zero-setup launch sets this, for its own setup child; an explicit
  // verb never inherits it.
  delete process.env[localDefaults];
@@ -52,6 +58,27 @@ export async function main(argv) {
  const target = locate(argv);
  if (target.profile === 'unsupported') { process.stderr.write(unsupportedMessage(target.root, target.version) + '\n'); return 2; }
  const first = target.profile === 'first-party', mode = first ? dispatcher(target.root).mode : undefined;
+ if (first) {
+  // Carry the effective directories to older dispatchers that used account HOME.
+  const { serversDirectory } = await import('./registry.mjs');
+  const { jobsDirectory } = await import('../modules/job-queue/config.mjs');
+  process.env.RER_SERVERS_DIR = serversDirectory(process.env);
+  process.env.RER_JOBS_DIR = jobsDirectory(process.env);
+  const bootstrap = pinnedPackage(target.root)?.ready === false && installsFirst.has(verb);
+  if ((bootstrap || ['install', 'setup', 'dev', 'preview', 'build', 'verify'].includes(verb)) && !argv.includes('--help') && !argv.includes('--stop')) {
+   const { parse } = await import('../cli/parse.mjs');
+   // The door's launch marker belongs to launchDev, which consumes it before
+   // calling the checkout's public dispatcher. Validate the same public args
+   // here, before provisioning the checkout's package manager.
+   const publicArgs = verb === 'dev' ? target.args.filter(arg => arg !== '--door-start') : target.args;
+   try { parse(publicArgs, target.root); }
+   catch (error) { process.stderr.write(error.message + '\n'); return error.exitCode ?? 2; }
+   const { ensureProjectPnpm } = await import('../cli/project-pnpm.mjs');
+   const { RerError } = await import('../cli/errors.mjs');
+   try { await ensureProjectPnpm(target.root, { report: text => process.stderr.write(text + '\n') }); }
+   catch (error) { if (!(error instanceof RerError)) throw error; process.stderr.write(error.message + '\n'); return error.exitCode; }
+  }
+ }
  if (verb === 'queue') {
   const [, name, separator, command] = argv;
   if (!name || separator !== '--' || !command) { process.stderr.write('Usage: rer queue NAME -- COMMAND [ARGS]\n'); return 2; }
@@ -59,7 +86,7 @@ export async function main(argv) {
   return (await import('../onboarding/queued-entry.mjs')).queuedCommandLine(argv.slice(1));
  }
  // A checkout that pins its own rer package runs all of it, launching included.
- // Until node_modules holds the pinned version, install, check and describe
+ // Until node_modules holds the pinned version, install, setup, check and describe
  // install it with the frozen lockfile (then run the pinned verb, so a fresh
  // clone checks with the pinned bytes), the zero-setup launch installs it
  // first, and every other verb says to install.

package/global/output.mjs

@@ -0,0 +1,12 @@
+let installed = false;
+
+export function handleBrokenPipes() {
+ if (installed) return;
+ installed = true;
+ for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', error => {
+   if (error.code === 'EPIPE') return;
+   throw error;
+  });
+ }
+}

package/global/registry.mjs

@@ -1,11 +1,11 @@
 // Read-only view of the shared server registry that every pinned dispatcher
 // writes (RER_SERVERS_DIR, else the account's ~/.rer/servers).
 import { readFile } from 'node:fs/promises';
-import { userInfo } from 'node:os';
+import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { alive } from '../modules/job-queue/identity.mjs';
 
-export const serversDirectory = (env = process.env) => resolve(env.RER_SERVERS_DIR ?? join(userInfo().homedir, '.rer/servers'));
+export const serversDirectory = (env = process.env) => resolve(env.RER_SERVERS_DIR ?? join((env.HOME || homedir()), '.rer/servers'));
 
 export async function liveServers(env = process.env) {
  let state;

package/global/rer.mjs

@@ -2,6 +2,9 @@
 // The installed `rer` command. This file avoids newer syntax so that an old
 // Node still reaches the one-line minimum-version message.
 import { readFileSync } from 'node:fs';
+import { handleBrokenPipes } from './output.mjs';
+
+handleBrokenPipes();
 
 function manifest() {
  // Packed: the package's own package.json. From a Base checkout: the template.

package/modules/container/deploy-input.mjs

@@ -1,17 +1,13 @@
-import { open, readFile } from 'node:fs/promises';
-import { constants } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { refuseLocalModels } from '../deploy-kit/local-only.mjs';
-import { LOCAL_ONLY_KEYS, localOnlyBinding } from '../deploy-kit/owner.mjs';
+import { localOnlyBinding } from '../deploy-kit/owner.mjs';
+import { readDeployEnvFile } from '../deploy-kit/env-file.mjs';
 export async function deployInputs({root,envFile,localOnlyKeys=[]}) {
  await refuseLocalModels(root);
  const declaration=JSON.parse(await readFile(join(root,'deploy.json'),'utf8'));
  if(localOnlyBinding(declaration,localOnlyKeys))throw new Error('Deploy declaration contains a local-only binding');
  if(!envFile)throw new Error('Container deploy requires --env-file with private production settings');
- const handle=await open(resolve(root,envFile),constants.O_RDONLY|constants.O_NOFOLLOW);
- let encoded;
- try{const status=await handle.stat();if(!status.isFile()||status.nlink!==1||(status.mode&0o077)!==0||(process.getuid&&status.uid!==process.getuid()))throw new Error('Deploy env file must be an owned private regular file (0600)');encoded=await handle.readFile('utf8');}finally{await handle.close();}
- const settings={};for(const line of encoded.split(/\r?\n/)){if(!line.trim()||line.trim().startsWith('#'))continue;const match=/^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);if(!match)throw new Error('Invalid deploy env file');if(Object.hasOwn(settings,match[1]))throw new Error('Repeated deploy env key');settings[match[1]]=match[2].replace(/^"(.*)"$/,'$1');}
- if([...LOCAL_ONLY_KEYS,...localOnlyKeys].some(key=>Object.hasOwn(settings,key)))throw new Error('Local-only keys are refused for deploy');
+ const settings=await readDeployEnvFile(root,envFile,localOnlyKeys);
  return{declaration,settings,encoded:Object.entries(settings).map(([key,value])=>key+'='+value).join('\n')+'\n'};
 }

package/modules/dependencies/auth.mjs

@@ -19,12 +19,13 @@ export function linkedProviders(options) {
    if(!await unclaimed())return null;
    if(native)return native.claimOwner?native.claimOwner({request,token,expectedPin}):null;
    return createIdpOwnerClaimHandler({expectedPin,db,authConfig:config,clientIp:()=>options.clientIp(request),clock:options.clock,fetch:options.fetch})(new Request(config.origin+'/auth/owner-claim',{method:'POST',headers:{Host:new URL(config.origin).host,Origin:config.origin,'Content-Type':'application/json'},body:JSON.stringify({token})}));
-  }, claimScope: unclaimed, config:{origin:config.origin,local:config.local,transactionSecret:config.OIDC_TRANSACTION_SECRET ?? config.SESSION_SECRET+'-oidc',providers:[{
+  }, claimScope: unclaimed, config:{origin:config.origin,local:config.local,signInPath:config.branding.signInPath,transactionSecret:config.OIDC_TRANSACTION_SECRET ?? config.SESSION_SECRET+'-oidc',providers:[{
    id:'auth',preset:'auth',issuer:link.issuer,clientId:link.client_id,privateKey:JSON.parse(row.private_key),
   }]}});
  }
  if(!config.dependencies) return staticProviders;
  return {
+  signInPath:config.branding.signInPath,
   ids:[...new Set(['auth',...(staticProviders?.ids??[])])],
   callbackPaths:{...staticProviders?.callbackPaths,'/auth/oidc/auth/callback':'auth'},
   async begin(...args){const p=args[1]!=='auth'?staticProviders:await current();return p?p.begin(...args):Response.json({error:'provider_unlinked'},{status:403});},

package/modules/deploy-kit/README.md

@@ -56,9 +56,9 @@ D1/Queue/DO account listings fully paginate with bounded page/request budgets. R
 
 The first receipt binds source commit SHA and tree, artifact/config SHA-256, effective deployment fingerprint, account/Worker, actual resource IDs, migration hashes, secret names and active provider deployment/version/etag. It contains no secret value. The CLI creates it exclusively at mode 0600 before the first health request; it is an identity receipt, not a claim that health passed (health attempts are added afterwards, see below). A failed health request still exits nonzero, while the retained identity allows the next explicit invocation to authenticate state without another upload. For the second deployment use the **same artifact, run/attempt and receipt**. Current provider state must match the prior receipt. The kit performs no resource creation, Worker/asset upload, SQL mutation, Cron/consumer update, or secret rewrite when unchanged. Read-only D1 queries use the provider's POST query transport; a POST is not by itself a database mutation. The receipt remains byte-identical on a repeat. Missing resources, drift or stale state fail without repair during this repeat.
 
-Opaque existing secrets are preserved by name and strict binding inheritance; values are never fetched or compared. Missing declared secrets are supplied in the upload metadata in memory only. Rotation is a separate explicit operation; changing an input value does not overwrite a deployed secret. No temporary secret files are used.
+Opaque existing secrets are preserved by name and strict binding inheritance; values are never fetched or compared. Missing declared secrets are supplied in the upload metadata in memory only. Rotation is a separate explicit operation (owner-account mode: `rer deploy --set-secret NAME`); changing an input value does not overwrite a deployed secret. No temporary secret files are used.
 
-Health independently reads current deployment/version/settings, resources, namespaces, schedules, consumers, secret presence and migration history. It requests only the authenticated account-derived `/health`, without credentials, rejects redirects/malformed/unhealthy/stale identity and reads deployment identity again afterward.
+Health independently reads current deployment/version/settings, resources, namespaces, schedules, consumers, secret presence and migration history. It requests only the authenticated account-derived `/health`, without credentials, rejects redirects/malformed/unhealthy/stale identity and reads deployment identity again afterward. A healthy answer naming another Worker version (an edge still serving the version before a secret change) is asked again within the window.
 
 `health.mjs` is Base's one health verifier. `waitForDeploymentHealth(url, options)` (formerly `deployment/health.mjs`) gives a newly published route and its bindings one bounded window, 30 seconds by default: only 404, 503 and network failures are retried, every other status and every redirect is terminal, and the final error states the last result. The standalone `health` command probes `/health` once; transient failures are recorded as failures without a retry. The library `verifyHealth` retains its bounded readiness window. After an upload, `deploy` uses the recorded readiness wait described below.
 
@@ -103,10 +103,20 @@ Ownership lives in a state file, by default `.rer/deploy/<environment>.json` und
 - **Partial failure and resume.** The kit records each create as `pending` before the request and `created` with the provider id after it. A failed create leaves `pending`. On the next run an absent pending name is created again, and a present one is refused as `uncertain-resource-create`, because a lost response cannot prove who created it. Inspect it: if it is the empty resource from the interrupted run, delete it and re-run. A Worker upload is recorded as created when the upload succeeds, so a failure after it resumes with one fresh upload. If the response to the very first upload is lost, the Worker exists but is still `pending`. The kit records the build and its fingerprint before sending an upload. With no prior receipt, the same build may recover its pending Worker only when the live fingerprint matches that intent, then resume with one fresh upload. A different build or fingerprint is refused as `uncertain-resource-create`; recover with the original build first. If the uncertain Worker cannot be authenticated, inspect it and delete it only after confirming that it is the kit-created Worker and that its Durable Object data is disposable. Back up any needed data before deleting it. Migration claims keep the rules under Migration safety.
 - **Drift.** A created resource that has gone is refused as `owned-resource-missing`; one replaced under the same name is refused as `owned-resource-replaced`. The kit never deletes or recreates them. This covers D1, KV, Queues and R2 (a bucket is identified by its creation date; a state file written before that was recorded keeps working and is not checked for that bucket). For the Worker, the live deployment (version id, deployment id and etag) must be the last receipt's before any write; someone else's upload under the same name is refused as `owned-resource-replaced` and never overwritten. Immediately before the Worker PUT, the kit rechecks every saved resource identity, including resources omitted from the current plan, then the Worker identity. A replacement during provisioning or asset upload is refused before the upload intent or receipt is saved. An interrupted successful upload may resume only when the live version id, deployment id and etag match the identity saved immediately after that upload. A historical fingerprint alone never overrides a receipt mismatch.
 - **Lost upgrade response.** If an upgrade response is lost and the live identity no longer matches the receipt, the kit refuses rather than guessing ownership. A [Cloudflare rollback](https://developers.cloudflare.com/workers/versions-and-deployments/rollbacks/) creates a new deployment, so it does not restore the recorded identity. Recover with a new environment and a fresh state path, or back up the state and any needed data, confirm ownership, and follow the cleanup under "If the state file is lost" with a fresh `--state` path.
+- **Settling listings.** Right after a create or delete, an account listing can briefly disagree with its own page counts (`provider-partial-list`: on 13 October 2026 D1's `total_count` lagged its rows by about 7 seconds after a create). Owner-mode deploy, health and removal discard such a snapshot and list again from the start for up to 30 seconds with a short backoff; a partial listing is never accepted.
 - **One run at a time.** A deploy takes an exclusive lock file, `<state file>.lock`, for the whole run and removes it at the end, even after a failure. A second run on the same state file is refused as `owner-state-locked` before any provider request. If a run was killed (power loss, `kill -9`) and no deploy is running, delete the lock file by hand.
 
 The CLI prints JSON: refusal codes and resource names only, never inputs, tokens or provider bodies.
 
+### rer deploy: inputs, the hosted owner, secret changes and removal
+
+`rer deploy` runs these steps for a seed whose adapter uses `ownerDeploy` from `cli/deploy.mjs`.
+
+- **Inputs.** Declared secrets come from the environment, then `--env-file FILE` (an owned 0600 file of `KEY=VALUE` lines), which wins. For a secret the Worker does not hold yet, rer supplies the setup manifest's owner email (`emailField`) from the local setup's private settings, and a fresh random value for each secret field the manifest generates (`generate`), such as the session secret and the setup token; a value the Worker already holds is kept. A still-missing secret stops the run before any write with a message that names it.
+- **Hosted owner.** After deploy and health pass, rer claims the setup owner on the hosted app: it POSTs the setup token to the seed's standard owner step (`hooks.owner`, by default `/auth/bootstrap`). 303 means claimed; `409 already_initialized` means an owner was already claimed and is kept. Then rer deletes the token secret from the Worker, records the new Worker version in the state file, and lists the token in `retiredSecrets`, so later plans no longer declare it. A Worker that still holds a token rer did not upload in this run (an older deploy) first gets a fresh token through the same recorded secret change. Dependency approvals that need the token run before the claim. A seed with an owner step function, an identity-provider claim, or no declared token secret claims its owner its own way.
+- **Secret changes.** `rer deploy --set-secret NAME` (value from the environment or `--env-file`, under the declaration's environment name) and `--unset-secret NAME` change one declared secret of the recorded Worker without a build. A secret change deploys a new Worker version of the same code, so rer checks the build fingerprint is unchanged and records the new version id, deployment id and etag as the receipt's provider identity: the next deploy recognises its own Worker. An unset secret is retired until it is set again. The change is recorded as pending before it is sent, and the secret listing and active deployment are read until they show it (they lag the change by seconds); a change the provider answers with an error clears that record. If a run ends before the change settles (a lost response), the next run adopts the live version only when the Worker's versions list shows exactly one version after the receipt's, it is the live one, and its script etag and build fingerprint are still the receipt's. A change made outside rer (dashboard, Wrangler), including one made after rer's own, still reads as a replacement and is refused.
+- **Removal.** `rer deploy --remove --yes` deletes what the state file says rer created for this environment: the Worker (schedules first; its Durable Objects go with it) and each D1, R2, KV and queue that is still the one rer created, after checking all of them before the first delete. A replaced or uncertain resource refuses the whole removal, except a resource whose create answer was lost: under this environment's derived name it is deleted once it is confirmed empty (a D1 with no tables, a KV namespace with no keys, an R2 bucket, which the provider refuses to delete while it holds objects); one holding data is refused as `uncertain-resource-not-empty`, and a queue, whose backlog rer cannot read, as `uncertain-resource-unverifiable` (delete it by hand if it is the empty one from the interrupted run). It then reads back that none is still listed and deletes the state file. An R2 bucket must be empty; a bucket with objects stays, the state file keeps it, and a later `--remove --yes` finishes. Resources rer did not create are never touched.
+
 ### If the state file is lost
 
 A fresh clone or CI runner has no `.rer/` directory, so the kit can no longer tell its own resources from anyone else's and refuses every later deploy as `resource-name-collision`. It is correct to refuse: the kit never adopts what it cannot prove it created. To recover, do one of these.
@@ -181,7 +191,7 @@ No Single Redirect (dynamic redirect ruleset) permission is needed. Base's refer
 
 ## Migration safety
 
-SQL files have ordered unique names and SHA-256 identities. `_rer_deploy_migrations` is permanent controller-owned history. Applied entries must be an unchanged prefix of the desired set. A new migration gets an `applying` claim before its SQL and completion marker are submitted together to the D1 batch query API. Any interrupted, failed or uncertain outcome remains blocked and must be inspected explicitly; the kit never automatically retries, rolls back user data, or marks an unknown outcome successful. Readback checks every final identity.
+SQL files have ordered unique names and SHA-256 identities. `d1_migrations` holds controller history with ordered IDs, names, timestamps, SHA-256 hashes and states. Native archives already exclude this installation table. Standard Wrangler name-only inserts remain possible, but their missing hashes/states block subsequent Base deployment pending reviewed adoption. Applied entries must be an unchanged prefix of the desired set. A new migration gets an `applying` claim before its SQL and completion marker are submitted together through the [Cloudflare D1 SQL import API](https://developers.cloudflare.com/api/resources/d1/subresources/database/methods/import/), using the same whole-file protocol as Wrangler to preserve compound trigger bodies and atomic SQL/completion. Uploads use bounded HTTPS R2 destinations, without account credentials; polling is bounded and signed URLs and import response text are never diagnostic output. Any interrupted, failed or uncertain outcome remains blocked and must be inspected explicitly; the kit never automatically retries, rolls back user data, or marks an unknown outcome successful. Readback checks every final identity.
 
 Completion preserves the original SQL bytes and always starts on a new line.
 Comment-only migrations are rejected before any provider request or ledger claim.
@@ -191,7 +201,7 @@ without treating quoted semicolons as terminators or changing migration hashes.
 
 A lexical guard rejects standalone transaction/resource control statements (`BEGIN`, `COMMIT`, `END`, `ROLLBACK`, `SAVEPOINT`, `RELEASE`, `ATTACH`, `DETACH`, `VACUUM`) at statement boundaries, including after a trigger. Bare `ROLLBACK` is also refused in conflict clauses and `RAISE`, which can roll back a batch without a standalone control statement. SQLite `CREATE [TEMP|TEMPORARY] TRIGGER` bodies and nested `CASE ... END` expressions are supported; quoted text and comments cannot create statement boundaries. Both ledger names are reserved in bare, double-quoted, backtick and bracket identifiers, including schema-qualified references. [SQLite also accepts single-quoted identifiers](https://www.sqlite.org/lang_keywords.html), so exact controller ledger names are reserved in every token, including data strings, relation names, virtual-table options and introspection arguments. Comments and longer descriptive strings remain allowed. This intentionally conservative policy does not attempt to authorize arbitrary SQLite name grammars. Incomplete quotes, block comments, parentheses, CASE expressions or trigger bodies and NUL bytes fail closed; trigger header expressions must close before BEGIN and body expressions before their statement semicolon. This guard protects controller custody; SQLite still validates application SQL syntax.
 
-Existing Wrangler `d1_migrations` records lack content hashes. Automatic adoption would fabricate historical certainty, so those installations require separately reviewed history/hash adoption before this kit proceeds. The kit can extend its own previous migrations while retaining existing application rows. Local SQLite tests prove failure rollback in the test transport; the provider's actual failure atomicity, retained data, and two-deploy no-mutation behavior remain live proof obligations. The conservative `applying` claim prevents automatic replay even if a remote batch partially commits.
+The old kit `_rer_deploy_migrations` ledger is moved atomically into `d1_migrations` only after every applied name/hash/state proves an exact desired-history prefix. An ordinary deploy performs this one-time metadata transition even for unchanged code; subsequent redeploys write nothing, and health remains read-only. Existing Wrangler `d1_migrations` records lack content hashes. Automatic adoption would fabricate historical certainty, so those installations require separately reviewed history/hash adoption before this kit proceeds unless their ordered rows exactly match a prefix already attested by the old kit ledger. That transition preserves their IDs and timestamps. The kit can extend its own previous migrations while retaining existing application rows. Local SQLite tests prove failure rollback in the test transport; the provider's actual failure atomicity, retained data, and two-deploy no-mutation behavior remain live proof obligations. The conservative `applying` claim prevents automatic replay even if a remote response is lost.
 
 ## Local operations and source templates
 
@@ -247,12 +257,20 @@ After an upload that changed the Worker, `deploy` gives `/health` a total
 90-second readiness budget (`readiness.totalMs`, never above 90000). Retries wait
 1 second, doubling to a 10-second cap, and never less than the 2-second poll of
 the standalone window: 2, 2, 4, 8, 10, 10 ... seconds. Only transport failures,
-404 and 5xx (including Cloudflare 52x) retry. A redirect, any other status, a
-malformed or unhealthy body and a deployment identity mismatch fail at once.
+404 and 5xx (including Cloudflare 52x) retry, and so does a healthy answer that
+names another Worker version (the edge still serving the previous version just
+after the upload). A redirect, any other status, a malformed or unhealthy body
+and a wrong identity from the uploaded version itself fail at once. The one
+built file then requested must answer 200; after an upload its 404, 5xx and
+transport failures are retried for up to 60 seconds, since an edge still serving
+the previous version does not have the new build's hashed files (seen live on
+13 October 2026).
 Each request is capped by both the 30-second request limit and the remaining
 budget, and no request starts at the deadline. An unchanged repeat uses the
 existing library window and does not record first-upload readiness attempts.
-The standalone CLI `health` command sends a single request. Library `verifyHealth`
+The standalone CLI `health` command sends a single request; only an answer from
+another Worker version (an edge still converging after a secret change) is asked
+again, within 30 seconds. Library `verifyHealth`
 retains the existing window, retrying only 404, 503 and network failures for
 30 seconds by default.
 

package/modules/deploy-kit/d1-import.mjs

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { assert, uuid } from './validation.mjs';
+
+// Wrangler's remote --file protocol. D1 imports execute the whole file atomically,
+// including trigger bodies; the query endpoint's semicolon splitting cannot.
+export async function importD1({ envelope, upload }, id, sql) {
+  assert(uuid(id) && typeof sql === 'string' && Buffer.byteLength(sql) <= 4 * 1024 * 1024, 'invalid-d1-import');
+  const bytes = Buffer.from(sql), etag = createHash('md5').update(bytes).digest('hex');
+  const post = async body => (await envelope(`/d1/database/${id}/import`, { method:'POST', body })).result;
+  let response = await post({ action:'init', etag });
+  if (response && Object.hasOwn(response, 'upload_url')) {
+    assert(typeof response.filename === 'string' && response.filename.length > 0 && response.filename.length <= 1024 && !/[\x00-\x1f\x7f]/.test(response.filename), 'invalid-d1-import-filename');
+    await upload(response.upload_url, bytes, etag);
+    response = await post({ action:'ingest', filename:response.filename, etag });
+  }
+  for (let polls = 0; polls < 100; polls++) {
+    // REST places errors on the envelope; validate nested errors when supplied.
+    assert(response?.success === true && response.type === 'import' && (!Object.hasOwn(response, 'errors') || Array.isArray(response.errors) && !response.errors.length), 'd1-import-failed');
+    if (response.status === 'complete') {
+      assert(Number.isSafeInteger(response.result?.num_queries) && response.result.num_queries > 0 && typeof response.result.final_bookmark === 'string' && response.result.final_bookmark.length > 0, 'd1-import-invalid-result');
+      return;
+    }
+    assert(response.status === 'active' && typeof response.at_bookmark === 'string' && response.at_bookmark.length > 0 && response.at_bookmark.length <= 1024, 'd1-import-uncertain');
+    response = await post({ action:'poll', current_bookmark:response.at_bookmark });
+  }
+  throw new Error('d1-import-poll-limit');
+}
+
+export function importUploadURL(value) {
+  assert(typeof value === 'string' && value.length <= 16384 && !/[\x00-\x20\x7f\\]/.test(value), 'invalid-d1-import-upload-url');
+  let url;
+  try { url = new URL(value); } catch { throw new Error('invalid-d1-import-upload-url'); }
+  assert(url.protocol === 'https:' && /^[a-f0-9]{32}\.r2\.cloudflarestorage\.com$/.test(url.hostname) && !url.port && !url.username && !url.password && !url.hash && url.pathname.length > 1 && url.search.length > 1, 'invalid-d1-import-upload-url');
+  return url.href;
+}

package/modules/deploy-kit/deploy.mjs

@@ -1,3 +1,4 @@
+import { recordDeployFailure } from './diagnostics.mjs';
 import { verifyServiceGrants } from './service-grants.mjs';
 import { assert, hash, validatePlan } from './validation.mjs';
 import { validateArtifact, publicAssetPaths } from './artifact.mjs';
@@ -32,13 +33,14 @@ export async function deploy({api,plan,artifact,artifactSha256,previousReceipt,r
   const authenticated = previousReceipt?.fingerprint === fingerprint && previousReceipt.accountId === api.accountId && previousReceipt.worker === plan.worker && previousReceipt.provider?.versionId === existing?.versionId && previousReceipt.provider?.etag === existing?.etag && previousReceipt.provider?.deploymentId === existing?.deploymentId;
   const unchanged = priorFingerprint === fingerprint && secrets.missing.length === 0 && !migration && !(uploadWithoutReceipt && !authenticated);
   if (repeatOnly) assert(unchanged && previousReceipt?.fingerprint === fingerprint && previousReceipt?.provider?.versionId === existing?.versionId && previousReceipt?.provider?.etag === existing?.etag, 'repeat-deployment-drift');
-  const migrations = [];
-  for (const item of plan.d1) migrations.push({binding:item.binding,...await migrate(api,resources.d1.find(x => x.binding === item.binding).id,item.migrations,{apply:!unchanged})});
   if (unchanged) {
     assert(previousReceipt?.fingerprint === fingerprint && previousReceipt.accountId === api.accountId && previousReceipt.worker === plan.worker && previousReceipt.provider?.versionId === existing.versionId && previousReceipt.provider?.etag === existing.etag && previousReceipt.provider?.deploymentId === existing.deploymentId, 'no-op-requires-authenticated-prior-receipt');
     verifyBindings(existing.settings.bindings,bindings);
   }
-  else await uploadWorker(api,{plan,artifact,bindings,secrets,migration,fingerprint});
+  const migrations = [];
+  // A migration failure names its database, so the owner knows which one to inspect.
+  for (const item of plan.d1) migrations.push({binding:item.binding,...await migrate(api,resources.d1.find(x => x.binding === item.binding).id,item.migrations,{apply:!unchanged,upgrade:true}).catch(error => { error.resource ??= `d1:${item.name}`; throw error; })});
+  if (!unchanged) await uploadWorker(api,{plan,artifact,bindings,secrets,migration,fingerprint});
   const published = unchanged ? existing : await activeWorker(api,plan.worker); assert(published,'missing-deployed-worker');
   verifyBindings(published.settings.bindings,bindings);
   verifyScheduledHandler(published,plan);
@@ -55,8 +57,10 @@ export async function deploy({api,plan,artifact,artifactSha256,previousReceipt,r
   if (onReceipt) await onReceipt(receipt);
   // One built file proves the Worker hands static assets to the browser (assets run behind it).
   const asset = publicAssetPaths(artifact.assets.map(x => x.path))[0];
-  if (unchanged) await verifyHealth({...healthOptions,api,plan,receipt,fetch,asset});
-  else await firstHealth({api,plan,receipt,fetch,healthOptions,readiness,onHealth,asset});
+  try {
+    if (unchanged) await verifyHealth({...healthOptions,api,plan,receipt,fetch,asset});
+    else await firstHealth({api,plan,receipt,fetch,healthOptions,readiness,onHealth,asset});
+  } catch (error) { throw recordDeployFailure(error,{step:'health',...(error.code ? {code:error.code,output:error.message} : {})}); }
   return receipt;
 }
 

package/modules/deploy-kit/diagnostics.mjs

@@ -0,0 +1,65 @@
+// Provider text is private until the CLI's existing credential redactor approves
+// it. Identity, rather than mutable Error properties, carries this diagnostic.
+const failures = new WeakMap();
+export function recordDeployFailure(error, details) {
+  failures.set(error,{...failures.get(error),...details});
+  return error;
+}
+export function deployDiagnostic(error, redact) {
+  const detail = failures.get(error);
+  if (!detail) return undefined;
+  const clean = value => (redact ?? String)(String(value)).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g,'').replace(/\b[a-f0-9]{32}\b/gi,'[REDACTED]');
+  const failureCode = detail.code ?? error.message;
+  const code = /^[a-zA-Z0-9_-]{1,120}$/.test(failureCode) ? clean(failureCode) : 'deploy-failed';
+  return {code,step:detail.step ?? 'deploy',created:(detail.created ?? []).map(clean),
+    ...(typeof error.resource==='string' && /^(?:d1|r2|kv|queues|worker|service):[a-z0-9-]+$/.test(error.resource) ? {resource:clean(error.resource)} : {}),
+    ...(detail.providerCodes?.length ? {providerCodes:detail.providerCodes} : {}),
+    output:(detail.output ? (redact ? clean(detail.output) : '(provider output withheld; rer deploy provides redacted details)') : '(no provider output)').split(/\r?\n/).slice(0,8).map(line=>line.slice(0,500)).join('\n')};
+}
+function operation(path, options = {}) {
+  const write = options.method && options.method !== 'GET';
+  if (/\/d1\/database\/[^/]+\/query/.test(path)) return 'migrate D1';
+  for (const [prefix,kind] of [['/d1/database','D1'],['/r2/buckets','R2'],['/queues','queue'],['/storage/kv/namespaces','KV']]) {
+    if (path === prefix && options.method === 'POST') return `create ${kind}`;
+    if (path.startsWith(prefix)) return `check ${kind}`;
+  }
+  if (path.includes('/secrets')) return 'secrets';
+  if (path.includes('/subdomain') || path.includes('/routes') || path.includes('/domains')) return 'route';
+  if (path.includes('/schedules')) return 'scheduled triggers';
+  if (write && path.startsWith('/workers/')) return 'upload Worker';
+  return 'check Worker';
+}
+const CREATED_KINDS = {D1:'d1',R2:'r2',KV:'kv',queue:'queues'};
+export function deploymentDiagnostics(api, {onCreated} = {}) {
+  const created = [];
+  const recordCreated = resource => { created.push(resource); onCreated?.(resource); };
+  let currentStep = 'prepare deploy';
+  const guard = method => async (path, options) => {
+    const step = operation(path,options);
+    currentStep = step;
+    try {
+      const result = await api[method](path,options);
+      if (step.startsWith('create ')) recordCreated(`${step.slice(7)}:${options.body.name ?? options.body.queue_name ?? options.body.title}`);
+      return result;
+    } catch (error) {
+      // A failed create names the resource it asked for: a lost answer may still have created it.
+      if (step.startsWith('create ') && error.resource === undefined) error.resource = `${CREATED_KINDS[step.slice(7)]}:${options.body.name ?? options.body.queue_name ?? options.body.title}`;
+      throw recordDeployFailure(error,{step,created:[...created]});
+    }
+  };
+  return {...api,request:guard('request'),list:guard('list'),envelope:guard('envelope'),recordCreated,
+    async importSql(id, sql) {
+      currentStep = 'migrate D1';
+      try { return await api.importSql(id, sql); }
+      catch (error) { throw recordDeployFailure(error,{step:currentStep,created:[...created]}); }
+    },
+    annotateFailure(error, step = currentStep) {
+      const prior = failures.get(error);
+      // Node filesystem/CLI codes are structural; their messages can hold paths
+      // and inputs, so retain them privately for the caller's redaction boundary.
+      const cliCode = typeof error.code === 'string' && /^(?:E[A-Z0-9_]{1,63}|health-[a-z-]+)$/.test(error.code) ? error.code : undefined;
+      recordDeployFailure(error,{step:prior?.step ?? step,created:prior?.created ?? [...created],
+        ...(!prior?.code && cliCode ? {code:cliCode,...(!prior?.output ? {output:error.message} : {})} : {})});
+      return error;
+    }};
+}

package/modules/deploy-kit/env-file.mjs

@@ -0,0 +1,26 @@
+import { open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolve } from 'node:path';
+import { LOCAL_ONLY_KEYS } from './owner.mjs';
+
+/** A deploy's private settings file: an owned 0600 regular file of KEY=VALUE lines
+ * (blank lines and # comments allowed, one optional pair of double quotes). */
+export async function readDeployEnvFile(root, envFile, localOnlyKeys = []) {
+  const handle = await open(resolve(root, envFile), constants.O_RDONLY | constants.O_NOFOLLOW);
+  let encoded;
+  try {
+    const status = await handle.stat();
+    if (!status.isFile() || status.nlink !== 1 || (status.mode & 0o077) !== 0 || (process.getuid && status.uid !== process.getuid())) throw new Error('Deploy env file must be an owned private regular file (0600)');
+    encoded = await handle.readFile('utf8');
+  } finally { await handle.close(); }
+  const settings = {};
+  for (const line of encoded.split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const match = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);
+    if (!match) throw new Error('Invalid deploy env file');
+    if (Object.hasOwn(settings, match[1])) throw new Error('Repeated deploy env key');
+    settings[match[1]] = match[2].replace(/^"(.*)"$/, '$1');
+  }
+  if ([...LOCAL_ONLY_KEYS, ...localOnlyKeys].some(key => Object.hasOwn(settings, key))) throw new Error('Local-only keys are refused for deploy');
+  return settings;
+}

package/modules/deploy-kit/health-request.mjs

@@ -55,6 +55,10 @@ export async function healthRequest({origin, receipt, versionId, request, timeou
   catch { attempt.errorClass = 'malformed-response'; return {attempt,transient:false}; }
   if (body?.ok !== true || body.deployment?.sourceSha !== receipt.source.sha || body.deployment?.fingerprint !== receipt.fingerprint || body.deployment?.versionId !== versionId) {
     attempt.errorClass = 'health-identity-mismatch';
+    // Right after an upload the edge can still answer from another version: that
+    // settles within the bound. The expected version answering wrongly does not.
+    const other = body?.ok === true && typeof body.deployment?.versionId === 'string' && body.deployment.versionId !== versionId;
+    return {attempt,transient:other};
   }
   return {attempt,transient:false};
 }
@@ -74,7 +78,8 @@ export async function waitHealth({origin,receipt,versionId,request,timeoutMs=300
     const result = await healthRequest({origin,receipt,versionId,request,timeoutMs:Math.max(1,Math.ceil(Math.min(timeoutMs,remaining))),offsetMs:Math.round(clock()-start)});
     attempts.push(result.attempt); await onAttempt(result.attempt,attempts);
     if (!result.attempt.errorClass) return {ok:true,versionId,attempts};
-    if (single || !result.transient) break;
+    // `single` asks once, except that an edge still answering from the previous version settles within the bound.
+    if (!result.transient || single && result.attempt.errorClass !== 'health-identity-mismatch') break;
     const rest = totalMs - (clock()-start);
     if (rest <= 0) break;
     await sleep(Math.min(Math.max(delay,MIN_DELAY_MS),rest)); delay = Math.min(delay*2,MAX_DELAY_MS);

package/modules/deploy-kit/health.mjs

@@ -46,14 +46,24 @@ export async function waitForDeploymentHealth(url, {
   throw healthError(`Deployment did not become healthy at ${url} within ${timeoutMs}ms; last result: ${lastResult}.`, lastResult === 'network error' ? 'health-transport-failed' : 'health-http-failed', lastResult);
 }
 
-/** One unauthenticated GET of a built file; anything but 200 means the browser gets no assets. */
-async function servedAsset(origin, path, request, timeoutMs) {
-  let response;
-  try { response = await request(`${origin}/${path.split('/').map(encodeURIComponent).join('/')}`,{redirect:'manual',signal:AbortSignal.timeout(timeoutMs),headers:{'Cache-Control':'no-cache'}}); }
-  catch { throw new Error('asset-transport-failed'); }
-  await response.body?.cancel().catch(() => {});
-  assert(response.status === 200 && !response.redirected,'asset-http-failed');
-  return {path,status:response.status};
+/** An unauthenticated GET of a built file; anything but 200 means the browser gets no assets.
+ * After an upload (`windowMs`), an edge still serving the previous version answers 404 for
+ * the new build's hashed files: 404, 5xx and transport failures are retried within the window. */
+async function servedAsset(origin, path, request, timeoutMs, {windowMs = 0, clock = () => performance.now(), sleep = ms => new Promise(resolve => setTimeout(resolve, ms))} = {}) {
+  const start = clock();
+  for (;;) {
+    let response, failure;
+    try { response = await request(`${origin}/${path.split('/').map(encodeURIComponent).join('/')}`,{redirect:'manual',signal:AbortSignal.timeout(timeoutMs),headers:{'Cache-Control':'no-cache'}}); }
+    catch { failure = 'asset-transport-failed'; }
+    if (response) {
+      await response.body?.cancel().catch(() => {});
+      if (response.status === 200 && !response.redirected) return {path,status:response.status};
+      failure = 'asset-http-failed';
+      if (response.redirected || response.status !== 404 && response.status < 500) throw new Error(failure);
+    }
+    if (clock() - start + 2000 > windowMs) throw new Error(failure);
+    await sleep(2000);
+  }
 }
 
 /** Authenticated provider readback, then the unauthenticated account-derived /health.
@@ -82,16 +92,26 @@ export async function verifyHealth({api,plan,receipt,fetch:request=globalThis.fe
   if (plan.workersDev === false) health = {ok:true,versionId:current.versionId,route:'none'};
   else if (readiness) health = await waitHealth({origin,receipt,versionId:current.versionId,request,timeoutMs,...readiness});
   else {
-    let response;
-    try {
-      response = await waitForDeploymentHealth(`${origin}/health`,{timeoutMs,intervalMs,attemptTimeoutMs:timeoutMs,headers:{'Cache-Control':'no-cache','Accept':'application/json'},fetchImpl:request,...(now ? {now} : {}),...(sleep ? {sleep} : {})});
-    } catch (error) { throw new Error(error.code ?? 'health-transport-failed'); }
-    assert(response.ok && response.status === 200 && !response.redirected,'health-http-failed');
-    const body = await boundedJSON(response,65536);
+    // A secret change makes a new version of the same build; until it reaches
+    // every edge, a healthy answer can still name the previous version. Ask again
+    // within the window; any other wrong identity fails at once.
+    const clock = now ?? Date.now, wait = sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms))), start = clock();
+    let body;
+    for (;;) {
+      let response;
+      try {
+        response = await waitForDeploymentHealth(`${origin}/health`,{timeoutMs,intervalMs,attemptTimeoutMs:timeoutMs,headers:{'Cache-Control':'no-cache','Accept':'application/json'},fetchImpl:request,...(now ? {now} : {}),...(sleep ? {sleep} : {})});
+      } catch (error) { throw new Error(error.code ?? 'health-transport-failed'); }
+      assert(response.ok && response.status === 200 && !response.redirected,'health-http-failed');
+      body = await boundedJSON(response,65536);
+      const other = body?.ok === true && typeof body.deployment?.versionId === 'string' && body.deployment.versionId !== current.versionId;
+      if (!other || clock() - start + intervalMs > timeoutMs) break;
+      await wait(intervalMs);
+    }
     assert(body?.ok === true && body.deployment?.sourceSha === receipt.source.sha && body.deployment?.fingerprint === receipt.fingerprint && body.deployment?.versionId === current.versionId,'health-identity-mismatch');
     health = {ok:true,versionId:current.versionId};
   }
-  if (asset && origin) health.asset = await servedAsset(origin,asset,request,timeoutMs);
+  if (asset && origin) health.asset = await servedAsset(origin,asset,request,timeoutMs,readiness ? {windowMs:60000,...(readiness.clock ? {clock:readiness.clock} : {}),...(readiness.sleep ? {sleep:readiness.sleep} : {})} : {});
   const after = await activeWorker(api,plan.worker);
   assert(after.versionId === current.versionId && after.deploymentId === current.deploymentId && after.etag === current.etag,'deployment-changed-during-health');
   await verifyServiceGrants(api, plan);

package/modules/deploy-kit/migration-ledger.mjs

@@ -0,0 +1,48 @@
+import { assert } from './validation.mjs';
+
+export const ledger = 'd1_migrations';
+const legacy = '_rer_deploy_migrations';
+export const literal = value => `'${value.replaceAll("'","''")}'`;
+export const createLedger = `CREATE TABLE ${ledger} (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE, applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, sha256 TEXT, state TEXT CHECK(state IN ('applying','applied')))`;
+const validPrefix = (rows, migrations) => rows.every((row, index) => row.name === migrations[index]?.name && row.sha256 === migrations[index]?.sha256 && row.state === 'applied');
+const same = (a, b) => a.length === b.length && a.every((row, index) => row.name === b[index].name && row.sha256 === b[index].sha256 && row.state === b[index].state);
+
+export async function readLedger(api, id, migrations, query) {
+  const read = async sql => (await query(api, id, sql))[0].results;
+  const tables = (await read(`SELECT name FROM sqlite_master WHERE type='table' AND name IN ('${legacy}','${ledger}')`)).map(row => row.name);
+  let old = [], applied = [], transition = '';
+  if (tables.includes(legacy)) {
+    const columns = await read(`SELECT name FROM pragma_table_info('${legacy}')`);
+    assert(columns.length === 3 && columns.every(row => ['name','sha256','state'].includes(row.name)), 'invalid-migration-ledger');
+    old = await read(`SELECT name, sha256, state FROM ${legacy} ORDER BY name`);
+    assert(validPrefix(old, migrations), 'changed-or-uncertain-migration-history');
+  }
+  if (tables.includes(ledger)) {
+    const columns = (await read(`SELECT name FROM pragma_table_info('${ledger}')`)).map(row => row.name);
+    assert(['id','name','applied_at'].every(name => columns.includes(name)), 'invalid-migration-ledger');
+    if (columns.includes('sha256') && columns.includes('state')) {
+      applied = await read(`SELECT name, sha256, state FROM ${ledger} ORDER BY id`);
+      assert(validPrefix(applied, migrations), 'changed-or-uncertain-migration-history');
+      if (tables.includes(legacy)) assert(same(applied, old), 'changed-or-uncertain-migration-history');
+    } else {
+      assert(!columns.includes('sha256') && !columns.includes('state'), 'invalid-migration-ledger');
+      const prior = await read(`SELECT name FROM ${ledger} ORDER BY id`);
+      // Names alone cannot attest historical bytes. Only an already verified kit
+      // prefix can supply hashes; preserve Wrangler row IDs and timestamps.
+      assert(prior.length <= old.length && prior.every((row,index) => row.name === old[index].name), 'legacy-migration-history-needs-reviewed-hash-adoption');
+      transition += `ALTER TABLE ${ledger} ADD COLUMN sha256 TEXT;\nALTER TABLE ${ledger} ADD COLUMN state TEXT;\n`;
+      for (const row of old.slice(0,prior.length)) transition += `UPDATE ${ledger} SET sha256=${literal(row.sha256)}, state='applied' WHERE name=${literal(row.name)};\n`;
+      for (const row of old.slice(prior.length)) transition += insert(row);
+      applied = old;
+    }
+  } else if (tables.includes(legacy)) {
+    transition = `${createLedger};\n`;
+    for (const row of old) transition += insert(row);
+    applied = old;
+  }
+  if (tables.includes(legacy)) transition += `DROP TABLE ${legacy};`;
+  return { applied, transition, exists:tables.includes(ledger) || tables.includes(legacy) };
+}
+function insert(row) {
+  return `INSERT INTO ${ledger}(name,sha256,state) VALUES (${literal(row.name)},${literal(row.sha256)},'applied');\n`;
+}