@kestack/kabuki 0.0.0-stage → 0.0.1

package/dist/core/runtime/mailbox.js

@@ -0,0 +1,64 @@
+/*
+ * The one Mailbox. A Message is stamped with its Time and handled before
+ * `send` returns, unless another is being handled (a Worker sending as it
+ * starts, say): then it waits its turn, so every Message sees a settled app
+ * and Times only grow along the queue. Subscribers are told once the queue
+ * is empty: many Messages make one render. A Message sent while the Mailbox
+ * is closed is dropped. One whose Update gives data that does not match its
+ * Schemas changes nothing; the rest of the queue is still handled, then the
+ * `send` that drained it throws.
+ */
+export const makeMailbox = (now, deliver, drained) => {
+    const waiting = [];
+    let open = false;
+    let busy = false;
+    const drain = () => {
+        if (busy)
+            return;
+        busy = true;
+        let failed;
+        try {
+            for (let next = waiting.shift(); next; next = waiting.shift())
+                try {
+                    deliver(next);
+                }
+                catch (error) {
+                    failed ??= { error };
+                }
+        }
+        finally {
+            busy = false;
+        }
+        drained();
+        if (failed)
+            throw failed.error;
+    };
+    return {
+        open: () => {
+            open = true;
+        },
+        close: () => {
+            open = false;
+            waiting.length = 0;
+        },
+        send: (destination, message, source) => {
+            if (!open)
+                return;
+            waiting.push({ destination, message, source, at: now() });
+            drain();
+        },
+        /** Run `f` without handling Messages, then handle what it sent. */
+        hold: (f) => {
+            const draining = busy;
+            busy = true;
+            try {
+                f();
+            }
+            finally {
+                busy = draining;
+                if (!draining)
+                    drain();
+            }
+        },
+    };
+};

package/dist/core/runtime/runtime.d.ts

@@ -0,0 +1,36 @@
+import { Effect, Layer } from 'effect';
+import type { Scope } from 'effect';
+import type { AnyActor, Tagged, Types } from '../actor/index.ts';
+import type { Snapshot, Source } from '../snapshot/index.ts';
+import { History } from '../history/index.ts';
+import type { WorkerStatus } from './instance/index.ts';
+/** Capabilities an Actor's tree still needs from the app's Layer. */
+export type Needs<A> = Types<A>['open'];
+/** The app's Layer, which must cover every Capability the tree still needs. */
+type LayerFor<A> = [Needs<A>] extends [never] ? [layer?: Layer.Layer<never>] : [layer: Layer.Layer<Needs<A>>];
+export interface Running<A> {
+    readonly history: History<A>;
+    /** The live Snapshot; the last one while stopped. */
+    readonly snapshot: () => Snapshot;
+    readonly running: () => boolean;
+    /** The Time now, in milliseconds. It stands still while stopped. */
+    readonly now: () => number;
+    /** Hand a Message to any Instance, from outside the tree unless said otherwise. Dropped while stopped. */
+    readonly send: (instance: string, message: Tagged & {
+        readonly [field: string]: unknown;
+    }, source?: Source) => void;
+    /** Called once the Mailbox is empty, and on every start and stop. */
+    readonly subscribe: (listener: () => void) => () => void;
+    /** What an Instance's Workers are doing now. Empty while stopped. */
+    readonly workers: (instance: string) => ReadonlyArray<WorkerStatus>;
+    /** Start at the Head, or move the Head to an entry first (`null`: init). Stops first if running. */
+    readonly start: (from?: number | null) => Effect.Effect<void>;
+    readonly stop: () => Effect.Effect<void>;
+}
+declare const start: <A extends AnyActor>(from: A | History<A>, ...layer: LayerFor<A>) => Effect.Effect<Running<A>, never, Scope.Scope>;
+/** Runs an Actor, or carries a History on, until its Scope closes. */
+export declare const Runtime: {
+    start: typeof start;
+};
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/core/runtime/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,MAAM,EAAS,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAEjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAa,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAoBxD,qEAAqE;AACrE,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAExC,+EAA+E;AAC/E,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACzC,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAC5B,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnC,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,QAAQ,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,0GAA0G;IAC1G,QAAQ,CAAC,IAAI,EAAE,CACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,EACvD,MAAM,CAAC,EAAE,MAAM,KACZ,IAAI,CAAC;IACV,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IACzD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,aAAa,CAAC,YAAY,CAAC,CAAC;IACpE,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,QAAA,MAAM,KAAK,GAAI,CAAC,SAAS,QAAQ,QACzB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,YACV,QAAQ,CAAC,CAAC,CAAC,KACpB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAgH3C,CAAC;AAEL,sEAAsE;AACtE,eAAO,MAAM,OAAO;;CAAY,CAAC"}

