@volter/world-core 2.0.0

package/dist/src/executor.js

@@ -0,0 +1,387 @@
+const MAX_ORIGIN_LENGTH = 2048;
+function isLoopbackHost(hostname) {
+    return hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '[::1]' || hostname === '::1';
+}
+/** Throws with the precise refusal; returns the parsed URL when the origin is usable. */
+export function validateRemoteOrigin(origin, opts = {}) {
+    if (origin.length > MAX_ORIGIN_LENGTH)
+        throw new Error(`remote origin exceeds ${MAX_ORIGIN_LENGTH} characters`);
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        throw new Error('remote origin must be an absolute URL');
+    }
+    if (url.username !== '' || url.password !== '')
+        throw new Error('remote origin must not carry userinfo');
+    const loopback = isLoopbackHost(url.hostname);
+    if (url.protocol !== 'https:') {
+        if (!(url.protocol === 'http:' && loopback && opts.allowInsecureLoopback === true)) {
+            throw new Error('remote origin must be https (http is allowed only to loopback, and only where the shell permits it)');
+        }
+    }
+    if (!loopback || opts.allowInsecureLoopback !== true) {
+        if (loopback)
+            throw new Error('remote origin must not target loopback on this deployment');
+        // Trailing dots defeat suffix/equality checks ('localhost.' resolves as localhost —
+        // review B2); strip before every hostname comparison.
+        const host = url.hostname.replace(/^\[|\]$/g, '').replace(/\.+$/, '');
+        // NO IP-LITERAL ORIGINS, v4 or v6 (review B2): the WHATWG parser normalizes exotic
+        // v4 spellings to dotted form, but v6 carries mapped-v4 ([::ffff:7f00:1]), NAT64
+        // and [::] forms no regex allowlist survives — and no real vendor publishes an IP
+        // origin. Hostnames only; loopback literals ride the explicit allowance above.
+        if (/^\d+\.\d+\.\d+\.\d+$/.test(host) || url.hostname.startsWith('[') || host.includes(':')) {
+            throw new Error('remote origin must be a hostname, never an IP literal');
+        }
+        if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.internal')) {
+            throw new Error('remote origin must not target a local-only hostname');
+        }
+    }
+    return url;
+}
+/** Build the kernel's RemoteExecute (R14 scheduled pull) from the link's validated
+ *  origin + the sealed credential — a pack never holds a credential, a scheduler never
+ *  learns a vendor shape. */
+const EGRESS_TIMEOUT_MS = 30_000;
+/** HMAC-SHA256 over WebCrypto — NOT `node:crypto`, deliberately. This file is on the credential
+ *  path and the host it runs on may be workerd (the contract's Cloudflare shell), which is the same
+ *  reason credential.ts is WebCrypto-only. Kept local rather than exported: nothing outside the
+ *  executor should be signing with a credential's secret. */
+async function hmacSha256(secret, payload, encoding) {
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const bytes = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payload)));
+    if (encoding === 'hex')
+        return [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+const encoder = new TextEncoder();
+async function hmacRaw(key, data) {
+    const k = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return new Uint8Array(await crypto.subtle.sign('HMAC', k, encoder.encode(data)));
+}
+const hex = (bytes) => [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+async function sha256Hex(data) {
+    return hex(new Uint8Array(await crypto.subtle.digest('SHA-256', typeof data === 'string' ? encoder.encode(data) : new Uint8Array(data))));
+}
+/** RFC3986 encoding, which is stricter than `encodeURIComponent` about these four. */
+// The apostrophe is written \x27 ON PURPOSE. A raw one inside a regex character class desynchronizes
+// the A2 guardrail's string-stripper — it reads the rest of the file as one long string literal and
+// then finds a bare `x` in `x-amz-date`, which it correctly refuses as the kernel naming a vendor
+// (there is a pack called `x`). The guardrail is blunt by design; this is the cheaper side to bend.
+const rfc3986 = (v) => encodeURIComponent(v).replace(/[!\x27()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+/**
+ * AWS SIGNATURE VERSION 4, the published algorithm — not a vendor branch. Everything specific to a
+ * vendor (which region, which service) arrives as an argument from the pack's `scope`.
+ *
+ * Returns the headers to add. The caller has already applied `credential.headers`, so this signs
+ * over what will actually be sent.
+ */
+async function awsSigV4Headers(input) {
+    const { method, url, body, keyId, secret, region, service, headers, at } = input;
+    const amzDate = `${at.toISOString().slice(0, 19).replace(/[:-]/g, '')}Z`; // YYYYMMDDTHHMMSSZ
+    const dateStamp = amzDate.slice(0, 8);
+    const payloadHash = await sha256Hex(body ?? '');
+    // S3 does NOT double-encode the path and every other service does. That clause is part of the
+    // SigV4 specification itself, which is why it lives with the algorithm rather than in a switch
+    // table on vendor identity.
+    //
+    // `url.pathname` is ALREADY RFC3986-encoded by the URL parser, so S3 — which signs the path as
+    // sent — takes it unchanged. Every other service signs the path encoded a SECOND time, which is
+    // encoding the already-encoded form (a space is `%2520`, not `%20`). Encoding twice for S3, or
+    // once for the rest, both produce a signature the vendor rejects.
+    const raw = url.pathname === '' ? '/' : url.pathname;
+    const canonicalUri = service === 's3' ? raw : raw.split('/').map(rfc3986).join('/');
+    const canonicalQuery = [...url.searchParams.entries()]
+        .map(([k, v]) => [rfc3986(k), rfc3986(v)])
+        // `left`/`right`, not `x`/`y`: there is a vendor pack named `x`, and the A2 guardrail reads a
+        // bare `x` in kernel source as the kernel branching on vendor identity. It is right to be that
+        // blunt — the name is free to change and the invariant is not.
+        .sort((left, right) => (left[0] === right[0] ? (left[1] < right[1] ? -1 : 1) : left[0] < right[0] ? -1 : 1))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    // Sign the host, the date, the payload hash, and anything the vendor's own protocol carries
+    // (`x-amz-*`, a content type). Sorted and lower-cased, values trimmed — the canonical form.
+    const signable = new Map([['host', url.host], ['x-amz-date', amzDate], ['x-amz-content-sha256', payloadHash]]);
+    headers.forEach((value, name) => {
+        const n = name.toLowerCase();
+        if (n.startsWith('x-amz-') || n === 'content-type')
+            signable.set(n, value.trim().replace(/\s+/g, ' '));
+    });
+    const names = [...signable.keys()].sort();
+    const canonicalHeaders = names.map((n) => `${n}:${signable.get(n)}\n`).join('');
+    const signedHeaders = names.join(';');
+    const canonicalRequest = [method.toUpperCase(), canonicalUri, canonicalQuery, canonicalHeaders, signedHeaders, payloadHash].join('\n');
+    const scope = `${dateStamp}/${region}/${service}/aws4_request`;
+    const stringToSign = ['AWS4-HMAC-SHA256', amzDate, scope, await sha256Hex(canonicalRequest)].join('\n');
+    // the four chained HMACs
+    let key = encoder.encode(`AWS4${secret}`);
+    for (const part of [dateStamp, region, service, 'aws4_request'])
+        key = await hmacRaw(key, part);
+    const signature = hex(await hmacRaw(key, stringToSign));
+    return {
+        'x-amz-date': amzDate,
+        'x-amz-content-sha256': payloadHash,
+        authorization: `AWS4-HMAC-SHA256 Credential=${keyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    };
+}
+export function buildRemoteExecute(origin, credential, auth, vendorHosts, options = {}) {
+    if (auth?.in === 'exchange')
+        return exchangeExecute(origin, credential, auth, vendorHosts, options.custody);
+    return async ({ method, path, headers, body, responseType, presigned }) => {
+        // A PRESIGNED UPLOAD URL the vendor returned: its own signature is its authorization, so the
+        // sealed credential never goes with it, whatever host it names. A host other than the root's
+        // passes the same validation the root does; the root's own origin (a twin standing in for the
+        // vendor on loopback) is already validated.
+        if (presigned) {
+            let target;
+            try {
+                target = new URL(path);
+            }
+            catch {
+                throw new Error('remote execute: a presigned request carries an absolute URL');
+            }
+            if (target.username || target.password)
+                throw new Error('remote execute: a presigned URL carries no userinfo');
+            // any other host passes the root's own validator: https, no IP literal, no local-only name
+            if (target.origin !== origin.origin)
+                validateRemoteOrigin(target.origin);
+            const response = await fetch(target, {
+                method,
+                headers: new Headers(headers ?? {}),
+                ...(body === undefined ? {} : { body: typeof body === 'string' ? body : new Uint8Array(body) }),
+                redirect: 'manual',
+                signal: AbortSignal.timeout(EGRESS_TIMEOUT_MS),
+            });
+            const responseHeaders = {};
+            response.headers.forEach((value, key) => { responseHeaders[key] = value; });
+            if (responseType === 'bytes') {
+                const bodyBytes = new Uint8Array(await response.arrayBuffer());
+                return { status: response.status, headers: responseHeaders, body: new TextDecoder().decode(bodyBytes), bodyBytes };
+            }
+            return { status: response.status, headers: responseHeaders, body: await response.text() };
+        }
+        // PATH ANCHORING (review M5): '@evil.com/x' concatenated after an origin reparses
+        // the origin into USERINFO and ships the credential to evil.com. A path is a path:
+        // it starts with '/', and the parse must land on the validated origin, asserted.
+        let target;
+        if (/^https:\/\//i.test(path) && vendorHosts?.length) {
+            // a second host the pack declares for this vendor, on a path its rule names: validated as the root is
+            target = new URL(path);
+            if (target.username || target.password)
+                throw new Error('remote execute: a vendor URL carries no userinfo');
+            validateRemoteOrigin(target.origin);
+            const declared = vendorHosts.some((r) => 'host' in r && !r.exclude && r.host === target.hostname && (r.pathPattern === undefined || new RegExp(r.pathPattern).test(target.pathname)));
+            if (!declared)
+                throw new Error(`remote execute: ${target.host}${target.pathname.slice(0, 64)} is not a host this vendor's pack declares for this path`);
+        }
+        else {
+            if (!path.startsWith('/'))
+                throw new Error(`remote execute: path must start with '/' (got ${JSON.stringify(path.slice(0, 64))})`);
+            // the base keeps its path: a served world's twin lives under /<org>/<world>/<vendor>, github.com under /
+            const base = origin.href.replace(/\/+$/, '');
+            target = new URL(base + path);
+            if (target.origin !== origin.origin || !target.pathname.startsWith(origin.pathname.replace(/\/+$/, '')))
+                throw new Error('remote execute: path escaped the validated origin');
+        }
+        const outbound = new Headers(headers ?? {});
+        for (const [name, value] of Object.entries(credential.headers))
+            outbound.set(name, value);
+        // ── THE STRATEGIES BEYOND HEADER REPLACEMENT ──────────────────────────────────────────────
+        // Applied AFTER the anchoring check above, so nothing here can move the request off the
+        // validated origin: `searchParams.set` only ever touches the query, and a header is a header.
+        //
+        // FAIL CLOSED. A strategy with no secret must never send a request that merely LOOKS
+        // authenticated — that silence is the whole defect this exists to remove. The refusals name the
+        // strategy and the parameter, never the secret.
+        if (auth !== undefined) {
+            const secret = credential.secret;
+            if (typeof secret !== 'string' || secret === '') {
+                throw new Error(`remote execute: the ${auth.in} credential strategy needs \`secret\` on the sealed credential, and it is absent`);
+            }
+            if (auth.in === 'query') {
+                // `set`, not `append`: it REPLACES whatever placeholder the pack put in its own path,
+                // exactly as `outbound.set` replaces a placeholder authorization header.
+                target.searchParams.set(auth.name, secret);
+            }
+            else if (auth.algorithm === 'aws-sigv4') {
+                const keyId = credential.keyId;
+                if (typeof keyId !== 'string' || keyId === '') {
+                    throw new Error('remote execute: the aws-sigv4 credential strategy needs `keyId` on the sealed credential, and it is absent');
+                }
+                // the HOST goes with it: an AWS endpoint names its own region, and only the pack knows how
+                const { region, service } = auth.scope({ method, path, host: target.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) });
+                const signed = await awsSigV4Headers({ method, url: target, ...(body === undefined ? {} : { body }), keyId, secret, region, service, headers: outbound, at: new Date() });
+                for (const [name, value] of Object.entries(signed))
+                    outbound.set(name, value);
+            }
+            else {
+                // `null` is the vendor's own exemption, declared by the pack — not an error, and not a
+                // reason to send an unsigned header.
+                if (body instanceof Uint8Array)
+                    throw new Error('remote execute: this signature canonicalizer accepts text bodies only');
+                const payload = auth.canonical({ method, path, ...(body === undefined ? {} : { body }) });
+                if (payload !== null)
+                    outbound.set(auth.header, await hmacSha256(secret, payload, auth.encoding));
+            }
+        }
+        const response = await fetch(target, {
+            method,
+            headers: outbound,
+            ...(body === undefined ? {} : { body: typeof body === 'string' ? body : new Uint8Array(body) }),
+            redirect: 'manual',
+            // A hung vendor must not hold the isolate store fence open-endedly (review B2);
+            // the pull records the abort as ordinary failure health and backs off.
+            signal: AbortSignal.timeout(EGRESS_TIMEOUT_MS),
+        });
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => { responseHeaders[key] = value; });
+        if (responseType === 'bytes') {
+            const bodyBytes = new Uint8Array(await response.arrayBuffer());
+            return { status: response.status, headers: responseHeaders, body: new TextDecoder().decode(bodyBytes), bodyBytes };
+        }
+        return { status: response.status, headers: responseHeaders, body: await response.text() };
+    };
+}
+/** Tokens the exchange strategy holds, per root and credential, for the life of the process: an executor
+ *  is built per deploy and per refresh, so a token kept only inside one would cost a fresh exchange on every
+ *  write (Bluesky allows 30 sessions in five minutes). In memory only; never written anywhere. */
+const exchangedTokens = new Map();
+/** A rotated credential a seal failed to keep, per custody key: the process spends it (never the spent one the file
+ *  still holds) until a seal succeeds or the file moves past the value it replaced. In memory only. */
+const unsealedRotations = new Map();
+/** The exchange strategy over the ordinary executor: the token request goes out with the credential's
+ *  declared fields in its body, the token comes back to this module only, and every non-presigned call
+ *  carries it. Presigned calls pass through untouched (they carry their own authorization). */
+function exchangeExecute(origin, sealed, auth, vendorHosts, custody) {
+    let credential = sealed;
+    const anchored = buildRemoteExecute(origin, credential, undefined, vendorHosts);
+    const header = auth.header ?? 'authorization';
+    const scheme = auth.scheme ?? 'Bearer';
+    const retryOn = auth.retryOn ?? [401];
+    if (!credential.headers || typeof credential.headers !== 'object')
+        throw new Error('remote execute: an exchange credential is sealed with a headers object (it may be empty)');
+    // the sealed headers are applied after the caller's, so one naming the token's header would replace it
+    if (Object.keys(credential.headers).some((name) => name.toLowerCase() === header.toLowerCase()))
+        throw new Error(`remote execute: an exchange credential must not seal its own \`${header}\` header`);
+    const field = (name) => {
+        const held = credential[name];
+        // fail closed, naming the field and never its value
+        if (typeof held !== 'string' || held === '')
+            throw new Error(`remote execute: the exchange needs \`${name}\` on the sealed credential, and it is absent`);
+        return held;
+    };
+    const key = custody ? `${origin.href}\n${custody.key}` : `${origin.href}\n${JSON.stringify(sealed)}`;
+    const exchange = async () => {
+        // a rotating secret is read as kept NOW (another executor or process may have rotated it since this one was
+        // built), or as this process holds it when its seal failed and the file still holds the spent value. Two
+        // processes reading the same value within one exchange's round trip can still both spend it: there is no lock
+        // across the call.
+        if (auth.rotate && custody) {
+            credential = await custody.open();
+            const unsealed = unsealedRotations.get(key);
+            if (unsealed && credential[auth.rotate.credential] === unsealed.replaced)
+                credential = unsealed.credential;
+            else
+                unsealedRotations.delete(key);
+        }
+        const fields = {};
+        for (const [name, value] of Object.entries(auth.request.body))
+            fields[name] = typeof value === 'string' ? value : field(value.credential);
+        const body = auth.request.format === 'json' ? JSON.stringify(fields) : new URLSearchParams(fields).toString();
+        const headers = { 'content-type': auth.request.format === 'json' ? 'application/json' : 'application/x-www-form-urlencoded' };
+        if (auth.request.basicAuth)
+            headers.authorization = `Basic ${btoa(`${field(auth.request.basicAuth.user.credential)}:${field(auth.request.basicAuth.password.credential)}`)}`;
+        const answer = await anchored({ method: auth.request.method, path: auth.request.path, headers, body });
+        if (answer.status < 200 || answer.status >= 300) {
+            // the vendor's own reason (an error code, never a secret: the answer carries no token on failure)
+            let reason = '';
+            try {
+                const parsed = JSON.parse(answer.body);
+                reason = String(parsed.error ?? parsed.message ?? '').slice(0, 120);
+            }
+            catch { /* no JSON */ }
+            throw new Error(`remote execute: the token exchange answered ${answer.status}${reason ? ` (${reason})` : ''}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(answer.body);
+        }
+        catch {
+            throw new Error('remote execute: the token exchange answered no JSON');
+        }
+        const value = auth.token.split('.').reduce((at, k) => (at && typeof at === 'object' ? at[k] : undefined), parsed);
+        if (typeof value !== 'string' || value === '') {
+            // an OAuth token endpoint may refuse a grant with a 2xx whose `error` names why (RFC 6749 §5.2's field): carry it, never a secret
+            const code = parsed && typeof parsed === 'object' ? parsed.error : undefined;
+            throw new Error(`remote execute: the token exchange answered no \`${auth.token}\`${typeof code === 'string' && code !== '' ? ` (${code.slice(0, 120)})` : ''}`);
+        }
+        if (auth.rotate) {
+            const next = auth.rotate.answer.split('.').reduce((at, k) => (at && typeof at === 'object' ? at[k] : undefined), parsed);
+            if (typeof next === 'string' && next !== '' && next !== credential[auth.rotate.credential]) {
+                // the spent secret is dead at the vendor: held at once, then sealed; a seal that fails is loud (the root would die
+                // on its next start), and the token the vendor already answered is kept
+                const replaced = String(credential[auth.rotate.credential] ?? '');
+                credential = { ...credential, [auth.rotate.credential]: next };
+                if (custody) {
+                    try {
+                        await custody.seal(credential);
+                        unsealedRotations.delete(key);
+                    }
+                    catch (error) {
+                        unsealedRotations.set(key, { replaced, credential });
+                        console.error(`remote execute: the vendor rotated \`${auth.rotate.credential}\` and sealing the new one failed (${error instanceof Error ? error.message : String(error)}); this process holds it until a seal succeeds`);
+                    }
+                }
+            }
+        }
+        return value;
+    };
+    const current = () => {
+        let held = exchangedTokens.get(key);
+        if (!held) {
+            const token = exchange();
+            held = { token };
+            exchangedTokens.set(key, held);
+            const entry = held;
+            token.catch(() => { if (exchangedTokens.get(key) === entry)
+                exchangedTokens.delete(key); });
+        }
+        return held;
+    };
+    const call = async (request, held) => {
+        const value = await held.token;
+        const headers = {};
+        for (const [name, v] of Object.entries(request.headers ?? {}))
+            if (name.toLowerCase() !== header.toLowerCase())
+                headers[name] = v;
+        headers[header] = scheme ? `${scheme} ${value}` : value;
+        return anchored({ ...request, headers });
+    };
+    return async (request) => {
+        if (request.presigned)
+            return anchored(request);
+        const held = current();
+        const first = await call(request, held);
+        if (!retryOn.includes(first.status))
+            return first;
+        if (auth.retryCode !== undefined) {
+            let code;
+            try {
+                code = JSON.parse(first.body).error;
+            }
+            catch {
+                code = undefined;
+            }
+            if (code !== auth.retryCode)
+                return first;
+        }
+        // exchange again only if the token that failed is still the one held (concurrent failures share one)
+        if (exchangedTokens.get(key) === held)
+            exchangedTokens.delete(key);
+        return call(request, current());
+    };
+}

package/dist/src/file-response.d.ts

@@ -0,0 +1,3 @@
+/** The content type a file's extension implies; `application/octet-stream` for the rest. */
+export declare function contentTypeOf(path: string): string;
+export declare function fileResponse(path: string, init?: ResponseInit): Response;

package/dist/src/file-response.js

@@ -0,0 +1,22 @@
+// A file as a Response, runtime-neutral (the serve seam's helpers,
+// docs/contributing/architecture.md#the-serve-seam): what `new Response(Bun.file(path), init)` answered — the bytes, a content type from
+// the extension unless `init` names one, a 404 when the file is not there.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+const TYPES = {
+    html: 'text/html; charset=utf-8', css: 'text/css; charset=utf-8', js: 'text/javascript; charset=utf-8', mjs: 'text/javascript; charset=utf-8',
+    json: 'application/json', map: 'application/json', txt: 'text/plain; charset=utf-8', md: 'text/markdown; charset=utf-8', csv: 'text/csv; charset=utf-8', xml: 'application/xml',
+    png: 'image/png', gif: 'image/gif', jpg: 'image/jpeg', jpeg: 'image/jpeg', svg: 'image/svg+xml', webp: 'image/webp', ico: 'image/x-icon',
+    woff: 'font/woff', woff2: 'font/woff2', ttf: 'font/ttf', wasm: 'application/wasm', pdf: 'application/pdf', mp3: 'audio/mpeg', mp4: 'video/mp4', wav: 'audio/wav',
+};
+/** The content type a file's extension implies; `application/octet-stream` for the rest. */
+export function contentTypeOf(path) {
+    return TYPES[path.slice(path.lastIndexOf('.') + 1).toLowerCase()] ?? 'application/octet-stream';
+}
+export function fileResponse(path, init) {
+    if (!existsSync(path) || !statSync(path).isFile())
+        return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+    const headers = new Headers(init?.headers);
+    if (!headers.has('content-type'))
+        headers.set('content-type', contentTypeOf(path));
+    return new Response(readFileSync(path), { ...init, headers });
+}

