@volter/world-core 2.0.1 → 2.0.3

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-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

@@ -77,13 +77,14 @@ const isGoogleOAuthTokenPath = (p) =>
 // operation must fail LOCALLY, not succeed remotely.
 
 /**
- * The www.googleapis.com paths it serves: the v1 (PEM) and v3 (JWK) cert endpoints, and the v3
- * userinfo alias. NOT `/oauth2/v2/*` — Google publishes no v2 certs endpoint at all, and the v2
- * userinfo alias returns a DIFFERENT field set the pack does not model
- * (`googleoauth.endpoints.userinfo_v2`, todo), so its handler refuses it.
+ * The www.googleapis.com paths it serves: the v1 (PEM) and v3 (JWK) cert endpoints, the v3
+ * userinfo alias, and the OAuth2 API v2's userinfo (`/oauth2/v2/userinfo` and its `/userinfo/v2/me`
+ * alias, a different field set: `googleoauth.endpoints.userinfo_v2`), which `@googleapis/oauth2`
+ * calls (Cal.com's Google Calendar callback). NOT `/oauth2/v2/certs`: Google publishes no v2 certs
+ * endpoint at all.
  */
 const isGoogleOAuthApisPath = (p) =>
-  typeof p === 'string' && /^\/oauth2\/(v1\/certs|v3\/(certs|userinfo))\/?$/.test(p);
+  typeof p === 'string' && /^\/(oauth2\/(v1\/certs|v3\/(certs|userinfo)|v2\/userinfo)|userinfo\/v2\/me)\/?$/.test(p);
 
 // vendor → predicate(hostname, pathname?). A vendor is only active if its twin URL is set.
 // THE HAND TABLE'S ONLY RESIDENTS: keys served by KERNEL packages (browser-assets serves

package/generated/pack-facts.json

@@ -506,6 +506,10 @@
         {
           "host": "cdn.bsky.app",
           "pathPattern": "^/img/"
+        },
+        {
+          "host": "bsky.app",
+          "pathPattern": "^/profile/[^/]+/?$|^/profile/[^/]+/post/[A-Za-z0-9._:~-]{1,512}/?$"
         }
       ],
       "archetype": "crud",
@@ -4274,6 +4278,38 @@
         {
           "host": "api.twitter.com",
           "pathPattern": "^(?:/2/media/upload/?|/2/media/upload/initialize/?|/2/media/upload/[0-9]+/(?:append|finalize)/?|/2/tweets/?|/2/tweets/[^/]+/?|/2/tweets/search/recent/?|/2/users/(?!me/?$)[^/]+/?|/2/users/by/username/[^/]+/?|/2/users/[^/]+/mentions/?|/2/users/[^/]+/tweets/?|/2/users/[^/]+/timelines/reverse_chronological/?)$|^/_twin/(?!assets/consent\\.(?:js|css)$)"
+        },
+        {
+          "host": "x.com",
+          "pathPattern": "^/(?!_twin/)[A-Za-z0-9_]{1,15}/status/[0-9]{1,19}/?$|^/(?!(?:i|en|home|explore|notifications|messages|settings|search|compose|login|logout|signup|tos|privacy|about|account|intent|share|hashtag|lists|bookmarks|jobs|download|grok|premium|communities|creators|twin|_twin)/?$)[A-Za-z0-9_]{1,15}/?$"
+        },
+        {
+          "host": "twitter.com",
+          "pathPattern": "^/(?!_twin/)[A-Za-z0-9_]{1,15}/status/[0-9]{1,19}/?$|^/(?!(?:i|en|home|explore|notifications|messages|settings|search|compose|login|logout|signup|tos|privacy|about|account|intent|share|hashtag|lists|bookmarks|jobs|download|grok|premium|communities|creators|twin|_twin)/?$)[A-Za-z0-9_]{1,15}/?$"
+        },
+        {
+          "host": "www.x.com",
+          "pathPattern": "^/(?!_twin/)[A-Za-z0-9_]{1,15}/status/[0-9]{1,19}/?$|^/(?!(?:i|en|home|explore|notifications|messages|settings|search|compose|login|logout|signup|tos|privacy|about|account|intent|share|hashtag|lists|bookmarks|jobs|download|grok|premium|communities|creators|twin|_twin)/?$)[A-Za-z0-9_]{1,15}/?$"
+        },
+        {
+          "host": "www.twitter.com",
+          "pathPattern": "^/(?!_twin/)[A-Za-z0-9_]{1,15}/status/[0-9]{1,19}/?$|^/(?!(?:i|en|home|explore|notifications|messages|settings|search|compose|login|logout|signup|tos|privacy|about|account|intent|share|hashtag|lists|bookmarks|jobs|download|grok|premium|communities|creators|twin|_twin)/?$)[A-Za-z0-9_]{1,15}/?$"
+        },
+        {
+          "host": "mobile.twitter.com",
+          "pathPattern": "^/(?!_twin/)[A-Za-z0-9_]{1,15}/status/[0-9]{1,19}/?$|^/(?!(?:i|en|home|explore|notifications|messages|settings|search|compose|login|logout|signup|tos|privacy|about|account|intent|share|hashtag|lists|bookmarks|jobs|download|grok|premium|communities|creators|twin|_twin)/?$)[A-Za-z0-9_]{1,15}/?$"
+        },
+        {
+          "host": "mobile.x.com",
+          "pathPattern": "^/(?!_twin/)[A-Za-z0-9_]{1,15}/status/[0-9]{1,19}/?$|^/(?!(?:i|en|home|explore|notifications|messages|settings|search|compose|login|logout|signup|tos|privacy|about|account|intent|share|hashtag|lists|bookmarks|jobs|download|grok|premium|communities|creators|twin|_twin)/?$)[A-Za-z0-9_]{1,15}/?$"
+        },
+        {
+          "host": "pbs.twimg.com",
+          "pathPattern": "^/media/[0-9a-f]{64}\\.(?:jpg|png|gif|webp)$|^/ext_tw_video_thumb/[0-9]{1,19}/pu/img/[0-9a-f]{64}\\.svg$"
+        },
+        {
+          "host": "video.twimg.com",
+          "pathPattern": "^/ext_tw_video/[0-9]{1,19}/pu/vid/avc1/[0-9]+x[0-9]+/[0-9a-f]{64}\\.mp4$"
         }
       ],
       "archetype": "crud",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "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,7 +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 { getActiveWorldStore } from './world-store.ts';
