@volter/world-core 2.0.0

package/src/twin-fetch.ts

@@ -0,0 +1,147 @@
+// THE ONE HTTP ADAPTATION (runtime contract R12b): most packs' serve path is the same
+// ~20 lines of glue — the keyless GET /twin manifest door, the body read, a header map,
+// the dispatch into `handle<Vendor>TwinRequest` with the WORLD instant, and a JSON
+// response. That glue is a MECHANISM, so it lives here once; a pack's differences are
+// VALUES (its manifest, its header threading, its static handler options, its extra
+// response headers). A pack whose wire genuinely exceeds this shape (SSE streaming,
+// multipart adaptation, raw-bytes responses) writes its own fetch instead — openai is
+// that reference; this adapter is the reference for everyone else.
+//
+// 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 { worldNow } from './world-clock.ts';
+
+/** The header a host sets when it mounts a twin under a path (a served World's wire:
+ *  `/<org>/<world>/<vendor>`), the reverse-proxy convention; with it the host sets
+ *  `x-forwarded-host` and `x-forwarded-proto` to where the World is reached. */
+export const TWIN_PREFIX_HEADER = 'x-forwarded-prefix';
+
+/** Where this twin is reached for this request: the request's origin plus the path a host mounted
+ *  the twin under. A pack mints every live URL it hands back (an upload target, a file link, a
+ *  callback) from this, never from the bare origin, so the URL works behind a served World. */
+export function twinPublicBase(request: Request): string {
+  const prefix = request.headers.get(TWIN_PREFIX_HEADER);
+  if (!prefix || !/^\/[A-Za-z0-9._~\/-]*$/.test(prefix)) return new URL(request.url).origin;
+  // the host that mounted the twin says where it is reached: a local World forwards to the twin's
+  // own port, so the request's own origin is not the public one
+  const host = request.headers.get('x-forwarded-host');
+  const proto = request.headers.get('x-forwarded-proto');
+  const origin = host && /^[A-Za-z0-9.-]+(:\d+)?$/.test(host) && (proto === 'http' || proto === 'https') ? `${proto}://${host}` : new URL(request.url).origin;
+  return `${origin}${prefix.replace(/\/+$/, '')}`;
+}
+
+/** A twin's BYTE-STREAM door: a pack whose clients speak a TCP protocol (SMTP, the MySQL wire) serves
+ *  it over whatever carries the bytes — a local listener's socket, or a WebSocket to a hosted World.
+ *  The pack owns framing and protocol; the host owns the transport. `open` greets through the sink;
+ *  `data` hands the connection bytes in arrival order; `settled` resolves when every byte handed so
+ *  far has been answered; `close` is the peer going away. */
+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;
+
+export type TwinFetchHandlerResult = {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+/** The common handler request shape. Extra vendor fields ride `handlerOptions` (static,
+ *  per instance) and `extras` (derived per request); handlers ignore keys they don't
+ *  declare, so the union is safe to pass wholesale. */
+export type TwinFetchHandlerRequest = {
+  method: string;
+  path: string;
+  body: string;
+  headers: Record<string, string>;
+  readOnly: boolean;
+  occurredAt: string;
+  root?: string;
+} & Record<string, unknown>;
+
+export interface TwinFetchAdapterConfig {
+  root?: string;
+  readOnly?: boolean;
+  /** The keyless GET /twin body — a value (stateful packs: statefulTwinManifest(...)) or
+   *  a thunk (generative packs build theirs around the scenario engine). */
+  manifest: unknown | (() => unknown);
+  /** GET /twin/scenario body (thunk) — scenario-carrying packs only. */
+  scenarioStatus?: () => unknown;
+  /** THE STORE DOOR (R5c, mirror purity R3): named, deterministic projections over stored
+   *  state, served at `GET /twin/store/<name>` and listed in the manifest as `stores`. A
+   *  mirror reads twin state ONLY through this door — never by importing the handler or a
+   *  `-twin-internal` module — so the vendor API lacking a listing endpoint (resend has no
+   *  list-emails) no longer breeds a bespoke `/_twin/*` route per mirror. Keyed in the skin
+   *  like every state read (only bare `GET /twin` is keyless). */
+  stores?: Record<string, () => unknown | Promise<unknown>>;
+  /** Per-request vendor extras (header threading: stripe-version, notion-version, …). */
+  extras?: (request: Request, url: URL) => Record<string, unknown>;
+  /** Static per-instance handler options (e.g. rateLimitPerSecond). */
+  handlerOptions?: Record<string, unknown>;
+  /** Extra response headers on every non-door reply (e.g. stripe's request-id, and
+   *  postmark's `connection: close` Bun-socket workaround — inert under workerd). */
+  responseHeaders?: Record<string, string>;
+}
+
+export function createTwinFetchFromHandler(
+  handler: (request: TwinFetchHandlerRequest) => TwinFetchHandlerResult | Promise<TwinFetchHandlerResult>,
+  config: TwinFetchAdapterConfig,
+): (request: Request) => Promise<Response> {
+  const readOnly = config.readOnly ?? false;
+  return async function twinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
+    if (request.method === 'GET' && cleanPath === '/twin') {
+      const manifest = typeof config.manifest === 'function' ? (config.manifest as () => unknown)() : config.manifest;
+      const storeNames = Object.keys(config.stores ?? {}).sort();
+      if (storeNames.length > 0 && manifest !== null && typeof manifest === 'object') {
+        const m = manifest as Record<string, unknown>;
+        const doors = m.doors !== null && typeof m.doors === 'object' ? (m.doors as Record<string, unknown>) : {};
+        // The manifest EDUCATES: it lists the store names and names the door's path.
+        return Response.json({ ...m, stores: storeNames, doors: { ...doors, store: 'GET /twin/store/<name>' } });
+      }
+      return Response.json(manifest);
+    }
+    if (request.method === 'GET' && cleanPath === '/twin/scenario' && config.scenarioStatus !== undefined) {
+      return Response.json(config.scenarioStatus());
+    }
+    if (request.method === 'GET' && cleanPath.startsWith('/twin/store/')) {
+      const name = cleanPath.slice('/twin/store/'.length);
+      const store = config.stores?.[name];
+      if (store === undefined) return Response.json({ error: 'unknown store', store: name, stores: Object.keys(config.stores ?? {}).sort() }, { status: 404 });
+      return Response.json(await store()); // a projection may read through the handler (async) — the door awaits it
+    }
+    const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => { headers[key] = value; });
+    // FIXED FIELDS WIN (review B1): handlerOptions/extras spread FIRST, so no config —
+    // and via extras, no WIRE INPUT — can override method/path/body/readOnly or the
+    // 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({
+      ...config.handlerOptions,
+      ...config.extras?.(request, url),
+      method: request.method,
+      path: url.pathname + (url.search || ''),
+      body,
+      headers,
+      readOnly,
+      occurredAt: worldNow(),
+      ...(config.root !== undefined ? { root: config.root } : {}),
+    });
+    const result = await (requestId ? runWithCorrelationId(requestId, invoke) : invoke());
+    // 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
+    // Bun silently serves '""' — either way a wire break on exactly one lane.
+    const nullBodyStatus = result.status === 204 || result.status === 205 || result.status === 304;
+    if (result.body === null || result.body === undefined || (nullBodyStatus && result.body === '')) {
+      return new Response(null, { status: result.status, headers: { ...config.responseHeaders, ...result.headers } });
+    }
+    return new Response(JSON.stringify(result.body), {
+      status: result.status,
+      headers: { 'content-type': 'application/json', ...config.responseHeaders, ...result.headers },
+    });
+  };
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+import type { z } from 'zod';
+import type {
+  GenericWorldStateSchema,
+  WorldServiceEventSchema,
+} from './schemas.ts';
+
+export type WorldServiceEvent = z.infer<typeof WorldServiceEventSchema>;
+export type GenericWorldState = z.infer<typeof GenericWorldStateSchema>;
+
+export type AppendEventResult = {
+  event: WorldServiceEvent;
+  appended: boolean;
+  duplicateOf?: string;
+};
+
+export type QueuedWorldServiceEvent = {
+  id: string;
+  service: string;
+  receivedAt: string;
+  source: 'listener' | 'webhook' | 'broker' | 'capture' | 'manual' | 'replay';
+  event: WorldServiceEvent;
+};
+
+export type EnqueueEventResult = {
+  queued: QueuedWorldServiceEvent;
+  appended: boolean;
+  duplicateOf?: string;
+};
+
+export type CommitQueuedEventsResult = {
+  service: string;
+  queued: number;
+  committed: number;
+  skipped: number;
+  eventIds: string[];
+};
+
+export type WorldPaths = {
+  root: string;
+  service: string;
+  dir: string;
+  events: string;
+  state: string;
+  resources: string;
+  cursors: string;
+  ingests: string;
+  eventQueue: string;
+};
+
+export type WorldReducer<State> = (state: State, event: WorldServiceEvent) => State;

