@volter/world-runtime 2.0.0

package/src/schema.ts

@@ -0,0 +1,922 @@
+import { normalizeWorldNetwork, type WorldNetwork } from '@volter/world-core/network-policy';
+
+export type WorldServiceType = 'twin' | 'process' | 'external';
+export type WorldMode = 'local' | 'share' | 'sealed';
+
+/**
+ * Process model for the world's twins — a DIAL, not a binary (see src/host.ts):
+ *  - 'process'   (default): one OS process per service — the existing spawn path. Strongest
+ *                 service-to-service process separation (not a network or Machine boundary),
+ *                 isolation; the oracle, and the only choice for share/sealed/hosted worlds
+ *                 (enforced by `upWorld` — see runtime.ts, not just documented here; TWIN-67).
+ *  - 'colocated': every service declaring `colocate` runs in ONE `volter-world-host` child
+ *                 sharing a single event loop + heap (host 'shared' mode). Lightest.
+ *  - 'worker'   : same single host child, but one Worker thread per twin — own event loop +
+ *                 heap, independently isolated (a crashed twin stays dead — never respawned),
+ *                 still one OS process to the orchestrator.
+ * Services without `colocate` (and all 'external' services) always use the spawn path.
+ */
+export type WorldIsolation = 'process' | 'colocated' | 'worker';
+export const WORLD_SCHEMA_VERSION = 2 as const;
+export const WORLD_USAGES = ['application', 'dependencies', 'build', 'deployment'] as const;
+export type WorldUsage = typeof WORLD_USAGES[number];
+export type WorldSelectionSelector = { usage?: WorldUsage; vendor?: string };
+export type WorldSelection = { include: WorldSelectionSelector[]; exclude: WorldSelectionSelector[] };
+
+/** The format-2 document is normalized to WorldConfig before runtime code sees it. */
+export type WorldManifestV2 = {
+  schemaVersion: 2;
+  metadata: { id: string; description?: string };
+  discovery?: { selection?: WorldSelection };
+  services: unknown[];
+  runtime?: { isolation?: WorldIsolation; environment?: { values?: Record<string, string>; strip?: string[] }; network?: WorldNetwork };
+  serving?: { mode?: 'app' | 'bare'; name?: string; share?: WorldShareConfig };
+  remotes?: Record<string, string>;
+  scenario?: { actors?: Record<string, unknown>; fixtures?: Record<string, unknown> };
+  provenance?: { catalog?: { sha: string; protocol?: string } };
+};
+
+/** The env value `init` writes for a name whose fake must be minted per instance (a service-account JSON with a real throwaway key). */
+export const MINT_ENV = '$mint';
+export type WorldShareProvider = 'cloudflare-quick' | 'command';
+
+/**
+ * EXTERNAL (self-managed) service type.
+ *
+ * Most services in a world are owned by us: we spawn `command`, assign a PORT, and inject a
+ * `*_URL` (types 'twin' and 'process'). An EXTERNAL service is the opposite: its lifecycle is
+ * DELEGATED to an external tool that runs the REAL software (e.g. Supabase's `supabase start`,
+ * LocalStack, MinIO, Mailpit). We do NOT assign it a port — the external tool manages its own
+ * ports — and its connection URL + keys are DISCOVERED from the tool's own output, then injected
+ * into the world env exactly like a twin's `injectEnv`.
+ *
+ * The runtime is deliberately VENDOR-AGNOSTIC: it never branches on a tool's identity. Everything
+ * the runtime needs (how to start, how to probe readiness, how to read connection info, how to
+ * stop) is declared in the config below. Supabase is just an EXAMPLE config (see
+ * `configs/supabase-world.json`, which mixes a Supabase external service with stripe/github twins);
+ * there is zero Supabase-specific code in `runtime.ts`.
+ *
+ * Lifecycle on world `up`:
+ *   1. run `up` (start the external stack),
+ *   2. wait for `readyWhen` (Docker-backed externals take seconds to boot),
+ *   3. run `status` (or reuse `up` output) to obtain connection info,
+ *   4. apply `discover` mappings → inject env vars into the world env (and world.env/instance.json).
+ * On world teardown (`down`): run `down` for each external service.
+ *
+ * Robustness contract: if the external tool is missing on PATH, or `up`/`status` fail, or
+ * readiness times out, world `up` fails LOUDLY with the captured output — never a fake success.
+ */
+
+/** Source of the text a `discover` mapping reads from: the `status` output (default) or `up` output. */
+export type WorldExternalDiscoverSource = 'status' | 'up';
+
+/**
+ * One declarative env-var extraction. Exactly one of `jsonPath` or `pattern` must be set.
+ *  - `jsonPath`: dotted path into the JSON the source command printed (e.g. `API_URL`, `db.url`,
+ *    `services.0.endpoint`). Numeric segments index into arrays.
+ *  - `pattern`: a regex applied to the raw source text; capture group `value` (or group 1) is used.
+ * The resolved value is injected as the env var named by `as`.
+ */
+export type WorldExternalDiscover = {
+  as: string;
+  source?: WorldExternalDiscoverSource;
+  jsonPath?: string;
+  pattern?: string;
+};
+
+/**
+ * Optional readiness probe, polled after `up` until it passes or `timeoutMs` elapses. Exactly one of:
+ *  - `command`/`args`: a command that must exit 0,
+ *  - `httpUrl`: an HTTP(S) URL that must return a 2xx/3xx response,
+ *  - `stdoutMatch`: a regex that must appear in the `up` command's captured stdout/stderr log.
+ */
+export type WorldExternalReadyWhen = {
+  command?: string;
+  args?: string[];
+  httpUrl?: string;
+  stdoutMatch?: string;
+  timeoutMs?: number;
+  intervalMs?: number;
+};
+
+export type WorldExternalServiceConfig = {
+  up: string[];
+  status?: string[];
+  down: string[];
+  discover?: WorldExternalDiscover[];
+  readyWhen?: WorldExternalReadyWhen;
+};
+
+export type WorldShareServiceConfig = {
+  id: string;
+  verifyPath?: string | false;
+};
+
+export type WorldShareConfig = {
+  provider?: WorldShareProvider;
+  /** Custom tunnel command (provider 'command'). `{url}` in args is replaced with the
+   *  service's local URL. When set, provider defaults to 'command'. */
+  command?: string;
+  args?: string[];
+  /** Lifecycle, independent of provider type. Cloudflare Quick Tunnels are always ephemeral;
+   * custom providers state the same fact explicitly when teardown retires the URL. */
+  ephemeral?: boolean;
+  services: WorldShareServiceConfig[];
+};
+
+/** Deprecated metadata from runtime v2. Not reserved or enforced by local runtime v3. */
+export type WorldResourceRequirements = {
+  memoryMiB: number;
+  writableStorageMiB: number;
+};
+
+export type WorldServiceConfig = {
+  /**
+   * A free-text NOTE about this service, ignored by the runtime — JSON has no comments, and a
+   * generated config needs somewhere to say WHY it is shaped the way it is. `volter-world init`
+   * writes the wiring rationale here (which `*_TWIN_URL` the injector actually reads, or why a
+   * vendor has no endpoint env at all), so an operator reading the emitted file is not left to
+   * reverse-engineer the decision. Hand-written configs may use it freely.
+   */
+  '//'?: string;
+  id: string;
+  type?: WorldServiceType;
+  /**
+   * The twin PACKAGE this service boots from (`@volter/twin-<vendor>`), resolved from the world
+   * root at boot by node's own `node_modules` walk (docs/concepts/worlds.md#the-config-and-the-running-world).
+   * With `package` set, `command` and the entry are derived (`bun <pkg>/src/cli.ts serve`), `args`
+   * are appended after `serve`, and a `colocate` without a `module` boots `<pkg>/src/index.ts`.
+   * A config written inside this checkout names checkout-relative paths instead.
+   */
+  package?: string;
+  /** Required for 'twin'/'process' services without `package`. Omitted for 'external' (the tool's `up`/`down` hold the commands). */
+  command?: string;
+  args?: string[];
+  /** Optional working directory for this process. Relative paths resolve from the world root. */
+  cwd?: string;
+  port?: number | 'auto';
+  /**
+   * Required whenever `port` is a literal number (schema-enforced, TWIN-66): stable configs are
+   * meant to be instance-agnostic (see docs/concepts/worlds.md's config/instance split), so a numeric port is the
+   * declared EXCEPTION, not the norm — it must record WHY the port can't be `'auto'`-allocated
+   * (e.g. a consumer needs a pre-known issuer/callback URL baked in elsewhere). Ignored/forbidden
+   * when `port` is `'auto'` or unset.
+   */
+  portReason?: string;
+  env?: Record<string, string>;
+  /**
+   * Marks this service as world infrastructure rather than an app/vendor process.
+   *
+   * Control-plane services still receive the world's declared/injected service env, but they do not
+   * inherit app-side egress machinery (`NODE_OPTIONS` injector preload or ambient HTTP(S) proxy env).
+   * Use this for helper proxies, seeders, local asset servers, or orchestration daemons that must talk
+   * to loopback services directly while presenting a disguised world to the app/user.
+   */
+  controlPlane?: boolean;
+  injectEnv?: string;
+  /**
+   * Additional env vars exported into the generated world env after this service starts.
+   * Templates are resolved against the owned loopback service:
+   *   - `${url}` / `${httpUrl}` → http://127.0.0.1:<port>
+   *   - `${host}` → 127.0.0.1
+   *   - `${port}` → the allocated port
+   * This is the process-service equivalent of external.discover for services whose client-facing
+   * endpoint is not the default http URL, e.g. a real local LiveKit server needing ws://.
+   */
+  injectEnvTemplates?: Record<string, string>;
+  /** THE ROOT (contract "The model"): the vendor's real account behind this twin on a shared world —
+   *  its API (or the one resource the account is), the deploy policy, how it is refreshed. Key-free;
+   *  the credential is sealed under `.volter/credentials/`. Written by `volter twin <vendor> root`. */
+  root?: { url: string; deploy: 'auto' | 'gated' | 'hold'; refresh?: { every?: string; webhook?: boolean }; scope?: string };
+  rootArg?: string | false;
+  portArg?: string | false;
+  /**
+   * Optional per-CLI redirect: env vars exported into the world env so the vendor's REAL CLI
+   * (`aws`, `gh`, `sentry-cli`, …) talks to THIS service instead of the real vendor. The literal
+   * `${url}` is substituted with the service's resolved URL — e.g. `{ "AWS_ENDPOINT_URL": "${url}" }`.
+   * Honored by `volter-world env/run/activate` (it flows into the world env like `injectEnv`). The
+   * pure-env path for CLIs that accept an http endpoint; CLIs needing https use the proxy (Phase 2).
+   * See docs/guides/route-a-cli-through-the-world.md.
+   */
+  cliRedirect?: Record<string, string>;
+  /**
+   * Readiness probe for a 'process'/'twin' service. The default (or `'tcp'`) waits only until the
+   * port accepts TCP connections — but a process can bind its port BEFORE it is actually serving
+   * (Vite, an HTTP app warming up a DB pool). Pass a probe object to make `up` wait until the
+   * service truly serves, so `up` returning means "ready" (no post-up re-polling needed):
+   *   - `{ httpUrl }`  — poll until 2xx/3xx. `${url}`/`${host}`/`${port}` resolve to the allocated port.
+   *   - `{ command, args }` — poll until the command exits 0 (runs with the service env, incl. `PORT`).
+   *   - `{ stdoutMatch }` — poll until a regex matches the service's stdout/stderr log.
+   * 'external' services use `external.readyWhen` instead.
+   */
+  ready?: 'tcp' | WorldExternalReadyWhen;
+  /**
+   * Extra Node preloads for a 'process'/'twin' service, appended as `--require <module>` to the
+   * world's NODE_OPTIONS (which already loads `@volter/world-core/inject`). Use this to add an app-local
+   * preload (e.g. an in-process sandbox) WITHOUT losing the injector. Setting `service.env.NODE_OPTIONS`
+   * directly REPLACES the world default (dropping the injector) — only do that if you truly mean to.
+   */
+  preload?: string[];
+  /** Required when `type === 'external'`: the self-managed lifecycle (up/status/down/discover/readyWhen). */
+  external?: WorldExternalServiceConfig;
+  /**
+   * Names this twin's in-process server factory so it can run CO-LOCATED inside the single
+   * `volter-world-host` child when the world's isolation is 'colocated'/'worker'. `module` is
+   * anything `import()` resolves — a package name (`@volter/twin-stripe`) or a file path
+   * (relative paths resolve from the world root); `export` names a
+   * `({port,root,readOnly}) => {port,stop}` factory (every pack ships one, e.g.
+   * `createStripeTwinServer`). Ignored under 'process' isolation (the default), where
+   * `command` is spawned as usual — declare BOTH to let one config serve every dial setting.
+   */
+  colocate?: { /** required unless `package` names the twin */ module?: string; export: string; /** the handlers file a scenario-carrying twin loads (R2a) */ scenarioPath?: string };
+  /** R17 — the external lockfile: pins the twin package's own version (its package.json). `up`
+   *  refuses a mounted package that does not satisfy it, naming both; `init` emits it from the
+   *  catalog the world was born against. Exact version or `^major.minor` range. */
+  version?: string;
+};
+
+export type WorldConfig = {
+  id: string;
+  /** Real external origins; omitted preserves legacy routing, [] explicitly closes egress. */
+  network?: WorldNetwork;
+  /** Internal normalized source format and saved discovery selection. */
+  manifestVersion?: 1 | 2;
+  selection?: WorldSelection;
+  description?: string;
+  /** A world with no app in front of it (`init --bare <org>/<world>`): a shared world for a team, or a
+   *  world standing in for a vendor. `name` is how it is served: `/<org>/<world>/…`. */
+  bare?: { name: string };
+  /** The worlds this one pushes to and fetches from, by name (`volter remote add`); `origin` is the
+   *  default. A URL a served world printed, or a path to a world's directory. Tokens are never here. */
+  remotes?: Record<string, string>;
+  /** Peak capacity for this World. Conservative defaults are used when omitted for compatibility;
+   * resource-intensive Worlds should always declare both values explicitly. */
+  resources?: WorldResourceRequirements;
+  /** Default process model for this world's twins ('process' when omitted). `upWorld`'s
+   * `isolation` option overrides it per boot. */
+  isolation?: WorldIsolation;
+  /** The world's env. A value of `$mint` (MINT_ENV) is minted at boot — a structurally valid
+   *  throwaway credential for that name (fixture-env) — and lives only in the live env file, so a
+   *  committed config never holds key material. */
+  env?: Record<string, string>;
+  /** Variables of the process that runs the world which never enter it — a name, a prefix ending in `*`, or `*` for all inherited variables
+   * (`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>;
+  fixtures?: Record<string, unknown>;
+  /** The birth stamp (R18), written by `init`: the catalog sha the world was born against and
+   *  the platform protocol major it was born under. `up` reads the major back and refuses a
+   *  world this platform can no longer read by construction (two majors back, or newer). */
+  catalog?: { sha: string; protocol?: string };
+};
+
+export type WorldServiceInstance = {
+  id: string;
+  type: WorldServiceType;
+  command: string[];
+  /** R17 — what the host actually mounted for a colocated twin: the package version read from
+   *  the module's own package.json, and the protocol standing (R16) it declared. */
+  resolvedVersion?: string;
+  protocol?: { declared?: string; major: number; standing: string };
+  /** Absent for 'external' services — we do not assign them a port. */
+  port?: number;
+  /** Absent for 'external' services — their URL is discovered into env vars, not assigned by us. */
+  url?: string;
+  /** 0 for 'external' services — they have no process we own (the external tool manages it). */
+  pid: number;
+  log: string;
+  env: Record<string, string>;
+  /**
+   * Set only for 'external' services. Records the `down` command so teardown can stop the
+   * self-managed stack, plus the cwd it was started from (the marker that the stack was brought up).
+   */
+  external?: {
+    down: string[];
+    cwd: string;
+    /** Env discovered during `up` (the injected vars), passed to the `down` command so teardown can
+     * reference connection info it needs (e.g. a stop command that takes the discovered URL). */
+    discoveredEnv?: Record<string, string>;
+  };
+  publicUrl?: string;
+  publicUrlEphemeral?: boolean;
+  publicReady?: boolean;
+  publicVerification?: {
+    path: string;
+    checkedAt: string;
+    hostname: string;
+    resolvedIp?: string;
+    status?: number;
+    body?: string;
+  };
+  tunnel?: {
+    provider: 'cloudflare-quick' | 'command';
+    pid: number;
+    log: string;
+    command: string[];
+    startedAt: string;
+  };
+  /**
+   * Set for a 'worker'-isolated co-located twin whose host-managed Worker thread crashed and
+   * was given up on (never respawned — still discoverable: the port answers nothing, but the
+   * dead twin is no longer silent). Not written directly by the runtime process: the co-located
+   * host CHILD records it in a sidecar file (`host-gaveup.json`, same instance dir) since it
+   * cannot safely rewrite instance.json out from under the parent; `readWorldInstance` merges
+   * the sidecar in here so every reader sees it as if it were in instance.json all along.
+   */
+  workerGaveUp?: {
+    /** ISO timestamp of the give-up. */
+    at: string;
+    /** Exits observed for this twin under the no-respawn contract (always 1 — field kept for
+     *  record compatibility with the sidecar/schema shape). */
+    exits: number;
+    detail: string;
+  };
+};
+
+/** Durable outcome of the most recent foreground consumer launched by `volter-world run`.
+ * Deliberately excludes argv and environment values: both can contain credentials. */
+export type WorldRunOutcome = {
+  state: 'completed';
+  runnerPid: number;
+  startedAt: string;
+  finishedAt: string;
+  exitCode: number;
+  log: string;
+  signal?: NodeJS.Signals;
+  error?: string;
+};
+
+export type WorldRunRecord = WorldRunOutcome | {
+  state: 'running';
+  runnerPid: number;
+  consumerPid?: number;
+  startedAt: string;
+  log: string;
+} | {
+  state: 'abrupt';
+  runnerPid: number;
+  consumerPid?: number;
+  startedAt: string;
+  observedAt: string;
+  log: string;
+  error: string;
+};
+
+export type WorldInstance = {
+  name: string;
+  /** Snapshot of the selection in force when this instance booted. */
+  selection?: WorldSelection;
+  config: string;
+  configPath: string;
+  root: string;
+  createdAt: string;
+  mode: WorldMode;
+  dirs: {
+    instance: string;
+    logs: string;
+    data: string;
+  };
+  services: Record<string, WorldServiceInstance>;
+  env: Record<string, string>;
+  envFile: string;
+  pidsFile: string;
+  actors?: Record<string, unknown>;
+  fixtures?: Record<string, unknown>;
+  /** Legacy runtime ownership; finish teardown with that installation before migration. */
+  resources?: WorldResourceRequirements & { log: string; holderPid: number; owner?: string };
+  lifecycle?: { log: string; owner?: string; holderPid?: number };
+  lastRun?: WorldRunRecord;
+  /** The ORIGIN this world clones from and fetches (docs/concepts/the-model.md): a hosted twin's
+   *  namespace — its canonical history. Absent = the placeholder is the only origin. */
+  origin?: { url: string; namespace: string; clonedAt?: string; fetchedAt?: string };
+};
+
+function assertStringArray(value: unknown, what: string, path: string): asserts value is string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string')) {
+    throw new Error(`${what} must be a non-empty string array in ${path}`);
+  }
+}
+
+function assertValidRegex(pattern: string, what: string, path: string): void {
+  try {
+    new RegExp(pattern);
+  } catch (error) {
+    throw new Error(`${what} has an invalid regex (${error instanceof Error ? error.message : String(error)}) in ${path}`);
+  }
+}
+
+/** Shared validator for a readiness probe — used by both `external.readyWhen` and a process/twin
+ * service's `ready` object. Exactly one of command/httpUrl/stdoutMatch, correct types, and any
+ * stdoutMatch regex must compile (so a typo fails at config time, not mid-boot). */
+function assertReadyWhen(ready: unknown, what: string, path: string): void {
+  if (!ready || typeof ready !== 'object' || Array.isArray(ready)) {
+    throw new Error(`${what} must be an object in ${path}`);
+  }
+  assertKeys(ready as Record<string, unknown>, ['command', 'args', 'httpUrl', 'stdoutMatch', 'timeoutMs', 'intervalMs'], what, path);
+  const r = ready as WorldExternalReadyWhen;
+  const probes = [r.command !== undefined, r.httpUrl !== undefined, r.stdoutMatch !== undefined].filter(Boolean).length;
+  if (probes !== 1) {
+    throw new Error(`${what} must set exactly one of command/httpUrl/stdoutMatch in ${path}`);
+  }
+  if (r.command !== undefined && typeof r.command !== 'string') throw new Error(`${what}.command must be a string in ${path}`);
+  if (r.args !== undefined && (!Array.isArray(r.args) || r.args.some((arg) => typeof arg !== 'string'))) throw new Error(`${what}.args must be a string array in ${path}`);
+  if (r.args !== undefined && r.command === undefined) throw new Error(`${what}.args requires command in ${path}`);
+  if (r.httpUrl !== undefined && typeof r.httpUrl !== 'string') throw new Error(`${what}.httpUrl must be a string in ${path}`);
+  if (r.stdoutMatch !== undefined) {
+    if (typeof r.stdoutMatch !== 'string') throw new Error(`${what}.stdoutMatch must be a string in ${path}`);
+    assertValidRegex(r.stdoutMatch, `${what}.stdoutMatch`, path);
+  }
+  for (const key of ['timeoutMs', 'intervalMs'] as const) {
+    if (r[key] !== undefined && (!Number.isInteger(r[key]) || r[key]! <= 0)) throw new Error(`${what}.${key} must be a positive integer in ${path}`);
+  }
+}
+
+function assertExternalServiceConfig(service: Partial<WorldServiceConfig>, path: string): void {
+  const id = service.id;
+  if (service.command !== undefined) {
+    throw new Error(`External service "${id}" must not set "command" (use external.up/down) in ${path}`);
+  }
+  if (service.port !== undefined) {
+    throw new Error(`External service "${id}" must not set "port" — the external tool manages its own ports in ${path}`);
+  }
+  if (service.portReason !== undefined) {
+    throw new Error(`External service "${id}" must not set "portReason" — it never sets a literal "port" in ${path}`);
+  }
+  const external = service.external;
+  if (!external || typeof external !== 'object' || Array.isArray(external)) {
+    throw new Error(`External service "${id}" must define an "external" object in ${path}`);
+  }
+  assertKeys(external as unknown as Record<string, unknown>, ['up', 'status', 'down', 'discover', 'readyWhen'], `External service "${id}" external`, path);
+  assertStringArray(external.up, `External service "${id}" external.up`, path);
+  assertStringArray(external.down, `External service "${id}" external.down`, path);
+  if (external.status !== undefined) assertStringArray(external.status, `External service "${id}" external.status`, path);
+  if (external.discover !== undefined) {
+    if (!Array.isArray(external.discover)) throw new Error(`External service "${id}" external.discover must be an array in ${path}`);
+    for (const mapping of external.discover) {
+      if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping)) {
+        throw new Error(`External service "${id}" discover entries must be objects in ${path}`);
+      }
+      assertKeys(mapping as unknown as Record<string, unknown>, ['as', 'source', 'jsonPath', 'pattern'], `External service "${id}" discover entry`, path);
+      if (!mapping.as || typeof mapping.as !== 'string') {
+        throw new Error(`External service "${id}" discover entry must define string "as" in ${path}`);
+      }
+      const hasJson = typeof mapping.jsonPath === 'string';
+      const hasPattern = typeof mapping.pattern === 'string';
+      if (hasJson === hasPattern) {
+        throw new Error(`External service "${id}" discover "${mapping.as}" must set exactly one of jsonPath/pattern in ${path}`);
+      }
+      if (hasPattern) assertValidRegex(mapping.pattern as string, `External service "${id}" discover "${mapping.as}" pattern`, path);
+      if (mapping.source !== undefined && mapping.source !== 'status' && mapping.source !== 'up') {
+        throw new Error(`External service "${id}" discover "${mapping.as}" source must be "status" or "up" in ${path}`);
+      }
+      if (mapping.source === 'status' && external.status === undefined && hasJson) {
+        // jsonPath against status requires a status command to produce the JSON.
+      }
+    }
+    if (external.status === undefined && external.discover.some((m) => (m.source ?? 'status') === 'status')) {
+      throw new Error(`External service "${id}" has discover entries reading "status" but no external.status command in ${path}`);
+    }
+  }
+  if (external.readyWhen !== undefined) {
+    assertReadyWhen(external.readyWhen, `External service "${id}" external.readyWhen`, path);
+  }
+}
+
+function assertLegacyWorldConfig(value: unknown, path: string): WorldConfig {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`World config must be an object: ${path}`);
+  }
+  const config = value as Partial<WorldConfig>;
+  if (!config.id || typeof config.id !== 'string') {
+    throw new Error(`World config must define string id: ${path}`);
+  }
+  if (!Array.isArray(config.services)) {
+    throw new Error(`World config must define services[]: ${path}`);
+  }
+  if (config.network !== undefined) config.network = normalizeWorldNetwork(config.network);
+  if (config.description !== undefined && typeof config.description !== 'string') throw new Error(`World config description must be a string in ${path}`);
+  if (config.env !== undefined && (!record(config.env) || Object.values(config.env).some((entry) => typeof entry !== 'string'))) throw new Error(`World config env must be a string→string object in ${path}`);
+  if (config.env?.VOLTER_WORLD_NETWORK_POLICY !== undefined) throw new Error(`World network permission belongs in runtime.network, not environment values in ${path}`);
+  for (const key of ['actors', 'fixtures'] as const) if (config[key] !== undefined && !record(config[key])) throw new Error(`World config ${key} must be an object in ${path}`);
+  if (config.bare !== undefined && (typeof config.bare !== 'object' || typeof (config.bare as { name?: unknown }).name !== 'string' || !/^[a-z0-9_-]+\/[a-z0-9_-]+$/i.test((config.bare as { name: string }).name))) {
+    throw new Error(`World config bare.name must be <org>/<world> in ${path}`);
+  }
+  if (config.remotes !== undefined) {
+    if (typeof config.remotes !== 'object' || Array.isArray(config.remotes)) throw new Error(`World config remotes must be an object of name → url|path in ${path}`);
+    for (const [name, target] of Object.entries(config.remotes as Record<string, unknown>)) if (typeof target !== 'string' || target === '' || !/^[A-Za-z0-9._-]+$/.test(name)) throw new Error(`World config remote "${name}" must be a non-empty url or path in ${path}`);
+  }
+  if (config.isolation !== undefined && config.isolation !== 'process' && config.isolation !== 'colocated' && config.isolation !== 'worker') {
+    throw new Error(`World config isolation must be "process", "colocated", or "worker" in ${path}`);
+  }
+  if (config.catalog !== undefined) {
+    const c = config.catalog as Partial<{ sha: unknown; protocol: unknown }>;
+    if (typeof c !== 'object' || c === null || typeof c.sha !== 'string' || (c.protocol !== undefined && !(typeof c.protocol === 'string' && /^\d+$/.test(c.protocol)))) {
+      throw new Error(`World config catalog must be { sha: string, protocol?: "<major>" } (the birth stamp init writes) in ${path}`);
+    }
+  }
+  if (config.resources !== undefined) {
+    if (!config.resources || typeof config.resources !== 'object' || Array.isArray(config.resources)) {
+      throw new Error(`World config resources must be an object in ${path}`);
+    }
+    for (const key of ['memoryMiB', 'writableStorageMiB'] as const) {
+      const amount = config.resources[key];
+      if (!Number.isInteger(amount) || amount <= 0) {
+        throw new Error(`World config resources.${key} must be a positive integer in ${path}`);
+      }
+    }
+  }
+  if (config.stripEnv !== undefined && (!Array.isArray(config.stripEnv) || config.stripEnv.some((s) => typeof s !== 'string' || (s !== '*' && !/^[A-Za-z_][A-Za-z0-9_]*\*?$/.test(s))))) {
+    throw new Error(`World config stripEnv must be a list of variable names, prefixes ending in *, or * for all inherited variables 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}`);
+    if (!service.id || typeof service.id !== 'string') throw new Error(`Service must define string id in ${path}`);
+    const exports = [service.injectEnv, ...Object.keys(service.injectEnvTemplates ?? {}), ...Object.keys(service.cliRedirect ?? {}), ...(Array.isArray(service.external?.discover) ? service.external.discover.map(entry => entry?.as) : [])];
+    if (service.env?.VOLTER_WORLD_NETWORK_POLICY !== undefined || exports.includes('VOLTER_WORLD_NETWORK_POLICY')) throw new Error(`Service ${service.id} cannot replace World network permission in ${path}`);
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(service.id)) throw new Error(`Invalid service id "${service.id}" in ${path}`);
+    if (ids.has(service.id)) throw new Error(`Duplicate service id "${service.id}" in ${path}`);
+    ids.add(service.id);
+    if (service.type !== undefined && service.type !== 'twin' && service.type !== 'process' && service.type !== 'external') {
+      throw new Error(`Service "${service.id}" type must be "twin", "process", or "external" in ${path}`);
+    }
+    if (service.command !== undefined && typeof service.command !== 'string') throw new Error(`Service "${service.id}" command must be a string in ${path}`);
+    if (service.args !== undefined && (!Array.isArray(service.args) || service.args.some((arg) => typeof arg !== 'string'))) throw new Error(`Service "${service.id}" args must be a string array in ${path}`);
+    if (service.cwd !== undefined && typeof service.cwd !== 'string') throw new Error(`Service "${service.id}" cwd must be a string in ${path}`);
+    if (service.controlPlane !== undefined && typeof service.controlPlane !== 'boolean') throw new Error(`Service "${service.id}" controlPlane must be a boolean in ${path}`);
+    for (const key of ['rootArg', 'portArg'] as const) if (service[key] !== undefined && service[key] !== false && typeof service[key] !== 'string') throw new Error(`Service "${service.id}" ${key} must be a string or false in ${path}`);
+    if (service.port !== undefined && service.port !== 'auto' && !(Number.isInteger(service.port) && service.port > 0 && service.port <= 65535)) throw new Error(`Service "${service.id}" port must be "auto" or an integer from 1 to 65535 in ${path}`);
+    if (service.type === 'external') {
+      assertExternalServiceConfig(service, path);
+    } else {
+      if (service.package !== undefined && !(typeof service.package === 'string' && /^@volter\/twin-[a-z0-9][a-z0-9-]*$/.test(service.package))) {
+        throw new Error(`Service "${service.id}" package must name a twin package (@volter/twin-<vendor>) in ${path}`);
+      }
+      if (service.package === undefined && (!service.command || typeof service.command !== 'string')) {
+        throw new Error(`Service "${service.id}" must define command (or package) in ${path}`);
+      }
+      if (service.ready !== undefined && service.ready !== 'tcp') {
+        assertReadyWhen(service.ready, `Service "${service.id}" ready`, path);
+      }
+      if (service.preload !== undefined) {
+        if (!Array.isArray(service.preload) || service.preload.some((p) => typeof p !== 'string')) {
+          throw new Error(`Service "${service.id}" preload must be a string array in ${path}`);
+        }
+      }
+      if (typeof service.port === 'number') {
+        if (!service.portReason || typeof service.portReason !== 'string') {
+          throw new Error(`Service "${service.id}" sets a literal "port" — this requires a "portReason" string recording why it can't be 'auto' in ${path}`);
+        }
+      } else if (service.portReason !== undefined) {
+        throw new Error(`Service "${service.id}" sets "portReason" without a literal numeric "port" in ${path}`);
+      }
+    }
+    if (service.root !== undefined) {
+      const r = service.root as { url?: unknown; deploy?: unknown; refresh?: unknown };
+      if (!record(r)) throw new Error(`Service "${service.id}" root must be an object in ${path}`);
+      assertKeys(r as Record<string, unknown>, ['url', 'deploy', 'refresh', 'scope'], `Service "${service.id}" root`, path);
+      if (typeof r.url !== 'string' || r.url === '') throw new Error(`Service "${service.id}" root.url must be a non-empty string in ${path}`);
+      if (r.deploy !== undefined && r.deploy !== 'auto' && r.deploy !== 'gated' && r.deploy !== 'hold') throw new Error(`Service "${service.id}" root.deploy must be "auto", "gated" or "hold" in ${path}`);
+      if ((r as { scope?: unknown }).scope !== undefined && typeof (r as { scope?: unknown }).scope !== 'string') throw new Error(`Service "${service.id}" root.scope must be a string in ${path}`);
+      if (r.refresh !== undefined) {
+        if (!record(r.refresh)) throw new Error(`Service "${service.id}" root.refresh must be an object in ${path}`);
+        assertKeys(r.refresh, ['every', 'webhook'], `Service "${service.id}" root.refresh`, path);
+        if (r.refresh.every !== undefined && typeof r.refresh.every !== 'string') throw new Error(`Service "${service.id}" root.refresh.every must be a string in ${path}`);
+        if (r.refresh.webhook !== undefined && typeof r.refresh.webhook !== 'boolean') throw new Error(`Service "${service.id}" root.refresh.webhook must be a boolean in ${path}`);
+      }
+      if (r.deploy === undefined) (service.root as { deploy: string }).deploy = 'gated';
+    }
+    if (service.colocate !== undefined) {
+      if (service.type === 'external') {
+        throw new Error(`External service "${service.id}" must not set colocate (its lifecycle is delegated) in ${path}`);
+      }
+      const colocate = service.colocate as Partial<{ module: string; export: string; scenarioPath: string }>;
+      if (record(colocate)) assertKeys(colocate as Record<string, unknown>, ['module', 'export', 'scenarioPath'], `Service "${service.id}" colocate`, path);
+      if (colocate?.scenarioPath !== undefined && (typeof colocate.scenarioPath !== 'string' || colocate.scenarioPath === '')) {
+        throw new Error(`Service "${service.id}" colocate.scenarioPath must be a non-empty string in ${path}`);
+      }
+      if (!colocate || typeof colocate !== 'object' || Array.isArray(colocate)
+        || (service.package === undefined ? (!colocate.module || typeof colocate.module !== 'string') : (colocate.module !== undefined && (typeof colocate.module !== 'string' || colocate.module === '')))
+        || !colocate.export || typeof colocate.export !== 'string') {
+        throw new Error(`Service "${service.id}" colocate must be { module, export } (non-empty strings; module optional with package) in ${path}`);
+      }
+    }
+    if (service.version !== undefined && !(typeof service.version === 'string' && /^\^?\d+\.\d+(\.\d+)?$/.test(service.version))) throw new Error(`Service "${service.id}" version must pin the twin package as "major.minor.patch" or "^major.minor" in ${path}`);
+    if (service.env !== undefined && (!record(service.env) || Object.values(service.env).some((entry) => typeof entry !== 'string'))) throw new Error(`Service "${service.id}" env must be a string→string object in ${path}`);
+    if (service.injectEnv !== undefined && typeof service.injectEnv !== 'string') {
+      throw new Error(`Service "${service.id}" injectEnv must be a string in ${path}`);
+    }
+    if (service.injectEnvTemplates !== undefined) {
+      if (typeof service.injectEnvTemplates !== 'object' || service.injectEnvTemplates === null || Array.isArray(service.injectEnvTemplates)
+        || Object.values(service.injectEnvTemplates).some((v) => typeof v !== 'string')) {
+        throw new Error(`Service "${service.id}" injectEnvTemplates must be a string→string object in ${path}`);
+      }
+    }
+    if (service.cliRedirect !== undefined) {
+      if (typeof service.cliRedirect !== 'object' || service.cliRedirect === null || Array.isArray(service.cliRedirect)
+        || Object.values(service.cliRedirect).some((v) => typeof v !== 'string')) {
+        throw new Error(`Service "${service.id}" cliRedirect must be a string→string object in ${path}`);
+      }
+    }
+  }
+  if (config.share !== undefined) {
+    if (!config.share || typeof config.share !== 'object' || Array.isArray(config.share)) {
+      throw new Error(`World config share must be an object in ${path}`);
+    }
+    const share = config.share as Partial<WorldShareConfig>;
+    assertKeys(config.share as unknown as Record<string, unknown>, ['provider', 'command', 'args', 'ephemeral', 'services'], 'World config share', path);
+    if (share.provider !== undefined && share.provider !== 'cloudflare-quick' && share.provider !== 'command') {
+      throw new Error(`World config share.provider must be "cloudflare-quick" or "command" in ${path}`);
+    }
+    if (share.provider === 'command' && (typeof share.command !== 'string' || !share.command)) {
+      throw new Error(`World config share.provider "command" requires a non-empty share.command in ${path}`);
+    }
+    if (share.command !== undefined) {
+      if (typeof share.command !== 'string' || !share.command) {
+        throw new Error(`World config share.command must be a non-empty string in ${path}`);
+      }
+      if (share.provider !== undefined && share.provider !== 'command') {
+        throw new Error(`World config share.command requires share.provider to be omitted or "command" in ${path}`);
+      }
+    }
+    if (share.args !== undefined) {
+      if (share.command === undefined) {
+        throw new Error(`World config share.args is only allowed when share.command is set in ${path}`);
+      }
+      if (!Array.isArray(share.args) || share.args.some((arg) => typeof arg !== 'string')) {
+        throw new Error(`World config share.args must be a string array in ${path}`);
+      }
+    }
+    if (share.ephemeral !== undefined && typeof share.ephemeral !== 'boolean') {
+      throw new Error(`World config share.ephemeral must be a boolean in ${path}`);
+    }
+    if (!Array.isArray(share.services)) throw new Error(`World config share.services must be an array in ${path}`);
+    for (const target of share.services as Partial<WorldShareServiceConfig>[]) {
+      if (!target || typeof target !== 'object' || Array.isArray(target)) throw new Error(`Invalid share service in ${path}`);
+      assertKeys(target as Record<string, unknown>, ['id', 'verifyPath'], 'Share service', path);
+      if (!target.id || typeof target.id !== 'string') throw new Error(`Share service must define string id in ${path}`);
+      if (!ids.has(target.id)) throw new Error(`Share service "${target.id}" does not match a configured service in ${path}`);
+      if (target.verifyPath !== undefined && target.verifyPath !== false && typeof target.verifyPath !== 'string') {
+        throw new Error(`Share service "${target.id}" verifyPath must be a string or false in ${path}`);
+      }
+    }
+  }
+  return config as WorldConfig;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function assertKeys(value: Record<string, unknown>, allowed: string[], what: string, path: string, allowComments = false): void {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key) && !(allowComments && key.startsWith('//')));
+  if (unexpected.length) throw new Error(`${what} has unknown field(s) ${unexpected.join(', ')} in ${path}`);
+}
+
+export const DEFAULT_WORLD_SELECTION: WorldSelection = {
+  include: [{ usage: 'application' }],
+  exclude: [],
+};
+
+export const LEGACY_WORLD_SELECTION: WorldSelection = {
+  include: WORLD_USAGES.map((usage) => ({ usage })),
+  exclude: [],
+};
+
+export function assertWorldSelection(value: unknown, path: string): asserts value is WorldSelection {
+  if (!record(value)) throw new Error(`discovery.selection must be an object in ${path}`);
+  assertKeys(value, ['include', 'exclude'], 'discovery.selection', path);
+  for (const list of ['include', 'exclude'] as const) {
+    if (!Array.isArray(value[list])) throw new Error(`discovery.selection.${list} must be an array in ${path}`);
+    for (const selector of value[list]) {
+      if (!record(selector)) throw new Error(`discovery.selection.${list} entries must be objects in ${path}`);
+      assertKeys(selector, ['usage', 'vendor'], `discovery.selection.${list} selector`, path);
+      if (selector.usage === undefined && selector.vendor === undefined) throw new Error(`discovery.selection.${list} selectors must not be empty in ${path}`);
+      if (selector.usage !== undefined && !WORLD_USAGES.includes(selector.usage as WorldUsage)) throw new Error(`Invalid discovery usage "${String(selector.usage)}" in ${path}`);
+      if (selector.vendor !== undefined && (typeof selector.vendor !== 'string' || selector.vendor.trim() === '')) throw new Error(`discovery selector vendor must be a non-empty string in ${path}`);
+    }
+  }
+}
+
+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);
+  const source = value.source === undefined ? {} : value.source;
+  const execution = value.execution === undefined ? {} : value.execution;
+  const endpoint = value.endpoint === undefined ? {} : value.endpoint;
+  const bindings = value.bindings === undefined ? {} : value.bindings;
+  if (!record(source) || !record(execution) || !record(endpoint) || !record(bindings)) throw new Error(`Service "${String(value.id ?? '')}" sections must be objects in ${path}`);
+  assertKeys(source, ['package', 'version'], 'service.source', path);
+  assertKeys(execution, ['process', 'colocate', 'lifecycle', 'cwd', 'environment', 'preload', 'controlPlane'], 'service.execution', path);
+  assertKeys(endpoint, ['port', 'portReason', 'ready'], 'service.endpoint', path);
+  assertKeys(bindings, ['injectEnv', 'injectEnvTemplates', 'cliRedirect', 'discover'], 'service.bindings', path);
+  const process = execution.process === undefined ? {} : execution.process;
+  const environment = execution.environment === undefined ? {} : execution.environment;
+  if (!record(process) || !record(environment)) throw new Error(`Service execution process/environment must be objects in ${path}`);
+  assertKeys(process, ['command', 'args', 'rootArg', 'portArg'], 'service.execution.process', path);
+  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.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}`);
+  if (execution.colocate !== undefined) {
+    if (!record(execution.colocate)) throw new Error(`Service "${value.id}" execution.colocate must be an object in ${path}`);
+    assertKeys(execution.colocate, ['module', 'export', 'scenarioPath'], `Service "${value.id}" execution.colocate`, path);
+  }
+  if (execution.preload !== undefined && (!Array.isArray(execution.preload) || execution.preload.some((entry) => typeof entry !== 'string'))) throw new Error(`Service "${value.id}" execution.preload must be a string array in ${path}`);
+  if (execution.lifecycle !== undefined) {
+    if (!record(execution.lifecycle)) throw new Error(`Service "${value.id}" execution.lifecycle must be an object in ${path}`);
+    assertKeys(execution.lifecycle, ['up', 'status', 'down', 'readyWhen'], `Service "${value.id}" execution.lifecycle`, path);
+  }
+  if (bindings.discover !== undefined) {
+    if (!Array.isArray(bindings.discover)) throw new Error(`Service "${value.id}" bindings.discover must be an array in ${path}`);
+    for (const mapping of bindings.discover) {
+      if (!record(mapping)) throw new Error(`Service "${value.id}" bindings.discover entries must be objects in ${path}`);
+      assertKeys(mapping, ['as', 'source', 'jsonPath', 'pattern'], `Service "${value.id}" bindings.discover entry`, path);
+    }
+  }
+  const type = value.type;
+  if (type !== 'twin' && type !== 'process' && type !== 'external') throw new Error(`Service "${String(value.id ?? '')}" must explicitly set type in ${path}`);
+  const lifecycle = execution.lifecycle;
+  const external = lifecycle === undefined ? undefined : {
+    ...lifecycle,
+    ...(bindings.discover === undefined ? {} : { discover: bindings.discover }),
+  } as WorldExternalServiceConfig;
+  const legacy: WorldServiceConfig = {
+    ...Object.fromEntries(Object.entries(value).filter(([key]) => key.startsWith('//'))),
+    ...(typeof value.description === 'string' ? { '//': value.description } : {}),
+    id: value.id as string,
+    type,
+    ...(source.package === undefined ? {} : { package: source.package as string }),
+    ...(source.version === undefined ? {} : { version: source.version as string }),
+    ...(process.command === undefined ? {} : { command: process.command as string }),
+    ...(process.args === undefined ? {} : { args: process.args as string[] }),
+    ...(process.rootArg === undefined ? {} : { rootArg: process.rootArg as string | false }),
+    ...(process.portArg === undefined ? {} : { portArg: process.portArg as string | false }),
+    ...(execution.colocate === undefined ? {} : { colocate: execution.colocate as WorldServiceConfig['colocate'] }),
+    ...(execution.cwd === undefined ? {} : { cwd: execution.cwd as string }),
+    ...(environment.values === undefined ? {} : { env: environment.values as Record<string, string> }),
+    ...(execution.preload === undefined ? {} : { preload: execution.preload as string[] }),
+    ...(execution.controlPlane === undefined ? {} : { controlPlane: execution.controlPlane as boolean }),
+    ...(endpoint.port === undefined ? {} : { port: endpoint.port as number | 'auto' }),
+    ...(endpoint.portReason === undefined ? {} : { portReason: endpoint.portReason as string }),
+    ...(endpoint.ready === undefined ? {} : { ready: endpoint.ready as WorldServiceConfig['ready'] }),
+    ...(bindings.injectEnv === undefined ? {} : { injectEnv: bindings.injectEnv as string }),
+    ...(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'] }),
+    ...(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}`);
+  if (type === 'twin' && ((legacy.package === undefined) === (legacy.command === undefined) || lifecycle !== undefined)) throw new Error(`Twin service "${legacy.id}" requires exactly one of source.package or execution.process.command and forbids lifecycle in ${path}`);
+  if (type === 'process' && (legacy.command === undefined || value.source !== undefined || execution.colocate !== undefined || lifecycle !== undefined || legacy.root !== undefined)) throw new Error(`Process service "${legacy.id}" has an invalid source/execution/root combination in ${path}`);
+  if (type === 'external' && (legacy.external === undefined || value.source !== undefined || execution.process !== undefined || execution.colocate !== undefined || value.endpoint !== undefined || execution.preload !== undefined || legacy.root !== undefined || bindings.injectEnv !== undefined || bindings.injectEnvTemplates !== undefined || bindings.cliRedirect !== undefined)) throw new Error(`External service "${legacy.id}" has an invalid source/execution/endpoint/bindings/root combination in ${path}`);
+  return legacy;
+}
+
+function normalizeV2(value: Record<string, unknown>, path: string): WorldConfig {
+  assertKeys(value, ['schemaVersion', 'metadata', 'discovery', 'services', 'runtime', 'serving', 'remotes', 'scenario', 'provenance'], 'World manifest', path, true);
+  for (const name of ['metadata', 'discovery', 'runtime', 'serving', 'scenario', 'provenance'] as const) if (value[name] !== undefined && !record(value[name])) throw new Error(`${name} must be an object in ${path}`);
+  const metadata = value.metadata as Record<string, unknown> | undefined;
+  if (!metadata) throw new Error(`World manifest must define metadata in ${path}`);
+  assertKeys(metadata, ['id', 'description'], 'metadata', path);
+  if (typeof metadata.id !== 'string' || metadata.id === '') throw new Error(`metadata.id must be a non-empty string in ${path}`);
+  if (metadata.description !== undefined && typeof metadata.description !== 'string') throw new Error(`metadata.description must be a string in ${path}`);
+  const discovery = (value.discovery ?? {}) as Record<string, unknown>;
+  const runtime = (value.runtime ?? {}) as Record<string, unknown>;
+  const serving = (value.serving ?? {}) as Record<string, unknown>;
+  const scenario = (value.scenario ?? {}) as Record<string, unknown>;
+  const provenance = (value.provenance ?? {}) as Record<string, unknown>;
+  assertKeys(discovery, ['selection'], 'discovery', path); assertKeys(runtime, ['isolation', 'environment', 'network'], 'runtime', path);
+  assertKeys(serving, ['mode', 'name', 'share'], 'serving', path); assertKeys(scenario, ['actors', 'fixtures'], 'scenario', path); assertKeys(provenance, ['catalog'], 'provenance', path);
+  const environment = runtime.environment ?? {};
+  if (!record(environment)) throw new Error(`runtime.environment must be an object in ${path}`);
+  assertKeys(environment, ['values', 'strip'], 'runtime.environment', path);
+  if (environment.values !== undefined && (!record(environment.values) || Object.values(environment.values).some((entry) => typeof entry !== 'string'))) throw new Error(`runtime.environment.values must be a string→string object in ${path}`);
+  if (scenario.actors !== undefined && !record(scenario.actors)) throw new Error(`scenario.actors must be an object in ${path}`);
+  if (scenario.fixtures !== undefined && !record(scenario.fixtures)) throw new Error(`scenario.fixtures must be an object in ${path}`);
+  const mode = serving.mode ?? 'app';
+  if (mode !== 'app' && mode !== 'bare') throw new Error(`serving.mode must be "app" or "bare" in ${path}`);
+  if (mode === 'bare' && typeof serving.name !== 'string') throw new Error(`Bare serving requires serving.name in ${path}`);
+  if (mode === 'app' && serving.name !== undefined) throw new Error(`App serving must omit serving.name in ${path}`);
+  const selection = discovery.selection ?? DEFAULT_WORLD_SELECTION;
+  assertWorldSelection(selection, path);
+  if (!Array.isArray(value.services)) throw new Error(`World manifest must define services[] in ${path}`);
+  const normalized: WorldConfig = {
+    ...Object.fromEntries(Object.entries(value).filter(([key]) => key.startsWith('//'))),
+    id: metadata.id as string,
+    ...(metadata.description === undefined ? {} : { description: metadata.description as string }),
+    manifestVersion: 2,
+    selection,
+    services: value.services.map((service) => serviceV2ToLegacy(service, path)),
+    ...(runtime.isolation === undefined ? {} : { isolation: runtime.isolation as WorldIsolation }),
+    ...(runtime.network === undefined ? {} : { network: normalizeWorldNetwork(runtime.network) }),
+    ...(environment.values === undefined ? {} : { env: environment.values as Record<string, string> }),
+    ...(environment.strip === undefined ? {} : { stripEnv: environment.strip as string[] }),
+    ...(mode === 'bare' ? { bare: { name: serving.name as string } } : {}),
+    ...(serving.share === undefined ? {} : { share: serving.share as WorldShareConfig }),
+    ...(value.remotes === undefined ? {} : { remotes: value.remotes as Record<string, string> }),
+    ...(scenario.actors === undefined ? {} : { actors: scenario.actors as Record<string, unknown> }),
+    ...(scenario.fixtures === undefined ? {} : { fixtures: scenario.fixtures as Record<string, unknown> }),
+    ...(provenance.catalog === undefined ? {} : { catalog: provenance.catalog as WorldConfig['catalog'] }),
+  };
+  return { ...assertLegacyWorldConfig(normalized, path), manifestVersion: 2, selection };
+}
+
+export function assertWorldConfig(value: unknown, path: string): WorldConfig {
+  if (record(value) && value.schemaVersion !== undefined) {
+    if (value.schemaVersion !== WORLD_SCHEMA_VERSION) throw new Error(`Unsupported World schemaVersion ${String(value.schemaVersion)} in ${path}`);
+    if ('id' in value || 'env' in value || 'isolation' in value || 'share' in value || 'catalog' in value) throw new Error(`World manifest mixes format-1 and format-2 fields in ${path}`);
+    return normalizeV2(value, path);
+  }
+  const legacy = assertLegacyWorldConfig(value, path);
+  return { ...legacy, manifestVersion: 1 };
+}
+
+export function worldSelectionIncludes(selection: WorldSelection, vendor: string, usage: WorldUsage): boolean {
+  const matches = (selector: WorldSelectionSelector): boolean =>
+    (selector.vendor === undefined || selector.vendor === vendor) && (selector.usage === undefined || selector.usage === usage);
+  return selection.include.some(matches) && !selection.exclude.some(matches);
+}
+
+function serviceToV2(service: WorldServiceConfig): Record<string, unknown> {
+  const process = {
+    ...(service.command === undefined ? {} : { command: service.command }),
+    ...(service.args === undefined ? {} : { args: service.args }),
+    ...(service.rootArg === undefined ? {} : { rootArg: service.rootArg }),
+    ...(service.portArg === undefined ? {} : { portArg: service.portArg }),
+  };
+  const execution = {
+    ...(Object.keys(process).length ? { process } : {}),
+    ...(service.colocate === undefined ? {} : { colocate: service.colocate }),
+    ...(service.external === undefined ? {} : { lifecycle: {
+      up: service.external.up,
+      ...(service.external.status === undefined ? {} : { status: service.external.status }),
+      down: service.external.down,
+      ...(service.external.readyWhen === undefined ? {} : { readyWhen: service.external.readyWhen }),
+    } }),
+    ...(service.cwd === undefined ? {} : { cwd: service.cwd }),
+    ...(service.env === undefined ? {} : { environment: { values: service.env } }),
+    ...(service.preload === undefined ? {} : { preload: service.preload }),
+    ...(service.controlPlane === undefined ? {} : { controlPlane: service.controlPlane }),
+  };
+  const endpoint = {
+    ...(service.port === undefined ? {} : { port: service.port }),
+    ...(service.portReason === undefined ? {} : { portReason: service.portReason }),
+    ...(service.ready === undefined ? {} : { ready: service.ready }),
+  };
+  const bindings = {
+    ...(service.injectEnv === undefined ? {} : { injectEnv: service.injectEnv }),
+    ...(service.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: service.injectEnvTemplates }),
+    ...(service.cliRedirect === undefined ? {} : { cliRedirect: service.cliRedirect }),
+    ...(service.external?.discover === undefined ? {} : { discover: service.external.discover }),
+  };
+  return {
+    ...Object.fromEntries(Object.entries(service as Record<string, unknown>).filter(([key]) => key.startsWith('//') && key !== '//')),
+    ...(service['//'] === undefined ? {} : { description: service['//'] }),
+    id: service.id,
+    type: service.type ?? 'twin',
+    ...(service.package === undefined && service.version === undefined ? {} : { source: {
+      ...(service.package === undefined ? {} : { package: service.package }),
+      ...(service.version === undefined ? {} : { version: service.version }),
+    } }),
+    ...(Object.keys(execution).length ? { execution } : {}),
+    ...(Object.keys(endpoint).length ? { endpoint } : {}),
+    ...(Object.keys(bindings).length ? { bindings } : {}),
+    ...(service.root === undefined ? {} : { root: service.root }),
+  };
+}
+
+/** Serialize normalized intent as the committed format-2 manifest. */
+export function worldConfigDocument(config: WorldConfig, selection: WorldSelection = config.selection ?? DEFAULT_WORLD_SELECTION): WorldManifestV2 & Record<string, unknown> {
+  return {
+    schemaVersion: WORLD_SCHEMA_VERSION,
+    metadata: { id: config.id, ...(config.description === undefined ? {} : { description: config.description }) },
+    discovery: { selection },
+    ...(config.isolation === undefined && config.env === undefined && config.stripEnv === undefined && config.network === undefined ? {} : { runtime: {
+      ...(config.isolation === undefined ? {} : { isolation: config.isolation }),
+      ...(config.network === undefined ? {} : { network: normalizeWorldNetwork(config.network) }),
+      ...(config.env === undefined && config.stripEnv === undefined ? {} : { environment: {
+        ...(config.env === undefined ? {} : { values: config.env }),
+        ...(config.stripEnv === undefined ? {} : { strip: config.stripEnv }),
+      } }),
+    } }),
+    services: config.services.map(serviceToV2),
+    ...(config.bare === undefined && config.share === undefined ? {} : { serving: {
+      ...(config.bare === undefined ? {} : { mode: 'bare' as const, name: config.bare.name }),
+      ...(config.share === undefined ? {} : { share: config.share }),
+    } }),
+    ...(config.remotes === undefined ? {} : { remotes: config.remotes }),
+    ...(config.actors === undefined && config.fixtures === undefined ? {} : { scenario: {
+      ...(config.actors === undefined ? {} : { actors: config.actors }),
+      ...(config.fixtures === undefined ? {} : { fixtures: config.fixtures }),
+    } }),
+    ...(config.catalog === undefined ? {} : { provenance: { catalog: config.catalog } }),
+    ...Object.fromEntries(Object.entries(config as Record<string, unknown>).filter(([key]) => key.startsWith('//'))),
+  };
+}