+import { currentTraceparent } from './trace-context.ts';
 import type { WorldServiceEvent } from './types.ts';
 import type { TwinResource } from './serve.ts';
 
@@ -94,6 +96,9 @@ export type TwinAction = {
    * alone, with no dependence on actionId/pushId naming conventions.
    */
   correlationId?: string;
+  /** The W3C `traceparent` of the request that caused this action, when it carried a valid one
+   *  (trace-context.ts). Authoring metadata like correlationId: excluded from replay identity. */
+  traceparent?: string;
   /**
    * The action's MERGE BASE against the remote (runtime contract R14, non-fast-forward
    * rule): per touched subject, the observed mirror's remote ref (shadow.ts remoteRefs)
@@ -129,7 +134,10 @@ function withCorrelationId(action: TwinAction): TwinAction {
   // The wire's request id (the addressed service stamps every response with one and threads it
   // 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.
-  return action.correlationId ? action : { ...action, correlationId: currentCorrelationId() ?? randomUUID() };
+  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;
+  return traceparent ? { ...correlated, traceparent } : correlated;
 }
 
 /** Subjects a `set` action touches: its own subject, every projection resource, and every
@@ -200,7 +208,7 @@ function landIfPlaceholderPull(action: TwinAction, root?: string): TwinAction |
 }
 
 function replayBody(action: TwinAction): string {
-  const { correlationId: _correlationId, ...stampedBody } = action;
+  const { correlationId: _correlationId, traceparent: _traceparent, ...stampedBody } = action;
   // A confirmation is content-addressed by the observed event ids. Its timestamp is observation
   // metadata, just like the occurredAt/observedAt values that appendEvent ignores when replaying
   // one content-addressed event. Two reconcilers confirming the same bytes at different wall-clock
@@ -233,6 +241,7 @@ export function runWithCorrelationId<T>(id: string, fn: () => T): T { return cor
 export function currentCorrelationId(): string | undefined { return correlationScope().getStore(); }
 
 export function appendAction(action: TwinAction, root?: string): TwinAction {
+  refuseReadOnlyWrite(action.service); // a read-only request writes nothing (request-scope.ts)
   // Evaluate and append under the service projection and actions locks. A precondition is a
   // compare-and-set, not an advisory validation: checking outside either lock would let another
   // writer invalidate it before this action lands. The shadow basis is stamped under the same
@@ -252,6 +261,7 @@ export function appendAction(action: TwinAction, root?: string): TwinAction {
  *  atomic across processes (two concurrent identical writes converge to ONE action; distinct
  *  writes both land). A reused id with different content fails loudly. */
 export function appendActionIfAbsent(action: TwinAction, root?: string): { action: TwinAction; appended: boolean; placeholder?: true } {
+  refuseReadOnlyWrite(action.service);
   return withFileLock(projectionLock(action.service, root), () => withFileLock(actionsLock(action.service, root), () => {
     const identified = withCorrelationId(action);
     // An exact retry is already committed. Resolve it before re-evaluating author-time
@@ -285,6 +295,7 @@ export function appendActionIfAbsent(action: TwinAction, root?: string): { actio
  * the same ordinals, which is what serve-path determinism requires.
  */
 export function appendActionOccurrence(base: TwinAction, root?: string): { action: TwinAction; appended: boolean; placeholder?: true } {
+  refuseReadOnlyWrite(base.service);
   return withFileLock(projectionLock(base.service, root), () => withFileLock(actionsLock(base.service, root), () => {
     const stamped = occurrenceOf(base, actionIds(base.service, root), root);
     assertPreconditions(stamped, root);
@@ -345,6 +356,7 @@ export function decideAndAppendAction<T>(
     const resources = projectResources(service, root);
     const decision = decide(resources);
     if (decision.kind === 'skip') return { value: decision.value, appended: false };
+    refuseReadOnlyWrite(service); // a decision to write is the write a read-only request may not make
     if (decision.action.service !== service) {
       throw new Error(`Atomic action service mismatch: expected ${service}, got ${decision.action.service}`);
     }
@@ -525,6 +537,7 @@ export function confirmAction(opts: {
   occurredAt: string;
   root?: string;
 }): { observedEventId: string; observedEventIds: string[] } {
+  refuseReadOnlyWrite(opts.service);
   // LANDING (log.ts): the entry is copied to the parent log with its receipt — no confirm row, no
   // suppression; the fold skips a branch entry the parent holds.
   const paths = worldPaths(opts.service, opts.root);
@@ -561,6 +574,7 @@ export type RevertOutcome =
  * Only `set` rows are revertable — reverting a revert or a confirm is a category error.
  */
 export function revertAction(opts: { service: string; actionId: string; occurredAt: string; root?: string }): RevertOutcome {
+  refuseReadOnlyWrite(opts.service);
   return withFileLock(projectionLock(opts.service, opts.root), () => withFileLock(actionsLock(opts.service, opts.root), (): RevertOutcome => {
     const all = listActions(opts.service, opts.root);
     const target = all.find((a) => a.id === opts.actionId);

package/src/blob-store.ts

@@ -23,6 +23,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync,
 import { dirname, join } from 'node:path';
 import { volterHome } from './volter-home.ts';
 import { sharedBlobIndex } from './shared-blob-index.ts';
+import { refuseReadOnlyWrite, writesRefused } from './request-scope.ts';
 
 export interface BlobStore {
   /** Bytes at `key`, or null when absent. Never throws for a missing key. */
@@ -165,8 +166,21 @@ export function blobDigest(bytes: Uint8Array): string {
 // (or a test) swaps in its adapter for the scope of a request.
 let activeBlobStore: BlobStore = new FsBlobStore();
 
+/** The active store; under a read-only request's refusing scope (request-scope.ts), one that refuses
+ *  to store or remove bytes before any reach it, as the log's appenders refuse (a git push's objects,
+ *  an upload's body), while reads pass. */
 export function getActiveBlobStore(): BlobStore {
-  return activeBlobStore;
+  return writesRefused() ? readOnlyBlobs(activeBlobStore) : activeBlobStore;
+}
+function readOnlyBlobs(store: BlobStore): BlobStore {
+  return {
+    get: (key) => store.get(key),
+    exists: (key) => store.exists(key),
+    list: (prefix) => store.list(prefix),
+    size: (key) => store.size(key),
+    put: async () => { refuseReadOnlyWrite('blobs'); },
+    remove: async () => { refuseReadOnlyWrite('blobs'); },
+  };
 }
 
 export function setActiveBlobStore(store: BlobStore): BlobStore {

package/src/client-bundle.ts

@@ -5,9 +5,22 @@
 // is retried on the next call. Nothing here runs at module scope.
 import { existsSync, readFileSync } from 'node:fs';
 
+/** A file URL's path on this machine, without `node:url` (the modules that call it ride into browser
+ *  bundles): percent-escapes decoded, and without the slash `URL.pathname` puts before a Windows drive
+ *  (`/C:/…`), which no file API opens. `new URL('../client/x.css', import.meta.url).pathname` is this. */
+export function filePathOf(url: URL): string {
+  const path = decodeURIComponent(url.pathname);
+  return /^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path;
+}
+
 const bundles = new Map<string, Promise<string>>();
 type BunBuild = { build: (o: { entrypoints: string[]; target: 'browser'; minify: boolean }) => Promise<{ success: boolean; logs: Array<{ message: string }>; outputs: Array<{ text: () => Promise<string> }> }> };
 
+/** A browser has no `process`. A client that imports shared helpers from its pack's server-side module can pull Node
+ *  code into its bundle (util.deprecate, crypto shims) that reads it; without a shim the page throws before it renders
+ *  (newer Bun no longer adds one to a browser build). A minimal one, the page's own, before the bundle. */
+const PROCESS_SHIM = 'globalThis.process=globalThis.process||{env:{NODE_ENV:"production"},browser:true,argv:[],versions:{},platform:"browser",emit:function(){return false},on:function(){},nextTick:function(f){var a=[].slice.call(arguments,1);queueMicrotask(function(){f.apply(null,a)})}};\n';
+
 export function bundleClient(entry: string): Promise<string> {
   let pending = bundles.get(entry);
   if (!pending) {
@@ -15,12 +28,12 @@ export function bundleClient(entry: string): Promise<string> {
     pending = (bun && typeof bun.build === 'function'
       ? (bun as BunBuild).build({ entrypoints: [entry], target: 'browser', minify: true }).then(async (result) => {
           if (!result.success) throw new Error(result.logs.map((l) => l.message).join('\n') || `client build failed: ${entry}`);
-          return result.outputs[0]!.text();
+          return PROCESS_SHIM + await result.outputs[0]!.text();
         })
       : Promise.resolve().then(() => {
           const prebuilt = entry.replace(/\.tsx?$/, '.bundle.js');
           if (!existsSync(prebuilt)) throw new Error(`client bundle missing at ${prebuilt} — the package's \`build\` writes it (scripts/publish/build.mjs); Node serves the prebuilt client`);
-          return readFileSync(prebuilt, 'utf8');
+          return PROCESS_SHIM + readFileSync(prebuilt, 'utf8');
         }))
       .catch((error) => { bundles.delete(entry); throw error; });
     bundles.set(entry, pending);

package/src/derived-core.ts

@@ -14,7 +14,8 @@ import { hashFieldValue } from './hash.ts';
 import { resolveSubjectId, subjectAliases } from './actions.ts';
 import { packReferences } from './references.ts';
 import type { SubjectFields } from './hash.ts';
-import { twinPublicBase } from './twin-fetch.ts';
+import { twinPublicBase, withRequestScopes } from './twin-fetch.ts';
+import { isReadOnlyRequest } from './request-scope.ts';
 import type { DerivedCall, DerivedCoreOutcome, DerivedHandler, DerivedOperation } from './derived.ts';
 
 // ── the manifest ─────────────────────────────────────────────────────────────────────────────
@@ -965,8 +966,10 @@ export function crossCutting(m: DerivedManifest, opts: CoreScope & { readOnly?:
       }
     }
     // a read-only twin refuses writes: what the operation does, not the HTTP verb it came by (an RPC
-    // wire POSTs its reads)
-    if (opts.readOnly && !['retrieve', 'list', 'computed'].includes(call.operation.class) && !m.reads?.includes(call.operation.id)) return vendorError(m, m.readOnly);
+    // wire POSTs its reads). A read-only REQUEST (x-volter-read-only, request-scope.ts) is refused the
+    // same way, up front, on a writable twin.
+    const readOnly = opts.readOnly || isReadOnlyRequest(request);
+    if (readOnly && !['retrieve', 'list', 'computed'].includes(call.operation.class) && !m.reads?.includes(call.operation.id)) return vendorError(m, m.readOnly);
     // a body labelled JSON that does not parse is the vendor's refusal, never a crash of the twin
     if ((request.headers.get('content-type') ?? '').includes('json') || m.body.json === 'always') {
       const text = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.clone().text().catch(() => '');
@@ -988,6 +991,8 @@ export function crossCutting(m: DerivedManifest, opts: CoreScope & { readOnly?:
       // a streamed answer replays as the stream it was; a record kept before text was kept replays its JSON
       return answer.text !== undefined ? new Response(answer.text, { status: answer.status, headers: { 'content-type': answer.contentType ?? 'application/json' } }) : Response.json(answer.body, { status: answer.status });
     }
+    // a read-only request replays a stored answer but records none: recording is a write
+    if (readOnly) return next();
     const response = await next();
     if (m.idempotency.onlySuccess && (response.status < 200 || response.status >= 300)) return response;
     const contentType = response.headers.get('content-type') ?? 'application/json';
@@ -997,6 +1002,15 @@ export function crossCutting(m: DerivedManifest, opts: CoreScope & { readOnly?:
   }
 }
 
+/** A derived pack's whole fetch behind the kernel's read scope (twin-fetch.ts withRequestScopes): a
+ *  read-only request's writes are refused at the write seam — the ones `crossCutting` cannot see
+ *  coming (another wire's mutation, a door, a screen) — and answered with the vendor's own read-only
+ *  error; `GET /twin` advertises `requestScopes`. The pack's catch-up runs under `runAsVendorMove`
+ *  (request-scope.ts), so time's moves still land when a read-only request is what arrives. */
+export function derivedRequestScopes<F extends (request: Request) => Promise<Response>>(m: DerivedManifest, fetch: F): F {
+  return withRequestScopes(fetch, { refuse: () => vendorError(m, m.readOnly) });
+}
+
 /** A semantics context for a request no surface operation names: another wire's (GraphQL) resolvers
  *  get the same interface as a handler, named by the operation id the wire gives. */
 export function semanticsContext(m: DerivedManifest, request: Request, operation: DerivedOperation, scope: CoreScope = {}): Promise<SemanticsContext> {

package/src/derived.ts

@@ -5,6 +5,7 @@
 // existing fetch, which keeps serving everything not yet moved (and every route outside the spec, such
 // as the `/twin` door). `owners` says, per operation, which of the two serves it: the count a pack's
 // move is measured by. Workerd-clean: no fs, no clock, nothing at import.
+import { runWithRequestTrace } from './trace-context.ts';
 
 /** The slice of a generated surface the dispatch reads. */
 export type DerivedOperation = {
@@ -141,7 +142,9 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
   const routes = compileSurface(options.surface);
   const fallback = (request: Request, operation: DerivedOperation | undefined, reason: string): Promise<Response> =>
     options.legacy ? options.legacy(request) : Promise.resolve(options.gap(request, operation, reason));
-  const fetch = (async (request: Request): Promise<Response> => {
+  // a valid incoming W3C traceparent scopes the dispatch, so every entry it appends records it (trace-context.ts)
+  const fetch = ((request: Request): Promise<Response> => runWithRequestTrace(request, () => dispatch(request))) as DerivedFetch;
+  const dispatch = async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
     const matched = options.anyMethod
       ? [...routes.keys()].map((m) => matchOperation(routes, m, url.pathname, url.searchParams, request.headers)).find(Boolean)
@@ -167,7 +170,7 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
       }
     }
     return fallback(request, matched.operation, 'no handler');
-  }) as DerivedFetch;
+  };
   fetch.owners = () =>
     Object.fromEntries(
       options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : options.legacy ? 'legacy' : 'gap'] as const),

package/src/git/refs.ts

@@ -3,15 +3,17 @@
 // state a snapshot carries, a projection can read, and (through the action log the plane keeps
 // beside it) a push policy can gate. No packed-refs: the store lists directories.
 import type { WorldStore } from '../world-store.ts';
+import { refuseReadOnlyWrite } from '../request-scope.ts';
 
 export class GitRefs {
   constructor(private readonly store: WorldStore, private readonly prefix: string) {}
   private path(name: string): string { return `${this.prefix}/${name}`; }
   get(name: string): string | null { const v = this.store.read(this.path(name)); return v === null ? null : v.trim(); }
-  set(name: string, sha: string): void { this.store.write(this.path(name), `${sha}\n`); }
-  delete(name: string): void { if (this.store.exists(this.path(name))) this.store.remove(this.path(name)); }
+  // a read-only request moves no ref (request-scope.ts): refused before the store is touched
+  set(name: string, sha: string): void { refuseReadOnlyWrite('git'); this.store.write(this.path(name), `${sha}\n`); }
+  delete(name: string): void { refuseReadOnlyWrite('git'); if (this.store.exists(this.path(name))) this.store.remove(this.path(name)); }
   head(): string { const v = this.store.read(this.path('HEAD')); return v === null ? 'refs/heads/main' : v.trim().replace(/^ref: /, ''); }
-  setHead(target: string): void { this.store.write(this.path('HEAD'), `ref: ${target}\n`); }
+  setHead(target: string): void { refuseReadOnlyWrite('git'); this.store.write(this.path('HEAD'), `ref: ${target}\n`); }
   /** Run `fn` holding the repository's ref lock (the world store's exclusive lock). */
   withLock<T>(fn: () => T): T { return this.store.withLock(this.path('refs.lock'), fn); }
   /** Every `refs/...` name with its sha, sorted by name. */