@volter/world-runtime 2.0.0

package/dist/src/command-lifetime.d.ts

@@ -0,0 +1,15 @@
+import type { ChildProcess } from 'node:child_process';
+export declare const COMMAND_GRACE_MS = 5000;
+export declare const commandProcessGroup: boolean;
+export declare class CommandRetirementError extends Error {
+}
+/** The child owns a private POSIX group. A bounded retirement requires both closed output and
+ * a vanished group. Unknown retirement keeps the caller's ownership record and reservation. */
+export declare function commandLifetime(child: ChildProcess, abort?: AbortSignal, preserveOnSuccess?: boolean): {
+    cancel: (value: NodeJS.Signals) => void;
+    readonly forwarded: NodeJS.Signals | undefined;
+    finish(): Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+};

package/dist/src/command-lifetime.js

@@ -0,0 +1,98 @@
+import { offSignal } from "./signals.js";
+import { survivingOwnedGroups } from "./process-groups.js";
+export const COMMAND_GRACE_MS = 5_000;
+export const commandProcessGroup = process.platform !== 'win32';
+export class CommandRetirementError extends Error {
+}
+/** The child owns a private POSIX group. A bounded retirement requires both closed output and
+ * a vanished group. Unknown retirement keeps the caller's ownership record and reservation. */
+export function commandLifetime(child, abort, preserveOnSuccess = false) {
+    let forwarded;
+    let code = null;
+    let exitSignal = null;
+    let exited = false;
+    let closed = false;
+    let deadline = 0;
+    let escalated = false;
+    let timer;
+    let resolveFinished;
+    let rejectFinished;
+    const finished = new Promise((resolve, reject) => { resolveFinished = resolve; rejectFinished = reject; });
+    finished.catch(() => { });
+    const signal = (value) => {
+        if (!child.pid)
+            return;
+        try {
+            if (commandProcessGroup)
+                process.kill(-child.pid, value);
+            else
+                child.kill(value);
+        }
+        catch { /* retirement is proved below, never inferred from signal delivery */ }
+    };
+    const alive = () => {
+        if (!child.pid)
+            return false;
+        return survivingOwnedGroups([child.pid]).length > 0;
+    };
+    const detach = () => {
+        if (timer)
+            clearInterval(timer);
+        offSignal('SIGINT', onInt);
+        offSignal('SIGTERM', onTerm);
+        abort?.removeEventListener('abort', onAbort);
+    };
+    const check = () => {
+        if (exited && closed && ((preserveOnSuccess && code === 0 && !forwarded) || !alive())) {
+            detach();
+            resolveFinished();
+            return;
+        }
+        if (deadline && Date.now() >= deadline) {
+            if (!escalated) {
+                escalated = true;
+                signal('SIGKILL');
+                deadline = Date.now() + 1_000;
+            }
+            else {
+                detach();
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                rejectFinished(new CommandRetirementError('Command retirement could not be confirmed; ownership and cleanup evidence retained'));
+            }
+        }
+    };
+    const watch = () => {
+        if (!deadline)
+            deadline = Date.now() + COMMAND_GRACE_MS;
+        timer ??= setInterval(check, 20);
+        check();
+    };
+    const cancel = (value) => { forwarded ??= value; signal(value); watch(); };
+    const onInt = () => cancel('SIGINT');
+    const onTerm = () => cancel('SIGTERM');
+    const onAbort = () => cancel(abort?.reason === 'SIGINT' ? 'SIGINT' : 'SIGTERM');
+    process.on('SIGINT', onInt);
+    process.on('SIGTERM', onTerm);
+    abort?.addEventListener('abort', onAbort, { once: true });
+    if (abort?.aborted)
+        onAbort();
+    child.once('exit', (value, signalValue) => {
+        code = value;
+        exitSignal = signalValue;
+        exited = true;
+        if (!(preserveOnSuccess && code === 0 && !forwarded))
+            signal('SIGTERM');
+        watch();
+    });
+    child.once('error', () => { if (!child.pid) {
+        exited = true;
+        watch();
+    } });
+    child.once('close', () => { closed = true; check(); });
+    return {
+        cancel,
+        get forwarded() { return forwarded; },
+        async finish() { await finished; return { code, signal: exitSignal }; },
+    };
+}