package/dist/core/runtime/runtime.js

@@ -0,0 +1,93 @@
+import { Clock, Context, Effect, Fiber, Layer } from 'effect';
+import { actorAt, isRestore } from '../snapshot/index.js';
+import { History, isHistory } from '../history/index.js';
+import { ActorInstance } from './instance/index.js';
+import { makeMailbox } from './mailbox.js';
+import { makeTime } from './time.js';
+const start = (from, ...layer) => Effect.gen(function* () {
+    const history = isHistory(from) ? from : History.make(from);
+    const root = history.actor.definition;
+    const scope = yield* Effect.scope;
+    const clock = yield* Clock.Clock;
+    const built = yield* Layer.build(layer[0] ?? Layer.empty);
+    const services = Context.add(built, Clock.Clock, clock);
+    const time = makeTime(() => clock.monotonicTimeNanosUnsafe());
+    const listeners = new Set();
+    const notify = () => listeners.forEach((listener) => listener());
+    let snapshot;
+    let instance;
+    let release = () => { };
+    const mailbox = makeMailbox(time.now, (envelope) => {
+        const handled = instance.receive(envelope);
+        snapshot = handled.snapshot;
+        history.append(envelope, handled);
+    }, notify);
+    // 2. Send
+    const send = (id, message, source) => {
+        if (!isRestore(message))
+            actorAt(root, snapshot, id)?.check.message(message, `Message ${JSON.stringify(message._tag)}`);
+        mailbox.send(id, message, source);
+    };
+    // 1. Start
+    const go = Effect.gen(function* () {
+        snapshot = yield* history.seek();
+        time.start(history.branch().at(-1)?.at ?? 0);
+        release = history.lock();
+        mailbox.open();
+        mailbox.hold(() => {
+            instance = ActorInstance.start(root, snapshot, { send, now: time.now, services }, scope);
+        });
+        notify();
+    });
+    // 3. Stop
+    const halt = Effect.suspend(() => {
+        if (!instance)
+            return Effect.void;
+        const stopping = instance;
+        instance = undefined;
+        mailbox.close();
+        time.stop();
+        release();
+        notify();
+        return stopping.stop();
+    });
+    const restart = (from) => Effect.gen(function* () {
+        yield* halt;
+        if (from !== undefined)
+            history.moveHead(from);
+        yield* go;
+    });
+    /** A new start or stop interrupts the one still under way. */
+    let current;
+    let closed = false;
+    const latest = (effect) => Effect.suspend(() => {
+        if (closed)
+            return Effect.void;
+        current?.interruptUnsafe();
+        const fiber = Effect.runForkWith(services)(effect);
+        current = fiber;
+        return Fiber.join(fiber);
+    });
+    yield* go;
+    yield* Effect.addFinalizer(() => Effect.suspend(() => {
+        closed = true;
+        current?.interruptUnsafe();
+        return halt;
+    }));
+    return {
+        history,
+        snapshot: () => snapshot,
+        running: () => instance !== undefined,
+        now: time.now,
+        send: (id, message, source = { kind: 'outside' }) => send(id, message, source),
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        workers: (id) => instance?.workers(id) ?? [],
+        start: (from) => latest(restart(from)),
+        stop: () => latest(halt),
+    };
+});
+/** Runs an Actor, or carries a History on, until its Scope closes. */
+export const Runtime = { start };

