@volter/world-runtime 3.0.166 → 3.0.167

package/dist/src/runtime.js

@@ -1,9 +1,11 @@
+import { isScalarCredentialField, withCurrentCredentialDoor } from "./credential-door.js";
 import { errorMessage } from "./error-message.js";
+import { recorderEnvironment, recordedApplicationEnvironment } from "./service-environment.js";
 import { materializeWorldBrowserFiles } from "./browser-files.js";
 import { claimEnvOutput, publishEnvOutput } from "./env-output.js";
 import { offSignal } from "./signals.js";
 import { parallelStartup } from "./startup.js";
-import { waitForHostReady } from "./host-ready.js";
+import { startedTwins, waitForHostReady } from "./host-ready.js";
 import { assertWorldStateRemovable, removeWorldState } from "./ancestry.js";
 import { packCli, packEntry } from "./catalog.js";
 import { vendorOfPackModule } from '@volter/world-core/runtime-state';
@@ -32,7 +34,7 @@ import { loadWorldConfig } from "./configs.js";
 import { createWorldNetworkPolicy, parseWorldNetworkPolicy, normalizeWorldNetwork, intersectWorldNetwork, WORLD_NETWORK_POLICY_ENV } from '@volter/world-core/network-policy';
 import { overlayPackFactsFile, resolveServicePackage } from "./catalog.js";
 import { fakeEnvValue } from "./fixture-env.js";
-import { APP_URL_ENV, ISSUE_ENV_PREFIX, MINT_ENV } from "./schema.js";
+import { APP_URL_ENV, ISSUE_ENV_PREFIX, MINT_ENV, assertRequiredCredentialBindings } from "./schema.js";
 import { readAppUrl } from "./app-url.js";
 import { inertInjectEnvWarnings } from "./inject-map.js";
 import { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, proxyEnvFor, tearDownCa } from "./proxy-env.js";
