@volter/world-core 3.0.155 → 3.0.157

package/dist/src/runtime-state.js

@@ -0,0 +1,13 @@
+// The lifecycle's state/identity primitives. Re-export their canonical modules
+// so the active store, locks and scopes are shared with the full runtime and packs.
+// Booting an empty World does not require pack registration or derived engines.
+export { getActiveWorldStore, removeCarriedLocks } from "./world-store.js";
+export { stateDirName, withFileLock, worldPaths, worldStateRoot, WORLD_DATA_ENV } from "./storage.js";
+export { assertStateRemovable, withAncestryLock, withStateRemoval } from "./ancestry.js";
+export { readBranchMeta } from "./log.js";
+export { volterHome } from "./volter-home.js";
+export { installedPackageDir, installedVendorPacks, isDerivedPack, packRepository, vendorOfPackModule } from "./pack-paths.js";
+export { PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from "./protocol.js";
+export { WORLD_BOOT_PATH } from "./serve-http.js";
+export { WORLD_ENV_NAMES_ENV } from "./world-env.js";
+export { beginPlaceholderPull, endPlaceholderPull, placeholderPullActive } from "./placeholder-remote.js";

package/dist/src/runtime.d.ts

@@ -36,9 +36,9 @@ export type { WorldStore, WorldStat, HydrationSource, HydrationSink } from './wo
 export type { CheckLoader } from './head.js';
 export { SqlWorldStore } from './world-store-sql.js';
 export type { SqlExec } from './world-store-sql.js';
-export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, } from './blob-store.js';
-export type { BlobStore } from './blob-store.js';
-export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, callerForHeader, callerFromHeader, journalTwinRequest, readTwinRequestJournalFrom, type TwinRequestJournalCursor, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, recordedInput, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from './serve.js';
+export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, streamChunks, writeBlobStream, } from './blob-store.js';
+export type { BlobStore, BlobWritten } from './blob-store.js';
+export { applyTwinWrite, applyTwinWrites, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, callerForHeader, callerFromHeader, journalTwinRequest, readTwinRequestJournalFrom, type TwinRequestJournalCursor, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, recordedInput, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from './serve.js';
 export type { AtomicTwinWriteDecision, TwinRequestJournalEntry, TwinResource, TwinWriteInput, TwinWriteResult, } from './serve.js';
 export { createTwinProxy } from './proxy.js';
 export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.js';
@@ -52,6 +52,7 @@ export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType,
 export { installedPackageDir, installedVendorPacks, packVendor, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from './pack-paths.js';
 export * as git from './git/index.js';
 export * as s3 from './s3/wire.js';
+export * as xml from './xml.js';
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from './placeholder-remote.js';
 export { aliasesFrom, ownFields, subjectHistory, rebaseBranch, cutCheckpoint, appendParentEntry, wholeLog, branchEntries, branchLogPath, branchMetaPath, CHECKPOINT_EVERY, dropCheckpoint, foldEntries, landedCopy, landedIds, parentEntries, parentLogPath, position, readBranchMeta, readTree, toEntry, toEvent, unpushedEntries, writeBranchMeta } from './log.js';
 export type { BranchMeta, Entry, EntryOp, Receipt } from './log.js';
@@ -69,7 +70,7 @@ export { observeResource, observeResources, collectObservations, foldObservation
 export type { ObservedResource, ObserveReport, Observation } from './observe.js';
 export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntries, appendOriginEntry, originLogPath, isUrlParent, parentPosition, positionAt, splitsBatch, assertBatchBoundary } from './log.js';
 export { referenceField, registerReferences, packReferences, resolveReferences, type ReferenceDeclaration } from './references.js';
-export { serveHttp, serveStream, connectWebSocket, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.js';
+export { serveHttp, serveStream, connectWebSocket, nodeBuiltin, servedHandlerOf, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.js';
 export { fileResponse, contentTypeOf } from './file-response.js';
 export { bundleClient, filePathOf } from './client-bundle.js';
 export { brandTokensResponse } from './brand-tokens.js';
@@ -78,7 +79,7 @@ export { corsHeaders, withCors, type CorsDecl } from './cors.js';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.js';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.js';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.js';
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from './resource-blob.js';
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from './ancestry.js';
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from './history.js';
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.js';
@@ -86,3 +87,4 @@ export { foldHistory } from './log.js';
 export { volterHome } from './volter-home.js';
 export type { MachinePool, MachineSpec, MachineProcess, MachineStatus, MachineFiles, MachineFileStat, GuestImage, LightPoolOptions } from './machines.js';
 export { boardFrameKey } from './board-keys.js';
+export * as managedOriginalInputs from './managed-original-inputs.js';

package/dist/src/runtime.js

@@ -54,8 +54,8 @@ export { FsWorldStore, MemoryWorldStore, getActiveWorldStore, setActiveWorldStor
 export { SqlWorldStore } from "./world-store-sql.js";
 // The blob seam (runtime contract R11): byte storage behind byte-carrying handlers, so a
 // serverless namespace puts bytes in object storage while local worlds keep today's layout.
-export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, } from "./blob-store.js";
-export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, callerForHeader, callerFromHeader, journalTwinRequest, readTwinRequestJournalFrom, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, recordedInput, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from "./serve.js";
+export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, streamChunks, writeBlobStream, } from "./blob-store.js";
+export { applyTwinWrite, applyTwinWrites, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, callerForHeader, callerFromHeader, journalTwinRequest, readTwinRequestJournalFrom, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, recordedInput, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from "./serve.js";
 export { createTwinProxy } from "./proxy.js";
 export { forkTwin, isFork, readForkMeta, } from "./fork.js";
 export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";
@@ -73,6 +73,8 @@ export { installedPackageDir, installedVendorPacks, packVendor, packRepository,
 export * as git from "./git/index.js";
 // 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.js";
+// Generic strict XML grammar; vendor interpretation remains in its consumer.
+export * as xml from "./xml.js";
 // The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
 // The placeholder remote (contract section of that name): the seed is a pull, never a pending write.
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from "./placeholder-remote.js";
@@ -88,7 +90,7 @@ export { observeResource, observeResources, collectObservations, foldObservation
 export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntries, appendOriginEntry, originLogPath, isUrlParent, parentPosition, positionAt, splitsBatch, assertBatchBoundary } from "./log.js";
 export { referenceField, registerReferences, packReferences, resolveReferences } from "./references.js";
 // the HTTP server seam: the one place the serve path meets the runtime (Bun or Node)
-export { serveHttp, serveStream, connectWebSocket, nodeBuiltin, WORLD_BOOT_PATH } from "./serve-http.js";
+export { serveHttp, serveStream, connectWebSocket, nodeBuiltin, servedHandlerOf, WORLD_BOOT_PATH } from "./serve-http.js";
 // two runtime-neutral helpers for a serve path: a file as a Response, a page's client bundle
 export { fileResponse, contentTypeOf } from "./file-response.js";
 export { bundleClient, filePathOf } from "./client-bundle.js";
@@ -98,9 +100,10 @@ export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBou
 export { corsHeaders, withCors } from "./cors.js";
 export { setInProcessTwins, vendorFetch, VendorUnreachableError } from "./vendor-call.js";
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver } from "./managed-database.js";
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from "./resource-blob.js";
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from "./resource-blob.js";
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from "./ancestry.js";
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from "./history.js";
 export { foldHistory } from "./log.js";
 export { volterHome } from "./volter-home.js";
 export { boardFrameKey } from "./board-keys.js";
+export * as managedOriginalInputs from "./managed-original-inputs.js";

package/dist/src/serve-http.d.ts

@@ -45,6 +45,8 @@ export type HttpServer = {
 export declare function setServeDecorator(fn: ((options: ServeHttpOptions) => HttpHandler) | undefined): void;
 /** The path a World asks a service it booted, when that service's port answers, which boot it belongs to. */
 export declare const WORLD_BOOT_PATH = "/__volter/world-boot";
+/** The handler serving `port` in this process, when a server made through the seam listens there. */
+export declare function servedHandlerOf(port: number): HttpHandler | undefined;
 export declare function serveHttp(options: ServeHttpOptions): Promise<HttpServer>;
 /** A Node builtin without a static import — `process.getBuiltinModule` (Node 22.3+, Bun): what a
  *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`

package/dist/src/serve-http.js

@@ -4,9 +4,10 @@
 // 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 { worldBootAnswer } from "./world-boot.js";
 /** One socket library at the host seam, shared by inbound upgrades and authenticated outbound relays. */
 const socketLibrary = () => import('ws');
 export async function connectWebSocket(url, headers, protocols = []) {
@@ -19,6 +20,22 @@ export function setServeDecorator(fn) { decorate = fn; }
 const bunRuntime = () => { const b = globalThis.Bun; return b && typeof b.serve === 'function' ? b : undefined; };
 /** 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 = () => (globalThis[Symbol.for('volter.servedHandlers')] ??= new Map());
+/** The handler serving `port` in this process, when a server made through the seam listens there. */
+export function servedHandlerOf(port) { return servedHandlers().get(port); }
+/** A server's handler kept by its port until the server stops. */
+function keepHandler(server, handler) {
+    const port = server.port;
+    if (!port)
+        return server;
+    servedHandlers().set(port, handler);
+    return { ...server, stop: async (closeActive) => { if (servedHandlers().get(port) === handler)
+            servedHandlers().delete(port); await server.stop(closeActive); } };
+}
 export async function serveHttp(options) {
     // 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.
@@ -33,7 +50,7 @@ export async function serveHttp(options) {
     const worldBoot = globalThis.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';
@@ -43,6 +60,37 @@ export async function serveHttp(options) {
         // 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();
+        const inflight = new Set();
+        const served = options.fetch;
+        const tracked = (request, ...rest) => {
+            inflight.add(request);
+            let answer;
+            try {
+                answer = served(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, server) => {
@@ -53,16 +101,35 @@ export async function serveHttp(options) {
                     return options.fetch(request);
                 },
                 websocket: {
-                    open: (peer) => upgrade.open(peer, peer.data.request),
+                    open: (peer) => { live.add(peer); return upgrade.open(peer, peer.data.request); },
                     message: (peer, data) => upgrade.message(peer, data),
-                    close: upgrade.close,
+                    close: (peer, ...rest) => { live.delete(peer); return upgrade.close(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.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);
 }
 /** A Node builtin without a static import — `process.getBuiltinModule` (Node 22.3+, Bun): what a
  *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`

package/dist/src/serve.d.ts

@@ -184,6 +184,16 @@ export declare function applyTwinWrite(service: string, write: TwinWriteInput, r
     result: TwinWriteResult;
     resource: 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 declare function applyTwinWrites(service: string, writes: readonly TwinWriteInput[], root?: string): Promise<Array<{
+    result: TwinWriteResult;
+    resource: TwinResource;
+}>>;
 export declare function createTwinServer(options: {
     service: string;
     root?: string;

package/dist/src/serve.js

@@ -12,12 +12,13 @@ import { parseExactJson } from "./exact-json.js";
 // 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 } from "./serve-http.js";
-import { performAtHead } from "./head.js";
+import { performAtHead, performsAtHeadNow } from "./head.js";
 import { withHeaders } from "./with-headers.js";
 import { createHash } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import { hashFieldValue } from "./hash.js";
-import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, projectResources } from "./actions.js";
+import { appendActionIfAbsent, appendActionOccurrence, appendActionOccurrences, decideAndAppendAction, projectResources } from "./actions.js";
+import { readSubject } from "./log.js";
 import { observeWorldPaths, worldPaths } from "./storage.js";
 import { getActiveWorldStore } from "./world-store.js";
 import { getActiveBlobStore } from "./blob-store.js";
@@ -596,11 +597,50 @@ export async function applyTwinWrite(service, write, root) {
     return {
         result,
         get resource() {
-            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 };
         },
     };
 }
+/**
+ * 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, writes, root) {
+    if (writes.length <= 1 || performsAtHeadNow(service, root) || writes.some((write) => write.idempotencyKey || write.actionId || write.preconditions?.length)) {
+        const out = [];
+        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();
+    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) })), root);
+    const out = [];
+    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;
+        out.push({
+            result: { status: appended ? 'performed' : 'replayed', actionId: landed.id },
+            get resource() {
+                return resolved ??= readSubject(service, write.subjectType, answerId, root)
+                    ?? { id: answerId, type: write.subjectType, updatedAt: landed.occurredAt, ...write.fields };
+            },
+        });
+    }
+    return out;
+}
 export async function createTwinServer(options) {
     const readOnly = options.readOnly ?? false;
     const serveOptions = {

package/dist/src/sockets.d.ts

@@ -44,8 +44,11 @@ export type SocketEngine<C> = {
 };
 /** The open sessions of one socket of the vendor in a World (a handler reaches them as `ctx.sockets(id)`). */
 export declare function openSessions(service: string, root: string | undefined, socket: string): SocketSession[];
+/** 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 declare function expireSocketWaits(service: string, root: string | undefined): void;
 /** 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 declare function socketWrite(service: string, root: string | undefined, write: EventWrite): void;
 /** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
-export declare function socketUpgrade<C>(service: string, root: string | undefined, decls: ReadonlyArray<SocketDecl>, engines: Record<string, SocketEngine<C>>, context: (request: Request, decl: SocketDecl) => Promise<C>, hostOf: (request: Request) => string, pathOf?: (request: Request) => string, decide?: (asked: unknown) => Promise<ScenarioServed | undefined>): WebSocketUpgrade;
+export declare function socketUpgrade<C>(service: string, root: string | undefined, decls: ReadonlyArray<SocketDecl>, engines: Record<string, SocketEngine<C>>, context: (request: Request, decl: SocketDecl, params: Record<string, string>) => Promise<C>, hostOf: (request: Request) => string, pathOf?: (request: Request) => string, decide?: (asked: unknown) => Promise<ScenarioServed | undefined>): WebSocketUpgrade;

package/dist/src/sockets.js

@@ -1,3 +1,12 @@
+// A vendor's persistent wire (architecture, "Other wires: sockets"): a WebSocket its clients hold open, on which the
+// vendor sends what happens as it happens (Discord's Gateway: a bot identifies, is told the guilds it is in, and is sent
+// each message, member and interaction as it lands). The manifest declares the socket (`sockets`); the pack's engine
+// (`semantics/sockets.ts`, one export per socket id) speaks its protocol: what a session is sent when it opens, what it
+// answers each frame, and which frames a write of the World sends it. The kernel holds the open sessions, serves the
+// 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.js";
 const sessions = new Map();
 /** 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. */
@@ -7,6 +16,21 @@ const keyOf = (service, root) => `${service}\0${root ?? ''}`;
 export function openSessions(service, root, 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, root) {
+    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, root, write) {
@@ -20,12 +44,41 @@ export function socketWrite(service, root, write) {
         o.queue = o.queue.then(async () => engine.write(o.session, write, await o.context())).catch((error) => o.session.close(1011, String(error.message ?? error).slice(0, 120)));
     }
 }
+/** 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, path) {
+    const names = [];
+    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(service, root, decls, engines, context, hostOf, pathOf = (request) => new URL(request.url).pathname, decide = async () => undefined) {
-    const declFor = (request) => decls.find((d) => {
+    const matchFor = (request) => {
         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) => matchFor(request)?.decl;
     const byPeer = new WeakMap();
     const key = keyOf(service, root);
     return {
@@ -38,7 +91,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
             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];
             const pending = new Map();
             const session = {
@@ -47,7 +100,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
                 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);
@@ -60,7 +113,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
                 },
                 decide,
             };
-            const o = { session, engine, context: () => context(request.clone(), decl), queue: Promise.resolve(), pending };
+            const o = { 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)

package/dist/src/storage.d.ts

@@ -1,3 +1,4 @@
+import { type WorldLockOptions } from './world-store.js';
 import type { AppendEventResult, GenericWorldState, WorldPaths, WorldReducer, WorldServiceEvent } from './types.js';
 /**
  * Name of the per-project state directory holding world data
@@ -60,7 +61,7 @@ export declare function twinLog(kind: string, details: Record<string, unknown>):
  *  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 declare function withFileLock<T>(lockPath: string, fn: () => T): T;
+export declare function withFileLock<T>(lockPath: string, fn: () => T, options?: WorldLockOptions): T;
 /** The parent log as observed rows: every entry the branch inherited or landed, as
  *  observed rows (log.ts `toEvent`). A branched world sees its base world's logs to the branch
  *  position first. */

package/dist/src/storage.js

@@ -3,7 +3,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { withStateLock, withStateRemoval } from "./ancestry.js";
 import { appendParentEntry, toEntry } from "./log.js";
 import { GenericWorldStateSchema, WorldServiceEventSchema, } from "./schemas.js";
-import { getActiveWorldStore } from "./world-store.js";
+import { getActiveWorldStore, storageLockScope, TREE_GENERATION } from "./world-store.js";
 import { refuseReadOnlyWrite } from "./request-scope.js";
 import { parentEntries, toEvent } from "./log.js";
 function nowIso() {
@@ -181,8 +181,8 @@ function appendJsonl(path, value) {
  *  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(lockPath, fn) {
-    return withStateLock(lockPath, fn);
+export function withFileLock(lockPath, fn, options = {}) {
+    return withStateLock(lockPath, fn, storageLockScope(options));
 }
 function writeJsonAtomic(path, value) {
     getActiveWorldStore().writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
@@ -327,6 +327,9 @@ function isKnownServiceEntry(name) {
     // 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);
 }
 /** A service dir "looks like" one of ours when every entry in it is something

package/dist/src/vendor-call.js

@@ -34,6 +34,52 @@ async function worldTwins() {
     }
     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();
+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, ask, host) {
+    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();
+    try {
+        const r = await ask();
+        const body = r.ok ? await r.json() : 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, twins) {
+    const { packFacts } = await import('../pack-facts.cjs');
+    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]] : []));
+    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, init, standIn) {
@@ -61,9 +107,21 @@ async function worldResponse(target, init, standIn) {
             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');
     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`);
 }
 /** A vendor URL (or the World's application), including redirects, always answered inside the World; `standIn` is the

package/dist/src/world-boot.d.ts

@@ -0,0 +1 @@
+export declare function worldBootAnswer(boot: string): Response;

package/dist/src/world-boot.js

@@ -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) {
+    const pid = globalThis.process?.pid;
+    return Response.json({ boot, pid });
+}

package/dist/src/world-clock.js

@@ -23,10 +23,14 @@ const machineNow = () => {
  *  now); real wall-clock time otherwise. */
 export function worldNow() {
     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();