@volter/world-core 3.0.156 → 3.0.157

package/dist/src/sockets.js

@@ -1,3 +1,12 @@
+// A vendor's persistent wire (architecture, "Other wires: sockets"): a WebSocket its clients hold open, on which the
+// vendor sends what happens as it happens (Discord's Gateway: a bot identifies, is told the guilds it is in, and is sent
+// each message, member and interaction as it lands). The manifest declares the socket (`sockets`); the pack's engine
+// (`semantics/sockets.ts`, one export per socket id) speaks its protocol: what a session is sent when it opens, what it
+// answers each frame, and which frames a write of the World sends it. The kernel holds the open sessions, serves the
+// upgrade through the serve seam, and offers every write to every open session of the vendor, after the write's
+// webhooks. A session's own counters (a sequence number, a heartbeat) are the connection's, never the World's state.
+// Nothing here runs at module scope beyond the empty registry.
+import { worldNow } from "./world-clock.js";
 const sessions = new Map();
 /** A World's next session number, per World (its service and root): a session's id is the World's, never the
  *  process's, so a life replayed on a fresh World numbers its sessions as it did the first time. */
@@ -7,6 +16,21 @@ const keyOf = (service, root) => `${service}\0${root ?? ''}`;
 export function openSessions(service, root, socket) {
     return [...(sessions.get(keyOf(service, root)) ?? [])].filter((o) => o.session.socket === socket).map((o) => o.session);
 }
+/** What a session awaits that the World's clock has run out (a life's `wait` past a relay's timeout), rejected as the
+ *  machine's clock would reject it; called as the vendor serves a request ("A request answered by a session"). */
+export function expireSocketWaits(service, root) {
+    const open = sessions.get(keyOf(service, root));
+    if (!open?.size)
+        return;
+    const now = Date.parse(worldNow());
+    for (const o of open)
+        for (const [k, p] of o.pending)
+            if (p.due <= now) {
+                clearTimeout(p.timer);
+                o.pending.delete(k);
+                p.reject(new Error('no reply in time'));
+            }
+}
 /** Offer a write to every open session of the vendor, each in its turn after what it is already doing. Queued, never
  *  awaited: the write may be one a session's own frame made, which that session finishes before it is told. */
 export function socketWrite(service, root, write) {
@@ -20,12 +44,41 @@ export function socketWrite(service, root, write) {
         o.queue = o.queue.then(async () => engine.write(o.session, write, await o.context())).catch((error) => o.session.close(1011, String(error.message ?? error).slice(0, 120)));
     }
 }
