@volter/world-core 3.0.154 → 3.0.156

package/dist/src/redis/stream.js

@@ -1,15 +1,38 @@
 import { RedisStatus, commandInteger, commandShapeError, globMatch } from "./engine.js";
 import { binaryBytes, binaryText, inlineCommand, readResp, respReply } from "./frames.js";
-export function createRedisStream(options) {
+import { worldNow } from "../world-clock.js";
+import { redisServiceTimes as times } from "./service-times.js";
+export function createRedisStream(given) {
+    // The pack's run, its time counted for the command it serves (service-times.ts).
+    const options = { ...given, run: async (commands, database) => { const began = times.now(); times.lapFrom(); try {
+            const ran = await given.run(commands, database);
+            if (ran.wrote)
+                times.wrote();
+            return ran;
+        }
+        finally {
+            times.lapEnd('8 answer read by the stream');
+            times.add('run', times.now() - began);
+        } } };
     const sessions = new Set();
-    let nextId = 0, commandCount = 0;
+    let nextId = 0, commandCount = 0, waiting = 0;
     let serial = Promise.resolve();
     const ordered = (f) => { const p = serial.then(f); serial = p.catch(() => { }); return p; };
     const error = (message) => ({ error: message });
     const ok = new RedisStatus('OK');
-    const answer = (s, v) => { if (!s.closed)
-        s.sink.write(binaryBytes(respReply(v))); };
-    const close = (s) => { s.closed = true; if (s.blocked?.timer)
+    const connectionTrace = (s, stage, command) => {
+        try {
+            console.error('[redis-twin-connection]', JSON.stringify({ at: performance.timeOrigin + times.now(), pid: globalThis.process?.pid ?? 0,
+                session: s.id, stage, received: s.received, answered: s.answered, ...(command ? { command } : {}) }));
+        }
+        catch { /* diagnostic output cannot change a connection */ }
+    };
+    const answer = (s, v) => { if (!s.closed) {
+        times.timed('reply', () => s.sink.write(binaryBytes(respReply(v))));
+        s.answered += 1;
+    } };
+    const close = (s) => { if (!s.closed)
+        connectionTrace(s, 'closed'); s.closed = true; if (s.blocked?.timer)
         clearTimeout(s.blocked.timer); sessions.delete(s); };
     const unblock = (s, v) => { if (s.blocked?.timer)
         clearTimeout(s.blocked.timer); s.blocked = undefined; answer(s, v); queueMicrotask(() => { void s.pump?.(); }); };
@@ -26,12 +49,26 @@ export function createRedisStream(options) {
         }
         throw new Error('the blocking command has no executor');
     };
-    const wake = async () => { for (const s of sessions)
-        if (s.blocked) {
+    // A CLIENT BLOCKED ON KEYS IS ASKED AGAIN ONLY WHEN ONE OF ITS KEYS WAS WRITTEN. Every write asked every blocked
+    // client again, each ask a whole run for each of its keys: Twenty's queue workers hold a blocked client apiece, and
+    // its twin made 59 to 89 runs for 31 to 41 commands in a two-second window, each run about 20 ms, with every
+    // other command waiting behind them (Twenty 51: commands waited 0.6 to 5.9 s). `touched` is the keys the run
+    // wrote, by name, whatever its database (a name written in another database asks a client that then finds
+    // nothing, never the reverse). Without it (an EXEC's queue, a run that does not say, a command that writes
+    // another database's keys) every blocked client is asked, as before.
+    const wake = async (touched) => {
+        for (const s of sessions) {
+            if (!s.blocked)
+                continue;
+            if (touched && !s.blocked.command.slice(1, -1).some((key) => touched.includes(key)))
+                continue;
             const v = await blockRun(s, s.blocked.command);
             if (v !== null)
                 unblock(s, v);
-        } };
+        }
+    };
+    /** Commands that write keys of a database other than their session's: their run's `touched` does not name them all. */
+    const CROSS_DATABASE = new Set(['MOVE', 'COPY', 'SWAPDB']);
     const command = async (s, argv, executing = false) => {
         if (!argv.length || s.closed)
             return;
@@ -272,12 +309,32 @@ export function createRedisStream(options) {
                 }
                 const initial = await options.run([], s.database);
                 s.blocked = { command: argv, deadline: timeout === 0 ? Infinity : (initial.instant ?? 0) + timeout };
-                const poll = () => { if (!s.blocked || s.closed)
-                    return; s.blocked.timer = setTimeout(() => { void ordered(async () => { if (!s.blocked)
-                    return; const now = await options.run([], s.database); if ((now.instant ?? 0) >= s.blocked.deadline)
-                    unblock(s, null);
-                else
-                    poll(); }); }, 50); };
+                // A BLOCKED CLIENT WAITS FOR A WRITE OR ITS DEADLINE, AND ASKS THE TREE NOTHING MEANWHILE. A write through this
+                // twin wakes it (wake, after every command that wrote). Its deadline is in the World's time, so the timer
+                // reads the World's clock (world-clock.ts worldNow: one check of the clock file, kept while it stands) and
+                // nothing else. It ran a whole empty request every 50 ms to read that time: the pack's fetch, its context
+                // and the keyspace's image with its tree stamp, for every blocked client, the whole time it was blocked.
+                // Twenty's queue workers each hold one blocked client: its Redis twin made about 18,700 stamps in a run, 56,145
+                // stat requests, and spent 55 s of 114 busy in them, with no command to answer. No timeout is no timer; a
+                // deadline far off is checked less often, never more than a second apart, and to 50 ms as it nears.
+                const poll = () => {
+                    if (!s.blocked || s.closed || s.blocked.deadline === Infinity)
+                        return;
+                    let left;
+                    try {
+                        left = s.blocked.deadline - Date.parse(worldNow());
+                    }
+                    catch (cause) {
+                        unblock(s, error(`ERR twin: ${cause instanceof Error ? cause.message : String(cause)}`.replace(/[\r\n]+/g, ' ')));
+                        return;
+                    }
+                    if (left <= 0) {
+                        void ordered(async () => { if (s.blocked)
+                            unblock(s, null); });
+                        return;
+                    }
+                    s.blocked.timer = setTimeout(poll, Math.max(50, Math.min(1000, left / 2)));
+                };
                 poll();
                 return;
             }
@@ -286,17 +343,45 @@ export function createRedisStream(options) {
                 const item = res.items[0];
                 answer(s, 'error' in item ? item : item.result);
                 if (res.wrote && !executing)
-                    await wake();
+                    await wake(CROSS_DATABASE.has(cmd) ? undefined : res.touched);
             }
         }
     };
     return (sink) => {
-        const s = { id: ++nextId, name: '', lib: {}, database: '0', authenticated: !options.password, queue: null, dirty: false, subscriptions: new Set(), patterns: new Set(), sink, closed: false };
+        const s = { id: ++nextId, name: '', lib: {}, database: '0', authenticated: !options.password, queue: null, dirty: false, subscriptions: new Set(), patterns: new Set(), sink, closed: false, received: 0, answered: 0 };
         sessions.add(s);
+        connectionTrace(s, 'opened');
         let buffer = '', chain = Promise.resolve();
         const pending = [];
-        const pump = async () => { while (pending.length && !s.blocked && !s.closed)
-            await ordered(() => command(s, pending.shift())); };
+        // A command whose storage fails (a World storage lock that timed out, a write that could not be made) answers its
+        // client with an error and the session goes on, as Redis answers one failed command: it was an unhandled
+        // rejection, and the twin's process exited with every client's connection (Twenty 46).
+        const pump = async () => {
+            while (pending.length && !s.blocked && !s.closed) {
+                const { argv, received } = pending.shift();
+                try {
+                    await ordered(async () => {
+                        waiting -= 1;
+                        times.begin(received, waiting, { session: s.id, command: argv[0]?.toUpperCase().slice(0, 32) ?? '' });
+                        let threw = false;
+                        try {
+                            await command(s, argv);
+                        }
+                        catch (cause) {
+                            threw = true;
+                            throw cause;
+                        }
+                        finally {
+                            times.end(threw);
+                        }
+                    });
+                }
+                catch (cause) {
+                    if (!s.closed)
+                        answer(s, error(`ERR twin: ${cause instanceof Error ? cause.message : String(cause)}`.replace(/[\r\n]+/g, ' ')));
+                }
+            }
+        };
         s.pump = pump;
         return {
             data(chunk) { if (s.closed)
@@ -321,7 +406,11 @@ export function createRedisStream(options) {
                         end = at + 2;
                     }
                     buffer = buffer.slice(end);
-                    pending.push(argv);
+                    pending.push({ argv, received: times.now() });
+                    waiting += 1;
+                    s.received += 1;
+                    if (s.received === 1)
+                        connectionTrace(s, 'first-command', argv[0]?.toUpperCase().slice(0, 32));
                 }
                 chain = chain.then(pump);
             }
@@ -331,7 +420,7 @@ export function createRedisStream(options) {
                 sink.end();
             } },
             settled: () => chain,
-            close: () => close(s),
+            close: () => { waiting -= pending.length; pending.length = 0; close(s); },
         };
     };
 }

package/dist/src/runtime-state.d.ts

@@ -0,0 +1,11 @@
+export { getActiveWorldStore, removeCarriedLocks } from './world-store.js';
+export type { WorldStore } 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-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

@@ -38,7 +38,7 @@ 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 { 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';
@@ -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

@@ -55,7 +55,7 @@ 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 { 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";
@@ -104,3 +106,4 @@ export { captureHistory, captureParentHistory, historyChanges, historyAtInstant,
 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';
@@ -60,9 +77,9 @@ export async function serveHttp(options) {
             } : {}),
         });
         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) => { await server.stop(closeActive); } }, 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/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/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();