@volter/world-core 3.0.155 → 3.0.157

package/src/runtime.ts

@@ -157,10 +157,13 @@ export {
   setActiveBlobStore,
   withBlobStore,
   readBlobRange,
+  streamChunks,
+  writeBlobStream,
 } from './blob-store.ts';
-export type { BlobStore } from './blob-store.ts';
+export type { BlobStore, BlobWritten } from './blob-store.ts';
 export {
   applyTwinWrite,
+  applyTwinWrites,
   applyTwinWriteAtomic,
   createTwinServer,
   CALLER_HEADER,
@@ -297,6 +300,8 @@ export { installedPackageDir, installedVendorPacks, packVendor, packRepository,
 export * as git from './git/index.ts';
 // S3's wire (contract "S3's wire is a kernel library too"): its XML, CORS, lifecycle, delete batches, ETags, body bytes.
 export * as s3 from './s3/wire.ts';
+// Generic strict XML grammar; vendor interpretation remains in its consumer.
+export * as xml from './xml.ts';
 
 // The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
 
@@ -323,7 +328,7 @@ export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntr
 
 export { referenceField, registerReferences, packReferences, resolveReferences, type ReferenceDeclaration } from './references.ts';
 // the HTTP server seam: the one place the serve path meets the runtime (Bun or Node)
-export { serveHttp, serveStream, connectWebSocket, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
+export { serveHttp, serveStream, connectWebSocket, nodeBuiltin, servedHandlerOf, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
 // two runtime-neutral helpers for a serve path: a file as a Response, a page's client bundle
 export { fileResponse, contentTypeOf } from './file-response.ts';
 export { bundleClient, filePathOf } from './client-bundle.ts';
@@ -335,7 +340,7 @@ export { corsHeaders, withCors, type CorsDecl } from './cors.ts';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.ts';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.ts';
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from './resource-blob.ts';
 
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from './ancestry.ts';
 
@@ -347,3 +352,5 @@ export type { MachinePool, MachineSpec, MachineProcess, MachineStatus, MachineFi
 
 
 export { boardFrameKey } from './board-keys.ts';
+
+export * as managedOriginalInputs from './managed-original-inputs.ts';

package/src/serve-http.ts

@@ -4,11 +4,12 @@
 // as a standard Request and the handler's Response written back. Async, because binding a port is
 // asynchronous on Node — Bun's synchronous bind is the special case.
 //
-// Nothing here runs at module scope, and `node:http` is reached through `process.getBuiltinModule`
+// Nothing here runs at module scope (the served-handler registry is made on first use), and `node:http` is reached through `process.getBuiltinModule`
 // rather than a static import: this module rides into browser client bundles through the kernel's
 // entrypoint, where a static `node:` import is the 2026-09-06 class of break.
 
 import type { TwinStream } from './twin-fetch.ts';
+import { worldBootAnswer } from './world-boot.ts';
 
 /** One socket library at the host seam, shared by inbound upgrades and authenticated outbound relays. */
 const socketLibrary = () => import('ws');
@@ -64,6 +65,24 @@ const bunRuntime = (): BunLike | undefined => { const b = (globalThis as { Bun?:
 /** The path a World asks a service it booted, when that service's port answers, which boot it belongs to. */
 export const WORLD_BOOT_PATH = '/__volter/world-boot';
 
+/** Each listening server's own handler, by its port, as the seam serves it (the boot door answered, nothing journaled):
+ *  the World's co-located host warms a twin in-process through it (world-runtime host.ts warmInProcess), so its warm-up is
+ *  never a request on the wire nor in any journal. A server leaves it when it stops. Kept on globalThis under a registered
+ *  symbol, as the reference registry is (references.ts), so a pack that resolved its own copy of this module shares it. */
+const servedHandlers = (): Map<number, HttpHandler> =>
+  ((globalThis as Record<symbol, unknown>)[Symbol.for('volter.servedHandlers')] ??= new Map<number, HttpHandler>()) as Map<number, HttpHandler>;
+
+/** The handler serving `port` in this process, when a server made through the seam listens there. */
+export function servedHandlerOf(port: number): HttpHandler | undefined { return servedHandlers().get(port); }
+
+/** A server's handler kept by its port until the server stops. */
+function keepHandler(server: HttpServer, handler: HttpHandler): HttpServer {
+  const port = server.port;
+  if (!port) return server;
+  servedHandlers().set(port, handler);
+  return { ...server, stop: async (closeActive?: boolean) => { if (servedHandlers().get(port) === handler) servedHandlers().delete(port); await server.stop(closeActive); } };
+}
+
 export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer> {
   // Inside a World every server made through the seam answers which boot it belongs to, so the World can tell its own
   // twin from a leftover World's that holds the same port. Outside a World nothing changes.
@@ -76,7 +95,7 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
   const worldBoot = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.VOLTER_WORLD_BOOT_ID;
   if (worldBoot) {
     const served = options.fetch;
-    options = { ...options, fetch: (request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Response.json({ boot: worldBoot }) : served(request)) };
+    options = { ...options, fetch: (request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? worldBootAnswer(worldBoot) : served(request)) };
   }
   // loopback by default: an unnamed interface is never every interface
   const hostname = options.hostname ?? '127.0.0.1';
@@ -86,6 +105,28 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
     // the global `Bun.serve` — the request journal's wrap of it (serve.ts) applies to packs and to
     // this seam alike, so the seam never decorates twice on Bun
     const upgrade = options.upgrade;
+    // the sockets open now, by the seam's own count: Bun keeps a socket its server closed (a refused key's 1008, from
+    // `open` or later) in `pendingWebSockets` after its close handler ran, and `stop()`'s promise then never settles
+    // (measured on Bun 1.3.11, macOS arm64, alone: a Bun.serve whose open() calls ws.close(1008) leaves
+    // pendingWebSockets at 1 with its close handler called once, and an awaited stop(true) had not settled after 3 s;
+    // unawaited, the listener closed and the process used 4 ms of CPU over the next 2 s; a client-initiated close
+    // stops in 0 ms). Conform's life hung on it after OpenAI's keyless Realtime step.
+    // and the requests whose handlers have not answered: a stop that drops connections (closeActive) aborts each one's
+    // signal, and Bun's stop still waits for the handler to settle, which a handler that never answers never does
+    // (measured on Bun 1.3.11, macOS arm64, alone: a Bun.serve whose fetch never resolves, its request's signal aborted
+    // by stop(true), pendingRequests 1, the stop unsettled after 3 s). Conform's client check hung on a pack served with
+    // a scenario that answered nothing. Node's path below reports such a handler as cleanup and resolves; so does this one.
+    const live = new Set<unknown>();
+    const inflight = new Set<Request>();
+    const served = options.fetch;
+    const tracked = (request: Request, ...rest: unknown[]): Response | Promise<Response> => {
+      inflight.add(request);
+      let answer: Response | Promise<Response>;
+      try { answer = (served as (r: Request, ...x: unknown[]) => Response | Promise<Response>)(request, ...rest); } catch (error) { inflight.delete(request); throw error; }
+      if (!(answer instanceof Promise)) { inflight.delete(request); return answer; }
+      return answer.finally(() => { inflight.delete(request); });
+    };
+    options = { ...options, fetch: tracked };
     const server = bun.serve({ ...options, hostname, port: options.port ?? 0,
       ...(upgrade ? {
         fetch: (request: Request, server: { upgrade: (request: Request, options: { data: { request: Request } }) => boolean }) => {
@@ -95,16 +136,34 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
           return options.fetch(request);
         },
         websocket: {
-          open: (peer: WebSocketPeer & { data: { request: Request } }) => upgrade.open(peer, peer.data.request),
+          open: (peer: WebSocketPeer & { data: { request: Request } }) => { live.add(peer); return upgrade.open(peer, peer.data.request); },
           message: (peer: WebSocketPeer, data: string | Uint8Array) => upgrade.message(peer, data),
-          close: upgrade.close,
+          close: (peer: WebSocketPeer, ...rest: unknown[]) => { live.delete(peer); return (upgrade.close as (p: WebSocketPeer, ...r: unknown[]) => unknown)(peer, ...rest); },
         },
       } : {}),
     });
     const port = server.port ?? 0;
-    return { hostname, port, url: server.url instanceof URL ? server.url : new URL(`http://${urlHost}:${port}/`), stop: async (closeActive = true) => { await server.stop(closeActive); } };
+    return keepHandler({ hostname, port, url: server.url instanceof URL ? server.url : new URL(`http://${urlHost}:${port}/`), stop: async (closeActive = true) => {
+      const stopping = Promise.resolve(server.stop(closeActive));
+      // stop closes the sockets still open (closeActive), each a close Bun may then keep counting, and drops the
+      // connections of handlers still running: once every socket the seam opened has closed and every handler left is
+      // one whose request was dropped, Bun's stop would never settle on them (above), and the seam has stopped
+      let settled = false;
+      stopping.then(() => { settled = true; }, () => { settled = true; });
+      while (!settled) {
+        const orphaned = [...inflight].every((request) => request.signal.aborted);
+        const counted = ((server as { pendingWebSockets?: number }).pendingWebSockets ?? 0) > 0;
+        if (live.size === 0 && orphaned && (counted || (closeActive && inflight.size > 0))) {
+          stopping.catch(() => {});
+          if (inflight.size) console.error(`serveHttp: forced stop left pending handler cleanup: ${inflight.size} request(s)`);
+          return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      }
+      await stopping;
+    } }, options.fetch);
   }
-  return serveOnNode({ ...options, hostname, urlHost, fetch: decorate ? decorate(options) : options.fetch });
+  return keepHandler(await serveOnNode({ ...options, hostname, urlHost, fetch: decorate ? decorate(options) : options.fetch }), options.fetch);
 }
 
 type NodeHttp = typeof import('node:http');

package/src/serve.ts

@@ -12,13 +12,14 @@ import { parseExactJson } from './exact-json.ts';
 // reality). Forking is a separate data operation (fork.ts), never a serve mode.
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { serveHttp, setServeDecorator, WORLD_BOOT_PATH, type HttpHandler } from './serve-http.ts';
-import { performAtHead } from './head.ts';
+import { performAtHead, performsAtHeadNow } from './head.ts';
 import { withHeaders } from './with-headers.ts';
 import { createHash } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import type { SubjectFields } from './hash.ts';
 import { hashFieldValue } from './hash.ts';
-import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, projectResources } from './actions.ts';
+import { appendActionIfAbsent, appendActionOccurrence, appendActionOccurrences, decideAndAppendAction, projectResources } from './actions.ts';
+import { readSubject } from './log.ts';
 import type { ActionProjection, TwinAction, TwinActionPrecondition } from './actions.ts';
 import { observeWorldPaths, worldPaths } from './storage.ts';
 import { getActiveWorldStore } from './world-store.ts';
@@ -699,12 +700,53 @@ export async function applyTwinWrite(
   return {
     result,
     get resource(): TwinResource {
-      return resolved ??= projectResources(service, root).find((r) => r.type === write.subjectType && r.id === answerId)
+      return resolved ??= readSubject(service, write.subjectType, answerId, root)
         ?? ({ id: answerId, type: write.subjectType, updatedAt: landed.occurredAt, ...write.fields } as TwinResource);
     },
   };
 }
 
+/**
+ * Several local writes of one service, landed as `applyTwinWrite` lands each called in turn — the same actions, ids and
+ * order — under one lock and one append (actions.ts `appendActionOccurrences`). Writes that need the one-at-a-time
+ * path take it: a caller's identity (`idempotencyKey`/`actionId`), preconditions, or a head that performs each entry as
+ * it lands. An input is offloaded once per distinct value, as each write's own offload would name it.
+ */
+export async function applyTwinWrites(
+  service: string,
+  writes: readonly TwinWriteInput[],
+  root?: string,
+): Promise<Array<{ result: TwinWriteResult; resource: TwinResource }>> {
+  if (writes.length <= 1 || performsAtHeadNow(service, root) || writes.some((write) => write.idempotencyKey || write.actionId || write.preconditions?.length)) {
+    const out: Array<{ result: TwinWriteResult; resource: TwinResource }> = [];
+    for (const write of writes) out.push(await applyTwinWrite(service, write, root));
+    return out;
+  }
+  // Each distinct input offloaded once (S2 R17): `offloadInput` is content-addressed (a string's blob is named by its
+  // SHA-256), so the result is the one each write's own offload would give, and a command's writes, which share one
+  // recorded request, hash and look up its blob once instead of once per write.
+  const offloaded = new Map<unknown, unknown>();
+  for (const write of writes) if (write.input !== undefined && !offloaded.has(write.input)) offloaded.set(write.input, await offloadInput(service, write.input, root));
+  const committed = appendActionOccurrences(writes.map((write) => actionForTwinWrite(service,
+    write.input === undefined ? write : { ...write, input: offloaded.get(write.input) as TwinWriteInput['input'] })), root);
+  const out: Array<{ result: TwinWriteResult; resource: TwinResource }> = [];
+  for (const [index, { appended, action: landed, placeholder }] of committed.entries()) {
+    const write = writes[index]!;
+    // the head does not perform here (`performsAtHeadNow` was false): this marks the request's deferred group as written
+    if (appended && !placeholder) await performAtHead(service, landed, root);
+    const answerId = write.subjectId;
+    let resolved: TwinResource | undefined;
+    out.push({
+      result: { status: appended ? 'performed' : 'replayed', actionId: landed.id },
+      get resource(): TwinResource {
+        return resolved ??= readSubject(service, write.subjectType, answerId, root)
+          ?? ({ id: answerId, type: write.subjectType, updatedAt: landed.occurredAt, ...write.fields } as TwinResource);
+      },
+    });
+  }
+  return out;
+}
+
 export async function createTwinServer(options: { service: string; root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; stop: () => void }> {
   const readOnly = options.readOnly ?? false;
   const serveOptions = {

package/src/sockets.ts

@@ -6,6 +6,7 @@
 // upgrade through the serve seam, and offers every write to every open session of the vendor, after the write's
 // webhooks. A session's own counters (a sequence number, a heartbeat) are the connection's, never the World's state.
 // Nothing here runs at module scope beyond the empty registry.
+import { worldNow } from './world-clock.ts';
 import type { EventWrite } from './events.ts';
 import type { ScenarioEngine } from './scenario.ts';
 import type { WebSocketPeer, WebSocketUpgrade } from './serve-http.ts';
@@ -48,7 +49,7 @@ export type SocketEngine<C> = {
   close?(session: SocketSession, ctx: C): void | Promise<void>;
 };
 
-type Open = { session: SocketSession; engine: SocketEngine<unknown>; context: () => Promise<unknown>; queue: Promise<void>; pending: Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }> };
+type Open = { session: SocketSession; engine: SocketEngine<unknown>; context: () => Promise<unknown>; queue: Promise<void>; pending: Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout>; due: number }> };
 const sessions = new Map<string, Set<Open>>();
 /** A World's next session number, per World (its service and root): a session's id is the World's, never the
  *  process's, so a life replayed on a fresh World numbers its sessions as it did the first time. */
@@ -60,6 +61,15 @@ export function openSessions(service: string, root: string | undefined, socket:
   return [...(sessions.get(keyOf(service, root)) ?? [])].filter((o) => o.session.socket === socket).map((o) => o.session);
 }
 
+/** What a session awaits that the World's clock has run out (a life's `wait` past a relay's timeout), rejected as the
+ *  machine's clock would reject it; called as the vendor serves a request ("A request answered by a session"). */
+export function expireSocketWaits(service: string, root: string | undefined): void {
+  const open = sessions.get(keyOf(service, root));
+  if (!open?.size) return;
+  const now = Date.parse(worldNow());
+  for (const o of open) for (const [k, p] of o.pending) if (p.due <= now) { clearTimeout(p.timer); o.pending.delete(k); p.reject(new Error('no reply in time')); }
+}
+
 /** Offer a write to every open session of the vendor, each in its turn after what it is already doing. Queued, never
  *  awaited: the write may be one a session's own frame made, which that session finishes before it is told. */
 export function socketWrite(service: string, root: string | undefined, write: EventWrite): void {
@@ -72,21 +82,42 @@ export function socketWrite(service: string, root: string | undefined, write: Ev
   }
 }
 
+/** A declared socket path's parameters for a request's path, or undefined when it does not match: a `{name}` segment
+ *  matches one segment, as an operation's path parameter does (architecture, sockets). */
+function socketParams(declared: string, path: string): Record<string, string> | undefined {
+  const names: string[] = [];
+  const pattern = (declared.replace(/\/+$/, '') || '/').split(/(\{[^}/]+\})/).map((part) => {
+    const name = /^\{([^}/]+)\}$/.exec(part)?.[1];
+    if (name === undefined) return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    names.push(name);
+    return '([^/]+)';
+  }).join('');
+  const hit = new RegExp(`^${pattern}$`).exec(path);
+  if (!hit) return undefined;
+  try { return Object.fromEntries(names.map((name, i) => [name, decodeURIComponent(hit[i + 1]!)])); } catch { return undefined; }
+}
+
 /** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
 export function socketUpgrade<C>(
   service: string,
   root: string | undefined,
   decls: ReadonlyArray<SocketDecl>,
   engines: Record<string, SocketEngine<C>>,
-  context: (request: Request, decl: SocketDecl) => Promise<C>,
+  context: (request: Request, decl: SocketDecl, params: Record<string, string>) => Promise<C>,
   hostOf: (request: Request) => string,
   pathOf: (request: Request) => string = (request) => new URL(request.url).pathname,
   decide: (asked: unknown) => Promise<ScenarioServed | undefined> = async () => undefined,
 ): WebSocketUpgrade {
-  const declFor = (request: Request): SocketDecl | undefined => decls.find((d) => {
+  const matchFor = (request: Request): { decl: SocketDecl; params: Record<string, string> } | undefined => {
     const path = pathOf(request).replace(/\/+$/, '') || '/';
-    return (d.path.replace(/\/+$/, '') || '/') === path && (!d.host || d.host.toLowerCase() === hostOf(request)) && engines[d.id] !== undefined;
-  });
+    for (const d of decls) {
+      if ((d.host && d.host.toLowerCase() !== hostOf(request)) || engines[d.id] === undefined) continue;
+      const params = socketParams(d.path, path);
+      if (params) return { decl: d, params };
+    }
+    return undefined;
+  };
+  const declFor = (request: Request): SocketDecl | undefined => matchFor(request)?.decl;
   const byPeer = new WeakMap<WebSocketPeer, Open>();
   const key = keyOf(service, root);
   return {
@@ -99,7 +130,7 @@ export function socketUpgrade<C>(
       return declared ? offered.find((p) => declared.includes(p)) : offered[0];
     },
     open: (peer, request) => {
-      const decl = declFor(request)!;
+      const { decl, params } = matchFor(request)!;
       const engine = engines[decl.id]! as SocketEngine<unknown>;
       const pending: Open['pending'] = new Map();
       const session: SocketSession = {
@@ -108,7 +139,7 @@ export function socketUpgrade<C>(
         close: (code, reason) => { peer.close(code, reason); },
         expect: (key, ms) => new Promise((resolve, reject) => {
           const timer = setTimeout(() => { pending.delete(key); reject(new Error('no reply in time')); }, ms);
-          pending.set(key, { resolve, reject, timer });
+          pending.set(key, { resolve, reject, timer, due: Date.parse(worldNow()) + ms });
         }),
         fulfil: (key, value) => {
           const p = pending.get(key);
@@ -118,7 +149,7 @@ export function socketUpgrade<C>(
         },
         decide,
       };
-      const o: Open = { session, engine, context: () => context(request.clone(), decl), queue: Promise.resolve(), pending };
+      const o: Open = { session, engine, context: () => context(request.clone(), decl, params), queue: Promise.resolve(), pending };
       byPeer.set(peer, o);
       (sessions.get(key) ?? sessions.set(key, new Set()).get(key)!).add(o);
       if (engine.open) o.queue = o.queue.then(async () => engine.open!(session, await o.context())).catch((error) => session.close(1011, String((error as Error).message ?? error).slice(0, 120)));

package/src/storage.ts

@@ -6,7 +6,7 @@ import {
   GenericWorldStateSchema,
   WorldServiceEventSchema,
 } from './schemas.ts';
-import { getActiveWorldStore } from './world-store.ts';
+import { getActiveWorldStore, storageLockScope, TREE_GENERATION, type WorldLockOptions } from './world-store.ts';
 import { refuseReadOnlyWrite } from './request-scope.ts';
 import { parentEntries, toEvent } from './log.ts';
 import type {
@@ -198,8 +198,8 @@ function appendJsonl(path: string, value: unknown): void {
  *  single-instance store it is a synchronous pass-through. Used to make read-then-append
  *  critical sections atomic. Public so world-runtime can guard concurrent `upWorld`
  *  claims of one instance dir with the SAME lock semantics the event log uses (TWIN-36). */
-export function withFileLock<T>(lockPath: string, fn: () => T): T {
-  return withStateLock(lockPath, fn);
+export function withFileLock<T>(lockPath: string, fn: () => T, options: WorldLockOptions = {}): T {
+  return withStateLock(lockPath, fn, storageLockScope(options));
 }
 
 function writeJsonAtomic(path: string, value: unknown): void {
@@ -385,6 +385,8 @@ const KNOWN_SERVICE_ENTRIES = new Set([
 function isKnownServiceEntry(name: string): boolean {
   // log.ts: the branch pointer and the checkpoint
   if (name === 'branch.json' || name === 'checkpoints') return true;
+  // world-store.ts: the generation a file store keeps beside a tree's files
+  if (name === TREE_GENERATION) return true;
   return KNOWN_SERVICE_ENTRIES.has(name) || name.endsWith('.tmp') || /\.stale\.\d+\.\d+$/.test(name);
 }
 

package/src/vendor-call.ts

@@ -41,6 +41,50 @@ async function worldTwins(): Promise<Record<string, string>> {
   return { ...twinOrigins(env), ...twinOrigins(instanceEnv) };
 }
 
+/** The hosts each claiming twin last listed at its `hostsClaimed` door, by the door's address, and when; read again
+ *  after CLAIMS_TTL_MS or for a host it lacks, as the injector polls the doors every five seconds (inject.cjs, "HOSTS A TWIN CLAIMS WHILE IT
+ *  RUNS"). */
+const claimsRead = new Map<string, { hosts: Set<string>; at: number }>();
+const CLAIMS_TTL_MS = 5_000;
+
+/** The hosts a twin claims at its door: in process (a journey walk's companion) or at its address, within the injector's
+ *  first-read deadline (inject.cjs CLAIMS_WAIT_MS, 1500 ms, measured beside it); a door that does not answer claims
+ *  nothing. */
+async function claimedHosts(at: string, ask: () => Promise<Response>, host: string): Promise<Set<string>> {
+  const held = claimsRead.get(at);
+  // a host the held list lacks is asked for again once, as the injector refreshes before it refuses: a domain claimed a
+  // moment ago is found
+  if (held && Date.now() - held.at < CLAIMS_TTL_MS && held.hosts.has(host)) return held.hosts;
+  let hosts = new Set<string>();
+  try {
+    const r = await ask();
+    const body = r.ok ? await r.json() as { hosts?: unknown[] } : null;
+    hosts = new Set((body?.hosts ?? []).map((h) => String(h).toLowerCase()));
+  } catch { /* an unanswered door claims nothing */ }
+  claimsRead.set(at, { hosts, at: Date.now() });
+  return hosts;
+}
+
+/** The twin that claims a host at its `hostsClaimed` door (an R2 bucket's custom domain, a Worker's), as the injector
+ *  routes it: a twin this process answers first, the World's twins after. */
+async function claimingTwin(target: URL, twins: Record<string, string>): Promise<{ vendor: string; local: boolean } | undefined> {
+  const { packFacts } = await import('../pack-facts.cjs') as { packFacts: () => { packs: Record<string, { hostsClaimed?: { door?: string } }> } };
+  const host = target.hostname.toLowerCase();
+  const key = process.env.VOLTER_TWINS_KEY;
+  const doors = Object.entries(packFacts().packs).flatMap(([vendor, facts]) => (facts.hostsClaimed?.door ? [[vendor, facts.hostsClaimed.door] as const] : []));
+  for (const [vendor, door] of doors) {
+    const twin = inProcessTwins[vendor];
+    if (twin && (await claimedHosts(`in-process:${vendor}${door}`, async () => twin(new Request(`http://${vendor}.twin${door}`)), host)).has(host)) return { vendor, local: true };
+  }
+  for (const [vendor, door] of doors) {
+    const origin = twins[vendor];
+    if (origin === undefined) continue;
+    const at = `${origin.replace(/\/$/, '')}${door}`;
+    if ((await claimedHosts(at, () => fetch(at, { headers: key ? { 'x-twins-key': key } : {}, signal: AbortSignal.timeout(1500) }), host)).has(host)) return { vendor, local: false };
+  }
+  return undefined;
+}
+
 /** One URL answered only by a World-held application or vendor twin: the fetch's application stand-in first (its answer
  *  is the application's; `'unreachable'` leaves no application to reach, the World's twins still reachable). */
 async function worldResponse(target: URL, init: RequestInit, standIn?: ApplicationStandIn): Promise<Response> {
@@ -67,8 +111,18 @@ async function worldResponse(target: URL, init: RequestInit, standIn?: Applicati
     if (key && !headers.has('x-twins-key')) headers.set('x-twins-key', key);
     return fetch(`${twins[vendor]!.replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers, redirect: 'manual' });
   }
+  // the application's own hosts before any twin's claimed ones: a call to the application asks no door
   const { appDestination, appFetch } = await import('../app-route.cjs') as { appDestination: (url: URL) => unknown; appFetch: (url: URL, init: RequestInit) => Promise<Response> };
   if (scripted !== 'unreachable' && appDestination(target)) return appFetch(target, { ...init, redirect: 'manual' });
+  const claimer = await claimingTwin(target, twins);
+  if (claimer !== undefined) {
+    const headers = new Headers(init.headers);
+    headers.set('x-volter-twin-original-host', target.host);
+    if (claimer.local) return inProcessTwins[claimer.vendor]!(new Request(target, { ...init, headers, redirect: 'manual' }));
+    const key = process.env.VOLTER_TWINS_KEY;
+    if (key && !headers.has('x-twins-key')) headers.set('x-twins-key', key);
+    return fetch(`${twins[claimer.vendor]!.replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers, redirect: 'manual' });
+  }
   throw new VendorUnreachableError(`${target.host}${target.pathname}: this World holds no application or vendor twin at this URL`);
 }
 

package/src/world-boot.ts

@@ -0,0 +1,6 @@
+// One private boot answer for the kernel's HTTP and gRPC serve seams.
+// Reading process identity happens on request; importing this helper has no side effects.
+export function worldBootAnswer(boot: string): Response {
+  const pid = (globalThis as { process?: { pid?: number } }).process?.pid;
+  return Response.json({ boot, pid });
+}

package/src/world-clock.ts

@@ -26,10 +26,14 @@ const machineNow = (): number => {
  *  now); real wall-clock time otherwise. */
 export function worldNow(): string {
   const file = process.env[WORLD_CLOCK_ENV];
-  if (file && getActiveWorldStore().exists(file)) {
+  // One read answers both whether the clock file is there and what it holds.
+  // Kept while the clock file's own facts stand (world-store.ts readKept): every operation asks the time.
+  const store = getActiveWorldStore();
+  const held = file ? (store.readKept ? store.readKept(file) : store.read(file)) : null;
+  if (held !== null) {
     // A configured-but-corrupt clock is a WORLD defect — parseClock fails loudly, never silently drifting back to
     // wall-clock (two services disagreeing about now breaks the world).
-    const clock = clockForm.parseClock(getActiveWorldStore().read(file) ?? '');
+    const clock = clockForm.parseClock(held);
     return new Date(clockForm.clockNowMs(clock, machineNow())).toISOString();
   }
   return new Date(machineNow()).toISOString();