@volter/world-core 3.0.155 → 3.0.157

package/dist/inject.cjs

@@ -146,32 +146,61 @@ function installPrismaAdapterShim() {
   if (candidates.length === 0) return;
   Module.__volterPrismaAdapterShimInstalled = true;
   const path = require('path');
-  const originalLoad = Module._load;
-  Module._load = function volterPrismaLoad(request, parent, isMain) {
-    const exports = originalLoad.apply(this, arguments);
-    if (request !== '@prisma/client' || !exports || typeof exports.PrismaClient !== 'function' || exports.PrismaClient.__volterAdapted) return exports;
+  // The package's own entry (its `main`, `default.js`; `index.js` before Prisma 5), patched as it loads (PACKAGE ENTRIES).
+  patchPackageEntry(/[\\/]node_modules[\\/]@prisma[\\/]client[\\/](default|index)\.js$/, (module) => {
+    const exports = module.exports;
+    if (!exports || typeof exports.PrismaClient !== 'function' || exports.PrismaClient.__volterAdapted) return;
     const vendor = candidates.find((candidate) => MAP[candidate] && process.env[packs[candidate].prismaAdapter.urlEnv]);
-    if (!vendor) return exports;
+    if (!vendor) return;
     const facts = packs[vendor].prismaAdapter;
-    // From the requiring module first (a library that constructs the client), then the
-    // application itself, whose dependency the adapter is under pnpm's isolated layout.
-    const from = parent && parent.filename ? path.dirname(parent.filename) : process.cwd();
-    let adapterModule;
-    try {
-      adapterModule = originalLoad.call(this, require.resolve(facts.adapter, { paths: [from, process.cwd()] }), parent, false);
-    } catch {
+    // THE ADAPTER IS FOUND WHERE THE CLIENT IS USED, AT ITS FIRST CONSTRUCTION WITHOUT ONE (review of the World 2209
+    // integration, 75f6a1dd). The entry's own parent is the first module that loaded it. For a copy cached before this
+    // prelude ran, that is not the library that later constructs the client, and an early miss there was final.
+    // At each construction without an adapter, until one is found, these places are asked in turn:
+    // - the directory of each CommonJS module that lists the entry among its children, most recently loaded first, by
+    //   Module._cache's insertion order, with the entry's module.parent last of them. Node's updateChildren records a
+    //   cached require too, so a consumer that requires the client later is found at the next construction;
+    // - the main module's directory and that of process.argv[1];
+    // - the working directory.
+    // An ES module that imports the client is never its parent or one of the cached modules that list it, so an ESM
+    // consumer is reached only through those last places. A found adapter is kept, and said once if a miss was said
+    // before it. A place that missed is not asked again (`missedPlaces`): a new consumer brings a new place, and no
+    // resolve is repeated. A miss is said once, and the construction is left as it was. Module._cache is read at each
+    // construction without an adapter until one is found, a walk of the cache's entries and no file system work.
+    let Adapter;
+    let missSaid = false;
+    const missedPlaces = new Set();
+    const adapterFor = () => {
+      if (Adapter) return Adapter;
+      const consumers = [module.parent, ...Object.values(Module._cache).filter((other) => other && other !== module.parent && Array.isArray(other.children) && other.children.includes(module))]
+        .filter((consumer) => consumer && consumer.filename).reverse();
+      // Each place with the module it is asked for, so the adapter loads as that module's child (Node's bookkeeping
+      // of parent and children only; resolution is by `paths`).
+      const places = new Map();
+      for (const consumer of consumers) if (!places.has(path.dirname(consumer.filename))) places.set(path.dirname(consumer.filename), consumer);
+      if (require.main && require.main.filename && !places.has(path.dirname(require.main.filename))) places.set(path.dirname(require.main.filename), require.main);
+      if (typeof process.argv[1] === 'string' && process.argv[1] && !places.has(path.dirname(path.resolve(process.argv[1])))) places.set(path.dirname(path.resolve(process.argv[1])), null);
+      if (!places.has(process.cwd())) places.set(process.cwd(), null);
+      let reason = `${facts.adapter} is not installed in this application`;
+      for (const [from, consumer] of places) {
+        if (missedPlaces.has(from)) continue;
+        let loaded;
+        try { loaded = Module._load(require.resolve(facts.adapter, { paths: [from] }), consumer, false); }
+        catch { missedPlaces.add(from); continue; }
+        const found = loaded && loaded[facts.export];
+        if (typeof found === 'function') {
+          Adapter = found;
+          if (missSaid) process.stderr.write(`[twin-inject] ${vendor}: ${facts.adapter} found from ${from}; a Prisma client constructed without an adapter from now on gets it\n`);
+          return Adapter;
+        }
+        missedPlaces.add(from);
+        reason = `${facts.adapter} exports no ${facts.export}`;
+      }
       // Left as it was, said once: on the client engine Prisma refuses the construction itself;
       // on the library engine the client reaches the twin over the vendor's own wire.
-      process.stderr.write(`[twin-inject] ${vendor}: ${facts.adapter} is not installed in this application, so a Prisma client constructed without an adapter is left as it was\n`);
-      exports.PrismaClient.__volterAdapted = true;
-      return exports;
-    }
-    const Adapter = adapterModule && adapterModule[facts.export];
-    if (typeof Adapter !== 'function') {
-      process.stderr.write(`[twin-inject] ${vendor}: ${facts.adapter} exports no ${facts.export}; a Prisma client constructed without an adapter is left as it was\n`);
-      exports.PrismaClient.__volterAdapted = true;
-      return exports;
-    }
+      if (!missSaid) { missSaid = true; process.stderr.write(`[twin-inject] ${vendor}: ${reason}, so a Prisma client constructed without an adapter is left as it was until it is found\n`); }
+      return undefined;
+    };
     const Base = exports.PrismaClient;
     class PrismaClient extends Base {
       constructor(options) {
@@ -180,16 +209,18 @@ function installPrismaAdapterShim() {
         // decision. The URL is the application's where it names one (its host is twinned by the
         // injector's own host rules), else the endpoint template's variable.
         if ('adapter' in given) { super(given); return; }
+        const Found = adapterFor();
+        // Left as it was: Prisma is given exactly what the application passed (`new PrismaClient()` is no options).
+        if (!Found) { super(...arguments); return; }
         const named = given.datasources && typeof given.datasources === 'object'
           ? Object.values(given.datasources).map((source) => source && source.url).find((value) => typeof value === 'string') : undefined;
         const url = given.datasourceUrl || named || process.env[facts.urlEnv];
-        super({ ...given, adapter: new Adapter({ url, fetch: (...args) => globalThis.fetch(...args) }) });
+        super({ ...given, adapter: new Found({ url, fetch: (...args) => globalThis.fetch(...args) }) });
       }
     }
     PrismaClient.__volterAdapted = true;
     exports.PrismaClient = PrismaClient;
-    return exports;
-  };
+  });
 }
 
 // The exact inverse of readMap's env lookup: which vendor (if any) would the injector read
@@ -647,50 +678,77 @@ function routedTwin(url) {
 }
 // Imported Undici APIs may hold a dispatcher obtained before the global view was installed.
 // Rewrite their public HTTP doors as well; an independent connector still faces the socket guards.
-let UNDICI_LOAD = null;
+// PACKAGE ENTRIES, TAKEN WHEN THEY LOAD (S2): the preludes that act on one package (undici, @prisma/client, miniflare)
+// wrapped Module._load and ran on every load of the process to compare one name (LibreChat's server: 20,228 loads,
+// ~20 ms in the tab, none of it in native's path), and a wrapped Module._load kept the tab's engine on its slower
+// replaced-load route for every require. Each is now a patch of the package's entry module, made when that file is
+// loaded (Module._extensions['.js'], once per new module): the entry is loaded once per copy (every version, every
+// root, late or early) and cached, so the exports the patch leaves are what every later require of that copy is
+// answered, and an `import` of it loads it the same way. A copy loaded before this prelude ran is patched where it is
+// cached: its exports object is patched in place, so later requires and imports, and a module that holds that exports
+// object, see the patch; only a binding taken from it before the prelude ran (a destructured PrismaClient, an ES
+// module's namespace already linked) keeps the original. Known limits: a '.js' handler installed later that does not call the one it replaced hides the entries
+// loaded through it; an entry outside a node_modules directory (a linked checkout of the package) is not recognized.
+const ENTRY_PATCHES = [];
+let ENTRY_LOAD = null;
+function patchPackageEntry(pattern, patch) {
+  ENTRY_PATCHES.push({ pattern, patch });
+  for (const [filename, module] of Object.entries(Module._cache)) {
+    if (pattern.test(filename) && module && module.loaded) patch(module, filename);
+  }
+  if (ENTRY_LOAD) return;
+  const original = ENTRY_LOAD = Module._extensions['.js'];
+  Module._extensions['.js'] = function volterPackageEntry(module, filename) {
+    const result = original.apply(this, arguments);
+    for (const entry of ENTRY_PATCHES) if (entry.pattern.test(filename)) entry.patch(module, filename);
+    return result;
+  };
+}
+
+let UNDICI_ROUTED = false;
 function routeImportedUndici() {
-  if (UNDICI_LOAD) return;
-  const original = UNDICI_LOAD = Module._load;
-  const seen = new WeakMap();
-  Module._load = function volterUndiciLoad(request, parent, isMain) {
-    const exports = original.apply(this, arguments);
-    if (request !== 'undici' || !exports || typeof exports.request !== 'function') return exports;
-    if (seen.has(exports)) return seen.get(exports);
-    const view = Object.assign({}, exports);
-    view.fetch = function routedUndiciFetch(input, init) {
-      if (!installed) return exports.fetch(input, init);
-      let url; try { url = new URL(typeof input === 'object' && input?.url ? input.url : String(input)); } catch {}
-      const twin = routedTwin(url);
-      // Local control planes may use their own Request class and dispatcher. Preserve both;
-      // connections still pass the socket guards, and claimed vendor hops still enter routing.
-      if (url && isLocalOrPrivateHost(url.hostname) && (!twin || twin.vendor === 'app')) return exports.fetch(input, init);
-      if (input && typeof input === 'object' && typeof input.url === 'string' && !(input instanceof globalThis.Request)) {
-        const options = {};
-        for (const name of ['method', 'signal', 'redirect', 'cache', 'credentials', 'integrity', 'keepalive', 'referrer', 'referrerPolicy']) {
-          if (input[name] !== undefined) options[name] = input[name];
-        }
-        options.headers = Array.from(input.headers);
-        if (input.body !== null && input.body !== undefined) { options.body = input.body; options.duplex = 'half'; }
-        return globalThis.fetch(input.url, { ...options, ...init });
+  if (UNDICI_ROUTED) return;
+  UNDICI_ROUTED = true;
+  patchPackageEntry(/[\\/]node_modules[\\/]undici[\\/]index\.js$/, (module) => {
+    if (module.exports && typeof module.exports.request === 'function' && !ROUTED_UNDICI.has(module.exports)) module.exports = routedUndici(module.exports);
+  });
+}
+const ROUTED_UNDICI = new WeakSet();
+function routedUndici(exports) {
+  const view = Object.assign({}, exports);
+  view.fetch = function routedUndiciFetch(input, init) {
+    if (!installed) return exports.fetch(input, init);
+    let url; try { url = new URL(typeof input === 'object' && input?.url ? input.url : String(input)); } catch {}
+    const twin = routedTwin(url);
+    // Local control planes may use their own Request class and dispatcher. Preserve both;
+    // connections still pass the socket guards, and claimed vendor hops still enter routing.
+    if (url && isLocalOrPrivateHost(url.hostname) && (!twin || twin.vendor === 'app')) return exports.fetch(input, init);
+    if (input && typeof input === 'object' && typeof input.url === 'string' && !(input instanceof globalThis.Request)) {
+      const options = {};
+      for (const name of ['method', 'signal', 'redirect', 'cache', 'credentials', 'integrity', 'keepalive', 'referrer', 'referrerPolicy']) {
+        if (input[name] !== undefined) options[name] = input[name];
       }
-      return globalThis.fetch(input, init);
-    };
-    view.request = function routedUndiciRequest(input, options, callback) {
-      if (!installed) return exports.request.apply(exports, arguments);
-      const opts = typeof options === 'function' ? {} : options ?? {};
-      let url; try { url = new URL(String(input)); if (opts.path !== undefined) url = new URL(url.origin + String(opts.path)); } catch {}
-      const twin = routedTwin(url);
-      if (!twin || twin.vendor === 'app') return exports.request.apply(exports, arguments);
-      const headers = undiciHeaderObject(opts.headers);
-      headers.host = url.host; headers['x-volter-twin-original-host'] = url.host;
-      const key = twinsKey(); if (key) headers['x-twins-key'] = key;
-      const target = twin.origin.replace(/\/$/, '') + url.pathname + url.search;
-      const { path: _path, ...requestOptions } = opts; // target already carries the effective path and endpoint prefix
-      return exports.request(target, { ...requestOptions, headers, maxRedirections: 0 }, typeof options === 'function' ? options : callback);
-    };
-    seen.set(exports, view);
-    return view;
+      options.headers = Array.from(input.headers);
+      if (input.body !== null && input.body !== undefined) { options.body = input.body; options.duplex = 'half'; }
+      return globalThis.fetch(input.url, { ...options, ...init });
+    }
+    return globalThis.fetch(input, init);
+  };
+  view.request = function routedUndiciRequest(input, options, callback) {
+    if (!installed) return exports.request.apply(exports, arguments);
+    const opts = typeof options === 'function' ? {} : options ?? {};
+    let url; try { url = new URL(String(input)); if (opts.path !== undefined) url = new URL(url.origin + String(opts.path)); } catch {}
+    const twin = routedTwin(url);
+    if (!twin || twin.vendor === 'app') return exports.request.apply(exports, arguments);
+    const headers = undiciHeaderObject(opts.headers);
+    headers.host = url.host; headers['x-volter-twin-original-host'] = url.host;
+    const key = twinsKey(); if (key) headers['x-twins-key'] = key;
+    const target = twin.origin.replace(/\/$/, '') + url.pathname + url.search;
+    const { path: _path, ...requestOptions } = opts; // target already carries the effective path and endpoint prefix
+    return exports.request(target, { ...requestOptions, headers, maxRedirections: 0 }, typeof options === 'function' ? options : callback);
   };
+  ROUTED_UNDICI.add(view);
+  return view;
 }
 function unkeyUndiciDispatches() {
   if (!ORIGINAL_DEFINE_PROPERTY) return;
@@ -1712,12 +1770,25 @@ function installWorldTime() {
   const worldMs = () => { const c = clock(); return c ? clockNowMs(c, machineNow()) : machineNow(); };
   // the machine's own Date, wrapped rather than subclassed, so identity holds everywhere: dates Node makes itself
   // (a file's mtime, structuredClone, a worker's message) are `instanceof Date`, `d.constructor === Date` stays true,
-  // and Date.prototype is the machine's; only now() and argument-less construction read the World's time
-  const WorldDate = new Proxy(MachineDate, {
-    construct: (target, args, newTarget) => Reflect.construct(target, args.length ? args : [worldMs()], newTarget === WorldDate ? target : newTarget),
+  // and Date.prototype is the machine's; only now() and argument-less construction read the World's time. A bound
+  // function, not a Proxy: every `new Date(x)` of the app (a driver decoding dates) ran the Proxy's construct trap,
+  // ~15 ms of self time on LibreChat's server start in the tab (S2). Bound, so Function.prototype.toString of Date
+  // says "function () { [native code] }", as the Proxy's did; a bound function constructs its target with the target
+  // as new.target, and a subclass's own new.target passes through. Its prototype is the machine's; its own keys are
+  // the machine's Date's (length, name, prototype, now, parse, UTC), `now` the World's.
+  const worldDate = function Date(...args) {
     // called as a function, Date() answers the current time's string, as the machine's does
-    apply: () => new MachineDate(worldMs()).toString(),
-  });
+    if (new.target === undefined) return new MachineDate(worldMs()).toString();
+    return Reflect.construct(MachineDate, args.length ? args : [worldMs()], new.target === worldDate ? MachineDate : new.target);
+  };
+  worldDate.prototype = MachineDate.prototype;
+  const WorldDate = worldDate.bind(undefined);
+  Object.defineProperty(WorldDate, 'name', { value: 'Date', configurable: true });
+  Object.defineProperty(WorldDate, 'length', { value: MachineDate.length, configurable: true });
+  Object.defineProperty(WorldDate, 'prototype', { value: MachineDate.prototype });
+  for (const [key, value] of [['now', worldMs], ['parse', MachineDate.parse], ['UTC', MachineDate.UTC]]) {
+    Object.defineProperty(WorldDate, key, { value, writable: true, configurable: true, enumerable: false });
+  }
   Object.defineProperty(globalThis, Symbol.for('volter.machineDateNow'), { value: machineNow, enumerable: false });
   MachineDate.now = worldMs;
   Object.defineProperty(MachineDate.prototype, 'constructor', { value: WorldDate, writable: true, configurable: true, enumerable: false });
@@ -1780,17 +1851,12 @@ function installMiniflareOutbound() {
     };
     return Array.isArray(options.workers) ? { ...options, workers: options.workers.map(worker) } : worker(options);
   };
-  const originalLoad = Module._load;
-  const seen = new WeakMap();
-  Module._load = function volterMiniflareLoad(request, parent) {
-    const exports = originalLoad.apply(this, arguments);
-    if (request !== 'miniflare' || !exports || typeof exports.Miniflare !== 'function' || exports.Miniflare.__volterRouted) return exports;
-    if (seen.has(exports)) return seen.get(exports);
-    if (!outbound) {
-      let at = null;
-      try { at = Module._resolveFilename(request, parent); } catch { at = null; }
-      outbound = outboundFor(at, exports.fetch);
-    }
+  // The package's own entry (miniflare's `main`, dist/src/index.js), patched as it loads (PACKAGE ENTRIES).
+  patchPackageEntry(/[\\/]node_modules[\\/]miniflare[\\/]dist[\\/]src[\\/]index\.js$/, (module, filename) => {
+    const exports = module.exports;
+    if (!exports || typeof exports.Miniflare !== 'function' || exports.Miniflare.__volterRouted) return;
+    // the entry is the file `require('miniflare')` resolved to: its undici is the one beside it
+    if (!outbound) outbound = outboundFor(filename, exports.fetch);
     const Original = exports.Miniflare;
     class Miniflare extends Original {
       constructor(options) { super(routed(options)); }
@@ -1799,10 +1865,8 @@ function installMiniflareOutbound() {
     Miniflare.__volterRouted = true;
     // miniflare's build exports `Miniflare` as a getter that can be neither assigned nor redefined: its importer is given
     // a view of the module whose `Miniflare` is this one, the same view each time it is required.
-    const view = new Proxy(exports, { get: (target, key, receiver) => (key === 'Miniflare' ? Miniflare : Reflect.get(target, key, receiver)) });
-    seen.set(exports, view);
-    return view;
-  };
+    module.exports = new Proxy(exports, { get: (target, key, receiver) => (key === 'Miniflare' ? Miniflare : Reflect.get(target, key, receiver)) });
+  });
 }
 
 // Auto-install as a preload (`--require`); strict refusal also applies without twin URLs.

package/dist/network-policy.cjs

@@ -140,6 +140,16 @@ function allowsWorldNetworkEgress(policy, value, method = 'GET') {
   return granted(policy.egress, to) || (policy.phase === 'build' && policy.publicReads === true && PUBLIC_BUILD_READS.includes(to.url.origin));
 }
 
+/** Whether the config grants this request by name (`egress` for a read, `writes` for any method): the grant that takes a
+ *  build World's request past a twinned host's twin to its real origin. The unlisted public build reads are not one:
+ *  on a twinned host the twin answers them (architecture, "Reads are granted generously, writes narrowly"). */
+function explicitlyGrantsWorldNetworkEgress(policy, value, method = 'GET') {
+  const to = destination(value, true);
+  if (!to) return false;
+  if (granted(policy.writes ?? [], to)) return true;
+  return READ_METHODS.includes(String(method).toUpperCase()) && granted(policy.egress, to);
+}
+
 function worldNetworkUsesPassthrough(policy, value) {
   const to = destination(value, true);
   if (!to || policy.phase !== 'build') return false;
@@ -222,4 +232,4 @@ function worldEgressRefusal(value, env = process.env, method = 'GET') {
   return answer.outcome === 'refuse' ? `${answer.reason} (${refusalSide(answer)})` : null;
 }
 
-module.exports = { worldAttachmentNetworkEnv, worldStrictEgress, worldGrantFromEnv, PUBLIC_BUILD_READS, READ_METHODS, intersectWorldNetwork, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough, isWorldInternalHost, worldEgressRefusal, WORLD_NETWORK_POLICY_ENV, normalizeWorldNetwork, createWorldNetworkPolicy, parseWorldNetworkPolicy, worldNetworkPolicyFromEnv, allowsWorldNetworkEgress };
+module.exports = { worldAttachmentNetworkEnv, worldStrictEgress, worldGrantFromEnv, PUBLIC_BUILD_READS, READ_METHODS, intersectWorldNetwork, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough, isWorldInternalHost, worldEgressRefusal, WORLD_NETWORK_POLICY_ENV, normalizeWorldNetwork, createWorldNetworkPolicy, parseWorldNetworkPolicy, worldNetworkPolicyFromEnv, allowsWorldNetworkEgress, explicitlyGrantsWorldNetworkEgress };

package/dist/network-policy.d.cts

@@ -10,6 +10,7 @@ export function worldNetworkPolicyFromEnv(env: Readonly<Record<string, string |
 export const READ_METHODS: readonly string[];
 export const PUBLIC_BUILD_READS: readonly string[];
 export function allowsWorldNetworkEgress(policy: WorldNetworkPolicy, value: string | URL, method?: string): boolean;
+export function explicitlyGrantsWorldNetworkEgress(policy: WorldNetworkPolicy, value: string | URL, method?: string): boolean;
 export function isWorldInternalHost(hostname: string): boolean;
 export function worldEgressRefusal(value: string | URL, env?: Readonly<Record<string, string | undefined>>, method?: string): string | null;
 export function worldNetworkNeedsPathInspection(policy: WorldNetworkPolicy, value: string | URL): boolean;

package/dist/pack-facts.d.cts

@@ -0,0 +1,3 @@
+export type PackFacts = { packs: Record<string, Record<string, unknown>>; installed: string[]; [key: string]: unknown };
+export function packFacts(): PackFacts;
+export function extendPackFacts(files: string[] | undefined): PackFacts;

package/dist/required-credential-transport.cjs

@@ -0,0 +1,29 @@
+// Metadata-only admission for native machine backings. Imports start no process and read no file.
+'use strict';
+
+exports.refuseRequiredMachineTransport = function refuseRequiredMachineTransport(source, transport) {
+  const path = source.VOLTER_WORLD_INSTANCE;
+  if (!path) {
+    if (source.VOLTER_WORLD) throw new Error('World machine execution has no retained credential declaration');
+    return; // No registered World declaration is asserted by the standalone provider.
+  }
+  const instance = JSON.parse(require('node:fs').readFileSync(path, 'utf8'));
+  if (!instance || typeof instance !== 'object' || Array.isArray(instance)
+    || !instance.env || instance.env.VOLTER_WORLD_INSTANCE !== path || instance.env.VOLTER_WORLD !== source.VOLTER_WORLD
+    || !Object.hasOwn(instance, 'requiredCredentials')) throw new Error('World machine boot lacks its own retained credential declaration');
+  const record = instance.requiredCredentials;
+  if (!record || typeof record !== 'object' || Array.isArray(record)
+    || Object.keys(record).some(key => !['version', 'owners', 'valuesSha256'].includes(key))
+    || !Object.hasOwn(record, 'version') || record.version !== 1 || !Object.hasOwn(record, 'owners')
+    || !record.owners || typeof record.owners !== 'object' || Array.isArray(record.owners))
+    throw new Error('World machine credential declaration has an unsupported version or shape');
+  if (Object.keys(record.owners).length) {
+    const error = new Error(`${transport} does not carry required credential bindings`);
+    error.code = 'WORLD_MACHINE_CAPABILITY_GAP';
+    throw error;
+  }
+  if (Object.hasOwn(record, 'valuesSha256')) {
+    const empty = require('node:crypto').createHash('sha256').update('[]').digest('hex');
+    if (record.valuesSha256 !== empty) throw new Error('World machine empty credential declaration changed');
+  }
+};

package/dist/required-credential-transport.d.cts

@@ -0,0 +1,3 @@
+/** Refuse a registered World's required declarations before a backing with no credential transport acts.
+ * Reads only the actual instance named by the provider's own environment; standalone providers assert no World proof. */
+export declare function refuseRequiredMachineTransport(source: Readonly<Record<string, string | undefined>>, transport: string): void;

package/dist/src/actions.d.ts

@@ -141,6 +141,21 @@ export declare function appendActionOccurrence(base: TwinAction, root?: string):
     appended: boolean;
     placeholder?: true;
 };
+/**
+ * Append several writes of ONE service as occurrences, in order, under one projection + actions lock and as one store
+ * append: each lands with the id, ordinal and correlation `appendActionOccurrence` would give it called once per write
+ * in the same order (a write's ordinal counts the batch's earlier writes as taken). A Redis run's flush made one
+ * append per changed member and key, each taking the history, projection and actions locks and appending alone, one
+ * after another under the twin's single command queue (S2 R19: Twenty's queue scripts spent up to 2.1 s of a 2 s
+ * window in flush while 38 commands waited). A write carrying preconditions is not taken here: each is checked against
+ * the state the earlier ones made, which only the one-at-a-time path sees. While a placeholder pull is open a write
+ * lands as observed events, as `appendActionOccurrence`'s does.
+ */
+export declare function appendActionOccurrences(bases: readonly TwinAction[], root?: string): Array<{
+    action: TwinAction;
+    appended: boolean;
+    placeholder?: true;
+}>;
 /** Occurrence 0 IS the base id — so nothing that exists today changes shape. The appender owns
  *  this math; a caller passing an already-ordinalled id would stack them (`…#1#1`). */
 export declare function occurrenceId(base: string, ordinal: number): string;

package/dist/src/actions.js

@@ -12,16 +12,16 @@ import { parseExactJson } from "./exact-json.js";
 //
 // Projection = observed mirror, then apply each `set` transaction in order,
 // skipping any transaction that was reverted or confirmed.
-import { withHistoryLock } from "./ancestry.js";
+import { canonicalStatePath, withHistoryLock } from "./ancestry.js";
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import { canonicalJson, subjectKey } from "./hash.js";
 import { appendDurable, eventsLockPath, ownerStoreRoots, projectionLockPath, twinLog, withFileLock, withoutIdentityClaim, worldPaths } from "./storage.js";
 import { landAsPlaceholder, placeholderPullActive } from "./placeholder-remote.js";
-import { aliasesFrom, dropCheckpoint, landedCopy, landedIds, parentEntries, readTree, treeStamp } from "./log.js";
+import { aliasesFrom, appendToBranchLog, dropCheckpoint, landedCopy, landedIds, parentEntries, readTree, treeStamp } from "./log.js";
 import { inVendorMove, refuseReadOnlyWrite } from "./request-scope.js";
-import { getActiveWorldStore } from "./world-store.js";
+import { getActiveWorldStore, storageLockScope } from "./world-store.js";
 import { currentTraceparent, traceparentForDelivery } from "./trace-context.js";
 export class TwinActionPreconditionError extends Error {
     actionId;
@@ -36,8 +36,11 @@ export class TwinActionPreconditionError extends Error {
 function actionsPath(service, root) {
     return join(dirname(worldPaths(service, root).events), 'actions.jsonl');
 }
-const actionsLock = (service, root) => `${actionsPath(service, root)}.lock`;
-const projectionLock = (service, root) => projectionLockPath(worldPaths(service, root));
+// Canonical, as the history lock's path is (ancestry.ts withHistoryLock), so a take inside it is seen as nested in the same
+// directory whatever the path it was asked by (/var or /private/var). The file is the same one, so a take by another
+// process through the other spelling still excludes this one.
+const actionsLock = (service, root) => join(canonicalStatePath(worldPaths(service, root).dir), 'actions.jsonl.lock');
+const projectionLock = (service, root) => { const paths = worldPaths(service, root); return projectionLockPath({ ...paths, dir: canonicalStatePath(paths.dir) }); };
 /** Every appended action carries a correlationId — generate one when the caller
  *  hasn't supplied it, so downstream joins (push ledger, logs) always have an id
  *  to key on (D3). Preserves a caller-supplied id (e.g. propagated from an HTTP
@@ -94,24 +97,38 @@ function actionIds(service, root) {
 }
 /** 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 withProjection(service, root, fn, options = {}) {
+    const scope = storageLockScope(options);
+    return withHistoryLock(worldPaths(service, root).dir, () => withFileLock(projectionLock(service, root), fn, scope), scope);
 }
 function appendActionRaw(action, root) {
-    const path = actionsPath(action.service, root);
-    getActiveWorldStore().mkdir(dirname(path));
+    appendActionsRaw([action], root);
+}
+/** One service's actions appended as ONE store append, in order: the same lines `appendActionRaw` writes one at a time. */
+function appendActionsRaw(actions, root) {
+    if (!actions.length)
+        return;
+    const service = actions[0].service;
+    const path = actionsPath(service, root);
+    // No mkdir: every append is made holding the projection lock (withProjection), whose file is in this same directory
+    // and was made there by the take (S2 R17 review).
     const memos = idMemoSlot(path);
     const held = memos.get(path);
     const current = held !== undefined && held.key === logKey(path);
-    withHistoryLock(worldPaths(action.service, root).dir, () => appendDurable(path, `${JSON.stringify(action)}\n`));
+    const data = actions.map((action) => `${JSON.stringify(action)}\n`).join('');
+    // the log is the branch log a read's tree is folded from: the append extends that memo too (log.ts appendToBranchLog)
+    const after = withHistoryLock(worldPaths(service, root).dir, () => appendToBranchLog(service, root, data, () => appendDurable(path, data)), { operation: 'action append' });
     if (current) {
-        held.ids.add(action.id);
-        held.key = logKey(path);
+        for (const action of actions)
+            held.ids.add(action.id);
+        held.key = after ?? logKey(path);
     }
     else
         memos.delete(path);
-    twinLog('action.append', { service: action.service, id: action.id, op: action.op, correlationId: action.correlationId });
-    appendObserver?.(action, root);
+    for (const action of actions) {
+        twinLog('action.append', { service: action.service, id: action.id, op: action.op, correlationId: action.correlationId });
+        appendObserver?.(action, root);
+    }
 }
 /** ONE observer of appended entries (state-system.ts: the runtime's `deploy: auto` hook). Called
  *  under the append locks, so it must only schedule work, never do it. */
@@ -173,7 +190,7 @@ export function appendAction(action, root) {
             return placeholder;
         appendActionRaw(stamped, root);
         return stamped;
-    }));
+    }, { operation: 'action append' }), { operation: 'action append' });
 }
 /** Append `action` only if no exact action with the same id already exists — the whole
  *  replay/precondition/append decision runs under the service projection + actions locks, so it's
@@ -196,7 +213,7 @@ export function appendActionIfAbsent(action, root) {
             return { action: placeholder, appended: true, placeholder: true };
         appendActionRaw(stamped, root);
         return { action: stamped, appended: true };
-    }));
+    }, { operation: 'action append' }), { operation: 'action append' });
 }
 /**
  * Append `build(n)` as an OCCURRENCE: the nth time this exact write has been made.
@@ -224,7 +241,51 @@ export function appendActionOccurrence(base, root) {
             return { action: placeholder, appended: true, placeholder: true };
         appendActionRaw(stamped, root);
         return { action: stamped, appended: true };
-    }));
+    }, { operation: 'action append' }), { operation: 'action append' });
+}
+/**
+ * Append several writes of ONE service as occurrences, in order, under one projection + actions lock and as one store
+ * append: each lands with the id, ordinal and correlation `appendActionOccurrence` would give it called once per write
+ * in the same order (a write's ordinal counts the batch's earlier writes as taken). A Redis run's flush made one
+ * append per changed member and key, each taking the history, projection and actions locks and appending alone, one
+ * after another under the twin's single command queue (S2 R19: Twenty's queue scripts spent up to 2.1 s of a 2 s
+ * window in flush while 38 commands waited). A write carrying preconditions is not taken here: each is checked against
+ * the state the earlier ones made, which only the one-at-a-time path sees. While a placeholder pull is open a write
+ * lands as observed events, as `appendActionOccurrence`'s does.
+ */
+export function appendActionOccurrences(bases, root) {
+    if (!bases.length)
+        return [];
+    const service = bases[0].service;
+    if (bases.some((base) => base.service !== service))
+        throw new Error(`appendActionOccurrences: one service per batch, got ${[...new Set(bases.map((base) => base.service))].join(', ')}`);
+    if (bases.some((base) => base.preconditions?.length))
+        throw new Error('appendActionOccurrences: a write with preconditions is appended alone');
+    refuseReadOnlyWrite(service);
+    return withProjection(service, root, () => withFileLock(actionsLock(service, root), () => {
+        const logged = actionIds(service, root);
+        const batch = new Set();
+        const taken = { has: (id) => batch.has(id) || logged.has(id) };
+        const landed = [];
+        let unwritten = [];
+        for (const base of bases) {
+            const stamped = occurrenceOf(base, taken, root);
+            const placeholder = landIfPlaceholderPull(stamped, root);
+            if (placeholder) {
+                // no action row: its id is not taken, as it is not in the log the one-at-a-time path reads
+                // the lines before it are written first, so the log and the pull keep the writes' order
+                appendActionsRaw(unwritten, root);
+                unwritten = [];
+                landed.push({ action: placeholder, appended: true, placeholder: true });
+                continue;
+            }
+            batch.add(stamped.id);
+            unwritten.push(stamped);
+            landed.push({ action: stamped, appended: true });
+        }
+        appendActionsRaw(unwritten, root);
+        return landed;
+    }, { operation: 'action append' }), { operation: 'action append' });
 }
 /** The occurrence rule, shared by both appenders that use it — the ordinal AND the merge base.
  *  Pure over (base, the log as it stands): the caller holds the lock. */
@@ -288,7 +349,7 @@ read = () => projectResources(service, root)) {
             return { value: decision.value, action: placeholder, appended: true, placeholder: true };
         appendActionRaw(stamped, root);
         return { value: decision.value, action: stamped, appended: true };
-    }));
+    }, { operation: 'action decision' }), { operation: 'action decision' });
 }
 export function appendTransactionCommit(commit, root) {
     return appendAction(commit, root);
@@ -439,9 +500,9 @@ export function confirmAction(opts) {
             for (const copy of copies)
                 if (!held.has(copy.id))
                     appendDurable(paths.events, `${JSON.stringify(copy)}\n`);
-        });
+        }, { operation: 'action confirmation' });
         dropCheckpoint(opts.service, opts.root);
-    });
+    }, { operation: 'action confirmation' });
     const observedEventIds = copies.map((c) => c.id);
     return { observedEventId: observedEventIds.at(-1), observedEventIds };
 }
@@ -477,7 +538,7 @@ export function revertAction(opts) {
         });
         appendActionRaw(revert, opts.root);
         return { status: 'reverted', revertId: revert.id };
-    }));
+    }, { operation: 'action revert' }), { operation: 'action revert' });
 }
 /** The LOCAL OVERLAY: pending actions (set, not reverted, not yet confirmed) — the divergence
  *  from the mirror, what a twin's projection folds over the observed state. A QUARANTINED row

package/dist/src/ancestry.d.ts

@@ -1,18 +1,19 @@
+import { type WorldLockOptions } from './world-store.js';
 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. 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;
+export declare function withAncestryLock<T>(fn: () => T, options?: WorldLockOptions): 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;
+export declare function withStateLock<T>(lockPath: string, fn: () => T, options?: WorldLockOptions): 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;
+export declare function withHistoryLock<T>(directory: string, fn: () => T, options?: WorldLockOptions): 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;
+export declare function withHistoryLocks<T>(directories: string[], fn: () => T, options?: WorldLockOptions): 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