@volter/world-core 2.0.37 → 3.0.1

package/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/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/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@volter/world-core",
-  "version": "2.0.37",
+  "version": "3.0.1",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",
     "local",
     "mock",
-    "mirror",
     "simulator",
     "fixtures",
     "testing",
@@ -29,6 +28,8 @@
     "network-policy.d.cts",
     "app-route.cjs",
     "vendor-hosts.cjs",
+    "pack-facts.cjs",
+    "vendor-hosts.d.cts",
     "world-clock.cjs",
     "world-clock.d.cts",
     "app-route.d.cts",
@@ -45,7 +46,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/volter-ai/twin.git",
+    "url": "git+https://github.com/volter-ai/twin-world.git",
     "directory": "packages/world-core"
   },
   "homepage": "https://world.volter.ai/docs/README",
@@ -55,10 +56,18 @@
       "types": "./dist/src/index.d.ts",
       "default": "./dist/src/index.js"
     },
+    "./runtime": {
+      "types": "./dist/src/runtime.d.ts",
+      "default": "./dist/src/runtime.js"
+    },
     "./args": {
       "types": "./dist/src/args.d.ts",
       "default": "./dist/src/args.js"
     },
+    "./s3": {
+      "types": "./dist/src/s3/wire.d.ts",
+      "default": "./dist/src/s3/wire.js"
+    },
     "./schemas": {
       "types": "./dist/src/schemas.d.ts",
       "default": "./dist/src/schemas.js"
@@ -75,6 +84,7 @@
       "default": "./app-route.cjs"
     },
     "./vendor-hosts": "./vendor-hosts.cjs",
