@volter/world-core 2.0.0 → 2.0.2

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

@@ -0,0 +1,28 @@
+/** The request header that marks a request read-only. Its one value is `1`. */
+export declare const READ_ONLY_REQUEST_HEADER = "x-volter-read-only";
+/** Whether a request carries the read-only marker. */
+export declare function isReadOnlyRequest(request: Request | {
+    headers: Headers;
+}): boolean;
+/** A write a read-only request attempted: refused before anything was written (rule D3's 405). */
+export declare class ReadOnlyRequestError extends Error {
+    readonly service: string;
+    constructor(service: string);
+}
+/** Run `fn` as a read-only request: every write it attempts outside a vendor move is refused. The
+ *  answer says whether one was — also when the handler caught the refusal and answered something
+ *  else, so a caller can answer the refusal whatever the handler made of it. */
+export declare function runAsReadOnlyRequest<T>(fn: () => T | Promise<T>): Promise<{
+    value: T;
+    refused: undefined;
+} | {
+    refused: ReadOnlyRequestError;
+}>;
+/** 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 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
+ *  read-only request's. Called by every appender before it writes anything. */
+export declare function refuseReadOnlyWrite(service: string): void;

package/dist/src/request-scope.js

@@ -0,0 +1,70 @@
+// THE READ-ONLY REQUEST (docs/contributing/architecture.md, "Viewing a World"): a request that
+// carries `x-volter-read-only: 1` is served with the twin's writes refused — whatever operation it
+// names and whatever HTTP method it came by (an RPC wire POSTs its reads). The marker only ever
+// RESTRICTS, so the twin trusts it without auth: a caller who sends it only limits itself. The
+// World's doors set it on every read-scope request and never classify operations themselves.
+//
+// Enforcement lives at the kernel's write seam: every appender (actions.ts, storage.ts appendEvent)
+// asks `refuseReadOnlyWrite` before it writes anything, so the first write a read-only request
+// attempts is refused and nothing is partially applied. The VENDOR's own moves are not the caller's
+// writes: a pack's catch-up (a renewal, a payout, a file's expiry falling due by the World clock)
+// runs under `runAsVendorMove` and still lands under a read-only request, as a real vendor renews a
+// subscription whoever is looking.
+//
+// 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';
+/** 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. */
+export function isReadOnlyRequest(request) {
+    return request.headers.get(READ_ONLY_REQUEST_HEADER)?.trim() === '1';
+}
+/** A write a read-only request attempted: refused before anything was written (rule D3's 405). */
+export class ReadOnlyRequestError extends Error {
+    service;
+    constructor(service) {
+        super(`${service}: this request is read-only (${READ_ONLY_REQUEST_HEADER}: 1); it cannot write`);
+        this.service = service;
+        this.name = 'ReadOnlyRequestError';
+    }
+}
+let writeScopeStore;
+const writeScope = () => (writeScopeStore ??= new AsyncLocalStorage());
+/** Run `fn` as a read-only request: every write it attempts outside a vendor move is refused. The
+ *  answer says whether one was — also when the handler caught the refusal and answered something
+ *  else, so a caller can answer the refusal whatever the handler made of it. */
+export async function runAsReadOnlyRequest(fn) {
+    const scope = { readOnly: true, vendorMove: false, refusals: [] };
+    try {
+        const value = await writeScope().run(scope, fn);
+        const refused = scope.refusals[0];
+        return refused ? { refused } : { value, refused: undefined };
+    }
+    catch (error) {
+        const refused = scope.refusals[0] ?? (error instanceof ReadOnlyRequestError ? error : undefined);
+        if (refused)
+            return { refused };
+        throw error;
+    }
+}
+/** 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 function runAsVendorMove(fn) {
+    const current = writeScope().getStore();
+    return current ? writeScope().run({ ...current, vendorMove: true }, fn) : fn();
+}
+/** Whether a write attempted here would be refused. */
+export function writesRefused() {
+    const scope = writeScopeStore?.getStore();
+    return scope !== undefined && scope.readOnly && !scope.vendorMove;
+}
+/** The write seam's check: throws (and records) the refusal when a write attempted here is a
+ *  read-only request's. Called by every appender before it writes anything. */
+export function refuseReadOnlyWrite(service) {
+    if (!writesRefused())
+        return;
+    const error = new ReadOnlyRequestError(service);
+    writeScopeStore.getStore().refusals.push(error);
+    throw error;
+}