package/dist/core/runtime/time.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The app's Time, in milliseconds: a starting Time plus what the clock has run
+ * since. Stopped, it stands still, and time spent stopped is never counted.
+ */
+export declare const makeTime: (nanos: () => bigint) => {
+    now: () => number;
+    /** Carry on from `from`, counting from now. */
+    start: (from: number) => void;
+    stop: () => void;
+};
+//# sourceMappingURL=time.d.ts.map

package/dist/core/runtime/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/time.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,QAAQ,UAAW,MAAM,MAAM;;IAOxC,+CAA+C;kBACjC,MAAM;;CASvB,CAAC"}

package/dist/core/runtime/time.js

@@ -0,0 +1,22 @@
+/**
+ * The app's Time, in milliseconds: a starting Time plus what the clock has run
+ * since. Stopped, it stands still, and time spent stopped is never counted.
+ */
+export const makeTime = (nanos) => {
+    let base = 0;
+    let origin = nanos();
+    let stoppedAt = 0;
+    const now = () => stoppedAt ?? base + Number(nanos() - origin) / 1_000_000;
+    return {
+        now,
+        /** Carry on from `from`, counting from now. */
+        start: (from) => {
+            base = from;
+            origin = nanos();
+            stoppedAt = undefined;
+        },
+        stop: () => {
+            stoppedAt = now();
+        },
+    };
+};

package/dist/core/snapshot/handle.d.ts

@@ -0,0 +1,14 @@
+import type { ActorDefinition } from '../actor/index.ts';
+import type { Envelope, Snapshot } from './snapshot.ts';
+/** What handling one Envelope did. Never kept in the History: handling it again says the same. */
+export interface Handled {
+    readonly outcome: 'handled' | 'ignored' | 'dropped';
+    /** The State tag before and after; empty when dropped. */
+    readonly from: string;
+    readonly to: string;
+    readonly snapshot: Snapshot;
+    /** The Commands the Update asked for, to run in the Instance it was for. */
+    readonly commands: ReadonlyArray<unknown>;
+}
+export declare const handle: (root: ActorDefinition, snapshot: Snapshot, { destination: id, message, at }: Envelope) => Handled;
+//# sourceMappingURL=handle.d.ts.map

package/dist/core/snapshot/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../../src/core/snapshot/handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,KAAK,EAAE,QAAQ,EAAY,QAAQ,EAAE,MAAM,eAAe,CAAC;AAsBlE,kGAAkG;AAClG,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACpD,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CAC3C;AAQD,eAAO,MAAM,MAAM,SACX,eAAe,YACX,QAAQ,oCACgB,QAAQ,KACzC,OA6CF,CAAC"}

package/dist/core/snapshot/handle.js

