@volter/world-runtime 2.0.0

package/dist/src/ca-trust.js

@@ -0,0 +1,64 @@
+import { createHash, randomUUID, X509Certificate } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import * as tls from 'node:tls';
+export class CaTrustError extends Error {
+}
+/** Per-client trust, materialized only when a caller attaches. Never modify the signing CA. */
+export function sessionTrustEnv(caCertPath, inputs = process.env) {
+    const callers = Array.isArray(inputs) ? inputs : [inputs];
+    const files = new Map();
+    const read = (path) => {
+        if (files.has(path))
+            return files.get(path);
+        try {
+            const contents = readFileSync(path, 'utf8');
+            const pattern = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+            const certificates = contents.match(pattern) ?? [];
+            if (!certificates.length || /-----BEGIN|-----END/.test(contents.replace(pattern, '')))
+                throw new Error('expected complete PEM certificates');
+            const pem = certificates.map(cert => new X509Certificate(cert).toString().trim()).join('\n');
+            files.set(path, pem);
+            return pem;
+        }
+        catch (error) {
+            throw new CaTrustError(`Cannot read configured CA file ${path}: ${String(error)}`);
+        }
+    };
+    const session = read(caCertPath);
+    const extra = callers.flatMap(caller => caller.NODE_EXTRA_CA_CERTS ? [read(caller.NODE_EXTRA_CA_CERTS)] : []).join('\n');
+    // getCACertificates is newer than our minimum Node version; bundled roots also cover callers
+    // whose current OpenSSL defaults have already been replaced by a session-only CA file.
+    const defaults = typeof tls.getCACertificates === 'function' ? tls.getCACertificates('default') : [];
+    const publicRoots = [...new Set([...tls.rootCertificates, ...defaults].map(cert => new X509Certificate(cert).toString().trim()))].join('\n');
+    const bundle = (contents) => {
+        const certificates = contents.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g) ?? [];
+        const pem = `${[...new Set(certificates.map(cert => cert.trim()))].sort().join('\n')}\n`;
+        const path = join(dirname(caCertPath), `trust-${createHash('sha256').update(pem).digest('hex')}.pem`);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            if (!existsSync(path) || readFileSync(path, 'utf8') !== pem) {
+                writeFileSync(temporary, pem, { flag: 'wx', mode: 0o600 });
+                renameSync(temporary, path);
+            }
+        }
+        catch (error) {
+            try {
+                rmSync(temporary, { force: true });
+            }
+            catch (cleanupError) {
+                throw new CaTrustError(`Cannot materialize session trust bundle: ${String(error)}; cleanup: ${String(cleanupError)}`);
+            }
+            throw new CaTrustError(`Cannot materialize session trust bundle: ${String(error)}`);
+        }
+        return path;
+    };
+    const env = {
+        NODE_EXTRA_CA_CERTS: extra ? bundle(`${extra}\n${session}`) : caCertPath,
+    };
+    for (const key of ['SSL_CERT_FILE', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'AWS_CA_BUNDLE', 'GIT_SSL_CAINFO']) {
+        const configured = callers.flatMap(caller => caller[key] ? [read(caller[key])] : []).join('\n');
+        env[key] = bundle(`${publicRoots}\n${extra}\n${configured}\n${session}`);
+    }
+    return env;
+}

package/dist/src/catalog.d.ts

@@ -0,0 +1,31 @@
+export declare const TWIN_PACKAGE_PREFIX = "@volter/twin-";
+/** Packages under the `@volter/twin-` prefix that are NOT twins. */
+export declare function twinPackageName(vendor: string): string;
+export type CatalogKind = 'checkout' | 'installed';
+export type Catalog = {
+    kind: CatalogKind;
+    /** The world root the catalog was resolved for. */
+    root: string;
+    /** Every vendor the catalog can run, sorted — a deterministic input to `init`. */
+    vendors(): string[];
+    /** The pack's directory (holds `src/cli.ts`, `src/index.ts`, `defaults/`, `package.json`), or undefined. */
+    packDir(vendor: string): string | undefined;
+    /** The pack's own version, from its package.json — the value a world's pin carries. */
+    version(vendor: string): string | undefined;
+    /** The birth stamp: the checkout's git sha, or a digest of the installed versions. */
+    sha(): string;
+};
+/** The pack's module entry, FROM ITS MANIFEST (docs/contributing/architecture.md#the-publishing-pipeline): `exports['.']`
+ *  — `src/index.ts` in the checkout, `dist/src/index.js` once published — so the same resolution
+ *  serves both; `main` behind it; the checkout convention last. */
+export declare function packEntry(dir: string): string;
+/** The pack's cli, from its manifest's `bin` (`world-<vendor>` when named, else the first), or undefined when the directory is no pack. */
+export declare function packCli(dir: string): string | undefined;
+/** The nearest `node_modules/<name>` above `from` that holds a package.json — node's own walk. */
+export declare function findInstalledPackage(from: string, name: string): string | undefined;
+export declare function checkoutCatalog(root: string): Catalog;
+export declare function installedCatalog(root: string): Catalog;
+/** The catalog for a world root: the checkout when `packages/twin` is there, else what is installed. */
+export declare function resolveCatalog(root: string): Catalog;
+/** The pack directory a service boots from: its `package` resolved from the world root at boot. */
+export declare function resolveServicePackage(root: string, pkg: string): string;