@@ -64,16 +66,14 @@ export function worldEventsPath(logs) {
  *  its output straight to `log` (capped, time-marked), its start and end are recorded there and in the World's events
  *  file, and it is handed a directory of its own for the log files it writes itself (VOLTER_WORLD_SERVICE_LOG_DIR).
  *  `ended` settles when the recorder exits, right after the service ends and its exit record is written. */
-function spawnRecorded(serviceId, command, args, cwd, env, log, boot) {
+function spawnRecorded(serviceId, command, args, cwd, env, log, boot, required) {
     const logDir = ownedPath(dirname(log), `${basename(log).replace(/\.log$/, '')}.d`);
+    const recorderEnv = recorderEnvironment(env, serviceId, log, logDir, worldEventsPath(dirname(log)));
+    // The recorder adds and removes its own names. Validate the same final child environment before opening a log or spawning.
+    if (required !== undefined)
+        assertRequiredCredentials(required, recordedApplicationEnvironment(recorderEnv), `service ${serviceId}'s recorded application environment`);
     mkdirSync(logDir, { recursive: true, mode: 0o700 });
     const out = openPrivateLog(log, 'a'); // the service's output and the recorder's records, appended
-    const recorderEnv = { ...env, VOLTER_WORLD_SERVICE_ID: serviceId, VOLTER_WORLD_SERVICE_LOG: log,
-        VOLTER_WORLD_SERVICE_LOG_DIR: logDir, VOLTER_WORLD_EVENTS: worldEventsPath(dirname(log)) };
-    if (recorderEnv.NODE_OPTIONS !== undefined) {
-        recorderEnv.VOLTER_WORLD_SERVICE_NODE_OPTIONS = recorderEnv.NODE_OPTIONS;
-        delete recorderEnv.NODE_OPTIONS;
-    }
     const child = spawn(process.execPath, [siblingScript(import.meta.url, 'service-recorder'), command, ...args], { windowsHide: true,
         cwd,
         env: recorderEnv,
@@ -563,9 +563,12 @@ function networkOf(name, own, recorded, parentEnv = process.env) {
         return undefined;
     return { [WORLD_NETWORK_POLICY_ENV]: JSON.stringify(createWorldNetworkPolicy(name, network)) };
 }
-/** Strip the publication envelope before combining permissions (the config shape admits only these keys). */
+/** Strip the publication envelope before combining permissions (the config shape admits only these keys). Every
+ *  permission the policy carries stays: a dropped `writes` or `publicReads` would read as the default when combined,
+ *  and a build World inside a closed one would read the public build origins its parent may not (sealing never widens). */
 function networkPermission(policy) {
-    return { egress: policy.egress, phase: policy.phase, passthrough: policy.passthrough, ...(policy.ownLoopback === false ? { ownLoopback: false } : {}) };
+    return { egress: policy.egress, ...(policy.writes !== undefined ? { writes: policy.writes } : {}), phase: policy.phase, passthrough: policy.passthrough,
+        ...(policy.publicReads !== undefined ? { publicReads: policy.publicReads } : {}), ...(policy.ownLoopback === false ? { ownLoopback: false } : {}) };
 }
 /** The boot permission, never a fallback to a mutable config. */
 export function recordedWorldNetwork(instance) {
@@ -701,7 +704,13 @@ function readWorldBootRecordLocked(name, root) {
         throw new Error(`World boot record is incomplete or invalid: ${path}\nFrom the app directory, inspect: volter-world doctor ${name} --root .\nComplete teardown with the owning runtime: volter-world down ${name} --root .\nRetain the startup diagnostics and any history. Only a disposable instance with no state to keep may be removed with down --purge; resume never discards it automatically.`);
     }
 }
-export function admittedEnv(strip, env = process.env) {
+/** What Windows itself needs in every process: without these, Winsock and DLL loading fail, the temp directory falls
+ *  back to C:\Windows\Temp and tools lose their profile folders. They hold no caller credential, so a strip (even
+ *  `*`) never removes them on win32. Windows names are case-insensitive. */
+const WINDOWS_BASELINE_ENV = new Set(['systemroot', 'windir', 'systemdrive', 'comspec', 'pathext', 'temp', 'tmp', 'userprofile',
+    'appdata', 'localappdata', 'programdata', 'programfiles', 'programfiles(x86)', 'programw6432', 'commonprogramfiles',
+    'commonprogramfiles(x86)', 'commonprogramw6432', 'homedrive', 'homepath', 'os', 'processor_architecture', 'number_of_processors']);
+export function admittedEnv(strip, env = process.env, platform = process.platform) {
     const out = {};
     const rules = (strip ?? []).map((s) => (s.endsWith('*') ? { prefix: s.slice(0, -1) } : { name: s }));
     for (const [k, v] of Object.entries(env)) {
@@ -711,6 +720,10 @@ export function admittedEnv(strip, env = process.env) {
         // whichever World happened to launch this operator process.
         if (k === WORLD_NETWORK_POLICY_ENV)
             continue;
+        if (platform === 'win32' && WINDOWS_BASELINE_ENV.has(k.toLowerCase())) {
+            out[k] = v;
+            continue;
+        }
         if (rules.some((r) => ('prefix' in r ? k.startsWith(r.prefix) : k === r.name)))
             continue;
         out[k] = v;
@@ -758,7 +771,7 @@ function savedStripEnvOf(instanceEnv) {
         return ['*'];
     }
 }
-function serviceProcessEnv(config, service, worldEnv, port) {
+function serviceProcessEnv(config, service, worldEnv, port, twin = service.type === 'twin') {
     const env = {
         ...admittedEnv(config.stripEnv),
         ...(config.env ?? {}),
@@ -772,6 +785,13 @@ function serviceProcessEnv(config, service, worldEnv, port) {
             delete env[key];
     }
     dropUnissued(env);
+    // NODE_ENV is the application's mode: a twin is the World's own server, run as built (React's production server build
+    // crashes Bun 1.3.11 at load, so Twenty's NODE_ENV=production stopped every twin with screens); a service's own env
+    // may still set it
+    // a twin is a service that runs a pack: declared `type: 'twin'`, or untyped and spawning a pack's module (never an
+    // untyped command of the application's)
+    if (twin)
+        delete env.NODE_ENV;
     const out = { ...env, ...(service.env ?? {}) };
     // the application's own origin: the World's own application service is reached where it listens (the URL
     // `volter-world app-url` answers for it); any other service never reads it, and a command resolves it at attach
@@ -1288,13 +1308,15 @@ export function externalServiceEnv(service, paths, worldEnv, stripEnv) {
             delete env[key];
     return env;
 }
-async function startExternalService(service, paths, worldEnv, stripEnv, boot) {
+async function startExternalService(service, paths, worldEnv, required, stripEnv, boot) {
     const external = service.external;
     if (!external)
         throw new Error(`External service "${service.id}" is missing its external config`);
     const log = ownedPath(paths.logs, `${service.id}.log`);
     const cwd = service.cwd ? resolve(paths.root, service.cwd) : paths.root;
     const env = externalServiceEnv(service, paths, worldEnv, stripEnv);
+    if (!ownInfrastructureService(service))
+        assertRequiredCredentials(required, env, `external service ${service.id}`);
     // 1. up — start the self-managed stack, STREAMING its output to the service log (no 1MB cap).
     if (!external.up[0] || !commandExists(external.up[0])) {
         throw new Error(`External service "${service.id}": \`${external.up[0] ?? ''}\` not found on PATH (the up command's tool is not installed)`);
@@ -1412,9 +1434,11 @@ async function trackBootingChild(child, boot, birth) {
     boot.identities[child.pid] = identity.start;
     boot.recordPids();
 }
-async function startService(config, service, worldEnv, paths, allocatedPorts, boot) {
+async function startService(config, service, worldEnv, paths, allocatedPorts, boot, required) {
+    if ((service.type ?? 'twin') !== 'twin' && !ownInfrastructureService(service))
+        assertRequiredCredentials(required, worldEnv, `service ${service.id}`);
     if (service.type === 'external')
-        return startExternalService(service, paths, worldEnv, config.stripEnv, boot);
+        return startExternalService(service, paths, worldEnv, required, config.stripEnv, boot);
     if (!service.command)
         throw new Error(`Service "${service.id}" must define command`);
     const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
@@ -1439,7 +1463,7 @@ async function startService(config, service, worldEnv, paths, allocatedPorts, bo
     if (service.rootArg !== false)
         args.push(service.rootArg ?? '--root', serviceDataDir);
     const log = ownedPath(paths.logs, `${service.id}.log`);
-    const env = serviceProcessEnv(config, service, worldEnv, port);
+    const env = serviceProcessEnv(config, service, worldEnv, port, service.type === 'twin' || (service.type === undefined && spawnedModule !== undefined));
     const cwd = service.cwd ? resolve(paths.root, service.cwd) : paths.root;
     // Augment NODE_OPTIONS with declared extra preloads, so a service can add an app-local preload
     // (e.g. a sandbox) WITHOUT replacing the world's injector. Paths resolve to absolute against the
@@ -1452,7 +1476,9 @@ async function startService(config, service, worldEnv, paths, allocatedPorts, bo
     // The service runs under the service recorder, which outlives it to write its end into its own log: `up`
     // returns once the World is ready, so nothing else is left to see a service stop.
     env.VOLTER_WORLD_BOOT_ID = boot.bootId;
-    const { child, ended, identity } = spawnRecorded(service.id, service.command, args, cwd, env, log, boot);
+    if ((service.type ?? 'twin') !== 'twin' && !ownInfrastructureService(service))
+        assertRequiredCredentials(required, env, `service ${service.id}'s effective environment`);
+    const { child, ended, identity } = spawnRecorded(service.id, service.command, args, cwd, env, log, boot, (service.type ?? 'twin') === 'twin' ? undefined : required);
     child.once('error', error => boot.fail(error));
     child.unref();
     await trackBootingChild(child, boot, identity);
@@ -1674,25 +1700,110 @@ function takeIssued(env) {
 /** How long a twin's credential door has to answer before its names are left unset (a door answers from the twin's
  *  own store, in milliseconds; this bounds a hung twin, not a slow one). */
 const ISSUE_TIMEOUT_MS = 15_000;
+function requiredCredentialClaims(config) {
+    const required = new Map();
+    for (const service of config.services)
+        for (const name of service.issues?.required ?? [])
+            required.set(name, { service: service.id, value: undefined });
+    return required;
+}
+/** Bind names and owners to the actual values retained in instance.env; the hash is not vendor authentication. */
+function requiredCredentialValuesDigest(required) {
+    const rows = [...required.keys()].sort().map(name => {
+        const claim = required.get(name);
+        if (claim.value === undefined)
+            throw new Error(`${name}: no issued value exists to retain`);
+        return [name, claim.service, claim.value];
+    });
+    return createHash('sha256').update(JSON.stringify(rows)).digest('hex');
+}
+/** New boots retain their required owners even if source config later changes; legacy optional records gain no proof. */
+function recordedRequiredCredentialClaims(instance) {
+    const required = new Map();
+    if (!Object.hasOwn(instance, 'requiredCredentials'))
+        throw new Error('World boot has no retained credential requirement declaration; finish teardown with its owning runtime and boot with this runtime before attachment');
+    const raw = instance.requiredCredentials;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error('World required credential record is invalid');
+    const record = raw;
+    if (Object.keys(record).some(key => !['version', 'owners', 'valuesSha256'].includes(key))
+        || !Object.hasOwn(record, 'version') || record.version !== 1 || !Object.hasOwn(record, 'owners') || record.owners === null
+        || typeof record.owners !== 'object' || Array.isArray(record.owners))
+        throw new Error('World required credential record has an unsupported version or shape');
+    if (!instance.env || typeof instance.env !== 'object' || Array.isArray(instance.env)
+        || !instance.services || typeof instance.services !== 'object' || Array.isArray(instance.services))
+        throw new Error('World required credential record lacks its retained environment or services');
+    for (const [name, owner] of Object.entries(record.owners)) {
+        if (!isEnvironmentName(name) || typeof owner !== 'string' || !owner || !Object.hasOwn(instance.services, owner))
+            throw new Error(`World required credential owner is invalid for ${name}`);
+        const service = instance.services[owner];
+        if (!service || service.id !== owner || service.type !== 'twin')
+            throw new Error(`World required credential ${name} names no twin owner`);
+        const value = instance.env[name];
+        if (!Object.hasOwn(instance.env, name) || typeof value !== 'string'
+            || value.startsWith(ISSUE_ENV_PREFIX) || value === APP_URL_ENV)
+            throw new Error(`World required credential ${name} has no retained scalar value`);
+        required.set(name, { service: owner, value });
+    }
+    if (!Object.hasOwn(record, 'valuesSha256')) {
+        if (required.size)
+            throw new Error('World required credential issuance has not completed; refusing attachment');
+        return required;
+    }
+    if (typeof record.valuesSha256 !== 'string' || !/^[0-9a-f]{64}$/.test(record.valuesSha256)
+        || record.valuesSha256 !== requiredCredentialValuesDigest(required))
+        throw new Error('World required credential names, owners or retained values changed; refusing attachment');
+    return required;
+}
+/** Capture the validated boot's values before an owned executor applies its own environment layers. */
+export function worldRequiredCredentialGate(instance) {
+    const required = recordedRequiredCredentialClaims(instance);
+    return (env, boundary) => assertRequiredCredentials(required, env, boundary);
+}
+/** These transports do not carry required ownership/value authority; refuse instead of exporting an optional-only rendering. */
+export function refuseRequiredCredentialTransport(instance, transport, code) {
+    const required = recordedRequiredCredentialClaims(instance);
+    if (required.size) {
+        const error = new Error(`World ${instance.name}: ${transport} does not carry required credential bindings (${[...required.keys()].join(', ')}); use local env attachment`);
+        throw code ? Object.assign(error, { code }) : error;
+    }
+}
+/** Check the actual response value, then the environment this boundary will use; never print credential values. */
+function assertRequiredCredentials(required, env, boundary) {
+    const failures = [];
+    for (const [name, claim] of required) {
+        if (claim.value === undefined)
+            failures.push(new Error(`${name}: ${claim.service} has not issued its required scalar credential`));
+        else if (!Object.hasOwn(env, name) || env[name] !== claim.value)
+            failures.push(new Error(`${name}: its issued value is missing or overridden at ${boundary}`));
+    }
+    if (failures.length)
+        throw new AggregateError(failures, `World required credential gate refused at ${boundary}: ${failures.map(reason => errorMessage(reason)).join('; ')}`);
+}
 /** A twin's issued credential (its `issues`, copied from its pack's credentialDoor by init): once it is up, the door is
  *  asked for one and each pending name of that service is set to it. A twin that answers no credential, or has no
- *  door, leaves the names unset and says so, rather than handing the application a fixture the twin would refuse. */
-async function issueCredentials(service, started, env, pending, unissued, controlRoot, times) {
+ *  door, leaves optional names unset and says so. Required scalar names fail the boot with their original reasons. */
+async function issueCredentials(service, started, env, pending, unissued, controlRoot, claims, fresh, times) {
     const direct = new Set([...pending].filter(([, id]) => id === `${service.id}@direct`).map(([name]) => name));
     const wanted = [...pending].filter(([name, id]) => id === service.id || direct.has(name)).map(([name]) => name);
     if (times) {
         times.names = wanted.length;
     }
+    const required = new Set(service.issues?.required ?? []);
+    const failures = [];
+    for (const name of required) {
+        if (!wanted.includes(name) || direct.has(name) || claims.get(name)?.service !== service.id)
+            failures.push(new Error(`${name}: its exact $issue:${service.id} scalar request is absent at issuance`));
+    }
+    if (failures.length)
+        throw new AggregateError(failures, `World service ${service.id}: required credential requests refused: ${failures.map(reason => errorMessage(reason)).join('; ')}`);
     if (wanted.length === 0)
         return;
     for (const name of wanted)
         pending.delete(name);
-    // the pack's door as it stands now (a door the pack fixed since the World was made reaches it), else the saved copy
-    let door = service.issues;
-    try {
-        door = packFacts()[service.id]?.credentialDoor ?? door;
-    }
-    catch { /* no artifact: the saved copy */ }
+    // Revalidate aliases at the actual issuance boundary. A missing current pack door cannot revive a saved issuer.
+    const door = (service.type ?? 'twin') === 'twin'
+        ? withCurrentCredentialDoor(service, packFacts()[service.id]?.credentialDoor).issues : service.issues;
     if (times)
         times.door = performance.now();
     try {
@@ -1700,8 +1811,12 @@ async function issueCredentials(service, started, env, pending, unissued, contro
             throw new Error('its service names no credential door');
         if (!started.url)
             throw new Error('it has no URL to ask');
-        // A boot's identity is existing account state, not an application write to deploy.
-        const enclosingSeed = placeholderPullActive(service.id, controlRoot);
+        // A boot's identity is existing account state, not an application write to deploy: asked inside the twin's
+        // placeholder-pull window, as the seed is (architecture, the descriptor's credentialDoor), on a fresh World's first
+        // issuance only: a resumed World's door answers what it issued before, and its branch keeps its own writes; a twin
+        // with a root is not seeded, and its door's writes stay its own
+        const seeds = fresh && !service.root;
+        const enclosingSeed = !seeds || placeholderPullActive(service.id, controlRoot);
         if (!enclosingSeed)
             beginPlaceholderPull(service.id, controlRoot);
         let answer;
@@ -1828,7 +1943,12 @@ async function issueCredentials(service, started, env, pending, unissued, contro
                     continue;
                 }
                 const field = spec;
+                if (required.has(name) && (!isScalarCredentialField(field) || answer === null || typeof answer !== 'object'
+                    || Array.isArray(answer) || !Object.hasOwn(answer, field)))
+                    throw new Error(`answered no own scalar ${field}`);
                 const value = answer[field];
+                if (required.has(name) && typeof value === 'string' && (value.startsWith(ISSUE_ENV_PREFIX) || value === APP_URL_ENV))
+                    throw new Error(`answered an interpreted environment marker for ${field}`);
                 if (typeof value !== 'string')
                     throw new Error(`answered no ${field}`);
                 if (direct.has(name)) {
@@ -1842,11 +1962,23 @@ async function issueCredentials(service, started, env, pending, unissued, contro
                 }
                 else
                     env[name] = value;
+                if (required.has(name)) {
+                    const claim = claims.get(name);
+                    if (!claim || claim.service !== service.id)
+                        throw new Error('its required credential owner changed');
+                    claim.value = value;
+                }
             }
             catch (error) {
-                process.stderr.write(`volter-world: ${service.id} did not issue ${name} (${errorMessage(error)}${typeof answer.codex_unavailable === 'string' ? `; the twin says: ${answer.codex_unavailable.slice(0, 300)}` : ''}); left unset\n`);
+                process.stderr.write(`volter-world: ${service.id} did not issue ${name} (${errorMessage(error)}${typeof answer?.codex_unavailable === 'string' ? `; the twin says: ${answer.codex_unavailable.slice(0, 300)}` : ''}); left unset\n`);
                 delete env[name];
                 unissued.add(name);
+                if (required.has(name)) {
+                    const claim = claims.get(name);
+                    if (claim)
+                        claim.value = undefined;
+                    failures.push(new Error(`${name}: ${service.id} did not issue its required credential (${errorMessage(error)})`, { cause: error }));
+                }
             }
         }
         if (started.url) {
@@ -1862,9 +1994,17 @@ async function issueCredentials(service, started, env, pending, unissued, contro
             delete env[name];
             unissued.add(name);
         }
+        for (const name of required) {
+            const claim = claims.get(name);
+            if (claim)
+                claim.value = undefined;
+            failures.push(new Error(`${name}: ${service.id}'s required credential ask failed (${errorMessage(error)})`, { cause: error }));
+        }
     }
     if (times)
         times.filled = performance.now();
+    if (failures.length)
+        throw new AggregateError(failures, `World service ${service.id}: required credential issuance refused: ${failures.map(reason => errorMessage(reason)).join('; ')}`);
 }
 function materializeConfig(config, root) {
     const services = config.services.map((service) => {
@@ -1976,6 +2116,8 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
         if (value === APP_URL_ENV)
             delete env[key];
     dropUnissued(env);
+    // the colocated twins' host runs the World's own servers: the application's NODE_ENV is not theirs (serviceProcessEnv)
+    delete env.NODE_ENV;
     env.VOLTER_WORLD_BOOT_ID = boot.bootId;
     const spawnedAt = Date.now();
     // Under the same exit recorder as a process service, so the host's end (and every twin it holds) is in host.log.
@@ -2014,12 +2156,7 @@ async function startColocatedServices(config, colocated, isolation, worldEnv, pa
     });
     const ready = (async () => {
         const hostTimeoutMs = allocated.reduce((timeout, { service }) => Math.max(timeout, typeof service.ready === 'object' ? service.ready.timeoutMs ?? 15_000 : 15_000), 15_000);
-        const hostTimes = await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort, () => { try {
-            return statSync(log).size;
-        }
-        catch {
-            return 0;
-        } }), ended, boot, 'the co-located host', log).catch(async (error) => {
+        const hostTimes = await untilReadyOrEnded((abort) => waitForHostReady(readyFile, boot.bootId, new Map(allocated.map(({ service, port }) => [service.id, port])), hostTimeoutMs, abort, () => startedTwins(log)), ended, boot, 'the co-located host', log).catch(async (error) => {
             if (undeadPids([child.pid]).length)
                 recordWorldStop([log], 'world.service.stop', 'up (host startup incomplete)', 'SIGTERM');
             try {
@@ -2144,6 +2281,11 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
     if (packFactsPaths.length)
         createRequire(import.meta.url)('@volter/world-core/pack-facts').extendPackFacts(packFactsPaths);
     const loaded = { path: found.path, config: materializeConfig(found.config, root) };
+    // Before any output claim or lifecycle write, every saved alias fits the actual current pack.
+    loaded.config.services = loaded.config.services.map(service => (service.type ?? 'twin') === 'twin'
+        ? withCurrentCredentialDoor(service, packFacts()[service.id]?.credentialDoor) : service);
+    assertRequiredCredentialBindings(loaded.config, found.path);
+    const required = requiredCredentialClaims(loaded.config);
     const name = options.name ?? loaded.config.id;
     const mode = options.mode ?? 'local';
     assertSafeWorldName(name);
@@ -2252,8 +2394,6 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
             // Verified teardown is independent of record shape. A fresh boot discards incomplete metadata.
             if (existsSync(instanceFile)) {
                 let prior;
-                if (options.keepState)
-                    prior = readWorldBootRecordLocked(name, root);
                 const priorRaw = readFileSync(instanceFile, 'utf8');
                 const receiptPath = join(instance, 'stopped.json');
                 const receipt = existsSync(receiptPath) ? JSON.parse(readFileSync(receiptPath, 'utf8')) : undefined;
@@ -2261,6 +2401,17 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
                     || !Number.isFinite(Date.parse(receipt.stoppedAt))) {
                     throw new Error(`World "${name}" has no verified teardown receipt for its prior instance; use its owning runtime to complete cleanup before replacement`);
                 }
+                // a resume reads the record its last boot completed; a boot that failed and was rolled back (the receipt above)
+                // completed none, and the resume writes a complete one over the kept state (architecture, the boot record)
+                let priorIncomplete = false;
+                if (options.keepState) {
+                    try {
+                        prior = readWorldBootRecordLocked(name, root);
+                    }
+                    catch {
+                        priorIncomplete = true;
+                    }
+                }
                 if (!prior) {
                     try {
                         prior = JSON.parse(priorRaw);
@@ -2284,7 +2435,7 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
                             carriedNetwork = carriedNetwork === undefined ? ceiling : intersectWorldNetwork(carriedNetwork, ceiling);
                     }
                     catch {
-                        if (options.keepState)
+                        if (options.keepState && !priorIncomplete)
                             throw new Error(`World boot record is incomplete or invalid: ${instanceFile}`);
                     }
                 }
@@ -2409,7 +2560,10 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
         const issuing = takeIssued(env);
         const unissued = new Set();
         writeProxyEnv(root, name, env);
+        const requiredCredentials = { version: 1,
+            owners: Object.fromEntries([...required].map(([name, claim]) => [name, claim.service])) };
         const worldInstance = {
+            requiredCredentials,
             name, instance: instanceToken, config: loaded.config.id, configPath: loaded.path, root, createdAt, mode,
             dirs: { instance, logs, data }, services, env, envFile, pidsFile,
             ...(envOutputClaim.contents === undefined ? {} : { previousEnvOutput: { path: envFile, sha256: createHash('sha256').update(envOutputClaim.contents).digest('hex') } }),
@@ -2492,7 +2646,8 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
                     // own sent and status says that twin's door.
                     const origin = performance.now();
                     const steps = [];
-                    const asks = await Promise.all(host.services.map(async (started) => {
+                    // A descriptor refusal still settles every owned ask before rollback can retire its custody.
+                    const asks = await Promise.allSettled(host.services.map(async (started) => {
                         const declared = colocated.find((s) => s.id === started.id);
                         if (!declared)
                             return undefined;
@@ -2500,7 +2655,7 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
                         const times = { ...(declared.package ? { twin: declared.package } : {}) };
                         steps.push({ id: started.id, queued: began, times });
                         const own = { ...before };
-                        await issueCredentials(declared, started, own, issuing, unissued, ownedPath(data, started.id), times);
+                        await issueCredentials(declared, started, own, issuing, unissued, ownedPath(data, started.id), required, !options.keepState, times);
                         return { id: started.id, ms: Math.round(performance.now() - began), own };
                     }));
                     const at = (time) => time === undefined ? '-' : `+${Math.round(time - origin)}`;
@@ -2510,7 +2665,13 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
                             .sort((left, right) => (right.times.filled ?? 0) - (left.times.filled ?? 0))
                             .map(({ id, queued, times }) => `${id}${times.twin ? ` (${times.twin})` : ''} ${at(queued)}/${at(times.door)}/${at(times.sent)}/${at(times.headers)}/${at(times.answered)}/${at(times.filled)}`).join('; ')}`);
                     const asked = [];
-                    for (const ask of asks) {
+                    const failures = [];
+                    for (const result of asks) {
+                        if (result.status === 'rejected') {
+                            failures.push(result.reason);
+                            continue;
+                        }
+                        const ask = result.value;
                         if (!ask)
                             continue;
                         for (const [key, value] of Object.entries(ask.own))
@@ -2523,6 +2684,8 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
                     }
                     if (asked.length)
                         boot.progress(`co-located twins: each asked for its credentials at once, slowest first: ${[...asked].sort((left, right) => right.ms - left.ms).slice(0, 6).map((each) => `${each.id} ${each.ms} ms`).join(', ')}; ${asked.length} asked, ${Math.max(...asked.map((each) => each.ms))} ms the longest`);
+                    if (failures.length)
+                        throw new AggregateError(failures, `World credential issuance refused: ${failures.map(reason => errorMessage(reason)).join('; ')}`);
                     writeProxyEnv(root, name, env);
                     if (colocated.length)
                         boot.progress('co-located twins: credentials issued, proxy environment written');
@@ -2537,7 +2700,7 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
                 if (services[service.id] || !ownInfrastructureService(service))
                     continue;
                 boot.progress(`${service.id}: starting beside the host (the runtime's own infrastructure)`);
-                const starting = startService(loaded.config, service, { ...env }, { root, instance, logs, data }, allocatedPorts, boot);
+                const starting = startService(loaded.config, service, { ...env }, { root, instance, logs, data }, allocatedPorts, boot, required);
                 starting.catch((error) => boot.fail(error instanceof Error ? error : new Error(errorMessage(error))));
                 early.set(service.id, starting);
             }
@@ -2586,20 +2749,22 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
                 boot.signal.throwIfAborted();
                 if (!starting)
                     boot.progress(`${service.id}: starting (${service.type ?? 'twin'})`);
-                const started = await (starting ?? startService(loaded.config, service, env, { root, instance, logs, data }, allocatedPorts, boot));
+                const started = await (starting ?? startService(loaded.config, service, env, { root, instance, logs, data }, allocatedPorts, boot, required));
                 // An early start published its teardown when it began; its record moves to its declared position.
                 if (starting)
                     delete services[service.id];
                 recordService(started);
                 recordPidsSoFar();
                 Object.assign(env, started.env);
-                await issueCredentials(service, started, env, issuing, unissued, ownedPath(data, started.id));
+                await issueCredentials(service, started, env, issuing, unissued, ownedPath(data, started.id), required, !options.keepState);
                 writeProxyEnv(root, name, env);
                 boot.progress(`${service.id}: started, its environment merged`);
             }
             if (colocatedReady)
                 await colocatedReady();
-            detachBootSignals();
+            // An abort records its reason while the final owned credential asks settle. No later service may remain
+            // to observe it, so completion itself must reject it before publishing a successful environment.
+            boot.signal.throwIfAborted();
             // a name a service of no twin in this World issues (a config edited after init) is left unset, and said
             if (issuing.size > 0)
                 process.stderr.write(`volter-world: nothing in this World issues ${[...issuing].map(([n, id]) => `${n} ($issue:${id})`).join(', ')}; left unset\n`);
@@ -2614,6 +2779,7 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
             // next service" never fires when there is no next service (TWIN-64) — the single-twin sealed
             // config test below exercises exactly this.
             attemptProxy();
+            assertRequiredCredentials(required, env, 'World environment publication');
             // Inert-injectEnv check (LibreChat blind-adoption finding): an injectEnv like AWS_TWIN_URL
             // lands in the world env, LOOKS wired, and does nothing — the injector reads no such vendor.
             // Warn loudly at `up`, when the operator is watching, instead of letting the disagreement
@@ -2621,6 +2787,12 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
             for (const warning of inertInjectEnvWarnings(loaded.config.services)) {
                 process.stderr.write(`${warning}\n`);
             }
+            // This can await the browser materializer's import. Keep boot cancellation attached through that work,
+            // and do not persist completed credential claims or publish the environment until it has finished.
+            await materializeWorldBrowserFiles(data, root, name, loaded.config.id);
+            boot.signal.throwIfAborted();
+            assertRequiredCredentials(required, env, 'World environment publication');
+            requiredCredentials.valuesSha256 = requiredCredentialValuesDigest(required);
             mkdirSync(dirname(envFile), { recursive: true });
             // Config env and discovered credentials: a file this writes is owner-only; a file the caller already made keeps
             // the mode the caller chose (a shared env file may be read under another uid).
@@ -2631,11 +2803,12 @@ async function upWorldRecorded(configId, options, abort, upStarted, lag) {
             delete worldInstance.previousEnvOutput;
             saveWorldInstance(worldInstance);
             boot.progress(`environment written: ${envFile}`);
-            await materializeWorldBrowserFiles(data, root, name, loaded.config.id);
             writePidsFromInstance(worldInstance, Object.values(worldInstance.services).map((service) => service.pid).filter((pid) => pid > 0));
             saveWorldInstance(worldInstance);
             const servicePids = [...new Set(Object.values(services).map((service) => service.pid).filter((pid) => pid > 0))];
+            boot.signal.throwIfAborted();
             handoffWorldLifecycle(root, name, servicePids);
+            detachBootSignals();
             boot.progress(`returning: the World is up; ${lag.account()}`);
             if (mode === 'share') {
                 try {
@@ -2895,6 +3068,32 @@ function killHeldSurvivorsSync(child, graceMs) {
  *    purge leaves that lock alone; its owner's finally releases it, so waiting claimants never
  *    enter through a replacement lock while the original is still held.
  */
+/** A purged World's env output outside its folder (architecture, "World environment exports are outputs"): removed with
+ *  the record that proved it the World's own, when it still holds exactly the World's exports as a single-link regular
+ *  file and no other World of the root records that path; anything else stays. */
+function purgeEnvOutput(root, name, purged, instance) {
+    const path = typeof instance.envFile === 'string' ? resolve(instance.envFile) : undefined;
+    if (!path || !relative(purged, path).startsWith('..'))
+        return;
+    const others = existsSync(worldBaseDir(root)) ? readdirSync(worldBaseDir(root)).filter((world) => world !== name && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(world)) : [];
+    const shared = others.some((world) => {
+        try {
+            return resolve(JSON.parse(readFileSync(join(instanceDir(root, world), 'instance.json'), 'utf8')).envFile) === path;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (shared)
+        return;
+    try {
+        const named = lstatSync(path);
+        if (!named.isFile() || named.nlink !== 1 || !readFileSync(path).equals(Buffer.from(envFileContents(instance.env))))
+            return;
+        rmSync(path);
+    }
+    catch { /* no output, or one the World cannot read: it stays */ }
+}
 function purgeInstanceDir(root, name) {
     assertSafeWorldName(name);
     const base = worldBaseDir(root);
@@ -3175,6 +3374,8 @@ async function downWorldClaimed(name, root, options, externalErrors = []) {
         const purged = purgeInstanceDir(resolvedRoot, name);
         if (purged && instance)
             clearBrowserFiles(instance.dirs.data, resolvedRoot);
+        if (purged && instance)
+            purgeEnvOutput(resolvedRoot, name, purged, instance);
         return { ...result, ...(externalAbandoned ? { externalAbandoned } : {}), purged };
     }));
 }
@@ -3857,6 +4058,18 @@ export async function doctorWorld(name, options = {}) {
     checks.push({ id: 'startup', ok: missingServices.length === 0, message: missingServices.length
             ? `startup incomplete: no ready service record for ${missingServices.join(', ')}; retained state requires normal teardown before resume`
             : 'declared boot services have instance records' });
+    // a vendor-backed root whose vendor rotated its refresh token while the seal failed (world-core head.ts
+    // unsealedMarkerOf): it renews only inside the process that held the new one, so a person must seal it again
+    const credentialDir = join(root, stateDirName(), 'credentials');
+    for (const file of existsSync(credentialDir) ? readdirSync(credentialDir).filter((f) => f.endsWith('.unsealed.json')).sort() : []) {
+        let said = '';
+        try {
+            const r = JSON.parse(readFileSync(join(credentialDir, file), 'utf8'));
+            said = `: ${r.field ?? 'a field'} rotated at ${r.at ?? '?'} was not sealed (${r.cause ?? 'no cause recorded'})`;
+        }
+        catch { /* the marker's presence is the finding */ }
+        checks.push({ id: `root-${file.replace(/\.unsealed\.json$/, '')}`, ok: false, message: `the root's credential lost a rotation${said}; seal it again before its process ends` });
+    }
     if (instance.lifecycle) {
         checks.push({ id: 'lifecycle', ok: hasWorldLifecycle(root, name) && existsSync(instance.lifecycle.log),
             message: `lifecycle ownership recorded; no capacity reserved; log=${instance.lifecycle.log}` });
@@ -4163,6 +4376,7 @@ export function listWorlds(root = process.cwd()) {
 }
 function worldAttachedCommandEnv(name, root, verbose = false, instance) {
     const status = instance ?? statusWorld(name, root);
+    const required = recordedRequiredCredentialClaims(status);
     const sealed = status.env.VOLTER_WORLD_MODE === 'sealed' || status.env[WORLD_NETWORK_POLICY_ENV] !== undefined;
     const baseEnv = { ...admittedEnv(stripEnvOf(status.env)), ...status.env };
     let proxyEnv = {};
@@ -4182,8 +4396,10 @@ function worldAttachedCommandEnv(name, root, verbose = false, instance) {
             throw new Error(`world "${name}" requires its network policy proxy: attachment proxy failed; refusing to run the command (${errorMessage(error)})`);
         // Keep env-only redirect if the ambient proxy cannot start.
     }
-    return { instance: status, env: withAppUrl(name, root, { ...baseEnv, ...proxyEnv, VOLTER_WORLD: name,
-            VOLTER_TWIN_INJECT_QUIET: verbose ? '0' : baseEnv.VOLTER_TWIN_INJECT_QUIET ?? '1' }) };
+    const env = withAppUrl(name, root, { ...baseEnv, ...proxyEnv, VOLTER_WORLD: name,
+        VOLTER_TWIN_INJECT_QUIET: verbose ? '0' : baseEnv.VOLTER_TWIN_INJECT_QUIET ?? '1' });
+    assertRequiredCredentials(required, env, 'command attachment');
+    return { instance: status, env, required };
 }
 /** The env with each `$app-url` value made the application URL its booter recorded. Unrecorded, the name is left
  *  unset (the application's own env files decide) and the command is told how to record it: never a guess. */
@@ -4210,10 +4426,12 @@ export function runWithWorldEnv(name, command, root = process.cwd(), options = {
     if (command.length === 0)
         throw new Error('Missing command after --');
     const attached = worldAttachedCommandEnv(name, root, options.verbose);
+    const env = { ...attached.env, ...(options.env ?? {}) };
+    assertRequiredCredentials(attached.required, env, 'SDK command environment');
     return new Promise((resolveExit) => {
         const child = spawn(command[0], command.slice(1), { windowsHide: true,
             cwd: resolve(options.cwd ?? root),
-            env: { ...attached.env, ...(options.env ?? {}) },
+            env,
             stdio: 'inherit',
         });
         const forward = (signal) => {
@@ -4290,6 +4508,8 @@ export async function attachWorld(name, command, root = process.cwd(), options =
             throw new Error(`World "${name}" is not running while attaching: none of its recorded processes is live and its own (recorded pids ${readPids(current.pidsFile).join(', ') || 'none'}; live and its own: none); ${describeWorldLifecycle(resolvedRoot, name, current.createdAt)})`);
         if (current.createdAt !== attached.instance.createdAt)
             throw new Error(`World "${name}" changed while attaching: its instance was created ${attached.instance.createdAt} when the command's environment was read and ${current.createdAt} now`);
+        // A supplied instance is a snapshot, not authority to erase the current boot's required bindings.
+        assertRequiredCredentials(recordedRequiredCredentialClaims(current), attached.env, 'registered command attachment');
         // Attaching to a World whose services died is allowed (a command may not need them), but never silent.
         for (const [id, state] of Object.entries(current.serviceStates)) {
             if (state === 'running' || state === 'external')
@@ -4472,14 +4692,21 @@ async function runWithWorldEnvLogged(name, command, root, options = {}) {
  * TLS-proxy env (HTTPS_PROXY + the CA-trust vars) is layered in by `shellWorld` once the proxy is up,
  * since starting a server is async; this pure helper stays synchronous + side-effect-free for tests. */
 export function worldShellEnv(name, root = process.cwd()) {
+    const { shell, cwd, env } = worldShellContext(name, root);
+    return { shell, cwd, env };
+}
+/** Keep the boot's required proof with the shell environment until its proxy transformations have finished. */
+function worldShellContext(name, root) {
     const status = statusWorld(name, root);
     if (!status.running)
         throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-out <path> --name ${name}`);
-    return {
-        shell: status.env.SHELL || admittedEnv(stripEnvOf(status.env)).SHELL || '/bin/bash',
-        cwd: resolve(root),
-        env: withAppUrl(name, root, { ...admittedEnv(stripEnvOf(status.env)), ...status.env, VOLTER_WORLD: name }),
-    };
+    const required = recordedRequiredCredentialClaims(status);
+    const env = withAppUrl(name, root, { ...admittedEnv(stripEnvOf(status.env)), ...status.env, VOLTER_WORLD: name });
+    assertRequiredCredentials(required, env, 'shell environment');
+    // Windows has no /bin/bash: its shell is the one ComSpec names (cmd.exe), kept by the Windows baseline (admittedEnv).
+    const inherited = admittedEnv(stripEnvOf(status.env));
+    const fallback = process.platform === 'win32' ? (inherited.ComSpec ?? inherited.COMSPEC ?? process.env.ComSpec ?? 'cmd.exe') : '/bin/bash';
+    return { shell: status.env.SHELL || inherited.SHELL || fallback, cwd: resolve(root), env, required };
 }
 /** Drop into an interactive subshell with the world active — the contained sibling of `activate`
  * (which wires your CURRENT shell + sets the `(world:<name>)` prompt marker). The subshell gets the
@@ -4488,7 +4715,7 @@ export function worldShellEnv(name, root = process.cwd()) {
  * land in the twins; `exit` restores normal (the proxy + its session CA are torn down). The CA is
  * trusted ONLY via this subshell's env — never installed system-wide. See docs/guides/route-a-cli-through-the-world.md. */
 export async function shellWorld(name, root = process.cwd()) {
-    const { shell, cwd, env } = worldShellEnv(name, root);
+    const { shell, cwd, env, required } = worldShellContext(name, root);
     const resolvedRoot = resolve(root);
     let proxy = null;
     const sealed = env.VOLTER_WORLD_MODE === 'sealed' || env[WORLD_NETWORK_POLICY_ENV] !== undefined;
@@ -4515,14 +4742,35 @@ export async function shellWorld(name, root = process.cwd()) {
             throw new Error(`world "${name}" requires its network policy proxy: openssl is unavailable; refusing to open a shell`);
         process.stderr.write(`world '${name}' active in a subshell — vendor calls hit the twins (env-only; install openssl for ambient https redirect). type 'exit' to leave.\n`);
     }
+    let failed = false;
+    let failure;
     try {
+        assertRequiredCredentials(required, env, 'interactive shell');
         const result = spawnSync(shell, ['-i'], { windowsHide: true, cwd, env, stdio: 'inherit' });
-        return result.status ?? 0;
+        if (result.error)
+            throw result.error;
+        if (result.signal)
+            throw new Error(`World shell ended by ${result.signal}`);
+        if (result.status === null)
+            throw new Error('World shell returned no exit status');
+        return result.status;
+    }
+    catch (error) {
+        failed = true;
+        failure = error;
+        throw error;
     }
     finally {
         if (proxy) {
-            await proxy.close();
-            tearDownCa(tlsDir(resolvedRoot, name));
+            try {
+                await proxy.close();
+                tearDownCa(tlsDir(resolvedRoot, name));
+            }
+            catch (cleanup) {
+                if (failed)
+                    throw new AggregateError([failure, cleanup], `World shell failed (${errorMessage(failure)}); proxy cleanup also failed (${errorMessage(cleanup)})`, { cause: failure });
+                throw cleanup;
+            }
         }
     }
 }
@@ -4844,6 +5092,7 @@ function clearWorldProxyFiles(root, name) {
  */
 export function activateScript(name, root = process.cwd()) {
     const status = statusWorld(name, root);
+    const required = recordedRequiredCredentialClaims(status);
     if (!status.running)
         throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-out <path> --name ${name}`);
     const baseEnv = status.env ?? {};
@@ -4869,6 +5118,8 @@ export function activateScript(name, root = process.cwd()) {
         // openssl missing or daemon failed — keep env-only redirect; never fabricate proxy success.
     }
     env = withAppUrl(name, root, env);
+    // Exports follow the bookkeeping assignments; the final prompt assignment is the one later value change.
+    assertRequiredCredentials(required, { ...env, PS1: `(world:${name}) ${env.PS1 ?? ''}` }, 'shell activation including its prompt');
     const keys = Object.keys(env).sort();
     const lines = [
         `# volter-world activate ${name} — run:  eval "$(volter-world activate ${name})"`,