package/src/v1-removed.ts

@@ -0,0 +1,172 @@
+// v1 LEFT THE KERNEL (company contract "Just like Neon", 5 — ruled 2026-09-06). These names are what
+// a protocol 1 pack still imports: the push ledger, the shadow refs and bases, observed deltas as a
+// row kind, egress intents, plans, leases, reconcile, remote refs, the queue lifecycle, the v1 status,
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// validation and inspector, the poll runner, the v1 apply. Each throws on its first call. A pack
+// that reaches one is out of date; the sweep moves it (protocol 2: the head, the fold, the tree).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+// Reaching a tombstone is RECORDED, process-wide (one list whichever copy of the kernel the caller
+// resolved), so a verify() that swallows the throw and answers false is still known to have reached
+// v1 machinery: the capability runner reads this list around each verify and says "out of date".
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const REACHED = Symbol.for('volter.v1.reached');
+export function v1Reached(): string[] { return ((globalThis as Record<symbol, unknown>)[REACHED] ??= []) as string[]; }
+// …and per SCOPE, so concurrent verifies attribute a reach to the one that made it (the runner opens a
+// scope around each verify); one storage per process, whichever copy of the kernel the caller resolved
+const SCOPE = Symbol.for('volter.v1.reached.scope');
+// created on first use, never at import (a browser bundle has no AsyncLocalStorage; see observe.ts)
+const scope = (): AsyncLocalStorage<string[]> => ((globalThis as Record<symbol, unknown>)[SCOPE] ??= new AsyncLocalStorage<string[]>()) as AsyncLocalStorage<string[]>;
+/** Run `fn` and learn which v1 names it reached (directly or through anything it awaited). */
+export async function v1ReachedIn<T>(fn: () => Promise<T>): Promise<{ value: T; reached: string[] }> {
+  const reached: string[] = [];
+  const value = await scope().run(reached, fn);
+  return { value, reached };
+}
+const gone = (name: string): any => { v1Reached().push(name); if (typeof AsyncLocalStorage === 'function') scope().getStore()?.push(name); throw new Error(`v1 removed: ${name} — protocol 2 replaces it (the head performs, the kernel folds observations, the tree is read); this pack is out of date until the sweep moves it`); };
+
+export function appendEventLocked(..._args: any[]): any { return gone('appendEventLocked'); }
+export function eventsLockPath(..._args: any[]): any { return gone('eventsLockPath'); }
+export function appendPushRecord(..._args: any[]): any { return gone('appendPushRecord'); }
+export function listPushLedger(..._args: any[]): any { return gone('listPushLedger'); }
+export function latestPushByActionId(..._args: any[]): any { return gone('latestPushByActionId'); }
+export function unconfirmedPushes(..._args: any[]): any { return gone('unconfirmedPushes'); }
+export function assertFastForward(..._args: any[]): any { return gone('assertFastForward'); }
+export function pushTransaction(..._args: any[]): any { return gone('pushTransaction'); }
+export function abandonPush(..._args: any[]): any { return gone('abandonPush'); }
+export function syncPull(..._args: any[]): any { return gone('syncPull'); }
+export function syncPush(..._args: any[]): any { return gone('syncPush'); }
+export function currentResources(..._args: any[]): any { return gone('currentResources'); }
+export function isEgressEventType(..._args: any[]): any { return gone('isEgressEventType'); }
+export function recordWriteIntent(..._args: any[]): any { return gone('recordWriteIntent'); }
+export function performExternalWrite(..._args: any[]): any { return gone('performExternalWrite'); }
+export function listUnreconciledWriteIntents(..._args: any[]): any { return gone('listUnreconciledWriteIntents'); }
+export function listEgressLedger(..._args: any[]): any { return gone('listEgressLedger'); }
+export function findWriteResultByExternal(..._args: any[]): any { return gone('findWriteResultByExternal'); }
+export function transactionSetId(..._args: any[]): any { return gone('transactionSetId'); }
+export function listPlanReviews(..._args: any[]): any { return gone('listPlanReviews'); }
+export function latestPlanReview(..._args: any[]): any { return gone('latestPlanReview'); }
+export function buildLocalActionPlan(..._args: any[]): any { return gone('buildLocalActionPlan'); }
+export function recordPlanReview(..._args: any[]): any { return gone('recordPlanReview'); }
+export function approvedPendingActionSet(..._args: any[]): any { return gone('approvedPendingActionSet'); }
+export function assertPendingActionsApproved(..._args: any[]): any { return gone('assertPendingActionsApproved'); }
+export function pendingConflicts(..._args: any[]): any { return gone('pendingConflicts'); }
+export function buildApplyPlan(..._args: any[]): any { return gone('buildApplyPlan'); }
+export function writePlan(..._args: any[]): any { return gone('writePlan'); }
+export function readPlan(..._args: any[]): any { return gone('readPlan'); }
+export function listPlans(..._args: any[]): any { return gone('listPlans'); }
+export function planRequiresApproval(..._args: any[]): any { return gone('planRequiresApproval'); }
+export function applyPlan(..._args: any[]): any { return gone('applyPlan'); }
+export function listLeases(..._args: any[]): any { return gone('listLeases'); }
+export function isLeaseActive(..._args: any[]): any { return gone('isLeaseActive'); }
+export function activeLease(..._args: any[]): any { return gone('activeLease'); }
+export function acquireLease(..._args: any[]): any { return gone('acquireLease'); }
+export function releaseLease(..._args: any[]): any { return gone('releaseLease'); }
+export function reconcile(..._args: any[]): any { return gone('reconcile'); }
+export function isCleanlyReconcilable(..._args: any[]): any { return gone('isCleanlyReconcilable'); }
+export function reconcileRequiresApproval(..._args: any[]): any { return gone('reconcileRequiresApproval'); }
+export function writeRemoteRef(..._args: any[]): any { return gone('writeRemoteRef'); }
+export function readRemoteRef(..._args: any[]): any { return gone('readRemoteRef'); }
+export function listRemoteRefs(..._args: any[]): any { return gone('listRemoteRefs'); }
+export function writeLocalRef(..._args: any[]): any { return gone('writeLocalRef'); }
+export function readLocalRef(..._args: any[]): any { return gone('readLocalRef'); }
+export function isBaseStale(..._args: any[]): any { return gone('isBaseStale'); }
+export function setQueueRowStatus(..._args: any[]): any { return gone('setQueueRowStatus'); }
+export function queueRowStatus(..._args: any[]): any { return gone('queueRowStatus'); }
+export function listQueueWithStatus(..._args: any[]): any { return gone('listQueueWithStatus'); }
+export function pendingQueueRows(..._args: any[]): any { return gone('pendingQueueRows'); }
+export function queueCounts(..._args: any[]): any { return gone('queueCounts'); }
+export function commitQueueRow(..._args: any[]): any { return gone('commitQueueRow'); }
+export function ignoreQueueRow(..._args: any[]): any { return gone('ignoreQueueRow'); }
+export function supersedeQueueRow(..._args: any[]): any { return gone('supersedeQueueRow'); }
+export function poisonQueueRow(..._args: any[]): any { return gone('poisonQueueRow'); }
+export function commitPendingQueue(..._args: any[]): any { return gone('commitPendingQueue'); }
+export function worldStatus(..._args: any[]): any { return gone('worldStatus'); }
+export function formatStatus(..._args: any[]): any { return gone('formatStatus'); }
+export function discoverWorldServices(..._args: any[]): any { return gone('discoverWorldServices'); }
+export function validateWorldService(..._args: any[]): any { return gone('validateWorldService'); }
+export function summarizeWorldFindings(..._args: any[]): any { return gone('summarizeWorldFindings'); }
+export function validateWorld(..._args: any[]): any { return gone('validateWorld'); }
+export function renderTwinHtml(..._args: any[]): any { return gone('renderTwinHtml'); }
+export function createVisualizerServer(..._args: any[]): any { return gone('createVisualizerServer'); }
+export function pushPending(..._args: any[]): any { return gone('pushPending'); }
+export function pushOperationOf(..._args: any[]): any { return gone('pushOperationOf'); }
+export function pushIdempotencyKeyOf(..._args: any[]): any { return gone('pushIdempotencyKeyOf'); }
+export function remoteRefs(..._args: any[]): any { return gone('remoteRefs'); }
+export function buildShadowState(..._args: any[]): any { return gone('buildShadowState'); }
+export function recordObservedDelta(..._args: any[]): any { return gone('recordObservedDelta'); }
+export function recordObservedDeltaLocked(..._args: any[]): any { return gone('recordObservedDeltaLocked'); }
+export function pollCursorPath(..._args: any[]): any { return gone('pollCursorPath'); }
+export function loadPollCursor(..._args: any[]): any { return gone('loadPollCursor'); }
+export function savePollCursor(..._args: any[]): any { return gone('savePollCursor'); }
+export function runConnectorPoll(..._args: any[]): any { return gone('runConnectorPoll'); }
+export function runConnectorSweep(..._args: any[]): any { return gone('runConnectorSweep'); }
+export function applyChangeset(..._args: any[]): any { return gone('applyChangeset'); }
+export function forkDivergence(..._args: any[]): any { return gone('forkDivergence'); }
+export function auditForkNoRealWrites(..._args: any[]): any { return gone('auditForkNoRealWrites'); }
+export function discardFork(..._args: any[]): any { return gone('discardFork'); }
+export function cherryPickActions(..._args: any[]): any { return gone('cherryPickActions'); }
+export function mergeForks(..._args: any[]): any { return gone('mergeForks'); }
+export function resetFork(..._args: any[]): any { return gone('resetFork'); }
+export function rebaseFork(..._args: any[]): any { return gone('rebaseFork'); }
+export const WRITE_INTENT_SUFFIX = '';
+export const WRITE_RESULT_SUFFIX = '';
+export class UnreconciledPushError extends Error { constructor(message = 'v1 removed: UnreconciledPushError') { super(message); this.name = 'UnreconciledPushError'; } }
+export class NonFastForwardPushError extends Error { constructor(message = 'v1 removed: NonFastForwardPushError') { super(message); this.name = 'NonFastForwardPushError'; } }
+export class UnreconciledWriteIntentError extends Error { constructor(message = 'v1 removed: UnreconciledWriteIntentError') { super(message); this.name = 'UnreconciledWriteIntentError'; } }
+export class LeaseHeldError extends Error { constructor(message = 'v1 removed: LeaseHeldError') { super(message); this.name = 'LeaseHeldError'; } }
+export type PushStatus = any;
+export type WorldPushRecord = any;
+export type SyncResource = any;
+export type PullResult = any;
+export type PushItemResult = any;
+export type PushResult = any;
+export type EgressActor = any;
+export type EgressWriteRequest = any;
+export type EgressWriteOutcome = any;
+export type EgressWriteResult = any;
+export type EgressLedgerEntry = any;
+export type ProviderCall = any;
+export type WorldApplyPlan = any;
+export type PlanReviewDecision = any;
+export type PlanReviewRecord = any;
+export type LocalActionPlan = any;
+export type ApprovedPendingActionSet = any;
+export type ActionMapper = any;
+export type ApplyResult = any;
+export type WorldApplyLease = any;
+export type ReconcilePolicy = any;
+export type FieldDecision = any;
+export type SubjectReconcile = any;
+export type ReconcilePlan = any;
+export type WorldRemoteRef = any;
+export type WorldLocalRef = any;
+export type QueueRowStatus = any;
+export type QueueStatusTransition = any;
+export type QueueRowWithStatus = any;
+export type QueueCounts = any;
+export type WorldStatus = any;
+export type WorldValidationFinding = any;
+export type WorldValidationSummary = any;
+export type WorldValidationReport = any;
+export type PushReport = any;
+export type RemoteRefsMode = any;
+export type ShadowState = any;
+export type SubjectFieldExtractor = any;
+export type DeltaObservation = any;
+export type DeltaResult = any;
+export type ConnectorObservation = any;
+export type WorldConnector = any;
+export type ConnectorPollResult = any;
+export type SweepConnector = any;
+export type ConnectorSweepResult = any;
+export type CopyResult = any;
+export type ForkAudit = any;
+export type ForkDivergence = any;
+export type SubjectDivergence = any;
+export type FieldDivergence = any;
+export type ApplyTarget = any;
+export type ApplyChangesetOutcome = any;
+export type TwinProxy = any;
+export type TwinProxyOptions = any;
+export type VendorRoute = any;

