@volter/world-core 2.0.1 → 2.0.2

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

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "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. */

package/src/head.ts

@@ -9,7 +9,7 @@
 // record: a `deployed` copy is never performed again, a `failed` one is retried.
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { confirmAction, isTwinBookkeeping, resolveSubjectId, revertAction, type TwinAction } from './actions.ts';
 import { openSealedCredential, sealCredential, type CredentialPayload, type SealedCredential } from './credential.ts';
 import { buildRemoteExecute, validateRemoteOrigin, type CredentialCustody } from './executor.ts';
@@ -116,11 +116,20 @@ export async function loadChecks(worldRoot: string): Promise<Check[]> {
  *  loader that runs the check in an isolate of its own, with no network and nothing of the World's. */
 export type CheckLoader = (path: string, name: string) => Promise<Check>;
 const importCheck: CheckLoader = async (path, name) => {
-  const mod = (await import(path)) as { check?: Check; default?: Check };
+  // Node's ESM loader takes an absolute path only as a file URL (on Windows `C:\…` reads as the scheme `c:`); Bun takes either
+  const mod = (await import(isAbsolute(path) ? fileUrlOf(path) : path)) as { check?: Check; default?: Check };
   const check = mod.check ?? mod.default;
   if (!check || typeof check.run !== 'function') throw new Error(`${path} must export a check { name, run }`);
   return { name: check.name ?? name, run: check.run };
 };
+/** An absolute path's file URL, built here: `node:url` is not in the browser bundles that also reach this module. */
+const fileUrlOf = (path: string): string => {
+  // a long path (`\\?\C:\…`) is the drive path it names; a UNC path (`\\server\share\…`) puts the server in the URL's host
+  const long = /^\\\\\?\\(?:UNC\\)?/i.exec(path); const unc = /^\\\\\?\\UNC\\/i.test(path) || (!long && /^\\\\[^\\?]/.test(path));
+  const rest = (long ? path.slice(long[0].length) : unc ? path.slice(2) : path).replace(/\\/g, '/');
+  const encoded = rest.split('/').map((seg) => encodeURIComponent(seg).replace(/%3A/g, ':')).join('/');
+  return unc ? `file://${encoded}` : `file://${rest.startsWith('/') ? '' : '/'}${encoded}`;
+};
 let checkLoader: CheckLoader = importCheck;
 export function setCheckLoader(loader: CheckLoader | null): void { checkLoader = loader ?? importCheck; }
 /** One check file through the host's loader: what placing a check validates with. */

package/src/index.ts

@@ -15,10 +15,13 @@ export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrit
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.ts';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, twinPublicBase } from './twin-fetch.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 type { Traceparent } from './trace-context.ts';
 export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.ts';
-export { bindSemantics, coreFor, crossCutting, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.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';
 export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, ResourceDecl, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.ts';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.ts';
 export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
@@ -313,7 +316,7 @@ export { referenceField, registerReferences, packReferences, resolveReferences,
 export { serveHttp, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
 // two runtime-neutral helpers for a pack's serve path: a file as a Response, a mirror's client bundle
 export { fileResponse, contentTypeOf } from './file-response.ts';
-export { bundleClient } from './client-bundle.ts';
+export { bundleClient, filePathOf } from './client-bundle.ts';
 // the brand's tokens and faces for a Volter page (the console, the site, the UI kit), fetched at build
 export { brandTokensResponse } from './brand-tokens.ts';
 

package/src/log.ts

@@ -71,6 +71,8 @@ export type Entry = {
   /** a landed copy under the vendor's id: the local subject id it stands for */
   aliasOf?: string;
   receipt?: Receipt;
+  /** the W3C traceparent of the request that wrote this entry (trace-context.ts); never part of its identity */
+  traceparent?: string;
   /** a v1 observed row kept verbatim for `listEvents`; folds nothing unless `fields` was derived */
   event?: WorldServiceEvent;
   [extra: string]: unknown;

package/src/request-scope.ts

@@ -0,0 +1,74 @@
+// 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: Request | { headers: Headers }): boolean {
+  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 {
+  constructor(readonly service: string) {
+    super(`${service}: this request is read-only (${READ_ONLY_REQUEST_HEADER}: 1); it cannot write`);
+    this.name = 'ReadOnlyRequestError';
+  }
+}
+
+type WriteScope = { readOnly: boolean; vendorMove: boolean; refusals: ReadOnlyRequestError[] };
+let writeScopeStore: AsyncLocalStorage<WriteScope> | undefined;
+const writeScope = (): AsyncLocalStorage<WriteScope> => (writeScopeStore ??= new AsyncLocalStorage<WriteScope>());
+
+/** 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<T>(fn: () => T | Promise<T>): Promise<{ value: T; refused: undefined } | { refused: ReadOnlyRequestError }> {
+  const scope: WriteScope = { 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<T>(fn: () => T): T {
+  const current = writeScope().getStore();
+  return current ? writeScope().run({ ...current, vendorMove: true }, fn) : fn();
+}
+
+/** Whether a write attempted here would be refused. */
+export function writesRefused(): boolean {
+  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: string): void {
+  if (!writesRefused()) return;
+  const error = new ReadOnlyRequestError(service);
+  writeScopeStore!.getStore()!.refusals.push(error);
+  throw error;
+}

package/src/storage.ts

@@ -6,6 +6,7 @@ import {
   WorldServiceEventSchema,
 } from './schemas.ts';
 import { getActiveWorldStore } from './world-store.ts';
+import { refuseReadOnlyWrite } from './request-scope.ts';
 import { parentEntries, toEvent } from './log.ts';
 import type {
   AppendEventResult,
@@ -249,6 +250,7 @@ export function projectionLockPath(paths: WorldPaths): string {
  */
 export function appendEvent(event: WorldServiceEvent, root?: string): AppendEventResult {
   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 as unknown as Record<string, unknown>), root);