@volter/world-core 2.0.37 → 3.0.0

package/dist/inject.cjs

@@ -13,8 +13,7 @@
 //   e.g. STRIPE_TWIN_URL=http://127.0.0.1:12111 or a hosted skin URL
 //   {twinsUrl}/{org}/{world}/{vendor} with VOLTER_TWINS_KEY set (R7c). Host claims come
 //   from pack-facts at runtime — this file carries no per-vendor roster to rot.
-//   AWS service-areas (DYNAMODB/TIMESTREAM/SESV2/SECRETSMANAGER/BEDROCK_TWIN_URL) point at
-//   the consolidated `aws` twin, same as S3_TWIN_URL.
+//   The aws pack's service keys (S3_TWIN_URL, SECRETSMANAGER_TWIN_URL) both point at its one twin.
 //   …or combined: TWIN_INJECT="stripe=http://127.0.0.1:12111,github=http://127.0.0.1:12120"
 //
 // It patches http/https `request`/`get` and global `fetch` at the process
@@ -44,6 +43,7 @@ const { createPublicKey, createVerify } = require('crypto');
 // serves it) has its own home, shared with the application route
 const { VENDOR_HOSTS, twinEnvStem, twinOrigins } = require('./vendor-hosts.cjs');
 const dns = require('dns');
