worldvm 0.0.0-stage → 0.1.0

package/dist/handle/world.js

@@ -0,0 +1,533 @@
+import * as K from "../_internal/reconciler/index.js";
+import { explainReconciliation } from "../explain.js";
+import { memory } from "./store.js";
+import { operate } from "./protocol.js";
+export class WorldError extends Error {
+    code;
+    details;
+    constructor(code, message, details = []) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.details = details;
+        this.name = "WorldError";
+    }
+}
+const actor = (input) => typeof input === "string"
+    ? { id: input, kind: "human", groups: [] }
+    : { id: input.id, kind: input.kind ?? "human", groups: input.groups ?? [] };
+const newId = () => globalThis.crypto.randomUUID();
+export const host = async (options) => {
+    // An embedder owns the release: absent a public operation declaration, expose
+    // its declared actions and decisions. Explicit operation
+    // lists and component contracts retain the kernel's narrower surface.
+    const ir = {
+        ...options.ir,
+        components: options.ir.components.map((c) => c.operations !== undefined ||
+            options.ir.componentContracts?.some((x) => x.component === c.name)
+            ? c
+            : {
+                ...c,
+                operations: [
+                    ...c.actions.map((a) => a.name),
+                    ...(options.ir.decisions ?? []).filter((d) => d.of === c.name).map((d) => d.name),
+                ],
+            }),
+    };
+    const files = options.files ?? [], store = options.store ?? memory(), clock = options.clock ?? (() => new Date().toISOString());
+    if (!options.account && ir.accounts.length !== 1)
+        throw new WorldError("E_ACCOUNT", `This world declares ${ir.accounts.length} accounts; pass account: one of ${ir.accounts.map((a) => a.name).join(", ")}.`);
+    const account = options.account ?? ir.accounts[0].name;
+    if (!ir.accounts.some((a) => a.name === account))
+        throw new WorldError("E_ACCOUNT", `Account ${account} is not declared by this world.`);
+    const program = K.link(ir, account);
+    const entities = new Map([...program.entities.values()]
+        .filter((e) => e.ns.split(".")[0] === program.account.package.name)
+        .map((e) => [e.name, e]));
+    const loaded = await store.load();
+    if (loaded && loaded.release !== program.release && !options.activate)
+        throw new WorldError("E_RELEASE_CHANGED", `The store was written under release ${loaded.release}; this source is release ${program.release}. Preview the change with worldvm diff and impact, then open with activate: true.`);
+    let state = loaded
+        ? { ...loaded, release: program.release }
+        : { release: program.release, revision: 0, records: K.emptyWorld, receipts: {}, proposals: {} };
+    if (loaded && loaded.release !== program.release)
+        await store.commit(state);
+    const listeners = new Set();
+    const seen = new Map();
+    let closed = false;
+    // Writes run one at a time, so each command sees the commit before it.
+    let queue = Promise.resolve();
+    const serial = (f) => {
+        const run = queue.then(() => {
+            if (closed)
+                throw new WorldError("E_CLOSED", "This world has been closed.");
+            return f();
+        });
+        queue = run.catch(() => { });
+        return run;
+    };
+    const evaluate = (subject, at) => K.reconcileSubject(program, K.basis(state.records, at), subject);
+    const statusOf = (subject, recon, at) => {
+        const b = K.basis(state.records, at);
+        return {
+            subject,
+            at,
+            release: program.release,
+            revision: state.revision,
+            wakeAt: recon.wakeAt,
+            wakeReason: recon.wakeReason,
+            machines: [...recon.instances.values()]
+                .sort((a, b) => a.id.localeCompare(b.id))
+                .flatMap((inst) => (program.components.get(inst.component)?.machines ?? []).map((m) => {
+                const scope = K.resourceMachineScope(program, b, inst, m.name);
+                const history = b
+                    .history(inst.id, m.name)
+                    .filter((r) => !scope ||
+                    ((r.generation ?? 1) === scope.generation &&
+                        (r.account === undefined || r.account === scope.account)));
+                const current = K.machineState(b, inst.id, m.name, scope);
+                let since = null;
+                for (let i = history.length - 1; i >= 0 && history[i].state === current; i--)
+                    since = history[i].at;
+                return { instance: inst.id, machine: m.name, state: current, since };
+            })),
+            instances: [...recon.results]
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([instance, r]) => ({
+                instance,
+                component: r.component,
+                digest: r.digest,
+                outputs: Object.fromEntries(r.outputs.map((o) => [o.name, o.status])),
+                requirements: r.requirements.map((q) => ({
+                    name: q.name,
+                    label: q.label,
+                    status: q.status,
+                    due: q.due,
+                    blocked: r.blocked.find((b) => b.requirement === q.name)?.reason ?? null,
+                })),
+            })),
+        };
+    };
+    const workOf = (recon, subject) => [
+        ...[...recon.results].flatMap(([instance, r]) => {
+            const names = new Set(K.operationsFor(recon, account, { instance }).operations.map((o) => o.name));
+            return r.actions
+                .filter((a) => names.has(a.action))
+                .map((a) => ({
+                id: K.workItems(recon).find((w) => w.members.some((m) => m.instance === instance && m.action === a.action)).key,
+                instance,
+                operation: a.action,
+                label: a.label,
+                kind: a.kind,
+                state: a.state,
+                advances: a.advancesAll ?? [a.advances],
+                assignee: { id: a.assigneeId ?? null, kind: a.assigneeKind },
+                missing: a.missing,
+                fields: (a.fields ?? []).map((f) => ({
+                    field: f.field,
+                    mode: f.mode,
+                    value: f.value,
+                })),
+            }));
+        }),
+        ...Object.values(state.proposals)
+            .filter((p) => p.subject === subject && p.state === "pending")
+            .map((p) => ({
+            id: `proposal:${p.id}`,
+            proposal: p.id,
+            instance: "",
+            operation: "accept-proposal",
+            label: p.rationale,
+            kind: "proposal",
+            state: "eligible",
+            advances: [],
+            assignee: { id: null, kind: "entity" },
+            missing: [],
+            fields: [],
+        })),
+    ].sort((a, b) => a.id < b.id
+        ? -1
+        : a.id > b.id
+            ? 1
+            : a.instance < b.instance
+                ? -1
+                : a.instance > b.instance
+                    ? 1
+                    : 0);
+    const open = (work) => work.filter((w) => w.state === "eligible" || w.state === "dispatched");
+    const diff = (subject, before, after) => {
+        const flat = (s) => new Map((s?.instances ?? []).flatMap((i) => [
+            ...i.requirements.map((q) => [JSON.stringify([i.instance, "requirement", q.name]), q.status]),
+            ...Object.entries(i.outputs).map(([name, status]) => [JSON.stringify([i.instance, "output", name]), status]),
+        ]));
+        const was = flat(before?.status), is = flat(after.status);
+        const transitions = [...new Set([...was.keys(), ...is.keys()])]
+            .filter((key) => was.get(key) !== is.get(key))
+            .sort()
+            .map((key) => {
+            const [instance, kind, name] = JSON.parse(key);
+            return { instance, kind, name, from: was.get(key) ?? null, to: is.get(key) ?? null };
+        });
+        const key = (w) => JSON.stringify([w.id, w.instance, w.operation]);
+        const wasOpen = new Map(open(before?.work ?? []).map((w) => [key(w), w])), isOpen = new Map(open(after.work).map((w) => [key(w), w]));
+        return {
+            subject,
+            revision: after.status.revision,
+            at: after.status.at,
+            transitions,
+            opened: [...isOpen].filter(([k]) => !wasOpen.has(k)).map(([, w]) => w),
+            closed: [...wasOpen].filter(([k]) => !isOpen.has(k)).map(([, w]) => w),
+        };
+    };
+    const view = (subject, at) => {
+        const recon = evaluate(subject, at);
+        return {
+            recon,
+            snapshot: { status: statusOf(subject, recon, at), work: workOf(recon, subject) },
+        };
+    };
+    const emit = (change) => {
+        if (!change.transitions.length && !change.opened.length && !change.closed.length)
+            return;
+        for (const listener of listeners)
+            listener(change);
+    };
+    /** Run one command: replay its receipt, or apply it, commit, and report what changed. */
+    const write = (subject, request, apply) => serial(async () => {
+        const at = clock(), id = request.id ?? newId();
+        const digest = K.sha256(K.canonicalJson({
+            release: program.release,
+            subject,
+            // Drop undefined options so an omitted option and an absent one hash alike.
+            body: JSON.parse(JSON.stringify(request.body)),
+        }));
+        const before = view(subject, at);
+        const previous = seen.get(subject) ?? before.snapshot;
+        const replay = (receipt) => {
+            seen.set(subject, before.snapshot);
+            return {
+                accepted: receipt.accepted,
+                codes: receipt.codes,
+                status: before.snapshot.status,
+                change: diff(subject, before.snapshot, before.snapshot),
+            };
+        };
+        const receipt = Object.hasOwn(state.receipts, id) ? state.receipts[id] : undefined;
+        if (receipt) {
+            if (receipt.digest !== digest)
+                return replay({ accepted: false, codes: ["command-duplicate"] });
+            return receipt.outcome;
+        }
+        const result = apply(before.recon, at, id);
+        let records = result.records;
+        if (result.accepted && records.facts.length > state.records.facts.length)
+            records = {
+                ...records,
+                facts: records.facts.map((f, index) => index < state.records.facts.length ? f : { ...f, command: id }),
+            };
+        if (result.accepted)
+            records = K.recordMilestones(K.reconcileSubject(program, K.basis(records, at), subject), records);
+        const next = {
+            release: program.release,
+            revision: state.revision + 1,
+            records,
+            proposals: result.proposals ?? state.proposals,
+            receipts: state.receipts,
+        };
+        // Compute the receipt against the candidate state, then persist both atomically.
+        const prior = state;
+        let after;
+        try {
+            state = next;
+            after = view(subject, at).snapshot;
+        }
+        finally {
+            state = prior;
+        }
+        const change = diff(subject, previous, after);
+        const outcome = {
+            accepted: result.accepted,
+            codes: result.codes,
+            status: after.status,
+            change,
+        };
+        const committed = {
+            ...next,
+            receipts: {
+                ...next.receipts,
+                [id]: { digest, accepted: result.accepted, codes: result.codes, outcome },
+            },
+        };
+        await store.commit(committed);
+        state = committed;
+        seen.set(subject, after);
+        emit(change);
+        return outcome;
+    });
+    const subject = (type, id) => {
+        const entity = entities.get(type);
+        if (!entity)
+            throw new WorldError("E_ENTITY", `Account ${account} declares no entity ${type}. Declared: ${[...entities.keys()].join(", ")}.`);
+        if (!id.trim())
+            throw new WorldError("E_ENTITY", "A subject id must be nonempty.");
+        const target = (recon, has, wanted) => {
+            const matches = [...recon.results.keys()].filter((i) => (!wanted || i === wanted) && has(i));
+            return matches.length === 1
+                ? matches[0]
+                : [matches.length ? "operation-ambiguous" : "operation-target"];
+        };
+        const refused = (...codes) => ({ accepted: false, codes, records: state.records });
+        const assertFacts = (values, options, recon, at) => {
+            const by = actor(options.by);
+            if (by.kind === "agent")
+                return refused("human-required");
+            const names = Object.keys(values);
+            if (!names.length)
+                return refused("fact-input");
+            const facts = names.map((name) => ({
+                name,
+                field: entity.fields.find((f) => f.name === name),
+                value: values[name],
+            }));
+            const invalid = facts.filter((f) => !f.field || !K.validFact(program, state.records, id, f.field.attr, f.value, at));
+            if (invalid.length)
+                return refused(...invalid.map((f) => `fact-invalid:${f.name}`));
+            const result = K.command(recon, state.records, at, {
+                kind: options.kind ?? "fact",
+                subject: id,
+                title: `Recorded ${type} ${names.join(", ")}`,
+                by: by.id,
+                facts: facts.map((f) => ({ e: id, a: f.field.attr, v: f.value })),
+            });
+            return {
+                accepted: !result.violations.length,
+                codes: result.violations.map((v) => v.invariant),
+                records: result.world,
+            };
+        };
+        const performOperation = (operation, options, recon, at, command) => {
+            const { by, id: _commandId, instance, ...input } = options;
+            if (actor(by).kind === "agent" && !input.unsigned)
+                return refused("human-required");
+            const item = workOf(recon).find((w) => w.id === operation && (!instance || w.instance === instance));
+            const name = item?.operation ?? operation;
+            const found = target(recon, (i) => K.operationsFor(recon, account, { instance: i }).operations.some((o) => o.name === name), instance ?? item?.instance);
+            if (typeof found !== "string")
+                return refused(...found);
+            const result = K.invokeOperation(recon, state.records, at, {
+                id: command,
+                account,
+                target: { instance: found },
+                operation: name,
+                actor: actor(by),
+                ...input,
+            });
+            return { accepted: result.accepted, codes: result.codes, records: result.world };
+        };
+        const resolveProposal = (proposal, options, reason) => write(id, {
+            id: options.id,
+            body: [
+                reason === undefined ? "accept-proposal" : "reject-proposal",
+                type,
+                proposal,
+                reason,
+                options.signature,
+                actor(options.by),
+            ],
+        }, (recon, at, command) => {
+            const by = actor(options.by);
+            if (by.kind !== "human")
+                return refused("human-required");
+            const p = Object.hasOwn(state.proposals, proposal)
+                ? state.proposals[proposal]
+                : undefined;
+            if (!p || p.type !== type || p.subject !== id)
+                return refused("not-found");
+            if (p.state !== "pending")
+                return refused("proposal-resolved");
+            if (reason !== undefined && !reason.trim())
+                return refused("proposal-input");
+            const draft = p.draft;
+            const result = reason !== undefined
+                ? { accepted: true, codes: [], records: state.records }
+                : draft.kind === "assert"
+                    ? assertFacts(draft.values, { by, ...(draft.factKind ? { kind: draft.factKind } : {}) }, recon, at)
+                    : performOperation(draft.operation, {
+                        by,
+                        values: draft.values,
+                        ...(options.signature ? { signature: options.signature } : {}),
+                        ...(draft.instance ? { instance: draft.instance } : {}),
+                    }, recon, at, command);
+            if (!result.accepted)
+                return result;
+            const resolved = {
+                ...p,
+                state: reason === undefined ? "accepted" : "rejected",
+                resolution: { by, at, command, ...(reason === undefined ? {} : { reason }) },
+            };
+            // The durable proposal cites the command; the write's audit journal cites the proposal.
+            return {
+                ...result,
+                records: {
+                    ...result.records,
+                    journal: [
+                        ...result.records.journal,
+                        {
+                            id: `proposal:${command}`,
+                            at,
+                            actor: by.id,
+                            title: `${resolved.state} proposal ${proposal}`,
+                            context: proposal,
+                            changes: [],
+                        },
+                    ],
+                },
+                proposals: { ...state.proposals, [proposal]: resolved },
+            };
+        });
+        return {
+            type,
+            id,
+            proposals: () => Object.values(state.proposals).filter((p) => p.type === type && p.subject === id),
+            propose: (draft, rationale, options) => write(id, { id: options.id, body: ["propose", type, draft, rationale, actor(options.by)] }, (_recon, at, command) => {
+                const by = actor(options.by);
+                if (by.kind !== "agent")
+                    return refused("forbidden");
+                if (!rationale.trim())
+                    return refused("proposal-input");
+                if (draft.kind === "evidence") {
+                    const recon = evaluate(id, at);
+                    const item = workOf(recon).find((w) => (w.operation === draft.operation || w.id === draft.operation) &&
+                        (!draft.instance || draft.instance === w.instance));
+                    if (!item || item.kind !== "interaction")
+                        return refused("operation-target");
+                }
+                const proposal = {
+                    id: command,
+                    type,
+                    subject: id,
+                    by,
+                    at,
+                    rationale,
+                    draft: structuredClone(draft),
+                    state: "pending",
+                };
+                return {
+                    accepted: true,
+                    codes: [],
+                    records: state.records,
+                    proposals: { ...state.proposals, [command]: proposal },
+                };
+            }),
+            acceptProposal: (proposal, options) => resolveProposal(proposal, options),
+            rejectProposal: (proposal, reason, options) => resolveProposal(proposal, options, reason),
+            assert: (values, options) => write(id, { id: options.id, body: ["assert", type, values, options.kind, actor(options.by)] }, (recon, at) => assertFacts(values, options, recon, at)),
+            perform: (operation, options) => {
+                const { by, id: commandId, instance, ...input } = options;
+                return write(id, { id: commandId, body: ["perform", type, operation, instance ?? null, input, actor(by)] }, (recon, at, command) => performOperation(operation, options, recon, at, command));
+            },
+            signal: (machine, to, options) => write(id, {
+                id: options.id,
+                body: ["signal", type, machine, to, options.instance ?? null, actor(options.by)],
+            }, (recon, at) => {
+                if (actor(options.by).kind === "agent")
+                    return refused("human-required");
+                const found = target(recon, (i) => !!program.components
+                    .get(recon.instances.get(i).component)
+                    ?.machines.some((m) => m.name === machine), options.instance);
+                if (typeof found !== "string")
+                    return { accepted: false, codes: found, records: state.records };
+                const accepted = K.canTransition(program, K.basis(state.records, at), recon.instances.get(found), machine, to);
+                // A refused signal is still journaled, so the rejection itself is on the record.
+                const records = K.signal(recon, state.records, at, {
+                    instance: found,
+                    machine,
+                    state: to,
+                    by: actor(options.by).id,
+                });
+                return { accepted, codes: accepted ? [] : ["transition"], records };
+            }),
+            facts: (at = clock()) => {
+                const b = K.basis(state.records, at);
+                return entity.fields
+                    .flatMap((field) => {
+                    const f = b.fact(id, field.attr);
+                    return f
+                        ? [{ fact: f.a, value: f.v, by: f.by, at: f.at, command: f.command ?? null }]
+                        : [];
+                })
+                    .sort((a, b) => a.fact.localeCompare(b.fact));
+            },
+            status: (at = clock()) => view(id, at).snapshot.status,
+            work: (at = clock()) => view(id, at).snapshot.work,
+            operations: (at = clock()) => {
+                const recon = evaluate(id, at);
+                return [...recon.results.keys()].sort().flatMap((instance) => K.operationsFor(recon, account, { instance }).operations.map((o) => ({
+                    instance,
+                    name: o.name,
+                    kind: o.kind,
+                    state: o.state,
+                })));
+            },
+            explain: (requirement, at = clock()) => explainReconciliation(ir, files, evaluate(id, at), null)
+                .instances.flatMap((i) => i.requirements)
+                .filter((q) => !requirement || q.name === requirement),
+        };
+    };
+    const subjects = (type) => {
+        const entity = entities.get(type);
+        if (!entity)
+            throw new WorldError("E_ENTITY", `Account ${account} declares no entity ${type}.`);
+        return [
+            ...new Set(state.records.facts.filter((f) => f.a.startsWith(entity.ns + "/")).map((f) => f.e)),
+        ].sort();
+    };
+    // Seed time-dependent projections before the application reads any subject.
+    const openedAt = clock();
+    for (const type of entities.keys())
+        for (const id of subjects(type))
+            seen.set(id, view(id, openedAt).snapshot);
+    const world = {
+        canRead: (actor, type, subject) => options.canRead?.({ actor, type, subject }) ?? true,
+        request: (verb, input, by) => operate(world, verb, input, by),
+        proposals: () => Object.values(state.proposals),
+        account,
+        release: program.release,
+        revision: () => state.revision,
+        now: clock,
+        types: [...entities.keys()].sort(),
+        subject,
+        subjects,
+        tick: () => serial(async () => {
+            const at = clock(), changes = [];
+            for (const type of entities.keys())
+                for (const id of subjects(type)) {
+                    const after = view(id, at).snapshot, before = seen.get(id);
+                    seen.set(id, after);
+                    // The first sighting is a baseline; there is nothing to compare it with.
+                    if (!before)
+                        continue;
+                    const change = diff(id, before, after);
+                    if (change.transitions.length || change.opened.length || change.closed.length) {
+                        changes.push(change);
+                        emit(change);
+                    }
+                }
+            return changes;
+        }),
+        nextWake: () => [...seen.values()]
+            .flatMap((s) => (s.status.wakeAt ? [s.status.wakeAt] : []))
+            .sort(K.compareTime)[0] ?? null,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => void listeners.delete(listener);
+        },
+        records: () => state.records,
+        close: async () => {
+            await queue;
+            closed = true;
+            listeners.clear();
+            await store.close();
+        },
+    };
+    return world;
+};

