@volter/world-core 2.0.0 → 2.0.2

package/dist/src/actions.js

@@ -16,10 +16,12 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import { canonicalJson, subjectKey } from "./hash.js";
-import { appendDurable, eventsLockPath, projectionLockPath, twinLog, withFileLock, worldPaths } from "./storage.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 } from "./log.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}`);
         }
@@ -334,6 +343,53 @@ function assertPreconditions(action, root) {
 export function projectResources(service, root, opts = {}) {
     return readTree(service, root, opts);
 }
+/** A read of another pack's store that cannot choose: the subject it looks for (or, with none named, the store itself)
+ *  is held by more than one service of the World. A reader answers it as the vendor answers a credential it cannot
+ *  resolve; it is never a server error. */
+export class OwnerStoreAmbiguousError extends Error {
+    constructor(owner, roots, subject) {
+        super(`${subject ? `${subject.type} ${subject.id} of ` : ''}${owner}'s store is held by more than one service of this World (${roots.join(', ')}); a cross-pack read cannot choose between them`);
+        this.name = 'OwnerStoreAmbiguousError';
+    }
+}
+const ownerIndexes = new Map();
+function ownerIndex(owner, root) {
+    const key = `${owner}\0${root}`;
+    const stamp = treeStamp(owner, root);
+    const held = ownerIndexes.get(key);
+    if (held && held.stamp === stamp)
+        return held;
+    const rows = readTree(owner, root).map((r) => Object.freeze(r));
+    const index = { stamp, rows: Object.freeze(rows), byKey: new Map(rows.map((r) => [`${r.type}:${r.id}`, r])) };
+    ownerIndexes.set(key, index);
+    return index;
+}
+/**
+ * ANOTHER pack's rows, read by contract (architecture A3: one vendor's store split across two packs, xidentity's tokens
+ * read by x, googleoauth's by googlecalendar; scripts/architecture.test.ts holds the declared reader-owner pairs): the
+ * owner's tree, from wherever the World keeps the owner's store (`ownerStoreRoots`). Read only: the rows are frozen and
+ * shared. It claims no journal identity (the twin answering is the reader).
+ *
+ * With `subject`, the store that holds that subject (the token a request presents): `[]` when none does, and
+ * `OwnerStoreAmbiguousError` only when more than one does, so a second service running the owning pack never breaks a
+ * lookup of what only one of them issued. Without it, the one store there is, and `OwnerStoreAmbiguousError` when the
+ * World holds two.
+ */
+export function projectOwnerResources(owner, root, subject) {
+    return withoutIdentityClaim(() => {
+        const roots = ownerStoreRoots(owner, root);
+        if (!subject) {
+            if (roots.length > 1)
+                throw new OwnerStoreAmbiguousError(owner, roots);
+            return roots[0] ? ownerIndex(owner, roots[0]).rows : [];
+        }
+        const key = `${subject.type}:${subject.id}`;
+        const holding = roots.filter((r) => ownerIndex(owner, r).byKey.has(key));
+        if (holding.length > 1)
+            throw new OwnerStoreAmbiguousError(owner, holding, subject);
+        return holding[0] ? ownerIndex(owner, holding[0]).rows : [];
+    });
+}
 /** The local → vendor id aliases the landed copies carry: a read by the id a caller was handed before
  *  its write was performed resolves to the row the vendor now owns. */
 export function subjectAliases(service, root) {
@@ -354,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);
@@ -384,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';
@@ -20,7 +23,7 @@ export { loadWorldConfig, } from './worldConfig.js';
 export type { WorldConfig, WorldServiceConfig, } from './worldConfig.js';
 export { DELTA_TYPE_SUFFIX, diffSubjectFields, hashFieldValue, subjectKey, deltaAfterFields } from './hash.js';
 export type { FieldChange, SubjectFields, } from './hash.js';
-export { appendDurable, appendEvent, createEvent, emptyGenericState, genericWorldReducer, listEvents, loadState, projectionLockPath, readJsonFile, rebuildGenericState, rebuildState, scrubService, scrubWorld, stateDirName, twinLog, withFileLock, worldPaths, worldStateRoot, } from './storage.js';
+export { appendDurable, appendEvent, createEvent, emptyGenericState, genericWorldReducer, listEvents, loadState, projectionLockPath, readJsonFile, rebuildGenericState, rebuildState, scrubService, scrubWorld, stateDirName, twinLog, withFileLock, worldPaths, worldStateRoot, ownerStoreRoots, WORLD_DATA_ENV, } from './storage.js';
 export type { AppendEventResult, CommitQueuedEventsResult, GenericWorldState, EnqueueEventResult, QueuedWorldServiceEvent, WorldPaths, WorldReducer, WorldServiceEvent, } from './types.js';
 export type { ScrubResult } from './storage.js';
 export { FsWorldStore, MemoryWorldStore, getActiveWorldStore, setActiveWorldStore, withWorldStore, hydrateInto, flushFrom, } from './world-store.js';
