@volter/world-core 3.0.38 → 3.0.40

package/dist/src/history.js

@@ -1,3 +1,4 @@
+import { parseExactJson } from "./exact-json.js";
 // Immutable views over shared append-only segments. A position is meaningful within a view.
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
@@ -37,7 +38,7 @@ const viewPath = (directory, id) => {
     return join(directory, 'views', `${id}.json`);
 };
 function rows(directory, file) {
-    return getActiveWorldStore().readLines(join(directory, file)).filter(line => line.trim()).map(line => toEntry(JSON.parse(line)));
+    return getActiveWorldStore().readLines(join(directory, file)).filter(line => line.trim()).map(line => toEntry(parseExactJson(line)));
 }
 function sliceLayout(layout, at) {
     const base = layout.base ? historyLength(layout.base) : 0;
@@ -47,7 +48,7 @@ export function readHistoryView(directory, id) {
     const raw = getActiveWorldStore().read(viewPath(directory, id));
     if (raw === null)
         throw new Error(`Missing retained history view ${id}`);
-    const { dependencies: _dependencies, ...view } = JSON.parse(raw);
+    const { dependencies: _dependencies, ...view } = parseExactJson(raw);
     if (view.version !== 1 || historyDigest({ ...view, dependencies: _dependencies }) !== id)
         throw new Error(`Invalid retained history view ${id}`);
     historyLength(view.layout);
@@ -124,7 +125,7 @@ export function inheritedHistoryKey(service, root) {
     }
     if (raw === null)
         return 'missing-view';
-    const view = JSON.parse(raw);
+    const view = parseExactJson(raw);
     const directories = new Set([view.owner?.directory ?? '', ...(view.segments ?? []).map((sp) => sp.directory)]);
     if (!isUrlParent(parent.at))
         directories.add(worldPaths(service, parent.at).dir);
@@ -166,7 +167,7 @@ export function captureHistory(service, root) {
 }
 export function originHead(service, root) {
     const raw = getActiveWorldStore().read(join(worldPaths(service, root).dir, 'origin-head.json'));
-    return raw === null ? null : JSON.parse(raw);
+    return raw === null ? null : parseExactJson(raw);
 }
 /** A complete remote view shares cached rows by content, never by mutable offsets or entry ID. */
 export function publishOriginHistory(service, root, remoteView, layout, entries) {

package/dist/src/host-port.d.ts

@@ -0,0 +1,5 @@
+/** Read a Host authority with the platform URL parser; bracketed IPv6 retains its address. */
+export declare function readHostPort(authority: string): {
+    host: string;
+    port: string;
+} | undefined;

package/dist/src/host-port.js

@@ -0,0 +1,14 @@
+/** Read a Host authority with the platform URL parser; bracketed IPv6 retains its address. */
+export function readHostPort(authority) {
+    try {
+        if (!authority || /[\s/\\?#@]/.test(authority))
+            return undefined;
+        const url = new URL(`http://${authority}`);
+        if (url.username || url.password)
+            return undefined;
+        return { host: url.hostname.toLowerCase(), port: url.port };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/index.d.ts

@@ -11,6 +11,11 @@ export declare const packOf: (manifest: {
 }, surface?: DerivedSurface | Record<string, {
     manifest: DerivedManifest;
     surface: DerivedSurface;
+}>, 
+/** the lanes beside a pack that has an API of its own (Clerk's `fapi`, PlanetScale's `api`) */
+beside?: Record<string, {
+    manifest: DerivedManifest;
+    surface: DerivedSurface;
 }>) => PackDescriptor;
 /** The pack registered, so the World finds it. */
 export declare const registerPack: (pack: PackDescriptor) => PackDescriptor;
@@ -20,7 +25,7 @@ export { verifyEvent } from './events.js';
 export { deriveStateSystem, deriveVendorStateSystem } from './derived-real.js';
 export type { IngestDecl } from './derived-core.js';
 export type { SocketDecl, SocketEngine, SocketSession } from './sockets.js';
-export { machinePool, type ExecSpec, type MachinePool, type MachineProcess, type MachineRun, type MachineSpec } from './machines.js';
+export { machinePool, isMachineCapabilityGap, type ExecSpec, type MachinePool, type MachineProcess, type MachineRun, type MachineSpec, type MachineStatus, type MachineFiles, type MachineFileStat } from './machines.js';
 export type { CorsDecl } from './cors.js';
 export type { Handler, HandlerContext, WriteHookContext } from './derived-core.js';
 export type { MultipartPart } from './multipart.js';
@@ -36,18 +41,19 @@ export { VendorUnreachableError } from './vendor-call.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.js';
 export { serveHttp, serveStream, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.js';
 export type { TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.js';
+export { privateTransportKey } from './private-transport.js';
 export { siteLabel, siteUrlOf, twinSiteUrl, twinVendorUrl } from './twin-fetch.js';
 export { statefulTwinManifest, twinManifest } from './scenario.js';
 export { assetContentType, packAsset } from './pack-assets.js';
 export { bytesResponse, contentTypeOf, fileResponse } from './file-response.js';
-export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from './signing.js';
+export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, base62From, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from './signing.js';
 export type { HandlerCrypto, Jwk, Jwks, JwtVerdict, SigningKey } from './signing.js';
 export { blobDigest } from './blob-store.js';
 export { gunzip, gzip } from './bytes.js';
 export { ownFields } from './log.js';
 export type { TwinResource } from './serve.js';
 export { passwordHash, personOf, personWith, recordPerson, type Person } from './people.js';
-export { EngineDatabaseError, EngineUnavailableError, quoteIdent, worldClockSql } from './managed-database.js';
+export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from './managed-database.js';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
 export type { Mail, SmtpRoute } from './smtp.js';
 export * as s3 from './s3/wire.js';
@@ -64,5 +70,7 @@ export * as redis from './redis/index.js';
 export * as git from './git/index.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';
+export { verifyAttestationBundle } from './attestation.js';
 export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
+export { readHostPort } from './host-port.js';
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.js';

package/dist/src/index.js

@@ -8,12 +8,14 @@ import { bindSemantics as bindAny } from "./derived-core.js";
 import { packOf as packOfAny, registerPack as registerAny } from "./packRegistry.js";
 /** The descriptor a manifest declares, with its vendor ("The descriptor"); given the pack's generated surface (a vendor of
  *  lanes: each lane's manifest and surface), with the real-system adapters the kernel derives from them. */
-export const packOf = (manifest, surface) => packOfAny(manifest, surface);
+export const packOf = (manifest, surface, 
+/** the lanes beside a pack that has an API of its own (Clerk's `fapi`, PlanetScale's `api`) */
+beside) => packOfAny(manifest, surface, beside);
 /** The pack registered, so the World finds it. */
 export const registerPack = (pack) => registerAny(pack);
 export { verifyEvent } from "./events.js";
 export { deriveStateSystem, deriveVendorStateSystem } from "./derived-real.js";
-export { machinePool } from "./machines.js";
+export { machinePool, isMachineCapabilityGap } from "./machines.js";
 /** A pack's handlers, by operationId, bound to the manifest: each is answered over the contract's context. */
 export const bindSemantics = (m, handlers, scope = {}) => bindAny(m, handlers, scope);
 // ── the derived fetch ──────────────────────────────────────────────────────────────────────────
@@ -28,13 +30,14 @@ export { VendorUnreachableError } from "./vendor-call.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from "./request-scope.js";
 // ── the serve factory ──────────────────────────────────────────────────────────────────────────
 export { serveHttp, serveStream } from "./serve-http.js";
+export { privateTransportKey } from "./private-transport.js";
 // where a page links a hostname its twin answers, inside the World that shows it
 export { siteLabel, siteUrlOf, twinSiteUrl, twinVendorUrl } from "./twin-fetch.js";
 export { statefulTwinManifest, twinManifest } from "./scenario.js";
 export { assetContentType, packAsset } from "./pack-assets.js";
 export { bytesResponse, contentTypeOf, fileResponse } from "./file-response.js";
 // ── the kernel's deterministic helpers ─────────────────────────────────────────────────────────
-export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from "./signing.js";
+export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, base62From, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from "./signing.js";
 export { blobDigest } from "./blob-store.js";
 // compressed bytes a wire carries (a SARIF upload), over web streams
 export { gunzip, gzip } from "./bytes.js";
@@ -43,7 +46,7 @@ export { ownFields } from "./log.js";
 // the people a vendor's pages sign in (a `_person` row with its password's hash)
 export { passwordHash, personOf, personWith, recordPerson } from "./people.js";
 // the World's managed Postgres a handler reaches as `ctx.engine` (managed-database.ts), and a mail's route (`ctx.mail`)
-export { EngineDatabaseError, EngineUnavailableError, quoteIdent, worldClockSql } from "./managed-database.js";
+export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from "./managed-database.js";
 // S3's wire (contract "S3's wire is a kernel library too") and the git plane (contract "The git plane is a kernel library")
 export * as s3 from "./s3/wire.js";
 export * as clickhouse from "./clickhouse/index.js";
@@ -59,5 +62,7 @@ export * as redis from "./redis/index.js";
 export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";
+export { verifyAttestationBundle } from "./attestation.js";
 export { browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
+export { readHostPort } from "./host-port.js";
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost } from "./browser-state.js";

package/dist/src/log.js

@@ -1,3 +1,4 @@
+import { parseExactJson } from "./exact-json.js";
 // THE LOG (docs/concepts/the-model.md). One kind of entry, one log per
 // branch, and a branch is a parent plus a position in the parent's log:
 //
@@ -45,7 +46,7 @@ function parseLines(path, lines, offset, out) {
         if (!line.trim())
             continue;
         try {
-            out.push(JSON.parse(line));
+            out.push(parseExactJson(line));
         }
         catch (error) {
             throw new Error(`${path}:${offset + i + 1}: invalid JSONL row: ${error.message}`);
@@ -115,7 +116,7 @@ export function readBranchMeta(service, root) {
     const raw = getActiveWorldStore().read(branchMetaPath(service, root));
     if (raw === null)
         return null;
-    const meta = JSON.parse(raw);
+    const meta = parseExactJson(raw);
     // a pointer written before positions were one number: the parent's whole log is parent then branch
     if (meta.parent && meta.parent.at === undefined && meta.parent.root !== undefined)
         meta.parent = { at: meta.parent.root, position: (meta.parent.parentCount ?? 0) + (meta.parent.branchCount ?? 0) };
@@ -274,7 +275,7 @@ export function landedIds(parent) {
 export function aliasesFrom(parent) {
     const vendorHeld = new Set();
     for (const e of parent)
-        if (e.batch !== undefined || e.operation === 'observed' || e.event !== undefined || e.landsId !== undefined)
+        if (e.batch !== undefined || e.operation === 'observed' || e.event !== undefined || (e.landsId !== undefined && e.receipt?.status === 'deployed'))
             vendorHeld.add(`${e.subject.type}:${e.subject.id}`);
     const out = new Map();
     for (const e of parent) {
@@ -355,7 +356,7 @@ export function treeResources(tree) {
         for (const [k, v] of Object.entries(s.fields)) {
             if (!META.has(k))
                 out[k] = v;
-            else if (v !== undefined && v !== out[k])
+            else if (v !== undefined)
                 own[k] = v;
         }
         if (Object.keys(own).length)
@@ -376,7 +377,11 @@ export function ownFields(r) {
     const { id: _id, type: _type, updatedAt: _at, ...rest } = r;
     const own = (r[OWN] ?? {});
     // restored first: a vendor's object leads with its id, and a reader's grep may count on the order
-    return { ...(own.id !== undefined ? { id: own.id } : {}), ...(own.type !== undefined ? { type: own.type } : {}), ...rest, ...(own.updatedAt !== undefined ? { updatedAt: own.updatedAt } : {}) };
+    const out = { ...(own.id !== undefined ? { id: own.id } : {}), ...(own.type !== undefined ? { type: own.type } : {}), ...rest, ...(own.updatedAt !== undefined ? { updatedAt: own.updatedAt } : {}) };
+    // the own record rides along unseen, so an own view taken of an own view is the same view (never one that drops them)
+    if (r[OWN] !== undefined)
+        Object.defineProperty(out, OWN, { value: own, enumerable: false });
+    return out;
 }
 export function dropCheckpoint(service, root) { getActiveWorldStore().remove(checkpointPath(service, root)); }
 /** Preserve each ancestor's observed-then-local overlay, including landed IDs and aliases. */
@@ -579,7 +584,7 @@ function readTreeMapFull(service, root, opts = {}) {
         const facts = opts.until === undefined ? `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}` : null;
         if (facts !== null) {
             const held = getActiveWorldStore().read(checkpointPath(service, root));
-            const cut = held === null ? null : JSON.parse(held);
+            const cut = held === null ? null : parseExactJson(held);
             if (cut?.facts === facts)
                 return new Map(cut.subjects.map(s => [`${s.type}:${s.id}`, { ...s, fields: { ...s.fields } }]));
         }
@@ -593,7 +598,7 @@ function readTreeMapFull(service, root, opts = {}) {
         const parentDigest = hashFieldValue({ inherited, own });
         const branchDigest = hashFieldValue(branch);
         const raw = opts.until === undefined ? getActiveWorldStore().read(checkpointPath(service, root)) : null;
-        const cp = raw === null ? null : JSON.parse(raw);
+        const cp = raw === null ? null : parseExactJson(raw);
         if (cp?.parentDigest === parentDigest && cp.branchDigest === branchDigest)
             return new Map(cp.subjects.map(s => [`${s.type}:${s.id}`, { ...s, fields: { ...s.fields } }]));
         const layout = { ...(inherited ? { base: inherited.layout } : {}), parent: own.length, branch: branch.length };

package/dist/src/machines.d.ts

@@ -4,13 +4,61 @@ export type MachineSpec = {
     env?: Record<string, string>;
     ports?: number[];
     command?: string[];
+    checks?: Array<{
+        port: number;
+        type: 'http' | 'tcp';
+        path?: string;
+    }>;
+    resetOnStop?: boolean;
+    mounts?: Array<{
+        name: string;
+        path: string;
+    }>;
+    signal?: AbortSignal;
+    startTimeoutMs?: number;
+};
+export type GuestImage = {
+    context: string;
+    dockerfile?: string;
+    runtime?: 'node' | 'bun' | 'python' | 'deno';
+    command?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    prepared?: boolean;
+};
+export type LightPoolOptions = {
+    images?: Record<string, GuestImage>;
 };
 export type MachineRun = {
     ports: Array<{
         internal: number;
         host: number;
+        url?: string;
     }>;
 };
+export type MachineStatus = {
+    state: 'started' | 'paused' | 'stopped' | 'exited' | 'failed';
+    exitCode?: number;
+    reason?: string;
+};
+export type MachineFileStat = {
+    type: 'file' | 'directory';
+    size: number;
+    mode: number;
+    mtime: string;
+};
+export type MachineFiles = {
+    read(path: string): Promise<Uint8Array>;
+    write(path: string, bytes: Uint8Array): Promise<unknown>;
+    list(path: string): Promise<Array<{
+        name: string;
+        type: 'file' | 'directory';
+        size: number;
+    }>>;
+    mkdir(path: string): Promise<unknown>;
+    remove(path: string): Promise<unknown>;
+    stat(path: string): Promise<MachineFileStat>;
+};
 /** A process started in a machine: its pid, and what it writes and how it ends, as they happen. */
 export type MachineProcess = {
     pid: number;
@@ -27,24 +75,52 @@ export type ExecSpec = {
     env?: Record<string, string>;
     cwd?: string;
 };
+export type MachineHttpReply = {
+    port: number;
+    method: string;
+    path: string;
+    requestText?: string;
+    status: number;
+    headers?: Record<string, string>;
+    body?: string;
+};
 export type MachinePool = {
-    readonly kind: 'docker' | 'none' | 'fake';
+    readonly kind: 'docker' | 'none' | 'fake' | 'light';
+    /** Optional capability admission, before vendor resource creation; starts no process. */
+    admitRun?(spec: MachineSpec): Promise<void>;
     /** runs the image; a failure (no container runtime, an image that will not start) rejects with the runtime's message */
     run(spec: MachineSpec): Promise<MachineRun>;
     /** starts a process in a running machine; a machine the pool does not run rejects */
     exec(name: string, spec: ExecSpec): Promise<MachineProcess>;
+    request(name: string, port: number, request: Request): Promise<Response>;
+    /** Undefined means the metadata-only/fake backing has no process lifecycle to observe. */
+    status(name: string): Promise<MachineStatus | undefined>;
+    ports(name: string): Promise<number[]>;
+    files(name: string): Promise<MachineFiles>;
+    pause(name: string): Promise<void>;
+    resume(name: string): Promise<void>;
     stop(name: string): Promise<void>;
     remove(name: string): Promise<void>;
     /** the fake pool's record of what it was asked */
     readonly asked?: Array<{
-        act: 'run' | 'exec' | 'stop' | 'remove';
+        act: 'run' | 'exec' | 'request' | 'pause' | 'resume' | 'stop' | 'remove';
         name: string;
         spec?: MachineSpec;
         exec?: ExecSpec;
+        port?: number;
+        path?: string;
+        requestText?: string;
     }>;
 };
+/** A declared compute capability gap, distinct from a failed admitted guest. */
+export declare function isMachineCapabilityGap(error: unknown): boolean;
 export declare const MACHINE_POOL = "_machine_pool";
-export declare const POOL_KINDS: readonly ["docker", "none", "fake"];
+export declare const POOL_KINDS: readonly ["docker", "none", "fake", "light"];
 /** The pool of a kind, for a World (`world`: the mark its containers carry). */
-export declare function machinePool(kind: MachinePool['kind'], world?: string): MachinePool;
-export declare function poolFor(service: string, root: string | undefined, kind: MachinePool['kind']): MachinePool;
+export declare function machinePool(kind: MachinePool['kind'], world?: string, httpReplies?: readonly MachineHttpReply[], light?: LightPoolOptions, root?: string): MachinePool;
+export declare function poolFor(service: string, root: string | undefined, kind: MachinePool['kind'], httpReplies?: readonly MachineHttpReply[], light?: LightPoolOptions): MachinePool;
+/** Re-enrolling a verification pool starts a fresh fake execution record. */
+export declare function resetFakePool(service: string, root: string | undefined): void;
+/** Every machine mutation shares the tree's refusal seam. HTTP/RPC reads must be explicitly
+ * classified by the pack; a computed operation may execute arbitrary guest code. */
+export declare function guardedMachinePool(pool: MachinePool, service: string, safeRead: boolean): MachinePool;

package/dist/src/machines.js

@@ -1,12 +1,51 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 // The World's machine pool (architecture, "Other wires: … machines"): what runs a vendor's customer's image when the
 // vendor is one that runs images (Fly's Machines). It is a platform provider enrolled through the kernel's door
 // `POST /_twin/machine-pool`, recorded in the pack's own tree; a handler reaches it as `ctx.machines`. `docker` runs
 // each machine as a local container with its internal ports published on loopback; `none` runs nothing; `fake`
 // records what it was asked (capability verification). Nothing here runs at module scope, and `node:child_process`
-// is reached only when a docker pool is asked to act.
+// is reached only when a compute pool is asked to act. The light pool delegates to the host's Substrate adapter.
+import { refuseReadOnlyWrite } from "./request-scope.js";
 import { nodeBuiltin } from "./serve-http.js";
+/** A declared compute capability gap, distinct from a failed admitted guest. */
+export function isMachineCapabilityGap(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'WORLD_MACHINE_CAPABILITY_GAP';
+}
 export const MACHINE_POOL = '_machine_pool';
-export const POOL_KINDS = ['docker', 'none', 'fake'];
+export const POOL_KINDS = ['docker', 'none', 'fake', 'light'];
+/** The host owns provider bootstrapping. Browser/kernel imports stay inert, and a missing
+ * host provider refuses rather than falling back to metadata-only success. */
+function lightPool(world, root, options) {
+    let ready;
+    const load = () => ready ??= (async () => {
+        const entry = typeof process === 'undefined' ? undefined : process.env.VOLTER_WORLD_GUEST_RUNNER;
+        if (!entry)
+            throw new Error('light guest runner is unavailable: run this twin inside a World');
+        const provider = await import(__rewriteRelativeImportExtension(entry));
+        return provider.createLightGuestPool({ world, root, ...options });
+    })();
+    return {
+        kind: 'light',
+        admitRun: async (spec) => { await (await load()).admitRun?.(spec); },
+        run: async (spec) => (await load()).run(spec),
+        exec: async (name, spec) => (await load()).exec(name, spec),
+        request: async (name, port, request) => (await load()).request(name, port, request),
+        status: async (name) => (await load()).status(name),
+        ports: async (name) => (await load()).ports(name),
+        files: async (name) => (await load()).files(name),
+        pause: async (name) => (await load()).pause(name),
+        resume: async (name) => (await load()).resume(name),
+        stop: async (name) => (await load()).stop(name),
+        remove: async (name) => (await load()).remove(name),
+    };
+}
 /** A container's name for a machine: the World's prefix, the World's own mark (a machine id repeats across Worlds and
  *  branches, which mint alike), then the vendor's machine name made safe for docker. */
 const containerName = (world, name) => `volter-world-machine-${world}-${name.replace(/[^A-Za-z0-9_.-]/g, '-')}`;
@@ -21,6 +60,12 @@ function dockerPool(world) {
     });
     return {
         kind: 'docker',
+        async status(name) {
+            const state = JSON.parse(await docker(['inspect', '--format', '{{json .State}}', containerName(world, name)]));
+            return state.Running ? { state: 'started' } : { state: 'exited', exitCode: state.ExitCode, ...(state.Error ? { reason: state.Error } : {}) };
+        },
+        async ports() { throw new Error('port discovery requires the light guest backing'); },
+        async files() { throw new Error('file access requires the light guest backing'); },
         async run(spec) {
             const name = containerName(world, spec.name);
             await docker(['rm', '-f', name]).catch(() => undefined);
@@ -105,47 +150,118 @@ function dockerPool(world) {
                 clearTimeout(timer);
             }
         },
+        async request(name, port, request) {
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                throw new Error('invalid machine port');
+            const line = (await docker(['port', containerName(world, name), String(port)])).split('\n')[0] ?? '';
+            const host = Number(line.split(':').at(-1));
+            if (!Number.isInteger(host) || host < 1 || host > 65535 || !line.startsWith('127.0.0.1:'))
+                throw new Error('the machine port is not published on loopback');
+            const source = new URL(request.url);
+            const headers = new Headers(request.headers);
+            for (const key of ['host', 'connection', 'content-length', 'transfer-encoding'])
+                headers.delete(key);
+            const body = ['GET', 'HEAD'].includes(request.method) ? undefined : await request.clone().arrayBuffer();
+            return fetch(`http://127.0.0.1:${host}${source.pathname}${source.search}`, { method: request.method, headers, body, redirect: 'manual', signal: request.signal });
+        },
+        async pause(name) { await docker(['pause', containerName(world, name)]); },
+        async resume(name) { await docker(['unpause', containerName(world, name)]); },
         async stop(name) { await docker(['stop', containerName(world, name)]).catch(() => undefined); },
         async remove(name) { await docker(['rm', '-f', containerName(world, name)]).catch(() => undefined); },
     };
 }
 /** The pool of a kind, for a World (`world`: the mark its containers carry). */
-export function machinePool(kind, world = 'world') {
+export function machinePool(kind, world = 'world', httpReplies = [], light = {}, root) {
+    if (kind === 'light')
+        return lightPool(world, root, light);
     if (kind === 'docker')
         return dockerPool(world);
     if (kind === 'fake') {
         const asked = [];
+        const running = new Map();
         return {
             kind, asked,
-            async run(spec) { asked.push({ act: 'run', name: spec.name, spec }); return { ports: (spec.ports ?? []).map((internal) => ({ internal, host: 40_000 + internal })) }; },
+            async status() { return undefined; },
+            async ports(name) { return running.get(name)?.ports ?? []; },
+            async files() { throw new Error('the fake pool has no filesystem'); },
+            async run(spec) { running.set(spec.name, { ports: spec.ports ?? [], paused: false }); asked.push({ act: 'run', name: spec.name, spec }); return { ports: (spec.ports ?? []).map((internal) => ({ internal, host: 40_000 + internal })) }; },
             async exec(name, spec) {
+                if (!running.has(name) || running.get(name).paused)
+                    throw new Error('the fake machine is not running');
                 asked.push({ act: 'exec', name, exec: spec });
                 // a fake process: its pid the count of processes asked, and it ends at once
                 const pid = asked.filter((a) => a.act === 'exec').length + 100;
                 return { pid, events: (async function* () { yield { exit: 0 }; })() };
             },
-            async stop(name) { asked.push({ act: 'stop', name }); },
-            async remove(name) { asked.push({ act: 'remove', name }); },
+            async request(name, port, request) {
+                const machine = running.get(name);
+                if (!machine || machine.paused || !machine.ports.includes(port))
+                    throw new Error('the fake machine port is not running');
+                const url = new URL(request.url), path = url.pathname + url.search;
+                const requestText = ['GET', 'HEAD'].includes(request.method) ? '' : await request.clone().text();
+                asked.push({ act: 'request', name, port, path, requestText });
+                const reply = httpReplies.find((r) => r.port === port && r.method === request.method && r.path === path && (r.requestText === undefined || r.requestText === requestText));
+                if (!reply)
+                    throw new Error('no fake HTTP reply matches');
+                return new Response(reply.body ?? null, { status: reply.status, headers: reply.headers });
+            },
+            async pause(name) { if (!running.has(name))
+                throw new Error('no fake machine'); running.get(name).paused = true; asked.push({ act: 'pause', name }); },
+            async resume(name) { if (!running.has(name))
+                throw new Error('no fake machine'); running.get(name).paused = false; asked.push({ act: 'resume', name }); },
+            async stop(name) { running.delete(name); asked.push({ act: 'stop', name }); },
+            async remove(name) { running.delete(name); asked.push({ act: 'remove', name }); },
         };
     }
     return {
         kind: 'none', async run() { return { ports: [] }; },
+        async status() { return undefined; },
+        async ports() { throw new Error('no guest ports'); },
+        async files() { throw new Error('no guest files'); },
         async exec() { throw new Error('no machine runs in this World: its machine pool is none'); },
+        async request() { throw new Error('no machine runs in this World: its machine pool is none'); },
+        async pause() { },
+        async resume() { },
         async stop() { }, async remove() { },
     };
 }
 /** A vendor's pool in a World, one per World and kind for the life of the process (a fake pool keeps what it was asked). */
 const pools = new Map();
-export function poolFor(service, root, kind) {
-    const key = `${service}\0${root ?? ''}\0${kind}`;
+export function poolFor(service, root, kind, httpReplies = [], light = {}) {
+    const key = `${service}\0${root ?? ''}\0${kind}${kind === 'light' ? JSON.stringify(light) : ''}`;
     let pool = pools.get(key);
     if (!pool) {
         // the World's mark: a short digest of the vendor and the World's tree, so two Worlds' machines never share a name
         let h = 0;
         for (const ch of `${service}:${root ?? ''}`)
             h = (Math.imul(h, 31) + ch.charCodeAt(0)) >>> 0;
-        pool = machinePool(kind, h.toString(16).padStart(8, '0'));
+        pool = machinePool(kind, h.toString(16).padStart(8, '0'), httpReplies, light, root);
         pools.set(key, pool);
     }
     return pool;
 }
+/** Re-enrolling a verification pool starts a fresh fake execution record. */
+export function resetFakePool(service, root) { pools.delete(`${service}\0${root ?? ''}\0fake`); }
+/** Every machine mutation shares the tree's refusal seam. HTTP/RPC reads must be explicitly
+ * classified by the pack; a computed operation may execute arbitrary guest code. */
+export function guardedMachinePool(pool, service, safeRead) {
+    const guard = () => refuseReadOnlyWrite(service);
+    return {
+        kind: pool.kind, asked: pool.asked,
+        ...(pool.admitRun ? { admitRun: (spec) => { guard(); return pool.admitRun(spec); } } : {}),
+        run: (spec) => { guard(); return pool.run(spec); },
+        exec: (name, spec) => { guard(); return pool.exec(name, spec); },
+        request: (name, port, request) => { if (!safeRead)
+            guard(); return pool.request(name, port, request); },
+        status: (name) => pool.status(name),
+        ports: (name) => pool.ports(name),
+        files: async (name) => {
+            const files = await pool.files(name);
+            return { ...files, write: (path, bytes) => { guard(); return files.write(path, bytes); }, mkdir: (path) => { guard(); return files.mkdir(path); }, remove: (path) => { guard(); return files.remove(path); } };
+        },
+        pause: (name) => { guard(); return pool.pause(name); },
+        resume: (name) => { guard(); return pool.resume(name); },
+        stop: (name) => { guard(); return pool.stop(name); },
+        remove: (name) => { guard(); return pool.remove(name); },
+    };
+}

package/dist/src/managed-database.d.ts

@@ -37,19 +37,14 @@ export type Batch = {
 export interface ManagedDatabase {
     /** Whether the World binds a database at all (a World with none refuses every batch). */
     readonly bound: boolean;
+    /** The URL the World binds it at, what an application connects to (a credential door's database URL); none when
+     *  unbound. */
+    readonly url?: string;
     /** One transaction as one pipeline and one Sync; the answer is the batch's own statements', in order. */
     batch(batch: Batch): Promise<StatementResult[]>;
     /** A whole SQL script as one simple Query (a vendor's migrations, several statements to a file). */
     script(text: string): Promise<void>;
 }
-/** The transaction-local setting every batch a handler makes carries: the World clock at the call (ctx.occurredAt). */
-export declare const WORLD_CLOCK_SETTING = "volter.world_clock";
-/** The World clock inside the database, for the schemas a vendor lays (its migrations stamp rows with Postgres's
- *  `now()`, which reads the wall clock): `volter.now()`, the World clock the batch set or the wall clock where none is
- *  set, and every column default in `schemas` that reads `now()` or `CURRENT_TIMESTAMP` (alone or inside an expression,
- *  GoTrue's `timezone('utc', now())`) rewritten to read it. Run after the schemas are laid; running it again changes
- *  nothing. A trigger or function that calls `now()` itself is the pack's to redefine. */
-export declare function worldClockSql(schemas: string[]): string;
 /** Quote an identifier the way Postgres's quote_ident does for a name that needs it. */
 export declare function quoteIdent(name: string): string;
 /** The part of a Postgres driver the kernel uses: node-postgres's (`pg`) Pool and its clients. */
@@ -73,12 +68,21 @@ export type DatabaseDriver = {
 /** A Postgres driver a host registers in place of node-postgres. */
 export declare function useDatabaseDriver(given: DatabaseDriver): void;
 /** The World's Postgres at `url` (the runtime's binding, never the environment); with `readOnly`, every transaction is
- *  READ ONLY whatever the batch asks (a read-only twin or request: Postgres itself refuses a write, 25006); with `clock`,
- *  every batch carries the World clock as `volter.world_clock`. */
+ *  READ ONLY whatever the batch asks (a read-only twin or request: Postgres itself refuses a write, 25006). */
 export declare function managedDatabase(url: string, options?: {
     readOnly?: boolean;
-    clock?: string;
 }): ManagedDatabase;
+/** One connection of an application's own to the World's Postgres (a journey's SQL steps: twin-standard
+ *  walk/journey-kit.ts), its statements sent as its client sends them: a text alone as one simple Query (a migration
+ *  file, a `BEGIN`), a text with values as one extended-protocol statement, the values bind parameters. A transaction it
+ *  opens stays open across its statements until it ends it, as on the application's own connection. Each statement's
+ *  answer is its results in Postgres's text format, untyped. */
+export type DatabaseSession = {
+    query(text: string, values?: ReadonlyArray<string | null>): Promise<StatementResult[]>;
+    end(): Promise<void>;
+};
+/** The World's Postgres at `url` as one connection held until `end()`. */
+export declare function databaseSession(url: string): Promise<DatabaseSession>;
 /** A handler's database when the World binds none: every use is the refusal naming what to add. */
 export declare function unboundDatabase(service: string): ManagedDatabase;
 /** Close every connection this process holds (a test's teardown; a served twin's connections end with it). */