@volter/world-core 2.0.1 → 2.0.3

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

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

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