@volter/world-core 2.0.0

package/dist/src/twin-fetch.js

@@ -0,0 +1,91 @@
+// 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.js";
+import { worldNow } from "./world-clock.js";
+/** 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) {
+    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(/\/+$/, '')}`;
+}
+export function createTwinFetchFromHandler(handler, config) {
+    const readOnly = config.readOnly ?? false;
+    return async function twinFetch(request) {
+        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() : config.manifest;
+            const storeNames = Object.keys(config.stores ?? {}).sort();
+            if (storeNames.length > 0 && manifest !== null && typeof manifest === 'object') {
+                const m = manifest;
+                const doors = m.doors !== null && typeof m.doors === 'object' ? m.doors : {};
+                // 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 = {};
+        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/dist/src/types.d.ts

@@ -0,0 +1,40 @@
+import type { z } from 'zod';
+import type { GenericWorldStateSchema, WorldServiceEventSchema } from './schemas.js';
+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/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/v1-removed.d.ts

@@ -0,0 +1,159 @@
+export declare function v1Reached(): string[];
+/** Run `fn` and learn which v1 names it reached (directly or through anything it awaited). */
+export declare function v1ReachedIn<T>(fn: () => Promise<T>): Promise<{
+    value: T;
+    reached: string[];
+}>;
+export declare function appendEventLocked(..._args: any[]): any;
+export declare function eventsLockPath(..._args: any[]): any;
+export declare function appendPushRecord(..._args: any[]): any;
+export declare function listPushLedger(..._args: any[]): any;
+export declare function latestPushByActionId(..._args: any[]): any;
+export declare function unconfirmedPushes(..._args: any[]): any;
+export declare function assertFastForward(..._args: any[]): any;
+export declare function pushTransaction(..._args: any[]): any;
+export declare function abandonPush(..._args: any[]): any;
+export declare function syncPull(..._args: any[]): any;
+export declare function syncPush(..._args: any[]): any;
+export declare function currentResources(..._args: any[]): any;
+export declare function isEgressEventType(..._args: any[]): any;
+export declare function recordWriteIntent(..._args: any[]): any;
+export declare function performExternalWrite(..._args: any[]): any;
+export declare function listUnreconciledWriteIntents(..._args: any[]): any;
+export declare function listEgressLedger(..._args: any[]): any;
+export declare function findWriteResultByExternal(..._args: any[]): any;
+export declare function transactionSetId(..._args: any[]): any;
+export declare function listPlanReviews(..._args: any[]): any;
+export declare function latestPlanReview(..._args: any[]): any;
+export declare function buildLocalActionPlan(..._args: any[]): any;
+export declare function recordPlanReview(..._args: any[]): any;
+export declare function approvedPendingActionSet(..._args: any[]): any;
+export declare function assertPendingActionsApproved(..._args: any[]): any;
+export declare function pendingConflicts(..._args: any[]): any;
+export declare function buildApplyPlan(..._args: any[]): any;
+export declare function writePlan(..._args: any[]): any;
+export declare function readPlan(..._args: any[]): any;
+export declare function listPlans(..._args: any[]): any;
+export declare function planRequiresApproval(..._args: any[]): any;
+export declare function applyPlan(..._args: any[]): any;
+export declare function listLeases(..._args: any[]): any;
+export declare function isLeaseActive(..._args: any[]): any;
+export declare function activeLease(..._args: any[]): any;
+export declare function acquireLease(..._args: any[]): any;
+export declare function releaseLease(..._args: any[]): any;
+export declare function reconcile(..._args: any[]): any;
+export declare function isCleanlyReconcilable(..._args: any[]): any;
+export declare function reconcileRequiresApproval(..._args: any[]): any;
+export declare function writeRemoteRef(..._args: any[]): any;
+export declare function readRemoteRef(..._args: any[]): any;
+export declare function listRemoteRefs(..._args: any[]): any;
+export declare function writeLocalRef(..._args: any[]): any;
+export declare function readLocalRef(..._args: any[]): any;
+export declare function isBaseStale(..._args: any[]): any;
+export declare function setQueueRowStatus(..._args: any[]): any;
+export declare function queueRowStatus(..._args: any[]): any;
+export declare function listQueueWithStatus(..._args: any[]): any;
+export declare function pendingQueueRows(..._args: any[]): any;
+export declare function queueCounts(..._args: any[]): any;
+export declare function commitQueueRow(..._args: any[]): any;
+export declare function ignoreQueueRow(..._args: any[]): any;
+export declare function supersedeQueueRow(..._args: any[]): any;
+export declare function poisonQueueRow(..._args: any[]): any;
+export declare function commitPendingQueue(..._args: any[]): any;
+export declare function worldStatus(..._args: any[]): any;
+export declare function formatStatus(..._args: any[]): any;
+export declare function discoverWorldServices(..._args: any[]): any;
+export declare function validateWorldService(..._args: any[]): any;
+export declare function summarizeWorldFindings(..._args: any[]): any;
+export declare function validateWorld(..._args: any[]): any;
+export declare function renderTwinHtml(..._args: any[]): any;
+export declare function createVisualizerServer(..._args: any[]): any;
+export declare function pushPending(..._args: any[]): any;
+export declare function pushOperationOf(..._args: any[]): any;
+export declare function pushIdempotencyKeyOf(..._args: any[]): any;
+export declare function remoteRefs(..._args: any[]): any;
+export declare function buildShadowState(..._args: any[]): any;
+export declare function recordObservedDelta(..._args: any[]): any;
+export declare function recordObservedDeltaLocked(..._args: any[]): any;
+export declare function pollCursorPath(..._args: any[]): any;
+export declare function loadPollCursor(..._args: any[]): any;
+export declare function savePollCursor(..._args: any[]): any;
+export declare function runConnectorPoll(..._args: any[]): any;
+export declare function runConnectorSweep(..._args: any[]): any;
+export declare function applyChangeset(..._args: any[]): any;
+export declare function forkDivergence(..._args: any[]): any;
+export declare function auditForkNoRealWrites(..._args: any[]): any;
+export declare function discardFork(..._args: any[]): any;
+export declare function cherryPickActions(..._args: any[]): any;
+export declare function mergeForks(..._args: any[]): any;
+export declare function resetFork(..._args: any[]): any;
+export declare function rebaseFork(..._args: any[]): any;
+export declare const WRITE_INTENT_SUFFIX = "";
+export declare const WRITE_RESULT_SUFFIX = "";
+export declare class UnreconciledPushError extends Error {
+    constructor(message?: string);
+}
+export declare class NonFastForwardPushError extends Error {
+    constructor(message?: string);
+}
+export declare class UnreconciledWriteIntentError extends Error {
+    constructor(message?: string);
+}
+export declare class LeaseHeldError extends Error {
+    constructor(message?: string);
+}
+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/dist/src/v1-removed.js