+/** A declared socket path's parameters for a request's path, or undefined when it does not match: a `{name}` segment
+ *  matches one segment, as an operation's path parameter does (architecture, sockets). */
+function socketParams(declared, path) {
+    const names = [];
+    const pattern = (declared.replace(/\/+$/, '') || '/').split(/(\{[^}/]+\})/).map((part) => {
+        const name = /^\{([^}/]+)\}$/.exec(part)?.[1];
+        if (name === undefined)
+            return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        names.push(name);
+        return '([^/]+)';
+    }).join('');
+    const hit = new RegExp(`^${pattern}$`).exec(path);
+    if (!hit)
+        return undefined;
+    try {
+        return Object.fromEntries(names.map((name, i) => [name, decodeURIComponent(hit[i + 1])]));
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
 export function socketUpgrade(service, root, decls, engines, context, hostOf, pathOf = (request) => new URL(request.url).pathname, decide = async () => undefined) {
-    const declFor = (request) => decls.find((d) => {
+    const matchFor = (request) => {
         const path = pathOf(request).replace(/\/+$/, '') || '/';
-        return (d.path.replace(/\/+$/, '') || '/') === path && (!d.host || d.host.toLowerCase() === hostOf(request)) && engines[d.id] !== undefined;
-    });
+        for (const d of decls) {
+            if ((d.host && d.host.toLowerCase() !== hostOf(request)) || engines[d.id] === undefined)
+                continue;
+            const params = socketParams(d.path, path);
+            if (params)
+                return { decl: d, params };
+        }
+        return undefined;
+    };
+    const declFor = (request) => matchFor(request)?.decl;
     const byPeer = new WeakMap();
     const key = keyOf(service, root);
     return {
@@ -38,7 +91,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
             return declared ? offered.find((p) => declared.includes(p)) : offered[0];
         },
         open: (peer, request) => {
-            const decl = declFor(request);
+            const { decl, params } = matchFor(request);
             const engine = engines[decl.id];
             const pending = new Map();
             const session = {
@@ -47,7 +100,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
                 close: (code, reason) => { peer.close(code, reason); },
                 expect: (key, ms) => new Promise((resolve, reject) => {
                     const timer = setTimeout(() => { pending.delete(key); reject(new Error('no reply in time')); }, ms);
-                    pending.set(key, { resolve, reject, timer });
+                    pending.set(key, { resolve, reject, timer, due: Date.parse(worldNow()) + ms });
                 }),
                 fulfil: (key, value) => {
                     const p = pending.get(key);
@@ -60,7 +113,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
                 },
                 decide,
             };
-            const o = { session, engine, context: () => context(request.clone(), decl), queue: Promise.resolve(), pending };
+            const o = { session, engine, context: () => context(request.clone(), decl, params), queue: Promise.resolve(), pending };
             byPeer.set(peer, o);
             (sessions.get(key) ?? sessions.set(key, new Set()).get(key)).add(o);
             if (engine.open)

package/dist/src/vendor-call.js

@@ -34,6 +34,52 @@ async function worldTwins() {
     }
     return { ...twinOrigins(env), ...twinOrigins(instanceEnv) };
 }
+/** The hosts each claiming twin last listed at its `hostsClaimed` door, by the door's address, and when; read again
+ *  after CLAIMS_TTL_MS or for a host it lacks, as the injector polls the doors every five seconds (inject.cjs, "HOSTS A TWIN CLAIMS WHILE IT
+ *  RUNS"). */
+const claimsRead = new Map();
+const CLAIMS_TTL_MS = 5_000;
+/** The hosts a twin claims at its door: in process (a journey walk's companion) or at its address, within the injector's
+ *  first-read deadline (inject.cjs CLAIMS_WAIT_MS, 1500 ms, measured beside it); a door that does not answer claims
+ *  nothing. */
+async function claimedHosts(at, ask, host) {
+    const held = claimsRead.get(at);
+    // a host the held list lacks is asked for again once, as the injector refreshes before it refuses: a domain claimed a
+    // moment ago is found
+    if (held && Date.now() - held.at < CLAIMS_TTL_MS && held.hosts.has(host))
+        return held.hosts;
+    let hosts = new Set();
+    try {
+        const r = await ask();
+        const body = r.ok ? await r.json() : null;
+        hosts = new Set((body?.hosts ?? []).map((h) => String(h).toLowerCase()));
+    }
+    catch { /* an unanswered door claims nothing */ }
+    claimsRead.set(at, { hosts, at: Date.now() });
+    return hosts;
+}
+/** The twin that claims a host at its `hostsClaimed` door (an R2 bucket's custom domain, a Worker's), as the injector
+ *  routes it: a twin this process answers first, the World's twins after. */
+async function claimingTwin(target, twins) {
+    const { packFacts } = await import('../pack-facts.cjs');
+    const host = target.hostname.toLowerCase();
+    const key = process.env.VOLTER_TWINS_KEY;
+    const doors = Object.entries(packFacts().packs).flatMap(([vendor, facts]) => (facts.hostsClaimed?.door ? [[vendor, facts.hostsClaimed.door]] : []));
+    for (const [vendor, door] of doors) {
+        const twin = inProcessTwins[vendor];
+        if (twin && (await claimedHosts(`in-process:${vendor}${door}`, async () => twin(new Request(`http://${vendor}.twin${door}`)), host)).has(host))
+            return { vendor, local: true };
+    }
+    for (const [vendor, door] of doors) {
+        const origin = twins[vendor];
+        if (origin === undefined)
+            continue;
+        const at = `${origin.replace(/\/$/, '')}${door}`;
+        if ((await claimedHosts(at, () => fetch(at, { headers: key ? { 'x-twins-key': key } : {}, signal: AbortSignal.timeout(1500) }), host)).has(host))
+            return { vendor, local: false };
+    }
+    return undefined;
+}
 /** One URL answered only by a World-held application or vendor twin: the fetch's application stand-in first (its answer
  *  is the application's; `'unreachable'` leaves no application to reach, the World's twins still reachable). */
 async function worldResponse(target, init, standIn) {
@@ -61,9 +107,21 @@ async function worldResponse(target, init, standIn) {
             headers.set('x-twins-key', key);
         return fetch(`${twins[vendor].replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers, redirect: 'manual' });
     }
+    // the application's own hosts before any twin's claimed ones: a call to the application asks no door
     const { appDestination, appFetch } = await import('../app-route.cjs');
     if (scripted !== 'unreachable' && appDestination(target))
         return appFetch(target, { ...init, redirect: 'manual' });
+    const claimer = await claimingTwin(target, twins);
+    if (claimer !== undefined) {
+        const headers = new Headers(init.headers);
+        headers.set('x-volter-twin-original-host', target.host);
+        if (claimer.local)
+            return inProcessTwins[claimer.vendor](new Request(target, { ...init, headers, redirect: 'manual' }));
+        const key = process.env.VOLTER_TWINS_KEY;
+        if (key && !headers.has('x-twins-key'))
+            headers.set('x-twins-key', key);
+        return fetch(`${twins[claimer.vendor].replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers, redirect: 'manual' });
+    }
     throw new VendorUnreachableError(`${target.host}${target.pathname}: this World holds no application or vendor twin at this URL`);
 }
 /** A vendor URL (or the World's application), including redirects, always answered inside the World; `standIn` is the

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

@@ -13,7 +13,21 @@ export type WorldLockOptions = {
     operation?: string;
     caller?: string;
 };
-/** Capture at the outermost lock helper, then carry the same caller through nested helpers. */
+/**
+ * Capture at the outermost lock helper, then carry the same caller through nested helpers.
+ * LIMIT THE CAPTURE TO THE FRAMES READ (browser-substrate S2 R44, AC-LC3): V8's third frame supplies the caller,
+ * while new Error().stack normally collects up to Error.stackTraceLimit frames (ten by default).
+ * Retained browser-substrate LibreChat World-realm warm-up profiles 73/74 from runs 36c6d279 and 991f63e7e
+ * attributed about 10-57 ms self/inclusive to storageLockScope over each full 13.3-13.4 second profile window.
+ * Samples are about 5 ms apart. Those totals include this helper's capture, string and regex work; they are
+ * neither isolated capture time nor the credential doors' share. The co-located host serves doors on one loop.
+ * Original profiles are under /Users/aaronclaw/heavy-lead/librechat/logs-kept/:
+ * librechat-sn-36c6d279-e9e2632a-004051/cpuprofile/ (SHA256 prefixes 04dfc4fe, 77df6e8e) and
+ * librechat-sn-991f63e7e/cpuprofile/ (be6c6a93, 2fe80e7c), realms 73 and 74 respectively.
+ * The limit is lowered to three only for Error's own writable numeric data property above three, and restored
+ * only when lowered. Absent, accessor, non-writable and lower limits receive no writes. Existing constructor
+ * and user stack-formatter failure paths remain; this diagnostic optimization changes no lock ownership rule.
+ */
 export declare function storageLockScope(options?: WorldLockOptions): WorldLockOptions & {
     operation: string;
     caller: string;

package/dist/src/world-store.js

@@ -28,9 +28,77 @@ import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { refuseReadOnlyWrite } from "./request-scope.js";
 import { basename, dirname, join, resolve } from 'node:path';
-/** Capture at the outermost lock helper, then carry the same caller through nested helpers. */
+// WHAT A LOCK HOLD ASKS (architecture, "What a hold asks is counted"): the file
+// store's questions counted inside an outermost lock hold and outside one, said at each outermost release where
+// VOLTER_TWIN_LOG=1 (storage.ts twinLog's gate and line), and not counted otherwise. Each counter counts the calls of
+// its own method: a readKept that misses its kept text, or meets a link, also counts the read it makes. A hold's
+// `heldMs` is the time of the hold's body, run once the lock is taken and before it is released, as the lock's release
+// line times its hold; the wait before the take is the wait line's `waitedMs`.
+const QUESTION_KINDS = ['generation', 'read', 'readKept', 'stat', 'exists', 'list', 'append'];
+// Read once, where a process is: a realm with none counts nothing.
+const questionsCounted = typeof process !== 'undefined' && process.env?.VOLTER_TWIN_LOG === '1';
+const noQuestions = () => ({ generation: 0, read: 0, readKept: 0, stat: 0, exists: 0, list: 0, append: 0 });
+let lockHoldDepth = 0;
+let questionsHeld = noQuestions();
+let questionsUnheld = noQuestions();
+function asked(kind) {
+    if (questionsCounted)
+        (lockHoldDepth > 0 ? questionsHeld : questionsUnheld)[kind] += 1;
+}
+function countedHold(operation, fn) {
+    if (!questionsCounted)
+        return fn;
+    return () => {
+        const began = Date.now();
+        lockHoldDepth += 1;
+        try {
+            return fn();
+        }
+        finally {
+            lockHoldDepth -= 1;
+            if (lockHoldDepth === 0) {
+                const held = questionsHeld, before = questionsUnheld;
+                questionsHeld = noQuestions();
+                questionsUnheld = noQuestions();
+                try {
+                    console.error('[twin:store-lock]', JSON.stringify({ operation, heldMs: Date.now() - began, held, before }));
+                }
+                catch { /* an instrument */ }
+            }
+        }
+    };
+}
+/**
+ * Capture at the outermost lock helper, then carry the same caller through nested helpers.
+ * LIMIT THE CAPTURE TO THE FRAMES READ (browser-substrate S2 R44, AC-LC3): V8's third frame supplies the caller,
+ * while new Error().stack normally collects up to Error.stackTraceLimit frames (ten by default).
+ * Retained browser-substrate LibreChat World-realm warm-up profiles 73/74 from runs 36c6d279 and 991f63e7e
+ * attributed about 10-57 ms self/inclusive to storageLockScope over each full 13.3-13.4 second profile window.
+ * Samples are about 5 ms apart. Those totals include this helper's capture, string and regex work; they are
+ * neither isolated capture time nor the credential doors' share. The co-located host serves doors on one loop.
+ * Original profiles are under /Users/aaronclaw/heavy-lead/librechat/logs-kept/:
+ * librechat-sn-36c6d279-e9e2632a-004051/cpuprofile/ (SHA256 prefixes 04dfc4fe, 77df6e8e) and
+ * librechat-sn-991f63e7e/cpuprofile/ (be6c6a93, 2fe80e7c), realms 73 and 74 respectively.
+ * The limit is lowered to three only for Error's own writable numeric data property above three, and restored
+ * only when lowered. Absent, accessor, non-writable and lower limits receive no writes. Existing constructor
+ * and user stack-formatter failure paths remain; this diagnostic optimization changes no lock ownership rule.
+ */
 export function storageLockScope(options = {}) {
-    const frame = options.caller ? undefined : new Error().stack?.split('\n')[3];
+    let frame;
+    if (!options.caller) {
+        const held = Object.getOwnPropertyDescriptor(Error, 'stackTraceLimit');
+        const lowered = held !== undefined && 'value' in held && held.writable === true
+            && typeof held.value === 'number' && held.value > 3;
+        if (lowered)
+            Error.stackTraceLimit = 3;
+        try {
+            frame = new Error().stack?.split('\n')[3];
+        }
+        finally {
+            if (lowered)
+                Error.stackTraceLimit = held.value;
+        }
+    }
     const location = frame?.slice(frame.lastIndexOf('(') + 1).trim().replace(/^at\s+/, '');
     const site = location?.match(/^(.*):(\d+):\d+\)?$/);
     const caller = options.caller ?? (site ? `${site[1].replace(/^file:\/\//, '')}:${site[2]}` : 'unknown:0');
@@ -564,6 +632,7 @@ export class FsWorldStore {
     // pays a kernel exchange for each, and a tree's stamp is a handful of these on every operation: Twenty's Redis twin
     // spent 54 s of 136 in `existsSync` and `statSync` under `treeStamp`, and its server's requests waited on it.
     read(path) {
+        asked('read');
         try {
             return readFileSync(path, 'utf8');
         }
@@ -586,6 +655,7 @@ export class FsWorldStore {
      */
     kept = new Map();
     readKept(path) {
+        asked('readKept');
         // A missing file is asked for without an error being made of it: a World with no parent has no branch.json, and
         // every stamp asks.
         let own;
@@ -639,6 +709,7 @@ export class FsWorldStore {
      * World with a parent: its view and its ancestors' logs) is never kept under a generation (log.ts).
      */
     generation(dirPath) {
+        asked('generation');
         let own;
         try {
             own = lstatSync(join(dirPath, TREE_GENERATION), { throwIfNoEntry: false });
@@ -721,6 +792,7 @@ export class FsWorldStore {
         }
     }
     append(path, data) {
+        asked('append');
         refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         this.kept.delete(path);
         // A tree's file in a tab: the generation's byte, the append and the byte again as one request of the kernel
@@ -774,6 +846,7 @@ export class FsWorldStore {
         });
     }
     exists(path) {
+        asked('exists');
         return existsSync(path);
     }
     remove(path) {
@@ -787,6 +860,7 @@ export class FsWorldStore {
         mkdirSync(dirPath, { recursive: true });
     }
     list(dirPath) {
+        asked('list');
         try {
             return readdirSync(dirPath);
         }
@@ -818,6 +892,7 @@ export class FsWorldStore {
         }
     }
     stat(path) {
+        asked('stat');
         // The path itself first: where it is no link, that is the whole answer. A link is followed by a second call,
         // and one that leads nowhere is absent, as it was.
         // Asked without an error being made of a missing path (a tree's parent log is absent in a World with no parent).
@@ -852,6 +927,7 @@ export class FsWorldStore {
     withLock(lockPath, fn, options = {}) {
         const started = Date.now();
         const scope = storageLockScope(options);
+        fn = countedHold(scope.operation, fn);
         let fd = null;
         // A kernel's file step takes the lock with its record in one request and keeps no descriptor (fileSteps).
         const steps = fileSteps();

package/generated/pack-facts.json

@@ -221,6 +221,50 @@
       },
       "serveExport": "createAxiomTwinServer"
     },
+    "bitly": {
+      "adoption": {
+        "sdks": [],
+        "envStems": [
+          "BITLY",
+          "BUFFER_BITLY"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "api-ssl.bitly.com"
+        },
+        {
+          "host": "bitly.com",
+          "pathPattern": "^/oauth/authorize/?$"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "group",
+        "bitlink"
+      ],
+      "endpointEnvNone": "Dub uses literal vendor URLs and native fetch; the World routes them by host.",
+      "credentialDoor": {
+        "path": "/_twin/signup",
+        "body": {
+          "email": "publisher@example.test",
+          "password": "throwaway-bitly-password",
+          "login": "publisher"
+        },
+        "fill": {
+          "BITLY_CLIENT_ID": "client_id",
+          "BITLY_CLIENT_SECRET": "client_secret",
+          "BUFFER_BITLY_API_KEY": "access_token"
+        }
+      },
+      "serveExport": "createBitlyTwinServer"
+    },
     "cerebras": {
       "adoption": {
         "sdks": [
@@ -270,6 +314,9 @@
         {
           "host": "api.clerk.com"
         },
+        {
+          "host": "dashboard.clerk.com"
+        },
         {
           "suffix": ".clerk.accounts.dev"
         },
@@ -594,7 +641,7 @@
       },
       "transport": "rest",
       "resources": [],
-      "endpointEnvNone": "Postiz calls https://api.deepgram.com/v1/listen; the World claims the host",
+      "endpointEnvNone": "No scanned application calls Deepgram; the World claims api.deepgram.com",
       "serveExport": "createDeepgramTwinServer"
     },
     "discord": {
@@ -842,7 +889,7 @@
       },
       "transport": "rest",
       "resources": [],
-      "endpointEnvNone": "Postiz calls https://fal.run/fal-ai/<model>; the World claims the hosts",
+      "endpointEnvNone": "the customer life calls https://fal.run/fal-ai/<model>; the World claims the hosts",
       "credentialDoor": {
         "path": "/_twin/app-credentials",
         "body": {},
@@ -1012,7 +1059,7 @@
         },
         {
           "host": "github.com",
-          "pathPattern": "^/login|^/session|^/settings/|^/organizations/|^/apps/|^/[^/]+/[^/]+/(?:info/refs|git-upload-pack|git-receive-pack)$|^/[^/]+/[^/]+\\.git/"
+          "pathPattern": "^/login|^/session|^/settings/|^/organizations/|^/apps/|^/[^/]+/[^/]+/(?:info/refs|git-upload-pack|git-receive-pack)$|^/[^/]+/[^/]+\\.git/|^/[^/]+/[^/]+/?$|^/[^/]+/[^/]+/(?:issues|pulls?|blob|raw|tree|commits?|compare)(?:/|$)"
         }
       ],
       "archetype": "crud",
@@ -1088,7 +1135,7 @@
         },
         {
           "host": "fonts.googleapis.com",
-          "pathPattern": "^/css$"
+          "pathPattern": "^/css2?$"
         },
         {
           "host": "fonts.gstatic.com",
@@ -1417,8 +1464,7 @@
           "host": "api.linear.app"
         },
         {
-          "host": "linear.app",
-          "pathPattern": "^/oauth/"
+          "host": "linear.app"
         }
       ],
       "archetype": "crud",
@@ -1438,7 +1484,7 @@
         "comment",
         "issue_label"
       ],
-      "endpointEnvNone": "Linear uses api.linear.app/graphql and linear.app/oauth/authorize; the World claims the documented hosts",
+      "endpointEnvNone": "Linear uses api.linear.app/graphql and linear.app for its workspace and OAuth authorize page; the World claims those hosts",
       "credentialDoor": {
         "path": "/_twin/local-credentials",
         "body": {},
@@ -2048,6 +2094,10 @@
           "host": "reddit.com",
           "demandPathPattern": "^/api/"
         },
+        {
+          "host": "old.reddit.com",
+          "demandPathPattern": "^/api/"
+        },
         {
           "host": "reddit-uploaded-media.s3-accelerate.amazonaws.com"
         },
@@ -2163,6 +2213,10 @@
         },
         {
           "host": "inbound-cdn.resend.com"
+        },
+        {
+          "host": "resend.com",
+          "pathPattern": "^/emails(?:/|$)"
         }
       ],
       "archetype": "crud",
@@ -2319,6 +2373,9 @@
         ]
       },
       "hosts": [
+        {
+          "host": "app.slack.com"
+        },
         {
           "host": "slack.com"
         },
@@ -2697,7 +2754,7 @@
         "publish",
         "video"
       ],
-      "endpointEnvNone": "Postiz calls open.tiktokapis.com and sends people to www.tiktok.com; the World claims the hosts",
+      "endpointEnvNone": "an app calls open.tiktokapis.com and sends people to www.tiktok.com; the World claims the hosts",
       "credentialDoor": {
         "path": "/_twin/app-credentials",
         "body": {},
@@ -3280,6 +3337,18 @@
         "_code_challenge",
         "upload"
       ],
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "fill": {
+          "TWITTER_API_KEY": "consumer_key",
+          "TWITTER_API_SECRET": "consumer_secret",
+          "TWITTER_ACCESS_TOKEN": "access_token",
+          "TWITTER_ACCESS_SECRET": "access_token_secret",
+          "TWITTER_CLIENT_ID": "client_id",
+          "TWITTER_CLIENT_SECRET": "client_secret"
+        }
+      },
       "serveExport": "createXTwinServer"
     },
     "xai": {

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

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.156",
+  "version": "3.0.157",
   "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",
@@ -25,6 +25,8 @@
     "attach.cjs",
     "stream-bridge.cjs",
     "http-bridge.cjs",
+    "required-credential-transport.cjs",
+    "required-credential-transport.d.cts",
     "network-policy.cjs",
     "network-policy.d.cts",
     "capability-decision.cjs",
@@ -34,6 +36,7 @@
     "host-routing.cjs",
     "host-routing.d.cts",
     "pack-facts.cjs",
+    "pack-facts.d.cts",
     "vendor-hosts.d.cts",
     "world-clock.cjs",
     "world-clock.d.cts",
@@ -89,6 +92,10 @@
     "./attach": "./attach.cjs",
     "./stream-bridge": "./stream-bridge.cjs",
     "./http-bridge": "./http-bridge.cjs",
+    "./required-credential-transport": {
+      "types": "./required-credential-transport.d.cts",
+      "default": "./required-credential-transport.cjs"
+    },
     "./network-policy": {
       "types": "./network-policy.d.cts",
       "default": "./network-policy.cjs"

package/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/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;