@volter/world-runtime 2.0.0 → 2.0.2

package/src/redis-backing.ts

@@ -0,0 +1,107 @@
+// The containerless backing for a World's managed REDIS: the redis twin (@volter/twin-redis) serving Redis's
+// own protocol on the loopback port the definition declares, its keys held in the World's tree under
+// VOLTER_WORLD_DATA. Chosen by `volter-world-infra` for every redis service unless the operator forces the
+// container backing (VOLTER_WORLD_INFRA_BACKING=docker); the definition, the injected REDIS_URL and the declared
+// service contract are the same either way, as the boundary comment in infra-cli.ts promises.
+//
+// Why the twin and not a container: a World's state branches, checkpoints and rolls back as one tree, and a Redis
+// in a container is state outside it (a branch of the World would share the container's queue and cache). The
+// twin keeps each key a subject of the World (packages/twin/redis/src/redis-storage.ts). It needs nothing
+// installed: no container runtime, no redis-server binary.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { findInstalledPackage, packCli } from './catalog.ts';
+import type { InfraService } from './pglite-backing.ts';
+
+const PACKAGE = '@volter/twin-redis';
+const READY_TIMEOUT_MS = 60_000;
+
+/** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export function redisTwinCli(from: string[]): string | undefined {
+  for (const dir of from) {
+    const found = findInstalledPackage(dir, PACKAGE);
+    const cli = found === undefined ? undefined : packCli(found);
+    if (cli !== undefined && existsSync(cli)) return cli;
+  }
+  return undefined;
+}
+
+const pidPath = (dataDir: string, service: InfraService): string => join(dataDir, `redis-twin-${service.hostPort}.pid`);
+/** Where the service's keys live: the World's tree for the `redis` service, under the World's data. */
+export const redisTwinRoot = (dataDir: string): string => join(dataDir, 'redis-twin');
+
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function listening(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+    // a port that answers PING with PONG is this service; anything else is not ready (or not ours)
+    socket.once('connect', () => socket.write('PING\r\n'));
+    socket.once('data', (chunk) => { socket.destroy(); resolve(chunk.toString('latin1').startsWith('+PONG')); });
+    socket.on('error', () => resolve(false));
+    socket.on('timeout', () => { socket.destroy(); resolve(false); });
+  });
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function redisTwinUp(services: InfraService[], dataDir: string, cli: string): Promise<void> {
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service);
+    if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort)) continue;
+    // a port that already answers is another process's (another World's twin, a redis-server): serving there would
+    // hand this World's app someone else's keys, so it is refused, never taken as ready
+    if (await listening(service.hostPort)) throw new Error(`port ${service.hostPort} already serves Redis for another process`);
+    const root = redisTwinRoot(dataDir);
+    mkdirSync(root, { recursive: true });
+    const log = join(dataDir, `redis-twin-${service.hostPort}.log`);
+    mkdirSync(dirname(log), { recursive: true });
+    // a real fd, not a pipe: the server outlives this process untethered
+    const logFd = openSync(log, 'a');
+    // the runtime this runs on: Bun runs the pack's TypeScript as it is; Node (volter-world-infra's shebang) needs
+    // type transformation, not only stripping (the kernel declares constructor parameter properties)
+    const runtime = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
+    const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+    closeSync(logFd);
+    writeFileSync(pidFile, `${child.pid}\n`);
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    while (!(await listening(service.hostPort)) || !alive(child.pid!)) {
+      if (!alive(child.pid!)) throw new Error(`redis exited before serving — see ${log}`);
+      if (Date.now() > deadline) throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+      await sleep(200);
+    }
+  }
+}
+
+export async function redisTwinStatus(services: InfraService[], dataDir: string): Promise<number> {
+  let ready = 0;
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service);
+    if (!existsSync(pidFile)) continue;
+    if (alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort)) ready += 1;
+  }
+  return ready;
+}
+
+export async function redisTwinDown(services: InfraService[], dataDir: string): Promise<void> {
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service);
+    if (!existsSync(pidFile)) continue;
+    const pid = Number(readFileSync(pidFile, 'utf8').trim());
+    if (alive(pid)) {
+      try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+      const deadline = Date.now() + 5000;
+      while (alive(pid) && Date.now() < deadline) await sleep(100);
+      if (alive(pid)) { try { process.kill(pid, 'SIGKILL'); } catch { /* raced */ } }
+    }
+    rmSync(pidFile, { force: true });
+  }
+}

