@volter/world-core 2.0.0

package/dist/src/head.js

@@ -0,0 +1,313 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// THE HEAD — where a write is applied (company contract "The head", ruled 2026-09-06).
+//
+// Every write is an entry first. Then the twin's head says what happens to it: no root, or a root
+// under `gated`/`hold`, and the entry waits (simulated); a root under `auto`, and the entry is
+// PERFORMED NOW, in the process that serves the twin, before the app is answered — checks, then the
+// pack's perform adapter over the kernel executor with the credential opened from its seal, then
+// the landed copy with the receipt. The push door and `volter world deploy` perform through the
+// same `performEntries`; there is no hook and no phase ledger. The receipt on the entry is the
+// record: a `deployed` copy is never performed again, a `failed` one is retried.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { confirmAction, isTwinBookkeeping, resolveSubjectId, revertAction } from "./actions.js";
+import { openSealedCredential, sealCredential } from "./credential.js";
+import { buildRemoteExecute, validateRemoteOrigin } from "./executor.js";
+import { getPack } from "./packRegistry.js";
+import { aliasesFrom, branchEntries, parentEntries, readTree } from "./log.js";
+import { resolveReferences } from "./references.js";
+import { authStrategyFor, NO_SECRETS_CHECK, readRoot, runChecks, stateSystemFor } from "./state-system.js";
+import { stateDirName, worldPaths } from "./storage.js";
+import { worldNow } from "./world-clock.js";
+import { getActiveWorldStore } from "./world-store.js";
+export function performContext(service, root, credential) {
+    return { resolve: (type, localId) => resolveSubjectId(service, type, localId, root), service, ...(root !== undefined ? { root } : {}), ...(credential !== undefined ? { credential } : {}) };
+}
+/** The keyed fingerprint of the root's sealed credential, or undefined when none is sealed. */
+function rootCredentialFingerprint(root) {
+    const sealed = getActiveWorldStore().read(root.credential);
+    if (sealed === null)
+        return undefined;
+    const fingerprint = JSON.parse(sealed).fingerprint;
+    return typeof fingerprint === 'string' && fingerprint !== '' ? fingerprint : undefined;
+}
+// ── the user's key and the sealed credential ────────────────────────────────────────────────
+/** The user's key-encryption key: `$XDG_CONFIG_HOME/volter/kek` (created on first use). */
+export function userKekPath() {
+    const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME !== '' ? process.env.XDG_CONFIG_HOME : join(homedir(), '.config');
+    return join(base, 'volter', 'kek');
+}
+export function userKek() {
+    const path = userKekPath();
+    if (existsSync(path))
+        return readFileSync(path, 'utf8').trim();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const key = Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64');
+    writeFileSync(path, `${key}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return key;
+}
+/** Where the key that wraps every sealed credential comes from. A local World uses the user's key
+ *  file (`userKek`); a hosted World's host supplies its deployment's secret once at start. */
+let sealingKeySource = null;
+export function setSealingKeySource(source) { sealingKeySource = source; }
+export function sealingKey() { return sealingKeySource ? sealingKeySource() : userKek(); }
+/** Open the credential a root names, under the user's key. */
+export async function openRootCredential(root, vendor = vendorOf(root)) {
+    const sealed = getActiveWorldStore().read(root.credential);
+    if (sealed === null)
+        throw new Error(`no credential sealed for ${vendor} — \`printf '<token>' | volter twin ${vendor} credential\``);
+    return openSealedCredential(sealingKey(), JSON.parse(sealed), vendor);
+}
+/** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key and
+ *  slot. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the
+ *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. */
+export async function resealRootCredential(root, payload, vendor = vendorOf(root)) {
+    const store = getActiveWorldStore();
+    const held = store.read(root.credential);
+    const before = held === null ? null : JSON.parse(held);
+    const now = new Date().toISOString();
+    const sealed = await sealCredential(sealingKey(), payload, before?.placedAt ?? now, vendor);
+    store.write(root.credential, `${JSON.stringify({ ...sealed, ...(before ? { fingerprint: before.fingerprint } : {}), rotatedAt: now }, null, 2)}\n`, { secret: true });
+}
+/** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one. */
+export function rootCustody(root, vendor = vendorOf(root)) {
+    // the credential's identity: its path and its fingerprint, which a rotation keeps and a user's re-seal of another
+    // credential changes, so a token exchanged for one account never answers for the next
+    const held = getActiveWorldStore().read(root.credential);
+    const fingerprint = held === null ? '' : String(JSON.parse(held).fingerprint ?? '');
+    return { key: `${root.credential}#${fingerprint}`, open: () => openRootCredential(root, vendor), seal: (credential) => resealRootCredential(root, credential, vendor) };
+}
+/** The vendor a root belongs to: its credential is sealed under the vendor's name. */
+export function vendorOf(root) { return basename(root.credential, '.json'); }
+/** The world a root belongs to: the credential sits at `<world>/.volter/credentials/<vendor>.json`. */
+export function worldRootOf(root) { return resolve(dirname(root.credential), '..', '..'); }
+// ── the world's checks ──────────────────────────────────────────────────────────────────────
+/** The checks a world runs before any entry is performed: the shipped no-secrets check, then every
+ *  file under `.volter/checks/` exporting `{ name, run }`. */
+export async function loadChecks(worldRoot) {
+    const dir = join(resolve(worldRoot), stateDirName(), 'checks');
+    const out = [NO_SECRETS_CHECK];
+    for (const file of getActiveWorldStore().list(dir).filter((f) => /\.(ts|js|mjs)$/.test(f)).sort())
+        out.push(await checkLoader(join(dir, file), file.replace(/\.(ts|js|mjs)$/, '')));
+    return out;
+}
+const importCheck = async (path, name) => {
+    const mod = (await import(__rewriteRelativeImportExtension(path)));
+    const check = mod.check ?? mod.default;
+    if (!check || typeof check.run !== 'function')
+        throw new Error(`${path} must export a check { name, run }`);
+    return { name: check.name ?? name, run: check.run };
+};
+let checkLoader = importCheck;
+export function setCheckLoader(loader) { checkLoader = loader ?? importCheck; }
+/** One check file through the host's loader: what placing a check validates with. */
+export function loadCheck(path, name) { return checkLoader(path, name); }
+/** The root a state service under `root` is bound to — its own root.json, else a sibling state's
+ *  (slack records under `chat`; the root was written under `slack`). */
+export function boundRoot(service, root) {
+    const own = readRoot(service, root);
+    if (own?.credential)
+        return own;
+    const stateRoot = dirname(worldPaths(service, root).dir);
+    const store = getActiveWorldStore();
+    const states = store.list(stateRoot).filter((name) => store.stat(join(stateRoot, name))?.isDirectory);
+    for (const state of states) {
+        if (state === service)
+            continue;
+        const r = readRoot(state, root);
+        if (r?.credential)
+            return r;
+    }
+    return null;
+}
+/** What this twin's head does with a write. */
+export function headOf(service, root) {
+    const bound = boundRoot(service, root);
+    return bound ? { kind: 'real', deploy: bound.deploy, root: bound } : { kind: 'simulated' };
+}
+/** A check refused the write: the entry is in the log as refused; the pack answers in the vendor's error shape. */
+export class RefusedWriteError extends Error {
+    check;
+    reason;
+    actionId;
+    constructor(check, reason, actionId) {
+        super(`${check}: ${reason}`);
+        this.check = check;
+        this.reason = reason;
+        this.actionId = actionId;
+        this.name = 'RefusedWriteError';
+    }
+}
+/** The head could not be bound for a write that needed it (no credential sealed, no adapter registered,
+ *  no root): a server-side fault, answered as one. */
+export class HeadError extends Error {
+    constructor(message) { super(message); this.name = 'HeadError'; }
+}
+/** The vendor refused or failed the write: the entry is in the log as failed, with the vendor's words. */
+export class VendorWriteError extends Error {
+    actionId;
+    constructor(message, actionId) {
+        super(message);
+        this.actionId = actionId;
+        this.name = 'VendorWriteError';
+    }
+}
+/** The receipt a branch entry's latest landed copy carries, if any. */
+function receiptsByEntry(parent) {
+    const out = new Map();
+    for (const e of parent)
+        if (e.landsId && e.receipt)
+            out.set(e.landsId, e.receipt);
+    return out;
+}
+/** The branch entries a root twin still has to perform: `set` rows, not reverted, whose landed copy
+ *  is absent or says `failed`/`skipped` (a `deployed` or `refused` copy settles the entry). */
+export function deployableEntries(service, root) {
+    const parent = parentEntries(service, root);
+    const receipts = receiptsByEntry(parent);
+    const branch = branchEntries(service, root);
+    const reverted = new Set(branch.filter((e) => e.op === 'revert' && e.revertsActionId).map((e) => e.revertsActionId));
+    return branch.filter((e) => {
+        if (e.op !== 'set' || reverted.has(e.id) || isTwinBookkeeping(e))
+            return false;
+        const r = receipts.get(e.id);
+        return r === undefined || r.status === 'failed' || r.status === 'skipped';
+    });
+}
+const queues = new Map(); // one performer per twin: wire writes perform in append order
+/**
+ * PERFORM this twin's deployable entries against its root, in order, checks in front of every one,
+ * stopping at the first refusal or failure. Each outcome lands as the entry's copy with its receipt
+ * on the parent log. `actionIds` narrows to a changeset's (or one write's) entries.
+ */
+export async function performEntries(opts) {
+    const key = `${opts.root ?? ''}::${opts.service}`;
+    const prior = queues.get(key) ?? Promise.resolve();
+    const run = prior.then(() => performNow(opts), () => performNow(opts));
+    queues.set(key, run.catch(() => undefined));
+    return run;
+}
+async function performNow(opts) {
+    const { service, root } = opts;
+    const head = headOf(service, root);
+    if (head.kind !== 'real')
+        throw new Error(`the ${service} twin has no root — nothing to perform against`);
+    const vendor = vendorOf(head.root);
+    const adapters = opts.adapters ?? stateSystemFor(vendor) ?? stateSystemFor(service);
+    if (!adapters?.perform)
+        throw new Error(`the ${vendor} twin has no perform adapter — a protocol 2 pack names one in its descriptor and registers itself (registerPack)`);
+    const execute = opts.execute ?? buildRemoteExecute(validateRemoteOrigin(head.root.url, { allowInsecureLoopback: true }), await openRootCredential(head.root, vendor), authStrategyFor(vendor), getPack(vendor)?.hosts, { custody: rootCustody(head.root, vendor) });
+    const checks = opts.checks ?? (await loadChecks(worldRootOf(head.root)));
+    const deployable = deployableEntries(service, root);
+    const entries = opts.actionIds === undefined ? deployable : opts.actionIds.map((id) => deployable.find((a) => a.id === id)).filter((a) => a !== undefined);
+    const report = { pushed: 0, deployed: [], skipped: [], replayed: [] };
+    if (opts.actionIds) {
+        const settled = receiptsByEntry(parentEntries(service, root));
+        for (const id of opts.actionIds)
+            if (settled.get(id)?.status === 'deployed')
+                report.replayed.push(id);
+    }
+    let stopped = false;
+    for (const action of entries) {
+        if (stopped) {
+            report.skipped.push(action.id);
+            continue;
+        }
+        const at = opts.at ?? worldNow();
+        const verdict = await runChecks(checks, action, readTree(service, root));
+        if (verdict) {
+            confirmAction({ service, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: at, receipt: { status: 'refused', reason: `${verdict.name}: ${verdict.reason}` }, ...(root !== undefined ? { root } : {}) });
+            report.refused = { actionId: action.id, check: verdict.name, reason: verdict.reason };
+            stopped = true;
+            continue;
+        }
+        try {
+            // a declared reference to an adopted id is resolved before the pack sees the entry: the vendor is
+            // asked about #7, never the local #3 (docs/contributing/architecture.md#alias-aware-lookup-at-the-request-boundary)
+            const fields = resolveReferences(service, action.subject.type, action.fields ?? {}, aliasesFrom(parentEntries(service, root)));
+            const outcome = await adapters.perform(execute, fields === action.fields ? action : { ...action, fields }, performContext(service, root, rootCredentialFingerprint(head.root)));
+            // the vendor's answer, when the adapter returned one as fields, is what the landed copy holds
+            const answered = outcome.data !== null && typeof outcome.data === 'object' && !Array.isArray(outcome.data) ? outcome.data : {};
+            confirmAction({
+                service, actionId: action.id, subject: action.subject, fields: { ...fields, ...answered }, occurredAt: at,
+                ...(outcome.externalId ? { vendorSubjectId: outcome.externalId } : {}),
+                receipt: { status: 'deployed', ...(outcome.url ? { url: outcome.url } : {}) },
+                ...(root !== undefined ? { root } : {}),
+            });
+            report.pushed += 1;
+            report.deployed.push({ actionId: action.id, at, ...(outcome.externalId ? { externalId: outcome.externalId } : {}), ...(outcome.data !== undefined ? { data: outcome.data } : {}) });
+        }
+        catch (error) {
+            // a write the pack itself refuses (it can never be sent: its subject never reached the vendor) is
+            // settled as refused, as a check's refusal is, so the next deploy moves on to the entry after it;
+            // anything else failed and stays deployable for a retry
+            if (error instanceof RefusedWriteError) {
+                confirmAction({ service, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: at, receipt: { status: 'refused', reason: error.message }, ...(root !== undefined ? { root } : {}) });
+                report.refused = { actionId: action.id, check: error.check, reason: error.reason };
+                stopped = true;
+                continue;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            confirmAction({ service, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: at, receipt: { status: 'failed', reason: message }, ...(root !== undefined ? { root } : {}) });
+            report.failed = { actionId: action.id, error: message };
+            stopped = true;
+        }
+    }
+    return report;
+}
+/**
+ * The write path's second half (serve.ts): a write just appended to a twin whose head is real and
+ * `auto` is performed now. Returns the vendor's id when it minted one, so the answer carries it.
+ * Raises `RefusedWriteError` / `VendorWriteError` for the pack to answer in the vendor's shape.
+ */
+export async function performAtHead(service, action, root) {
+    const head = headOf(service, root);
+    if (head.kind !== 'real' || head.deploy !== 'auto')
+        return { performed: false };
+    let report;
+    try {
+        report = await performEntries({ service, actionIds: [action.id], ...(root !== undefined ? { root } : {}) });
+    }
+    catch (error) {
+        throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error));
+    }
+    // under live use an entry the vendor did not take does not stay in the tree: the app was told no, the
+    // world says no — a revert lands (the receipt stays on the original, so the log shows what happened)
+    const undone = report.refused?.actionId === action.id || report.failed?.actionId === action.id;
+    if (undone)
+        revertAction({ service, actionId: action.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+    if (report.refused?.actionId === action.id)
+        throw new RefusedWriteError(report.refused.check, report.refused.reason, action.id);
+    if (report.failed?.actionId === action.id)
+        throw new VendorWriteError(report.failed.error, action.id);
+    const done = report.deployed.find((d) => d.actionId === action.id);
+    return { performed: done !== undefined, ...(done?.externalId ? { externalId: done.externalId } : {}), ...(done?.data !== undefined ? { data: done.data } : {}) };
+}
+/** Wrap a pack's fetch: a `RefusedWriteError` or `VendorWriteError` the head raised becomes the
+ *  vendor's own error body (the pack's `shape`), so an app under live use sees what the vendor
+ *  would have said. Anything else propagates. */
+export function answerVendorErrors(fetch, shape) {
+    return async (request) => {
+        try {
+            return await fetch(request);
+        }
+        catch (error) {
+            if (error instanceof RefusedWriteError || error instanceof VendorWriteError)
+                return shape(error);
+            // a head that could not be bound is a server error, answered as one (never a runtime's fallback
+            // page); anything else the twin threw propagates as it always did
+            if (error instanceof HeadError)
+                return Response.json({ error: error.message }, { status: 500 });
+            throw error;
+        }
+    };
+}

package/dist/src/history.d.ts

@@ -0,0 +1,76 @@
+import { type Entry } from './log.js';
+export type HistoryLayout = {
+    base?: HistoryLayout;
+    parent: number;
+    branch: number;
+};
+type Segment = {
+    directory: string;
+    generation: string;
+    file: 'events.jsonl' | 'actions.jsonl' | 'origin.jsonl';
+    start: number;
+    count: number;
+    digest: string;
+};
+export type HistoryOrigin = {
+    at: string;
+    directory: string;
+    generation: string;
+    view: string;
+    position: number;
+    remoteView?: string;
+    depth: number;
+    incomplete?: boolean;
+};
+export type HistoryView = {
+    version: 1;
+    owner: {
+        directory: string;
+        generation: string;
+    };
+    layout: HistoryLayout;
+    segments: Segment[];
+    origin?: HistoryOrigin;
+};
+export type HistoryReference = {
+    view: string;
+    position: number;
+};
+export declare function validateHistoryOrigin(origin: HistoryOrigin, layout?: HistoryLayout): void;
+export declare const historyEntryTime: (entry: Entry) => number;
+export declare const historyDigest: (value: unknown) => string;
+export declare function historyLength(layout: HistoryLayout, depth?: number): number;
+export declare function readHistoryView(directory: string, id: string): HistoryView;
+export declare function historyEntries(view: HistoryView): Entry[];
+export declare function historyPrefix(view: HistoryView, at: number): HistoryView;
+export declare function saveHistoryView(directory: string, view: HistoryView): string;
+/** What an inherited history's content stands on, as file facts: every segment file the view names
+ *  (and the view document itself) and each named directory's ancestry record (its generation). A read cache keyed by this sees an
+ *  ancestor's retained history truncated, replaced or its directory re-created, which the full read
+ *  refuses (`historyEntries`), instead of serving a tree folded from the history it replaced. */
+export declare function inheritedHistoryKey(service: string, root?: string): string;
+export declare function inheritedHistory(service: string, root?: string): HistoryView | undefined;
+/** Capture under the same coordinator as append and complete observation batches. */
+export declare function captureHistory(service: string, root?: string): {
+    view: string;
+    position: number;
+    descriptor: HistoryView;
+};
+export declare function originHead(service: string, root?: string): {
+    view: string;
+    remoteView: string;
+} | null;
+/** A complete remote view shares cached rows by content, never by mutable offsets or entry ID. */
+export declare function publishOriginHistory(service: string, root: string, remoteView: string, layout: HistoryLayout, entries: Entry[]): {
+    view: string;
+    appended: number;
+};
+/** A changeset binds the complete inherited view, including this root's observations. */
+export declare function captureParentHistory(service: string, root?: string): HistoryReference;
+/** Compare evaluated views, so removals, reordered rows and layout changes count as drift. */
+export declare function historyChanges(service: string, before: HistoryView, after: HistoryView): Entry[];
+/** A timestamp can select across layers; represent it as a view, never a misleading offset. */
+export declare function historyAtInstant(service: string, instant: string, root?: string, selectedView?: string): HistoryReference;
+/** Replace only the tracked origin layer; inherited local layers keep their exact projection order. */
+export declare function replaceHistoryOrigin(previous: HistoryView, origin: HistoryOrigin, next: HistoryOrigin): HistoryView;
+export {};