@volter/world-runtime 3.0.37 → 3.0.39

package/src/mongodb-backing.ts

@@ -0,0 +1,55 @@
+// MongoDB's own server behind the existing declared-infrastructure lifecycle. Process ownership,
+// logs, stopped-state copying and teardown stay in pglite-backing.ts and branch.ts, as for Postgres.
+import type { HostLaunch, InfraService } from './pglite-backing.ts';
+
+/** PATH is the binary contract, as for the native PostgreSQL example and LiveKit. No acquisition at boot. */
+export function mongodbArgv(service: InfraService, data: string): string[] {
+  return ['mongod', '--bind_ip', '127.0.0.1', '--port', String(service.hostPort), '--dbpath', data,
+    ...(service.replicaSet ? ['--replSet', service.replicaSet] : [])];
+}
+
+/** MongoDB's structured record comes from this child, not a listener already holding the port. */
+export function mongodbListening(log: string, port: number): boolean {
+  return log.split('\n').some((line) => {
+    try {
+      const record = JSON.parse(line);
+      return record.id === 23016 && record.msg === 'Waiting for connections' && record.attr?.port === port;
+    } catch { return false; } // Non-JSON log lines are not the structured readiness record.
+  });
+}
+
+/** Ping the server; initialize only an explicitly declared one-member set and await its primary. */
+export async function mongodbReady(service: InfraService, launch: HostLaunch, deadline: number, initialize = true): Promise<void> {
+  const { MongoClient } = await import('mongodb');
+  // Use the infrastructure lifecycle's remaining readiness budget rather than another fixed limit.
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) throw new Error('World-managed MongoDB readiness deadline elapsed');
+  const client = new MongoClient(`mongodb://127.0.0.1:${service.hostPort}`, {
+    directConnection: true, timeoutMS: remaining,
+  });
+  try {
+    await client.connect();
+    const admin = client.db('admin');
+    await admin.command({ ping: 1 });
+    if (!service.replicaSet) return;
+    let config;
+    try {
+      config = (await admin.command({ replSetGetConfig: 1 })).config;
+    } catch (error) {
+      // MongoDB's NotYetInitialized; any other refusal remains its own error.
+      if ((error as { code?: number }).code !== 94 || !initialize) throw error;
+      config = { _id: service.replicaSet, members: [{ _id: 0, host: `127.0.0.1:${service.hostPort}` }] };
+      await admin.command({ replSetInitiate: config });
+    }
+    if (config._id !== service.replicaSet || config.members?.length !== 1 || config.members[0].host !== `127.0.0.1:${service.hostPort}`) {
+      throw new Error('World-managed MongoDB replica-set name or member address differs from the declared service; refusing reconfiguration');
+    }
+    while (!(await admin.command({ hello: 1 })).isWritablePrimary) {
+      launch.signal?.throwIfAborted();
+      if (Date.now() >= deadline) throw new Error('World-managed MongoDB did not elect its single-node primary before the readiness deadline');
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+  } finally {
+    await client.close();
+  }
+}

package/src/native-postgres-backing.ts