package/dist/src/configs.d.ts

@@ -0,0 +1,18 @@
+import { type WorldConfig } from './schema.js';
+export declare function resolveConfigPath(config: string, root?: string): string;
+export declare function loadWorldConfig(config: string, root?: string): {
+    path: string;
+    config: WorldConfig;
+};
+/** Persist an already-normalized config without changing its document format. */
+export declare function writeWorldConfig(path: string, config: WorldConfig): void;
+export type WorldConfigMigration = {
+    path: string;
+    backup: string;
+    from: 1;
+    to: 2;
+    moved: string[];
+    dropped: string[];
+};
+/** Explicit, backed-up, atomic format-1 → format-2 migration. Ordinary reads never call this. */
+export declare function migrateWorldConfig(config: string, root?: string): WorldConfigMigration;

package/dist/src/configs.js

@@ -0,0 +1,119 @@
+import { copyFileSync, constants, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { getActiveWorldStore } from '@volter/world-core';
+import { assertWorldConfig, LEGACY_WORLD_SELECTION, worldConfigDocument } from "./schema.js";
+export function resolveConfigPath(config, root = process.cwd()) {
+    const candidates = config.includes('/') || config.endsWith('.json')
+        ? [resolve(root, config)]
+        : [
+            resolve(root, 'worlds/configs', `${config}.json`),
+            resolve(root, 'worlds/configs', config, 'world.config.json'),
+            resolve(root, `${config}.world.config.json`),
+        ];
+    const found = candidates.find((candidate) => getActiveWorldStore().exists(candidate));
+    if (!found) {
+        throw new Error(`World config not found: ${config}\nTried:\n${candidates.map((candidate) => `  ${candidate}`).join('\n')}`);
+    }
+    return found;
+}
+export function loadWorldConfig(config, root = process.cwd()) {
+    const path = resolveConfigPath(config, root);
+    const parsed = JSON.parse(getActiveWorldStore().read(path) ?? '');
+    return { path, config: assertWorldConfig(parsed, path) };
+}
+/** Persist an already-normalized config without changing its document format. */
+export function writeWorldConfig(path, config) {
+    const document = config.manifestVersion === 2
+        ? worldConfigDocument(config)
+        : Object.fromEntries(Object.entries(config).filter(([key]) => key !== 'manifestVersion' && key !== 'selection'));
+    getActiveWorldStore().write(path, `${JSON.stringify(document, null, 2)}\n`);
+}
+const LEGACY_TOP_LEVEL = new Set(['id', 'description', 'bare', 'remotes', 'resources', 'isolation', 'env', 'stripEnv', 'services', 'share', 'actors', 'fixtures', 'catalog', 'network']);
+const LEGACY_SERVICE = new Set(['id', 'type', 'package', 'command', 'args', 'cwd', 'port', 'portReason', 'env', 'controlPlane', 'injectEnv', 'injectEnvTemplates', 'root', 'rootArg', 'portArg', 'cliRedirect', 'ready', 'preload', 'external', 'colocate', 'version']);
+const LEGACY_NESTED = {
+    bare: new Set(['name']), resources: new Set(['memoryMiB', 'writableStorageMiB']), catalog: new Set(['sha', 'protocol']),
+    root: new Set(['url', 'deploy', 'refresh', 'scope']), refresh: new Set(['every', 'webhook']),
+    external: new Set(['up', 'status', 'down', 'discover', 'readyWhen']), discover: new Set(['as', 'source', 'jsonPath', 'pattern']),
+    ready: new Set(['command', 'args', 'httpUrl', 'stdoutMatch', 'timeoutMs', 'intervalMs']), colocate: new Set(['module', 'export', 'scenarioPath']),
+    share: new Set(['provider', 'command', 'args', 'ephemeral', 'services']), shareService: new Set(['id', 'verifyPath']),
+};
+function unknownKeys(value, known, allowComments = false) {
+    return Object.keys(value).filter((key) => !known.has(key) && !(allowComments && key.startsWith('//')));
+}
+function rejectUnknown(value, known, what, path) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return;
+    const unknown = unknownKeys(value, known);
+    if (unknown.length)
+        throw new Error(`Cannot migrate unknown ${what} field(s) ${unknown.join(', ')} in ${path}`);
+}
+/** Explicit, backed-up, atomic format-1 → format-2 migration. Ordinary reads never call this. */
+export function migrateWorldConfig(config, root = process.cwd()) {
+    const path = resolveConfigPath(config, root);
+    const text = readFileSync(path, 'utf8');
+    const raw = JSON.parse(text);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error(`World config must be an object: ${path}`);
+    if ('schemaVersion' in raw)
+        throw new Error(`World config is already versioned; migration only accepts legacy format 1: ${path}`);
+    const topUnknown = unknownKeys(raw, LEGACY_TOP_LEVEL, true);
+    if (topUnknown.length)
+        throw new Error(`Cannot migrate unknown legacy field(s) ${topUnknown.join(', ')} in ${path}`);
+    const legacy = raw;
+    rejectUnknown(legacy.bare, LEGACY_NESTED.bare, 'bare', path);
+    rejectUnknown(legacy.resources, LEGACY_NESTED.resources, 'resources', path);
+    rejectUnknown(legacy.catalog, LEGACY_NESTED.catalog, 'catalog', path);
+    rejectUnknown(legacy.share, LEGACY_NESTED.share, 'share', path);
+    if (legacy.share && typeof legacy.share === 'object' && !Array.isArray(legacy.share)) {
+        const targets = legacy.share.services;
+        if (Array.isArray(targets))
+            for (const target of targets)
+                rejectUnknown(target, LEGACY_NESTED.shareService, 'share service', path);
+    }
+    const rawServices = raw.services;
+    if (Array.isArray(rawServices))
+        for (const service of rawServices) {
+            if (!service || typeof service !== 'object' || Array.isArray(service))
+                continue;
+            const legacyService = service;
+            const serviceUnknown = unknownKeys(legacyService, LEGACY_SERVICE, true);
+            if (serviceUnknown.length)
+                throw new Error(`Cannot migrate unknown service field(s) ${serviceUnknown.join(', ')} in ${path}`);
+            rejectUnknown(legacyService.root, LEGACY_NESTED.root, 'service root', path);
+            if (legacyService.root && typeof legacyService.root === 'object' && !Array.isArray(legacyService.root))
+                rejectUnknown(legacyService.root.refresh, LEGACY_NESTED.refresh, 'service root.refresh', path);
+            rejectUnknown(legacyService.external, LEGACY_NESTED.external, 'service external', path);
+            if (legacyService.external && typeof legacyService.external === 'object' && !Array.isArray(legacyService.external)) {
+                const external = legacyService.external;
+                if (Array.isArray(external.discover))
+                    for (const mapping of external.discover)
+                        rejectUnknown(mapping, LEGACY_NESTED.discover, 'service external.discover', path);
+                rejectUnknown(external.readyWhen, LEGACY_NESTED.ready, 'service external.readyWhen', path);
+            }
+            rejectUnknown(legacyService.ready, LEGACY_NESTED.ready, 'service ready', path);
+            rejectUnknown(legacyService.colocate, LEGACY_NESTED.colocate, 'service colocate', path);
+        }
+    const normalized = assertWorldConfig(raw, path);
+    const document = worldConfigDocument(normalized, LEGACY_WORLD_SELECTION);
+    const backup = `${path}.v1.bak`;
+    copyFileSync(path, backup, constants.COPYFILE_EXCL);
+    const temporary = resolve(dirname(path), `.${basename(path)}.migrate-${process.pid}`);
+    try {
+        writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { flag: 'wx' });
+        assertWorldConfig(JSON.parse(readFileSync(temporary, 'utf8')), temporary);
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        try {
+            if (existsSync(temporary))
+                renameSync(temporary, `${temporary}.failed`);
+        }
+        catch { /* retain primary error */ }
+        throw error;
+    }
+    return {
+        path, backup, from: 1, to: 2,
+        moved: ['id→metadata.id', 'description→metadata.description', 'env/stripEnv→runtime.environment', 'isolation→runtime.isolation', 'bare/share→serving', 'actors/fixtures→scenario', 'catalog→provenance.catalog', 'service fields→typed service sections'],
+        dropped: normalized.resources === undefined ? [] : ['resources (deprecated; retained in backup)'],
+    };
+}

