@volter/world-core 2.0.0 → 2.0.2

package/src/derived.ts

@@ -5,6 +5,7 @@
 // existing fetch, which keeps serving everything not yet moved (and every route outside the spec, such
 // as the `/twin` door). `owners` says, per operation, which of the two serves it: the count a pack's
 // move is measured by. Workerd-clean: no fs, no clock, nothing at import.
+import { runWithRequestTrace } from './trace-context.ts';
 
 /** The slice of a generated surface the dispatch reads. */
 export type DerivedOperation = {
@@ -141,7 +142,9 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
   const routes = compileSurface(options.surface);
   const fallback = (request: Request, operation: DerivedOperation | undefined, reason: string): Promise<Response> =>
     options.legacy ? options.legacy(request) : Promise.resolve(options.gap(request, operation, reason));
-  const fetch = (async (request: Request): Promise<Response> => {
+  // a valid incoming W3C traceparent scopes the dispatch, so every entry it appends records it (trace-context.ts)
+  const fetch = ((request: Request): Promise<Response> => runWithRequestTrace(request, () => dispatch(request))) as DerivedFetch;
+  const dispatch = async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
     const matched = options.anyMethod
       ? [...routes.keys()].map((m) => matchOperation(routes, m, url.pathname, url.searchParams, request.headers)).find(Boolean)
@@ -167,7 +170,7 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
       }
     }
     return fallback(request, matched.operation, 'no handler');
-  }) as DerivedFetch;
+  };
   fetch.owners = () =>
     Object.fromEntries(
       options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : options.legacy ? 'legacy' : 'gap'] as const),

package/src/git/refs.ts

@@ -3,15 +3,17 @@
 // state a snapshot carries, a projection can read, and (through the action log the plane keeps
 // beside it) a push policy can gate. No packed-refs: the store lists directories.
 import type { WorldStore } from '../world-store.ts';
+import { refuseReadOnlyWrite } from '../request-scope.ts';
 
 export class GitRefs {
   constructor(private readonly store: WorldStore, private readonly prefix: string) {}
   private path(name: string): string { return `${this.prefix}/${name}`; }
   get(name: string): string | null { const v = this.store.read(this.path(name)); return v === null ? null : v.trim(); }
-  set(name: string, sha: string): void { this.store.write(this.path(name), `${sha}\n`); }
-  delete(name: string): void { if (this.store.exists(this.path(name))) this.store.remove(this.path(name)); }
+  // a read-only request moves no ref (request-scope.ts): refused before the store is touched
+  set(name: string, sha: string): void { refuseReadOnlyWrite('git'); this.store.write(this.path(name), `${sha}\n`); }
+  delete(name: string): void { refuseReadOnlyWrite('git'); if (this.store.exists(this.path(name))) this.store.remove(this.path(name)); }
   head(): string { const v = this.store.read(this.path('HEAD')); return v === null ? 'refs/heads/main' : v.trim().replace(/^ref: /, ''); }
-  setHead(target: string): void { this.store.write(this.path('HEAD'), `ref: ${target}\n`); }
+  setHead(target: string): void { refuseReadOnlyWrite('git'); this.store.write(this.path('HEAD'), `ref: ${target}\n`); }
   /** Run `fn` holding the repository's ref lock (the world store's exclusive lock). */
   withLock<T>(fn: () => T): T { return this.store.withLock(this.path('refs.lock'), fn); }
   /** Every `refs/...` name with its sha, sorted by name. */

package/src/head.ts

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

package/src/index.ts

@@ -15,10 +15,13 @@ export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrit
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.ts';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, twinPublicBase } from './twin-fetch.ts';
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from './twin-fetch.ts';
+export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
+export { currentTraceparent, deliveryTraceHeaders, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
+export type { Traceparent } from './trace-context.ts';
 export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.ts';
-export { bindSemantics, coreFor, crossCutting, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
+export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
 export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, ResourceDecl, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.ts';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.ts';
 export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
@@ -111,6 +114,9 @@ export {
   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.ts';
 export type {
   AppendEventResult,
@@ -190,6 +196,8 @@ export {
   isTwinBookkeeping,
   pendingTransactionCommits,
   projectResources,
+  projectOwnerResources,
+  OwnerStoreAmbiguousError,
   revertAction,
   TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.ts';
 export type {
@@ -308,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/packRegistry.ts

@@ -15,12 +15,14 @@ import { registerAuthStrategy, registerStateSystem, type StateSystemAdapters } f
 
 /**
  * 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