@@ -0,0 +1,329 @@
+// World-managed multi-session PostgreSQL. The declaration, data, process and teardown
+// belong to the infrastructure service; a recipe never operates postgres itself.
+import { spawn, type ChildProcess } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { connect } from 'node:net';
+import { join, resolve } from 'node:path';
+import { commandLifetime, COMMAND_GRACE_MS, CommandRetirementError } from './command-lifetime.ts';
+import { survivingOwnedGroups } from './process-groups.ts';
+import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess, type SpawnIdentity } from './process-receipt.ts';
+import { signalChild, childIdentity } from './process-signal.mjs';
+import { errorMessage } from './error-message.ts';
+import type { HostLaunch, InfraService } from './pglite-backing.ts';
+
+interface Ownership { pid: number; data: string; port: number; binary: string }
+interface Started { child: ChildProcess; owned: Ownership; closed: boolean; identity?: SpawnIdentity; birth?: Promise<SpawnIdentity | undefined>; error?: Error }
+const starts = new Map<string, Started>();
+const wait = (ms: number) => new Promise<void>(done => setTimeout(done, ms));
+const recordPath = (root: string) => join(root, 'native-postgres.owner.json');
+const startingPath = (root: string) => join(root, 'native-postgres.starting.json');
+// Reuse pglite-backing.ts's 60-second managed readiness ceiling for the WHOLE
+// startup, including initdb/psql/createdb. The conditioned native lifecycle walk
+// measured native boot was 2487.76 ms (initdb 793.79 ms, psql 149.18 ms,
+// createdb 81.13 ms) with empty PostgreSQL 17.9 state, Node 24.21, shared host,
+// no app server, ae14857 plus this change; full command/fault shim source and
+// output are in cookbook/calcom/output/native-lifetime.txt.
+const READY_TIMEOUT_MS = 60_000;
+// Retirement uses the existing command grace twice (grace, then confirmation),
+// within the former native backing's 10-second shutdown budget. The same walk
+// records cancellation, graceful shutdown and forced escalation; no new wall-clock limit.
+function ownership(root: string) {
+  const records = [recordPath(root), startingPath(root)].map(file => readProcessReceipt(file, text => {
+    const row = JSON.parse(text) as Ownership;
+    if (!Number.isInteger(row?.pid) || row.pid < 0 || row.data !== resolve(root, 'native-postgres-data')
+      || !Number.isInteger(row.port) || row.port < 1 || row.port > 65535 || typeof row.binary !== 'string') {
+      throw new Error('Invalid native postgres ownership');
+    }
+    return row;
+  }));
+  const spawn = readSpawnReceipt(recordPath(root));
+  const values = records.flatMap(row => row.value ? [row.value] : []);
+  const errors = [...records, spawn].flatMap(row => row.error ? [row.error] : []);
+  if (values.length > 1 && values.some(row => JSON.stringify(row) !== JSON.stringify(values[0]))) {
+    errors.push(new Error('native postgres has conflicting ownership receipts; ownership uncertain'));
+  }
+  return { present: records.some(row => row.present) || spawn.present, held: values.find(row => row.pid === spawn.value?.pid) ?? values[0], identity: spawn.value, values, errors };
+}
+function verifyOwner(held: Ownership): void {
+  const lines = readFileSync(join(held.data, 'postmaster.pid'), 'utf8').split('\n');
+  if (Number(lines[0]) !== held.pid || resolve(lines[1]!) !== held.data || Number(lines[3]) !== held.port) {
+    throw new Error('native postgres ownership does not match the cluster; teardown refused');
+  }
+}
+const liveGroup = (pid: number) => pid > 0 && survivingOwnedGroups([pid]).length > 0;
+function removeReceipts(root: string): void {
+  // Called only after confirmed retirement. Do not parse a damaged receipt while clearing it.
+  const errors: unknown[] = [];
+  for (const file of [recordPath(root), startingPath(root)]) {
+    try { rmSync(file, { force: true }); } catch (error) { errors.push(error); }
+  }
+  // Keep the independent identity while ANY damaged readiness record still needs cleanup.
+  if (!errors.length) {
+    try { rmSync(spawnReceiptPath(recordPath(root)), { force: true }); } catch (error) { errors.push(error); }
+  }
+  if (errors.length) throw new AggregateError(errors, 'native postgres retired but receipt cleanup failed');
+}
+async function retireIdentity(identity: SpawnIdentity): Promise<void> {
+  const { pid } = identity;
+  for (const signal of ['SIGINT', 'SIGKILL'] as const) {
+    if (!liveGroup(pid)) return;
+    await signalOwnedProcess(identity, signal, true);
+    const deadline = Date.now() + COMMAND_GRACE_MS;
+    while (liveGroup(pid) && Date.now() < deadline) await wait(20);
+  }
+  if (liveGroup(pid)) throw new Error(`native postgres group ${pid} retirement unconfirmed; ownership retained`);
+}
+/** A retained child is ownership even before postmaster.pid or the ready receipt exists. */
+async function retireStarted(started: Started): Promise<void> {
+  const { child, owned } = started;
+  child.ref();
+  for (const signal of ['SIGINT', 'SIGKILL'] as const) {
+    if (started.closed && !liveGroup(owned.pid)) return;
+    if (owned.pid > 0 && !signalChild(child, signal, true) && liveGroup(owned.pid)) {
+      await signalOwnedProcess(started.identity ?? await started.birth, signal, true);
+    }
+    const deadline = Date.now() + COMMAND_GRACE_MS;
+    while (Date.now() < deadline) {
+      if (started.closed && !liveGroup(owned.pid)) return;
+      await wait(20);
+    }
+  }
+  throw new Error(`native postgres child ${owned.pid} retirement unconfirmed; ownership retained`);
+}
+async function listening(port: number, deadline: number, signal?: AbortSignal): Promise<boolean> {
+  signal?.throwIfAborted();
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) throw new Error('native postgres readiness deadline elapsed');
+  return new Promise((done, fail) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: Math.min(1000, remaining) });
+    const settle = (value?: boolean, error?: unknown) => {
+      socket.destroy(); signal?.removeEventListener('abort', abort);
+      if (error) fail(error); else done(value!);
+    };
+    const abort = () => settle(undefined, signal!.reason);
+    signal?.addEventListener('abort', abort, { once: true });
+    socket.once('connect', () => settle(true));
+    socket.once('error', () => settle(false));
+    socket.once('timeout', () => settle(false));
+    if (signal?.aborted) abort();
+  });
+}
+/** Every helper joins exit and its private group, including spawn errors and abort. */
+async function tool(command: string, args: string[], env: NodeJS.ProcessEnv, deadline: number, root: string, signal?: AbortSignal): Promise<string> {
+  signal?.throwIfAborted();
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) throw new Error(`native postgres readiness deadline elapsed before ${command}`);
+  const child = spawn(command, args, { env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  const lifetime = commandLifetime(child, signal);
+  let output = ''; let errorOutput = ''; let spawnError: Error | undefined; let timedOut = false; let failure: unknown;
+  child.stdout?.on('data', chunk => { output += chunk; });
+  child.stderr?.on('data', chunk => { errorOutput += chunk; });
+  child.on('error', error => { spawnError = error; });
+  const timer = setTimeout(() => { timedOut = true; lifetime.cancel('SIGTERM'); }, remaining);
+  const receipt = join(root, `native-postgres-tool-${child.pid ?? 'unspawned'}.json`);
+  try {
+    try {
+      const birth = await lifetime.identity;
+      if (birth?.start) {
+        publishProcessReceipt(spawnReceiptPath(receipt), JSON.stringify(birth) + '\n');
+        publishProcessReceipt(receipt, JSON.stringify({ pid: child.pid, command }) + '\n');
+      } else if (child.pid && liveGroup(child.pid)) throw new Error('native postgres helper birth capture failed; retiring held child');
+    } catch (error) {
+      lifetime.cancel('SIGTERM');
+      try { await lifetime.finish(); }
+      catch (cleanup) { throw new AggregateError([error, cleanup], 'native postgres helper publication and retirement failed'); }
+      throw error;
+    }
+    const result = await lifetime.finish();
+    signal?.throwIfAborted();
+    if (timedOut) throw new Error(`native postgres readiness deadline elapsed during ${command}`);
+    if (spawnError) throw spawnError;
+    if (result.code !== 0 || lifetime.forwarded) throw new Error(`${command} exited ${result.code}/${result.signal}: ${errorOutput.trim()}`);
+    return output;
+  } catch (error) {
+    failure = error;
+    if (error instanceof CommandRetirementError) {
+      error.message += `; native postgres helper ${command}, pid ${child.pid}, receipt ${receipt}`;
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    // The lifetime has awaited closed output and vanished descendants. Unknown
+    // retirement retains this receipt and the World's rollback evidence.
+    if (!child.pid || !liveGroup(child.pid)) {
+      try { rmSync(receipt, { force: true }); rmSync(spawnReceiptPath(receipt), { force: true }); }
+      catch (cleanup) {
+        if (failure !== undefined) throw new AggregateError([failure, cleanup], 'native postgres helper failed and receipt cleanup failed');
+        throw cleanup;
+      }
+    }
+  }
+}
+// init emits literal environment values in its fixed compose shape. Unknown forms
+// are refused rather than interpreted as shell, substitutions or another config.
+function settings(definition: string): { user: string; database: string } {
+  const values: Record<string, string> = {};
+  let postgres = false;
+  for (const line of definition.split('\n')) {
+    const service = line.match(/^  ([a-z][a-z0-9_-]*):$/);
+    if (service) postgres = service[1] === 'postgres';
+    const field = postgres && line.match(/^      POSTGRES_(USER|DB): (.+)$/);
+    if (field) {
+      const value = field[2]!;
+      values[field[1]!] = value.startsWith('"') ? JSON.parse(value) : value;
+    }
+  }
+  const user = values.USER || 'postgres';
+  const database = values.DB || user;
+  if ([user, database].some(value => typeof value !== 'string' || !value || /[\r\n\0$]/.test(value))) {
+    throw new Error('native postgres requires literal POSTGRES_USER and POSTGRES_DB');
+  }
+  return { user, database };
+}
+
+export async function nativePostgresUp(services: InfraService[], root: string, definition: string, launch: HostLaunch): Promise<void> {
+  if (services.length !== 1 || services[0]!.kind !== 'postgres') throw new Error('native postgres requires one declared postgres service');
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  const env: NodeJS.ProcessEnv = { ...(launch.env ?? process.env), LC_ALL: launch.env?.LC_ALL || 'C' };
+  const binaries = env.VOLTER_WORLD_POSTGRES_BIN;
+  if (!binaries) throw new Error('native postgres requires VOLTER_WORLD_POSTGRES_BIN (an installed PostgreSQL tool directory)');
+  for (const name of ['initdb', 'postgres', 'createdb', 'psql']) {
+    if (!existsSync(join(binaries, name))) throw new Error(`native postgres tool is missing: ${join(binaries, name)}`);
+  }
+  const previous = ownership(root);
+  if (previous.present || starts.has(root)) {
+    const pid = previous.identity?.pid ?? previous.held?.pid;
+    if (!previous.errors.length && !existsSync(startingPath(root)) && previous.held && pid && liveGroup(pid)) {
+      if (previous.identity) await verifySpawnIdentity(previous.identity);
+      else verifyOwner(previous.held);
+      throw new Error('native postgres is already running; stop this World before booting again');
+    }
+    await nativePostgresDown(root);
+  }
+  await retireTools(root);
+  const service = services[0]!;
+  if (await listening(service.hostPort, deadline, launch.signal)) throw new Error(`native postgres port ${service.hostPort} is already occupied`);
+  const data = resolve(root, 'native-postgres-data');
+  mkdirSync(data, { recursive: true, mode: 0o700 });
+  const { user, database } = settings(definition);
+  if (!existsSync(join(data, 'PG_VERSION'))) {
+    await tool(join(binaries, 'initdb'), ['-D', data, `--username=${user}`, '--auth=trust', '--no-locale', '--encoding=UTF8'], env, deadline, root, launch.signal);
+  }
+  launch.signal?.throwIfAborted();
+  const binary = join(binaries, 'postgres');
+  const log = join(root, 'native-postgres.log');
+  // Reserve durable startup evidence before spawning. A ready-receipt publication
+  // failure still leaves this receipt and the live handle for rollback.
+  const current: Ownership = { pid: 0, data, port: service.hostPort, binary };
+  publishProcessReceipt(startingPath(root), JSON.stringify(current) + '\n');
+  let started: Started | undefined;
+  try {
+    const fd = openSync(log, 'a');
+    let child: ChildProcess;
+    try {
+      child = spawn(binary, ['-D', data, '-h', '127.0.0.1', '-p', String(service.hostPort), '-k', ''], { env, detached: true, stdio: ['ignore', fd, fd] });
+      current.pid = child.pid ?? 0;
+      started = { child, owned: current, closed: false };
+      const observed = started;
+      child.on('error', error => { observed.error = error; });
+      child.once('close', () => { observed.closed = true; });
+      starts.set(root, started);
+      started.birth = childIdentity(child);
+    } finally { closeSync(fd); }
+    // The immutable spawn identity precedes either mutable ownership receipt.
+    started.identity = await started.birth;
+    if (child.pid && !started.identity?.start) throw new Error('native postgres birth capture failed; retiring held child');
+    if (child.pid) publishProcessReceipt(spawnReceiptPath(recordPath(root)), JSON.stringify(started.identity) + '\n');
+    publishProcessReceipt(startingPath(root), JSON.stringify(current) + '\n');
+    if (started.error) throw started.error;
+    if (!child.pid) throw new Error('native postgres spawn failed');
+    publishProcessReceipt(recordPath(root), JSON.stringify(current) + '\n');
+    for (;;) {
+      launch.signal?.throwIfAborted();
+      if (started.error) throw started.error;
+      if (child.exitCode !== null || child.signalCode !== null || started.closed) throw new Error(`native postgres exited before readiness; see ${log}`);
+      if (Date.now() >= deadline) throw new Error(`native postgres did not become ready; see ${log}`);
+      if (existsSync(join(data, 'postmaster.pid'))) {
+        verifyOwner(current);
+        const lines = readFileSync(join(data, 'postmaster.pid'), 'utf8').split('\n');
+        if (lines[7]?.trim() === 'ready' && await listening(service.hostPort, deadline, launch.signal)) break;
+      }
+      await wait(100);
+    }
+    if (database !== 'postgres') {
+      const sql = `SELECT 1 FROM pg_database WHERE datname = '${database.replaceAll("'", "''")}'`;
+      const output = await tool(join(binaries, 'psql'), ['-h', '127.0.0.1', '-p', String(service.hostPort), '-U', user, '-d', 'postgres', '-tAc', sql], env, deadline, root, launch.signal);
+      if (!output.trim()) await tool(join(binaries, 'createdb'), ['-h', '127.0.0.1', '-p', String(service.hostPort), '-U', user, '--', database], env, deadline, root, launch.signal);
+    }
+    launch.signal?.throwIfAborted();
+    if (child.exitCode !== null || child.signalCode !== null) throw new Error(`native postgres exited during readiness; see ${log}`);
+    rmSync(startingPath(root));
+    child.unref();
+  } catch (error) {
+    // The original publication/readiness failure survives every cleanup failure.
+    const failures: unknown[] = [error];
+    try {
+      if (started) await retireStarted(started);
+      removeReceipts(root);
+      starts.delete(root);
+    } catch (cleanup) { failures.push(cleanup); }
+    if (failures.length > 1) throw new AggregateError(failures, `native postgres startup and retirement failed; receipts retained`);
+    throw error;
+  }
+}
+export async function nativePostgresStatus(root: string): Promise<boolean> {
+  const state = ownership(root);
+  if (state.errors.length) throw new AggregateError(state.errors, 'native postgres ownership uncertain; retry down');
+  if (!state.held || !liveGroup(state.held.pid)) return false;
+  if (state.identity) await verifySpawnIdentity(state.identity);
+  verifyOwner(state.held);
+  return listening(state.held.port, Date.now() + READY_TIMEOUT_MS);
+}
+
+async function retireTools(root: string): Promise<void> {
+  if (!existsSync(root)) return;
+  const receipts = new Set(readdirSync(root).filter(name => /^native-postgres-tool-.*\.json(?:\.spawn\.json)?$/.test(name))
+    .map(name => name.endsWith('.spawn.json') ? name.slice(0, -'.spawn.json'.length) : name));
+  for (const file of receipts) {
+    const receipt = join(root, file);
+    const identity = readSpawnReceipt(receipt);
+    const recorded = readProcessReceipt(receipt, text => {
+      const row = JSON.parse(text);
+      if (!Number.isInteger(row.pid) || row.pid <= 0) throw new Error('Invalid helper PID');
+      return row as { pid: number };
+    });
+    const pid = identity.value?.pid ?? recorded.value?.pid;
+    if (!pid) throw new AggregateError([identity.error, recorded.error].filter(Boolean), `native postgres helper ownership uncertain; retained ${receipt}`);
+    if (liveGroup(pid)) {
+      if (!identity.value) throw new Error(`native postgres helper ${pid} has no verified spawn identity; ownership retained`);
+      await verifySpawnIdentity(identity.value);
+      await retireIdentity(identity.value);
+    }
+    rmSync(receipt, { force: true }); rmSync(spawnReceiptPath(receipt), { force: true });
+  }
+}
+export async function nativePostgresDown(root: string): Promise<void> {
+  const started = starts.get(root);
+  const state = ownership(root);
+  if (state.errors.length) process.stderr.write(`${errorMessage(new AggregateError(state.errors, 'native postgres ownership uncertain; retrying retirement through established identity'))}\n`);
+  if (started) {
+    await retireStarted(started);
+  } else if (state.identity) {
+    if (liveGroup(state.identity.pid)) {
+      await verifySpawnIdentity(state.identity);
+      await retireIdentity(state.identity);
+    }
+  } else if (state.held && state.held.pid > 0) {
+    if (liveGroup(state.held.pid)) {
+      throw new Error('native postgres spawn identity missing; retirement refused; receipts retained');
+    }
+  } else if (state.present) {
+    throw new AggregateError(state.errors, 'native postgres ownership uncertain; no established process identity; receipts retained');
+  }
+  if (state.values.some(row => row.pid > 0 && liveGroup(row.pid))) {
+    throw new AggregateError(state.errors, 'native postgres receipt still names a live or uncertain group; ownership retained');
+  }
+  removeReceipts(root);
+  starts.delete(root);
+  await retireTools(root);
+}

package/src/origin.ts

@@ -1,3 +1,4 @@
+import { errorMessage } from './error-message.ts';
 import { captureHistory, historyDigest, originHead, publishOriginHistory, type HistoryLayout, type HistoryReference, readHistoryView, historyLength, worldPaths } from '@volter/world-core/runtime';
 // `volter world clone` and `fetch` — a world's ORIGIN is another world, served (docs/concepts/the-model.md
 // #a-branch-is-a-position-not-a-copy: a clone is a branch whose parent is at a URL): its whole log per twin is this world's PARENT. `clone` records the origin
@@ -137,7 +138,7 @@ export async function fetchFromOrigin(name: string, options: FetchOptions): Prom
       const { path: configPath, config } = loadWorldConfig(instance.configPath, root);
       const named = isPathRemote(origin.url) ? origin.url : `${origin.url}/${origin.namespace}`;
       if (config.remotes?.origin !== named) writeWorldConfig(configPath, { ...config, remotes: { ...(config.remotes ?? {}), origin: named } });
-    } catch (error) { console.error(`[origin] ${name}: the remote was not named in its config: ${(error as Error).message}`); }
+    } catch (error) { console.error(`[origin] ${name}: the remote was not named in its config: ${errorMessage(error)}`); }
   }
   return { world: name, origin, full: options.full ?? false, appended, behind, snapshots };
 }