@@ -0,0 +1,70 @@
+import { Array as Arr } from 'effect';
+import { enter, follow } from './invoke.js';
+import { checkRestore, isRestore } from './restore.js';
+import { pathTo, replace } from './tree.js';
+const nothing = (snapshot, outcome, tag = '') => ({ outcome, from: tag, to: tag, snapshot, commands: [] });
+export const handle = (root, snapshot, { destination: id, message, at }) => {
+    if (isRestore(message))
+        return restored(root, snapshot, id, message);
+    // 1. Find
+    const path = pathTo(root, snapshot, id);
+    if (!path)
+        return nothing(snapshot, 'dropped');
+    const { instance, definition } = path.at(-1);
+    const from = instance.state._tag;
+    // 2. Update
+    const rule = (definition.update[from]?.[message._tag] ??
+        definition.update['*']?.[message._tag]);
+    if (!rule)
+        return nothing(snapshot, 'ignored', from);
+    const next = rule(message, {
+        model: instance.model,
+        state: instance.state,
+        props: instance.props,
+        at,
+    });
+    const by = `the Update for ${JSON.stringify(message._tag)} in ${from} gave ${id}`;
+    if (next.model !== undefined && next.model !== instance.model)
+        definition.check.model(next.model, `the Model ${by}`);
+    if (next.state !== undefined && next.state !== instance.state)
+        definition.check.state(next.state, `the State ${by}`);
+    // 3. Apply
+    const model = next.model ?? instance.model;
+    const state = next.state ?? instance.state;
+    const changed = model !== instance.model || state !== instance.state;
+    const after = !changed
+        ? instance
+        : state._tag !== from
+            ? enter(definition, { ...instance, model, state })
+            : follow(definition, { ...instance, model, state });
+    // 4. Replace
+    return {
+        outcome: 'handled',
+        from,
+        to: state._tag,
+        snapshot: after === instance ? snapshot : replace(path, after),
+        commands: next.command === undefined ? [] : Arr.ensure(next.command),
+    };
+};
+const warned = new WeakSet();
+const restored = (root, snapshot, id, message) => {
+    const from = snapshot.state._tag;
+    if (id !== snapshot.id)
+        return nothing(snapshot, 'dropped');
+    const checked = checkRestore(root, message);
+    if ('reason' in checked) {
+        if (!warned.has(message)) {
+            warned.add(message);
+            console.warn(`[@kestack/kabuki] a Restore no longer matches ${root.name}, and is ignored: ${checked.reason}`);
+        }
+        return nothing(snapshot, 'ignored', from);
+    }
+    const after = checked.snapshot;
+    return {
+        outcome: 'handled',
+        from,
+        to: after.state._tag,
+        snapshot: after,
+        commands: [],
+    };
+};

package/dist/core/snapshot/index.d.ts

@@ -0,0 +1,8 @@
+export { init } from './snapshot.ts';
+export type { Envelope, Instance, Snapshot, Source } from './snapshot.ts';
+export { handle } from './handle.ts';
+export type { Handled } from './handle.ts';
+export { actorAt, instanceAt, isMany, within } from './tree.ts';
+export { RESTORE, isRestore, restore } from './restore.ts';
+export type { Restore } from './restore.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/snapshot/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/snapshot/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/core/snapshot/index.js

@@ -0,0 +1,4 @@
+export { init } from './snapshot.js';
+export { handle } from './handle.js';
+export { actorAt, instanceAt, isMany, within } from './tree.js';
+export { RESTORE, isRestore, restore } from './restore.js';

package/dist/core/snapshot/invoke.d.ts

@@ -0,0 +1,17 @@
+import type { ActorDefinition } from '../actor/index.ts';
+import type { Instance } from './snapshot.ts';
+/** What a parent hands one Child: its Input, read once by init, and its Props, read live. */
+type Given = {
+    readonly input?: unknown;
+    readonly props?: unknown;
+};
+export declare const create: (definition: ActorDefinition, id: string, key: string | undefined, { input, props }: Given) => Instance;
+/**
+ * Enter the Instance's State: every Child the State writes is Invoked fresh.
+ * A Child written at the top lasts through the Transition; then every Child
+ * follows the parent's data.
+ */
+export declare const enter: (definition: ActorDefinition, instance: Instance) => Instance;
+export declare const follow: (definition: ActorDefinition, instance: Instance) => Instance;
+export {};
+//# sourceMappingURL=invoke.d.ts.map

package/dist/core/snapshot/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../../src/core/snapshot/invoke.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAmB9C,6FAA6F;AAC7F,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAMpE,eAAO,MAAM,MAAM,eACL,eAAe,MACvB,MAAM,OACL,MAAM,GAAG,SAAS,oBACL,KAAK,KACtB,QAkBF,CAAC;AAGF;;;;GAIG;AACH,eAAO,MAAM,KAAK,eACJ,eAAe,YACjB,QAAQ,KACjB,QA0BF,CAAC;AAGF,eAAO,MAAM,MAAM,eACL,eAAe,YACjB,QAAQ,KACjB,QAmCF,CAAC"}

package/dist/core/snapshot/invoke.js