package/src/root.ts

@@ -16,6 +16,7 @@ import {
 import { loadWorldConfig, writeWorldConfig } from './configs.ts';
 import { changesetReadiness, collectObservations, type Observation, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding, userKek, type DeployReport, type ObserveReport } from '@volter/world-core';
 import { findWorldChangeset, listWorldChangesets } from './changeset.ts';
+import { importModule } from './import-module.ts';
 import { statusWorld } from './runtime.ts';
 import { findInstalledPackage, twinPackageName } from './catalog.ts';
 import type { WorldConfig } from './schema.ts';
@@ -120,7 +121,7 @@ async function packModule(vendor: string, from: string): Promise<Record<string,
   const registered = getPack(vendor);
   if (registered) return { pack: registered };
   const entry = packEntryPath(vendor, from);
-  return entry ? ((await import(entry)) as Record<string, unknown>) : null;
+  return entry ? await importModule(entry) : null;
 }
 /** The pack's module itself, installed beside the World or in this checkout: its every export (a
  *  mirror's shell and client), where the registry holds only the descriptor. */
@@ -137,8 +138,32 @@ export async function packMirrorExports(vendor: string, from: string): Promise<R
   if (!entry) return null;
   const dir = dirname(entry);
   const file = existsSync(dir) ? readdirSync(dir).find((f) => /-mirror-ui\.(ts|js)$/.test(f) && !f.includes('.test.')) : undefined;
-  return (await import(file ? join(dir, file) : entry)) as Record<string, unknown>;
+  return importModule(file ? join(dir, file) : entry);
 }
+/** A pack's mirror as the pack builds it (`<vendor>MirrorHtml`, `build<Vendor>MirrorClient`,
+ *  `<vendor>MirrorStyles`), found the way a World finds the pack; null when the pack has none. The
+ *  client builds at serve under Bun and is served prebuilt under Node, by the pack's own builder. */
+export type PackMirror = { html: () => string; client: () => Promise<string>; styles?: () => Promise<string>; /** the account and a credential its screens sign in with (`<vendor>MirrorSignIn`): the account found in the twin's
+   *  state at `root`, the credential minted for it through the twin's own doors (`twin`), never a stored one read back */
+  signIn?: (as: string, ctx: MirrorSignInContext) => Promise<{ account: string; token: string } | null> | { account: string; token: string } | null };
+/** What a pack's `<vendor>MirrorSignIn` is given: the twin's state root (to find the account) and the twin's own doors
+ *  (to mint a credential for it, as the World's seed does through `/_twin/…`). */
+export type MirrorSignInContext = { root: string; twin: (path: string, init?: RequestInit) => Promise<Response> };
+export async function packMirror(vendor: string, from: string): Promise<PackMirror | null> {
+  const installed = findInstalledPackage(from, twinPackageName(vendor));
+  const dir = installed ?? resolve(import.meta.dir, '..', '..', 'twin', vendor);
+  // the pack's mirror module, as the hosted build reads it (its index need not re-export every builder)
+  const src = join(dir, 'src');
+  const file = existsSync(src) ? readdirSync(src).find((f) => f.endsWith('-mirror-ui.ts')) : undefined;
+  const entry = file ? join(src, file) : installed ? packEntry(installed) : join(src, 'index.ts');
+  if (!existsSync(entry)) return null;
+  const mod = await importModule(entry);
+  const pick = (re: RegExp): ((...a: unknown[]) => unknown) | undefined => { const k = Object.keys(mod).find((key) => re.test(key) && typeof mod[key] === 'function'); return k ? mod[k] as (...a: unknown[]) => unknown : undefined; };
+  const html = pick(/^\w+MirrorHtml$/); const client = pick(/^build\w+MirrorClient$/); const styles = pick(/^\w+MirrorStyles$/); const signIn = pick(/^\w+MirrorSignIn$/);
+  if (!html || !client) return null;
+  return { html: html as () => string, client: client as () => Promise<string>, ...(styles ? { styles: styles as () => Promise<string> } : {}), ...(signIn ? { signIn: signIn as PackMirror['signIn'] } : {}) };
+}
+
 /** The real state system's adapters for a vendor: registered with the pack (protocol 2), else the
  *  pack's anchored exports (protocol 1: `perform<Name>Action`, `sync<Name>FromRemote`). */
 export type IngestAdapter = (request: Request, ctx: { root?: string; secret?: string }) => Response | Promise<Response>;