package/src/owned-path.ts

@@ -0,0 +1,32 @@
+import { lstatSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+function realBase(path: string): string {
+  // Init may plan a base that has not been created. Resolve its nearest existing ancestor, preserving the suffix.
+  if (lstatSync(path, { throwIfNoEntry: false })) return realpathSync(path);
+  return resolve(realBase(dirname(path)), basename(path));
+}
+
+/** Check against a previously resolved owner, so re-reading a changed base cannot move the containment boundary. */
+export function assertOwnedRealPath(realOwner: string, path: string): void {
+  const rel = relative(realOwner, realpathSync(path));
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error('Invalid World-owned path');
+}
+
+/** A name-derived destination stays within its owner; inspect existing components before any write. */
+export function ownedPath(base: string, name: string): string {
+  const lexicalRoot = resolve(base), rel = relative(lexicalRoot, resolve(lexicalRoot, name));
+  const invalid = (): never => { throw new Error('Invalid World-owned path'); };
+  if (isAbsolute(name) || !rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) invalid();
+  // The operator chooses the base (including a symlink to another volume); only the name-derived join is guarded.
+  const root = realBase(lexicalRoot), components: string[] = [];
+  let component = root;
+  for (const part of rel.split(sep)) { component = resolve(component, part); components.push(component); }
+  for (const [index, component] of components.entries()) {
+    const stat = lstatSync(component, { throwIfNoEntry: false });
+    if (stat && (stat.isSymbolicLink() || (index < components.length - 1 && !stat.isDirectory()))) invalid();
+    if (stat) assertOwnedRealPath(root, component);
+  }
+  // Preserve the operator's spelling: init plans later compare destinations relative to that same configured base.
+  return resolve(lexicalRoot, rel);
+}

package/src/pack-facts.ts

@@ -14,6 +14,7 @@ import factsDocument from '@volter/world-core/generated/pack-facts.json' with {
 export type PackAdoption = { sdks?: string[]; pypi?: string[]; scopes?: string[]; envStems?: string[]; worldIds?: string[]; tools?: Array<{ package: string; usage: 'build' | 'deployment' }>; configFiles?: Array<{ file: string; usage: 'application' | 'build' | 'deployment'; when?: string }> };
 export type PackFacts = {
   serverBacking?: { command: string };
+  maxRequestBodySize?: number;
   /** Existing descriptor transport, compiled into the same artifact as endpoint/adoption facts. */
   transport?: string;
   adoption?: PackAdoption;