@runeditrun/rer 0.2.0 → 0.2.2

package/cli/inspect.mjs

@@ -7,7 +7,7 @@ import { aliases, pins, requiredHooks, serverDefaults, verbs, releaseFlags } fro
 import { runningVersion } from './version.mjs';
 import { contained, readPackage } from './project.mjs';
 import { shared } from './shared.mjs';
-import { missing, RerError } from './errors.mjs';
+import { missing } from './errors.mjs';
 import { projectNodePin } from './node-runtime-discovery.mjs';
 import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
 import { localAiDiagnostics } from './ai-local.mjs';
@@ -18,6 +18,7 @@ import { commandArgv, commandLine, declaredPackage, exactVersion, lockedPackage,
 import { vendoredCalls } from './package-calls.mjs';
 import { doorProtocol } from './door.mjs';
 import { savedOrigin } from './door-mode.mjs';
+import { probePnpm } from './pnpm-probe.mjs';
 
 // cliVersion: the rer version of the code answering (absent for a vendored copy
 // too old to record one). defaults: what a server start applies when the person
@@ -31,7 +32,16 @@ export async function describe(project) {
  };
  const capabilities = project.adapter?.verbs ?? {};
  return { contractVersion: 1, ...versioned, profile: 'first-party', defaults, pins: { node: pkg.engines?.node, pnpm: pkg.packageManager?.replace(/^pnpm@/, '') },
-  verbs: Object.fromEntries(Object.entries(capabilities).map(([verb, capability]) => [verb, { flags: (verbs[verb]?.flags ?? releaseFlags).filter(flag => capability.flags?.includes(flag)), effects: verbs[verb]?.effects ?? 'Existing Base release producer.' }])),
+  verbs: Object.fromEntries(Object.entries(capabilities).map(([verb, capability]) => {
+   const adapterEffects = capability.effects;
+   const operationsEffects = project.descriptor.commands?.[verb]?.effects;
+   const effects = typeof adapterEffects === 'string' && adapterEffects.trim()
+    ? adapterEffects
+    : typeof operationsEffects === 'string' && operationsEffects.trim()
+     ? operationsEffects
+     : verbs[verb]?.effects ?? 'Produce releases; keygen writes a public anchor and, on success, its private key to non-terminal stdout; sign writes a detached signature and prints (but does not execute) the GitHub upload command; receipt verifies against local anchors offline.';
+   return [verb, { flags: (verbs[verb]?.flags ?? releaseFlags).filter(flag => capability.flags?.includes(flag)), effects }];
+  })),
   aliases: Object.fromEntries(Object.entries(aliases).filter(([alias, verb]) => pkg.scripts?.[alias] === commandLine(verb, declaredPackage(pkg) !== undefined))),
   local: { state: project.adapter?.state, settings: project.adapter?.settings ?? [], installerState: '.seed/installer', outbox: '/__dev/outbox', ...await localState(project), origin: await savedOrigin(project), ...(project.adapter?.devIdentity ? { devIdentity: true, devKey: '.rer/local/dev-key.env' } : {}) },
   // This pin serves a checkout through the machine's front door (rer door).
@@ -137,25 +147,20 @@ async function packageClauses(root, pkg) {
 export async function tools(root, store, signal) {
  const node = await projectNodePin(root);
  if (node && process.versions.node !== node) throw missing(`Node ${node} is required. Run it with rer, with automatic project runtime selection enabled.`);
- const found = await probePnpm(root, store, signal).catch(error => { if (signal?.aborted) throw error; return null; });
- if (found === pins.pnpm) return;
- const { cachedPnpm, downloadPnpm } = await import('./pnpm-runtime.mjs');
- let directory = await cachedPnpm(pins.pnpm);
- if (!directory) {
-  store.report?.(`Fetching pnpm ${pins.pnpm} for this project (PATH has ${found ? `pnpm ${found}` : 'no pnpm'}); rer keeps it in its own cache.`);
-  try { directory = await downloadPnpm(pins.pnpm, signal); }
-  catch (error) { if (signal?.aborted || error instanceof RerError) throw error; throw missing(`pnpm ${pins.pnpm} is required and could not be fetched (${error.message}). Check the connection, or install pnpm ${pins.pnpm} yourself.`); }
- }
- usePnpm(directory);
- if (await probePnpm(root, store, signal) !== pins.pnpm) throw missing(`pnpm ${pins.pnpm} is required. The pnpm rer provides did not report it; install pnpm ${pins.pnpm} yourself.`);
+ const { ensureProjectPnpm } = await import('./project-pnpm.mjs');
+ await ensureProjectPnpm(root, { signal, store, report: text => store.report?.(text) });
 }
-const usePnpm = directory => { process.env.PATH = [dirname(process.execPath), directory, process.env.PATH].filter(Boolean).join(delimiter); };
+const usePnpm = directory => { process.env.PATH = [directory, dirname(process.execPath), process.env.PATH].filter(Boolean).join(delimiter); };
 
 export async function doctor(project, store, signal) {
  const { inspectOperations } = await import('../operations/operations.mjs');
  const diagnostic = await inspectOperations(project.root);
  const { localVariables } = await shared('local/environment.mjs');
- let values = {}, pnpm, stateValid = true;
+ let values = {}, pnpm, expectedPnpm, pnpmIssue, stateValid = true;
+ if (project.profile === 'first-party') {
+  try { expectedPnpm = await (await import('./project-pnpm.mjs')).projectPnpmPin(project.root); }
+  catch (error) { pnpmIssue = error.message; }
+ }
  if (project.profile === 'first-party') {
   const { selectLocalState } = await shared('local/state.mjs');
   try { await selectLocalState(project.root, project.adapter.state); } catch { stateValid = false; }
@@ -170,8 +175,8 @@ export async function doctor(project, store, signal) {
   } catch {}
   try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; }
   // A pnpm rer already provides counts; doctor never fetches one.
-  if (pnpm !== pins.pnpm) {
-   const directory = await (await import('./pnpm-runtime.mjs')).cachedPnpm(pins.pnpm).catch(() => undefined);
+  if (expectedPnpm && pnpm !== expectedPnpm) {
+   const directory = await (await import('./pnpm-runtime.mjs')).cachedPnpm(expectedPnpm).catch(() => undefined);
    if (directory) { usePnpm(directory); try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; } }
   }
  }
@@ -181,27 +186,14 @@ export async function doctor(project, store, signal) {
  const keys = localSettingKeys(project);
  const inputs = project.profile === 'first-party' ? requiredLocalSettings(project, values) : [];
  const warnings = project.profile === 'first-party' ? await cacheWarnings(project.root) : [];
- return { dependencies, warnings, ok: !aiIssues.length && dependencies.every(d=>d.ok) && diagnostic.ok && stateValid && !inputs.length && (project.profile !== 'first-party' || (process.versions.node === expectedNode && pnpm === pins.pnpm)),
+ return { dependencies, warnings, ok: !aiIssues.length && dependencies.every(d=>d.ok) && diagnostic.ok && stateValid && !inputs.length && (project.profile !== 'first-party' || (Boolean(expectedPnpm) && process.versions.node === expectedNode && pnpm === expectedPnpm)),
   node: { actual: process.versions.node, expected: expectedNode },
-  pnpm: project.profile === 'first-party' ? { actual: pnpm, expected: pins.pnpm } : undefined,
+  pnpm: project.profile === 'first-party' ? { actual: pnpm, expected: expectedPnpm ?? null, ...(pnpmIssue ? { issue: pnpmIssue } : {}) } : undefined,
   ai: { issues: aiIssues },
   missingInputs: [...new Set([...diagnostic.missingEnvironment, ...inputs])],
   sources: project.descriptor.environmentSources ?? {}, state: { path: project.adapter?.state, safe: stateValid }, scope: 'local-inputs-only' };
 }
 
-// Diagnostics and execution use the same identity-checked process custody.
-// Exit starts cleanup even if a descendant still holds the output pipes.
-async function probePnpm(root, store, signal) {
- const probeSignal = AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean));
- const child = store.spawn('Checking pinned pnpm', 'pnpm', ['--version'], { cwd: root, signal: probeSignal });
- let version = '';
- child.stdout.on('data', chunk => { version = (version + chunk).slice(-1024); });
- const code = await new Promise(resolve => { child.once('error', () => resolve(null)); child.once('exit', code => resolve(code)); });
- await store.stop(child);
- if (probeSignal.aborted || code !== 0) throw missing('The pinned pnpm version probe failed. Select the documented tool.');
- return version.trim();
-}
-
 // SC-05: a seed declaring devIdentity loads the dev layer only from a local-only
 // entry that its dev configuration names, never from the deployed main, lets
 // rer build scan its output, and keeps one end-to-end email-link test.

package/cli/lifecycle.mjs

@@ -19,7 +19,7 @@ import { announceDoorRoute, routeRunning, verifyDoorFor } from './door-mode.mjs'
 export async function runCommand(project, options, out) {
  if(project.profile==='first-party'&&['dev','preview'].includes(options.verb))return (await import('./managed-server.mjs')).managedServer(project,options,out);
  const cancellation = new AbortController(), signal = cancellation.signal;
- let termination, operation, store, temporary, proxy;
+ let termination, operation, store, temporary, proxy, failed = false;
  const handlers = new Map(['SIGINT', 'SIGTERM'].map(name => [name, () => { if (!termination) { termination = name; cancellation.abort(name); } }]));
  for (const [name, handler] of handlers) process.on(name, handler);
  try {
@@ -85,8 +85,10 @@ export async function runCommand(project, options, out) {
   if (['export', 'import'].includes(options.verb)) return await transfer(project, options, signal, { store, operationToken: operation.token });
   if (options.verb === 'deploy') {
    if (typeof adapter.deploy !== 'function') throw refuse('Owner-account deploy declaration is missing.');
-   const deployed = await adapter.deploy({ root: project.root, options, store, signal, operationToken: operation.token, localOnlyKeys: adapter.localOnlyKeys ?? [], checkBuild: () => refuseDevLayerOutput(project.root, adapter.devIdentity) });
-   if(deployed.deployed && !options.dryRun) await linkDependencies({project,input:await savedSetupAnswers(project,project.setupSeed.model),origin:deployed.origin,store,signal,appSetupToken:process.env[project.setupManifest?.steps.find(step=>step.type==='owner-claim')?.tokenField??'SETUP_TOKEN']});
+   const link = async (origin, appSetupToken) => linkDependencies({project,input:project.setupSeed?await savedSetupAnswers(project,project.setupSeed.model):undefined,origin,store,signal,appSetupToken});
+   const deployed = await adapter.deploy({ root: project.root, options, store, signal, operationToken: operation.token, localOnlyKeys: adapter.localOnlyKeys ?? [], checkBuild: () => refuseDevLayerOutput(project.root, adapter.devIdentity), setupManifest: project.setupManifest, linkDependencies: link });
+   // Base's owner-account deploy links while its setup token is live; another deploy hook is linked here.
+   if(deployed.deployed && !options.dryRun && !deployed.dependenciesLinked) await link(deployed.origin,process.env[project.setupManifest?.steps.find(step=>step.type==='owner-claim')?.tokenField??'SETUP_TOKEN']);
    return deployed;
   }
   // Setup writes the checkout's dev key; its temporary app and the CLI's own
@@ -135,10 +137,18 @@ export async function runCommand(project, options, out) {
   } else if (options.verb !== 'build') throw refuse('The requested first-party capability is unavailable.');
   return {};
  } catch (error) {
+  failed = true;
   if (error instanceof RerError) throw error;
   throw await lifecycleError(error, store);
  } finally {
-  await store?.closeCommands(); await proxy?.close(); await operation?.release();
+  // Every closer runs: one that fails must not leave the job-queue policy socket
+  // listening (the process would never exit) or the local operation held, and
+  // must not turn a finished command into a failure or hide the real one.
+  const unclosed = [];
+  for (const close of [() => store?.closeCommands(), () => proxy?.close(), () => operation?.release()]) {
+   try { await close(); } catch (error) { unclosed.push(store?.redact?.(String(error?.message)) ?? 'unknown cause'); }
+  }
+  if (unclosed.length && !failed) out.progress(`Local cleanup could not confirm that every helper process stopped (${unclosed.join('; ')}). The ${options.verb} itself finished.\n`);
   if (temporary) await rm(temporary, { recursive: true, force: true });
   for (const [name, handler] of handlers) process.removeListener(name, handler);
   if (termination) throw new RerError('cancelled', `Stopped by ${termination} after owned children were stopped.`, termination === 'SIGINT' ? 130 : 143);

package/cli/main.mjs

@@ -27,6 +27,7 @@ export async function main(argv = process.argv.slice(2)) {
   if (project.profile === 'independent' && !['describe', 'check', 'doctor'].includes(options.verb)) options = parse(argv, process.cwd(), { independent: true });
   else if (options.forwarded.length) throw invalid('First-party commands accept only the documented flags, without forwarded arguments.');
   out = output(options);
+  if (project.profile === 'first-party' && options.detach && ['dev','preview'].includes(options.verb)) return (await import('./detached-server.mjs')).detachedServer(options, argv, out);
   if (options.verb === 'describe') { const result = await describe(project); out.human(options.json ? JSON.stringify(result) : JSON.stringify(result, null, 2)); return 0; }
   if (options.verb === 'check') {
    const result = await check(project, options.profile);

package/cli/managed-server.mjs

@@ -131,8 +131,14 @@ export async function managedServer(project,options,out,{clock={}}={}){
   const outbox=await outboxServed(selected.url,devKey,controller.signal);
   if(options.verb==='dev'&&project.adapter.site){
    const {devSite}=await import('./site.mjs');
-   site=await devSite(project,store,controller.signal,{host:selected.host,port:selected.port});
-   await registry.update({siteUrl:site.url});
+   try {
+    site=await devSite(project,store,controller.signal,{host:selected.host,port:selected.port});
+    await registry.update({siteUrl:site.url});
+   } catch(error) {
+    if(error.code!=='site_private_data')throw error;
+    const message=`Run site preview refused: ${error.message} The app is running; fix the site and run rer build --site before publishing it.`;
+    if(options.json)out.event('warning',{code:error.code,message});else out.progress(`Warning: ${message}\n`);
+   }
   }
   activity.ready();await emitReady(out,options,project.root,selected.url,dev,outbox,site?.url);
   if(crons.length){
@@ -147,8 +153,9 @@ export async function managedServer(project,options,out,{clock={}}={}){
  }catch(error){if(termination)throw new RerError('cancelled',`Stopped by ${termination} after owned children were stopped.`,termination==='SIGINT'?130:143);if(['idle timeout','explicit stop'].includes(reason))return {};throw await lifecycleError(error,store);}finally{await cleanup();cleaned();while(activityWriting)await activityWrites;await registry.close();for(const [name,handler]of handlers)process.off(name,handler);}
 }
 function reportScheduled(out,options,run){
- const at=new Date().toISOString().replace(/\.\d+Z$/,'Z'),outcome=run.skipped?`skipped (${run.error})`:run.ok?`ok ${run.ms}ms`:`failed (${run.status?`HTTP ${run.status}`:run.error}) ${run.ms}ms`;
- if(options.json)out.event('scheduled',{at,cron:run.cron,ok:run.ok,skipped:Boolean(run.skipped),status:run.status,ms:run.ms});else out.human(`RER_SCHEDULED ${at} "${run.cron}" ${outcome}`);
+ const error=options.verb==='preview'&&run.status===404 ? 'The preview target does not expose /cdn-cgi/local/scheduled. Forward the adapter context scheduled flag to previewTarget, or set RER_RUNTIME_TRIGGERS=1 in a custom target using the shared production runtime. For another runtime, expose that internal trigger endpoint or declare scheduled:false.' : run.error;
+ const at=new Date().toISOString().replace(/\.\d+Z$/,'Z'),outcome=run.skipped?`skipped (${error})`:run.ok?`ok ${run.ms}ms`:`failed (${run.status?`HTTP ${run.status}`:error}) ${run.ms}ms`;
+ if(options.json)out.event('scheduled',{at,cron:run.cron,ok:run.ok,skipped:Boolean(run.skipped),status:run.status,ms:run.ms,...(error?{error}:{})});else out.human(`RER_SCHEDULED ${at} "${run.cron}" ${outcome}${error&&run.status?` — ${error}`:''}`);
 }
 // GET, not HEAD: a seed's outbox route need not answer HEAD. The body is never read.
 async function outboxServed(url,devKey,signal){
@@ -169,7 +176,7 @@ async function emitReady(out,options,root,url,dev,outbox,siteUrl){
 }
 async function devReady(url,key,options,signal){
  if(options.verb==='preview')return {openUrl:openUrl(url,key,{path:'/__dev/key',next:'/__dev/outbox'})};
- if(options.login)return {openUrl:openUrl(url,key,{next:'/__dev/outbox'})};
+ if(options.login)return {openUrl:openUrl(url,key,{path:'/__dev/key',next:'/__dev/outbox'})};
  const as=options.as??'owner',persona=await resolvePersona(url,key,as,signal);
  // The owner persona names the owner the session will actually have (the
  // remaining owner once the setup owner has left), or none when none is left.

package/cli/parse.mjs

@@ -2,7 +2,7 @@ import { resolve } from 'node:path';
 import { commonFlags, serverDefaults, verbs } from './contract.mjs';
 import { invalid, refuse } from './errors.mjs';
 import { isLoopbackHost } from '../modules/operator-auth/loopback.mjs';
-const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--open', '--stop', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata', '--door', '--direct', '--site']);
+const booleans = new Set(['--help', '--json', '--non-interactive', '--yes', '--dry-run', '--open', '--stop', '--detach', '--foreground', '--no-queue', '--login', '--legacy-v1', '--acknowledge-unverified-metadata', '--door', '--direct', '--site', '--remove']);
 export const mailbox = value => typeof value === 'string' && value.length <= 254 && /^[a-zA-Z0-9.!+_%\-]+@[a-zA-Z0-9\-]+(?:\.[a-zA-Z0-9\-]+)+$/.test(value);
 // A loopback host: the shared predicate (including `*.localhost` door names),
 // plus `::1` as --host and a bracket-stripped hostname spell it.
@@ -45,7 +45,8 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
  }
  if (options.help) return options;
  if (deferTail) { options.cwd=resolve(cwd,options.cwd);return options; }
- if(options.stop && ['--port','--host','--idle-timeout','--no-queue','--as','--login','--models','--models-service','--door','--direct'].some(flag=>options.supplied.has(flag)))throw invalid('--stop cannot be combined with start-only flags.');
+ if (options.detach && options.foreground) throw invalid('Choose one of --detach and --foreground.');
+ if(options.stop && ['--port','--host','--idle-timeout','--detach','--foreground','--no-queue','--as','--login','--models','--models-service','--door','--direct'].some(flag=>options.supplied.has(flag)))throw invalid('--stop cannot be combined with start-only flags.');
  // --port and --host always mean direct mode; --door and --direct pick a mode.
  if(options.door&&options.direct)throw invalid('Choose one of --door and --direct.');
  if(options.door&&['--port','--host'].some(flag=>options.supplied.has(flag)))throw invalid('--door cannot be combined with --port or --host, which always serve directly.');
@@ -71,6 +72,8 @@ export function parse(argv, cwd = process.cwd(), { independent = false, deferTai
  if (options.target !== undefined && !['local', 'remote'].includes(options.target)) throw invalid('Target must be local or remote.');
  if (options.profile !== undefined && options.profile !== 'first-party') throw invalid('The supported explicit profile is first-party.');
  if (options.environment !== undefined && !/^[a-z][a-z0-9-]{0,39}$/.test(options.environment)) throw invalid('Provide a valid deployment environment name.');
+ for (const key of ['setSecret', 'unsetSecret']) if (options[key] !== undefined && !/^[A-Z][A-Z0-9_]{0,63}$/.test(options[key])) throw invalid('Name a declared secret binding, such as SESSION_SECRET.');
+ if ((options.remove || options.setSecret || options.unsetSecret) && options.site) throw invalid('--remove, --set-secret and --unset-secret act on the application Worker, not the run site.');
  if (options.origin !== undefined) {
   let url; try { url = new URL(options.origin); } catch { throw invalid('Provide a valid credential-free origin.'); }
   if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw invalid('Provide a credential-free HTTP origin without a path.');

package/cli/pnpm-probe.mjs

@@ -0,0 +1,14 @@
+import { missing } from './errors.mjs';
+
+// A version check owns its descendants just like a lifecycle command. Cleanup
+// starts at leader exit, even when quiet descendants still hold the pipes.
+export async function probePnpm(root, store, signal, env = process.env) {
+ const probeSignal = AbortSignal.any([signal, AbortSignal.timeout(10000)].filter(Boolean));
+ const child = store.spawn('Checking pinned pnpm', 'pnpm', ['--version'], { cwd: root, env, signal: probeSignal });
+ let version = '';
+ child.stdout.on('data', chunk => { version = (version + chunk).slice(-1024); });
+ const code = await new Promise(resolve => { child.once('error', () => resolve(null)); child.once('exit', code => resolve(code)); });
+ await store.stop(child);
+ if (probeSignal.aborted || code !== 0) throw missing('The pinned pnpm version probe failed. Select the documented tool.');
+ return version.trim();
+}

package/cli/pnpm-runtime.mjs

@@ -15,11 +15,11 @@ import { shellQuote } from './node-runtime-cache.mjs';
 // rer's own cache (~/.rer/pnpm/pnpm-VERSION). Only rer's own commands for the
 // project put it on their PATH; nothing global changes, and it is used only
 // when the person's PATH has no pnpm of the pinned version.
-export const pnpmCache = () => join(homedir(), '.rer', 'pnpm');
-const directoryOf = version => join(pnpmCache(), `pnpm-${version}`);
-const shim = version => join(directoryOf(version), 'shim');
-const receipt = version => join(directoryOf(version), '.rer-verified.json');
-const entry = version => join(directoryOf(version), 'bin', 'pnpm.cjs');
+export const pnpmCache = (env = process.env) => join(env.HOME || homedir(), '.rer', 'pnpm');
+const directoryOf = (version, env) => join(pnpmCache(env), `pnpm-${version}`);
+const shim = (version, env) => join(directoryOf(version, env), 'shim');
+const receipt = (version, env) => join(directoryOf(version, env), '.rer-verified.json');
+const entry = (version, env) => join(directoryOf(version, env), 'bin', 'pnpm.cjs');
 
 async function digest(path, algorithm, encoding) {
  const hash = createHash(algorithm);
@@ -30,25 +30,25 @@ async function owned(path, directory) {
  const stat = await lstat(path);
  if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile()) || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o022)) throw Error('Unsafe pnpm cache placement.');
 }
-async function prepareCache() {
- for (const path of [join(homedir(), '.rer'), pnpmCache()]) {
+async function prepareCache(env) {
+ for (const path of [join(env.HOME || homedir(), '.rer'), pnpmCache(env)]) {
   await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
   try { await owned(path, true); } catch { throw missing(`The pnpm cache directory must be an owned, non-linked directory without group/other write access: ${path}. Correct its placement and permissions before retrying.`); }
  }
- return pnpmCache();
+ return pnpmCache(env);
 }
 
 /** The verified cached pnpm's PATH directory, or undefined when none is cached. */
-export async function cachedPnpm(version) {
- try { await lstat(directoryOf(version)); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+export async function cachedPnpm(version, env = process.env) {
+ try { await lstat(directoryOf(version, env)); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
  try {
-  for (const path of [join(homedir(), '.rer'), pnpmCache(), directoryOf(version), shim(version)]) await owned(path, true);
-  for (const path of [receipt(version), entry(version), join(shim(version), 'pnpm')]) await owned(path, false);
-  const record = JSON.parse(await readFile(receipt(version), 'utf8'));
-  if (record.version !== version || !/^sha512-/.test(record.integrity) || record.entrySha256 !== await digest(entry(version), 'sha256', 'hex')) throw Error('pnpm cache integrity mismatch.');
-  return shim(version);
+  for (const path of [join(env.HOME || homedir(), '.rer'), pnpmCache(env), directoryOf(version, env), shim(version, env)]) await owned(path, true);
+  for (const path of [receipt(version, env), entry(version, env), join(shim(version, env), 'pnpm')]) await owned(path, false);
+  const record = JSON.parse(await readFile(receipt(version, env), 'utf8'));
+  if (record.version !== version || !/^sha512-/.test(record.integrity) || record.entrySha256 !== await digest(entry(version, env), 'sha256', 'hex')) throw Error('pnpm cache integrity mismatch.');
+  return shim(version, env);
  } catch {
-  throw missing(`The cached pnpm is unsafe or incomplete. Preserve it for inspection with: mv ${shellQuote(directoryOf(version))} ${shellQuote(directoryOf(version) + '.quarantine-' + Date.now())}. Then rerun the original rer command to fetch a verified release.`);
+  throw missing(`The cached pnpm is unsafe or incomplete. Preserve it for inspection with: mv ${shellQuote(directoryOf(version, env))} ${shellQuote(directoryOf(version, env) + '.quarantine-' + Date.now())}. Then rerun the original rer command to fetch a verified release.`);
  }
 }
 
@@ -69,8 +69,8 @@ function extract(archive, directory, signal) {
 }
 
 /** Fetch, verify and cache pnpm VERSION; returns its PATH directory. `registry` is the npm registry origin. */
-export async function downloadPnpm(version, cancellation, { registry = 'https://registry.npmjs.org' } = {}) {
- const cache = await prepareCache(), temporary = await mkdtemp(join(cache, '.download-'));
+export async function downloadPnpm(version, cancellation, { registry = 'https://registry.npmjs.org', env = process.env } = {}) {
+ const cache = await prepareCache(env), temporary = await mkdtemp(join(cache, '.download-'));
  const signal = AbortSignal.any([cancellation, AbortSignal.timeout(60000)].filter(Boolean));
  try {
   const metadata = join(temporary, 'release.json'), archive = join(temporary, 'pnpm.tgz');
@@ -86,11 +86,11 @@ export async function downloadPnpm(version, cancellation, { registry = 'https://
   if (JSON.parse(await readFile(join(extracted, 'package.json'), 'utf8')).version !== version) throw Error('Verified pnpm release did not name the project pin.');
   await mkdir(join(extracted, 'shim'), { mode: 0o700 });
   // `node` is rer's own: the command puts its Node first on PATH beside this.
-  await writeFile(join(extracted, 'shim', 'pnpm'), `#!/bin/sh\nexec node ${shellQuote(entry(version))} "$@"\n`, { mode: 0o700 });
+  await writeFile(join(extracted, 'shim', 'pnpm'), `#!/bin/sh\nexec node ${shellQuote(entry(version, env))} "$@"\n`, { mode: 0o700 });
   await writeFile(join(extracted, '.rer-verified.json'), JSON.stringify({ version, integrity, entrySha256: await digest(join(extracted, 'bin', 'pnpm.cjs'), 'sha256', 'hex') }) + '\n', { flag: 'wx', mode: 0o600 });
   await chmod(extracted, 0o700);
-  try { await rename(extracted, directoryOf(version)); }
-  catch (error) { if (!['EEXIST', 'ENOTEMPTY'].includes(error.code) || !(await cachedPnpm(version))) throw error; }
-  return shim(version);
+  try { await rename(extracted, directoryOf(version, env)); }
+  catch (error) { if (!['EEXIST', 'ENOTEMPTY'].includes(error.code) || !(await cachedPnpm(version, env))) throw error; }
+  return shim(version, env);
  } finally { await rm(temporary, { recursive: true, force: true }); }
 }

package/cli/portability-policy.mjs

@@ -0,0 +1,55 @@
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { policy as validatePolicy } from '../modules/portability/catalogue.mjs';
+import { PortabilityError } from '../modules/portability/index.mjs';
+
+// Only seed configuration supplies this entry point. Never resolve executable
+// policy from archive metadata, or stringify functions across the process seam.
+export async function policyModuleURL(root, entry) {
+ try {
+  let path;
+  if (entry instanceof URL || (typeof entry === 'string' && entry.startsWith('file:'))) {
+   const url = new URL(entry);
+   if (url.protocol !== 'file:' || url.search || url.hash) throw new Error();
+   path = fileURLToPath(url);
+  } else {
+   if (typeof entry !== 'string' || !entry || isAbsolute(entry) || /^[a-z][a-z\d+.-]*:/i.test(entry)) throw new Error();
+   path = resolve(root, entry);
+  }
+  const base = await realpath(root), actual = await realpath(path), within = relative(base, actual);
+  if (!within || within === '..' || within.startsWith('..' + sep) || isAbsolute(within) || !(await stat(actual)).isFile()) throw new Error();
+  return pathToFileURL(actual).href;
+ } catch { throw new PortabilityError('invalid_policy_module', 409); }
+}
+
+export function serializablePolicy(input) {
+ const seen = new Set();
+ function copy(value) {
+  if (value === null || value === undefined || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))) return value;
+  if (typeof value !== 'object' || seen.has(value) || (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))) throw new PortabilityError('policy_module_required', 409);
+  seen.add(value);
+  const result = Array.isArray(value) ? [] : Object.create(null);
+  for (const key of Reflect.ownKeys(value)) {
+   if (Array.isArray(value) && key === 'length') continue;
+   const descriptor = Object.getOwnPropertyDescriptor(value, key);
+   if (typeof key !== 'string' || !descriptor.enumerable || !('value' in descriptor)) throw new PortabilityError('policy_module_required', 409);
+   result[key] = copy(descriptor.value);
+  }
+  seen.delete(value);
+  return result;
+ }
+ const result = copy(input);
+ validatePolicy(result);
+ return result;
+}
+
+export async function loadPolicy(root, policy, policyModule) {
+ if (policyModule === undefined) return serializablePolicy(policy);
+ if (policy !== undefined) throw new PortabilityError('ambiguous_policy', 409);
+ try {
+  const { default: input } = await import(await policyModuleURL(root, policyModule));
+  validatePolicy(input);
+  return input;
+ } catch { throw new PortabilityError('invalid_policy_module', 409); }
+}

package/cli/portability-worker.mjs

@@ -4,27 +4,31 @@ import { readLegacyArchive } from '../modules/portability/format.mjs';
 import { recoverLegacyArchive } from '../modules/portability/legacy-files.mjs';
 import { legacyTargetState, requireLegacyEmpty } from '../modules/portability/legacy-safety.mjs';
 import { migrationReplay } from '../modules/portability/migration-history.mjs';
+import { appliedMigrations as appliedMigrationNames } from '../modules/portability/bridge.mjs';
 import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { createPortability, PortabilityError, readArchive } from '../modules/portability/index.mjs';
 import { parseJsonc } from './jsonc.mjs';
+import { loadPolicy } from './portability-policy.mjs';
 
-// The migrations this installation applied, in Wrangler's applied order, so a
+// The migrations this installation applied, in its ledger's order, so a
 // restore can place an older archive within them.
 async function appliedMigrations(root, db, binding, split) {
  const config = parseJsonc(await readFile(join(root, 'wrangler.jsonc'), 'utf8'));
  const directory = join(root, config.d1_databases.find(entry => entry.binding === binding).migrations_dir ?? 'migrations');
- const names = (await db.prepare('SELECT name FROM d1_migrations ORDER BY id').all()).results.map(row => row.name);
+ const names = await appliedMigrationNames(db) ?? [];
  return Promise.all(names.map(async name => ({ name, statements: split(await readFile(join(directory, name), 'utf8')) })));
 }
 
-async function run(direction, { root, path, journal, binding, buckets, policy, transient, legacyRecovery }) {
+async function run(direction, { root, path, journal, binding, buckets, policy, policyModule, transient, legacyRecovery }) {
  // Validate all inputs before opening bindings or acquiring a restore lock.
  if (direction === 'import') {
   for await (const record of fileRecords(path,legacyRecovery?readLegacyArchive:readArchive)) {}
   if(journal)for await(const record of fileRecords(journal)) {}
  }
+ policy = await loadPolicy(root, policy, policyModule);
+ if (direction === 'policy-preflight') return { checkedPolicy: true };
  const { getPlatformProxy, unstable_splitSqlQuery } = createRequire(join(root, 'package.json'))('wrangler');
 
  // Unlike Wrangler's --persist-to base, the API takes the versioned directory.
@@ -46,7 +50,7 @@ async function run(direction, { root, path, journal, binding, buckets, policy, t
 try { console.log(JSON.stringify({ ok: true, ...await run(process.argv[2], JSON.parse(process.argv[3])) })); }
 catch (error) {
  // Erasure-fence refusals name the fence: an older archive is refused, not a failed transfer.
- const refusal = error instanceof PortabilityError && (error.status === 409 || ['wrong_product', 'schema_mismatch', 'table_inventory', 'configuration_inventory', 'erased_row', 'erasure_epoch', 'later_journal', 'invalid_journal'].includes(error.code.split(':')[0]));
+ const refusal = error instanceof PortabilityError && (error.status === 409 || ['wrong_product', 'schema_mismatch', 'table_inventory', 'configuration_inventory', 'erased_row', 'erasure_epoch', 'later_journal', 'invalid_journal', 'staged_validation'].includes(error.code.split(':')[0]));
  const exitCode = error.message === 'archive_json' ? 2 : refusal || error.code === 'EEXIST' ? 4 : 1;
  // Report only symbolic codes; native database errors can contain private data.
  const reason = error instanceof PortabilityError ? error.code.split(':')[0] : /^[A-Z_]+$/.test(error.code ?? '') ? error.code : error.message === 'archive_json' ? 'archive_json' : 'native_error';

package/cli/portability.mjs

@@ -5,10 +5,11 @@ import { readArchive, PortabilityError } from '../modules/portability/index.mjs'
 import { readLegacyArchive } from '../modules/portability/format.mjs';
 import { fileRecords } from '../modules/portability/files.mjs';
 import { RerError, refuse } from './errors.mjs';
+import { policyModuleURL, serializablePolicy } from './portability-policy.mjs';
 
 // Seeds declare their real bindings and data policy. The shared module owns the
 // archive format and atomic restore; the shared runner owns its native children.
-export function localPortability({ database, binding = 'DB', buckets = {}, policy, transient = [] }) {
+export function localPortability({ database, binding = 'DB', buckets = {}, policy, policyModule, transient = [] }) {
  async function run({ root, path, journal, store, signal, operationToken, platform, legacyRecovery }, direction) {
   if (direction === 'export') {
    if (await lstat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; })) throw refuse('Export requires a new archive path.');
@@ -22,6 +23,7 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
     if(journal)for await(const record of fileRecords(journal)) {}
    }
    catch (error) {
+    if (error.message === 'archive_json') throw new RerError('invalid_archive', 'Restore refused (archive_json): archive JSON is invalid.', 2);
     if (!(error instanceof PortabilityError)) throw error;
     const message = error.code === 'legacy_archive_unverifiable'
      ? 'Restore refused (legacy_archive_unverifiable): version 1 metadata cannot be authenticated. Upgrade the original installation and re-export, or use rer import --legacy-v1 --input FILE --yes --acknowledge-unverified-metadata --output exports/recovered-v2.rer in an empty installation. See modules/portability/README.md#backup-only-v1-recovery.'
@@ -31,8 +33,22 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
    }
   }
   if(legacyRecovery)store.report('Legacy v1 recovery: manifest metadata is unverified. Restored data will be audited and exported to a new v2 backup.');
-  if(platform==='container') return (await import('./container-transfer.mjs')).containerTransfer({root,path,journal,store,signal,direction,binding,buckets,policy,transient});
-  const input={ root, path, journal, binding, buckets, policy, transient, legacyRecovery };
+  let declaration;
+  try {
+   if (policyModule !== undefined) {
+    if (policy !== undefined) throw new PortabilityError('ambiguous_policy', 409);
+    if (platform === 'container') throw new PortabilityError('container_policy_module_unsupported', 409);
+    declaration = { policyModule: await policyModuleURL(root, policyModule) };
+   } else declaration = { policy: serializablePolicy(policy) };
+  } catch (error) {
+   if (!(error instanceof PortabilityError)) throw error;
+   throw refuse(`Local portability policy refused (${error.code}). Executable policies require a seed-owned policyModule with a valid default policy export; policyModule requires native local transport.`);
+  }
+  if(platform==='container') return (await import('./container-transfer.mjs')).containerTransfer({root,path,journal,store,signal,direction,binding,buckets,policy:declaration.policy,transient});
+  const input={ root, path, journal, binding, buckets, ...declaration, transient, legacyRecovery };
+  // Check the executable policy before migrations; the transfer worker imports
+  // it again in its own process so module closures are retained during restore.
+  if (policyModule !== undefined) await nativeWorker(store,'policy-preflight',input,signal);
   // Do not apply pending product migrations to a populated recovery target.
   // Check real existing bindings first; finalize repeats this under the lock.
   if(legacyRecovery)await nativeWorker(store,'legacy-preflight',input,signal);
@@ -48,7 +64,7 @@ export function localPortability({ database, binding = 'DB', buckets = {}, polic
 
 async function nativeWorker(store,direction,input,signal) {
   const worker = fileURLToPath(new URL('./portability-worker.mjs', import.meta.url));
-  const child = store.spawn(`${direction === 'legacy-preflight' ? 'Checking empty recovery destination' : direction === 'export' ? 'Exporting' : 'Restoring'} local installation data`, process.execPath,
+  const child = store.spawn(`${direction === 'policy-preflight' ? 'Checking archive policy' : direction === 'legacy-preflight' ? 'Checking empty recovery destination' : direction === 'export' ? 'Exporting' : 'Restoring'} local installation data`, process.execPath,
    [worker, direction, JSON.stringify(input)], { cwd: input.root, signal, env: { ...process.env, WRANGLER_SEND_METRICS: 'false' } });
   let output = '';
   child.stdout.on('data', chunk => { output += chunk; });

package/cli/project-pnpm.mjs

@@ -0,0 +1,67 @@
+// Resolve the checkout's package manager before its own rer can be loaded.
+// The verified cache is private to rer; the resulting PATH travels to children.
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { delimiter, dirname, join } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { cachedPnpm, downloadPnpm } from './pnpm-runtime.mjs';
+import { missing, RerError } from './errors.mjs';
+import { shellQuote } from './node-runtime-cache.mjs';
+import { probePnpm } from './pnpm-probe.mjs';
+import { shared } from './shared.mjs';
+
+export async function projectPnpmPin(root) {
+ let pkg;
+ try { pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')); } catch {}
+ const pin = /^pnpm@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\+sha\d+\.[0-9a-f]+)?$/.exec(pkg?.packageManager ?? '')?.[1];
+ if (!pin) throw missing('This first-party checkout must declare an exact pnpm version in package.json packageManager. Correct that declaration, then rerun rer.');
+ return pin;
+}
+async function probe(root, env, signal, store) {
+ try { return await probePnpm(root, store, signal, env); }
+ catch (error) { if (signal?.aborted) throw error; return undefined; }
+}
+export async function ensureProjectPnpm(root, options = {}) {
+ if (options.store) return ensure(root, options);
+ // Global bootstrap has no adapter or lifecycle store yet. Give it the same
+ // command custody, with a temporary log and cancellation lasting through the
+ // download, both probes, and cleanup.
+ const cancellation = new AbortController();
+ const signal = AbortSignal.any([options.signal, cancellation.signal].filter(Boolean));
+ let termination, directory, store;
+ const handlers = new Map(['SIGINT', 'SIGTERM'].map(name => [name, () => { termination ??= name; cancellation.abort(name); }]));
+ for (const [name, handler] of handlers) process.on(name, handler);
+ try {
+  // Invalid manifests refuse before acquiring command custody or tools.
+  const pin = await projectPnpmPin(root);
+  directory = await mkdtemp(join(tmpdir(), 'rer-prerequisites-'));
+  const { createCommands } = await shared('commands.mjs');
+  store = await createCommands(directory, { logs: [] }, { terminal: () => {} });
+  store.setCommandSignal(signal);
+  return await ensure(root, { ...options, signal, store }, pin);
+ } finally {
+  try { await store?.closeCommands(); if (directory) await rm(directory, { recursive: true, force: true }); }
+  finally { for (const [name, handler] of handlers) process.removeListener(name, handler); }
+  if (termination) throw new RerError('cancelled', `Stopped by ${termination} after owned children were stopped.`, termination === 'SIGINT' ? 130 : 143);
+ }
+}
+async function ensure(root, { env = process.env, signal, report = () => {}, store }, pin) {
+ pin ??= await projectPnpmPin(root);
+ if (await probe(root, env, signal, store) === pin) return env;
+ let directory = await cachedPnpm(pin, env);
+ if (!directory) {
+  report(`Fetching pnpm ${pin} for this project; rer keeps it in its own cache.`);
+  try { directory = await downloadPnpm(pin, signal, { env }); }
+  catch (error) {
+   if (signal?.aborted || error instanceof RerError) throw error;
+   const prefix = join(env.HOME || homedir(), '.rer', 'pnpm', `manual-${pin}`);
+   throw missing(`pnpm ${pin} could not be fetched (${error.message}). Retry with a working connection, or run in this shell: npm install --prefix ${shellQuote(prefix)} --no-save pnpm@${pin} && export PATH=${shellQuote(join(prefix, 'node_modules/.bin'))}:"$PATH"`);
+  }
+ }
+ // Select the verified pnpm before any tool beside Node. Its shim still finds
+ // this process's Node before the caller's PATH, but cannot be shadowed by a
+ // different pnpm installed in that Node's bin directory.
+ const supplied = { ...env, PATH: [directory, dirname(process.execPath), env.PATH].filter(Boolean).join(delimiter) };
+ if (await probe(root, supplied, signal, store) !== pin) throw missing(`The verified pnpm ${pin} did not report the project version. Run ${shellQuote(join(directory, 'pnpm'))} --version to inspect it, then rerun rer.`);
+ Object.assign(env, supplied);
+ return env;
+}

package/cli/release.mjs

@@ -1,5 +1,41 @@
 // Preserve release's accepted parser, producer, receipt and validation exits.
+const releaseHelp = `Usage: rer release --repo DIR --project PUBLISHER/NAME --repository GITHUB_URL --output NEW_DIR [FLAGS]
+
+Produce local release artifacts after frozen installation, verification and publication checks.
+Without --tag, write a preview. This command never pushes, uploads or deploys.
+
+  --repo DIR             Source Git repository.
+  --project PUBLISHER/NAME
+                         Publishing identity.
+  --repository GITHUB_URL
+                         Credential-free https://github.com/<owner>/<repository> destination.
+  --output NEW_DIR       New output directory outside the source repository.
+  --ref REF              Selected committed source (default: HEAD).
+  --tag [vVERSION]       Prepare source artifacts and create a local annotated tag;
+                         an explicit tag must match the committed release version.
+  --dry-run              Run the real gates and suppress local tag creation.
+  --clean-history        Prepare a parentless public export.
+  --onto GITHUB_URL#BRANCH
+                         Prepare a public child of the destination's current branch;
+                         cannot be combined with --clean-history.
+  --env-file FILE        Credential file for publication inspection.
+  --no-queue             Bypass the job queue only in the original CI environment.
+  --help                 Print this help without performing release work.
+
+Signing and receipt commands:
+  rer release sign --artifact DIR (--key-file FILE | --key-stdin) [--scope test|rer]
+  rer release receipt --artifact DIR --anchors FILE [--environment test] [--after VERSION:SHA256]
+  rer release keygen --scope test|rer --publisher NAMESPACE --github-owner LOGIN --github-owner-id ID --anchor-out FILE
+    [--not-before YYYY-MM-DDTHH:MM:SSZ] [--not-after YYYY-MM-DDTHH:MM:SSZ]
+    [--unsigned-through PROJECT:VERSION ...]
+
+Signing scope defaults to rer; receipt environment defaults to production.
+Key generation requires non-terminal stdout; --key-stdin requires non-terminal stdin.
+`;
+
 export async function dispatchRelease(args) {
+ if (args.length === 1 && args[0] === '--help') { console.log(releaseHelp); return 0; }
+ if (['sign', 'receipt', 'keygen'].includes(args[0])) return (await import('../modules/release/signing-cli.mjs')).dispatchSigning(args[0], args.slice(1));
  try {
   const options = {};
   for (let index = 0; index < args.length; index++) {