@volter/world-core 2.0.20 → 2.0.22

package/dist/inject.cjs

@@ -728,8 +728,9 @@ function socketTargetHosts(args, isTls) {
     return hosts;
   }
   if (typeof first === 'string' && !/^\d+$/.test(first)) return hosts; // a unix socket path
-  hosts.push(typeof second === 'string' ? second : 'localhost');
   const options = typeof second === 'object' && second !== null ? second : typeof third === 'object' && third !== null ? third : null;
+  // connect(port, host) names the host; connect(port, { host }) puts it in the options, which Node merges
+  hosts.push(typeof second === 'string' ? second : typeof options?.host === 'string' ? options.host : 'localhost');
   if (isTls && options && options.servername) hosts.push(options.servername);
   return hosts;
 }
@@ -811,7 +812,15 @@ function patchedPromisesLookup(original) {
   };
 }
 
-function socketRefusal(hostname) {
+/** The port a net/tls connect names (`connect(port, host)`, `connect({ port, host })`), or undefined. */
+function socketTargetPort(args) {
+  const [first] = args;
+  const raw = first !== null && typeof first === 'object' ? first.port : first;
+  const port = Number(raw);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : undefined;
+}
+
+function socketRefusal(hostname, port, isTls) {
   const host = String(hostname || '').toLowerCase();
   if (host === WORLD_ADDRESS[4] || host === WORLD_ADDRESS[6]) {
     return `[twin-inject] refused a socket to ${host}, the address this World's DNS gives the names it routes: `
@@ -831,8 +840,11 @@ function socketRefusal(hostname) {
     return `[twin-inject] refused a raw socket to ${host}, which this world routes to the application (volter-world app-url --host): `
       + 'the client opened its own connection instead of going through http/https or fetch, so it could not be routed.';
   }
-  const url = (() => { try { return new URL(`https://${isIP(host) === 6 ? `[${host}]` : host}/`); } catch { return null; } })();
-  if (url && shouldBlockUntwinned(url)) return `[twin-inject] blocked untwinned external socket to ${host}`;
+  // the destination as an origin, its port and its protocol included: a policy that lists https://host allows TLS to
+  // host:443, never another port or a plaintext connection to it
+  const authority = `${isIP(host) === 6 ? `[${host}]` : host}${port !== undefined && !(isTls && port === 443) ? `:${port}` : ''}`;
+  const url = (() => { try { return new URL(`${isTls ? 'https' : 'http'}://${authority}/`); } catch { return null; } })();
+  if (url && shouldBlockUntwinned(url)) return `[twin-inject] blocked untwinned external socket to ${authority}`;
   return null;
 }
 
@@ -844,8 +856,9 @@ function refusedSocket(message) {
 
 function patchedConnect(originalConnect, isTls) {
   return function patchedSocketConnect(...args) {
+    const port = socketTargetPort(args);
     for (const host of socketTargetHosts(args, isTls)) {
-      const refusal = socketRefusal(host);
+      const refusal = socketRefusal(host, port, isTls);
       if (refusal) return refusedSocket(refusal);
     }
     return originalConnect.apply(this, args);

package/dist/network-policy.cjs

@@ -66,9 +66,11 @@ function isWorldInternalHost(hostname) {
   const v4 = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(h);
   if (v4) {
     const a = Number(v4[1]); const b = Number(v4[2]);
-    return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    // not link-local 169.254/16: it holds a cloud's instance metadata (169.254.169.254), the box's credentials
+    return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
   }
-  return h.includes(':') && (h.startsWith('fc') || h.startsWith('fd') || h.startsWith('fe80:'));
+  // nor fe80::/10, nor a cloud's IPv6 metadata address (fd00:ec2::254)
+  return h.includes(':') && (h.startsWith('fc') || h.startsWith('fd')) && h !== 'fd00:ec2::254';
 }
 
 /**

package/dist/src/actions.js

@@ -19,9 +19,9 @@ 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 { refuseReadOnlyWrite } from "./request-scope.js";
+import { inVendorMove, refuseReadOnlyWrite } from "./request-scope.js";
 import { getActiveWorldStore } from "./world-store.js";
-import { currentTraceparent } from "./trace-context.js";
+import { currentTraceparent, traceparentForDelivery } from "./trace-context.js";
 export class TwinActionPreconditionError extends Error {
     actionId;
     failed;
@@ -46,8 +46,11 @@ function withCorrelationId(action) {
     // into the handler's async context) is the correlation when the caller supplies none — the
     // join from a request on the wire to the action rows it caused, with no pack involved.
     const correlated = action.correlationId ? action : { ...action, correlationId: currentCorrelationId() ?? randomUUID() };
-    // the request's W3C trace context (trace-context.ts) is stamped the same way, from the handler's async context
-    const traceparent = correlated.traceparent === undefined ? currentTraceparent() : undefined;
+    // the request's W3C trace context (trace-context.ts) is stamped the same way, from the handler's async context. What the
+    // vendor makes on its own while a request is served (its actor is the system's, or a vendor move) is a span of its own
+    // in that trace, so it is never joined to the request's caller (served-world's timeline), who did not make it
+    const vendors = action.actor?.kind === 'system' || inVendorMove();
+    const traceparent = correlated.traceparent === undefined ? (vendors ? traceparentForDelivery() : currentTraceparent()) : undefined;
     return traceparent ? { ...correlated, traceparent } : correlated;
 }
 /** Subjects a `set` action touches: its own subject, every projection resource, and every

package/dist/src/index.d.ts

@@ -6,7 +6,7 @@ export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.js';
 export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from './twin-fetch.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.js';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.js';
-export { currentTraceparent, deliveryTraceHeaders, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';
+export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';
 export type { Traceparent } from './trace-context.js';
 export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.js';
 export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.js';
@@ -33,7 +33,7 @@ export { SqlWorldStore } from './world-store-sql.js';
 export type { SqlExec } from './world-store-sql.js';
 export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, } from './blob-store.js';
 export type { BlobStore } from './blob-store.js';
-export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, journalTwinRequest, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from './serve.js';
+export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, journalTwinRequest, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, readTwinRequestJournalFrom, type TwinRequestJournalCursor, twinResources, } from './serve.js';
 export type { AtomicTwinWriteDecision, TwinRequestJournalEntry, TwinResource, TwinWriteInput, TwinWriteResult, } from './serve.js';
 export { createTwinProxy } from './proxy.js';
 export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.js';

package/dist/src/index.js

@@ -17,7 +17,7 @@ export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
 export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from "./twin-fetch.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
-export { currentTraceparent, deliveryTraceHeaders, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
+export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
 export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from "./derived-core.js";
 export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from "./emit.js";
 // The vendor-agnostic CLIENT-SIDE RATE BUDGET — the fail-closed backstop a pack's guarded client
@@ -55,7 +55,7 @@ export { SqlWorldStore } from "./world-store-sql.js";
 // The blob seam (runtime contract R11): byte storage behind byte-carrying handlers, so a
 // serverless namespace puts bytes in object storage while local worlds keep today's layout.
 export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, } from "./blob-store.js";
-export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, journalTwinRequest, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from "./serve.js";
+export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, journalTwinRequest, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, readTwinRequestJournalFrom, twinResources, } from "./serve.js";
 export { createTwinProxy } from "./proxy.js";
 export { forkTwin, isFork, readForkMeta, } from "./fork.js";
 export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";

package/dist/src/request-scope.d.ts

@@ -21,6 +21,8 @@ export declare function runAsReadOnlyRequest<T>(fn: () => T | Promise<T>): Promi
 /** Run `fn` as the VENDOR's own move (a pack's catch-up): its writes land even under a read-only
  *  request. Outside one it changes nothing. */
 export declare function runAsVendorMove<T>(fn: () => T): T;
+/** Whether this runs as the vendor's own move (runAsVendorMove). */
+export declare function inVendorMove(): boolean;
 /** Whether a write attempted here would be refused. */
 export declare function writesRefused(): boolean;
 /** The write seam's check: throws (and records) the refusal when a write attempted here is a

package/dist/src/request-scope.js

@@ -14,6 +14,7 @@
 // Created on first use, never at import: a browser bundle of a mirror client carries the kernel and
 // has no AsyncLocalStorage (see serve.ts identitySlot).
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { runWithTraceparent, traceparentForDelivery } from "./trace-context.js";
 /** The request header that marks a request read-only. Its one value is `1`. */
 export const READ_ONLY_REQUEST_HEADER = 'x-volter-read-only';
 /** Whether a request carries the read-only marker. */
@@ -52,8 +53,14 @@ export async function runAsReadOnlyRequest(fn) {
  *  request. Outside one it changes nothing. */
 export function runAsVendorMove(fn) {
     const current = writeScope().getStore();
-    return current ? writeScope().run({ ...current, vendorMove: true }, fn) : fn();
+    // the vendor's move is its own span of the request's trace (a delivery's shape): what it writes is joined to the
+    // trace, never to the request's caller, who did not make it
+    const own = traceparentForDelivery();
+    const run = own ? () => runWithTraceparent(own, fn) : fn;
+    return current ? writeScope().run({ ...current, vendorMove: true }, run) : run();
 }
+/** Whether this runs as the vendor's own move (runAsVendorMove). */
+export function inVendorMove() { return writeScopeStore?.getStore()?.vendorMove === true; }
 /** Whether a write attempted here would be refused. */
 export function writesRefused() {
     const scope = writeScopeStore?.getStore();

package/dist/src/serve.d.ts

@@ -15,6 +15,10 @@ export type TwinCredentialShape = {
     /** the name arrived with an EMPTY value — the "the SDK sent the header but no key" case. */
     empty?: true;
 };
+/** The header a World puts on a request it forwards to a twin: who made it (`key:<name>`, `person:<who>`, `token`,
+ *  `token:read`). The World replaces any a caller sent; the serve seam records it in the twin's request journal and
+ *  removes it before the twin's handler. A twin reached on its own port, not through a World, records what it was sent. */
+export declare const CALLER_HEADER = "x-volter-caller";
 export type TwinRequestJournalEntry = {
     at?: string;
     method: string;
@@ -24,6 +28,14 @@ export type TwinRequestJournalEntry = {
     ms?: number;
     /** credential-looking headers/query params that arrived, named + fingerprinted, never quoted. */
     credentials?: TwinCredentialShape[];
+    /** who made it, as the World named its caller (CALLER_HEADER: `key:<name>`, `person:<who>`, `token`); absent for a
+     *  request that did not come through a World */
+    caller?: string;
+    /** the request's trace-id and parent-id (its `traceparent`). The World mints the parent-id of every request it
+     *  forwards, and the request's log entries carry it, so an entry is joined to its caller by `span`, which no caller
+     *  chooses (a trace-id is the caller's and spans requests) */
+    trace?: string;
+    span?: string;
     /** `request`: written BEFORE the request is served (an audit device's request entry, so a request whose
      *  audit cannot be written is refused); its outcome is the entry without a phase written after. */
     phase?: 'request';
@@ -36,6 +48,23 @@ export declare function readTwinRequestJournal(service: string, root?: string, o
 /** Journal lines this process failed to keep, since it started, for one service's journal under `root`
  *  (a World's request report sums its own twins and links). */
 export declare function twinRequestJournalFailures(service: string, root?: string): number;
+/** Where a reader of a journal stopped: the newest closed segment it had seen and the bytes of the live file it read. */
+export type TwinRequestJournalCursor = {
+    segment: number;
+    offset: number;
+};
+/** The journal's lines after `cursor` (all of them without one), and the cursor to read on from. A rotation closes
+ *  the live file into the next segment as it stood, so a reader that stopped in the live file goes on in that
+ *  segment at its offset, then any later segments, and the next read takes the live file from its start; a live file shorter than where
+ *  the reader stopped (read between a rotation's two writes) is read again from its start, its lines repeated rather
+ *  than lost. Only whole lines are read (a line being appended is read next time). Without a cursor, the newest
+ *  `segments` closed segments are read (all of them when omitted), then the live file. */
+export declare function readTwinRequestJournalFrom(service: string, root: string | undefined, cursor: TwinRequestJournalCursor | null, options?: {
+    segments?: number;
+}): {
+    entries: TwinRequestJournalEntry[];
+    cursor: TwinRequestJournalCursor;
+};
 /** Non-reversible, stable fingerprint. 64 bits of sha256 — enough that two distinct credentials
  *  never collide in a journal, far too little to walk back to a real key. */
 export declare function credentialFingerprint(value: string): string;

package/dist/src/serve.js

@@ -18,6 +18,11 @@ import { hashFieldValue } from "./hash.js";
 import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, projectResources } from "./actions.js";
 import { observeWorldPaths, worldPaths } from "./storage.js";
 import { getActiveWorldStore } from "./world-store.js";
+import { parseTraceparent } from "./trace-context.js";
+/** The header a World puts on a request it forwards to a twin: who made it (`key:<name>`, `person:<who>`, `token`,
+ *  `token:read`). The World replaces any a caller sent; the serve seam records it in the twin's request journal and
+ *  removes it before the twin's handler. A twin reached on its own port, not through a World, records what it was sent. */
+export const CALLER_HEADER = 'x-volter-caller';
 /** The journal's closed segments, oldest first: `requests.jsonl.<n>` beside the live file. */
 function journalSegments(path) {
     const base = path.slice(path.lastIndexOf('/') + 1);
@@ -70,6 +75,49 @@ export function twinRequestJournalFailures(service, root) {
         return 0;
     }
 }
+/** The journal's lines after `cursor` (all of them without one), and the cursor to read on from. A rotation closes
+ *  the live file into the next segment as it stood, so a reader that stopped in the live file goes on in that
+ *  segment at its offset, then any later segments, and the next read takes the live file from its start; a live file shorter than where
+ *  the reader stopped (read between a rotation's two writes) is read again from its start, its lines repeated rather
+ *  than lost. Only whole lines are read (a line being appended is read next time). Without a cursor, the newest
+ *  `segments` closed segments are read (all of them when omitted), then the live file. */
+export function readTwinRequestJournalFrom(service, root, cursor, options = {}) {
+    const path = twinRequestJournalPath(service, root);
+    const store = getActiveWorldStore();
+    const segments = journalSegments(path).map((file) => Number(file.slice(path.length + 1)));
+    const newest = segments[segments.length - 1] ?? 0;
+    const entries = [];
+    const take = (file, start, whole) => {
+        const text = store.readRange ? store.readRange(file, start) : ((t) => (t === null ? null : Buffer.from(t, 'utf8').subarray(start).toString('utf8')))(store.read(file));
+        if (!text)
+            return start;
+        const end = whole ? text.length : text.lastIndexOf('\n') + 1;
+        for (const line of text.slice(0, end).split('\n')) {
+            if (!line)
+                continue;
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch { /* a torn line */ }
+        }
+        return start + Buffer.byteLength(text.slice(0, end), 'utf8');
+    };
+    if (cursor === null) {
+        for (const n of options.segments === undefined ? segments : segments.slice(-options.segments))
+            take(`${path}.${n}`, 0, true);
+        return { entries, cursor: { segment: newest, offset: take(path, 0, false) } };
+    }
+    if (newest === cursor.segment) {
+        const from = (store.stat(path)?.size ?? 0) < cursor.offset ? 0 : cursor.offset;
+        return { entries, cursor: { segment: newest, offset: take(path, from, false) } };
+    }
+    for (const n of segments)
+        if (n > cursor.segment)
+            take(`${path}.${n}`, n === cursor.segment + 1 ? cursor.offset : 0, true);
+    // the live file is read next time, from its start: read now, it may be the one the rotation has not emptied yet,
+    // and an offset into it would land inside the new one
+    return { entries, cursor: { segment: newest, offset: 0 } };
+}
 /** ~1 MB per segment: tens of thousands of entries (a shape line is ~80 bytes), and a report over a
  *  recent period reads only the segments that reach into it. */
 const REQUEST_JOURNAL_MAX_BYTES = 1_000_000;
@@ -155,6 +203,9 @@ export function journalTwinRequest(service, entry, root) {
     const line = JSON.stringify({
         at: entry.at ?? new Date().toISOString(),
         ...(entry.phase ? { phase: entry.phase } : {}),
+        ...(entry.caller ? { caller: entry.caller.slice(0, 120) } : {}),
+        ...(entry.trace && /^[0-9a-f]{32}$/.test(entry.trace) ? { trace: entry.trace } : {}),
+        ...(entry.span && /^[0-9a-f]{16}$/.test(entry.span) ? { span: entry.span } : {}),
         method: entry.method.toUpperCase(),
         path: entry.path.split('?')[0], // the query STRING never lands; its credential params do, named + fingerprinted
         status: entry.status,
@@ -286,6 +337,13 @@ function journalingFetch(config, callSiteVendor) {
         let identity = declared;
         const inner = config.fetch;
         const journaling = async function (request, server) {
+            // who made it is read here and goes no further: no twin's handler (a tunnel's, a proxy's) hands it on
+            const caller = request.headers.get(CALLER_HEADER) ?? undefined;
+            if (caller !== undefined) {
+                const headers = new Headers(request.headers);
+                headers.delete(CALLER_HEADER);
+                request = new Request(request, { headers });
+            }
             // The World's own boot probe (serve-http.ts, WORLD_BOOT_PATH) is not the app's traffic: never journaled.
             if (!twinRequestJournalEnabled() || new URL(request.url).pathname === WORLD_BOOT_PATH)
                 return inner.call(this, request, server);
@@ -308,12 +366,15 @@ function journalingFetch(config, callSiteVendor) {
                 const resolved = identity ?? fallbackIdentity(callSiteVendor);
                 if (resolved) {
                     const url = new URL(request.url);
+                    const parent = parseTraceparent(request.headers.get('traceparent'));
                     journalTwinRequest(resolved.service, {
                         method: request.method,
                         path: url.pathname,
                         status,
                         ms: Date.now() - startedAt,
                         credentials: twinRequestCredentials(request.headers, url),
+                        ...(caller ? { caller } : {}),
+                        ...(parent ? { trace: parent.traceId, span: parent.parentId } : {}),
                     }, resolved.root);
                 }
             }

package/dist/src/trace-context.d.ts

@@ -16,6 +16,9 @@ export declare function runWithTraceparent<T>(traceparent: string | undefined, f
 export declare function currentTraceparent(): string | undefined;
 /** Run `fn` inside the trace context `request` carries (its `traceparent` header), if any. */
 export declare function runWithRequestTrace<T>(request: Request, fn: () => T): T;
+/** A new trace's `traceparent` (version 00, a fresh trace-id and parent-id, sampled): for a request that carried none,
+ *  so what it causes can be told apart and joined to it. */
+export declare function newTraceparent(): string;
 /**
  * The `traceparent` an outbound delivery carries: a CHILD of its cause — the same trace-id and
  * flags, a new parent-id — so the receiving handler continues the cause's trace. The cause is the

package/dist/src/trace-context.js

@@ -51,6 +51,17 @@ export function currentTraceparent() {
 export function runWithRequestTrace(request, fn) {
     return runWithTraceparent(request.headers.get(TRACEPARENT_HEADER) ?? undefined, fn);
 }
+/** A new trace's `traceparent` (version 00, a fresh trace-id and parent-id, sampled): for a request that carried none,
+ *  so what it causes can be told apart and joined to it. */
+export function newTraceparent() {
+    const bytes = new Uint8Array(16);
+    let trace = '';
+    do {
+        globalThis.crypto.getRandomValues(bytes);
+        trace = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    } while (/^0+$/.test(trace));
+    return `00-${trace}-${newSpanId()}-01`;
+}
 function newSpanId() {
     const bytes = new Uint8Array(8);
     for (;;) {

package/inject.cjs

@@ -728,8 +728,9 @@ function socketTargetHosts(args, isTls) {
     return hosts;
   }
   if (typeof first === 'string' && !/^\d+$/.test(first)) return hosts; // a unix socket path
-  hosts.push(typeof second === 'string' ? second : 'localhost');
   const options = typeof second === 'object' && second !== null ? second : typeof third === 'object' && third !== null ? third : null;
+  // connect(port, host) names the host; connect(port, { host }) puts it in the options, which Node merges
+  hosts.push(typeof second === 'string' ? second : typeof options?.host === 'string' ? options.host : 'localhost');
   if (isTls && options && options.servername) hosts.push(options.servername);
   return hosts;
 }
@@ -811,7 +812,15 @@ function patchedPromisesLookup(original) {
   };
 }
 
-function socketRefusal(hostname) {
+/** The port a net/tls connect names (`connect(port, host)`, `connect({ port, host })`), or undefined. */
+function socketTargetPort(args) {
+  const [first] = args;
+  const raw = first !== null && typeof first === 'object' ? first.port : first;
+  const port = Number(raw);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : undefined;
+}
+
+function socketRefusal(hostname, port, isTls) {
   const host = String(hostname || '').toLowerCase();
   if (host === WORLD_ADDRESS[4] || host === WORLD_ADDRESS[6]) {
     return `[twin-inject] refused a socket to ${host}, the address this World's DNS gives the names it routes: `
@@ -831,8 +840,11 @@ function socketRefusal(hostname) {
     return `[twin-inject] refused a raw socket to ${host}, which this world routes to the application (volter-world app-url --host): `
       + 'the client opened its own connection instead of going through http/https or fetch, so it could not be routed.';
   }
-  const url = (() => { try { return new URL(`https://${isIP(host) === 6 ? `[${host}]` : host}/`); } catch { return null; } })();
-  if (url && shouldBlockUntwinned(url)) return `[twin-inject] blocked untwinned external socket to ${host}`;
+  // the destination as an origin, its port and its protocol included: a policy that lists https://host allows TLS to
+  // host:443, never another port or a plaintext connection to it
+  const authority = `${isIP(host) === 6 ? `[${host}]` : host}${port !== undefined && !(isTls && port === 443) ? `:${port}` : ''}`;
+  const url = (() => { try { return new URL(`${isTls ? 'https' : 'http'}://${authority}/`); } catch { return null; } })();
+  if (url && shouldBlockUntwinned(url)) return `[twin-inject] blocked untwinned external socket to ${authority}`;
   return null;
 }
 
@@ -844,8 +856,9 @@ function refusedSocket(message) {
 
 function patchedConnect(originalConnect, isTls) {
   return function patchedSocketConnect(...args) {
+    const port = socketTargetPort(args);
     for (const host of socketTargetHosts(args, isTls)) {
-      const refusal = socketRefusal(host);
+      const refusal = socketRefusal(host, port, isTls);
       if (refusal) return refusedSocket(refusal);
     }
     return originalConnect.apply(this, args);

package/network-policy.cjs

@@ -66,9 +66,11 @@ function isWorldInternalHost(hostname) {
   const v4 = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(h);
   if (v4) {
     const a = Number(v4[1]); const b = Number(v4[2]);
-    return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    // not link-local 169.254/16: it holds a cloud's instance metadata (169.254.169.254), the box's credentials
+    return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
   }
-  return h.includes(':') && (h.startsWith('fc') || h.startsWith('fd') || h.startsWith('fe80:'));
+  // nor fe80::/10, nor a cloud's IPv6 metadata address (fd00:ec2::254)
+  return h.includes(':') && (h.startsWith('fc') || h.startsWith('fd')) && h !== 'fd00:ec2::254';
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "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",

package/src/actions.ts

@@ -21,9 +21,9 @@ import { appendDurable, eventsLockPath, ownerStoreRoots, projectionLockPath, twi
 import { landAsPlaceholder, placeholderPullActive } from './placeholder-remote.ts';
 import { aliasesFrom, dropCheckpoint, landedCopy, landedIds, parentEntries, readTree, treeStamp, type Receipt } from './log.ts';
 import { WorldServiceEventSchema } from './schemas.ts';
-import { refuseReadOnlyWrite } from './request-scope.ts';
+import { inVendorMove, refuseReadOnlyWrite } from './request-scope.ts';
 import { getActiveWorldStore } from './world-store.ts';
-import { currentTraceparent } from './trace-context.ts';
+import { currentTraceparent, traceparentForDelivery } from './trace-context.ts';
 import type { WorldServiceEvent } from './types.ts';
 import type { TwinResource } from './serve.ts';
 
@@ -135,8 +135,11 @@ function withCorrelationId(action: TwinAction): TwinAction {
   // into the handler's async context) is the correlation when the caller supplies none — the
   // join from a request on the wire to the action rows it caused, with no pack involved.
   const correlated = action.correlationId ? action : { ...action, correlationId: currentCorrelationId() ?? randomUUID() };
-  // the request's W3C trace context (trace-context.ts) is stamped the same way, from the handler's async context
-  const traceparent = correlated.traceparent === undefined ? currentTraceparent() : undefined;
+  // the request's W3C trace context (trace-context.ts) is stamped the same way, from the handler's async context. What the
+  // vendor makes on its own while a request is served (its actor is the system's, or a vendor move) is a span of its own
+  // in that trace, so it is never joined to the request's caller (served-world's timeline), who did not make it
+  const vendors = action.actor?.kind === 'system' || inVendorMove();
+  const traceparent = correlated.traceparent === undefined ? (vendors ? traceparentForDelivery() : currentTraceparent()) : undefined;
   return traceparent ? { ...correlated, traceparent } : correlated;
 }
 

package/src/index.ts

@@ -18,7 +18,7 @@ export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
 export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from './twin-fetch.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
-export { currentTraceparent, deliveryTraceHeaders, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
+export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
 export type { Traceparent } from './trace-context.ts';
 export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.ts';
 export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
@@ -161,6 +161,7 @@ export {
   applyTwinWrite,
   applyTwinWriteAtomic,
   createTwinServer,
+  CALLER_HEADER,
   journalTwinRequest,
   twinRequestJournalFailures,
   twinRequestCredentials,
@@ -168,6 +169,8 @@ export {
   resolveTwinRead,
   twinRequestJournalEnabled,
   twinRequestJournalPath,
+  readTwinRequestJournalFrom,
+  type TwinRequestJournalCursor,
   twinResources,
 } from './serve.ts';
 export type {

package/src/request-scope.ts

@@ -14,6 +14,7 @@
 // Created on first use, never at import: a browser bundle of a mirror client carries the kernel and
 // has no AsyncLocalStorage (see serve.ts identitySlot).
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { runWithTraceparent, traceparentForDelivery } from './trace-context.ts';
 
 /** The request header that marks a request read-only. Its one value is `1`. */
 export const READ_ONLY_REQUEST_HEADER = 'x-volter-read-only';
@@ -55,9 +56,16 @@ export async function runAsReadOnlyRequest<T>(fn: () => T | Promise<T>): Promise
  *  request. Outside one it changes nothing. */
 export function runAsVendorMove<T>(fn: () => T): T {
   const current = writeScope().getStore();
-  return current ? writeScope().run({ ...current, vendorMove: true }, fn) : fn();
+  // the vendor's move is its own span of the request's trace (a delivery's shape): what it writes is joined to the
+  // trace, never to the request's caller, who did not make it
+  const own = traceparentForDelivery();
+  const run = own ? () => runWithTraceparent(own, fn) : fn;
+  return current ? writeScope().run({ ...current, vendorMove: true }, run) : run();
 }
 
+/** Whether this runs as the vendor's own move (runAsVendorMove). */
+export function inVendorMove(): boolean { return writeScopeStore?.getStore()?.vendorMove === true; }
+
 /** Whether a write attempted here would be refused. */
 export function writesRefused(): boolean {
   const scope = writeScopeStore?.getStore();

package/src/serve.ts

@@ -20,6 +20,7 @@ import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, pr
 import type { ActionProjection, TwinAction, TwinActionPrecondition } from './actions.ts';
 import { observeWorldPaths, worldPaths } from './storage.ts';
 import { getActiveWorldStore } from './world-store.ts';
+import { parseTraceparent } from './trace-context.ts';
 
 // ── the request journal: the INSPECT half of the read path ─────────────────────────────────────
 // `actions.jsonl` records MUTATIONS only, so a twin's READS are invisible to `volter-world tail`
@@ -75,6 +76,11 @@ export type TwinCredentialShape = {
   empty?: true;
 };
 
+/** The header a World puts on a request it forwards to a twin: who made it (`key:<name>`, `person:<who>`, `token`,
+ *  `token:read`). The World replaces any a caller sent; the serve seam records it in the twin's request journal and
+ *  removes it before the twin's handler. A twin reached on its own port, not through a World, records what it was sent. */
+export const CALLER_HEADER = 'x-volter-caller';
+
 export type TwinRequestJournalEntry = {
   at?: string;
   method: string;
@@ -84,6 +90,14 @@ export type TwinRequestJournalEntry = {
   ms?: number;
   /** credential-looking headers/query params that arrived, named + fingerprinted, never quoted. */
   credentials?: TwinCredentialShape[];
+  /** who made it, as the World named its caller (CALLER_HEADER: `key:<name>`, `person:<who>`, `token`); absent for a
+   *  request that did not come through a World */
+  caller?: string;
+  /** the request's trace-id and parent-id (its `traceparent`). The World mints the parent-id of every request it
+   *  forwards, and the request's log entries carry it, so an entry is joined to its caller by `span`, which no caller
+   *  chooses (a trace-id is the caller's and spans requests) */
+  trace?: string;
+  span?: string;
   /** `request`: written BEFORE the request is served (an audit device's request entry, so a request whose
    *  audit cannot be written is refused); its outcome is the entry without a phase written after. */
   phase?: 'request';
@@ -130,6 +144,41 @@ export function twinRequestJournalFailures(service: string, root?: string): numb
 }
 
 
+/** Where a reader of a journal stopped: the newest closed segment it had seen and the bytes of the live file it read. */
+export type TwinRequestJournalCursor = { segment: number; offset: number };
+
+/** The journal's lines after `cursor` (all of them without one), and the cursor to read on from. A rotation closes
+ *  the live file into the next segment as it stood, so a reader that stopped in the live file goes on in that
+ *  segment at its offset, then any later segments, and the next read takes the live file from its start; a live file shorter than where
+ *  the reader stopped (read between a rotation's two writes) is read again from its start, its lines repeated rather
+ *  than lost. Only whole lines are read (a line being appended is read next time). Without a cursor, the newest
+ *  `segments` closed segments are read (all of them when omitted), then the live file. */
+export function readTwinRequestJournalFrom(service: string, root: string | undefined, cursor: TwinRequestJournalCursor | null, options: { segments?: number } = {}): { entries: TwinRequestJournalEntry[]; cursor: TwinRequestJournalCursor } {
+  const path = twinRequestJournalPath(service, root); const store = getActiveWorldStore();
+  const segments = journalSegments(path).map((file) => Number(file.slice(path.length + 1)));
+  const newest = segments[segments.length - 1] ?? 0;
+  const entries: TwinRequestJournalEntry[] = [];
+  const take = (file: string, start: number, whole: boolean): number => {
+    const text = store.readRange ? store.readRange(file, start) : ((t) => (t === null ? null : Buffer.from(t, 'utf8').subarray(start).toString('utf8')))(store.read(file));
+    if (!text) return start;
+    const end = whole ? text.length : text.lastIndexOf('\n') + 1;
+    for (const line of text.slice(0, end).split('\n')) { if (!line) continue; try { entries.push(JSON.parse(line) as TwinRequestJournalEntry); } catch { /* a torn line */ } }
+    return start + Buffer.byteLength(text.slice(0, end), 'utf8');
+  };
+  if (cursor === null) {
+    for (const n of options.segments === undefined ? segments : segments.slice(-options.segments)) take(`${path}.${n}`, 0, true);
+    return { entries, cursor: { segment: newest, offset: take(path, 0, false) } };
+  }
+  if (newest === cursor.segment) {
+    const from = (store.stat(path)?.size ?? 0) < cursor.offset ? 0 : cursor.offset;
+    return { entries, cursor: { segment: newest, offset: take(path, from, false) } };
+  }
+  for (const n of segments) if (n > cursor.segment) take(`${path}.${n}`, n === cursor.segment + 1 ? cursor.offset : 0, true);
+  // the live file is read next time, from its start: read now, it may be the one the rotation has not emptied yet,
+  // and an offset into it would land inside the new one
+  return { entries, cursor: { segment: newest, offset: 0 } };
+}
+
 /** ~1 MB per segment: tens of thousands of entries (a shape line is ~80 bytes), and a report over a
  *  recent period reads only the segments that reach into it. */
 const REQUEST_JOURNAL_MAX_BYTES = 1_000_000;
@@ -212,6 +261,9 @@ export function journalTwinRequest(service: string, entry: TwinRequestJournalEnt
   const line = JSON.stringify({
     at: entry.at ?? new Date().toISOString(),
     ...(entry.phase ? { phase: entry.phase } : {}),
+    ...(entry.caller ? { caller: entry.caller.slice(0, 120) } : {}),
+    ...(entry.trace && /^[0-9a-f]{32}$/.test(entry.trace) ? { trace: entry.trace } : {}),
+    ...(entry.span && /^[0-9a-f]{16}$/.test(entry.span) ? { span: entry.span } : {}),
     method: entry.method.toUpperCase(),
     path: entry.path.split('?')[0], // the query STRING never lands; its credential params do, named + fingerprinted
     status: entry.status,
@@ -349,6 +401,9 @@ function journalingFetch(config: Record<string | symbol, unknown> & { fetch: (..
     let identity: TwinJournalIdentity | undefined = declared;
     const inner = config.fetch as (this: unknown, request: Request, server: unknown) => unknown;
     const journaling = async function (this: unknown, request: Request, server: unknown) {
+      // who made it is read here and goes no further: no twin's handler (a tunnel's, a proxy's) hands it on
+      const caller = request.headers.get(CALLER_HEADER) ?? undefined;
+      if (caller !== undefined) { const headers = new Headers(request.headers); headers.delete(CALLER_HEADER); request = new Request(request, { headers }); }
       // The World's own boot probe (serve-http.ts, WORLD_BOOT_PATH) is not the app's traffic: never journaled.
       if (!twinRequestJournalEnabled() || new URL(request.url).pathname === WORLD_BOOT_PATH) return inner.call(this, request, server);
       const slot: { identity?: TwinJournalIdentity } = {};
@@ -366,12 +421,15 @@ function journalingFetch(config: Record<string | symbol, unknown> & { fetch: (..
         const resolved = identity ?? fallbackIdentity(callSiteVendor);
         if (resolved) {
           const url = new URL(request.url);
+          const parent = parseTraceparent(request.headers.get('traceparent'));
           journalTwinRequest(resolved.service, {
             method: request.method,
             path: url.pathname,
             status,
             ms: Date.now() - startedAt,
             credentials: twinRequestCredentials(request.headers, url),
+            ...(caller ? { caller } : {}),
+            ...(parent ? { trace: parent.traceId, span: parent.parentId } : {}),
           }, resolved.root);
         }
       }

package/src/trace-context.ts

@@ -59,6 +59,15 @@ export function runWithRequestTrace<T>(request: Request, fn: () => T): T {
   return runWithTraceparent(request.headers.get(TRACEPARENT_HEADER) ?? undefined, fn);
 }
 
+/** A new trace's `traceparent` (version 00, a fresh trace-id and parent-id, sampled): for a request that carried none,
+ *  so what it causes can be told apart and joined to it. */
+export function newTraceparent(): string {
+  const bytes = new Uint8Array(16);
+  let trace = '';
+  do { globalThis.crypto.getRandomValues(bytes); trace = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join(''); } while (/^0+$/.test(trace));
+  return `00-${trace}-${newSpanId()}-01`;
+}
+
 function newSpanId(): string {
   const bytes = new Uint8Array(8);
   for (;;) {