@@ -0,0 +1,119 @@
+import { Equal } from 'effect';
+import { childId, counterOf } from './tree.js';
+const SINGLE = { _tag: 'Single' };
+// 1. Create
+export const create = (definition, id, key, { input, props }) => {
+    definition.check.input(input, `the Input of ${id}`);
+    definition.check.props(props, `the Props of ${id}`);
+    const init = definition.init(input);
+    const model = init.model ?? {};
+    const state = init.state ?? SINGLE;
+    definition.check.model(model, `the Model init gave ${id}`);
+    definition.check.state(state, `the State init gave ${id}`);
+    return enter(definition, {
+        id,
+        actor: definition.name,
+        ...(key === undefined ? {} : { key }),
+        model,
+        state,
+        ...(props === undefined ? {} : { props }),
+        children: {},
+        invoked: {},
+    });
+};
+// 2. Enter
+/**
+ * Enter the Instance's State: every Child the State writes is Invoked fresh.
+ * A Child written at the top lasts through the Transition; then every Child
+ * follows the parent's data.
+ */
+export const enter = (definition, instance) => {
+    const slots = definition.children[instance.state._tag];
+    if (!slots)
+        return { ...instance, children: {} };
+    const invocation = invocationOf(definition, instance);
+    const invoked = { ...instance.invoked };
+    const children = {};
+    for (const [slot, { definition: child, many }] of Object.entries(slots)) {
+        const kept = definition.lasting.includes(slot)
+            ? instance.children[slot]
+            : undefined;
+        children[slot] =
+            kept ??
+                (many
+                    ? keyedIn(invocation, slot).map((given) => invoke(child, instance.id, slot, given.key, given, invoked))
+                    : invoke(child, instance.id, slot, undefined, givenIn(invocation, slot), invoked));
+    }
+    return follow(definition, { ...instance, children, invoked });
+};
+// 3. Follow
+export const follow = (definition, instance) => {
+    const slots = Object.entries(definition.children[instance.state._tag] ?? {});
+    if (slots.length === 0)
+        return instance;
+    const invocation = invocationOf(definition, instance);
+    let invoked;
+    let children;
+    for (const [slot, { definition: child, many }] of slots) {
+        if (!many) {
+            const held = instance.children[slot];
+            if (!held)
+                continue;
+            const handed = handedProps(child, held, givenIn(invocation, slot).props);
+            if (handed !== held)
+                (children ??= { ...instance.children })[slot] = handed;
+            continue;
+        }
+        const before = (instance.children[slot] ?? []);
+        const byKey = new Map(before.map((kept) => [kept.key, kept]));
+        const wanted = keyedIn(invocation, slot);
+        let changed = wanted.length !== before.length;
+        const after = wanted.map((given, index) => {
+            const kept = byKey.get(given.key);
+            if (kept) {
+                const handed = handedProps(child, kept, given.props);
+                if (before[index] !== handed)
+                    changed = true;
+                return handed;
+            }
+            changed = true;
+            invoked ??= { ...instance.invoked };
+            return invoke(child, instance.id, slot, given.key, given, invoked);
+        });
+        if (changed)
+            (children ??= { ...instance.children })[slot] = after;
+    }
+    return children
+        ? { ...instance, children, invoked: invoked ?? instance.invoked }
+        : instance;
+};
+/** A Child kept, with the Props it is handed now: the same Instance while they say the same. */
+const handedProps = (definition, child, props) => {
+    if (Equal.equals(child.props, props))
+        return child;
+    definition.check.props(props, `the Props of ${child.id}`);
+    const { props: _, ...rest } = child;
+    return follow(definition, props === undefined ? rest : { ...rest, props });
+};
+const invoke = (definition, parent, slot, key, given, invoked) => {
+    const counter = counterOf(slot, key);
+    const generation = (invoked[counter] ?? 0) + 1;
+    invoked[counter] = generation;
+    return create(definition, childId(parent, slot, key, generation), key, given);
+};
+const invocationOf = (definition, instance) => definition.invoke[instance.state._tag]?.({
+    model: instance.model,
+    state: instance.state,
+    props: instance.props,
+}) ?? {};
+const givenIn = (invocation, slot) => (invocation[slot] ?? {});
+const keyedIn = (invocation, slot) => {
+    const keyed = (invocation[slot] ?? []);
+    const seen = new Set();
+    for (const { key } of keyed) {
+        if (seen.has(key))
+            throw new Error(`[@kestack/kabuki] ${slot}: key "${key}" is Invoked twice`);
+        seen.add(key);
+    }
+    return keyed;
+};