package/src/volter-home.ts

@@ -0,0 +1,11 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** The directory host-owned state lives under — rate-budget ledgers, the branch-ancestry lock and
+ *  removals, the shared blob index, World lifecycle records: `VOLTER_HOME`, else `~/.volter`. A
+ *  verification run points it at a directory of its own (scripts/isolated-home.ts), so a run
+ *  spends no other actor's allowance and deletes none of their records. Read on every call. */
+export function volterHome(): string {
+  const set = process.env.VOLTER_HOME;
+  return set !== undefined && set !== '' ? set : join(homedir(), '.volter');
+}

package/src/world-clock.ts

@@ -0,0 +1,33 @@
+// THE WORLD CLOCK — the one piece of physics every twin consults (TWIN-PROGRAMMING-MODEL P3).
+// Time is a GLOBAL fact requiring simultaneous agreement: TTL/expiry logic reads it at serve
+// time, so no seed-side workaround exists. The clock is a FILE, not a service — every twin
+// reads it per request (a tiny local read; the serve-path determinism tooth bans network
+// egress, not filesystem reads), the world runtime owns writing it, and `volter-world clock`
+// is the operator door (set / advance / show). No file, or no env → real wall-clock time,
+// exactly the pre-clock behavior; a world only has scripted time when its operator says so.
+//
+// File format: a single ISO-8601 line (a FROZEN instant). Every read returns exactly that
+// instant — deterministic by construction. Advancing time is an explicit operator act, never
+// a background drift.
+// Read through the ACTIVE WorldStore, not node:fs: the clock file is world state, and a
+// hydrated serverless namespace must carry its frozen instant with it (runtime contract R11–R14
+// — a MemoryWorldStore world that read the clock off the host filesystem would silently
+// serve the HOST's time, the exact two-services-disagreeing-about-now defect below).
+import { getActiveWorldStore } from './world-store.ts';
+
+export const WORLD_CLOCK_ENV = 'TWIN_WORLD_CLOCK_FILE';
+
+/** The world's "now": the frozen instant in the clock file when one is configured and
+ *  parseable; real wall-clock time otherwise. */
+export function worldNow(): string {
+  const file = process.env[WORLD_CLOCK_ENV];
+  if (file && getActiveWorldStore().exists(file)) {
+    const raw = (getActiveWorldStore().read(file) ?? '').trim();
+    const parsed = Date.parse(raw);
+    if (!Number.isNaN(parsed)) return new Date(parsed).toISOString();
+    // A configured-but-corrupt clock is a WORLD defect — fail loudly, never silently drift
+    // back to wall-clock (two services disagreeing about now breaks the world).
+    throw new Error(`world clock: ${file} does not contain a parseable ISO-8601 instant (got ${JSON.stringify(raw.slice(0, 40))})`);
+  }
+  return new Date().toISOString();
+}

