@volter/world-runtime 2.0.0

package/src/inject-map.ts

@@ -0,0 +1,72 @@
+// The ONE world-runtime home for the injector's host→twin knowledge (`@volter/world-core/inject`:
+// `VENDOR_HOSTS` + `readMap` + `resolveTwin` + `twinUrlVendor`). The redirect proxy, `covers`,
+// and `up`'s inert-injectEnv warning all read the injector THROUGH this module, so none of them
+// can re-encode (and silently drift from) what the injector actually redirects — the exact
+// failure mode of the LibreChat blind-adoption run, where a world injected AWS_TWIN_URL that no
+// injector vendor reads and nothing said so.
+import { createRequire } from 'node:module';
+
+/** The slice of `@volter/world-core/inject` reused here (data + pure functions only). */
+export type InjectModule = {
+  readMap(env: Record<string, string | undefined>): Record<string, string>;
+  /** `pathname` is optional; it only disambiguates hosts two vendors share (see inject.cjs). */
+  resolveTwin(host: string, map: Record<string, string>, pathname?: string): { vendor: string; origin: string } | null;
+  /** `S3_TWIN_URL` → 's3'; a `*_TWIN_URL` name readMap would never read → null. */
+  twinUrlVendor(name: string): string | null;
+  /** the headers a request routed to the application carries: the host and scheme it was made with */
+  appForwardHeaders(url: URL): Record<string, string>;
+  VENDOR_HOSTS: Record<string, (host: string, pathname?: string) => boolean>;
+  restore(): void;
+};
+
+let injectCache: InjectModule | null = null;
+
+/** Lazily load the injector's host→twin table. Loading the CJS auto-installs its http/fetch
+ * patches as a side effect; we immediately `restore()` so requiring it here is inert (we only
+ * want the data + pure functions, not to patch THIS process). */
+export function loadInject(): InjectModule {
+  if (injectCache) return injectCache;
+  const require = createRequire(import.meta.url);
+  const mod = require('@volter/world-core/inject') as InjectModule;
+  try { mod.restore(); } catch { /* nothing was installed */ }
+  injectCache = mod;
+  return mod;
+}
+
+/** The vendor keys the injector can redirect for (the keys of VENDOR_HOSTS). */
+export function injectableVendorKeys(): Set<string> {
+  return new Set(Object.keys(loadInject().VENDOR_HOSTS));
+}
+
+/** Does the injector actually read this env var name? (`S3_TWIN_URL` → 's3'; `AWS_TWIN_URL`
+ * → null — the consolidated aws twin answers under the s3/dynamodb/timestream keys.) */
+export function twinUrlVendorFor(name: string): string | null {
+  return loadInject().twinUrlVendor(name);
+}
+
+/** WARN lines for twin-shaped injectEnv vars the injector will never read — an injectEnv like
+ * `AWS_TWIN_URL` is written into the world env, looks wired, and does NOTHING (readMap iterates
+ * VENDOR_HOSTS keys looking for `<VENDOR>_TWIN_URL`; there is no `aws` vendor key). `up` prints
+ * these loudly so the disagreement is visible at boot instead of surfacing as silently-real
+ * vendor traffic later. Vars that do not end in `_TWIN_URL` are app-read config (SUPABASE_URL,
+ * LIVEKIT_URL, …), not injector input — never warned about. */
+export function inertInjectEnvWarnings(
+  services: Array<{ id: string; injectEnv?: string }>,
+): string[] {
+  const warnings: string[] = [];
+  for (const service of services) {
+    const name = service.injectEnv;
+    if (!name || !/_TWIN_URL$/.test(name)) continue;
+    if (twinUrlVendorFor(name) !== null) continue;
+    const stem = name.replace(/_TWIN_URL$/, '');
+    const hint = stem.toUpperCase() === 'AWS'
+      ? ' The consolidated aws twin is read under its per-AREA keys — S3_TWIN_URL / DYNAMODB_TWIN_URL / TIMESTREAM_TWIN_URL / SESV2_TWIN_URL / SECRETSMANAGER_TWIN_URL / BEDROCK_TWIN_URL — point those at the aws twin instead.'
+      : '';
+    warnings.push(
+      `[volter-world] WARN: service "${service.id}" injects ${name}, but the injector reads no such vendor` +
+      ` ("${stem.toLowerCase()}" is not a VENDOR_HOSTS key in @volter/world-core/inject) — the var is INERT and this` +
+      ` vendor's SDK traffic will NOT be redirected to the twin.${hint}`,
+    );
+  }
+  return warnings;
+}

package/src/lifecycle-record.ts

