@volter/world-runtime 2.0.0

package/dist/src/inject-map.d.ts

@@ -0,0 +1,34 @@
+/** The slice of `@volter/world-core/inject` reused here (data + pure functions only). */
+export type InjectModule = {
+    readMap(env: Record<string, string | undefined>): Record<string, string>;
+    /** `pathname` is optional; it only disambiguates hosts two vendors share (see inject.cjs). */
+    resolveTwin(host: string, map: Record<string, string>, pathname?: string): {
+        vendor: string;
+        origin: string;
+    } | null;
+    /** `S3_TWIN_URL` → 's3'; a `*_TWIN_URL` name readMap would never read → null. */
+    twinUrlVendor(name: string): string | null;
+    /** the headers a request routed to the application carries: the host and scheme it was made with */
+    appForwardHeaders(url: URL): Record<string, string>;
+    VENDOR_HOSTS: Record<string, (host: string, pathname?: string) => boolean>;
+    restore(): void;
+};
+/** Lazily load the injector's host→twin table. Loading the CJS auto-installs its http/fetch
+ * patches as a side effect; we immediately `restore()` so requiring it here is inert (we only
+ * want the data + pure functions, not to patch THIS process). */
+export declare function loadInject(): InjectModule;
+/** The vendor keys the injector can redirect for (the keys of VENDOR_HOSTS). */
+export declare function injectableVendorKeys(): Set<string>;
+/** Does the injector actually read this env var name? (`S3_TWIN_URL` → 's3'; `AWS_TWIN_URL`
+ * → null — the consolidated aws twin answers under the s3/dynamodb/timestream keys.) */
+export declare function twinUrlVendorFor(name: string): string | null;
+/** WARN lines for twin-shaped injectEnv vars the injector will never read — an injectEnv like
+ * `AWS_TWIN_URL` is written into the world env, looks wired, and does NOTHING (readMap iterates
+ * VENDOR_HOSTS keys looking for `<VENDOR>_TWIN_URL`; there is no `aws` vendor key). `up` prints
+ * these loudly so the disagreement is visible at boot instead of surfacing as silently-real
+ * vendor traffic later. Vars that do not end in `_TWIN_URL` are app-read config (SUPABASE_URL,
+ * LIVEKIT_URL, …), not injector input — never warned about. */
+export declare function inertInjectEnvWarnings(services: Array<{
+    id: string;
+    injectEnv?: string;
+}>): string[];

package/dist/src/inject-map.js

@@ -0,0 +1,56 @@
+// The ONE world-runtime home for the injector's host→twin knowledge (`@volter/world-core/inject`:
+// `VENDOR_HOSTS` + `readMap` + `resolveTwin` + `twinUrlVendor`). The redirect proxy, `covers`,
+// and `up`'s inert-injectEnv warning all read the injector THROUGH this module, so none of them
+// can re-encode (and silently drift from) what the injector actually redirects — the exact
+// failure mode of the LibreChat blind-adoption run, where a world injected AWS_TWIN_URL that no
+// injector vendor reads and nothing said so.
+import { createRequire } from 'node:module';
+let injectCache = null;
+/** Lazily load the injector's host→twin table. Loading the CJS auto-installs its http/fetch
+ * patches as a side effect; we immediately `restore()` so requiring it here is inert (we only
+ * want the data + pure functions, not to patch THIS process). */
+export function loadInject() {
+    if (injectCache)
+        return injectCache;
+    const require = createRequire(import.meta.url);
+    const mod = require('@volter/world-core/inject');
+    try {
+        mod.restore();
+    }
+    catch { /* nothing was installed */ }
+    injectCache = mod;
+    return mod;
+}
+/** The vendor keys the injector can redirect for (the keys of VENDOR_HOSTS). */
+export function injectableVendorKeys() {
+    return new Set(Object.keys(loadInject().VENDOR_HOSTS));
+}
+/** Does the injector actually read this env var name? (`S3_TWIN_URL` → 's3'; `AWS_TWIN_URL`
+ * → null — the consolidated aws twin answers under the s3/dynamodb/timestream keys.) */
+export function twinUrlVendorFor(name) {
+    return loadInject().twinUrlVendor(name);
+}
+/** WARN lines for twin-shaped injectEnv vars the injector will never read — an injectEnv like
+ * `AWS_TWIN_URL` is written into the world env, looks wired, and does NOTHING (readMap iterates
+ * VENDOR_HOSTS keys looking for `<VENDOR>_TWIN_URL`; there is no `aws` vendor key). `up` prints
+ * these loudly so the disagreement is visible at boot instead of surfacing as silently-real
+ * vendor traffic later. Vars that do not end in `_TWIN_URL` are app-read config (SUPABASE_URL,
+ * LIVEKIT_URL, …), not injector input — never warned about. */
+export function inertInjectEnvWarnings(services) {
+    const warnings = [];
+    for (const service of services) {
+        const name = service.injectEnv;
+        if (!name || !/_TWIN_URL$/.test(name))
+            continue;
+        if (twinUrlVendorFor(name) !== null)
+            continue;
+        const stem = name.replace(/_TWIN_URL$/, '');
+        const hint = stem.toUpperCase() === 'AWS'
+            ? ' The consolidated aws twin is read under its per-AREA keys — S3_TWIN_URL / DYNAMODB_TWIN_URL / TIMESTREAM_TWIN_URL / SESV2_TWIN_URL / SECRETSMANAGER_TWIN_URL / BEDROCK_TWIN_URL — point those at the aws twin instead.'
+            : '';
+        warnings.push(`[volter-world] WARN: service "${service.id}" injects ${name}, but the injector reads no such vendor` +
+            ` ("${stem.toLowerCase()}" is not a VENDOR_HOSTS key in @volter/world-core/inject) — the var is INERT and this` +
+            ` vendor's SDK traffic will NOT be redirected to the twin.${hint}`);
+    }
+    return warnings;
+}