package/src/world-env.ts

@@ -0,0 +1,18 @@
+// A WORLD'S OWN ENV VALUES, as a twin reads them. A World hands its env to every twin it runs (a spawned process, a
+// colocated host, a worker) on top of the caller's own, which only `runtime.environment.strip` keeps out. The runtime
+// names the variables the World itself sets in WORLD_ENV_NAMES_ENV; a twin that must agree with the app (a signing
+// secret the app verifies with) reads only those, so a developer's own exported secret never becomes World state.
+// Read per call: an import reads nothing, and a runtime with no `process` (a browser tab) has no World env.
+
+export const WORLD_ENV_NAMES_ENV = 'VOLTER_WORLD_ENV_NAMES';
+
+/** The value the World set for `name`; undefined when the World sets none (whatever the caller's shell holds). */
+export function worldEnvValue(name: string): string | undefined {
+  const env = typeof process === 'undefined' ? undefined : process.env;
+  const raw = env?.[WORLD_ENV_NAMES_ENV];
+  if (!raw) return undefined;
+  let names: unknown;
+  try { names = JSON.parse(raw); } catch { return undefined; }
+  const value = Array.isArray(names) && names.includes(name) ? env![name] : undefined;
+  return value ? value : undefined;
+}

package/src/world-store-sql.ts