+    "./pack-facts": "./pack-facts.cjs",
     "./world-clock": {
       "types": "./world-clock.d.cts",
       "default": "./world-clock.cjs"
@@ -87,6 +97,10 @@
     "./redis": {
       "types": "./dist/src/redis/index.d.ts",
       "default": "./dist/src/redis/index.js"
+    },
+    "./clickhouse": {
+      "types": "./dist/src/clickhouse/index.d.ts",
+      "default": "./dist/src/clickhouse/index.js"
     }
   },
   "scripts": {

package/src/actions.ts

@@ -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.ts';
+import { withHistoryLock } from './ancestry.ts';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
@@ -183,13 +183,19 @@ function actionIds(service: string, root?: string): ReadonlySet<string> {
   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<T>(service: string, root: string | undefined, fn: () => T): T {
+  return withHistoryLock(worldPaths(service, root).dir, () => withFileLock(projectionLock(service, root), fn));
+}
+
 function appendActionRaw(action: TwinAction, root?: string): void {
   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); } else memos.delete(path);
   twinLog('action.append', { service: action.service, id: action.id, op: action.op, correlationId: action.correlationId });
   appendObserver?.(action, root);
@@ -234,9 +240,10 @@ function existingExactAction(action: TwinAction, root?: string): TwinAction | un
   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: AsyncLocalStorage<string> | undefined;
 const correlationScope = (): AsyncLocalStorage<string> => (correlationStore ??= new AsyncLocalStorage<string>());
@@ -249,7 +256,7 @@ export function appendAction(action: TwinAction, root?: string): TwinAction {
   // 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);
@@ -265,7 +272,7 @@ export function appendAction(action: TwinAction, root?: string): TwinAction {
  *  writes both land). A reused id with different content fails loudly. */
 export function appendActionIfAbsent(action: TwinAction, root?: string): { action: TwinAction; appended: boolean; placeholder?: true } {
   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
@@ -285,7 +292,7 @@ export function appendActionIfAbsent(action: TwinAction, root?: string): { actio
  * 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
@@ -299,7 +306,7 @@ export function appendActionIfAbsent(action: TwinAction, root?: string): { actio
  */
 export function appendActionOccurrence(base: TwinAction, root?: string): { action: TwinAction; appended: boolean; placeholder?: true } {
   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);
@@ -355,7 +362,7 @@ export function decideAndAppendAction<T>(
   decide: (resources: TwinResource[]) => AtomicActionDecision<T>,
   root?: string,
 ): { value: T; action?: TwinAction; appended: boolean; placeholder?: true } {
-  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') return { value: decision.value, appended: false };
@@ -481,8 +488,8 @@ function ownerIndex(owner: string, root: string): OwnerIndex {
 }
 
 /**
- * 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).
  *
@@ -551,11 +558,11 @@ 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);
@@ -578,7 +585,7 @@ export type RevertOutcome =
  */
 export function revertAction(opts: { service: string; actionId: string; occurredAt: string; root?: string }): RevertOutcome {
   refuseReadOnlyWrite(opts.service);
-  return withFileLock(projectionLock(opts.service, opts.root), () => withFileLock(actionsLock(opts.service, opts.root), (): RevertOutcome => {
+  return withProjection(opts.service, opts.root, () => withFileLock(actionsLock(opts.service, opts.root), (): RevertOutcome => {
     const all = listActions(opts.service, opts.root);
     const target = all.find((a) => a.id === opts.actionId);
     if (target === undefined) return { status: 'not-found' };

package/src/ancestry.ts

@@ -14,7 +14,10 @@ const metaPath = (dir: string) => join(dir, 'ancestry.json');
 const inside = (base: string, path: string) => { 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<T>(fn: () => T): T {
   const store = getActiveWorldStore();
   const active = entered ??= new WeakSet<WorldStore>();
@@ -27,6 +30,61 @@ export function withAncestryLock<T>(fn: () => T): T {
   }, { retainLiveOwner: true });
 }
 
+/** The state locks this process holds, per store: taken again inside one, a lock is already ours. */
+let heldLocks: WeakMap<WorldStore, Set<string>> | undefined;
+const heldBy = (store: WorldStore): Set<string> => { 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<T>(lockPath: string, fn: () => T): T {
+  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<T>(directory: string, fn: () => T): T {
+  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: string | null): boolean {
+  try { const holder = JSON.parse(text ?? '') as { pid?: unknown }; 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<T>(directories: string[], fn: () => T): T {
+  const sorted = [...new Set(directories.map((d) => canonicalStatePath(d)))].sort();
+  const take = (i: number): T => (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: string): string[] {
+  const store = getActiveWorldStore();
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    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: string): Ancestry | null {
   const raw = getActiveWorldStore().read(metaPath(dir));
   if (raw === null) return null;
@@ -186,7 +244,8 @@ export 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 function withStateRemoval<T>(path: string, remove: () => T, check?: () => void): T {
   const store = getActiveWorldStore();
   const { removal, receipt } = withAncestryLock(() => {
@@ -202,6 +261,19 @@ export function withStateRemoval<T>(path: string, remove: () => T, 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)) throw new Error(`Branch state removal incomplete: ${path}; receipt retained`);

package/src/anthropic-wire.ts

@@ -0,0 +1,137 @@
+// Anthropic's Messages wire (architecture, "The kernel owns shared mechanics"): the Messages shapes a vendor serves as
+// Anthropic defines them (https://platform.claude.com/docs/en/api/messages and /build-with-claude/streaming), for
+// generative packs that run no model, beside the OpenAI wire (./openai-wire.ts) whose turn vocabulary it answers. A
+// pack decides its turn (the World's scenario's, else the stub) and its own facts (its ids, its usage fields); this
+// module reads a request as the scenario reads it and shapes the answer and its Server-Sent Events. Importing it does
+// nothing.
+import { estimateTokens, forbidsTools, type WireRequest, type WireTurn } from './openai-wire.ts';
+import { sampleFromSchema } from './schema-sample.ts';
+
+type Row = Record<string, unknown>;
+const obj = (v: unknown): Row => (v && typeof v === 'object' && !Array.isArray(v) ? v as Row : {});
+const arr = (v: unknown): Row[] => (Array.isArray(v) ? v as Row[] : []);
+
+/** A message's content as text: a string, or its text blocks (and the text of its tool results) joined. */
+export const messagesText = (content: unknown): string =>
+  typeof content === 'string' ? content : arr(content).map((c) => (c.type === 'text' ? String(c.text ?? '') : c.type === 'tool_result' ? messagesText(c.content) : '')).filter(Boolean).join('\n');
+
+/** The last user message's text. */
+export function messagesLastUserText(messages: Row[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) if (messages[i]!.role === 'user') { const t = messagesText(messages[i]!.content); if (t) return t; }
+  return '';
+}
+
+/** The tool results the last message carries, by the names of the tool_use blocks they answer. */
+export function messagesToolResults(messages: Row[]): string[] {
+  const ids = arr(messages.at(-1)?.content).filter((c) => c.type === 'tool_result').map((c) => c.tool_use_id);
+  if (!ids.length) return [];
+  return messages.flatMap((m) => arr(m.content)).filter((c) => c.type === 'tool_use' && ids.includes(c.id)).map((c) => String(c.name));
+}
+
+/** 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 function messagesWireRequest(body: Row): WireRequest {
+  const messages = arr(body.messages);
+  const system = typeof body.system === 'string' ? body.system : messagesText(body.system);
+  return {
+    model: String(body.model ?? ''), text: [system, ...messages.map((m) => messagesText(m.content))].join('\n'), lastUser: messagesLastUserText(messages),
+    tools: arr(body.tools).map((t) => String(t.name ?? '')).filter(Boolean), results: messagesToolResults(messages),
+    ...(forbidsTools(body.tool_choice) ? { toolsForbidden: true } : {}),
+  };
+}
+
+/** 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 function messagesStubTurn(body: Row, label: string): WireTurn {
+  const model = String(body.model);
+  const messages = arr(body.messages);
+  const tools = arr(body.tools).filter((t) => t.input_schema !== undefined);
+  const choice = obj(body.tool_choice ?? { type: 'auto' });
+  if (tools.length && choice.type !== 'none' && (messagesToolResults(messages).length === 0 || choice.type === 'any' || choice.type === 'tool')) {
+    const tool = (choice.type === 'tool' ? tools.find((t) => t.name === choice.name) : undefined) ?? tools[0]!;
+    return { toolCalls: [{ name: String(tool.name), arguments: sampleFromSchema(tool.input_schema, String(tool.name)) as Row }] };
+  }
+  const format = obj(obj(body.output_config).format ?? body.output_format);
+  if (format.type === 'json_schema') return { text: JSON.stringify(sampleFromSchema(format.schema)) };
+  const said = messagesLastUserText(messages).trim();
+  return { text: `[twin-stub:${model}] This is a deterministic stub from the ${label} (no model runs). Your last message: ${said.length > 200 ? `${said.slice(0, 200)}…` : said || '(empty)'}` };
+}
+
+/** The OpenAI wire's finish reasons as the Messages stop reasons they mean. */
+const STOP: Record<string, string> = { stop: 'end_turn', length: 'max_tokens', tool_calls: 'tool_use', content_filter: 'refusal' };
+
+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 function message(s: MessageShape): Row {
+  const b = s.body;
+  // thinking blocks come only when the request turns thinking on; a turn's reasoning is then their text
+  const thinkingOn = ['enabled', 'adaptive'].includes(String(obj(b.thinking).type));
+  const max = typeof b.max_tokens === 'number' ? b.max_tokens : undefined;
+  let text = s.turn.text ?? undefined;
+  let cut = false;
+  if (text !== undefined && max !== undefined && estimateTokens(text) > max) { text = text.slice(0, Math.max(1, max) * 4); cut = true; }
+  const content: Row[] = [];
+  if (thinkingOn) {
+    const thinking = s.turn.reasoning ?? '[twin-stub] No model runs here, so there is no reasoning to show.';
+    content.push({ type: 'thinking', thinking, signature: s.signature ? s.signature(thinking) : '' });
+  }
+  if (text !== undefined) content.push({ type: 'text', text });
+  (s.turn.toolCalls ?? []).forEach((c, i) => content.push({ type: 'tool_use', id: s.toolId(i), name: c.name, input: c.arguments ?? {} }));
+  const stop = cut ? 'max_tokens' : s.turn.finishReason ? (STOP[s.turn.finishReason] ?? s.turn.finishReason) : s.turn.toolCalls?.length ? 'tool_use' : 'end_turn';
+  const request = messagesWireRequest(b);
+  const output = estimateTokens(content.map((c) => (c.type === 'tool_use' ? JSON.stringify(c.input) : String(c.text ?? c.thinking ?? ''))).join(''));
+  return {
+    id: s.id, type: 'message', role: 'assistant', model: s.model, content, stop_reason: stop, stop_sequence: null,
+    usage: { input_tokens: estimateTokens(request.text), cache_creation_input_tokens: 0, cache_read_input_tokens: 0, output_tokens: output, ...(s.usage ?? {}) },
+  };
+}
+
+/** Text in the pieces a stream sends it in: a few words at a time. */
+function pieces(text: string): string[] {
+  const words = text.match(/\S+\s*|\s+/g) ?? [text];
+  const out: string[] = [];
+  for (let i = 0; i < words.length; i += 4) out.push(words.slice(i, i + 4).join(''));
+  return out.length ? out : [''];
+}
+
+/** 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 function messageSSE(m: Row, extra: Row = {}, options: { ping?: boolean; completeToolInput?: boolean } = {}): string {
+  const events: string[] = [];
+  const send = (type: string, data: Row): void => { events.push(`event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n`); };
+  const usage = obj(m.usage);
+  send('message_start', { message: { ...m, content: [], stop_reason: null, stop_sequence: null, usage: { ...usage, output_tokens: 1 } } });
+  arr(m.content).forEach((block, index) => {
+    if (block.type === 'text') {
+      send('content_block_start', { index, content_block: { type: 'text', text: '' } });
+      if (index === 0 && options.ping !== false) send('ping', {});
+      for (const piece of pieces(String(block.text))) send('content_block_delta', { index, delta: { type: 'text_delta', text: piece } });
+    } else if (block.type === 'thinking') {
+      send('content_block_start', { index, content_block: { type: 'thinking', thinking: '', signature: '' } });
+      if (index === 0 && options.ping !== false) send('ping', {});
+      for (const piece of pieces(String(block.thinking))) send('content_block_delta', { index, delta: { type: 'thinking_delta', thinking: piece } });
+      send('content_block_delta', { index, delta: { type: 'signature_delta', signature: block.signature } });
+    } else {
+      send('content_block_start', { index, content_block: { ...block, input: {} } });
+      if (index === 0 && options.ping !== false) send('ping', {});
+      for (const piece of options.completeToolInput ? [JSON.stringify(block.input)] : pieces(JSON.stringify(block.input))) send('content_block_delta', { index, delta: { type: 'input_json_delta', partial_json: piece } });
+    }
+    send('content_block_stop', { index });
+  });
+  send('message_delta', { delta: { stop_reason: m.stop_reason, stop_sequence: null }, usage: { output_tokens: usage.output_tokens }, ...extra });
+  send('message_stop', { ...extra });
+  return events.join('');
+}