@volter/twin-world 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-world",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",

package/src/resources.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statfsSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statfsSync, statSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir, hostname, totalmem } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -13,6 +13,7 @@ export const DEFAULT_WORLD_RESOURCES: WorldResourceRequirements = {
 
 export type WorldResourceClaim = {
   world: string;
+  root?: string;
   identity: string;
   ownerPid: number;
   holderPids: number[];
@@ -77,7 +78,17 @@ function writePrivate(path: string, contents: string): void {
   writeFileSync(path, contents, { mode: 0o600 });
 }
 
-function capacity(root: string, claims: WorldResourceClaim[]): WorldResourceRequirements {
+/** Resolve old claims without rewriting them. Unknown locations stay charged on every
+ * filesystem rather than silently allowing a reservation we cannot locate. */
+function sharesStorage(root: string, claim: WorldResourceClaim): boolean {
+  try {
+    const claimRoot = claim.root ?? resolve(dirname(claim.log), '../../..');
+    if (claimIdentity(claimRoot, claim.world) !== claim.identity) return true;
+    return statSync(claimRoot).dev === statSync(root).dev;
+  } catch { return true; }
+}
+
+export function worldResourceCapacity(root: string, claims: WorldResourceClaim[]): WorldResourceRequirements {
   const fs = statfsSync(resolve(root));
   const diskFreeMiB = Math.floor((Number(fs.bavail) * Number(fs.bsize)) / MIB);
   const memoryTotalMiB = Math.floor(totalmem() / MIB);
@@ -85,7 +96,8 @@ function capacity(root: string, claims: WorldResourceClaim[]): WorldResourceRequ
   const diskTotalMiB = Math.floor((Number(fs.blocks) * Number(fs.bsize)) / MIB);
   const diskSafetyMiB = Math.max(512, Math.min(2048, Math.floor(diskTotalMiB * 0.05)));
   const reservedMemoryMiB = claims.reduce((sum, claim) => sum + claim.resources.memoryMiB, 0);
-  const reservedDiskMiB = claims.reduce((sum, claim) => sum + claim.resources.writableStorageMiB, 0);
+  const reservedDiskMiB = claims.filter((claim) => sharesStorage(root, claim))
+    .reduce((sum, claim) => sum + claim.resources.writableStorageMiB, 0);
   return {
     memoryMiB: Math.max(0, memoryTotalMiB - memorySafetyMiB - reservedMemoryMiB),
     writableStorageMiB: Math.max(0, diskFreeMiB - diskSafetyMiB - reservedDiskMiB),
@@ -106,7 +118,7 @@ export function claimWorldResources(root: string, world: string, requested: Worl
   return withFileLock(join(dir, 'claims.lock'), () => {
     const identity = claimIdentity(root, world);
     const claims = liveClaims(identity);
-    const available = capacity(root, claims);
+    const available = worldResourceCapacity(root, claims);
     const shortages: string[] = [];
     if (requested.memoryMiB > available.memoryMiB) shortages.push(`memory requires ${requested.memoryMiB} MiB, ${available.memoryMiB} MiB available`);
     if (requested.writableStorageMiB > available.writableStorageMiB) {
@@ -120,6 +132,7 @@ export function claimWorldResources(root: string, world: string, requested: Worl
     }
     const claim: WorldResourceClaim = {
       world,
+      root: resolve(root),
       identity,
       ownerPid: process.pid,
       holderPids: [],

package/src/runtime.ts

@@ -329,6 +329,24 @@ const CONTROL_PLANE_EGRESS_ENV = [
   'all_proxy',
 ];
 
+/** The process's environment as the world admits it: what `stripEnv` names stays outside. */
+export function admittedEnv(strip: string[] | undefined, env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const out: Record<string, string> = {};
+  const rules = (strip ?? []).map((s): { prefix: string } | { name: string } => (s.endsWith('*') ? { prefix: s.slice(0, -1) } : { name: s }));
+  for (const [k, v] of Object.entries(env)) {
+    if (v === undefined) continue;
+    if (rules.some((r) => ('prefix' in r ? k.startsWith(r.prefix) : k === r.name))) continue;
+    out[k] = v;
+  }
+  return out;
+}
+// The strip list of a running world, for `env`/`attach`: its config is the one the instance recorded.
+function stripEnvOf(instanceEnv: Record<string, string>): string[] | undefined {
+  const path = instanceEnv.VOLTER_WORLD_CONFIG;
+  if (!path) return undefined;
+  try { return (JSON.parse(readFileSync(path, 'utf8')) as { stripEnv?: string[] }).stripEnv; } catch { return undefined; }
+}
+
 function serviceProcessEnv(
   config: WorldConfig,
   service: WorldServiceConfig,
@@ -336,7 +354,7 @@ function serviceProcessEnv(
   port: number,
 ): Record<string, string> {
   const env: Record<string, string> = {
-    ...process.env,
+    ...admittedEnv(config.stripEnv),
     ...(config.env ?? {}),
     ...worldEnv,
     PORT: String(port),
@@ -645,6 +663,7 @@ async function startExternalService(
   service: WorldServiceConfig,
   paths: { root: string; logs: string },
   worldEnv: Record<string, string>,
+  stripEnv?: string[],
 ): Promise<WorldServiceInstance> {
   const external = service.external;
   if (!external) throw new Error(`External service "${service.id}" is missing its external config`);
@@ -653,7 +672,7 @@ async function startExternalService(
   // External commands see the accumulated world env (process.env + earlier services' discovered/
   // injected vars), so a later external can consume an earlier service's connection info.
   const env: NodeJS.ProcessEnv = {
-    ...process.env,
+    ...admittedEnv(stripEnv),
     ...worldEnv,
     ...(service.env ?? {}),
     VOLTER_WORLD_SERVICE_ID: service.id,
@@ -737,7 +756,7 @@ async function startService(
   worldEnv: Record<string, string>,
   paths: { root: string; instance: string; logs: string; data: string },
 ): Promise<WorldServiceInstance> {
-  if (service.type === 'external') return startExternalService(service, paths, worldEnv);
+  if (service.type === 'external') return startExternalService(service, paths, worldEnv, config.stripEnv);
   if (!service.command) throw new Error(`Service "${service.id}" must define command`);
   const port = service.port === undefined || service.port === 'auto' ? await allocatePort() : service.port;
   const serviceDataDir = join(paths.data, service.id);
@@ -862,7 +881,7 @@ async function startColocatedServices(
   const out = openPrivateLog(log, 'a');
   // The host is world infrastructure, not an app process — same egress hygiene as controlPlane
   // services (no injector preload, no ambient proxy): its twins SERVE, they don't call vendors.
-  const env: Record<string, string> = { ...process.env as Record<string, string>, ...(config.env ?? {}), ...worldEnv };
+  const env: Record<string, string> = { ...admittedEnv(config.stripEnv), ...(config.env ?? {}), ...worldEnv };
   for (const key of CONTROL_PLANE_EGRESS_ENV) delete env[key];
   const child = spawn(process.execPath, args, {
     cwd: paths.root,
@@ -2106,7 +2125,7 @@ function worldAttachedCommandEnv(name: string, root: string): { instance: Return
     if (sealed) throw new Error(`sealed world "${name}": attachment proxy failed; refusing to run the command (${error instanceof Error ? error.message : String(error)})`);
     // Keep env-only redirect if the ambient proxy cannot start.
   }
-  return { instance: status, env: { ...process.env, ...status.env, ...proxyEnv } };
+  return { instance: status, env: { ...admittedEnv(stripEnvOf(status.env)), ...status.env, ...proxyEnv } };
 }
 
 export function runWithWorldEnv(name: string, command: string[], root = process.cwd(), options: { cwd?: string } = {}): number {

package/src/schema.ts

@@ -207,6 +207,11 @@ export type WorldConfig = {
    * `isolation` option overrides it per boot. */
   isolation?: WorldIsolation;
   env?: Record<string, string>;
+  /** Variables of the process that runs the world which never enter it — a name, or a prefix ending in `*`
+   * (`HERMES_*`). The world seals what leaves over the wire; this seals what comes in through the environment:
+   * whatever steered the outer process (an agent's worker pinning its board and run) must not steer what runs
+   * inside, whose state is the world's own. Applied to every service the world starts and to `env`/`attach`. */
+  stripEnv?: string[];
   services: WorldServiceConfig[];
   share?: WorldShareConfig;
   actors?: Record<string, unknown>;
@@ -431,6 +436,9 @@ export function assertWorldConfig(value: unknown, path: string): WorldConfig {
       }
     }
   }
+  if (config.stripEnv !== undefined && (!Array.isArray(config.stripEnv) || config.stripEnv.some((s) => typeof s !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*\*?$/.test(s)))) {
+    throw new Error(`World config stripEnv must be a list of variable names or prefixes ending in * in ${path}`);
+  }
   const ids = new Set<string>();
   for (const service of config.services as Partial<WorldServiceConfig>[]) {
     if (!service || typeof service !== 'object') throw new Error(`Invalid service in ${path}`);