package/dist/src/console-apart.d.ts

@@ -0,0 +1,38 @@
+import { type HttpServer } from '@volter/world-core';
+/** What a console offers a host: its shell and assets under `base`, told where the Worlds are served. */
+export type ConsoleMount = {
+    handle: (request: Request, base: string, opts?: {
+        worlds?: string;
+        names?: string[];
+    }) => Promise<Response | null>;
+};
+export declare const CONSOLE_BASE = "/-/console";
+/** Serve `mount` on its own listener; doors under `/-/` go to `upstream` (the Worlds' origin). */
+/** `upstream`: where this listener reaches the host's doors (its own address); `worlds`: the origin the
+ *  person's browser reaches the Worlds at (an advertised URL), else `upstream`. */
+export declare function serveConsoleApart(mount: ConsoleMount, opts: {
+    upstream: string;
+    worlds?: string;
+    names?: string[];
+    hostname: string;
+    port?: number;
+}): Promise<{
+    url: string;
+    server: HttpServer;
+}>;
+/** The console for a World served elsewhere (a hosted World), on this machine. Two local listeners, as
+ *  `volter world serve` has: the console on one origin, its doors forwarded to the host; and the Worlds'
+ *  origin on the next port, forwarding everything (a twin's mirror, the session door) to the host, so
+ *  the console and the pages twins serve are same-site as they are locally, and still two origins. A
+ *  host keeps its tenants' names to itself, so the World is named by the URL: `<origin>/<org>/<world>`. */
+export declare function serveConsoleFor(target: string, opts?: {
+    hostname?: string;
+    port?: number;
+}): Promise<{
+    url: string;
+    worlds: string;
+    servers: HttpServer[];
+}>;
+/** The host's old console address (`/-/console/…`, a bookmark or a portal's link) sent on to the console's
+ *  own listener, path kept; the browser carries any `#token=` fragment across the redirect. */
+export declare function consoleRedirect(request: Request, consoleOrigin: string | null): Response | null;