package/dist/src/catalog.js

@@ -0,0 +1,148 @@
+// The catalog — where the twins a world can run come from (docs/concepts/worlds.md
+// #the-config-and-the-running-world). Two sources answer one interface: this CHECKOUT (`packages/twin/<vendor>/`, the
+// catalog as the repo holds it) and an INSTALLED catalog (`@volter/twin-<vendor>` packages under
+// `node_modules`, walked up from the world root — hoisting-proof, and independent of the
+// packages' `exports` maps, which do not expose `package.json`). A world born in an app repo
+// names its twins as packages and the runtime resolves them at boot; a world born here names the
+// checkout-relative paths, as before.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+export const TWIN_PACKAGE_PREFIX = '@volter/twin-';
+/** Packages under the `@volter/twin-` prefix that are NOT twins. */
+export function twinPackageName(vendor) { return `${TWIN_PACKAGE_PREFIX}${vendor}`; }
+function packageVersion(dir) {
+    const p = join(dir, 'package.json');
+    if (!existsSync(p))
+        return undefined;
+    try {
+        const v = JSON.parse(readFileSync(p, 'utf8')).version;
+        return typeof v === 'string' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPackDir(dir) { return packCli(dir) !== undefined; }
+function manifest(dir) { const p = join(dir, 'package.json'); if (!existsSync(p))
+    return undefined; try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return undefined;
+} }
+/** The pack's module entry, FROM ITS MANIFEST (docs/contributing/architecture.md#the-publishing-pipeline): `exports['.']`
+ *  — `src/index.ts` in the checkout, `dist/src/index.js` once published — so the same resolution
+ *  serves both; `main` behind it; the checkout convention last. */
+export function packEntry(dir) {
+    const m = manifest(dir);
+    const dot = m?.exports === undefined ? undefined : typeof m.exports === 'string' ? m.exports : m.exports['.'];
+    const value = typeof dot === 'string' ? dot : dot && typeof dot === 'object' ? (dot.default ?? dot.import) : undefined;
+    const rel = typeof value === 'string' ? value : typeof m?.main === 'string' ? m.main : 'src/index.ts';
+    return join(dir, rel);
+}
+/** The pack's cli, from its manifest's `bin` (`world-<vendor>` when named, else the first), or undefined when the directory is no pack. */
+export function packCli(dir) {
+    const m = manifest(dir);
+    const bins = m === undefined ? {} : typeof m.bin === 'string' ? { [m.name ?? 'cli']: m.bin } : m.bin ?? {};
+    const named = Object.entries(bins).find(([n]) => n.startsWith('world-'))?.[1] ?? Object.values(bins)[0];
+    if (named)
+        return join(dir, named);
+    return existsSync(join(dir, 'src', 'cli.ts')) ? join(dir, 'src', 'cli.ts') : undefined;
+}
+/** The nearest `node_modules/<name>` above `from` that holds a package.json — node's own walk. */
+export function findInstalledPackage(from, name) {
+    let dir = resolve(from);
+    for (;;) {
+        const candidate = join(dir, 'node_modules', ...name.split('/'));
+        if (existsSync(join(candidate, 'package.json')))
+            return candidate;
+        const up = dirname(dir);
+        if (up === dir)
+            return undefined;
+        dir = up;
+    }
+}
+/** Every installed `@volter/twin-<vendor>` visible from `from`, nearest wins. */
+function installedTwins(from) {
+    const found = new Map();
+    let dir = resolve(from);
+    for (;;) {
+        const scope = join(dir, 'node_modules', '@volter');
+        if (existsSync(scope)) {
+            for (const entry of readdirSync(scope, { withFileTypes: true })) {
+                if (!entry.isDirectory() && !entry.isSymbolicLink())
+                    continue;
+                const name = `@volter/${entry.name}`;
+                if (!name.startsWith(TWIN_PACKAGE_PREFIX))
+                    continue; // the platform's packages are `@volter/world-*`: outside the prefix by name
+                const vendor = name.slice(TWIN_PACKAGE_PREFIX.length);
+                const packDir = join(scope, entry.name);
+                if (!found.has(vendor) && isPackDir(packDir))
+                    found.set(vendor, packDir);
+            }
+        }
+        const up = dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    return found;
+}
+function fnv1a(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+export function checkoutCatalog(root) {
+    const packsDir = resolve(root, 'packages', 'twin');
+    const vendors = () => readdirSync(packsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && isPackDir(join(packsDir, entry.name)))
+        .map((entry) => entry.name)
+        .sort();
+    return {
+        kind: 'checkout',
+        root: resolve(root),
+        vendors,
+        packDir: (vendor) => (isPackDir(join(packsDir, vendor)) ? join(packsDir, vendor) : undefined),
+        version: (vendor) => packageVersion(join(packsDir, vendor)),
+        sha: () => {
+            const proc = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+            const sha = proc.status === 0 ? proc.stdout.trim() : '';
+            return /^[0-9a-f]{40}$/.test(sha) ? sha : 'unknown';
+        },
+    };
+}
+export function installedCatalog(root) {
+    const twins = installedTwins(root);
+    return {
+        kind: 'installed',
+        root: resolve(root),
+        vendors: () => [...twins.keys()].sort(),
+        packDir: (vendor) => twins.get(vendor),
+        version: (vendor) => { const dir = twins.get(vendor); return dir === undefined ? undefined : packageVersion(dir); },
+        sha: () => `installed-${fnv1a([...twins.keys()].sort().map((v) => `${v}@${packageVersion(twins.get(v)) ?? '?'}`).join(','))}`,
+    };
+}
+/** The catalog for a world root: the checkout when `packages/twin` is there, else what is installed. */
+export function resolveCatalog(root) {
+    const resolved = resolve(root);
+    if (existsSync(join(resolved, 'packages', 'twin')))
+        return checkoutCatalog(resolved);
+    const installed = installedCatalog(resolved);
+    if (installed.vendors().length === 0) {
+        throw new Error(`No twins found for ${resolved}: no \`packages/twin\` catalog here and no \`@volter/twin-<vendor>\` package installed above it. `
+            + `Install the twins your app needs (e.g. \`bun add -d @volter/twin-stripe\`) and run init again.`);
+    }
+    return installed;
+}
+/** The pack directory a service boots from: its `package` resolved from the world root at boot. */
+export function resolveServicePackage(root, pkg) {
+    const dir = findInstalledPackage(root, pkg);
+    if (dir === undefined)
+        throw new Error(`Twin package ${pkg} is not installed above ${root} — \`bun add -d ${pkg}\` (or npm/pnpm) and run up again`);
+    return dir;
+}

package/dist/src/changeset.d.ts

@@ -0,0 +1,142 @@
+import type { ChangesetApplication, RebaseReport, Changeset, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, LedgerDelta, LedgerRef, ReplayReport, WorldMarker } from '@volter/world-core';
+export type WorldRootOptions = {
+    root?: string;
+};
+/** Every action ledger in a world, as control-plane ledger references. */
+export declare function worldLedgers(name: string, root?: string): LedgerRef[];
+export declare function worldMarksDir(name: string, root?: string): string;
+export declare function worldChangesetsDir(name: string, root?: string): string;
+/** Capture a cross-service base marker for `world` and persist it. */
+/** A world mark with the note it was taken with, if any: what the moment was, in words (a commit's message). The
+ *  note is the runtime's, beside world-core's marker, which reads no field of it. */
+export type NotedMarker = WorldMarker & {
+    note?: string;
+};
+/** The longest note a mark keeps; a longer one is cut. */
+export declare const MARK_NOTE_MAX = 600;
+export declare function markWorld(name: string, options?: WorldRootOptions & {
+    id?: string;
+    now?: Date;
+    note?: string;
+}): NotedMarker;
+/** Every mark recorded in a world, oldest first. */
+export declare function listWorldMarks(name: string, root?: string): NotedMarker[];
+/**
+ * The base a diff/changeset is taken against:
+ *   explicit `--base <id>` → that mark (which must belong to THIS world),
+ *   otherwise the world's most recent mark,
+ *   otherwise `world-boot` — position 0 on every ledger, i.e. everything this world recorded.
+ *
+ * `--base world-boot` is spellable explicitly, so "show me the whole session" never requires
+ * deleting marks.
+ */
+export declare function resolveBaseMarker(name: string, options?: WorldRootOptions & {
+    base?: string;
+}): WorldMarker;
+/** The world's ledger delta since `base` (default: the last mark, else world-boot). */
+export declare function diffWorld(name: string, options?: WorldRootOptions & {
+    base?: string;
+}): LedgerDelta;
+export type ChangesetLocation = {
+    changeset: Changeset;
+    world: string;
+    path: string;
+};
+/** Freeze the current delta into `<world>/changesets/<name>.json`. */
+export declare function createWorldChangeset(world: string, name: string, options?: WorldRootOptions & {
+    base?: string;
+    verifiers?: ChangesetVerifier[];
+    now?: Date;
+    overwrite?: boolean;
+    message?: string;
+}): Changeset;
+/** Every changeset in every world under `root` (or one world with `world`), newest first. */
+export declare function listWorldChangesets(options?: WorldRootOptions & {
+    world?: string;
+}): ChangesetLocation[];
+/** Resolve a bare changeset name across worlds. Ambiguity is an error, never a guess. */
+export declare function findWorldChangeset(name: string, options?: WorldRootOptions & {
+    world?: string;
+}): ChangesetLocation;
+/** Replay a changeset into `into`'s twins, through the control plane's kernel write path. */
+export declare function replayWorldChangeset(name: string, options: WorldRootOptions & {
+    into: string;
+    world?: string;
+}): Promise<ReplayReport>;
+export type VerifyWorldOutcome = {
+    changeset: Changeset;
+    verification: ChangesetVerification;
+    report: ReplayReport;
+    world: string;
+    path: string;
+};
+/** The label a throwaway verify target reports as `into` — not a world name on purpose. */
+export declare const EPHEMERAL_VERIFY_TARGET = "ephemeral";
+/**
+ * `volter-world changeset verify <name> --into <world> | --ephemeral`: replay the changeset
+ * into a clean target, run its verifiers against the post-replay projected state, and record
+ * the outcome ON the object as `verification` — REPLACING any prior run (the record carries
+ * its own provenance: when, into what, against which body hash and world digest). The body
+ * hash never moves: verification is about-the-body metadata, like approvals.
+ *
+ * `--ephemeral` builds a throwaway replay target (fresh empty ledgers per twin, no world
+ * booted), verifies against it, and removes it — the zero-setup CI check. `--into` verifies
+ * inside an existing world, whose twins must cover the changeset AND its verifiers.
+ */
+export declare function verifyWorldChangeset(name: string, options: WorldRootOptions & {
+    into?: string;
+    ephemeral?: boolean;
+    world?: string;
+    now?: Date;
+}): Promise<VerifyWorldOutcome>;
+export type ApproveWorldOutcome = {
+    changeset: Changeset;
+    approval: ChangesetApproval;
+    world: string;
+    path: string;
+};
+/** `volter-world changeset approve <name> --as <principal>`: append an approval bound to the
+ *  current body hash. The control plane refuses a drifted object loudly. */
+export declare function approveWorldChangeset(name: string, options: WorldRootOptions & {
+    principal: string;
+    note?: string;
+    world?: string;
+    now?: Date;
+}): ApproveWorldOutcome;
+/** `volter-world changeset status <name>`: the apply-readiness gate, recomputed from the
+ *  object. Truth only — pushing is v2's job. */
+export declare function statusWorldChangeset(name: string, options?: WorldRootOptions & {
+    world?: string;
+}): ChangesetReadiness;
+export type PushWorldOptions = WorldRootOptions & {
+    world?: string;
+    /** the remote's twins url and namespace; default to the world's recorded origin */
+    to?: string;
+    namespace?: string;
+    /** the namespace key (a push is a write; the read key is refused) */
+    key: string;
+    force?: boolean;
+};
+export type PushWorldOutcome = {
+    application: ChangesetApplication;
+    changeset: Changeset;
+    world: string;
+    path: string;
+    remote: {
+        url: string;
+        namespace: string;
+    }; /** the entries landed; these named records did not follow them (a warning, not a refusal) */
+    unsent?: string;
+};
+export declare function pushWorldChangeset(name: string, options: PushWorldOptions): Promise<PushWorldOutcome>;
+export type RebaseWorldOutcome = {
+    changeset: Changeset;
+    report: RebaseReport;
+    world: string;
+    path: string;
+};
+/** `volter-world changeset rebase <name>`: the merge onto the authoring world's moved mirror. */
+export declare function rebaseWorldChangeset(name: string, options?: WorldRootOptions & {
+    world?: string;
+    now?: Date;
+}): RebaseWorldOutcome;