package/dist/core/snapshot/restore.d.ts

@@ -0,0 +1,16 @@
+import type { ActorDefinition, Tagged } from '../actor/index.ts';
+import type { Snapshot } from './snapshot.ts';
+export declare const RESTORE = "@kestack/kabuki/Restore";
+export interface Restore extends Tagged {
+    readonly _tag: typeof RESTORE;
+    readonly snapshot: Snapshot;
+}
+export declare const isRestore: (message: Tagged) => message is Restore;
+export declare const restore: (snapshot: Snapshot) => Restore;
+/** The saved Snapshot if every Instance in it matches its Actor, else why not. */
+export declare const checkRestore: (root: ActorDefinition, { snapshot }: Restore) => {
+    readonly snapshot: Snapshot;
+} | {
+    readonly reason: string;
+};
+//# sourceMappingURL=restore.d.ts.map

package/dist/core/snapshot/restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.d.ts","sourceRoot":"","sources":["../../../src/core/snapshot/restore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,eAAe,CAAC;AAYxD,eAAO,MAAM,OAAO,4BAA4B,CAAC;AAEjD,MAAM,WAAW,OAAQ,SAAQ,MAAM;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,OAAO,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,eAAO,MAAM,SAAS,YAAa,MAAM,KAAG,OAAO,IAAI,OAC7B,CAAC;AAE3B,eAAO,MAAM,OAAO,aAAc,QAAQ,KAAG,OAG3C,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,YAAY,SACjB,eAAe,gBACP,OAAO,KACpB;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAK7D,CAAC"}

package/dist/core/snapshot/restore.js

@@ -0,0 +1,63 @@
+import { counterOf, isMany, slotToward } from './tree.js';
+/*
+ * Restore: a Message to the root that replaces the whole Snapshot with one
+ * saved before. The only Message no Update sees. Before it is put in place,
+ * every Instance is checked against its Actor: its ID, its Actor's name, its
+ * State, its Model, its Props and its Children's slots, every one its State
+ * Invokes and no other; one that does not
+ * match is a reason, and the Restore is ignored.
+ */
+export const RESTORE = '@kestack/kabuki/Restore';
+export const isRestore = (message) => message._tag === RESTORE;
+export const restore = (snapshot) => ({
+    _tag: RESTORE,
+    snapshot,
+});
+/** The saved Snapshot if every Instance in it matches its Actor, else why not. */
+export const checkRestore = (root, { snapshot }) => {
+    if (snapshot.id !== root.name)
+        return { reason: `its root is ${snapshot.id}, not ${root.name}` };
+    const reason = check(root, snapshot, undefined);
+    return reason === undefined ? { snapshot } : { reason };
+};
+const check = (definition, instance, key) => {
+    const { id } = instance;
+    if (instance.actor !== definition.name)
+        return `${id} is a ${instance.actor}, not a ${definition.name}`;
+    if (instance.key !== key)
+        return `${id} has the key ${instance.key}`;
+    const tag = instance.state._tag;
+    if (!definition.states.includes(tag))
+        return `${id} is in ${tag}, which ${definition.name} has no State for`;
+    try {
+        definition.check.model(instance.model, `the Model of ${id}`);
+        definition.check.state(instance.state, `the State of ${id}`);
+        definition.check.props(instance.props, `the Props of ${id}`);
+    }
+    catch (error) {
+        return error.message;
+    }
+    const slots = definition.children[tag] ?? {};
+    for (const slot of Object.keys(slots))
+        if (!(slot in instance.children))
+            return `${id} is in ${tag}, which Invokes "${slot}", but holds no such Child`;
+    for (const [slot, held] of Object.entries(instance.children)) {
+        const wanted = slots[slot];
+        if (!wanted)
+            return `${id} has a Child "${slot}" that ${tag} does not Invoke`;
+        if (isMany(held) !== wanted.many)
+            return `${id}'s Child "${slot}" is ${wanted.many ? '' : 'not '}keyed`;
+        for (const child of isMany(held) ? held : [held]) {
+            if (slotToward(id, child.id) !== slot)
+                return `${child.id} is not under ${id}'s "${slot}"`;
+            const generation = Number(child.id.slice(child.id.lastIndexOf('#') + 1));
+            const counted = instance.invoked[counterOf(slot, child.key)] ?? 0;
+            if (!(generation <= counted))
+                return `${id} has Invoked "${slot}" ${counted} times, but holds ${child.id}`;
+            const reason = check(wanted.definition, child, isMany(held) ? child.key : undefined);
+            if (reason !== undefined)
+                return reason;
+        }
+    }
+    return undefined;
+};