@@ -0,0 +1,124 @@
+// 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() { return (globalThis[REACHED] ??= []); }
+// …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 = () => (globalThis[SCOPE] ??= new AsyncLocalStorage());
+/** Run `fn` and learn which v1 names it reached (directly or through anything it awaited). */
+export async function v1ReachedIn(fn) {
+    const reached = [];
+    const value = await scope().run(reached, fn);
+    return { value, reached };
+}
+const gone = (name) => { 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) { return gone('appendEventLocked'); }
+export function eventsLockPath(..._args) { return gone('eventsLockPath'); }
+export function appendPushRecord(..._args) { return gone('appendPushRecord'); }
+export function listPushLedger(..._args) { return gone('listPushLedger'); }
+export function latestPushByActionId(..._args) { return gone('latestPushByActionId'); }
+export function unconfirmedPushes(..._args) { return gone('unconfirmedPushes'); }
+export function assertFastForward(..._args) { return gone('assertFastForward'); }
+export function pushTransaction(..._args) { return gone('pushTransaction'); }
+export function abandonPush(..._args) { return gone('abandonPush'); }
+export function syncPull(..._args) { return gone('syncPull'); }
+export function syncPush(..._args) { return gone('syncPush'); }
+export function currentResources(..._args) { return gone('currentResources'); }
+export function isEgressEventType(..._args) { return gone('isEgressEventType'); }
+export function recordWriteIntent(..._args) { return gone('recordWriteIntent'); }
+export function performExternalWrite(..._args) { return gone('performExternalWrite'); }
+export function listUnreconciledWriteIntents(..._args) { return gone('listUnreconciledWriteIntents'); }
+export function listEgressLedger(..._args) { return gone('listEgressLedger'); }
+export function findWriteResultByExternal(..._args) { return gone('findWriteResultByExternal'); }
+export function transactionSetId(..._args) { return gone('transactionSetId'); }
+export function listPlanReviews(..._args) { return gone('listPlanReviews'); }
+export function latestPlanReview(..._args) { return gone('latestPlanReview'); }
+export function buildLocalActionPlan(..._args) { return gone('buildLocalActionPlan'); }
+export function recordPlanReview(..._args) { return gone('recordPlanReview'); }
+export function approvedPendingActionSet(..._args) { return gone('approvedPendingActionSet'); }
+export function assertPendingActionsApproved(..._args) { return gone('assertPendingActionsApproved'); }
+export function pendingConflicts(..._args) { return gone('pendingConflicts'); }
+export function buildApplyPlan(..._args) { return gone('buildApplyPlan'); }
+export function writePlan(..._args) { return gone('writePlan'); }
+export function readPlan(..._args) { return gone('readPlan'); }
+export function listPlans(..._args) { return gone('listPlans'); }
+export function planRequiresApproval(..._args) { return gone('planRequiresApproval'); }
+export function applyPlan(..._args) { return gone('applyPlan'); }
+export function listLeases(..._args) { return gone('listLeases'); }
+export function isLeaseActive(..._args) { return gone('isLeaseActive'); }
+export function activeLease(..._args) { return gone('activeLease'); }
+export function acquireLease(..._args) { return gone('acquireLease'); }
+export function releaseLease(..._args) { return gone('releaseLease'); }
+export function reconcile(..._args) { return gone('reconcile'); }
+export function isCleanlyReconcilable(..._args) { return gone('isCleanlyReconcilable'); }
+export function reconcileRequiresApproval(..._args) { return gone('reconcileRequiresApproval'); }
+export function writeRemoteRef(..._args) { return gone('writeRemoteRef'); }
+export function readRemoteRef(..._args) { return gone('readRemoteRef'); }
+export function listRemoteRefs(..._args) { return gone('listRemoteRefs'); }
+export function writeLocalRef(..._args) { return gone('writeLocalRef'); }
+export function readLocalRef(..._args) { return gone('readLocalRef'); }
+export function isBaseStale(..._args) { return gone('isBaseStale'); }
+export function setQueueRowStatus(..._args) { return gone('setQueueRowStatus'); }
+export function queueRowStatus(..._args) { return gone('queueRowStatus'); }
+export function listQueueWithStatus(..._args) { return gone('listQueueWithStatus'); }
+export function pendingQueueRows(..._args) { return gone('pendingQueueRows'); }
+export function queueCounts(..._args) { return gone('queueCounts'); }
+export function commitQueueRow(..._args) { return gone('commitQueueRow'); }
+export function ignoreQueueRow(..._args) { return gone('ignoreQueueRow'); }
+export function supersedeQueueRow(..._args) { return gone('supersedeQueueRow'); }
+export function poisonQueueRow(..._args) { return gone('poisonQueueRow'); }
+export function commitPendingQueue(..._args) { return gone('commitPendingQueue'); }
+export function worldStatus(..._args) { return gone('worldStatus'); }
+export function formatStatus(..._args) { return gone('formatStatus'); }
+export function discoverWorldServices(..._args) { return gone('discoverWorldServices'); }
+export function validateWorldService(..._args) { return gone('validateWorldService'); }
+export function summarizeWorldFindings(..._args) { return gone('summarizeWorldFindings'); }
+export function validateWorld(..._args) { return gone('validateWorld'); }
+export function renderTwinHtml(..._args) { return gone('renderTwinHtml'); }
+export function createVisualizerServer(..._args) { return gone('createVisualizerServer'); }
+export function pushPending(..._args) { return gone('pushPending'); }
+export function pushOperationOf(..._args) { return gone('pushOperationOf'); }
+export function pushIdempotencyKeyOf(..._args) { return gone('pushIdempotencyKeyOf'); }
+export function remoteRefs(..._args) { return gone('remoteRefs'); }
+export function buildShadowState(..._args) { return gone('buildShadowState'); }
+export function recordObservedDelta(..._args) { return gone('recordObservedDelta'); }
+export function recordObservedDeltaLocked(..._args) { return gone('recordObservedDeltaLocked'); }
+export function pollCursorPath(..._args) { return gone('pollCursorPath'); }
+export function loadPollCursor(..._args) { return gone('loadPollCursor'); }
+export function savePollCursor(..._args) { return gone('savePollCursor'); }
+export function runConnectorPoll(..._args) { return gone('runConnectorPoll'); }
+export function runConnectorSweep(..._args) { return gone('runConnectorSweep'); }
+export function applyChangeset(..._args) { return gone('applyChangeset'); }
+export function forkDivergence(..._args) { return gone('forkDivergence'); }
+export function auditForkNoRealWrites(..._args) { return gone('auditForkNoRealWrites'); }
+export function discardFork(..._args) { return gone('discardFork'); }
+export function cherryPickActions(..._args) { return gone('cherryPickActions'); }
+export function mergeForks(..._args) { return gone('mergeForks'); }
+export function resetFork(..._args) { return gone('resetFork'); }
+export function rebaseFork(..._args) { 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'; }
+}