+const http2 = require('http2');
 
 function decodeBase64UrlJson(part) {
   try {
@@ -130,7 +130,7 @@ installClerkFastifyTwinShim();
 // twin that is attached AND whose URL variable is set; the first such pack wins.
 function installPrismaAdapterShim() {
   if (Module.__volterPrismaAdapterShimInstalled) return;
-  const { packs } = require('./generated/pack-facts.json');
+  const { packs } = require('./pack-facts.cjs').packFacts();
   const candidates = Object.keys(packs).filter((vendor) => packs[vendor].prismaAdapter).sort();
   if (candidates.length === 0) return;
   Module.__volterPrismaAdapterShimInstalled = true;
@@ -225,7 +225,7 @@ function resolveTwin(hostname, map, pathname) {
   const base = worldBase();
   // a name a vendor's host rule gives a twin running here is that twin's, never an application's (a vendor with no
   // twin here can be one of the World's applications: the product itself)
-  const app = appRouteFor(map[APP_INSTANCE], bare, map);
+  const app = appRouteFor(map[APP_INSTANCE], bare, map, claimedAppHosts(map));
   if (app && !isTwinOriginHost(bare) && (!base || new URL(base.origin).hostname !== bare)) {
     return { vendor: 'app', origin: app.origin };
   }
@@ -245,17 +245,18 @@ const { appRouteFor, appForwardHeaders, appRequestOptions, sessionCa } = require
 // to a vendor, so each claiming twin lists its own at its door, read here every five seconds from the moment the
 // injector installs (or, in a process that only resolves, the proxy, from its first resolve). A fetch that would be
 // refused while a first read is still in flight waits for it; a name connected moments ago is refused until the next
-// read, as a new DNS record takes a moment.
+// read, as a new DNS record takes a moment. The door's `appHosts` are the names a hosting twin serves as the
+// customer's own application (a domain added to a Vercel project): those route to the application, not the twin.
 const CLAIMERS = {};
 {
-  const { packs } = require('./generated/pack-facts.json');
+  const { packs } = require('./pack-facts.cjs').packFacts();
   for (const vendor of Object.keys(packs)) if (packs[vendor].hostsClaimed) CLAIMERS[vendor] = packs[vendor].hostsClaimed.door;
 }
 const CLAIMS = new Map(); // cache: origin -> the hosts its twin last listed; refreshed by the poll below
 function claimsAt(origin, door) {
   const held = CLAIMS.get(origin);
   if (held) return held;
-  const entry = { hosts: new Set(), loaded: false, ready: null };
+  const entry = { hosts: new Set(), appHosts: new Set(), loaded: false, ready: null };
   let settle;
   entry.ready = new Promise((resolve) => { settle = resolve; });
   CLAIMS.set(origin, entry);
@@ -266,7 +267,10 @@ function claimsAt(origin, door) {
     Promise.resolve()
       .then(() => f(`${origin}${door}`, { headers: attachTwinsKey({}) }))
       .then((r) => (r.ok ? r.json() : null))
-      .then((body) => { if (body && Array.isArray(body.hosts)) entry.hosts = new Set(body.hosts.map((h) => String(h).toLowerCase())); })
+      .then((body) => {
+        if (body && Array.isArray(body.hosts)) entry.hosts = new Set(body.hosts.map((h) => String(h).toLowerCase()));
+        if (body) entry.appHosts = new Set(Array.isArray(body.appHosts) ? body.appHosts.map((h) => String(h).toLowerCase()) : []);
+      })
       .catch(() => {})
       .then(() => { entry.loaded = true; settle(); });
   };
@@ -277,6 +281,15 @@ function claimsAt(origin, door) {
   if (timer.unref) timer.unref();
   return entry;
 }
+/** The names the claiming twins of this map serve as the application (their doors' `appHosts`), or null for none. */
+function claimedAppHosts(map) {
+  let out = null;
+  for (const vendor of Object.keys(CLAIMERS)) {
+    if (!map[vendor]) continue;
+    for (const h of claimsAt(map[vendor], CLAIMERS[vendor]).appHosts) (out ??= new Set()).add(h);
+  }
+  return out;
+}
 /** The first read of a claiming twin's door still in flight for this map, or null when every one has landed. */
 function claimsPending(map) {
   const pending = Object.keys(CLAIMERS).filter((v) => map[v]).map((v) => claimsAt(map[v], CLAIMERS[v])).filter((e) => !e.loaded);
@@ -737,7 +750,7 @@ function socketTargetHosts(args, isTls) {
 
 function endpointEnvFor(vendor) {
   try {
-    const facts = require('./generated/pack-facts.json').packs[vendor];
+    const facts = require('./pack-facts.cjs').packFacts().packs[vendor];
     const endpoint = facts && facts.endpointEnv;
     if (!endpoint) return null;
     const templates = Object.keys(endpoint.templates || {});
@@ -868,6 +881,33 @@ function patchedConnect(originalConnect, isTls) {
 let MAP = {};
 let installed = false;
 
+/** A request asking to switch protocols (a WebSocket's `Upgrade: websocket`): a vendor's socket a twin serves (Slack's
+ *  Socket Mode link, Discord's Gateway), which the fetch-backed stand-in cannot carry. */
+function isUpgrade(headers) {
+  for (const [k, v] of Object.entries(headers || {})) if (k.toLowerCase() === 'upgrade' && v) return true;
+  return false;
+}
+
+/** An upgrade to a twinned host, sent as a real request to the twin's own listener (its origin's scheme, host and port,
+ *  the vendor's path under it), the vendor's host kept in `Host`: the client's upgrade, its socket and its frames are the
+ *  twin's. The caller's own connection options (a TLS `createConnection`, an agent, a servername) name the vendor and
+ *  are left behind. Where the evidence stops: a hosted World's front upgrades nothing yet, so this carries a local
+ *  World's twins only. */
+function upgradeToTwin(origin, url, method, headers, args, callback) {
+  const target = new URL(origin);
+  const given = args.find((a) => a && typeof a === 'object' && !(a instanceof URL)) || {};
+  const options = {};
+  for (const [k, v] of Object.entries(given)) {
+    if (!['protocol', 'host', 'hostname', 'port', 'path', 'agent', 'createConnection', 'servername', 'defaultPort', 'socketPath', 'headers', 'method', 'href', 'origin', 'search', 'pathname'].includes(k)) options[k] = v;
+  }
+  Object.assign(options, {
+    protocol: target.protocol, hostname: target.hostname, port: target.port || (target.protocol === 'https:' ? 443 : 80),
+    path: `${target.pathname.replace(/\/+$/, '')}${url.pathname}${url.search}`, method, headers,
+  });
+  const request = target.protocol === 'https:' ? ORIGINALS.httpsRequest : ORIGINALS.httpRequest;
+  return callback ? request(options, callback) : request(options);
+}
+
 function patchedFactory(originalRequest, defaultProtocol) {
   return function patchedRequest(...args) {
     const { url, method, headers, callback } = describe(args, defaultProtocol);
@@ -879,6 +919,7 @@ function patchedFactory(originalRequest, defaultProtocol) {
     if (twin) {
       const fwdHeaders = Object.assign({}, headers);
       if (!fwdHeaders.host && !fwdHeaders.Host) fwdHeaders.host = url.host;
+      if (isUpgrade(headers)) return upgradeToTwin(twin.origin, url, method, fwdHeaders, args, callback);
       return fakeClientRequest(twin.origin, method, url.pathname + url.search, fwdHeaders, callback);
     }
     // No twin claims this path — but if configured twins claim the HOST, the path is an unclaimed
@@ -926,6 +967,7 @@ function install(mapOverride) {
     tlsConnect: tls.connect,
     dnsLookup: dns.lookup,
     dnsPromisesLookup: dns.promises.lookup,
+    http2Connect: http2.connect,
   };
 
   http.request = patchedFactory(ORIGINALS.httpRequest, 'http:');
@@ -937,6 +979,18 @@ function install(mapOverride) {
   tls.connect = patchedConnect(ORIGINALS.tlsConnect, true);
   dns.lookup = patchedLookup(ORIGINALS.dnsLookup);
   dns.promises.lookup = patchedPromisesLookup(ORIGINALS.dnsPromisesLookup);
+  // gRPC (architecture, "Other wires": gRPC): an HTTP/2 session to a host a twin serves (grpc-js on google-gax: TLS to
+  // webrisk.googleapis.com) connects to that twin's origin in plain text, where the kernel's HTTP/2 server answers it;
+  // the client carries on unchanged. Any other authority is the real one's.
+  http2.connect = function patchedHttp2Connect(authority, options, listener) {
+    let url = null;
+    try { url = new URL(typeof authority === 'string' ? authority : authority && authority.href ? authority.href : `https://${authority.hostname || authority.host}`); } catch { url = null; }
+    const twin = url && resolveTwin(url.hostname, MAP, '/');
+    if (!twin) return ORIGINALS.http2Connect.apply(this, arguments);
+    const cb = typeof options === 'function' ? options : listener;
+    const opts = typeof options === 'function' || !options ? {} : Object.fromEntries(Object.entries(options).filter(([k]) => !['secureContext', 'servername', 'ca', 'cert', 'key', 'checkServerIdentity', 'ALPNProtocols', 'createConnection', 'rejectUnauthorized'].includes(k)));
+    return ORIGINALS.http2Connect.call(this, new URL(twin.origin).origin, opts, cb);
+  };
 
   if (ORIGINALS.fetch) {
     const originalFetch = ORIGINALS.fetch;
@@ -1084,6 +1138,7 @@ function restore() {
   tls.connect = ORIGINALS.tlsConnect;
   dns.lookup = ORIGINALS.dnsLookup;
   dns.promises.lookup = ORIGINALS.dnsPromisesLookup;
+  http2.connect = ORIGINALS.http2Connect;
   installed = false;
   MAP = {};
 }

package/dist/pack-facts.cjs

@@ -0,0 +1,44 @@
+// THE PACK FACTS a process routes by (docs/contributing/architecture.md, "The catalog: where twins come from"): the facts
+// this kernel was built with (generated/pack-facts.json, compiled from the packs of its checkout), overlaid by the facts
+// of the packs the World resolved from installed packages. Each released pack carries its own
+// (`generated/pack-facts.json`), and the World's instance file (VOLTER_WORLD_INSTANCE, which every World process already
+// has) names them as `packFacts`. A pack's own facts replace the built-in ones for its vendor. Plain CommonJS, no
+// dependency: the injector preloads it. Read once per process.
+'use strict';
+const fs = require('fs');
+
+let cached;
+function packFacts() {
+  if (cached) return cached;
+  const base = require('./generated/pack-facts.json');
+  const packs = Object.assign({}, base.packs);
+  // the vendors whose facts came from an installed pack (the host rules let those replace a hand entry)
+  const installed = [];
+  const instance = process.env.VOLTER_WORLD_INSTANCE;
+  if (instance) {
+    try {
+      const files = JSON.parse(fs.readFileSync(instance, 'utf8')).packFacts || [];
+      for (const file of files) {
+        try { const own = JSON.parse(fs.readFileSync(file, 'utf8')).packs || {}; Object.assign(packs, own); installed.push(...Object.keys(own)); } catch (_) { /* a pack without readable facts keeps the built-in ones */ }
+      }
+    } catch (_) { /* no instance yet: the built-in facts */ }
+  }
+  cached = Object.assign({}, base, { packs, installed });
+  return cached;
+}
+
+/** Facts files a process knows before any World instance names them (the runtime booting a World it has not written
+ *  the instance of): merged as the instance's are, and into the host rules already built. */
+function extendPackFacts(files) {
+  const facts = packFacts();
+  const added = {};
+  for (const file of files || []) {
+    try { Object.assign(added, JSON.parse(fs.readFileSync(file, 'utf8')).packs || {}); } catch (_) { /* the facts it has stand */ }
+  }
+  Object.assign(facts.packs, added);
+  // the host rules already built from the facts learn these packs too
+  require('./vendor-hosts.cjs').addPackHosts(added);
+  return facts;
+}
+
+module.exports = { packFacts, extendPackFacts };

package/dist/src/actions.d.ts

@@ -124,7 +124,7 @@ export declare function appendActionIfAbsent(action: TwinAction, root?: string):
  * Append `build(n)` as an OCCURRENCE: the nth time this exact write has been made.
  *
  * A local vendor write is an occurrence, not a replay — two calls are two actions, even
- * byte-identical in the same instant (docs/contributing/adding-a-twin.md#5-build-on-the-shared-kernel--dont-reinvent,
+ * byte-identical in the same instant (docs/contributing/architecture.md, "The state kernel",
  * "A local write is an occurrence"). `appendActionIfAbsent` cannot express that: its identity is content, and
  * content provably cannot separate "the same request delivered twice" from "the same change made
  * twice". So a caller wanting at-most-once passes an explicit key and uses that function; a caller
@@ -205,8 +205,8 @@ export declare class OwnerStoreAmbiguousError extends Error {
     });
 }
 /**
- * ANOTHER pack's rows, read by contract (architecture A3: one vendor's store split across two packs, xidentity's tokens
- * read by x, googleoauth's by googlecalendar; scripts/architecture.test.ts holds the declared reader-owner pairs): the
+ * ANOTHER pack's rows, read by contract (architecture A3: one vendor's store split across two packs, googleoauth's tokens
+ * read by webrisk; the reader's manifest declares the pair, `ownerReads`): the
  * owner's tree, from wherever the World keeps the owner's store (`ownerStoreRoots`). Read only: the rows are frozen and
  * shared. It claims no journal identity (the twin answering is the reader).
  *

package/dist/src/actions.js

@@ -11,7 +11,7 @@
 //
 // Projection = observed mirror, then apply each `set` transaction in order,
 // skipping any transaction that was reverted or confirmed.
-import { withAncestryLock } from "./ancestry.js";
+import { withHistoryLock } from "./ancestry.js";
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
@@ -91,13 +91,18 @@ function actionIds(service, root) {
     memos.set(path, { key, ids });
     return ids;
 }
+/** A service's projection lock, under its history lock: one directory's locks are taken history, projection,
+ *  actions, events, in that order (architecture, the history lock). */
+function withProjection(service, root, fn) {
+    return withHistoryLock(worldPaths(service, root).dir, () => withFileLock(projectionLock(service, root), fn));
+}
 function appendActionRaw(action, root) {
     const path = actionsPath(action.service, root);
     getActiveWorldStore().mkdir(dirname(path));
     const memos = idMemoSlot(path);
     const held = memos.get(path);
     const current = held !== undefined && held.key === logKey(path);
-    withAncestryLock(() => appendDurable(path, `${JSON.stringify(action)}\n`));
+    withHistoryLock(worldPaths(action.service, root).dir, () => appendDurable(path, `${JSON.stringify(action)}\n`));
     if (current) {
         held.ids.add(action.id);
         held.key = logKey(path);
@@ -144,9 +149,10 @@ function existingExactAction(action, root) {
     }
     return existing;
 }
-/** The request-scoped correlation id (D3): set by the kernel fetch adapter for the duration of one
- *  handler call from the wire's `x-twins-request-id`; read by appendAction as the default. */
-// created on first use, never at import: a browser bundle of a mirror client carries this module and has
+/** The request-scoped correlation id (D3): for the duration of one handler call, the id a pack fetch mints for the
+ *  request (a caller's `x-twins-request-id` is recorded with each write as provenance, never as the group), or, under
+ *  the kernel fetch adapter, the wire's `x-twins-request-id`; read by appendAction as the default. */
+// created on first use, never at import: a browser bundle carrying the kernel carries this module and has
 // no AsyncLocalStorage (see serve.ts identitySlot)
 let correlationStore;
 const correlationScope = () => (correlationStore ??= new AsyncLocalStorage());
@@ -158,7 +164,7 @@ export function appendAction(action, root) {
     // compare-and-set, not an advisory validation: checking outside either lock would let another
     // writer invalidate it before this action lands. The shadow basis is stamped under the same
     // lock so the recorded merge base is the mirror the preconditions were checked against.
-    return withFileLock(projectionLock(action.service, root), () => withFileLock(actionsLock(action.service, root), () => {
+    return withProjection(action.service, root, () => withFileLock(actionsLock(action.service, root), () => {
         const stamped = withCorrelationId(action);
         assertPreconditions(stamped, root);
         const placeholder = landIfPlaceholderPull(stamped, root);
@@ -174,7 +180,7 @@ export function appendAction(action, root) {
  *  writes both land). A reused id with different content fails loudly. */
 export function appendActionIfAbsent(action, root) {
     refuseReadOnlyWrite(action.service);
-    return withFileLock(projectionLock(action.service, root), () => withFileLock(actionsLock(action.service, root), () => {
+    return withProjection(action.service, root, () => withFileLock(actionsLock(action.service, root), () => {
         const identified = withCorrelationId(action);
         // An exact retry is already committed. Resolve it before re-evaluating author-time
         // preconditions against the state that first commit intentionally changed — and
@@ -195,7 +201,7 @@ export function appendActionIfAbsent(action, root) {
  * Append `build(n)` as an OCCURRENCE: the nth time this exact write has been made.
  *
  * A local vendor write is an occurrence, not a replay — two calls are two actions, even
- * byte-identical in the same instant (docs/contributing/adding-a-twin.md#5-build-on-the-shared-kernel--dont-reinvent,
+ * byte-identical in the same instant (docs/contributing/architecture.md, "The state kernel",
  * "A local write is an occurrence"). `appendActionIfAbsent` cannot express that: its identity is content, and
  * content provably cannot separate "the same request delivered twice" from "the same change made
  * twice". So a caller wanting at-most-once passes an explicit key and uses that function; a caller
@@ -209,7 +215,7 @@ export function appendActionIfAbsent(action, root) {
  */
 export function appendActionOccurrence(base, root) {
     refuseReadOnlyWrite(base.service);
-    return withFileLock(projectionLock(base.service, root), () => withFileLock(actionsLock(base.service, root), () => {
+    return withProjection(base.service, root, () => withFileLock(actionsLock(base.service, root), () => {
         const stamped = occurrenceOf(base, actionIds(base.service, root), root);
         assertPreconditions(stamped, root);
         const placeholder = landIfPlaceholderPull(stamped, root);
@@ -247,7 +253,7 @@ export function occurrenceId(base, ordinal) {
  * appends before releasing the lock.
  */
 export function decideAndAppendAction(service, decide, root) {
-    return withFileLock(projectionLock(service, root), () => withFileLock(actionsLock(service, root), () => {
+    return withProjection(service, root, () => withFileLock(actionsLock(service, root), () => {
         const resources = projectResources(service, root);
         const decision = decide(resources);
         if (decision.kind === 'skip')
@@ -368,8 +374,8 @@ function ownerIndex(owner, root) {
     return index;
 }
 /**
- * ANOTHER pack's rows, read by contract (architecture A3: one vendor's store split across two packs, xidentity's tokens
- * read by x, googleoauth's by googlecalendar; scripts/architecture.test.ts holds the declared reader-owner pairs): the
+ * ANOTHER pack's rows, read by contract (architecture A3: one vendor's store split across two packs, googleoauth's tokens
+ * read by webrisk; the reader's manifest declares the pair, `ownerReads`): the
  * owner's tree, from wherever the World keeps the owner's store (`ownerStoreRoots`). Read only: the rows are frozen and
  * shared. It claims no journal identity (the twin answering is the reader).
  *
@@ -424,13 +430,13 @@ export function confirmAction(opts) {
         ...(opts.additionalObservations ?? []).map((o) => landedCopy(base, receipt, { subject: o.subject, fields: o.fields })),
         landedCopy(base, receipt, { subject: opts.subject, fields: opts.fields, ...(opts.vendorSubjectId ? { vendorSubjectId: opts.vendorSubjectId } : {}) }),
     ];
-    withFileLock(projectionLock(opts.service, opts.root), () => {
-        withAncestryLock(() => withFileLock(eventsLockPath(paths), () => {
+    withProjection(opts.service, opts.root, () => {
+        withFileLock(eventsLockPath(paths), () => {
             const held = landedIds(parentEntries(opts.service, opts.root));
             for (const copy of copies)
                 if (!held.has(copy.id))
                     appendDurable(paths.events, `${JSON.stringify(copy)}\n`);
-        }));
+        });
         dropCheckpoint(opts.service, opts.root);
     });
     const observedEventIds = copies.map((c) => c.id);
@@ -445,7 +451,7 @@ export function confirmAction(opts) {
  */
 export function revertAction(opts) {
     refuseReadOnlyWrite(opts.service);
-    return withFileLock(projectionLock(opts.service, opts.root), () => withFileLock(actionsLock(opts.service, opts.root), () => {
+    return withProjection(opts.service, opts.root, () => withFileLock(actionsLock(opts.service, opts.root), () => {
         const all = listActions(opts.service, opts.root);
         const target = all.find((a) => a.id === opts.actionId);
         if (target === undefined)

package/dist/src/ancestry.d.ts

@@ -1,7 +1,18 @@
 export declare const canonicalStatePath: (path: string) => string;
 /** Synchronous only; use exclusive acquisition without age-stealing a live owner.
- * The coordinator lives outside service, instance and hosted World deletion trees. */
+ * The coordinator lives outside service, instance and hosted World deletion trees. It is held only for ancestry
+ * bookkeeping (generations, pins, branch pointers, removal receipts) and the not-being-removed check: every World
+ * sharing the VOLTER_HOME waits on it, so no append, fold or caller's critical section runs inside it, and no state lock
+ * is taken inside it (`withStateLock` takes its lock first). */
 export declare function withAncestryLock<T>(fn: () => T): T;
+/** Run `fn` holding the cross-process lock at `lockPath`, a lock of the directory it sits in: taken first, then the
+ *  coordinator only to check that the directory is not being removed. Re-entrant within a process. */
+export declare function withStateLock<T>(lockPath: string, fn: () => T): T;
+/** A state directory's history lock: its appends, captures, observation batches and folds. A branch's is taken before
+ *  its ancestors'. */
+export declare function withHistoryLock<T>(directory: string, fn: () => T): T;
+/** Several sibling directories' history locks at once (a World's services, a changeset's targets), in one order. */
+export declare function withHistoryLocks<T>(directories: string[], fn: () => T): T;
 /** Create an identity only for an existing parent. A recreated path gets a new identity. */
 export declare function stateGeneration(dir: string): string;
 /** Must be called in the same critical section as child pointer publication. A crash before
@@ -18,5 +29,6 @@ export declare function assertNotBeingRemoved(path: string): void;
 /** force on scrub bypasses shape checking only, never another branch's ownership. The coordinator is held to decide
  * and record the removal (`check`, the caller's own precondition, runs there too) and to release it, not through the
  * deletion: every World on the machine shares the coordinator, and a large tree's deletion outlasts their writes'
- * patience. The receipt, written first, keeps the path from being pinned or written while it is deleted. */
+ * patience. The receipt, written first, keeps the path from being pinned or locked while it is deleted; the deletion
+ * then waits on each lock inside the tree in turn, so a holder that checked before the receipt finishes first. */
 export declare function withStateRemoval<T>(path: string, remove: () => T, check?: () => void): T;

package/dist/src/ancestry.js

@@ -10,7 +10,10 @@ export const canonicalStatePath = (path) => getActiveWorldStore().canonicalPath?
 const metaPath = (dir) => join(dir, 'ancestry.json');
 const inside = (base, path) => { const rel = relative(canonicalStatePath(base), canonicalStatePath(path)); return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep)); };
 /** Synchronous only; use exclusive acquisition without age-stealing a live owner.
- * The coordinator lives outside service, instance and hosted World deletion trees. */
+ * The coordinator lives outside service, instance and hosted World deletion trees. It is held only for ancestry
+ * bookkeeping (generations, pins, branch pointers, removal receipts) and the not-being-removed check: every World
+ * sharing the VOLTER_HOME waits on it, so no append, fold or caller's critical section runs inside it, and no state lock
+ * is taken inside it (`withStateLock` takes its lock first). */
 export function withAncestryLock(fn) {
     const store = getActiveWorldStore();
     const active = entered ??= new WeakSet();
@@ -28,6 +31,76 @@ export function withAncestryLock(fn) {
         }
     }, { retainLiveOwner: true });
 }
+/** The state locks this process holds, per store: taken again inside one, a lock is already ours. */
+let heldLocks;
+const heldBy = (store) => { const map = heldLocks ??= new WeakMap(); let set = map.get(store); if (!set) {
+    set = new Set();
+    map.set(store, set);
+} return set; };
+/** Run `fn` holding the cross-process lock at `lockPath`, a lock of the directory it sits in: taken first, then the
+ *  coordinator only to check that the directory is not being removed. Re-entrant within a process. */
+export function withStateLock(lockPath, fn) {
+    const store = getActiveWorldStore();
+    const held = heldBy(store);
+    if (held.has(lockPath))
+        return fn();
+    if (entered?.has(store))
+        throw new Error(`State lock ${lockPath} taken inside the ancestry coordinator: a state lock is taken before it, never inside it`);
+    return store.withLock(lockPath, () => {
+        withAncestryLock(() => assertNotBeingRemoved(dirname(lockPath)));
+        held.add(lockPath);
+        try {
+            return fn();
+        }
+        finally {
+            held.delete(lockPath);
+        }
+    });
+}
+/** A state directory's history lock: its appends, captures, observation batches and folds. A branch's is taken before
+ *  its ancestors'. */
+export function withHistoryLock(directory, fn) {
+    return withStateLock(join(canonicalStatePath(directory), 'history.lock'), fn);
+}
+/** A lock file a holder has recorded itself in (`{pid, hostname}`, written before the holder runs anything): a file
+ *  that only ends in `.lock` (a yarn.lock) is not one. */
+function isHeldLock(text) {
+    try {
+        const holder = JSON.parse(text ?? '');
+        return Number.isInteger(holder.pid);
+    }
+    catch {
+        return false;
+    }
+}
+/** Several sibling directories' history locks at once (a World's services, a changeset's targets), in one order. */
+export function withHistoryLocks(directories, fn) {
+    const sorted = [...new Set(directories.map((d) => canonicalStatePath(d)))].sort();
+    const take = (i) => (i === sorted.length ? fn() : withHistoryLock(sorted[i], () => take(i + 1)));
+    return take(0);
+}
+/** The locks inside a tree a removal waits on before deleting it. */
+function locksUnder(path) {
+    const store = getActiveWorldStore();
+    const out = [];
+    const walk = (dir) => {
+        for (const name of store.list(dir)) {
+            if (name === 'node_modules' || name === '.git')
+                continue;
+            const child = join(dir, name);
+            const stat = store.stat(child);
+            if (!stat || stat.isSymbolicLink)
+                continue;
+            if (stat.isDirectory)
+                walk(child);
+            else if (name.endsWith('.lock') && isHeldLock(store.read(child)))
+                out.push(child);
+        }
+    };
+    if (store.stat(path)?.isDirectory)
+        walk(path);
+    return out.sort();
+}
 function metadata(dir) {
     const raw = getActiveWorldStore().read(metaPath(dir));
     if (raw === null)
@@ -209,7 +282,8 @@ export function assertNotBeingRemoved(path) {
 /** force on scrub bypasses shape checking only, never another branch's ownership. The coordinator is held to decide
  * and record the removal (`check`, the caller's own precondition, runs there too) and to release it, not through the
  * deletion: every World on the machine shares the coordinator, and a large tree's deletion outlasts their writes'
- * patience. The receipt, written first, keeps the path from being pinned or written while it is deleted. */
+ * patience. The receipt, written first, keeps the path from being pinned or locked while it is deleted; the deletion
+ * then waits on each lock inside the tree in turn, so a holder that checked before the receipt finishes first. */
 export function withStateRemoval(path, remove, check) {
     const store = getActiveWorldStore();
     const { removal, receipt } = withAncestryLock(() => {
@@ -225,6 +299,22 @@ export function withStateRemoval(path, remove, check) {
         beingRemoved = [...beingRemoved, removal.path];
         return { removal, receipt };
     });
+    // Each lock is waited on alone, taken and let go: a holder that checked before the receipt finishes, and a taker
+    // after it refuses once it holds the lock (withStateLock), so the removal never holds one lock while waiting on
+    // another and no lock order can deadlock it. A wait that fails leaves nothing deleted: the receipt is released.
+    const held = heldBy(store);
+    try {
+        for (const lock of locksUnder(path).filter((l) => !held.has(l)))
+            store.withLock(lock, () => undefined);
+    }
+    catch (error) {
+        withAncestryLock(() => {
+            if (store.exists(receipt))
+                store.remove(receipt);
+            beingRemoved = beingRemoved.filter((p) => p !== removal.path);
+        });
+        throw error;
+    }
     const result = remove();
     withAncestryLock(() => {
         if (store.exists(path))

package/dist/src/anthropic-wire.d.ts

@@ -0,0 +1,39 @@
+import { type WireRequest, type WireTurn } from './openai-wire.js';
+type Row = Record<string, unknown>;
+/** A message's content as text: a string, or its text blocks (and the text of its tool results) joined. */
+export declare const messagesText: (content: unknown) => string;
+/** The last user message's text. */
+export declare function messagesLastUserText(messages: Row[]): string;
+/** The tool results the last message carries, by the names of the tool_use blocks they answer. */
+export declare function messagesToolResults(messages: Row[]): string[];
+/** A Messages request as a scenario reads it (the OpenAI wire's `WireRequest`): its model, its system and messages'
+ *  text, its last user text, the tools it offers and the tool results it ends with. */
+export declare function messagesWireRequest(body: Row): WireRequest;
+/** The labeled stub for a Messages request: with tools offered (`tool_choice` not `none`) and the last message not a
+ *  tool's result, it calls the tool the choice names, else the first, with input its schema admits; with a JSON schema
+ *  for the output, it answers a value the schema admits; otherwise it echoes the last user message. `label` names the
+ *  twin. */
+export declare function messagesStubTurn(body: Row, label: string): WireTurn;
+export type MessageShape = {
+    id: string;
+    model: string;
+    turn: WireTurn;
+    body: Row;
+    /** each tool_use block's id, and the thinking block's signature */
+    toolId: (i: number) => string;
+    signature?: (thinking: string) => string;
+    /** usage fields the vendor adds (service_tier, the prompt cache's counts) */
+    usage?: Row;
+};
+/** A message (`type: message`): a thinking block when the request turns thinking on, then the
+ *  text, then the tool_use blocks; its stop reason, and its usage estimated from the request and the answer. A text
+ *  longer than `max_tokens` is cut there and stops `max_tokens`. */
+export declare function message(s: MessageShape): Row;
+/** A message as the stream's events: message_start (its content empty), per block its start, deltas and stop (a ping
+ *  after the first start), message_delta with the stop reason and the output usage, message_stop. `extra` adds fields
+ *  a vendor puts on the two closing events (Merge's `routing`). */
+export declare function messageSSE(m: Row, extra?: Row, options?: {
+    ping?: boolean;
+    completeToolInput?: boolean;
+}): string;
+export {};