@volter/world-core 2.0.0 → 2.0.2

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,
@@ -59,13 +60,25 @@ function assertServiceName(service: string): string {
  */
 let worldPathsObserver: ((service: string, root: string | undefined) => void) | undefined;
 
-export 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 function observeWorldPaths(observer: ((service: string, root: string | undefined) => void) | undefined): ((service: string, root: string | undefined) => void) | undefined {
+  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<T>(fn: () => T): T {
+  identityQuiet++;
+  try { return fn(); } finally { identityQuiet--; }
 }
 
 export function worldPaths(service: string, root?: string): WorldPaths {
   const safeService = assertServiceName(service);
-  worldPathsObserver?.(safeService, root);
+  if (identityQuiet === 0) worldPathsObserver?.(safeService, root);
   const resolvedRoot = projectRoot(root);
   const dir = join(worldStateRoot(root), safeService);
   return {
@@ -81,6 +94,44 @@ export 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 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: string, root: string): boolean {
+  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: string, root?: string): string[] {
+  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<T>(path: string): T[] {
   const rows: T[] = [];
   for (const [index, line] of getActiveWorldStore().readLines(path).entries()) {
@@ -199,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);

package/src/trace-context.ts

@@ -0,0 +1,87 @@
+// 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);
+
+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 function parseTraceparent(value: unknown): Traceparent | null {
+  if (typeof value !== 'string') return null;
+  const m = TRACEPARENT.exec(value.trim());
+  if (!m) return null;
+  const [, version, traceId, parentId, flags] = m as unknown as [string, string, string, string, string];
+  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: unknown): string | undefined {
+  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: AsyncLocalStorage<string> | undefined;
+const traceScope = (): AsyncLocalStorage<string> => (traceStore ??= new AsyncLocalStorage<string>());
+
+/** Run `fn` with `traceparent` as the request's trace context; an invalid value runs `fn` outside any. */
+export function runWithTraceparent<T>(traceparent: string | undefined, fn: () => T): T {
+  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(): string | undefined {
+  return traceStore?.getStore();
+}
+
+/** Run `fn` inside the trace context `request` carries (its `traceparent` header), if any. */
+export function runWithRequestTrace<T>(request: Request, fn: () => T): T {
+  return runWithTraceparent(request.headers.get(TRACEPARENT_HEADER) ?? undefined, fn);
+}
+
+function newSpanId(): string {
+  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?: string | { traceparent?: unknown } | null): string | undefined {
+  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?: string | { traceparent?: unknown } | null): Record<string, string> {
+  const traceparent = traceparentForDelivery(cause);
+  return traceparent ? { [TRACEPARENT_HEADER]: traceparent } : {};
+}

package/src/twin-fetch.ts

@@ -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.ts';
+import { runWithRequestTrace } from './trace-context.ts';
+import { isReadOnlyRequest, runAsReadOnlyRequest, type ReadOnlyRequestError } from './request-scope.ts';
 import { worldNow } from './world-clock.ts';
 
 /** The header a host sets when it mounts a twin under a path (a served World's wire:
@@ -40,6 +42,53 @@ export type TwinStreamSink = { write(bytes: Uint8Array): void; end(): void };
 export type TwinStreamConnection = { data(chunk: Uint8Array): void; settled(): Promise<void>; 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 const TWIN_REQUEST_SCOPES: readonly string[] = ['read'];
+
+/** `GET /twin`'s body with the request scopes this seam enforces. */
+function advertised(manifest: unknown): unknown {
+  return manifest !== null && typeof manifest === 'object' && !Array.isArray(manifest) ? { ...(manifest as Record<string, unknown>), 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: ReadOnlyRequestError): Response {
+  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<F extends (request: Request) => Promise<Response>>(
+  fetch: F,
+  opts: { refuse?: (request: Request, error: ReadOnlyRequestError) => Response | Promise<Response> } = {},
+): F {
+  const scoped = async (request: Request): Promise<Response> => {
+    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 type TwinFetchHandlerResult = {
   status: number;
   body: unknown;
@@ -119,18 +168,23 @@ export function createTwinFetchFromHandler(
     // 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
@@ -145,3 +199,15 @@ export function createTwinFetchFromHandler(
     });
   };
 }
+
+/** 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: (asReadOnly?: boolean) => TwinFetchHandlerResult | Promise<TwinFetchHandlerResult>): Promise<TwinFetchHandlerResult> {
+  const out = await runAsReadOnlyRequest(() => run());
+  if (!out.refused) return out.value;
+  return { status: 405, body: { error: 'read_only', message: out.refused.message } };
+}

package/src/world-clock.ts

@@ -6,28 +6,31 @@
 // 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.ts';
+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 = (): number => {
+  const real = (globalThis as Record<symbol, unknown>)[Symbol.for('volter.machineDateNow')];
+  return typeof real === 'function' ? (real as () => number)() : 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(): string {
   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/src/world-store.ts

@@ -44,6 +44,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { hostname } from 'node:os';
+import { refuseReadOnlyWrite } from './request-scope.ts';
 import { basename, dirname, join, resolve } from 'node:path';
 
 /** Metadata a caller needs about a stored path. `isDirectory` distinguishes a JSON
@@ -183,6 +184,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   append(path: string, data: string): void {
+    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');
@@ -195,6 +197,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   write(path: string, data: string, options: { secret?: boolean } = {}): void {
+    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);
@@ -206,6 +209,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   writeAtomic(path: string, data: string, options: { secret?: boolean } = {}): void {
+    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 {
@@ -222,6 +226,7 @@ export class FsWorldStore implements WorldStore {
   }
 
   remove(path: string): void {
+    refuseReadOnlyWrite('the World'); // a read-only request writes nothing, whatever path it takes to the store
     rmSync(path, { recursive: true, force: true });
   }
 
@@ -391,18 +396,21 @@ export class MemoryWorldStore implements WorldStore {
   }
 
   append(path: string, data: string): void {
+    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: string, data: string): void {
+    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: string, data: string): void {
+    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);
@@ -419,6 +427,7 @@ export class MemoryWorldStore implements WorldStore {
   }
 
   remove(path: string): void {
+    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/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).
  */

package/world-clock.cjs

@@ -0,0 +1,40 @@
+'use strict';
+// THE WORLD CLOCK'S FORM — the one home of how a clock file reads (dependency-free, side-effect free), shared by the
+// twins' worldNow() (src/world-clock.ts, reading through the active WorldStore) and the injector, which gives an
+// application process the same time (inject.cjs, WORLD TIME).
+//
+// A clock file holds one line in one of two forms:
+//   · FROZEN:  `<ISO-8601 instant>` — every read answers exactly that instant (scripted time: lives, seeds, a story);
+//   · RUNNING: `<ISO-8601 instant> from <ISO-8601 wall instant>` — the World's time was <instant> when the machine's was
+//     <wall instant>, and runs on at the machine's pace from there: a World serving an application moves time this way
+//     (`volter-world clock <world> shift <N s|m|h|d>`), since a frozen instant would stop the application's time.
+// No file: the machine's time.
+
+/** The clock a file's text states, or throws on text that states neither form. */
+function parseClock(raw) {
+  const text = String(raw ?? '').trim();
+  const m = /^(\S+)\s+from\s+(\S+)$/.exec(text);
+  if (m) {
+    const at = Date.parse(m[1]);
+    const since = Date.parse(m[2]);
+    if (!Number.isNaN(at) && !Number.isNaN(since)) return { kind: 'running', at, since };
+  } else {
+    const at = Date.parse(text);
+    if (!Number.isNaN(at)) return { kind: 'frozen', at };
+  }
+  throw new Error(`world clock: expected an ISO-8601 instant, or "<instant> from <instant>", got ${JSON.stringify(text.slice(0, 60))}`);
+}
+
+/** The World's time in ms for a parsed clock, at the machine's time `wallMs`. */
+function clockNowMs(clock, wallMs) {
+  return clock.kind === 'running' ? clock.at + (wallMs - clock.since) : clock.at;
+}
+
+/** A clock's text: frozen at `atMs`, or running from `atMs` as of the machine's `sinceMs`. */
+function formatClock(clock) {
+  return clock.kind === 'running'
+    ? `${new Date(clock.at).toISOString()} from ${new Date(clock.since).toISOString()}`
+    : new Date(clock.at).toISOString();
+}
+
+module.exports = { parseClock, clockNowMs, formatClock };

package/world-clock.d.cts

@@ -0,0 +1,4 @@
+export type WorldClock = { kind: 'frozen'; at: number } | { kind: 'running'; at: number; since: number };
+export function parseClock(raw: string | null | undefined): WorldClock;
+export function clockNowMs(clock: WorldClock, wallMs: number): number;
+export function formatClock(clock: WorldClock): string;