@volter/world-core 3.0.155 → 3.0.156

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();

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

@@ -7,6 +7,17 @@ export type WorldStat = {
     isDirectory: boolean;
     isSymbolicLink?: boolean;
 };
+/** Diagnostic context only; it does not change lock acquisition or stale-owner policy. */
+export type WorldLockOptions = {
+    retainLiveOwner?: boolean;
+    operation?: string;
+    caller?: string;
+};
+/** Capture at the outermost lock helper, then carry the same caller through nested helpers. */
+export declare function storageLockScope(options?: WorldLockOptions): WorldLockOptions & {
+    operation: string;
+    caller: string;
+};
 /**
  * The synchronous persistence seam. Every path is an ABSOLUTE key the caller already
  * computed (via `worldPaths`/`worldStateRoot`); the store treats it as an opaque key,
@@ -51,13 +62,57 @@ export interface WorldStore {
     readRange?(path: string, start: number): string | null;
     /** Resolve filesystem aliases for durable ownership; absent on opaque-key stores. */
     canonicalPath?(path: string): string;
+    /** `read`, for a small file every operation needs and few change (a branch's pointer, the World's clock): the text
+     *  kept from the last read while the path's own facts stand, so an unchanged file costs one check and no read.
+     *  Optional: a store without it is read. */
+    readKept?(path: string): string | null;
+    /** The facts of the generation kept beside a tree's files in `dirPath` (TREE_FILES): one string that differs after
+     *  any write of one of them through a store, by this process or another; `null` where the directory has none yet,
+     *  which says nothing. Optional: a store without it is asked for each file's own facts. */
+    generation?(dirPath: string): string | null;
+    /** The generation in `dirPath` now, when exactly one write of a tree's file through a store has moved it since
+     *  `before` (a generation this store answered for it); `null` when it cannot say so. A writer that read `before` just
+     *  ahead of its own write, holding the directory's history lock, learns that its write was the only one (log.ts
+     *  appendToBranchLog). Optional, beside `generation`. */
+    generationAfterOwnWrite?(dirPath: string, before: string): string | null;
     /** Run `fn` holding an exclusive lock on `lockPath`, releasing it afterwards. The fs
      *  backend uses the historical cross-process reclaimable file lock; an in-memory,
      *  single-instance backend is a synchronous pass-through. */
-    withLock<T>(lockPath: string, fn: () => T, options?: {
-        retainLiveOwner?: boolean;
-    }): T;
+    withLock<T>(lockPath: string, fn: () => T, options?: WorldLockOptions): T;
 }