package/src/run-task.ts

@@ -13,7 +13,7 @@ export type RunTaskReply = { result: RunTaskResult } | { error: string };
  * The task process is outside the caller's POSIX process group and owns boot through teardown. */
 export function superviseWorldRun(configId: string, command: string[], options: RunWorldOptions): Promise<RunTaskResult> {
   return new Promise((done, reject) => {
-    const child = spawn(process.execPath, [siblingScript(import.meta.url, 'run-task-worker')], {
+    const child = spawn(process.execPath, [siblingScript(import.meta.url, 'run-task-worker')], { windowsHide: true,
       cwd: process.cwd(), env: process.env, detached: process.platform !== 'win32',
       stdio: ['inherit', 'inherit', 'inherit', 'ipc'], serialization: 'json',
     });

package/src/runtime.ts

@@ -17,7 +17,7 @@ import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { packFacts } from './pack-facts.ts';
 import { describeServiceEnd, readServiceEnd, serviceOutput } from './service-exit.ts';
 import { Socket } from 'node:net';
-import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
+import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
 import type { PlanReviewRecord } from '@volter/world-core';
 import { loadWorldConfig } from './configs.ts';
 import { createWorldNetworkPolicy, WORLD_NETWORK_POLICY_ENV } from '@volter/world-core/network-policy';
@@ -63,7 +63,7 @@ function spawnRecorded(serviceId: string, command: string, args: string[], cwd:
   const recorderEnv: NodeJS.ProcessEnv = { ...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], {
+  const child = spawn(process.execPath, [siblingScript(import.meta.url, 'service-recorder'), command, ...args], { windowsHide: true,
     cwd,
     env: recorderEnv,
     detached: true,
@@ -662,7 +662,7 @@ function processStarts(pids: number[]): Map<number, string> {
     }
     return starts;
   }
-  const result = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', pids.join(',')], { encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } });
+  const result = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', pids.join(',')], { windowsHide: true, encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } });
   for (const line of (result.stdout ?? '').split('\n')) {
     const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
     if (match) starts.set(Number(match[1]), match[2]!);
@@ -798,11 +798,11 @@ async function runExternalCommand(
   command: string[], cwd: string, serviceId: string, phase: string,
   env: NodeJS.ProcessEnv = process.env, abort?: AbortSignal, timeoutMs = 60_000,
 ): Promise<{ stdout: string; stderr: string }> {
-  const [bin, ...args] = command;
+  const [bin, ...args] = ownCommand(command);
   if (!bin) throw new Error(`External service "${serviceId}": ${phase} command is empty`);
   if (!commandExists(bin)) throw new Error(`External service "${serviceId}": \`${bin}\` not found on PATH (the ${phase} command's tool is not installed)`);
   abort?.throwIfAborted();
-  const child = spawn(bin, args, { cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
+  const child = spawn(bin, args, { windowsHide: true, cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
   const lifetime = commandLifetime(child, abort, true);
   let stdout = ''; let stderr = ''; let failure: Error | undefined;
   const collect = (chunk: Buffer, out: boolean) => {
@@ -832,7 +832,7 @@ async function runExternalUp(
   logPath: string,
   abort?: AbortSignal,
 ): Promise<string> {
-  const [bin, ...args] = command;
+  const [bin, ...args] = ownCommand(command);
   if (!bin) throw new Error(`External service "${serviceId}": up command is empty`);
   if (!commandExists(bin)) {
     throw new Error(`External service "${serviceId}": \`${bin}\` not found on PATH (the up command's tool is not installed)`);
@@ -843,7 +843,7 @@ async function runExternalUp(
   const chunks: string[] = [];
   try {
     abort?.throwIfAborted();
-    const child = spawn(bin, args, { cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawn(bin, args, { windowsHide: true, cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
     const lifetime = commandLifetime(child, abort, true);
     let failure: unknown;
     child.on('error', error => { failure = error; });
@@ -1456,7 +1456,8 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       VOLTER_WORLD_MODE: mode,
       VOLTER_WORLD_CONFIG: loaded.path,
       VOLTER_WORLD_INSTANCE: instanceFile,
-      VOLTER_WORLD_DATA: data,
+      // every service's root is `<data>/<service id>`; the kernel finds another pack's store across them (A3, ownerStoreRoots)
+      [WORLD_DATA_ENV]: data,
       // the live env file this `up` writes: what a service that runs apps elsewhere (world-machine's guest) carries there
       VOLTER_WORLD_ENV_FILE: envFile,
       // THE WORLD CLOCK: every service stamps from this file via the kernel's worldNow();
@@ -2190,12 +2191,28 @@ function sleep(ms: number): Promise<void> {
 
 function commandExists(command: string): boolean {
   // Pass the live env so PATH reflects the current process (some runtimes snapshot env otherwise).
-  const result = spawnSync('which', [command], { stdio: 'ignore', env: process.env });
-  return result.status === 0;
+  return OWN_COMMANDS[command] !== undefined || onPath(command);
+}
+
+/** A lifecycle command naming this runtime's own bin (`volter-world-infra`, which `init` names in every managed
+ *  infrastructure's lifecycle) runs this runtime's own script with the executable running it, when nothing on PATH
+ *  answers the name: a bare `volter-world down` (no runner that put node_modules/.bin on PATH) failed "not found on
+ *  PATH" and left the infrastructure up. Only the name is mapped — no directory joins PATH — and a same-named
+ *  command on PATH still wins, as before. */
+const OWN_COMMANDS: Record<string, string> = { 'volter-world-infra': 'infra-cli' };
+export function ownCommand(command: string[]): string[] {
+  const [bin, ...args] = command;
+  const stem = bin === undefined ? undefined : OWN_COMMANDS[bin];
+  if (stem === undefined || onPath(bin!)) return command;
+  return [process.execPath, siblingScript(import.meta.url, stem), ...args];
+}
+
+function onPath(command: string): boolean {
+  return spawnSync('which', [command], { windowsHide: true, stdio: 'ignore', env: process.env }).status === 0;
 }
 
 function resolveWithPublicDns(hostname: string): string | undefined {
-  const result = spawnSync('dig', ['+short', '@1.1.1.1', hostname, 'A'], {
+  const result = spawnSync('dig', ['+short', '@1.1.1.1', hostname, 'A'], { windowsHide: true,
     encoding: 'utf8',
   });
   if (result.status !== 0) return undefined;
@@ -2235,7 +2252,7 @@ async function verifyPublicUrl(
     || (isIP(normalizedHostname) === 4 && normalizedHostname.split('.')[0] === '127');
   if (local) {
     const target = publicHealthUrl(publicUrl, path);
-    const result = spawnSync('curl', ['--noproxy', '*', '-sS', '-o', '-', '-w', '\n%{http_code}', '--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))), target], { encoding: 'utf8' });
+    const result = spawnSync('curl', ['--noproxy', '*', '-sS', '-o', '-', '-w', '\n%{http_code}', '--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))), target], { windowsHide: true, encoding: 'utf8' });
     const separator = result.stdout.lastIndexOf('\n');
     const body = separator >= 0 ? result.stdout.slice(0, separator).trim() : result.stdout.trim();
     const status = Number(separator >= 0 ? result.stdout.slice(separator + 1).trim() : '0');
@@ -2269,7 +2286,7 @@ async function verifyPublicUrl(
         `${hostname}:443:${resolvedIp}`,
         target,
       ],
-      { encoding: 'utf8' },
+      { windowsHide: true, encoding: 'utf8' },
     );
     if (result.status === 0) {
       const output = result.stdout;
@@ -2331,7 +2348,7 @@ async function shareWorldReserved(name: string, options: ShareWorldOptions): Pro
   // Each spawned tunnel owns one log generation. Truncating before spawn prevents a repeated
   // share from accepting the previous process's URL handshake as the new process's endpoint.
   const out = openPrivateLog(log, 'w');
-  const child = spawn(tunnel.command, tunnel.args, {
+  const child = spawn(tunnel.command, tunnel.args, { windowsHide: true,
     cwd: root,
     env: process.env,
     detached: true,
@@ -2505,7 +2522,8 @@ async function probeExternalOnce(
     if (!commandExists(ready.command)) {
       return { ok: false, message: `readiness command \`${ready.command}\` not found on PATH` };
     }
-    const result = spawnSync(ready.command, ready.args ?? [], {
+    const [probeBin, ...probeArgs] = ownCommand([ready.command, ...(ready.args ?? [])]);
+    const result = spawnSync(probeBin!, probeArgs, { windowsHide: true,
       cwd, encoding: 'utf8', env, timeout: DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024,
     });
     if (result.status === 0) return { ok: true, message: 'probe ok (command)' };
@@ -2860,7 +2878,7 @@ export function runWithWorldEnv(name: string, command: string[], root = process.
   if (command.length === 0) throw new Error('Missing command after --');
   const attached = worldAttachedCommandEnv(name, root, options.verbose);
   return new Promise((resolveExit) => {
-    const child = spawn(command[0]!, command.slice(1), {
+    const child = spawn(command[0]!, command.slice(1), { windowsHide: true,
       cwd: resolve(options.cwd ?? root),
       env: attached.env,
       stdio: 'inherit',
@@ -2933,7 +2951,7 @@ export async function attachWorld(name: string, command: string[], root = proces
   let retired = true;
   try {
     return await new Promise<number>((done, reject) => {
-      const child = spawn(command[0]!, command.slice(1), { cwd: resolve(options.cwd ?? root), env: attached.env, stdio: 'inherit', detached: commandProcessGroup });
+      const child = spawn(command[0]!, command.slice(1), { windowsHide: true, cwd: resolve(options.cwd ?? root), env: attached.env, stdio: 'inherit', detached: commandProcessGroup });
       const lifetime = commandLifetime(child);
       let failure: unknown;
       record.consumerPid = child.pid;
@@ -3014,7 +3032,7 @@ async function runWithWorldEnvLogged(name: string, command: string[], root: stri
     let spawnError: string | undefined;
     let child;
     try {
-      child = spawn(command[0]!, command.slice(1), {
+      child = spawn(command[0]!, command.slice(1), { windowsHide: true,
         cwd: resolve(options.cwd ?? root),
         env: attached.env,
         stdio: ['inherit', 'pipe', 'pipe'],
@@ -3096,7 +3114,7 @@ export async function shellWorld(name: string, root = process.cwd()): Promise<nu
     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`);
   }
   try {
-    const result = spawnSync(shell, ['-i'], { cwd, env, stdio: 'inherit' });
+    const result = spawnSync(shell, ['-i'], { windowsHide: true, cwd, env, stdio: 'inherit' });
     return result.status ?? 0;
   } finally {
     if (proxy) {
@@ -3189,7 +3207,7 @@ function startProxyDaemonOwned(name: string, root: string, caCertPath: string, e
     mkdirSync(dirname(proxyLogPath(root, name)), { recursive: true, mode: 0o700 });
     const proxyOut = openPrivateLog(proxyLogPath(root, name), 'a');
     try {
-      child = spawn(process.execPath, [proxyDaemonEntry(), name, '--root', root, ...(envFile ? [`--env-file=${envFile}`] : [])], {
+      child = spawn(process.execPath, [proxyDaemonEntry(), name, '--root', root, ...(envFile ? [`--env-file=${envFile}`] : [])], { windowsHide: true,
         cwd: root, env: process.env, detached: true, stdio: ['ignore', proxyOut, proxyOut],
       });
     } finally { closeSync(proxyOut); }

package/src/schema.ts

@@ -173,6 +173,9 @@ export type WorldServiceConfig = {
    * to loopback services directly while presenting a disguised world to the app/user.
    */
   controlPlane?: boolean;
+  /** The account a vendor's own screens (its mirror) open signed in as: its handle, username or email, which the pack
+   *  resolves against the accounts this World holds (`<vendor>MirrorSignIn`). Nothing secret is written here. */
+  signIn?: { as: string };
   injectEnv?: string;
   /**
    * Additional env vars exported into the generated world env after this service starts.
@@ -704,7 +707,7 @@ export function assertWorldSelection(value: unknown, path: string): asserts valu
 
 function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
   if (!record(value)) throw new Error(`World service must be an object in ${path}`);
-  assertKeys(value, ['id', 'type', 'description', 'source', 'execution', 'endpoint', 'bindings', 'root'], `Service ${String(value.id ?? '')}`, path, true);
+  assertKeys(value, ['id', 'type', 'description', 'source', 'execution', 'endpoint', 'bindings', 'root', 'signIn'], `Service ${String(value.id ?? '')}`, path, true);
   const source = value.source === undefined ? {} : value.source;
   const execution = value.execution === undefined ? {} : value.execution;
   const endpoint = value.endpoint === undefined ? {} : value.endpoint;
@@ -721,6 +724,11 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
   assertKeys(environment, ['values'], 'service.execution.environment', path);
   if (typeof value.id !== 'string' || value.id === '') throw new Error(`World service must define string id in ${path}`);
   if (value.description !== undefined && typeof value.description !== 'string') throw new Error(`Service "${value.id}" description must be a string in ${path}`);
+  if (value.signIn !== undefined) {
+    if (!record(value.signIn)) throw new Error(`Service "${value.id}" signIn must be an object in ${path}`);
+    assertKeys(value.signIn, ['as'], `Service "${value.id}" signIn`, path);
+    if (typeof value.signIn.as !== 'string' || value.signIn.as.trim() === '') throw new Error(`Service "${value.id}" signIn.as must name an account (a handle, username or email) in ${path}`);
+  }
   if (value.description !== undefined && value['//'] !== undefined) throw new Error(`Service "${value.id}" must not set both description and // in ${path}`);
   if (execution.cwd !== undefined && typeof execution.cwd !== 'string') throw new Error(`Service "${value.id}" execution.cwd must be a string in ${path}`);
   if (execution.controlPlane !== undefined && typeof execution.controlPlane !== 'boolean') throw new Error(`Service "${value.id}" execution.controlPlane must be a boolean in ${path}`);
@@ -770,6 +778,7 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
     ...(bindings.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: bindings.injectEnvTemplates as Record<string, string> }),
     ...(bindings.cliRedirect === undefined ? {} : { cliRedirect: bindings.cliRedirect as Record<string, string> }),
     ...(value.root === undefined ? {} : { root: value.root as WorldServiceConfig['root'] }),
+    ...(value.signIn === undefined ? {} : { signIn: { as: (value.signIn as { as: string }).as } }),
     ...(external === undefined ? {} : { external }),
   };
   if (type !== 'external' && bindings.discover !== undefined) throw new Error(`Service "${legacy.id}" bindings.discover is only valid for external services in ${path}`);
@@ -889,6 +898,7 @@ function serviceToV2(service: WorldServiceConfig): Record<string, unknown> {
     ...(Object.keys(endpoint).length ? { endpoint } : {}),
     ...(Object.keys(bindings).length ? { bindings } : {}),
     ...(service.root === undefined ? {} : { root: service.root }),
+    ...(service.signIn === undefined ? {} : { signIn: service.signIn }),
   };
 }