package/dist/src/lifecycle-record.d.ts

@@ -0,0 +1,47 @@
+export type WorldLifecycleRecord = {
+    version: 1;
+    world: string;
+    root: string;
+    identity: string;
+    instanceCreatedAt: string;
+    owner?: string;
+    ownerUid?: number;
+    ownerPid: number;
+    hostname: string;
+    startedAt: string;
+    phase: 'starting' | 'running' | 'cleanup-pending';
+    pids: number[];
+    log: string;
+};
+export declare const lifecycleLogPath: (root: string, world: string) => string;
+/** Called under the instance lock, before replacing data. Only this identity is read. */
+export declare function assertLifecycleStartable(root: string, world: string): void;
+/** A missing process is not successful teardown; records persist until explicit release. */
+export declare function beginWorldLifecycle(root: string, world: string, instanceCreatedAt: string, owner?: string): void;
+export declare function handoffWorldLifecycle(root: string, world: string, pids: number[]): void;
+export declare function retainWorldLifecycleForCleanup(root: string, world: string): void;
+export declare function recordWorldLifecycleEvent(root: string, world: string, message: string): void;
+/** Called only after verified cleanup. Never touches legacy records. */
+export declare function releaseWorldLifecycle(root: string, world: string): void;
+/**
+ * Releases the record of a World whose instance metadata is gone when nothing it
+ * recorded can still run: the record is this host's and this user's, and its owner
+ * and every process it handed off have exited. There is nothing left to tear down,
+ * so the record is the only thing left to release. Anything alive, another host's,
+ * another user's, or unreadable keeps the record. Returns whether it released.
+ */
+export declare function releaseAbandonedWorldLifecycle(root: string, world: string): boolean;
+export declare function hasWorldLifecycle(root: string, world: string): boolean;
+export declare function inspectWorldLifecycles(): {
+    worlds: WorldLifecycleRecord[];
+    legacyRecords: {
+        path: string;
+        world?: string;
+        root?: string;
+        cleanupPending?: boolean;
+        readable: boolean;
+    }[];
+    warnings: string[];
+};
+/** Runtime phase is meaningful only for the same instance generation; it is not a health probe. */
+export declare function isWorldLifecycleRunning(root: string, world: string, instanceCreatedAt: string): boolean;

package/dist/src/lifecycle-record.js