package/dist/core/snapshot/snapshot.d.ts

@@ -0,0 +1,61 @@
+import type { ActorDefinition, Tagged } from '../actor/index.ts';
+/** One running Actor in the tree. */
+export interface Instance {
+    readonly id: string;
+    /** Its Actor's name. */
+    readonly actor: string;
+    /** Its key, if it is a keyed Child. */
+    readonly key?: string;
+    readonly state: Tagged;
+    readonly model: unknown;
+    /**
+     * What its parent hands it now, if its Actor declares Props. Worked out by
+     * the parent, never written by the Instance.
+     */
+    readonly props?: unknown;
+    /** A fixed Child by its name; keyed Children by their slot, in the Model's order. */
+    readonly children: Readonly<Record<string, Instance | ReadonlyArray<Instance>>>;
+    /** How many times this Instance has Invoked each Child, for the next ID. */
+    readonly invoked: Readonly<Record<string, number>>;
+}
+/** The whole app: its root Instance. */
+export type Snapshot = Instance;
+/**
+ * Who Sent a Message: the Instance, and what in it Sent: its View, a Command
+ * by its name, a Worker by its name and key, or what it Provides. Only a
+ * Request comes from another Instance than its destination. A Message from outside the tree, by
+ * a test or a tool, comes from no Instance; a Restore no one Sent: it was
+ * given to the app.
+ */
+export type Source = {
+    readonly kind: 'view';
+    readonly instance: string;
+} | {
+    readonly kind: 'command';
+    readonly instance: string;
+    readonly name: string;
+} | {
+    readonly kind: 'worker';
+    readonly instance: string;
+    readonly name: string;
+    /** The key an `each` Worker runs for. */
+    readonly key?: string;
+} | {
+    readonly kind: 'provide';
+    readonly instance: string;
+} | {
+    readonly kind: 'outside';
+} | {
+    readonly kind: 'restore';
+};
+/** A Message, the Instance it is for, who Sent it, and its Time. */
+export interface Envelope {
+    /** The ID of the Instance it is for. */
+    readonly destination: string;
+    readonly message: Tagged;
+    readonly source: Source;
+    readonly at: number;
+}
+/** The app right after init: the root, named after its Actor, and every Child its State Invokes. */
+export declare const init: (root: ActorDefinition, input?: unknown) => Snapshot;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/core/snapshot/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../../src/core/snapshot/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAWjE,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CACzB,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,CACnD,CAAC;IACF,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,wCAAwC;AACxC,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC,oEAAoE;AACpE,MAAM,WAAW,QAAQ;IACvB,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAGD,oGAAoG;AACpG,eAAO,MAAM,IAAI,SAAU,eAAe,UAAU,OAAO,KAAG,QACf,CAAC"}

package/dist/core/snapshot/snapshot.js

@@ -0,0 +1,4 @@
+import { create } from './invoke.js';
+// 1. Init
+/** The app right after init: the root, named after its Actor, and every Child its State Invokes. */
+export const init = (root, input) => create(root, root.name, undefined, { input });