Config

.volter/world.json is the committed, portable intent for a World. volter world init writes format 2; up accepts format 2 and legacy unversioned files. Resolved ports, process identities, minted values and timestamps belong to the ignored instance record. Live credentials never belong here.

{
  "schemaVersion": 2,
  "metadata": { "id": "acme-web" },
  "discovery": {
    "selection": {
      "include": [{ "usage": "application" }],
      "exclude": []
    }
  },
  "runtime": {
    "isolation": "colocated",
    "environment": {
      "values": { "GITHUB_TOKEN": "twin-fake-github-token" },
      "strip": ["HOST_SECRET_*"]
    }
  },
  "services": [
    {
      "id": "github",
      "type": "twin",
      "source": { "package": "@volter/twin-github", "version": "2.0.0" },
      "execution": { "colocate": { "export": "createGithubTwinServer" } },
      "endpoint": { "port": "auto" },
      "bindings": { "injectEnv": "GITHUB_TWIN_URL" }
    }
  ]
}

The documentCopy Anchor Link

Unknown structural fields fail validation. At the document or service level, keys beginning with // are comments; nested sections do not accept comment keys. User-keyed maps and scenario values are not treated as structural fields.

SelectionCopy Anchor Link

Selection contains include and exclude arrays. A selector has usage, vendor, or both:

{
  "include": [
    { "usage": "application" },
    { "usage": "deployment", "vendor": "cloudflare" }
  ],
  "exclude": [{ "usage": "dependencies" }]
}

Usages are application, dependencies, build, and deployment. Fields within one selector must all match; selectors within a list are alternatives; exclusion wins. A vendor is selected when at least one detected use survives. The default selects application uses only, and init writes that default so later runs reuse it. A vendor-only selector addresses all uses of that vendor. Native connection rows also match their protocol vendor (redis selects redis:REDIS_URL); an exclusion on the protocol or precise row wins. Registry destinations are dependency use; twin-declared tools such as Wrangler carry their declared build or deployment use.

Selection controls automatic proposals and coverage obligations. It does not authorize network access, expose credentials, remove explicitly declared services, or excuse broken routing. An excluded finding remains visible as excluded, never covered.

Regeneration keeps saved service bindings, comments and authored infrastructure stubs. Conflicting new endpoint claims fail before writing files. Existing seed.ts files retain their contents and ordering; init reports the imports and calls to add for newly introduced default seeds.

ServicesCopy Anchor Link

Every service has id and an explicit type: twin, process, or external.

A twin has exactly one of source.package or execution.process.command; it may additionally declare execution.colocate. A process requires a command and cannot declare twin source, colocation, external lifecycle, or root. An external service requires lifecycle up and down, uses bindings.discover for outputs, and cannot declare source, process, colocation, endpoint, preload, or root. Invalid combinations fail before anything starts.

Under colocated or worker isolation, a twin declared outside the host starts beside the host's startup: its co-located twins' addresses are in its environment already, but their ports open only when the host is ready. Such a twin contacts them only to answer a request, never while it starts. A service that must reach one while it starts is declared process and starts after the host is ready (ADR 0015).

A twin rootCopy Anchor Link

root identifies the real vendor account behind a twin on a shared World. The credential is sealed separately under .volter/credentials/.

SharingCopy Anchor Link

serving.share retains the existing share shape: provider is cloudflare-quick or command; a custom provider supplies command and optional args; ephemeral records URL lifetime; and services is an array of { id, verifyPath? } targets declared in this World.

MigrationCopy Anchor Link

volter-world migrate-config .volter/world.json

Migration accepts only unversioned format 1. It refuses unknown legacy fields, creates the byte-for-byte backup world.json.v1.bak, validates a temporary format-2 file, then replaces the manifest atomically. It preserves service order, path-resolution behavior, roots, remotes, scenario data, comments and provenance. The old all-signals coverage behavior is materialized as all four included usages; changing to the application-only default is a separate edit. Deprecated resources metadata is retained only in the backup and reported as dropped. Ordinary reads never migrate a file, and running instance records are never rewritten.

The World directoryCopy Anchor Link

Beside world.json, committed files include handlers/<vendor>.json, seeds/story.ts, and checks/*.ts. Running state is ignored: worlds/<branch>/, world.env, token, credentials/, and current.

The instance record stores actual service URLs, pids, logs, data directories, resolved twin versions, the live environment, and the selection snapshot used at boot. Coverage of a running World uses that snapshot; editing the manifest does not retroactively change it.

Explicit build grants take precedence over twin routing for their matching public paths. Redirects return to the client; each subsequent request is authorized separately.

Without a container runtime, World-managed infrastructure serves a declared PostgreSQL with the machine's own PostgreSQL wherever it has one. The tool directory (postgres, initdb, psql, createdb) comes from VOLTER_WORLD_POSTGRES_BIN, or else from the directory of a postgres server on PATH. A World keeps the database server its retained data was made by. Where no server is installed it is PGlite, and the infrastructure log names PGlite's one shared session. Nothing installs PostgreSQL, and VOLTER_WORLD_INFRA_BACKING=native|pglite|docker forces one. Native PostgreSQL is the installed version with the installation's extensions, and it keeps machine time. It serves the declared PostgreSQL through independent sessions in a private loopback-only cluster, retained on ordinary down and owned by the World lifecycle. It reads the generated definition's literal POSTGRES_USER and POSTGRES_DB; synthetic local connections use trust auth. Unix sockets are disabled. Native database time remains machine time. An occupied port or ownership mismatch is refused; teardown evidence is retained if shutdown cannot be verified. Other supported containerless kinds retain their existing implementation. Do not change the infrastructure implementation over a live instance or treat retained PGlite files as native PostgreSQL: stop and purge a disposable World before changing its infrastructure implementation.

For a browser or other client without the process injector, an issued URL can be requested as $issue:<service>@direct. It retains the twin-issued URL's user information, path and query and replaces its scheme and authority with that service's endpoint. Opaque tokens, non-HTTP URLs and credential files are refused in this form. For a URL embedded by a build, declare a stable endpoint port so the same URL serves after closing build permissions and resuming runtime state.