package/dist/http.d.ts

@@ -0,0 +1,3 @@
+import type { World } from "./handle/world.js";
+/** Dev-only trusted actor header. Authenticate and replace this header at a trusted boundary. */
+export declare const createHandler: (world: World) => ((request: Request) => Promise<Response>);

package/dist/http.js

@@ -0,0 +1,72 @@
+import { decodeActor, verbs } from "./_internal/protocol/index.js";
+import { failure } from "./handle/protocol.js";
+const json = (value, status = 200) => Response.json(value, { status });
+const httpStatus = (code) => ({
+    "invalid-request": 400,
+    unauthenticated: 401,
+    forbidden: 403,
+    "human-required": 403,
+    "not-found": 404,
+    internal: 500,
+})[code] ?? 409;
+/** Dev-only trusted actor header. Authenticate and replace this header at a trusted boundary. */
+export const createHandler = (world) => async (request) => {
+    const url = new URL(request.url);
+    const name = url.pathname.match(/^\/v1\/([^/]+)$/)?.[1];
+    if (!name || !verbs.includes(name))
+        return json(failure("not-found", "Unknown protocol verb."), 404);
+    let by;
+    try {
+        by = decodeActor(JSON.parse(request.headers.get("x-worldvm-actor") ?? "null"));
+    }
+    catch {
+        return json(failure("unauthenticated", "x-worldvm-actor must contain a trusted actor JSON object."), 401);
+    }
+    if (request.method === "GET" && name === "changes") {
+        let cleanup = () => { };
+        const body = new ReadableStream({
+            start(controller) {
+                const encoder = new TextEncoder();
+                let ended = false;
+                const unsubscribe = world.subscribe((change) => {
+                    if (!ended)
+                        controller.enqueue(encoder.encode(`event: change\ndata: ${JSON.stringify(change)}\n\n`));
+                });
+                const abort = () => {
+                    cleanup();
+                    controller.close();
+                };
+                cleanup = () => {
+                    ended = true;
+                    unsubscribe();
+                    request.signal.removeEventListener("abort", abort);
+                };
+                controller.enqueue(encoder.encode(": worldvm changes; live events only\n\n"));
+                request.signal.addEventListener("abort", abort, { once: true });
+                if (request.signal.aborted)
+                    abort();
+            },
+            cancel() {
+                cleanup();
+            },
+        });
+        return new Response(body, {
+            headers: {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            },
+        });
+    }
+    if (request.method !== "POST")
+        return json(failure("invalid-request", "Use POST /v1/<verb> or GET /v1/changes."), 405);
+    let input;
+    try {
+        input = await request.json();
+    }
+    catch {
+        return json(failure("invalid-request", "Expected a JSON request body."), 400);
+    }
+    const result = await world.request(name, input, by);
+    return json(result, result.ok ? 200 : httpStatus(result.error.code));
+};

package/dist/impact.d.ts

@@ -0,0 +1,21 @@
+import { type CliDiagnostic } from "./project.js";
+import { type Impact } from "./release/impact.js";
+import type { SidedDiagnostic } from "./diff.js";
+export interface ImpactOptions {
+    /** A `worldvm/world@1` snapshot: the population to preview against. */
+    readonly world: string;
+    /** Evaluation instant; the CLI never reads the clock. */
+    readonly at: string;
+}
+export interface ImpactReport {
+    readonly format: "worldvm/impact-report@1";
+    readonly command: "impact";
+    readonly old: string;
+    readonly new: string;
+    readonly snapshot: string;
+    /** False on compile, snapshot or evaluation failure, and when a change escaped the selection. */
+    readonly ok: boolean;
+    readonly diagnostics: readonly (CliDiagnostic | SidedDiagnostic)[];
+    readonly impact: Impact | null;
+}
+export declare const impactDirectories: (before: string, after: string, options: ImpactOptions) => Promise<ImpactReport>;