@@ -0,0 +1,118 @@
+// SQL WORLD STORE — the WorldStore primitives over a SYNCHRONOUS SQLite handle.
+//
+// A Cloudflare Durable Object's `ctx.storage.sql` is synchronous, so the kernel's synchronous
+// store seam maps onto it directly: no hydrate-the-world-then-flush boundary, no snapshot cap, and
+// a request touches only the rows it reads. The handle is injected (`SqlExec` is the one method the
+// store calls), so this module imports nothing and stays safe in every bundle.
+//
+// Layout: `ws_files` holds one row per file (byte size, version); `ws_chunks` holds its content in
+// order. An append adds a chunk; a write replaces them. Content is split so no row nears SQLite's
+// per-row limit on the Durable Object backend (2 MB). Directories are implicit in the path set, as
+// in MemoryWorldStore, whose semantics this store matches method for method.
+//
+// Versions: `stat().mtimeMs` is the file's version, drawn from a counter persisted in the database.
+// storage.ts's append-dedupe cache lives across requests in an isolate and is validated by
+// (size, mtimeMs), so a version may never repeat for a path — not across requests, not across a
+// restarted object.
+import type { WorldStat, WorldStore } from './world-store.ts';
+
+type SqlValue = string | number | null | ArrayBuffer;
+/** The slice of a SQLite handle the store uses — Durable Objects' `SqlStorage` satisfies it. */
+export type SqlExec = { exec(query: string, ...bindings: unknown[]): { toArray(): Record<string, SqlValue>[] } };
+
+/** Characters per stored chunk: at most 4 UTF-8 bytes each, well under a 2 MB row. */
+const CHUNK = 256 * 1024;
+const encoder = new TextEncoder();
+
+/** `[low, high)` bounds selecting every path strictly under `dir`. */
+function under(dir: string): [string, string] {
+  const base = dir.endsWith('/') ? dir.slice(0, -1) : dir;
+  return [`${base}/`, `${base}0`]; // '0' is the code point after '/'
+}
+
+export class SqlWorldStore implements WorldStore {
+  private version: number;
+
+  constructor(private readonly sql: SqlExec) {
+    sql.exec('CREATE TABLE IF NOT EXISTS ws_files (path TEXT PRIMARY KEY, size INTEGER NOT NULL, version INTEGER NOT NULL, chunks INTEGER NOT NULL)');
+    sql.exec('CREATE TABLE IF NOT EXISTS ws_chunks (path TEXT NOT NULL, seq INTEGER NOT NULL, data TEXT NOT NULL, PRIMARY KEY (path, seq))');
+    this.version = Number(sql.exec('SELECT COALESCE(MAX(version), 0) AS v FROM ws_files').toArray()[0]?.v ?? 0);
+  }
+
+  private file(path: string): { size: number; version: number; chunks: number } | null {
+    const row = this.sql.exec('SELECT size, version, chunks FROM ws_files WHERE path = ?', path).toArray()[0];
+    return row ? { size: Number(row.size), version: Number(row.version), chunks: Number(row.chunks) } : null;
+  }
+
+  private put(path: string, data: string, from: number, size: number): void {
+    let seq = from;
+    for (let i = 0; i < data.length; i += CHUNK) this.sql.exec('INSERT INTO ws_chunks (path, seq, data) VALUES (?, ?, ?)', path, seq++, data.slice(i, i + CHUNK));
+    this.version += 1;
+    this.sql.exec('INSERT INTO ws_files (path, size, version, chunks) VALUES (?, ?, ?, ?) ON CONFLICT(path) DO UPDATE SET size = excluded.size, version = excluded.version, chunks = excluded.chunks', path, size, this.version, seq);
+  }
+
+  read(path: string): string | null {
+    if (!this.file(path)) return null;
+    return this.sql.exec('SELECT data FROM ws_chunks WHERE path = ? ORDER BY seq', path).toArray().map((r) => String(r.data)).join('');
+  }
+
+  readLines(path: string): string[] {
+    const content = this.read(path);
+    return content === null ? [] : content.split('\n');
+  }
+
+  append(path: string, data: string): void {
+    const existing = this.file(path);
+    this.put(path, data, existing?.chunks ?? 0, (existing?.size ?? 0) + encoder.encode(data).length);
+  }
+
+  write(path: string, data: string): void {
+    this.sql.exec('DELETE FROM ws_chunks WHERE path = ?', path);
+    this.put(path, data, 0, encoder.encode(data).length);
+  }
+
+  writeAtomic(path: string, data: string): void {
+    // One synchronous run of SQL with no await inside: no reader interleaves, and the object's
+    // output gate holds the response until the write is durable.
+    this.write(path, data);
+  }
+
+  exists(path: string): boolean {
+    if (this.file(path)) return true;
+    const [low, high] = under(path);
+    return this.sql.exec('SELECT 1 FROM ws_files WHERE path >= ? AND path < ? LIMIT 1', low, high).toArray().length > 0;
+  }
+
+  remove(path: string): void {
+    const [low, high] = under(path);
+    this.sql.exec('DELETE FROM ws_chunks WHERE path = ? OR (path >= ? AND path < ?)', path, low, high);
+    this.sql.exec('DELETE FROM ws_files WHERE path = ? OR (path >= ? AND path < ?)', path, low, high);
+  }
+
+  mkdir(_dirPath: string): void {
+    // Directories are implicit in the path set.
+  }
+
+  list(dirPath: string): string[] {
+    const [low, high] = under(dirPath);
+    const children = new Set<string>();
+    for (const row of this.sql.exec('SELECT path FROM ws_files WHERE path >= ? AND path < ?', low, high).toArray()) {
+      const rest = String(row.path).slice(low.length);
+      const slash = rest.indexOf('/');
+      children.add(slash === -1 ? rest : rest.slice(0, slash));
+    }
+    return [...children];
+  }
+
+  stat(path: string): WorldStat | null {
+    const file = this.file(path);
+    if (file) return { size: file.size, mtimeMs: file.version, isDirectory: false };
+    return this.exists(path) ? { size: 0, mtimeMs: 0, isDirectory: true } : null;
+  }
+
+  withLock<T>(_lockPath: string, fn: () => T): T {
+    // A Durable Object runs one synchronous stretch of JavaScript at a time and `fn` is synchronous,
+    // so the kernel's read-then-append critical sections are already exclusive.
+    return fn();
+  }
+}