@@ -0,0 +1,196 @@
+// Durable ownership of one World. This inventory does not allocate or reserve capacity.
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { volterHome } from '@volter/world-core';
+import { hostname } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { stateDirName, withFileLock } from '@volter/world-core';
+import { checkedOwner } from "./consumers.js";
+const directory = () => join(volterHome(), 'world-lifecycles');
+const identity = (root, world) => createHash('sha256').update(`${resolve(root)}\0${world}`).digest('hex');
+const recordPath = (root, world) => join(directory(), `${identity(root, world)}.json`);
+const legacyPath = (root, world) => join(volterHome(), 'world-resource-claims', `${identity(root, world)}.json`);
+export const lifecycleLogPath = (root, world) => join(resolve(root), stateDirName(), 'worlds', '.lifecycle', `${world}.log`);
+function read(path) {
+    const record = JSON.parse(readFileSync(path, 'utf8'));
+    if (record?.version !== 1 || typeof record.world !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(record.world)
+        || typeof record.root !== 'string' || !record.root || record.identity !== identity(record.root, record.world)
+        || !Number.isFinite(Date.parse(record.instanceCreatedAt)) || !Number.isFinite(Date.parse(record.startedAt))
+        || !Number.isInteger(record.ownerPid) || record.ownerPid <= 0 || typeof record.hostname !== 'string'
+        || !['starting', 'running', 'cleanup-pending'].includes(record.phase) || !Array.isArray(record.pids)
+        || record.pids.some(pid => !Number.isInteger(pid) || pid <= 0)
+        || record.log !== lifecycleLogPath(record.root, record.world))
+        throw new Error('invalid lifecycle record');
+    checkedOwner(record.owner);
+    return record;
+}
+function write(path, record) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/** Called under the instance lock, before replacing data. Only this identity is read. */
+export function assertLifecycleStartable(root, world) {
+    if (existsSync(legacyPath(root, world)))
+        throw new Error(`World "${world}" has a legacy ownership record; finish teardown using its pinned old runtime before migration. Record retained: ${legacyPath(root, world)}`);
+    if (existsSync(recordPath(root, world)))
+        throw new Error(`World "${world}" still owns a lifecycle record; complete volter-world down before replacing it. Record retained: ${recordPath(root, world)}`);
+}
+/** A missing process is not successful teardown; records persist until explicit release. */
+export function beginWorldLifecycle(root, world, instanceCreatedAt, owner) {
+    checkedOwner(owner);
+    assertLifecycleStartable(root, world);
+    const record = {
+        version: 1, world, root: resolve(root), identity: identity(root, world), instanceCreatedAt,
+        owner, ownerUid: process.getuid?.(), ownerPid: process.pid, hostname: hostname(),
+        startedAt: new Date().toISOString(), phase: 'starting', pids: [], log: lifecycleLogPath(root, world),
+    };
+    recordWorldLifecycleEvent(root, world, 'recording startup ownership; no capacity reserved');
+    write(recordPath(root, world), record);
+}
+function update(root, world, change) {
+    const path = recordPath(root, world);
+    withFileLock(`${path}.lock`, () => {
+        if (!existsSync(path))
+            throw new Error(`World "${world}" lifecycle record is missing; ownership update refused`);
+        const record = read(path);
+        if (record.identity !== identity(root, world))
+            throw new Error('World lifecycle identity mismatch');
+        write(path, change(record));
+    });
+}
+export function handoffWorldLifecycle(root, world, pids) {
+    update(root, world, record => ({ ...record, phase: 'running', pids: [...new Set(pids.filter(pid => pid > 0))] }));
+}
+export function retainWorldLifecycleForCleanup(root, world) {
+    if (existsSync(legacyPath(root, world)))
+        throw new Error(`World "${world}" has legacy ownership; use its pinned runtime for teardown`);
+    if (!existsSync(recordPath(root, world)))
+        return;
+    update(root, world, record => ({ ...record, phase: 'cleanup-pending' }));
+}
+export function recordWorldLifecycleEvent(root, world, message) {
+    const path = lifecycleLogPath(root, world);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${new Date().toISOString()} ${message}\n`, { flag: 'a', mode: 0o600 });
+}
+/** Called only after verified cleanup. Never touches legacy records. */
+export function releaseWorldLifecycle(root, world) {
+    const path = recordPath(root, world);
+    if (!existsSync(path))
+        return;
+    withFileLock(`${path}.lock`, () => {
+        if (!existsSync(path))
+            return;
+        const record = read(path);
+        if (record.identity !== identity(root, world))
+            throw new Error('World lifecycle identity mismatch');
+        // The receipt line is evidence, not a precondition: failing to append it must not keep ownership (and so the next
+        // `up`) blocked after a verified teardown.
+        try {
+            recordWorldLifecycleEvent(root, world, 'teardown verified; ownership released');
+        }
+        catch { /* released regardless */ }
+        rmSync(path);
+    });
+}
+/**
+ * Releases the record of a World whose instance metadata is gone when nothing it
+ * recorded can still run: the record is this host's and this user's, and its owner
+ * and every process it handed off have exited. There is nothing left to tear down,
+ * so the record is the only thing left to release. Anything alive, another host's,
+ * another user's, or unreadable keeps the record. Returns whether it released.
+ */
+export function releaseAbandonedWorldLifecycle(root, world) {
+    const path = recordPath(root, world);
+    if (!existsSync(path))
+        return false;
+    return withFileLock(`${path}.lock`, () => {
+        if (!existsSync(path))
+            return false;
+        let record;
+        try {
+            record = read(path);
+        }
+        catch {
+            return false;
+        }
+        if (record.identity !== identity(root, world) || record.hostname !== hostname())
+            return false;
+        if (record.ownerUid !== undefined && record.ownerUid !== process.getuid?.())
+            return false;
+        if ([record.ownerPid, ...record.pids].some((pid) => processExists(pid)))
+            return false;
+        try {
+            recordWorldLifecycleEvent(root, world, 'instance metadata gone and every recorded process exited; ownership released');
+        }
+        catch { /* the root may be gone with it */ }
+        rmSync(path);
+        return true;
+    });
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        return cause.code === 'EPERM';
+    }
+}
+export function hasWorldLifecycle(root, world) {
+    return existsSync(recordPath(root, world)) || existsSync(legacyPath(root, world));
+}
+export function inspectWorldLifecycles() {
+    const worlds = [];
+    const warnings = [];
+    for (const file of existsSync(directory()) ? readdirSync(directory()).sort() : []) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const record = read(join(directory(), file));
+            if (file !== `${record.identity}.json`)
+                throw new Error('filename identity mismatch');
+            worlds.push(record);
+        }
+        catch {
+            warnings.push(`Unreadable lifecycle record ${file}; retained, ownership unknown.`);
+        }
+    }
+    const legacyDirectory = join(volterHome(), 'world-resource-claims');
+    const legacyRecords = [];
+    for (const file of existsSync(legacyDirectory) ? readdirSync(legacyDirectory).sort() : []) {
+        if (!file.endsWith('.json'))
+            continue;
+        const path = join(legacyDirectory, file);
+        try {
+            const old = JSON.parse(readFileSync(path, 'utf8'));
+            const root = old.root ?? (typeof old.log === 'string' ? resolve(dirname(old.log), '../../..') : undefined);
+            if (typeof root !== 'string' || typeof old.world !== 'string' || identity(root, old.world) !== old.identity
+                || file !== `${old.identity}.json`)
+                throw new Error('unknown identity');
+            legacyRecords.push({ path, world: old.world, root, cleanupPending: old.cleanupPending === true, readable: true });
+        }
+        catch {
+            legacyRecords.push({ path, readable: false });
+            warnings.push(`Unreadable legacy record ${file}; retained, not charged as capacity.`);
+        }
+    }
+    return { worlds, legacyRecords, warnings };
+}
+/** Runtime phase is meaningful only for the same instance generation; it is not a health probe. */
+export function isWorldLifecycleRunning(root, world, instanceCreatedAt) {
+    try {
+        const record = read(recordPath(root, world));
+        return record.identity === identity(root, world) && record.instanceCreatedAt === instanceCreatedAt && record.phase === 'running';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/origin.d.ts

@@ -0,0 +1,31 @@
+import { type HistoryReference } from '@volter/world-core';
+import type { WorldInstance } from './schema.js';
+export type FetchOptions = {
+    root?: string;
+    url?: string;
+    namespace?: string;
+    key: string;
+    full?: boolean;
+    services?: string[];
+    views?: Record<string, HistoryReference>;
+    now?: Date;
+};
+export type FetchOutcome = {
+    /** per twin: entries in the cache past the branch's position — what a rebase folds */
+    snapshots: Record<string, HistoryReference & {
+        remoteView?: string;
+    }>;
+    behind: Record<string, number>;
+    world: string;
+    origin: {
+        url: string;
+        namespace: string;
+    };
+    full: boolean;
+    appended: Record<string, number>;
+    files?: number;
+};
+/** Bring in what the origin has past this world's recorded position, per twin; `full` starts from
+ *  zero and records the origin as this world's. */
+export declare function fetchFromOrigin(name: string, options: FetchOptions): Promise<FetchOutcome>;
+export declare function worldOrigin(name: string, root?: string): WorldInstance['origin'] | null;

package/dist/src/origin.js

@@ -0,0 +1,139 @@
+import { captureHistory, historyDigest, publishOriginHistory, readHistoryView, historyLength, worldPaths } from '@volter/world-core';
+// `volter world clone` and `fetch` — a world's ORIGIN is another world, served (docs/concepts/the-model.md
+// #a-branch-is-a-position-not-a-copy: a clone is a branch whose parent is at a URL): its whole log per twin is this world's PARENT. `clone` records the origin
+// and brings every twin's log in from position zero; `fetch` appends what the origin has past the
+// recorded position. Nothing here touches a vendor: an origin is always a world, the token is the
+// served world's, and what arrives are entries — the parent log grows, the branch log is untouched.
+import { join, resolve } from 'node:path';
+import { getActiveWorldStore, readBranchMeta, withAncestryLock, writeBranchMeta } from '@volter/world-core';
+import { saveWorldInstance, statusWorld } from "./runtime.js";
+import { fetchReady, isPathRemote, localWorld, TOKEN_HEADER } from "./served-world.js";
+function originOf(instance, options) {
+    const url = options.url ?? instance.origin?.url;
+    const namespace = options.namespace ?? instance.origin?.namespace;
+    if (!url || !namespace)
+        throw new Error(`World "${instance.name}" has no origin recorded — \`volter remote add origin <url>\` or \`volter world clone <url>\` first`);
+    if (!isPathRemote(url) && !/^[a-z0-9_-]+\/[a-z0-9_-]+$/i.test(namespace))
+        throw new Error(`a served world is <org>/<world>, got ${JSON.stringify(namespace)}`);
+    return { url: url.replace(/\/+$/, ''), namespace };
+}
+/** A twin's whole log from the origin, from a position: over http from a served world's door, or
+ *  straight off the disk of a world at a path. */
+/** The state service a twin records under: its own name, else the one state dir under its control root (slack → chat). */
+function stateServiceOf(controlRoot, service) {
+    const stateRoot = join(controlRoot, '.volter', 'world');
+    const store = getActiveWorldStore();
+    const states = store.list(stateRoot).filter((name) => store.stat(join(stateRoot, name))?.isDirectory);
+    return states.includes(service) ? service : states.length === 1 ? states[0] : service;
+}
+async function pageOf(origin, service, after, key, view) {
+    return door(origin, `log/${service}?after=${after}&limit=500${view ? `&view=${encodeURIComponent(view)}` : ''}`, key);
+}
+async function door(origin, path, key) {
+    const res = await fetchReady(`${origin.url}/-/${origin.namespace}/${path}`, { headers: { [TOKEN_HEADER]: key } });
+    if (!res.ok)
+        throw new Error(`origin ${origin.url}/-/${origin.namespace}/${path} answered ${res.status}: ${(await res.text()).slice(0, 200)}`);
+    return (await res.json());
+}
+/** Bring in what the origin has past this world's recorded position, per twin; `full` starts from
+ *  zero and records the origin as this world's. */
+export async function fetchFromOrigin(name, options) {
+    const root = resolve(options.root ?? process.cwd());
+    const instance = statusWorld(name, root);
+    const origin = originOf(instance, options);
+    const at_ = (options.now ?? new Date()).toISOString();
+    const services = (options.services ?? Object.keys(instance.services)).sort();
+    const appended = {};
+    const behind = {};
+    const snapshots = {};
+    withAncestryLock(() => {
+        for (const service of services) {
+            const controlRoot = join(instance.dirs.data, service);
+            const meta = readBranchMeta(stateServiceOf(controlRoot, service), controlRoot);
+            if (meta?.parent && !meta.origin)
+                throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
+        }
+    });
+    for (const service of services) {
+        const controlRoot = join(instance.dirs.data, service);
+        const state = stateServiceOf(controlRoot, service);
+        if (isPathRemote(origin.url)) {
+            // A PARENT ON THIS MACHINE is read live through the pointer, like a local branch (contract
+            // "Just like Neon", 1): nothing is copied; a clone points at the parent's head, a fetch only
+            // says how far the parent has moved past this branch's position
+            withAncestryLock(() => {
+                const target = localWorld(origin.url);
+                const at = join(target.instance.dirs.data, service);
+                const parentState = stateServiceOf(at, service);
+                const head = options.views?.[service] ?? captureHistory(parentState, at);
+                const parentLength = historyLength(readHistoryView(worldPaths(parentState, at).dir, head.view).layout);
+                if (head.position !== parentLength)
+                    throw new Error('Origin view and position disagree');
+                snapshots[service] = { view: head.view, position: parentLength };
+                const meta = readBranchMeta(state, controlRoot);
+                if (meta?.parent && !meta.origin)
+                    throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
+                const before = meta?.origin?.position ?? meta?.parent?.position ?? 0;
+                const descriptor = readHistoryView(worldPaths(parentState, at).dir, head.view);
+                const tracking = { at, directory: descriptor.owner.directory, generation: descriptor.owner.generation, view: head.view, position: parentLength, depth: 0 };
+                // a world with no pointer adopts this origin as its parent: a clone starts at the origin's head,
+                // a world that only added the remote starts at zero and rebases onto it
+                if (!meta?.parent)
+                    writeBranchMeta(state, { parent: { at, position: options.full ? parentLength : 0, view: head.view }, origin: { ...tracking, ...(!options.full ? { position: 0, incomplete: true } : {}) }, fetchedOrigin: tracking, branchedAt: at_ }, controlRoot);
+                else
+                    writeBranchMeta(state, { ...meta, fetchedOrigin: tracking }, controlRoot);
+                const selected = readBranchMeta(state, controlRoot);
+                const pointer = selected?.origin ?? selected?.parent;
+                appended[service] = Math.max(0, parentLength - before);
+                behind[service] = pointer ? Math.max(0, parentLength - pointer.position) || (pointer.view === head.view ? 0 : 1) : 0;
+            });
+            continue;
+        }
+        // Download one immutable view, then publish its complete cache head. No mixed pages.
+        const requested = options.views?.[service];
+        const first = await pageOf(origin, service, 0, options.key, requested?.view);
+        if (requested && (first.view !== requested.view || first.position !== requested.position))
+            throw new Error('Origin did not return the requested history snapshot');
+        if (!first.view || !Number.isInteger(first.position) || first.position < 0 || first.after !== 0)
+            throw new Error('Origin did not return an immutable history view');
+        const entries = [];
+        let page = first;
+        for (;;) {
+            if (page.view !== first.view || page.position !== first.position || page.after !== entries.length || page.state !== first.state || page.digest !== first.digest || historyDigest(page.layout) !== historyDigest(first.layout))
+                throw new Error('Origin changed history view during pagination');
+            entries.push(...page.entries);
+            if (entries.length > first.position)
+                throw new Error('Origin history exceeds its declared position');
+            if (entries.length === first.position)
+                break;
+            if (page.entries.length === 0)
+                throw new Error('Origin history page ended before its declared position');
+            page = await pageOf(origin, service, entries.length, options.key, first.view);
+        }
+        if (historyDigest({ layout: first.layout, entries }) !== first.digest)
+            throw new Error('Origin history digest mismatch');
+        withAncestryLock(() => {
+            const meta = readBranchMeta(state, controlRoot);
+            if (meta?.parent && !meta.origin)
+                throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
+            const cached = publishOriginHistory(state, controlRoot, first.view, first.layout, entries);
+            appended[service] = cached.appended;
+            snapshots[service] = { view: cached.view, position: entries.length, remoteView: first.view };
+            const descriptor = readHistoryView(worldPaths(state, controlRoot).dir, cached.view);
+            const tracking = { at: `${origin.url}/${origin.namespace}`, directory: descriptor.owner.directory, generation: descriptor.owner.generation, view: cached.view, position: entries.length, remoteView: first.view, depth: 0 };
+            if (!meta?.parent)
+                writeBranchMeta(state, { parent: { at: tracking.at, position: options.full ? entries.length : 0, view: cached.view, remoteView: first.view }, origin: { ...tracking, ...(!options.full ? { position: 0, incomplete: true } : {}) }, fetchedOrigin: tracking, branchedAt: at_ }, controlRoot);
+            else
+                writeBranchMeta(state, { ...meta, fetchedOrigin: tracking }, controlRoot);
+            const selected = readBranchMeta(state, controlRoot);
+            const pointer = selected?.origin ?? selected?.parent;
+            // Changed same-length snapshots are still drift; offsets are scoped to a view.
+            behind[service] = pointer ? Math.max(0, entries.length - pointer.position) || (pointer.remoteView === first.view ? 0 : 1) : 0;
+        });
+    }
+    saveWorldInstance({ ...instance, origin: { ...origin, ...(options.full ? { clonedAt: at_ } : instance.origin?.clonedAt ? { clonedAt: instance.origin.clonedAt } : {}), fetchedAt: at_ } });
+    return { world: name, origin, full: options.full ?? false, appended, behind, snapshots };
+}
+export function worldOrigin(name, root) {
+    return statusWorld(name, resolve(root ?? process.cwd())).origin ?? null;
+}