package/dist/src/fork.d.ts

@@ -0,0 +1,26 @@
+import type { TwinResource } from './serve.js';
+export type ForkMeta = {
+    service: string;
+    forkedAt: string;
+    baseRoot: string;
+    baseView: string;
+    baseEventCount: number;
+    baseLatestEventId: string | null;
+    baseline: TwinResource[];
+};
+/**
+ * Create a fork of `service` from `fromRoot` into the fresh isolated `toRoot`.
+ * References the base log at a position, then records the divergence baseline. `occurredAt` is supplied by the caller (deterministic; no clock).
+ */
+export declare function forkTwin(opts: {
+    service: string;
+    toRoot: string;
+    fromRoot?: string;
+    occurredAt: string;
+    /** the position in the base's whole log to branch from (contract "Just like Neon", 3); the head when absent */
+    at?: number;
+    view?: string;
+    expectedGeneration?: string;
+}): ForkMeta;
+export declare function readForkMeta(service: string, root: string): ForkMeta;
+export declare function isFork(service: string, root: string): boolean;

package/dist/src/fork.js

@@ -0,0 +1,68 @@
+import { captureHistory, historyEntries, historyLength, historyPrefix, readHistoryView } from "./history.js";
+// Local branches share parent history at a position and retain a divergence baseline.
+// The kernel registers parent ownership before publishing the pointer. Lifecycle removal
+// refuses while a child depends on that storage; direct filesystem deletion bypasses it.
+import { dirname, join } from 'node:path';
+import { checkParent, withAncestryLock } from "./ancestry.js";
+import { getActiveWorldStore } from "./world-store.js";
+import { writeBranchMeta } from "./log.js";
+import { twinResources } from "./serve.js";
+import { readJsonFile, worldPaths } from "./storage.js";
+// Fields that are bookkeeping, not vendor data — excluded from divergence diffs.
+function forkMetaPath(service, root) {
+    return join(dirname(worldPaths(service, root).events), 'fork-meta.json');
+}
+/**
+ * Create a fork of `service` from `fromRoot` into the fresh isolated `toRoot`.
+ * References the base log at a position, then records the divergence baseline. `occurredAt` is supplied by the caller (deterministic; no clock).
+ */
+export function forkTwin(opts) {
+    return withAncestryLock(() => {
+        // A BRANCH IS A POINTER (log.ts): the base root and the position in its logs, nothing copied.
+        // The branch reads the base's parent view and branch log up to that position as its own
+        // parent, and records only its own entries from there. The base keeps appending past the
+        // position without the branch seeing it; destructive lifecycle operations respect this pin.
+        const { service, toRoot } = opts;
+        if (getActiveWorldStore().exists(forkMetaPath(service, toRoot))) {
+            throw new Error(`fork target already initialized for ${service}: ${toRoot}`);
+        }
+        const fromRoot = worldPaths(service, opts.fromRoot).root;
+        if (opts.expectedGeneration !== undefined)
+            checkParent(worldPaths(service, fromRoot).dir, opts.expectedGeneration);
+        else
+            getActiveWorldStore().mkdir(worldPaths(service, fromRoot).dir);
+        const view = opts.view ?? captureHistory(service, fromRoot).view;
+        const descriptor = readHistoryView(worldPaths(service, fromRoot).dir, view);
+        const head = historyLength(descriptor.layout);
+        const at = opts.at ?? head;
+        if (!Number.isInteger(at) || at < 0 || at > head)
+            throw new Error(`Invalid branch position ${at}; parent head is ${head}`);
+        const entries = historyEntries(descriptor);
+        if (at > 0 && at < entries.length && entries[at]?.batch && entries[at]?.batch === entries[at - 1]?.batch)
+            throw new Error(`position ${at} falls inside observation ${entries[at].batch}`);
+        const log = entries.slice(0, at);
+        const selected = historyPrefix(descriptor, at);
+        writeBranchMeta(service, { parent: { at: fromRoot, position: at, view }, branchedAt: opts.occurredAt, ...(selected.origin ? { origin: selected.origin } : {}) }, toRoot);
+        const baseline = twinResources(service, toRoot).sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        const meta = {
+            service,
+            forkedAt: opts.occurredAt,
+            baseRoot: fromRoot,
+            baseView: view,
+            baseEventCount: at,
+            baseLatestEventId: log.at(-1)?.id ?? null,
+            baseline,
+        };
+        getActiveWorldStore().write(forkMetaPath(service, toRoot), `${JSON.stringify(meta, null, 2)}\n`);
+        return meta;
+    });
+}
+export function readForkMeta(service, root) {
+    const path = forkMetaPath(service, root);
+    if (!getActiveWorldStore().exists(path))
+        throw new Error(`not a fork (no fork-meta.json) for ${service}: ${root}`);
+    return readJsonFile(path);
+}
+export function isFork(service, root) {
+    return getActiveWorldStore().exists(forkMetaPath(service, root));
+}