package/dist/src/console-apart.js

@@ -0,0 +1,107 @@
+// THE CONSOLE ON AN ORIGIN OF ITS OWN. The console keeps the token a person types in its tab's
+// storage; the Worlds' origin serves what twins serve (a mirror bundle, a tunnel's visitor pages,
+// an app's own HTML), and a script there could read any storage of that origin. So a host serves the
+// console on a listener of its own: the console's shell and bundle, and the host's `/-/` doors
+// forwarded to the host — never a twin's path, so no twin-served script ever runs on this origin.
+// The console opens a World's pages (a twin's mirror) on the Worlds' origin, which it is told.
+import { serveHttp } from '@volter/world-core';
+export const CONSOLE_BASE = '/-/console';
+/** Serve `mount` on its own listener; doors under `/-/` go to `upstream` (the Worlds' origin). */
+/** `upstream`: where this listener reaches the host's doors (its own address); `worlds`: the origin the
+ *  person's browser reaches the Worlds at (an advertised URL), else `upstream`. */
+export async function serveConsoleApart(mount, opts) {
+    const upstream = opts.upstream.replace(/\/+$/, '');
+    const worlds = (opts.worlds ?? upstream).replace(/\/+$/, '');
+    const server = await serveHttp({
+        hostname: opts.hostname, port: opts.port ?? 0, twinRequestJournal: false,
+        async fetch(request) {
+            const url = new URL(request.url);
+            if (url.pathname === '/' || url.pathname === CONSOLE_BASE)
+                return Response.redirect(`${url.origin}${CONSOLE_BASE}/`, 302);
+            const answered = await mount.handle(request, CONSOLE_BASE, { worlds, ...(opts.names?.length ? { names: opts.names } : {}) });
+            if (answered)
+                return answered;
+            if (!url.pathname.startsWith('/-/') || url.pathname.startsWith(`${CONSOLE_BASE}/`))
+                return Response.json({ error: 'the console serves the console and the host\'s doors only' }, { status: 404 });
+            // a door, forwarded: the caller's token header rides along; no cookie goes up (this origin holds
+            // none) and none comes back (a World's session belongs to the Worlds' origin, set there)
+            const headers = new Headers(request.headers);
+            for (const h of ['host', 'cookie', 'origin', 'referer'])
+                headers.delete(h);
+            const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
+            const answer = await fetch(`${upstream}${url.pathname}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' });
+            const out = new Headers(answer.headers);
+            out.delete('set-cookie');
+            out.delete('content-encoding');
+            out.delete('content-length');
+            return new Response(answer.body, { status: answer.status, headers: out });
+        },
+    });
+    return { url: `http://${opts.hostname === '0.0.0.0' ? '127.0.0.1' : opts.hostname}:${server.port}`, server };
+}
+/** The console for a World served elsewhere (a hosted World), on this machine. Two local listeners, as
+ *  `volter world serve` has: the console on one origin, its doors forwarded to the host; and the Worlds'
+ *  origin on the next port, forwarding everything (a twin's mirror, the session door) to the host, so
+ *  the console and the pages twins serve are same-site as they are locally, and still two origins. A
+ *  host keeps its tenants' names to itself, so the World is named by the URL: `<origin>/<org>/<world>`. */
+export async function serveConsoleFor(target, opts = {}) {
+    let at;
+    try {
+        at = new URL(target);
+    }
+    catch {
+        throw new Error(`volter world console: ${target} is not a URL (https://<host>/<org>/<world>)`);
+    }
+    if (at.protocol !== 'https:' && at.protocol !== 'http:')
+        throw new Error(`volter world console: ${target} is not an http(s) URL`);
+    const origin = at.origin;
+    const segments = at.pathname.split('/').filter((s) => s !== '');
+    const names = segments.length >= 2 ? [`${segments[0]}/${segments[1]}`] : [];
+    let mount;
+    try {
+        mount = (await import('@volter/world-console')).createConsole();
+    }
+    catch (error) {
+        if (error instanceof Error && /Cannot find (module|package)/.test(error.message))
+            throw new Error('the console is not installed: add @volter/world-console beside @volter/world');
+        throw error;
+    }
+    const hostname = opts.hostname ?? '127.0.0.1';
+    const worldsServer = await serveHttp({
+        hostname, port: opts.port !== undefined && opts.port !== 0 ? opts.port + 1 : 0, twinRequestJournal: false,
+        async fetch(request) {
+            const url = new URL(request.url);
+            const headers = new Headers(request.headers);
+            for (const h of ['host', 'origin', 'referer'])
+                headers.delete(h);
+            const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
+            const answer = await fetch(`${origin}${url.pathname}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' });
+            const out = new Headers();
+            for (const [k, v] of answer.headers)
+                if (!['content-encoding', 'content-length', 'set-cookie'].includes(k))
+                    out.append(k, v);
+            // the World session's cookie, kept on this plain-http loopback origin (a Secure cookie is https-only)
+            for (const c of answer.headers.getSetCookie())
+                out.append('set-cookie', c.replace(/;\s*Secure/i, ''));
+            // the host's own redirects (the session door's, a twin root's to its mirror) stay on this origin
+            const location = out.get('location');
+            if (location?.startsWith(origin))
+                out.set('location', `${url.origin}${location.slice(origin.length)}`);
+            return new Response(answer.body, { status: answer.status, headers: out });
+        },
+    });
+    const worlds = `http://${hostname}:${worldsServer.port}`;
+    const consoleServer = await serveConsoleApart(mount, { upstream: origin, worlds, names, hostname, ...(opts.port !== undefined ? { port: opts.port } : {}) });
+    return { url: consoleServer.url, worlds, servers: [consoleServer.server, worldsServer] };
+}
+/** The host's old console address (`/-/console/…`, a bookmark or a portal's link) sent on to the console's
+ *  own listener, path kept; the browser carries any `#token=` fragment across the redirect. */
+export function consoleRedirect(request, consoleOrigin) {
+    const url = new URL(request.url);
+    if (!consoleOrigin || (url.pathname !== CONSOLE_BASE && !url.pathname.startsWith(`${CONSOLE_BASE}/`)))
+        return null;
+    // a console named at this very origin (a misconfigured --console-url) would redirect to itself forever
+    if (new URL(consoleOrigin).origin === url.origin)
+        return null;
+    return Response.redirect(`${consoleOrigin.replace(/\/+$/, '')}${url.pathname}${url.search}`, 302);
+}

package/dist/src/consumers.d.ts

@@ -0,0 +1,46 @@
+export type WorldConsumer = {
+    id: string;
+    instanceCreatedAt: string;
+    kind: 'attach' | 'run';
+    owner?: string;
+    uid?: number;
+    hostname: string;
+    runnerPid: number;
+    consumerPid?: number;
+    retirementUncertain?: boolean;
+    /** Published before spawn; only confirmed completion removes this command's record. */
+    completionRequired?: boolean;
+    startedAt: string;
+    heartbeatAt: string;
+};
+export declare const CONSUMER_HEARTBEAT_MS = 5000;
+export declare function checkedOwner(owner: string | undefined): string | undefined;
+/** Called under the World's lifecycle lock, before starting the command. No argv or env is stored. */
+export declare function createConsumer(root: string, name: string, instanceCreatedAt: string, kind: WorldConsumer['kind'], owner?: string, options?: {
+    completionRequired?: boolean;
+}): WorldConsumer;
+export declare function refreshConsumer(root: string, name: string, record: WorldConsumer): void;
+export declare function releaseConsumer(root: string, name: string, record: WorldConsumer): void;
+/** Inspection never deletes records or interprets incomplete coverage as no consumers. */
+export declare function worldConsumers(root: string, name: string, instanceCreatedAt?: string): {
+    consumers: (WorldConsumer & {
+        state: "active" | "uncertain" | "exited";
+    })[];
+    warnings: string[];
+};
+/** Delete one consumer record. Only `retireWorldConsumers` calls it, under the World's lifecycle
+ *  lock, after proving the command and its process group are gone. */
+export declare function removeConsumerRecord(root: string, name: string, id: string): void;
+/** Host-clock observations, not the world's simulated vendor clock or proof of idleness. */
+export declare function worldUsage(root: string, name: string, attached?: {
+    consumers: (WorldConsumer & {
+        state: "active" | "uncertain" | "exited";
+    })[];
+    warnings: string[];
+}): {
+    createdAt: string | null;
+    lastUsedAt: string;
+    lastUseSource: "run" | "attach";
+    coverage: "partial";
+    warnings: string[];
+};

package/dist/src/consumers.js

@@ -0,0 +1,200 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { stateDirName, withFileLock } from '@volter/world-core';
+export const CONSUMER_HEARTBEAT_MS = 5000;
+const STALE_MS = 30_000;
+export function checkedOwner(owner) {
+    if (owner !== undefined && (!owner.trim() || owner.length > 120 || /[\x00-\x1f\x7f]/.test(owner))) {
+        throw new Error('World owner must be a nonempty label of at most 120 characters, without control characters');
+    }
+    return owner;
+}
+function consumerDir(root, name) {
+    return join(root, stateDirName(), 'worlds', name, 'consumers');
+}
+function writeAtomic(path, value) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx' });
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+/** Called under the World's lifecycle lock, before starting the command. No argv or env is stored. */
+export function createConsumer(root, name, instanceCreatedAt, kind, owner, options = {}) {
+    const now = new Date().toISOString();
+    const record = {
+        id: randomUUID(), instanceCreatedAt, kind, owner: checkedOwner(owner),
+        ...(process.getuid ? { uid: process.getuid() } : {}),
+        hostname: hostname(), runnerPid: process.pid, startedAt: now, heartbeatAt: now,
+        ...(options.completionRequired ? { completionRequired: true } : {}),
+    };
+    const dir = consumerDir(root, name);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeAtomic(join(dir, `${record.id}.json`), record);
+    return record;
+}
+export function refreshConsumer(root, name, record) {
+    const dir = consumerDir(root, name);
+    const path = join(dir, `${record.id}.json`);
+    if (!existsSync(path))
+        return; // teardown may already have removed this generation
+    const instance = JSON.parse(readFileSync(join(dir, '..', 'instance.json'), 'utf8'));
+    if (instance.createdAt !== record.instanceCreatedAt)
+        return;
+    const next = { ...record, heartbeatAt: new Date().toISOString() };
+    writeAtomic(path, next);
+}
+export function releaseConsumer(root, name, record) {
+    const dir = consumerDir(root, name);
+    try {
+        if (record.consumerPid && existsSync(join(dir, `${record.id}.json`))) {
+            const path = join(dir, '..', 'last-use.json');
+            withFileLock(`${path}.lock`, () => {
+                const instance = JSON.parse(readFileSync(join(dir, '..', 'instance.json'), 'utf8'));
+                if (instance.createdAt !== record.instanceCreatedAt)
+                    return;
+                // Timestamp inside the lock: two commands finishing together cannot overwrite a
+                // newer observation with a timestamp captured before waiting for this lock.
+                let at = new Date().toISOString();
+                try {
+                    const previous = JSON.parse(readFileSync(path, 'utf8'));
+                    if (previous.instanceCreatedAt === record.instanceCreatedAt && previous.source === 'attach'
+                        && typeof previous.at === 'string' && Date.parse(previous.at) > Date.parse(at))
+                        at = previous.at;
+                }
+                catch { /* missing/corrupt advisory data can be replaced by a known observation */ }
+                writeAtomic(path, { instanceCreatedAt: record.instanceCreatedAt, at, source: 'attach' });
+            });
+        }
+    }
+    catch {
+        // Activity is advisory; a telemetry failure must not replace the command's exit status.
+        console.warn(`[volter-world] WARNING: could not retain last observed command use for ${name}; usage metadata may be incomplete.`);
+    }
+    finally {
+        rmSync(join(dir, `${record.id}.json`), { force: true });
+    }
+}
+function alive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+/** Inspection never deletes records or interprets incomplete coverage as no consumers. */
+export function worldConsumers(root, name, instanceCreatedAt) {
+    const consumers = [];
+    const warnings = [];
+    const dir = consumerDir(root, name);
+    if (!existsSync(dir))
+        return { consumers, warnings };
+    if (instanceCreatedAt === undefined) {
+        try {
+            instanceCreatedAt = JSON.parse(readFileSync(join(dir, '..', 'instance.json'), 'utf8')).createdAt;
+        }
+        catch {
+            warnings.push('World instance unreadable; consumer ownership is uncertain.');
+        }
+    }
+    let files;
+    try {
+        files = readdirSync(dir).sort();
+    }
+    catch {
+        return { consumers, warnings: [...warnings, 'Consumer directory unreadable; consumer coverage is incomplete.'] };
+    }
+    for (const file of files) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const r = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+            if (!r || !/^[a-f0-9-]{36}$/.test(r.id) || file !== `${r.id}.json`
+                || !['attach', 'run'].includes(r.kind) || typeof r.hostname !== 'string'
+                || !Number.isInteger(r.runnerPid) || r.runnerPid <= 0
+                || (r.consumerPid !== undefined && (!Number.isInteger(r.consumerPid) || r.consumerPid <= 0))
+                || (r.retirementUncertain !== undefined && typeof r.retirementUncertain !== 'boolean')
+                || (r.completionRequired !== undefined && typeof r.completionRequired !== 'boolean')
+                || (r.uid !== undefined && (!Number.isSafeInteger(r.uid) || r.uid < 0))
+                || !Number.isFinite(Date.parse(r.instanceCreatedAt)) || !Number.isFinite(Date.parse(r.startedAt))
+                || !Number.isFinite(Date.parse(r.heartbeatAt)))
+                throw new Error('invalid');
+            checkedOwner(r.owner);
+            const age = Date.now() - Date.parse(r.heartbeatAt);
+            const sameInstance = instanceCreatedAt === r.instanceCreatedAt;
+            const state = r.retirementUncertain || r.hostname !== hostname() || !sameInstance ? 'uncertain'
+                : !alive(r.runnerPid) && r.consumerPid === undefined ? 'uncertain'
+                    : !alive(r.runnerPid) && !alive(r.consumerPid) ? (r.completionRequired ? 'uncertain' : 'exited')
+                        : alive(r.runnerPid) && age >= -STALE_MS && age <= STALE_MS ? 'active' : 'uncertain';
+            // Explicit fields only: malformed records must never leak arbitrary metadata into reports.
+            consumers.push({ id: r.id, instanceCreatedAt: r.instanceCreatedAt, kind: r.kind, owner: r.owner,
+                uid: r.uid, hostname: r.hostname, runnerPid: r.runnerPid, consumerPid: r.consumerPid,
+                ...(r.retirementUncertain ? { retirementUncertain: true } : {}),
+                ...(r.completionRequired ? { completionRequired: true } : {}),
+                startedAt: r.startedAt, heartbeatAt: r.heartbeatAt, state });
+        }
+        catch {
+            warnings.push('Unreadable consumer record; consumer coverage is incomplete.');
+        }
+    }
+    return { consumers, warnings };
+}
+/** Delete one consumer record. Only `retireWorldConsumers` calls it, under the World's lifecycle
+ *  lock, after proving the command and its process group are gone. */
+export function removeConsumerRecord(root, name, id) {
+    if (!/^[a-f0-9-]{36}$/.test(id))
+        throw new Error('Invalid consumer id');
+    rmSync(join(consumerDir(root, name), `${id}.json`), { force: true });
+}
+/** Host-clock observations, not the world's simulated vendor clock or proof of idleness. */
+export function worldUsage(root, name, attached = worldConsumers(root, name)) {
+    const warnings = [...attached.warnings];
+    let createdAt = null;
+    const observations = [];
+    const add = (at, source) => {
+        if (typeof at === 'string' && Number.isFinite(Date.parse(at)))
+            observations.push({ at, source });
+    };
+    const dir = join(consumerDir(root, name), '..');
+    try {
+        const instance = JSON.parse(readFileSync(join(dir, 'instance.json'), 'utf8'));
+        if (typeof instance.createdAt !== 'string' || !Number.isFinite(Date.parse(instance.createdAt)))
+            throw new Error('invalid');
+        createdAt = instance.createdAt;
+        const runPath = join(dir, 'foreground-run.json');
+        const run = existsSync(runPath) ? JSON.parse(readFileSync(runPath, 'utf8')) : instance.lastRun;
+        if (run && ((Number.isInteger(run.consumerPid) && run.consumerPid > 0)
+            || (run.state === 'completed' && !run.error))) {
+            add(run.startedAt, 'run');
+            if (run.state === 'completed')
+                add(run.finishedAt, 'run');
+        }
+        const path = join(dir, 'last-use.json');
+        if (existsSync(path)) {
+            const last = JSON.parse(readFileSync(path, 'utf8'));
+            if (last.instanceCreatedAt !== createdAt || last.source !== 'attach'
+                || typeof last.at !== 'string' || !Number.isFinite(Date.parse(last.at)))
+                throw new Error('invalid');
+            add(last.at, 'attach');
+        }
+    }
+    catch {
+        warnings.push('Usage metadata unreadable; last observed use may be incomplete.');
+    }
+    for (const consumer of attached.consumers) {
+        if (consumer.instanceCreatedAt === createdAt && consumer.consumerPid)
+            add(consumer.heartbeatAt, 'attach');
+    }
+    observations.sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+    return { createdAt, lastUsedAt: observations[0]?.at ?? null, lastUseSource: observations[0]?.source ?? null,
+        coverage: 'partial', warnings };
+}