@@ -0,0 +1,168 @@
+// Durable ownership of one World. This inventory does not allocate or reserve capacity.
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { volterHome } from '@volter/world-core';
+import { hostname } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { stateDirName, withFileLock } from '@volter/world-core';
+import { checkedOwner } from './consumers.ts';
+
+export type WorldLifecycleRecord = {
+  version: 1; world: string; root: string; identity: string; instanceCreatedAt: string;
+  owner?: string; ownerUid?: number; ownerPid: number; hostname: string; startedAt: string;
+  phase: 'starting' | 'running' | 'cleanup-pending'; pids: number[]; log: string;
+};
+
+const directory = () => join(volterHome(), 'world-lifecycles');
+const identity = (root: string, world: string) => createHash('sha256').update(`${resolve(root)}\0${world}`).digest('hex');
+const recordPath = (root: string, world: string) => join(directory(), `${identity(root, world)}.json`);
+const legacyPath = (root: string, world: string) => join(volterHome(), 'world-resource-claims', `${identity(root, world)}.json`);
+export const lifecycleLogPath = (root: string, world: string) => join(resolve(root), stateDirName(), 'worlds', '.lifecycle', `${world}.log`);
+
+function read(path: string): WorldLifecycleRecord {
+  const record = JSON.parse(readFileSync(path, 'utf8')) as WorldLifecycleRecord;
+  if (record?.version !== 1 || typeof record.world !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(record.world)
+    || typeof record.root !== 'string' || !record.root || record.identity !== identity(record.root, record.world)
+    || !Number.isFinite(Date.parse(record.instanceCreatedAt)) || !Number.isFinite(Date.parse(record.startedAt))
+    || !Number.isInteger(record.ownerPid) || record.ownerPid <= 0 || typeof record.hostname !== 'string'
+    || !['starting', 'running', 'cleanup-pending'].includes(record.phase) || !Array.isArray(record.pids)
+    || record.pids.some(pid => !Number.isInteger(pid) || pid <= 0)
+    || record.log !== lifecycleLogPath(record.root, record.world)) throw new Error('invalid lifecycle record');
+  checkedOwner(record.owner);
+  return record;
+}
+
+function write(path: string, record: WorldLifecycleRecord): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+  } finally { rmSync(temporary, { force: true }); }
+}
+
+/** Called under the instance lock, before replacing data. Only this identity is read. */
+export function assertLifecycleStartable(root: string, world: string): void {
+  if (existsSync(legacyPath(root, world))) throw new Error(`World "${world}" has a legacy ownership record; finish teardown using its pinned old runtime before migration. Record retained: ${legacyPath(root, world)}`);
+  if (existsSync(recordPath(root, world))) throw new Error(`World "${world}" still owns a lifecycle record; complete volter-world down before replacing it. Record retained: ${recordPath(root, world)}`);
+}
+
+/** A missing process is not successful teardown; records persist until explicit release. */
+export function beginWorldLifecycle(root: string, world: string, instanceCreatedAt: string, owner?: string): void {
+  checkedOwner(owner);
+  assertLifecycleStartable(root, world);
+  const record: WorldLifecycleRecord = {
+    version: 1, world, root: resolve(root), identity: identity(root, world), instanceCreatedAt,
+    owner, ownerUid: process.getuid?.(), ownerPid: process.pid, hostname: hostname(),
+    startedAt: new Date().toISOString(), phase: 'starting', pids: [], log: lifecycleLogPath(root, world),
+  };
+  recordWorldLifecycleEvent(root, world, 'recording startup ownership; no capacity reserved');
+  write(recordPath(root, world), record);
+}
+
+function update(root: string, world: string, change: (record: WorldLifecycleRecord) => WorldLifecycleRecord): void {
+  const path = recordPath(root, world);
+  withFileLock(`${path}.lock`, () => {
+    if (!existsSync(path)) throw new Error(`World "${world}" lifecycle record is missing; ownership update refused`);
+    const record = read(path);
+    if (record.identity !== identity(root, world)) throw new Error('World lifecycle identity mismatch');
+    write(path, change(record));
+  });
+}
+
+export function handoffWorldLifecycle(root: string, world: string, pids: number[]): void {
+  update(root, world, record => ({ ...record, phase: 'running', pids: [...new Set(pids.filter(pid => pid > 0))] }));
+}
+
+export function retainWorldLifecycleForCleanup(root: string, world: string): void {
+  if (existsSync(legacyPath(root, world))) throw new Error(`World "${world}" has legacy ownership; use its pinned runtime for teardown`);
+  if (!existsSync(recordPath(root, world))) return;
+  update(root, world, record => ({ ...record, phase: 'cleanup-pending' }));
+}
+
+export function recordWorldLifecycleEvent(root: string, world: string, message: string): void {
+  const path = lifecycleLogPath(root, world);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${new Date().toISOString()} ${message}\n`, { flag: 'a', mode: 0o600 });
+}
+
+/** Called only after verified cleanup. Never touches legacy records. */
+export function releaseWorldLifecycle(root: string, world: string): void {
+  const path = recordPath(root, world);
+  if (!existsSync(path)) return;
+  withFileLock(`${path}.lock`, () => {
+    if (!existsSync(path)) return;
+    const record = read(path);
+    if (record.identity !== identity(root, world)) throw new Error('World lifecycle identity mismatch');
+    // The receipt line is evidence, not a precondition: failing to append it must not keep ownership (and so the next
+    // `up`) blocked after a verified teardown.
+    try { recordWorldLifecycleEvent(root, world, 'teardown verified; ownership released'); } catch { /* released regardless */ }
+    rmSync(path);
+  });
+}
+
+/**
+ * Releases the record of a World whose instance metadata is gone when nothing it
+ * recorded can still run: the record is this host's and this user's, and its owner
+ * and every process it handed off have exited. There is nothing left to tear down,
+ * so the record is the only thing left to release. Anything alive, another host's,
+ * another user's, or unreadable keeps the record. Returns whether it released.
+ */
+export function releaseAbandonedWorldLifecycle(root: string, world: string): boolean {
+  const path = recordPath(root, world);
+  if (!existsSync(path)) return false;
+  return withFileLock(`${path}.lock`, () => {
+    if (!existsSync(path)) return false;
+    let record: WorldLifecycleRecord;
+    try { record = read(path); } catch { return false; }
+    if (record.identity !== identity(root, world) || record.hostname !== hostname()) return false;
+    if (record.ownerUid !== undefined && record.ownerUid !== process.getuid?.()) return false;
+    if ([record.ownerPid, ...record.pids].some((pid) => processExists(pid))) return false;
+    try { recordWorldLifecycleEvent(root, world, 'instance metadata gone and every recorded process exited; ownership released'); } catch { /* the root may be gone with it */ }
+    rmSync(path);
+    return true;
+  });
+}
+
+function processExists(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (cause) { return (cause as NodeJS.ErrnoException).code === 'EPERM'; }
+}
+
+export function hasWorldLifecycle(root: string, world: string): boolean {
+  return existsSync(recordPath(root, world)) || existsSync(legacyPath(root, world));
+}
+
+export function inspectWorldLifecycles() {
+  const worlds: WorldLifecycleRecord[] = [];
+  const warnings: string[] = [];
+  for (const file of existsSync(directory()) ? readdirSync(directory()).sort() : []) {
+    if (!file.endsWith('.json')) continue;
+    try {
+      const record = read(join(directory(), file));
+      if (file !== `${record.identity}.json`) throw new Error('filename identity mismatch');
+      worlds.push(record);
+    } catch { warnings.push(`Unreadable lifecycle record ${file}; retained, ownership unknown.`); }
+  }
+  const legacyDirectory = join(volterHome(), 'world-resource-claims');
+  const legacyRecords: Array<{ path: string; world?: string; root?: string; cleanupPending?: boolean; readable: boolean }> = [];
+  for (const file of existsSync(legacyDirectory) ? readdirSync(legacyDirectory).sort() : []) {
+    if (!file.endsWith('.json')) continue;
+    const path = join(legacyDirectory, file);
+    try {
+      const old = JSON.parse(readFileSync(path, 'utf8'));
+      const root = old.root ?? (typeof old.log === 'string' ? resolve(dirname(old.log), '../../..') : undefined);
+      if (typeof root !== 'string' || typeof old.world !== 'string' || identity(root, old.world) !== old.identity
+        || file !== `${old.identity}.json`) throw new Error('unknown identity');
+      legacyRecords.push({ path, world: old.world, root, cleanupPending: old.cleanupPending === true, readable: true });
+    } catch { legacyRecords.push({ path, readable: false }); warnings.push(`Unreadable legacy record ${file}; retained, not charged as capacity.`); }
+  }
+  return { worlds, legacyRecords, warnings };
+}
+
+/** Runtime phase is meaningful only for the same instance generation; it is not a health probe. */
+export function isWorldLifecycleRunning(root: string, world: string, instanceCreatedAt: string): boolean {
+  try {
+    const record = read(recordPath(root, world));
+    return record.identity === identity(root, world) && record.instanceCreatedAt === instanceCreatedAt && record.phase === 'running';
+  } catch { return false; }
+}

package/src/origin.ts

@@ -0,0 +1,134 @@
+import { captureHistory, historyDigest, originHead, publishOriginHistory, type HistoryLayout, type HistoryReference, readHistoryView, historyLength, worldPaths } from '@volter/world-core';
+// `volter world clone` and `fetch` — a world's ORIGIN is another world, served (docs/concepts/the-model.md
+// #a-branch-is-a-position-not-a-copy: a clone is a branch whose parent is at a URL): its whole log per twin is this world's PARENT. `clone` records the origin
+// and brings every twin's log in from position zero; `fetch` appends what the origin has past the
+// recorded position. Nothing here touches a vendor: an origin is always a world, the token is the
+// served world's, and what arrives are entries — the parent log grows, the branch log is untouched.
+import { join, resolve } from 'node:path';
+import { appendOriginEntry, appendParentEntry, branchEntries, getActiveWorldStore, landedIds, originEntries, parentEntries, readBranchMeta, type Entry, wholeLog, withAncestryLock, writeBranchMeta } from '@volter/world-core';
+import { saveWorldInstance, statusWorld } from './runtime.ts';
+import type { WorldInstance } from './schema.ts';
+import { fetchReady, isPathRemote, localWorld, TOKEN_HEADER } from './served-world.ts';
+
+export type FetchOptions = { root?: string; url?: string; namespace?: string; key: string; full?: boolean; services?: string[]; views?: Record<string, HistoryReference>; now?: Date };
+export type FetchOutcome = {
+  /** per twin: entries in the cache past the branch's position — what a rebase folds */
+  snapshots: Record<string, HistoryReference & { remoteView?: string }>; behind: Record<string, number>; world: string; origin: { url: string; namespace: string }; full: boolean; appended: Record<string, number>; files?: number };
+
+function originOf(instance: WorldInstance, options: FetchOptions): { url: string; namespace: string } {
+  const url = options.url ?? instance.origin?.url; const namespace = options.namespace ?? instance.origin?.namespace;
+  if (!url || !namespace) throw new Error(`World "${instance.name}" has no origin recorded — \`volter remote add origin <url>\` or \`volter world clone <url>\` first`);
+  if (!isPathRemote(url) && !/^[a-z0-9_-]+\/[a-z0-9_-]+$/i.test(namespace)) throw new Error(`a served world is <org>/<world>, got ${JSON.stringify(namespace)}`);
+  return { url: url.replace(/\/+$/, ''), namespace };
+}
+
+/** A twin's whole log from the origin, from a position: over http from a served world's door, or
+ *  straight off the disk of a world at a path. */
+/** The state service a twin records under: its own name, else the one state dir under its control root (slack → chat). */
+function stateServiceOf(controlRoot: string, service: string): string {
+  const stateRoot = join(controlRoot, '.volter', 'world');
+  const store = getActiveWorldStore();
+  const states = store.list(stateRoot).filter((name) => store.stat(join(stateRoot, name))?.isDirectory);
+  return states.includes(service) ? service : states.length === 1 ? states[0]! : service;
+}
+
+type HistoryPage = { state: string; view: string; position: number; after: number; layout: HistoryLayout; digest: string; entries: Entry[] };
+async function pageOf(origin: { url: string; namespace: string }, service: string, after: number, key: string, view?: string): Promise<HistoryPage> {
+  return door<HistoryPage>(origin, `log/${service}?after=${after}&limit=500${view ? `&view=${encodeURIComponent(view)}` : ''}`, key);
+}
+
+async function door<T>(origin: { url: string; namespace: string }, path: string, key: string): Promise<T> {
+  const res = await fetchReady(`${origin.url}/-/${origin.namespace}/${path}`, { headers: { [TOKEN_HEADER]: key } });
+  if (!res.ok) throw new Error(`origin ${origin.url}/-/${origin.namespace}/${path} answered ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  return (await res.json()) as T;
+}
+
+/** Bring in what the origin has past this world's recorded position, per twin; `full` starts from
+ *  zero and records the origin as this world's. */
+export async function fetchFromOrigin(name: string, options: FetchOptions): Promise<FetchOutcome> {
+  const root = resolve(options.root ?? process.cwd());
+  const instance = statusWorld(name, root);
+  const origin = originOf(instance, options);
+  const at_ = (options.now ?? new Date()).toISOString();
+  const services = (options.services ?? Object.keys(instance.services)).sort();
+  const appended: Record<string, number> = {};
+  const behind: Record<string, number> = {};
+  const snapshots: FetchOutcome['snapshots'] = {};
+  withAncestryLock(() => {
+    for (const service of services) {
+      const controlRoot = join(instance.dirs.data, service);
+      const meta = readBranchMeta(stateServiceOf(controlRoot, service), controlRoot);
+      if (meta?.parent && !meta.origin) throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
+    }
+  });
+  for (const service of services) {
+    const controlRoot = join(instance.dirs.data, service);
+    const state = stateServiceOf(controlRoot, service);
+    if (isPathRemote(origin.url)) {
+      // A PARENT ON THIS MACHINE is read live through the pointer, like a local branch (contract
+      // "Just like Neon", 1): nothing is copied; a clone points at the parent's head, a fetch only
+      // says how far the parent has moved past this branch's position
+      withAncestryLock(() => {
+      const target = localWorld(origin.url);
+      const at = join(target.instance.dirs.data, service);
+      const parentState = stateServiceOf(at, service);
+      const head = options.views?.[service] ?? captureHistory(parentState, at);
+      const parentLength = historyLength(readHistoryView(worldPaths(parentState, at).dir, head.view).layout);
+      if (head.position !== parentLength) throw new Error('Origin view and position disagree');
+      snapshots[service] = { view: head.view, position: parentLength };
+      const meta = readBranchMeta(state, controlRoot);
+      if (meta?.parent && !meta.origin) throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
+      const before = meta?.origin?.position ?? meta?.parent?.position ?? 0;
+      const descriptor = readHistoryView(worldPaths(parentState, at).dir, head.view);
+      const tracking = { at, directory: descriptor.owner.directory, generation: descriptor.owner.generation, view: head.view, position: parentLength, depth: 0 };
+      // a world with no pointer adopts this origin as its parent: a clone starts at the origin's head,
+      // a world that only added the remote starts at zero and rebases onto it
+      if (!meta?.parent) writeBranchMeta(state, { parent: { at, position: options.full ? parentLength : 0, view: head.view }, origin: { ...tracking, ...(!options.full ? { position: 0, incomplete: true } : {}) }, fetchedOrigin: tracking, branchedAt: at_ }, controlRoot);
+      else writeBranchMeta(state, { ...meta, fetchedOrigin: tracking }, controlRoot);
+      const selected = readBranchMeta(state, controlRoot);
+      const pointer = selected?.origin ?? selected?.parent;
+      appended[service] = Math.max(0, parentLength - before);
+      behind[service] = pointer ? Math.max(0, parentLength - pointer.position) || (pointer.view === head.view ? 0 : 1) : 0;
+      });
+      continue;
+    }
+    // Download one immutable view, then publish its complete cache head. No mixed pages.
+    const requested = options.views?.[service];
+    const first = await pageOf(origin, service, 0, options.key, requested?.view);
+    if (requested && (first.view !== requested.view || first.position !== requested.position)) throw new Error('Origin did not return the requested history snapshot');
+    if (!first.view || !Number.isInteger(first.position) || first.position < 0 || first.after !== 0) throw new Error('Origin did not return an immutable history view');
+    const entries: Entry[] = [];
+    let page = first;
+    for (;;) {
+      if (page.view !== first.view || page.position !== first.position || page.after !== entries.length || page.state !== first.state || page.digest !== first.digest || historyDigest(page.layout) !== historyDigest(first.layout)) throw new Error('Origin changed history view during pagination');
+      entries.push(...page.entries);
+      if (entries.length > first.position) throw new Error('Origin history exceeds its declared position');
+      if (entries.length === first.position) break;
+      if (page.entries.length === 0) throw new Error('Origin history page ended before its declared position');
+      page = await pageOf(origin, service, entries.length, options.key, first.view);
+    }
+    if (historyDigest({ layout: first.layout, entries }) !== first.digest) throw new Error('Origin history digest mismatch');
+    withAncestryLock(() => {
+    const meta = readBranchMeta(state, controlRoot);
+      if (meta?.parent && !meta.origin) throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
+    const cached = publishOriginHistory(state, controlRoot, first.view, first.layout, entries);
+    appended[service] = cached.appended;
+    snapshots[service] = { view: cached.view, position: entries.length, remoteView: first.view };
+    const descriptor = readHistoryView(worldPaths(state, controlRoot).dir, cached.view);
+    const tracking = { at: `${origin.url}/${origin.namespace}`, directory: descriptor.owner.directory, generation: descriptor.owner.generation, view: cached.view, position: entries.length, remoteView: first.view, depth: 0 };
+    if (!meta?.parent) writeBranchMeta(state, { parent: { at: tracking.at, position: options.full ? entries.length : 0, view: cached.view, remoteView: first.view }, origin: { ...tracking, ...(!options.full ? { position: 0, incomplete: true } : {}) }, fetchedOrigin: tracking, branchedAt: at_ }, controlRoot);
+    else writeBranchMeta(state, { ...meta, fetchedOrigin: tracking }, controlRoot);
+    const selected = readBranchMeta(state, controlRoot);
+    const pointer = selected?.origin ?? selected?.parent;
+    // Changed same-length snapshots are still drift; offsets are scoped to a view.
+    behind[service] = pointer ? Math.max(0, entries.length - pointer.position) || (pointer.remoteView === first.view ? 0 : 1) : 0;
+    });
+
+  }
+  saveWorldInstance({ ...instance, origin: { ...origin, ...(options.full ? { clonedAt: at_ } : instance.origin?.clonedAt ? { clonedAt: instance.origin.clonedAt } : {}), fetchedAt: at_ } });
+  return { world: name, origin, full: options.full ?? false, appended, behind, snapshots };
+}
+
+export function worldOrigin(name: string, root?: string): WorldInstance['origin'] | null {
+  return statusWorld(name, resolve(root ?? process.cwd())).origin ?? null;
+}

package/src/pack-facts.ts

@@ -0,0 +1,128 @@
+// PACK FACTS OVERLAY — the world-runtime consumer of the generated pack-facts artifact
+// (packages/world-core/generated/pack-facts.json, compiled by scripts/pack-facts.ts
+// from each pack's `pack: TwinPack` descriptor).
+//
+// During the descriptor-first migration (adding-a-twin.md §3) (adding-a-twin.md §3 (the descriptor is the one home)), the
+// adoption tables here are the UNION of the legacy central maps and the pack declarations.
+// The overlay MUTATES the central tables at module init — every use-site keeps reading the
+// object it always read — and a fact declared in BOTH places throws: dual declaration is the
+// drift this migration exists to end, so it is loud everywhere, not just in a test.
+
+import factsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
+
+export type PackAdoption = { sdks?: string[]; pypi?: string[]; scopes?: string[]; envStems?: string[]; worldIds?: string[]; tools?: Array<{ package: string; usage: 'build' | 'deployment' }> };
+export type PackFacts = {
+  /** Existing descriptor transport, compiled into the same artifact as endpoint/adoption facts. */
+  transport?: string;
+  /** Optional native frontend of the same state owner, selected explicitly on the pack CLI. */
+  nativeTransport?: { protocol: string; flag: string; upstreamEnv: string };
+  adoption?: PackAdoption;
+  hosts?: Array<{ host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true }>;
+  hostsNone?: string;
+  endpointEnv?: { name: string; templates?: Record<string, string>; note: string };
+  endpointEnvNone?: string;
+  /** The pack's colocatable `create<Name>TwinServer` factory export, derived (or descriptor-
+   *  declared under ambiguity) by scripts/pack-facts.ts. Consumed by `init` to emit
+   *  `colocate:` service entries so a world's twins boot inside ONE host process (R2a). */
+  serveExport?: string;
+  /** R16: the protocol major the package targets and its standing against the kernel that compiled the artifact. */
+  protocol?: { declared?: string; major: number; standing: 'current' | 'deprecated' | 'refused' | 'assumed' };
+};
+
+// world-runtime and core are sibling workspace packages; the artifact is committed,
+// so a missing file is a broken checkout (or an unbuilt generator change), never a soft state.
+// core's artifact, imported as a JSON module: the published runtime resolves it beside an installed
+// core, a bundle carries it, and no host needs a filesystem to read it
+export function packFacts(): Record<string, PackFacts> {
+  return (factsDocument as unknown as { packs: Record<string, PackFacts> }).packs;
+}
+
+const dual = (vendor: string, kind: string, key: string, holder: string): Error =>
+  new Error(
+    `pack-facts: ${kind} "${key}" is declared BOTH on the ${vendor} pack descriptor AND in the central ${holder} table — ` +
+    `the migration rule is one home per fact. Delete the central entry (the descriptor wins).`,
+  );
+
+/** Overlay descriptor-declared npm SDK names onto the central SDK_TWINS map (project-inspect.ts). */
+/** The PyPI half of the SDK map, built the same way from each descriptor's `adoption.pypi`
+ *  (PEP 503 names). One name belongs to one pack; a second claim refuses at load. */
+export function overlayPypiTwins(pypiTwins: Record<string, { vendor: string; twin: string }>): void {
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    for (const raw of facts.adoption?.pypi ?? []) {
+      const name = normalizePypiName(raw);
+      if (Object.hasOwn(pypiTwins, name)) {
+        const holder = pypiTwins[name]!.vendor;
+        if (holder !== vendor) throw new Error(`pack-facts overlay: pypi package "${name}" is claimed by BOTH the "${holder}" and "${vendor}" packs' descriptors — one name, one pack`);
+        continue;
+      }
+      pypiTwins[name] = { vendor, twin: `@volter/twin-${vendor}` };
+    }
+  }
+}
+/** PEP 503: case-insensitive, runs of `-_.` collapse to one `-`. */
+export function normalizePypiName(name: string): string {
+  return name.trim().toLowerCase().replace(/[-_.]+/g, '-');
+}
+
+export function overlaySdkTwins(sdkTwins: Record<string, { vendor: string; twin: string }>): void {
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    for (const sdk of facts.adoption?.sdks ?? []) {
+      // Object.hasOwn, not `in`: `in` walks the prototype chain, so a pathological name like
+      // 'constructor' would throw a bogus dual error. And when the holder is another PACK's
+      // overlay (two descriptors claiming one name), the right fix is different from a hand-
+      // table collision — say which it is (§9 round two L2, 2026-08-31).
+      if (Object.hasOwn(sdkTwins, sdk)) {
+        const holder = sdkTwins[sdk]!.vendor;
+        if (holder !== vendor) {
+          throw new Error(
+            `pack-facts overlay: npm sdk "${sdk}" is claimed by BOTH the "${holder}" and "${vendor}" packs' descriptors (or by ${holder} in the central SDK_TWINS table) — one home per fact: decide which pack owns the client and remove the other claim.`,
+          );
+        }
+        throw dual(vendor, 'sdk', sdk, 'SDK_TWINS');
+      }
+      sdkTwins[sdk] = { vendor, twin: `@volter/twin-${vendor}` };
+    }
+  }
+}
+
+/** Overlay descriptor-declared scopes/env stems/world ids onto covers.ts's central maps. */
+export function overlayCoversMaps(maps: {
+  scopeVendors: Record<string, string>;
+  envStemVendors: Record<string, string>;
+  vendorWorldIds: Record<string, string[]>;
+}): void {
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    for (const scope of facts.adoption?.scopes ?? []) {
+      if (scope in maps.scopeVendors) throw dual(vendor, 'scope', scope, 'SDK_SCOPE_VENDORS');
+      maps.scopeVendors[scope] = vendor;
+    }
+    for (const stemRaw of facts.adoption?.envStems ?? []) {
+      const stem = stemRaw.toLowerCase();
+      if (stem in maps.envStemVendors) throw dual(vendor, 'env stem', stem, 'ENV_STEM_VENDORS');
+      maps.envStemVendors[stem] = vendor;
+    }
+    const worldIds = facts.adoption?.worldIds ?? [];
+    if (worldIds.length > 0) {
+      if (vendor in maps.vendorWorldIds) throw dual(vendor, 'world ids', vendor, 'VENDOR_WORLD_IDS');
+      maps.vendorWorldIds[vendor] = [vendor, ...worldIds];
+    }
+  }
+}
+
+/** Overlay descriptor-declared endpoint-env wiring for packs with no injectable host.
+ * Packs that also declare hosts are wired through the injector; init reads their optional
+ * endpoint templates directly from pack facts without misclassifying them as app-read-only. */
+export function overlayEndpointEnv(
+  table: Record<string, { injectEnv?: string; injectEnvTemplates?: Record<string, string>; note: string }>,
+): void {
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    if (facts.endpointEnv === undefined) continue;
+    if ((facts.hosts?.length ?? 0) > 0) continue;
+    if (vendor in table) throw dual(vendor, 'endpoint env', vendor, 'APP_READ_ENDPOINT_ENV');
+    table[vendor] = {
+      injectEnv: facts.endpointEnv.name,
+      ...(facts.endpointEnv.templates ? { injectEnvTemplates: facts.endpointEnv.templates } : {}),
+      note: facts.endpointEnv.note,
+    };
+  }
+}

