@volter/world-runtime 2.0.0

package/dist/src/schema.js

@@ -0,0 +1,605 @@
+import { normalizeWorldNetwork } from '@volter/world-core/network-policy';
+export const WORLD_SCHEMA_VERSION = 2;
+export const WORLD_USAGES = ['application', 'dependencies', 'build', 'deployment'];
+/** 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';
+function assertStringArray(value, what, path) {
+    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, what, path) {
+    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, what, path) {
+    if (!ready || typeof ready !== 'object' || Array.isArray(ready)) {
+        throw new Error(`${what} must be an object in ${path}`);
+    }
+    assertKeys(ready, ['command', 'args', 'httpUrl', 'stdoutMatch', 'timeoutMs', 'intervalMs'], what, path);
+    const r = ready;
+    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']) {
+        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, path) {
+    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, ['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', '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, `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, path) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`World config must be an object: ${path}`);
+    }
+    const config = value;
+    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'])
+        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.name !== 'string' || !/^[a-z0-9_-]+\/[a-z0-9_-]+$/i.test(config.bare.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))
+            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;
+        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']) {
+            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();
+    for (const service of config.services) {
+        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'])
+            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;
+            if (!record(r))
+                throw new Error(`Service "${service.id}" root must be an object in ${path}`);
+            assertKeys(r, ['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.scope !== undefined && typeof r.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.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;
+            if (record(colocate))
+                assertKeys(colocate, ['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;
+        assertKeys(config.share, ['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) {
+            if (!target || typeof target !== 'object' || Array.isArray(target))
+                throw new Error(`Invalid share service in ${path}`);
+            assertKeys(target, ['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;
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function assertKeys(value, allowed, what, path, allowComments = false) {
+    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 = {
+    include: [{ usage: 'application' }],
+    exclude: [],
+};
+export const LEGACY_WORLD_SELECTION = {
+    include: WORLD_USAGES.map((usage) => ({ usage })),
+    exclude: [],
+};
+export function assertWorldSelection(value, path) {
+    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']) {
+        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))
+                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, path) {
+    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 }),
+    };
+    const legacy = {
+        ...Object.fromEntries(Object.entries(value).filter(([key]) => key.startsWith('//'))),
+        ...(typeof value.description === 'string' ? { '//': value.description } : {}),
+        id: value.id,
+        type,
+        ...(source.package === undefined ? {} : { package: source.package }),
+        ...(source.version === undefined ? {} : { version: source.version }),
+        ...(process.command === undefined ? {} : { command: process.command }),
+        ...(process.args === undefined ? {} : { args: process.args }),
+        ...(process.rootArg === undefined ? {} : { rootArg: process.rootArg }),
+        ...(process.portArg === undefined ? {} : { portArg: process.portArg }),
+        ...(execution.colocate === undefined ? {} : { colocate: execution.colocate }),
+        ...(execution.cwd === undefined ? {} : { cwd: execution.cwd }),
+        ...(environment.values === undefined ? {} : { env: environment.values }),
+        ...(execution.preload === undefined ? {} : { preload: execution.preload }),
+        ...(execution.controlPlane === undefined ? {} : { controlPlane: execution.controlPlane }),
+        ...(endpoint.port === undefined ? {} : { port: endpoint.port }),
+        ...(endpoint.portReason === undefined ? {} : { portReason: endpoint.portReason }),
+        ...(endpoint.ready === undefined ? {} : { ready: endpoint.ready }),
+        ...(bindings.injectEnv === undefined ? {} : { injectEnv: bindings.injectEnv }),
+        ...(bindings.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: bindings.injectEnvTemplates }),
+        ...(bindings.cliRedirect === undefined ? {} : { cliRedirect: bindings.cliRedirect }),
+        ...(value.root === undefined ? {} : { root: value.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, path) {
+    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'])
+        if (value[name] !== undefined && !record(value[name]))
+            throw new Error(`${name} must be an object in ${path}`);
+    const metadata = value.metadata;
+    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 ?? {});
+    const runtime = (value.runtime ?? {});
+    const serving = (value.serving ?? {});
+    const scenario = (value.scenario ?? {});
+    const provenance = (value.provenance ?? {});
+    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 = {
+        ...Object.fromEntries(Object.entries(value).filter(([key]) => key.startsWith('//'))),
+        id: metadata.id,
+        ...(metadata.description === undefined ? {} : { description: metadata.description }),
+        manifestVersion: 2,
+        selection,
+        services: value.services.map((service) => serviceV2ToLegacy(service, path)),
+        ...(runtime.isolation === undefined ? {} : { isolation: runtime.isolation }),
+        ...(runtime.network === undefined ? {} : { network: normalizeWorldNetwork(runtime.network) }),
+        ...(environment.values === undefined ? {} : { env: environment.values }),
+        ...(environment.strip === undefined ? {} : { stripEnv: environment.strip }),
+        ...(mode === 'bare' ? { bare: { name: serving.name } } : {}),
+        ...(serving.share === undefined ? {} : { share: serving.share }),
+        ...(value.remotes === undefined ? {} : { remotes: value.remotes }),
+        ...(scenario.actors === undefined ? {} : { actors: scenario.actors }),
+        ...(scenario.fixtures === undefined ? {} : { fixtures: scenario.fixtures }),
+        ...(provenance.catalog === undefined ? {} : { catalog: provenance.catalog }),
+    };
+    return { ...assertLegacyWorldConfig(normalized, path), manifestVersion: 2, selection };
+}
+export function assertWorldConfig(value, path) {
+    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, vendor, usage) {
+    const matches = (selector) => (selector.vendor === undefined || selector.vendor === vendor) && (selector.usage === undefined || selector.usage === usage);
+    return selection.include.some(matches) && !selection.exclude.some(matches);
+}
+function serviceToV2(service) {
+    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).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, selection = config.selection ?? DEFAULT_WORLD_SELECTION) {
+    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', 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).filter(([key]) => key.startsWith('//'))),
+    };
+}

package/dist/src/serve.d.ts

@@ -0,0 +1,30 @@
+import { type WorldManifest } from './attach.js';
+export declare const MANIFEST_PATH = "/.well-known/volter-world";
+/** The manifest a REMOTE attacher sees: every vendor behind the one advertised
+ * door. The serving side keeps routing against its own loopback env. */
+export declare function advertiseWorldManifest(name: string, root: string, advertisedOrigin: string): WorldManifest;
+export interface ManifestServerOptions {
+    manifest: () => WorldManifest;
+    host?: string;
+    port?: number;
+    /** when set, GET requires `Authorization: Bearer <token>` — the attach token
+     * for a shared world (docs/guides/route-a-cli-through-the-world.md). Constant-time-ish compare via length
+     * gate + timingSafeEqual to avoid trivial token oracles. */
+    token?: string;
+}
+export interface ManifestServerHandle {
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startManifestServer(options: ManifestServerOptions): Promise<ManifestServerHandle>;
+/** Fetch a remote world's manifest. Accepts the manifest URL itself or the
+ * world's base URL (the well-known path is appended). */
+export declare function fetchRemoteManifest(ref: string, options?: {
+    token?: string;
+}): Promise<WorldManifest>;
+/** The env a remote env-attachment exports: vendor twin URLs (the advertised
+ * door), suggested fake credentials, CA trust, and the injector preload. */
+export declare function remoteAttachEnv(manifest: WorldManifest, options: {
+    caFile?: string;
+    injectPath: string;
+}): Record<string, string>;