package/dist/src/volter-home.d.ts

@@ -0,0 +1,5 @@
+/** 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 declare function volterHome(): string;

package/dist/src/volter-home.js

@@ -0,0 +1,10 @@
+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() {
+    const set = process.env.VOLTER_HOME;
+    return set !== undefined && set !== '' ? set : join(homedir(), '.volter');
+}

package/dist/src/world-clock.d.ts

@@ -0,0 +1,4 @@
+export declare 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 declare function worldNow(): string;

package/dist/src/world-clock.js

@@ -0,0 +1,32 @@
+// 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.js";
+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() {
+    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/dist/src/world-env.d.ts

@@ -0,0 +1,3 @@
+export declare 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 declare function worldEnvValue(name: string): string | undefined;

package/dist/src/world-env.js

@@ -0,0 +1,22 @@
+// 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) {
+    const env = typeof process === 'undefined' ? undefined : process.env;
+    const raw = env?.[WORLD_ENV_NAMES_ENV];
+    if (!raw)
+        return undefined;
+    let names;
+    try {
+        names = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const value = Array.isArray(names) && names.includes(name) ? env[name] : undefined;
+    return value ? value : undefined;
+}

package/dist/src/world-store-sql.d.ts

@@ -0,0 +1,27 @@
+import type { WorldStat, WorldStore } from './world-store.js';
+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>[];
+    };
+};
+export declare class SqlWorldStore implements WorldStore {
+    private readonly sql;
+    private version;
+    constructor(sql: SqlExec);
+    private file;
+    private put;
+    read(path: string): string | null;
+    readLines(path: string): string[];
+    append(path: string, data: string): void;
+    write(path: string, data: string): void;
+    writeAtomic(path: string, data: string): void;
+    exists(path: string): boolean;
+    remove(path: string): void;
+    mkdir(_dirPath: string): void;
+    list(dirPath: string): string[];
+    stat(path: string): WorldStat | null;
+    withLock<T>(_lockPath: string, fn: () => T): T;
+}
+export {};

package/dist/src/world-store-sql.js

@@ -0,0 +1,86 @@
+/** 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) {
+    const base = dir.endsWith('/') ? dir.slice(0, -1) : dir;
+    return [`${base}/`, `${base}0`]; // '0' is the code point after '/'
+}
+export class SqlWorldStore {
+    sql;
+    version;
+    constructor(sql) {
+        this.sql = sql;
+        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);
+    }
+    file(path) {
+        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;
+    }
+    put(path, data, from, size) {
+        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) {
+        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) {
+        const content = this.read(path);
+        return content === null ? [] : content.split('\n');
+    }
+    append(path, data) {
+        const existing = this.file(path);
+        this.put(path, data, existing?.chunks ?? 0, (existing?.size ?? 0) + encoder.encode(data).length);
+    }
+    write(path, data) {
+        this.sql.exec('DELETE FROM ws_chunks WHERE path = ?', path);
+        this.put(path, data, 0, encoder.encode(data).length);
+    }
+    writeAtomic(path, data) {
+        // 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) {
+        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) {
+        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) {
+        // Directories are implicit in the path set.
+    }
+    list(dirPath) {
+        const [low, high] = under(dirPath);
+        const children = new Set();
+        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) {
+        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(_lockPath, fn) {
+        // 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();
+    }
+}