package/src/pglite-backing.ts

@@ -0,0 +1,141 @@
+// The containerless backing for World-managed infrastructure: PGlite hosts
+// (see pglite-host.ts) instead of docker compose. Selected by
+// `volter-world-infra` when no container runtime is available (or by
+// explicit VOLTER_WORLD_INFRA_BACKING=pglite); the world config, definition
+// file, injected env, and declared-service contract are byte-identical either
+// way — backing is private, exactly as the boundary comment in
+// infra-cli.ts promises.
+//
+// Capability is stated, not stretched: this backing serves POSTGRES services
+// only. A definition declaring mysql/redis without a container runtime is
+// refused with the kinds named, never half-booted.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+export interface InfraService { kind: string; hostPort: number }
+
+/** Parse the services out of world.infrastructure.yml. This is NOT a YAML
+ * parser: init's renderComposeFile emits a deterministic shape, and this
+ * reads exactly that shape back (service key at 2-space indent = the kind;
+ * the single loopback port mapping beneath it). Anything else is a malformed
+ * definition and fails loudly. */
+export function parseInfraDefinition(text: string): InfraService[] {
+  const services: InfraService[] = [];
+  let current: string | null = null;
+  let inServices = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^services:\s*$/.test(line)) { inServices = true; continue; }
+    if (!inServices) continue;
+    const service = line.match(/^ {2}([a-z][a-z0-9_-]*):\s*$/);
+    if (service) { current = service[1]!; continue; }
+    const port = line.match(/^ {6}- "127\.0\.0\.1:(\d+):\d+"\s*$/);
+    if (port && current) {
+      services.push({ kind: current, hostPort: Number(port[1]) });
+      current = null;
+    }
+  }
+  return services;
+}
+
+/** Endpoints of the declared infrastructure, published through external.discover. Only URLs
+ * whose protocol and loopback port match a declared service belong to this lifecycle. */
+export function infraConnections(services: InfraService[], env: Record<string, string | undefined>): Record<string, string> {
+  const connections: Record<string, string> = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (value === undefined) continue;
+    try {
+      const url = new URL(value);
+      if (url.hostname !== '127.0.0.1') continue;
+      const kind = url.protocol === 'postgresql:' ? 'postgres' : url.protocol.slice(0, -1);
+      if (services.some((service) => service.kind === kind && service.hostPort === Number(url.port))) connections[name] = value;
+    } catch { /* not an infrastructure endpoint */ }
+  }
+  return connections;
+}
+
+const HOST = join(import.meta.dir, 'pglite-host.mjs');
+const READY_TIMEOUT_MS = 60_000;
+
+function pidPath(dataDir: string, kind: string): string {
+  return join(dataDir, `pglite-${kind}.pid`);
+}
+
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function listening(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: 1000 }, () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.on('error', () => resolve(false));
+    socket.on('timeout', () => { socket.destroy(); resolve(false); });
+  });
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** The kinds this backing cannot serve, or [] when it can serve the world. */
+export function unsupportedKinds(services: InfraService[]): string[] {
+  return [...new Set(services.filter((s) => s.kind !== 'postgres').map((s) => s.kind))];
+}
+
+export async function pgliteUp(services: InfraService[], dataDir: string): Promise<void> {
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service.kind);
+    if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim()))) continue;
+    const serviceData = join(dataDir, `pglite-${service.kind}-data`);
+    mkdirSync(serviceData, { recursive: true });
+    const log = join(dataDir, `pglite-${service.kind}.log`);
+    mkdirSync(dirname(log), { recursive: true });
+    // a real fd, not a pipe: the host must outlive this process untethered
+    const logFd = openSync(log, 'a');
+    const child = spawn('node', [HOST, '--port', String(service.hostPort), '--data', serviceData], {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+    closeSync(logFd);
+    writeFileSync(pidFile, `${child.pid}\n`);
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    while (!(await listening(service.hostPort))) {
+      if (!alive(child.pid!)) {
+        throw new Error(`pglite ${service.kind} exited before serving — see ${log}`);
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`pglite ${service.kind} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+      }
+      await sleep(200);
+    }
+  }
+}
+
+export async function pgliteStatus(services: InfraService[], dataDir: string): Promise<{ ok: boolean; ready: number }> {
+  let ready = 0;
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service.kind);
+    if (!existsSync(pidFile)) continue;
+    const pid = Number(readFileSync(pidFile, 'utf8').trim());
+    if (alive(pid) && await listening(service.hostPort)) ready += 1;
+  }
+  return { ok: ready === services.length && services.length > 0, ready };
+}
+
+export async function pgliteDown(services: InfraService[], dataDir: string): Promise<void> {
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service.kind);
+    if (!existsSync(pidFile)) continue;
+    const pid = Number(readFileSync(pidFile, 'utf8').trim());
+    if (alive(pid)) {
+      try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+      const deadline = Date.now() + 5000;
+      while (alive(pid) && Date.now() < deadline) await sleep(100);
+      if (alive(pid)) { try { process.kill(pid, 'SIGKILL'); } catch { /* raced */ } }
+    }
+    rmSync(pidFile, { force: true });
+  }
+}