package/dist/src/git/history.d.ts

@@ -0,0 +1,36 @@
+import { GitObjectStore } from './objects.js';
+/** A best common ancestor of `a` and `b` (one that is not an ancestor of another common ancestor), or null. */
+export declare function mergeBase(store: GitObjectStore, a: string, b: string, limit?: number): Promise<string | null>;
+export type TreeChange = {
+    path: string;
+    status: 'added' | 'removed' | 'modified';
+    oldSha?: string;
+    newSha?: string;
+    oldMode?: string;
+    newMode?: string;
+};
+/** Recursive tree compare between two commits or trees (paths in the post-image order, no rename pairing — like `diff-tree -r` without -M). */
+export declare function diffTrees(store: GitObjectStore, from: string | null, to: string, prefix?: string): Promise<TreeChange[]>;
+export type Edit = {
+    kind: ' ' | '-' | '+';
+    line: string;
+};
+/** A shortest edit script between two texts (Myers, O((N+M)D)). */
+export declare function lineDiff(oldText: string, newText: string): Edit[];
+/** The unified-diff hunks (the body GitHub serves as a file's `patch`), 3 lines of context. */
+export declare function unifiedPatch(oldText: string, newText: string, context?: number): string;
+export type DiffFile = {
+    filename: string;
+    status: 'added' | 'removed' | 'modified';
+    additions: number;
+    deletions: number;
+    sha?: string;
+    patch?: string;
+};
+/** GitHub's file list between `base` and `head` (three-dot: from merge-base(base, head), or base when histories are unrelated), with counts and patches. */
+export declare function diffFiles(store: GitObjectStore, baseSha: string, headSha: string, opts?: {
+    patch?: boolean;
+}): Promise<DiffFile[] | null>;
+/** Three-way line merge. Return null for overlapping edits; preserve exact line endings.
+ * Binary payloads belong to the caller's conflict path, never a text decoder's replacement. */
+export declare function mergeText(base: string, ours: string, theirs: string): string | null;