+/** The files a service's tree is folded from, by name in its state directory (log.ts: the parent log, the branch log,
+ *  the branch's pointer), and the generation a store keeps beside them. */
+export declare const TREE_FILES: {
+    readonly parent: "events.jsonl";
+    readonly branch: "actions.jsonl";
+    readonly pointer: "branch.json";
+};
+export declare const TREE_GENERATION = "tree.generation";
+/**
+ * A WORLD'S CARRIED LOCKS, REMOVED AT ITS OPEN (S2 K4). A World booted over its kept state (`up --keep-state`, a
+ * tab's restored archive) carries whatever lock files its last life left in its services' state directories. One whose
+ * holder record cannot be read is no holder's once its taker has gone, and a restore gives it the restore's file time,
+ * so the empty-record grace and the 60 s age ran from the restore: every waiter waited them, or gave up at 10 s (Twenty
+ * e946aa4c run 2: anthropic's projection.lock, "holder record unreadable", 10,086 ms, then its credentials 500 and the
+ * server 10 s late). A carried `.recovery` that is not empty and does not parse was never ended by R13's rule at all.
+ *
+ * A file is carried only when all of these hold: it is a world-core lock or its reclaim record (`*.lock`,
+ * `*.lock.recovery`) in a service's state directory (`<root>/<service>/<stateDir>/world`, never a yarn.lock or any
+ * project file); its text is empty or a holder record's beginning (`{"pid"`) that does not parse; and its file time is
+ * before `before`, the start of this boot's claim. A restore sets the time before the claim; a taker that is live now
+ * (a CLI's changeset rebase, a branch World keeping this one as its parent's storage, a two-call taker between its
+ * create and its record) made its file after it. Each removal is still a reclaimer's: a lock's under its `.recovery`,
+ * taken with its record (createRecorded), a held `.recovery` skipped; the file read again, renamed aside, the aside copy
+ * read again and linked back where it now holds a record (EEXIST there is the path taken since, left to its holder).
+ * A record that parses is kept, under its rules (a dead holder's, our own pid's, the 60 s age, which a restore resets:
+ * not this rule's). Answers the paths removed.
+ */
+export declare function removeCarriedLocks(roots: readonly string[], options: {
+    stateDir: string;
+    before: number;
+}): string[];
+/** Name a bookkeeping phase within an existing acquisition; never acquire another lock. */
+export declare function withStorageLockOperation<T>(path: string, operation: string, fn: () => T): T;
 /**
  * The default store: a thin, faithful pass-through to `node:fs`. Every method preserves
  * the exact behavior the kernel had before the seam existed — the durable append
@@ -66,6 +121,51 @@ export interface WorldStore {
  */
 export declare class FsWorldStore implements WorldStore {
     read(path: string): string | null;
+    /**
+     * A small file's text, kept while its own facts stand. THE GUARANTEE: the key is the path's own lstat (device,
+     * inode, size, modification and change times); this process's own writes through the store drop what is kept at
+     * once; another process's write is seen when any of those facts moves. That is the guarantee a tree's stamp
+     * already rests on for its logs (their size and modification time), with the inode and change time added: a
+     * replaced file (writeAtomic) is another inode, a file written in place has another time. What it cannot see is a
+     * rewrite to the same size on the same or a reused inode within one tick of the file system's clock, with no check
+     * between; the logs' stamp has the same limit. A link is read through, and not kept.
+     * A text read after a write that came between the lstat and the read is kept under the OLDER key, so the next
+     * check finds the facts moved and reads again: what is kept is never newer than its key, and never served past it.
+     */
+    private readonly kept;
+    readKept(path: string): string | null;
+    /**
+     * A TREE'S GENERATION: one file beside a tree's three files, a byte longer after every write of any of them, so a
+     * reader that has the tree's stamp asks ONE question to know it still stands (log.ts treeFacts), where it asked
+     * three, two of them of files a World with no parent does not have.
+     *
+     * WHAT MAKES IT SOUND. A writer appends a byte BEFORE its write and another AFTER it; a reader takes the
+     * generation's facts BEFORE it reads the files' own. The file only grows, so its size never repeats on one inode,
+     * and a replaced or removed file is another inode or none. So for any write W and any reader that kept a stamp S
+     * under generation G: if W's first byte is after G was read, the kept G is behind and S is not served; if it is
+     * before, then either W itself was before S's own reads (S holds it), or W's second byte is after G was read, and
+     * again G is behind. An append is one call the system orders among all writers: each byte is one append of its
+     * own, whole or not at all, on a POSIX filesystem and in a tab's one kernel (browser-substrate
+     * packages/node/src/kernel-virtual-filesystem.ts appendFileSync, an O_APPEND open and writeAll, which sends a write
+     * of at most DATA_BYTES as one SYS_write request the kernel serves whole; or, by a file step, its table's own
+     * O_APPEND open and write of the one byte, filesystem.ts appendFileBytes). The proof rests on that; log.ts
+     * appendToBranchLog's (`generationAfterOwnWrite`: one write is exactly two bytes) as well.
+     *
+     * WHERE THAT STOPS. (1) A writer that dies between its write and its second byte, with a reader's whole check
+     * between its first byte and its write: that reader keeps the older stamp until the next write of the tree. (2) A
+     * writer of these files that does not come through a store of this version (an older package, a copy made over a
+     * live directory by another program): the generation does not move. A directory made or removed whole has no
+     * generation or another's, which serves nothing kept. (3) A stamp that names files outside its own directory (a
+     * World with a parent: its view and its ancestors' logs) is never kept under a generation (log.ts).
+     */
+    generation(dirPath: string): string | null;
+    /** One write is `moved` twice, a byte each: the same file, those two bytes longer. */
+    generationAfterOwnWrite(dirPath: string, before: string): string | null;
+    /** One more byte on the generation beside `path`, where `path` is one of a tree's files. A directory that is not
+     *  there has no reader to tell: the write that makes it is followed by the byte that makes its generation. */
+    private moved;
+    /** A write of `path`, with the generation beside it moved before and after where it is one of a tree's files. */
+    private writing;
     readLines(path: string): string[];
     readRange(path: string, start: number): string | null;
     append(path: string, data: string): void;
@@ -79,17 +179,18 @@ export declare class FsWorldStore implements WorldStore {
     remove(path: string): void;
     mkdir(dirPath: string): void;
     list(dirPath: string): string[];
+    /** The real path of each path already resolved: a state directory's does not move under a running process, and
+     *  every history lock asked for it again. A path that does not exist yet is not kept. */
+    private readonly canonical;
     canonicalPath(path: string): string;
     stat(path: string): WorldStat | null;
     /** Run `fn` holding an exclusive cross-process file lock. The lockfile records
-     *  `{pid, hostname, at}`; a contender that finds a stale lock (dead pid or age >
+     *  identity, operation, caller and any nested wait; a contender that finds a stale lock (dead pid or age >
      *  LOCK_STALE_MS) reclaims it by atomically renaming it aside — so a crashed holder
      *  can't wedge the world forever. Reclaim is race-safe: only the process that wins
      *  the rename clears the stale inode, and the exclusive `wx` create still decides the
      *  winner. (Moved verbatim from storage.ts `withFileLock`.) */
-    withLock<T>(lockPath: string, fn: () => T, options?: {
-        retainLiveOwner?: boolean;
-    }): T;
+    withLock<T>(lockPath: string, fn: () => T, options?: WorldLockOptions): T;
 }
 /**
  * An in-memory store. Files are entries in a `Map<path, string>`; directories are