package/dist/src/storage.d.ts

@@ -7,8 +7,29 @@ import type { AppendEventResult, GenericWorldState, WorldPaths, WorldReducer, Wo
  */
 export declare function stateDirName(): string;
 export declare function worldStateRoot(root?: string): string;
-export declare function observeWorldPaths(observer: (service: string, root: string | undefined) => void): void;
+/** Install the observer; the one it replaces is returned (a test puts it back). */
+export declare function observeWorldPaths(observer: ((service: string, root: string | undefined) => void) | undefined): ((service: string, root: string | undefined) => void) | undefined;
+/** Run `fn` without its worldPaths calls reaching the identity observer. */
+export declare function withoutIdentityClaim<T>(fn: () => T): T;
 export declare function worldPaths(service: string, root?: string): WorldPaths;
+/**
+ * THE WORLD'S DATA DIRECTORY, as the World runtime hands it to every service it starts. Each twin of a World runs on
+ * its own root, `<data>/<service id>` (world-runtime's startService and startColocatedServices), so one twin's
+ * `.volter/world/<service>` is not another's; `ownerStoreRoots` finds a store across them.
+ */
+export declare const WORLD_DATA_ENV = "VOLTER_WORLD_DATA";
+/**
+ * The roots that hold the store of `owner` (ANOTHER pack's, read by contract: architecture A3), for a twin on `root`:
+ *   - `[root]` when `root` itself holds that store (both packs on one root: `volter world serve`, a test, a pack serving
+ *     several services on its root, as aws does);
+ *   - else, when `root` is one of a World's service roots (a directory directly under the World's data directory), every
+ *     other service root there that holds it (usually one; two when the World runs the owning pack twice);
+ *   - else `[]`: nothing is issued yet, or the twin runs outside a World.
+ * Only a declared cross-pack read resolves through here (`projectOwnerResources`); a pack's reads of its OWN store never
+ * leave its root, so a fresh twin never reads a sibling that happens to run the same pack. Not memoized: it is a few
+ * stats per service root, and a store that appears after the first read (the owner's first write) must be found.
+ */
+export declare function ownerStoreRoots(owner: string, root?: string): string[];
 /** Read + parse a whole-file JSON sidecar, citing the path on a parse failure (mirrors
  *  readJsonl's `${path}:...` error shape). Callers own existence semantics — this parses a
  *  file that is expected to exist; guard with existsSync first when absence is allowed. */

package/dist/src/storage.js

@@ -3,6 +3,7 @@ import { assertNotBeingRemoved, withAncestryLock, withStateRemoval } from "./anc
 import { appendParentEntry, toEntry } from "./log.js";
 import { GenericWorldStateSchema, WorldServiceEventSchema, } from "./schemas.js";
 import { getActiveWorldStore } from "./world-store.js";
+import { refuseReadOnlyWrite } from "./request-scope.js";
 import { parentEntries, toEvent } from "./log.js";
 function nowIso() {
     return new Date().toISOString();
@@ -40,12 +41,29 @@ function assertServiceName(service) {
  * Nothing else may use this: it is a one-slot observability hook, never a control seam.
  */
 let worldPathsObserver;
+/** Install the observer; the one it replaces is returned (a test puts it back). */
 export function observeWorldPaths(observer) {
+    const previous = worldPathsObserver;
     worldPathsObserver = observer;
+    return previous;
+}
+/** While > 0, a read of ANOTHER pack's store is in progress (`projectOwnerResources`): that is not the request's twin
+ *  saying who it is, so it claims no journal identity. */
+let identityQuiet = 0;
+/** Run `fn` without its worldPaths calls reaching the identity observer. */
+export function withoutIdentityClaim(fn) {
+    identityQuiet++;
+    try {
+        return fn();
+    }
+    finally {
+        identityQuiet--;
+    }
 }
 export function worldPaths(service, root) {
     const safeService = assertServiceName(service);
-    worldPathsObserver?.(safeService, root);
+    if (identityQuiet === 0)
+        worldPathsObserver?.(safeService, root);
     const resolvedRoot = projectRoot(root);
     const dir = join(worldStateRoot(root), safeService);
     return {
@@ -60,6 +78,43 @@ export function worldPaths(service, root) {
         eventQueue: join(dir, 'event-queue.jsonl'),
     };
 }
+/**
+ * THE WORLD'S DATA DIRECTORY, as the World runtime hands it to every service it starts. Each twin of a World runs on
+ * its own root, `<data>/<service id>` (world-runtime's startService and startColocatedServices), so one twin's
+ * `.volter/world/<service>` is not another's; `ownerStoreRoots` finds a store across them.
+ */
+export const WORLD_DATA_ENV = 'VOLTER_WORLD_DATA';
+/** Does `root` hold `service`'s store: its log or its branch record (what a write or a fork leaves; a read leaves
+ *  neither)? The paths are built without worldPaths, so a probe claims no journal identity. */
+function holdsStore(service, root) {
+    const dir = join(worldStateRoot(root), service);
+    const store = getActiveWorldStore();
+    return ['events.jsonl', 'actions.jsonl', 'branch.json'].some((file) => store.exists(join(dir, file)));
+}
+/**
+ * The roots that hold the store of `owner` (ANOTHER pack's, read by contract: architecture A3), for a twin on `root`:
+ *   - `[root]` when `root` itself holds that store (both packs on one root: `volter world serve`, a test, a pack serving
+ *     several services on its root, as aws does);
+ *   - else, when `root` is one of a World's service roots (a directory directly under the World's data directory), every
+ *     other service root there that holds it (usually one; two when the World runs the owning pack twice);
+ *   - else `[]`: nothing is issued yet, or the twin runs outside a World.
+ * Only a declared cross-pack read resolves through here (`projectOwnerResources`); a pack's reads of its OWN store never
+ * leave its root, so a fresh twin never reads a sibling that happens to run the same pack. Not memoized: it is a few
+ * stats per service root, and a store that appears after the first read (the owner's first write) must be found.
+ */
+export function ownerStoreRoots(owner, root) {
+    const safeOwner = assertServiceName(owner);
+    const own = projectRoot(root);
+    if (holdsStore(safeOwner, own))
+        return [own];
+    const data = typeof process === 'undefined' ? undefined : process.env[WORLD_DATA_ENV];
+    if (!data || dirname(own) !== resolve(data))
+        return [];
+    return getActiveWorldStore().list(dirname(own))
+        .map((name) => join(dirname(own), name))
+        .filter((candidate) => candidate !== own && holdsStore(safeOwner, candidate))
+        .sort();
+}
 function readJsonl(path) {
     const rows = [];
     for (const [index, line] of getActiveWorldStore().readLines(path).entries()) {
@@ -172,6 +227,7 @@ export function projectionLockPath(paths) {
  */
 export function appendEvent(event, root) {
     const parsed = WorldServiceEventSchema.parse(event);
+    refuseReadOnlyWrite(parsed.service); // a read-only request writes nothing (request-scope.ts)
     const paths = worldPaths(parsed.service, root);
     ensureEventDirs(paths);
     const { appended } = appendParentEntry(toEntry(parsed), root);

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

@@ -0,0 +1,31 @@
+export declare const TRACEPARENT_HEADER = "traceparent";
+export type Traceparent = {
+    version: string;
+    traceId: string;
+    parentId: string;
+    flags: string;
+};
+/** A `traceparent` header value parsed strictly, or null: malformed, version `ff`, or an all-zero
+ *  trace-id or parent-id is no trace at all (the spec: such a header is ignored). */
+export declare function parseTraceparent(value: unknown): Traceparent | null;
+/** The value itself when it is a valid traceparent (normalized: trimmed), else undefined. */
+export declare function validTraceparent(value: unknown): string | undefined;
+/** Run `fn` with `traceparent` as the request's trace context; an invalid value runs `fn` outside any. */
+export declare function runWithTraceparent<T>(traceparent: string | undefined, fn: () => T): T;
+/** The trace context of the request being handled, when it carried a valid traceparent. */
+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;
+/**
+ * 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
+ * given traceparent, or an entry's recorded one, or (omitted) the trace context of the request
+ * being handled. No valid cause, no traceparent: a delivery never invents a trace.
+ */
+export declare function traceparentForDelivery(cause?: string | {
+    traceparent?: unknown;
+} | null): string | undefined;
+/** `traceparentForDelivery` as headers to spread into a delivery's own: `{ traceparent }` or `{}`. */
+export declare function deliveryTraceHeaders(cause?: string | {
+    traceparent?: unknown;
+} | null): Record<string, string>;

package/dist/src/trace-context.js

@@ -0,0 +1,78 @@
+// W3C TRACE CONTEXT across a World (https://www.w3.org/TR/trace-context/): one cause followed across
+// vendors by the tracing standard, never an id of our own. An app instrumented with OpenTelemetry
+// sends `traceparent` on its outgoing calls; a real vendor ignores it, so the vendor wire is
+// unchanged. The kernel serve seams (twin-fetch.ts, derived.ts) run a handler inside the request's
+// valid traceparent; every entry appended while handling it records that value (actions.ts
+// `traceparent`, authoring metadata excluded from replay identity like `correlationId`); and a
+// pack's outbound delivery the write caused (a webhook to the app) carries a CHILD of it — the
+// same trace-id, a new parent-id — so the app's handler continues the same trace.
+//
+// Nothing here is vendor knowledge, and nothing runs at import: the async-context store is made on
+// first use (a browser bundle of a mirror client carries the kernel and has no AsyncLocalStorage).
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const TRACEPARENT_HEADER = 'traceparent';
+// version-traceid-parentid-flags, lowercase hex only (the spec's HEXDIGLC). Version ff is invalid;
+// a future version is read by its version-00 prefix only when nothing else follows, which keeps the
+// accepted form exactly the one this module emits.
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const ZERO_TRACE = '0'.repeat(32);
+const ZERO_SPAN = '0'.repeat(16);
+/** A `traceparent` header value parsed strictly, or null: malformed, version `ff`, or an all-zero
+ *  trace-id or parent-id is no trace at all (the spec: such a header is ignored). */
+export function parseTraceparent(value) {
+    if (typeof value !== 'string')
+        return null;
+    const m = TRACEPARENT.exec(value.trim());
+    if (!m)
+        return null;
+    const [, version, traceId, parentId, flags] = m;
+    if (version === 'ff' || traceId === ZERO_TRACE || parentId === ZERO_SPAN)
+        return null;
+    return { version, traceId, parentId, flags };
+}
+/** The value itself when it is a valid traceparent (normalized: trimmed), else undefined. */
+export function validTraceparent(value) {
+    const parsed = parseTraceparent(value);
+    return parsed ? `${parsed.version}-${parsed.traceId}-${parsed.parentId}-${parsed.flags}` : undefined;
+}
+// created on first use, never at import (see the header)
+let traceStore;
+const traceScope = () => (traceStore ??= new AsyncLocalStorage());
+/** Run `fn` with `traceparent` as the request's trace context; an invalid value runs `fn` outside any. */
+export function runWithTraceparent(traceparent, fn) {
+    const valid = validTraceparent(traceparent);
+    return valid ? traceScope().run(valid, fn) : fn();
+}
+/** The trace context of the request being handled, when it carried a valid traceparent. */
+export function currentTraceparent() {
+    return traceStore?.getStore();
+}
+/** Run `fn` inside the trace context `request` carries (its `traceparent` header), if any. */
+export function runWithRequestTrace(request, fn) {
+    return runWithTraceparent(request.headers.get(TRACEPARENT_HEADER) ?? undefined, fn);
+}
+function newSpanId() {
+    const bytes = new Uint8Array(8);
+    for (;;) {
+        globalThis.crypto.getRandomValues(bytes);
+        const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+        if (hex !== ZERO_SPAN)
+            return hex;
+    }
+}
+/**
+ * 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
+ * given traceparent, or an entry's recorded one, or (omitted) the trace context of the request
+ * being handled. No valid cause, no traceparent: a delivery never invents a trace.
+ */
+export function traceparentForDelivery(cause) {
+    const source = cause === undefined ? currentTraceparent() : typeof cause === 'string' ? cause : cause?.traceparent;
+    const parent = parseTraceparent(source);
+    return parent ? `00-${parent.traceId}-${newSpanId()}-${parent.flags}` : undefined;
+}
+/** `traceparentForDelivery` as headers to spread into a delivery's own: `{ traceparent }` or `{}`. */
+export function deliveryTraceHeaders(cause) {
+    const traceparent = traceparentForDelivery(cause);
+    return traceparent ? { [TRACEPARENT_HEADER]: traceparent } : {};
+}

package/dist/src/twin-fetch.d.ts

@@ -1,3 +1,4 @@
+import { type ReadOnlyRequestError } from './request-scope.js';
 /** The header a host sets when it mounts a twin under a path (a served World's wire:
  *  `/<org>/<world>/<vendor>`), the reverse-proxy convention; with it the host sets
  *  `x-forwarded-host` and `x-forwarded-proto` to where the World is reached. */
@@ -21,6 +22,21 @@ export type TwinStreamConnection = {
     close(): void;
 };
 export type TwinStream = (sink: TwinStreamSink, peer: string) => TwinStreamConnection;
+/** The request scopes a pack wrapped in `withRequestScopes` enforces, advertised on its `GET /twin` as
+ *  `requestScopes`: `read` — a request carrying `x-volter-read-only: 1` (request-scope.ts) has every
+ *  write it attempts refused at the kernel's write seam, whatever operation it names. A World's doors
+ *  forward a read-scope request that is not a GET only to a twin that advertises it. */
+export declare const TWIN_REQUEST_SCOPES: readonly string[];
+/**
+ * THE READ SCOPE for a pack that writes its own fetch (the derived packs, the byte-wire packs): a
+ * request carrying the read-only marker runs with the kernel's write seam refusing its writes, and a
+ * refused write answers `refuse` (the vendor's own read-only error; a generic 405 without one) —
+ * whatever the handler made of the refusal. `GET /twin` advertises `requestScopes`. Everything else
+ * passes through untouched; the wrapped fetch keeps its own properties (a derived fetch's `owners`).
+ */
+export declare function withRequestScopes<F extends (request: Request) => Promise<Response>>(fetch: F, opts?: {
+    refuse?: (request: Request, error: ReadOnlyRequestError) => Response | Promise<Response>;
+}): F;
 export type TwinFetchHandlerResult = {
     status: number;
     body: unknown;

package/dist/src/twin-fetch.js

@@ -10,6 +10,8 @@
 // Workerd-clean by construction: no Bun APIs, no fs, no clock but worldNow() — the same
 // closure serves under Bun.serve locally and mounted in-process on Cloudflare.
 import { runWithCorrelationId } from "./actions.js";
+import { runWithRequestTrace } from "./trace-context.js";
+import { isReadOnlyRequest, runAsReadOnlyRequest } from "./request-scope.js";
 import { worldNow } from "./world-clock.js";
 /** The header a host sets when it mounts a twin under a path (a served World's wire:
  *  `/<org>/<world>/<vendor>`), the reverse-proxy convention; with it the host sets
@@ -29,6 +31,50 @@ export function twinPublicBase(request) {
     const origin = host && /^[A-Za-z0-9.-]+(:\d+)?$/.test(host) && (proto === 'http' || proto === 'https') ? `${proto}://${host}` : new URL(request.url).origin;
     return `${origin}${prefix.replace(/\/+$/, '')}`;
 }
+/** The request scopes a pack wrapped in `withRequestScopes` enforces, advertised on its `GET /twin` as
+ *  `requestScopes`: `read` — a request carrying `x-volter-read-only: 1` (request-scope.ts) has every
+ *  write it attempts refused at the kernel's write seam, whatever operation it names. A World's doors
+ *  forward a read-scope request that is not a GET only to a twin that advertises it. */
+export const TWIN_REQUEST_SCOPES = ['read'];
+/** `GET /twin`'s body with the request scopes this seam enforces. */
+function advertised(manifest) {
+    return manifest !== null && typeof manifest === 'object' && !Array.isArray(manifest) ? { ...manifest, requestScopes: [...TWIN_REQUEST_SCOPES] } : manifest;
+}
+/** The answer to a read-only request's write when the twin names no vendor-shaped one (rule D3). */
+function readOnlyRefusal(error) {
+    return Response.json({ error: 'read_only', message: error.message }, { status: 405 });
+}
+/**
+ * THE READ SCOPE for a pack that writes its own fetch (the derived packs, the byte-wire packs): a
+ * request carrying the read-only marker runs with the kernel's write seam refusing its writes, and a
+ * refused write answers `refuse` (the vendor's own read-only error; a generic 405 without one) —
+ * whatever the handler made of the refusal. `GET /twin` advertises `requestScopes`. Everything else
+ * passes through untouched; the wrapped fetch keeps its own properties (a derived fetch's `owners`).
+ */
+export function withRequestScopes(fetch, opts = {}) {
+    const scoped = async (request) => {
+        const url = new URL(request.url);
+        if (request.method === 'GET' && (url.pathname.replace(/\/+$/, '') || '/') === '/twin') {
+            const answer = await fetch(request);
+            if (!answer.ok || !(answer.headers.get('content-type') ?? '').includes('json'))
+                return answer;
+            const headers = new Headers(answer.headers);
+            headers.delete('content-length');
+            return new Response(JSON.stringify(advertised(await answer.json())), { status: answer.status, headers });
+        }
+        // the request's W3C traceparent follows every entry the fetch writes, as through the kernel's own adapters
+        // (a custom fetch never entered it, so the timeline's trace filter missed its entries)
+        return runWithRequestTrace(request, async () => {
+            if (!isReadOnlyRequest(request))
+                return fetch(request);
+            const out = await runAsReadOnlyRequest(() => fetch(request));
+            if (!out.refused)
+                return out.value;
+            return opts.refuse ? await opts.refuse(request, out.refused) : readOnlyRefusal(out.refused);
+        });
+    };
+    return Object.assign(scoped, fetch);
+}
 export function createTwinFetchFromHandler(handler, config) {
     const readOnly = config.readOnly ?? false;
     return async function twinFetch(request) {
@@ -63,18 +109,23 @@ export function createTwinFetchFromHandler(handler, config) {
         // world instant. A client-settable occurredAt would be a direct R9 hole.
         // D3 — the wire's request id becomes the correlation of every action this handler appends.
         const requestId = request.headers.get('x-twins-request-id') ?? undefined;
-        const invoke = () => handler({
+        const invoke = (asReadOnly = readOnly) => handler({
             ...config.handlerOptions,
             ...config.extras?.(request, url),
             method: request.method,
             path: url.pathname + (url.search || ''),
             body,
             headers,
-            readOnly,
+            readOnly: asReadOnly,
             occurredAt: worldNow(),
             ...(config.root !== undefined ? { root: config.root } : {}),
         });
-        const result = await (requestId ? runWithCorrelationId(requestId, invoke) : invoke());
+        // a read-only request is, to the handler, a request to a read-only twin: the pack refuses its
+        // writes in the vendor's own shape (D3), and the kernel's write seam refuses any it misses
+        const scoped = readOnly || isReadOnlyRequest(request);
+        const run = (asReadOnly = scoped) => (requestId ? runWithCorrelationId(requestId, () => invoke(asReadOnly)) : invoke(asReadOnly));
+        // W3C trace context: a valid incoming traceparent scopes the handler, so its entries record it
+        const result = await runWithRequestTrace(request, () => (isReadOnlyRequest(request) ? readScoped(run) : run()));
         // A null/undefined body is an EMPTY reply (`JSON.stringify(null)` would serve the
         // four bytes "null") — and so is the estate's own 204 idiom, `body: ''` with a
         // null-body status: workerd THROWS on any body with 204/205/304 (review B2), where
@@ -89,3 +140,15 @@ export function createTwinFetchFromHandler(handler, config) {
         });
     };
 }
+/** A read-only request through the handler seam: the handler runs once, with its writes refused at
+ *  the kernel's write seam; a write it attempted answers 405 (rule D3). The handler is never asked
+ *  twice (a second run would repeat whatever it did before its first write: a rate-limit slot, a
+ *  vendor call). The seam enforces the marker for whoever sends it, but does not advertise
+ *  `requestScopes`: a pack opts in to being handed a World's read-token requests by wrapping its
+ *  fetch in `withRequestScopes`, once it has made sure nothing it does on a read escapes the seam. */
+async function readScoped(run) {
+    const out = await runAsReadOnlyRequest(() => run());
+    if (!out.refused)
+        return out.value;
+    return { status: 405, body: { error: 'read_only', message: out.refused.message } };
+}

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

@@ -1,4 +1,4 @@
 export declare const WORLD_CLOCK_ENV = "TWIN_WORLD_CLOCK_FILE";
-/** The world's "now": the frozen instant in the clock file when one is configured and
- *  parseable; real wall-clock time otherwise. */
+/** The world's "now": the clock file's time when one is configured (its frozen instant, or a running clock's time
+ *  now); real wall-clock time otherwise. */
 export declare function worldNow(): string;

package/dist/src/world-clock.js

@@ -6,27 +6,28 @@
 // is the operator door (set / advance / show). No file, or no env → real wall-clock time,
 // exactly the pre-clock behavior; a world only has scripted time when its operator says so.
 //
-// File format: a single ISO-8601 line (a FROZEN instant). Every read returns exactly that
-// instant — deterministic by construction. Advancing time is an explicit operator act, never
-// a background drift.
-// Read through the ACTIVE WorldStore, not node:fs: the clock file is world state, and a
-// hydrated serverless namespace must carry its frozen instant with it (runtime contract R11–R14
-// — a MemoryWorldStore world that read the clock off the host filesystem would silently
-// serve the HOST's time, the exact two-services-disagreeing-about-now defect below).
+// File format (world-clock.cjs, the one home of it, shared with the injector that gives an application process the
+// same time): a FROZEN instant, one ISO-8601 line, every read returning exactly that instant; or a RUNNING clock,
+// `<instant> from <wall instant>`, the World's time at a moment of the machine's, running on at the machine's pace (a
+// World serving an application). Moving time is an explicit operator act either way, never a background drift.
 import { getActiveWorldStore } from "./world-store.js";
+import clockForm from '../world-clock.cjs';
 export const WORLD_CLOCK_ENV = 'TWIN_WORLD_CLOCK_FILE';
-/** The world's "now": the frozen instant in the clock file when one is configured and
- *  parseable; real wall-clock time otherwise. */
+/** The machine's own time: the real Date.now even where the injector gives the process the World's time (inject.cjs
+ *  leaves the original under this symbol), so a running clock's offset is applied once. */
+const machineNow = () => {
+    const real = globalThis[Symbol.for('volter.machineDateNow')];
+    return typeof real === 'function' ? real() : Date.now();
+};
+/** The world's "now": the clock file's time when one is configured (its frozen instant, or a running clock's time
+ *  now); real wall-clock time otherwise. */
 export function worldNow() {
     const file = process.env[WORLD_CLOCK_ENV];
     if (file && getActiveWorldStore().exists(file)) {
-        const raw = (getActiveWorldStore().read(file) ?? '').trim();
-        const parsed = Date.parse(raw);
-        if (!Number.isNaN(parsed))
-            return new Date(parsed).toISOString();
-        // A configured-but-corrupt clock is a WORLD defect — fail loudly, never silently drift
-        // back to wall-clock (two services disagreeing about now breaks the world).
-        throw new Error(`world clock: ${file} does not contain a parseable ISO-8601 instant (got ${JSON.stringify(raw.slice(0, 40))})`);
+        // A configured-but-corrupt clock is a WORLD defect — parseClock fails loudly, never silently drifting back to
+        // wall-clock (two services disagreeing about now breaks the world).
+        const clock = clockForm.parseClock(getActiveWorldStore().read(file) ?? '');
+        return new Date(clockForm.clockNowMs(clock, machineNow())).toISOString();
     }
-    return new Date().toISOString();
+    return new Date(machineNow()).toISOString();
 }

package/dist/src/world-store.js

@@ -25,6 +25,7 @@
 // `node:fs`. See its module header.
 import { appendFileSync, chmodSync, closeSync, existsSync, fsyncSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { hostname } from 'node:os';
+import { refuseReadOnlyWrite } from "./request-scope.js";
 import { basename, dirname, join, resolve } from 'node:path';
 // ── FsWorldStore — the DEFAULT, byte-identical to the historical node:fs behavior ────
 let fsAtomicSequence = 0;
@@ -122,6 +123,7 @@ export class FsWorldStore {
         }
     }
     append(path, data) {
+        refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         // Historical appendDurable: a completed append syscall survives a process crash;
         // fsync additionally survives kernel-panic/power-loss when VOLTER_DURABLE=1.
         const fd = openSync(path, 'a');
@@ -135,6 +137,7 @@ export class FsWorldStore {
         }
     }
     write(path, data, options = {}) {
+        refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         if (!options.secret) {
             mkdirSync(dirname(path), { recursive: true });
             writeFileSync(path, data);
@@ -145,6 +148,7 @@ export class FsWorldStore {
         chmodSync(path, 0o600);
     }
     writeAtomic(path, data, options = {}) {
+        refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         mkdirSync(dirname(path), { recursive: true });
         const tmp = `${path}.${process.pid}.${Date.now()}.${fsAtomicSequence++}.tmp`;
         try {
@@ -161,6 +165,7 @@ export class FsWorldStore {
         return existsSync(path);
     }
     remove(path) {
+        refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         rmSync(path, { recursive: true, force: true });
     }
     mkdir(dirPath) {
@@ -339,16 +344,19 @@ export class MemoryWorldStore {
         return content === undefined ? [] : content.split('\n');
     }
     append(path, data) {
+        refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         this.files.set(path, (this.files.get(path) ?? '') + data);
         this.sizes.set(path, (this.sizes.get(path) ?? 0) + byteLength(data));
         this.bump(path);
     }
     write(path, data) {
+        refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         this.files.set(path, data);
         this.sizes.set(path, byteLength(data));
         this.bump(path);
     }
     writeAtomic(path, data) {
+        refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         // Atomic by nature in a single process: the assignment is indivisible, so no reader
         // ever observes a partial document.
         this.files.set(path, data);
@@ -366,6 +374,7 @@ export class MemoryWorldStore {
         return false;
     }
     remove(path) {
+        refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
         let removedAny = false;
         if (this.files.delete(path)) {
             this.versions.delete(path);

package/dist/vendor-hosts.cjs

@@ -22,7 +22,7 @@
 //
 // THE SHARED-HOST RULE (Cal.com incident, 2026-08): a shared-host predicate must claim ONLY the
 // paths its twin actually serves — never "the rest of the host". Claiming the remainder is how
-// every `@googleapis/calendar` call (37 methods, all defaulting to www.googleapis.com) was routed
+// every `@googleapis/calendar` call (all of its methods default to www.googleapis.com) was routed
 // into the googleauth/gemini twin and answered with a plausible Google-shaped 404: a mis-route
 // that fails OPEN and PLAUSIBLE, strictly worse than a coverage gap. An UNCLAIMED path on a
 // claimed host is refused LOUDLY instead (see unclaimedTwinnedHostPathMessage below): the error
@@ -32,7 +32,7 @@
  * Exactly the routes gemini-twin.ts §googleauth models: `POST /token` (the oauth2.googleapis.com
  * path, also answered on the legacy host) and `POST /oauth2/v4/token` (the legacy
  * www.googleapis.com token path older google-auth-library versions default to). NOTHING else:
- * /calendar/v3/*, /drive/v3/*, … are other Google products with no twin in this repo, and
+ * /calendar/v3/* (the googlecalendar pack's), /drive/v3/*, … are other Google products, and
  * claiming them would mis-route those SDKs into an auth twin that answers with vendor-shaped
  * 404s (the Cal.com incident).
  */