@volter/world-core 2.0.1 → 2.0.2

package/dist/src/actions.d.ts

@@ -87,6 +87,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;
 };
 export type TwinTransactionCommit = TwinAction;
 export type TwinTransactionCommitOp = TwinActionOp;

package/dist/src/actions.js

@@ -19,7 +19,9 @@ import { canonicalJson, subjectKey } from "./hash.js";
 import { appendDurable, eventsLockPath, ownerStoreRoots, projectionLockPath, twinLog, withFileLock, withoutIdentityClaim, worldPaths } from "./storage.js";
 import { landAsPlaceholder, placeholderPullActive } from "./placeholder-remote.js";
 import { aliasesFrom, dropCheckpoint, landedCopy, landedIds, parentEntries, readTree, treeStamp } from "./log.js";
+import { refuseReadOnlyWrite } from "./request-scope.js";
 import { getActiveWorldStore } from "./world-store.js";
+import { currentTraceparent } from "./trace-context.js";
 export class TwinActionPreconditionError extends Error {
     actionId;
     failed;
@@ -43,7 +45,10 @@ function withCorrelationId(action) {
     // 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
  *  precondition subject — a precondition established the action's validity against that
@@ -114,7 +119,7 @@ function landIfPlaceholderPull(action, root) {
     return { ...action, id: events.at(-1)?.id ?? action.id };
 }
 function replayBody(action) {
-    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
@@ -145,6 +150,7 @@ const correlationScope = () => (correlationStore ??= new AsyncLocalStorage());
 export function runWithCorrelationId(id, fn) { return correlationScope().run(id, fn); }
 export function currentCorrelationId() { return correlationScope().getStore(); }
 export function appendAction(action, root) {
+    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
@@ -164,6 +170,7 @@ export function appendAction(action, root) {
  *  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, root) {
+    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
@@ -198,6 +205,7 @@ export function appendActionIfAbsent(action, root) {
  * the same ordinals, which is what serve-path determinism requires.
  */
 export function appendActionOccurrence(base, root) {
+    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);
@@ -241,6 +249,7 @@ export function decideAndAppendAction(service, decide, 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}`);
         }
@@ -401,6 +410,7 @@ export function resolveSubjectId(service, type, id, root) {
  * the change is counted exactly once. Returns the observed event id.
  */
 export function confirmAction(opts) {
+    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);
@@ -431,6 +441,7 @@ export function confirmAction(opts) {
  * Only `set` rows are revertable — reverting a revert or a confirm is a category error.
  */
 export function revertAction(opts) {
+    refuseReadOnlyWrite(opts.service);
     return withFileLock(projectionLock(opts.service, opts.root), () => withFileLock(actionsLock(opts.service, opts.root), () => {
         const all = listActions(opts.service, opts.root);
         const target = all.find((a) => a.id === opts.actionId);

package/dist/src/blob-store.d.ts

@@ -50,6 +50,9 @@ export declare class MemoryBlobStore implements BlobStore {
 }
 /** Content-address helper shared by byte-carrying packs: sha256 hex of the bytes. */
 export declare function blobDigest(bytes: Uint8Array): string;
+/** 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 declare function getActiveBlobStore(): BlobStore;
 export declare function setActiveBlobStore(store: BlobStore): BlobStore;
 export declare function withBlobStore<T>(store: BlobStore, fn: () => Promise<T> | T): Promise<T>;

package/dist/src/blob-store.js

@@ -23,6 +23,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync,
 import { dirname, join } from 'node:path';
 import { volterHome } from "./volter-home.js";
 import { sharedBlobIndex } from "./shared-blob-index.js";
+import { refuseReadOnlyWrite, writesRefused } from "./request-scope.js";
 /** A range of the blob at `key` through the active store: native when the store has it, else sliced. */
 export async function readBlobRange(key, start, endInclusive) {
     // one clamping for every backend: a negative or non-finite start reads from 0, a range that ends
@@ -167,8 +168,21 @@ export function blobDigest(bytes) {
 // Active-store scoping, the world-store.ts pattern exactly: default fs; a serverless entry
 // (or a test) swaps in its adapter for the scope of a request.
 let activeBlobStore = 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() {
-    return activeBlobStore;
+    return writesRefused() ? readOnlyBlobs(activeBlobStore) : activeBlobStore;
+}
+function readOnlyBlobs(store) {
+    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) {
     const previous = activeBlobStore;

package/dist/src/client-bundle.d.ts

@@ -1 +1,5 @@
+/** 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 declare function filePathOf(url: URL): string;
 export declare function bundleClient(entry: string): Promise<string>;

package/dist/src/client-bundle.js

@@ -4,7 +4,18 @@
 // by scripts/publish/build.mjs into dist/client/. Built once per process and kept; a failed build
 // 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) {
+    const path = decodeURIComponent(url.pathname);
+    return /^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path;
+}
 const bundles = new Map();
+/** 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) {
     let pending = bundles.get(entry);
     if (!pending) {
@@ -13,13 +24,13 @@ export function bundleClient(entry) {
             ? bun.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/dist/src/derived-core.d.ts

@@ -447,6 +447,12 @@ export declare function coreFor(m: DerivedManifest, scope?: CoreScope): {
 export declare function crossCutting(m: DerivedManifest, opts?: CoreScope & {
     readOnly?: boolean;
 }): (call: DerivedCall, next: () => Promise<Response>) => Promise<Response>;
+/** 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 declare function derivedRequestScopes<F extends (request: Request) => Promise<Response>>(m: DerivedManifest, fetch: F): F;
 /** 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 declare function semanticsContext(m: DerivedManifest, request: Request, operation: DerivedOperation, scope?: CoreScope): Promise<SemanticsContext>;

package/dist/src/derived-core.js

@@ -12,7 +12,8 @@ import { createHash } from 'node:crypto';
 import { hashFieldValue } from "./hash.js";
 import { resolveSubjectId, subjectAliases } from "./actions.js";
 import { packReferences } from "./references.js";
-import { twinPublicBase } from "./twin-fetch.js";
+import { twinPublicBase, withRequestScopes } from "./twin-fetch.js";
+import { isReadOnlyRequest } from "./request-scope.js";
 /** What a move to `to` stores in the field: a boolean field's value is a boolean, and a derived field's
  *  value is written by the move's effects (a state name is not a timestamp), so it stores nothing itself. */
 export function storedState(decl, to) {
@@ -732,8 +733,10 @@ export function crossCutting(m, opts = {}) {
             }
         }
         // 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))
+        // 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') {
@@ -766,6 +769,9 @@ export function crossCutting(m, opts = {}) {
             // 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;
@@ -775,6 +781,14 @@ export function crossCutting(m, opts = {}) {
         return response;
     }
 }
+/** 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(m, fetch) {
+    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, request, operation, scope = {}) {

package/dist/src/derived.js

@@ -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.js";
 class Unmodeled extends Error {
 }
 function compile(operation, basePath, spanning) {
@@ -85,7 +86,9 @@ export function createDerivedFetch(options) {
         throw new Error(`derived dispatch: handlers name operations the surface does not have: ${unknown.sort().join(', ')}`);
     const routes = compileSurface(options.surface);
     const fallback = (request, operation, reason) => options.legacy ? options.legacy(request) : Promise.resolve(options.gap(request, operation, reason));
-    const fetch = (async (request) => {
+    // a valid incoming W3C traceparent scopes the dispatch, so every entry it appends records it (trace-context.ts)
+    const fetch = ((request) => runWithRequestTrace(request, () => dispatch(request)));
+    const dispatch = async (request) => {
         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)
@@ -116,7 +119,7 @@ export function createDerivedFetch(options) {
             }
         }
         return fallback(request, matched.operation, 'no handler');
-    });
+    };
     fetch.owners = () => Object.fromEntries(options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : options.legacy ? 'legacy' : 'gap']));
     return fetch;
 }

package/dist/src/git/refs.js

@@ -1,3 +1,4 @@
+import { refuseReadOnlyWrite } from "../request-scope.js";
 export class GitRefs {
     store;
     prefix;
@@ -7,11 +8,12 @@ export class GitRefs {
     }
     path(name) { return `${this.prefix}/${name}`; }
     get(name) { const v = this.store.read(this.path(name)); return v === null ? null : v.trim(); }
-    set(name, sha) { this.store.write(this.path(name), `${sha}\n`); }
-    delete(name) { if (this.store.exists(this.path(name)))
+    // a read-only request moves no ref (request-scope.ts): refused before the store is touched
+    set(name, sha) { refuseReadOnlyWrite('git'); this.store.write(this.path(name), `${sha}\n`); }
+    delete(name) { refuseReadOnlyWrite('git'); if (this.store.exists(this.path(name)))
         this.store.remove(this.path(name)); }
     head() { const v = this.store.read(this.path('HEAD')); return v === null ? 'refs/heads/main' : v.trim().replace(/^ref: /, ''); }
-    setHead(target) { this.store.write(this.path('HEAD'), `ref: ${target}\n`); }
+    setHead(target) { 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(fn) { return this.store.withLock(this.path('refs.lock'), fn); }
     /** Every `refs/...` name with its sha, sorted by name. */

package/dist/src/head.js

@@ -17,7 +17,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // 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 } from "./actions.js";
 import { openSealedCredential, sealCredential } from "./credential.js";
 import { buildRemoteExecute, validateRemoteOrigin } from "./executor.js";
@@ -101,12 +101,22 @@ export async function loadChecks(worldRoot) {
     return out;
 }
 const importCheck = async (path, name) => {
-    const mod = (await import(__rewriteRelativeImportExtension(path)));
+    // 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(__rewriteRelativeImportExtension(isAbsolute(path) ? fileUrlOf(path) : path)));
     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) => {
+    // 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 = importCheck;
 export function setCheckLoader(loader) { checkLoader = loader ?? importCheck; }
 /** One check file through the host's loader: what placing a check validates with. */

package/dist/src/index.d.ts

@@ -3,10 +3,13 @@ export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrit
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.js';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.js';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.js';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, twinPublicBase } from './twin-fetch.js';
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from './twin-fetch.js';
+export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.js';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.js';
+export { currentTraceparent, deliveryTraceHeaders, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';
+export type { Traceparent } from './trace-context.js';
 export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.js';
-export { bindSemantics, coreFor, crossCutting, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.js';
+export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.js';
 export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, ResourceDecl, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.js';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.js';
 export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.js';
@@ -62,7 +65,7 @@ export * from './v1-removed.js';
 export { referenceField, registerReferences, packReferences, resolveReferences, type ReferenceDeclaration } from './references.js';
 export { serveHttp, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.js';
 export { fileResponse, contentTypeOf } from './file-response.js';
-export { bundleClient } from './client-bundle.js';
+export { bundleClient, filePathOf } from './client-bundle.js';
 export { brandTokensResponse } from './brand-tokens.js';
 export { readResourceBlob, readResourceBlobRange, resourceBlobSize, resourceChain } from './resource-blob.js';
 export { mirrorShellUnder } from './mirror-shell.js';

package/dist/src/index.js

@@ -14,9 +14,11 @@ export { clearRegistry, getPack, hasPack, listPacks, registerPack, pullPosture,
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
 export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, twinPublicBase } from "./twin-fetch.js";
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from "./twin-fetch.js";
+export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
-export { bindSemantics, coreFor, crossCutting, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from "./derived-core.js";
+export { currentTraceparent, deliveryTraceHeaders, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
+export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from "./derived-core.js";
 export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from "./emit.js";
 // The vendor-agnostic CLIENT-SIDE RATE BUDGET — the fail-closed backstop a pack's guarded client
 // routes every live vendor call through. The MECHANISM is here; the per-vendor ceiling/window/
@@ -89,7 +91,7 @@ export { referenceField, registerReferences, packReferences, resolveReferences }
 export { serveHttp, nodeBuiltin, WORLD_BOOT_PATH } from "./serve-http.js";
 // 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.js";
-export { bundleClient } from "./client-bundle.js";
+export { bundleClient, filePathOf } from "./client-bundle.js";
 // 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.js";
 export { readResourceBlob, readResourceBlobRange, resourceBlobSize, resourceChain } from "./resource-blob.js";

package/dist/src/log.d.ts

@@ -64,6 +64,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/dist/src/request-scope.d.ts

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

package/dist/src/request-scope.js

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

package/dist/src/storage.js

@@ -3,6 +3,7 @@ import { assertNotBeingRemoved, withAncestryLock, withStateRemoval } from "./anc
 import { appendParentEntry, toEntry } from "./log.js";
 import { GenericWorldStateSchema, WorldServiceEventSchema, } from "./schemas.js";
 import { getActiveWorldStore } from "./world-store.js";
+import { refuseReadOnlyWrite } from "./request-scope.js";
 import { parentEntries, toEvent } from "./log.js";
 function nowIso() {
     return new Date().toISOString();
@@ -226,6 +227,7 @@ export function projectionLockPath(paths) {
  */
 export function appendEvent(event, root) {
     const parsed = WorldServiceEventSchema.parse(event);
+    refuseReadOnlyWrite(parsed.service); // a read-only request writes nothing (request-scope.ts)
     const paths = worldPaths(parsed.service, root);
     ensureEventDirs(paths);
     const { appended } = appendParentEntry(toEntry(parsed), root);

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

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

package/dist/src/trace-context.js

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