package/dist/src/pack-facts.d.ts

@@ -0,0 +1,75 @@
+export type PackAdoption = {
+    sdks?: string[];
+    pypi?: string[];
+    scopes?: string[];
+    envStems?: string[];
+    worldIds?: string[];
+    tools?: Array<{
+        package: string;
+        usage: 'build' | 'deployment';
+    }>;
+};
+export type PackFacts = {
+    /** Existing descriptor transport, compiled into the same artifact as endpoint/adoption facts. */
+    transport?: string;
+    /** Optional native frontend of the same state owner, selected explicitly on the pack CLI. */
+    nativeTransport?: {
+        protocol: string;
+        flag: string;
+        upstreamEnv: string;
+    };
+    adoption?: PackAdoption;
+    hosts?: Array<{
+        host?: string;
+        suffix?: string;
+        hostPattern?: string;
+        pathPattern?: string;
+        key?: string;
+        exclude?: true;
+    }>;
+    hostsNone?: string;
+    endpointEnv?: {
+        name: string;
+        templates?: Record<string, string>;
+        note: string;
+    };
+    endpointEnvNone?: string;
+    /** The pack's colocatable `create<Name>TwinServer` factory export, derived (or descriptor-
+     *  declared under ambiguity) by scripts/pack-facts.ts. Consumed by `init` to emit
+     *  `colocate:` service entries so a world's twins boot inside ONE host process (R2a). */
+    serveExport?: string;
+    /** R16: the protocol major the package targets and its standing against the kernel that compiled the artifact. */
+    protocol?: {
+        declared?: string;
+        major: number;
+        standing: 'current' | 'deprecated' | 'refused' | 'assumed';
+    };
+};
+export declare function packFacts(): Record<string, PackFacts>;
+/** Overlay descriptor-declared npm SDK names onto the central SDK_TWINS map (project-inspect.ts). */
+/** The PyPI half of the SDK map, built the same way from each descriptor's `adoption.pypi`
+ *  (PEP 503 names). One name belongs to one pack; a second claim refuses at load. */
+export declare function overlayPypiTwins(pypiTwins: Record<string, {
+    vendor: string;
+    twin: string;
+}>): void;
+/** PEP 503: case-insensitive, runs of `-_.` collapse to one `-`. */
+export declare function normalizePypiName(name: string): string;
+export declare function overlaySdkTwins(sdkTwins: Record<string, {
+    vendor: string;
+    twin: string;
+}>): void;
+/** Overlay descriptor-declared scopes/env stems/world ids onto covers.ts's central maps. */
+export declare function overlayCoversMaps(maps: {
+    scopeVendors: Record<string, string>;
+    envStemVendors: Record<string, string>;
+    vendorWorldIds: Record<string, string[]>;
+}): void;
+/** Overlay descriptor-declared endpoint-env wiring for packs with no injectable host.
+ * Packs that also declare hosts are wired through the injector; init reads their optional
+ * endpoint templates directly from pack facts without misclassifying them as app-read-only. */
+export declare function overlayEndpointEnv(table: Record<string, {
+    injectEnv?: string;
+    injectEnvTemplates?: Record<string, string>;
+    note: string;
+}>): void;