@volter/world-runtime 2.0.0

package/dist/src/schema.d.ts

@@ -0,0 +1,449 @@
+import { 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 declare const WORLD_SCHEMA_VERSION: 2;
+export declare const WORLD_USAGES: readonly ["application", "dependencies", "build", "deployment"];
+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 declare 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?: {
+        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;
+    };
+};
+export declare const DEFAULT_WORLD_SELECTION: WorldSelection;
+export declare const LEGACY_WORLD_SELECTION: WorldSelection;
+export declare function assertWorldSelection(value: unknown, path: string): asserts value is WorldSelection;
+export declare function assertWorldConfig(value: unknown, path: string): WorldConfig;
+export declare function worldSelectionIncludes(selection: WorldSelection, vendor: string, usage: WorldUsage): boolean;
+/** Serialize normalized intent as the committed format-2 manifest. */
+export declare function worldConfigDocument(config: WorldConfig, selection?: WorldSelection): WorldManifestV2 & Record<string, unknown>;