@@ -36,7 +39,7 @@ export { createTwinProxy } from './proxy.js';
 export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.js';
 export { forkTwin, isFork, readForkMeta, } from './fork.js';
 export type { ForkMeta } from './fork.js';
-export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.js';
+export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.js';
 export type { ActionProjection, ProjectedDelivery, ProjectedResource, ProjectedResourcePatch, ProjectedResourceRef, TwinAction, TwinActionOp, TwinActionPrecondition, TwinActionPreconditionOp, TwinActionRevertSpec, TwinTransactionCommit, TwinTransactionCommitOp, TwinTransactionPrecondition, TwinTransactionRevertSpec, } from './actions.js';
 export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, CHANGESET_KIND, diffLedgers, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from './changeset.js';
 export type { ApplyReceipt, RebaseActionResult, RebaseReport, RebaseTarget, Changeset, ChangesetAction, ChangesetApplication, CompensationEntry, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, ChangesetVerifierResult, LedgerDelta, LedgerPosition, LedgerRef, ReplayActionResult, ReplayReport, ReplayTarget, VendorSummary, WorldMarker, } from './changeset.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/
@@ -42,7 +44,9 @@ twinLog,
 // The kernel's cross-process mutual-exclusion primitive (exclusive-create lockfile with
 // stale-holder reclaim). Public so world-runtime can guard concurrent `upWorld` claims of
 // one instance dir with the SAME lock semantics the event log uses (TWIN-36).
-withFileLock, worldPaths, worldStateRoot, } from "./storage.js";
+withFileLock, worldPaths, worldStateRoot, 
+// Where another pack's store is in a World (architecture A3), and the variable the runtime names its data directory in.
+ownerStoreRoots, WORLD_DATA_ENV, } from "./storage.js";
 // The pluggable persistence seam: the sync WorldStore interface, its fs (default) and
 // in-memory implementations, the active-store injection point, and the async
 // hydrate/flush boundary a serverless (Durable Object / KV / redis) entry uses.
@@ -54,7 +58,7 @@ export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActive
 export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, journalTwinRequest, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from "./serve.js";
 export { createTwinProxy } from "./proxy.js";
 export { forkTwin, isFork, readForkMeta, } from "./fork.js";
-export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";
+export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";
 // ── Operator control plane (R19/R20): remote refs, queue lifecycle, push ledger,
 // apply leases, plan, status. (the twins architecture notes)
 // The CHANGESET primitive + the ledger DIFF (docs/concepts/the-model.md v0) — "commit" and
@@ -87,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/packRegistry.d.ts

@@ -5,12 +5,14 @@ import type { TwinEmitter } from './emit.js';
 import { type StateSystemAdapters } from './state-system.js';
 /**
  * How a pack's clients ADDRESS it. The first three are HTTP API styles; `raw-tcp` is the
- * RAW-PROTOCOL class — a pack whose clients speak a line protocol directly over a TCP socket
- * rather than HTTP, so none of the HTTP machinery applies: no `browserRouting`, and no entry in
- * the injector's `VENDOR_HOSTS` host map is possible (the injector patches http/fetch and never
- * sees the traffic). Such a pack is wired into a world through app-read host/port env instead,
- * and this value is what tells a reader that "no injector entry" is STRUCTURAL rather than a
- * missing wiring point. `packages/twin/smtp` is the first.
+ * RAW-PROTOCOL class — a pack whose clients speak their protocol directly over a TCP socket
+ * rather than through the HTTP/1 fetch machinery, so none of the HTTP machinery applies: no
+ * `browserRouting`, and no entry in the injector's `VENDOR_HOSTS` host map is possible (the
+ * injector patches http/fetch and never sees the traffic). Such a pack is wired into a world
+ * through app-read host/port env instead, and this value is what tells a reader that "no injector
+ * entry" is STRUCTURAL rather than a missing wiring point. `packages/twin/smtp` (a line protocol)
+ * is the first; `packages/twin/temporal` (gRPC: HTTP/2 framing its clients drive themselves) the
+ * second.
  *
  * Deliberately the transport CLASS, not the protocol name: naming the wire protocol would put a
  * vendor id in the kernel the moment a pack is named after its protocol, which is exactly what