@lambdot/core 0.1.0 → 0.2.0

package/src/kernel.ts

@@ -1,306 +1,275 @@
-import type { ContextView } from "./context.ts";
-import type { OutputContractMap } from "./context.ts";
-import { collectEffect, type Disposer } from "./effect.ts";
-import { EventBus, INGRESS, type BotEvent, type OnOptions } from "./events.ts";
-import type { EventMap } from "./events.ts";
-import { Fiber } from "./fiber.ts";
-import type {
-    AnyPlugin,
-    CapsOf,
-    ConfigOf,
-    EventsOf,
-    OutputsOf,
-    Spread,
-    StateOf,
-    Validate,
-} from "./plugin.ts";
+import { runDisposers, type Disposer } from "./effect.ts";
+import type { Composite, Plugin, PluginSpec, Scope } from "./plugin.ts";
 import { validateConfig } from "./schema.ts";
-import { createStateAccessor, type StateBackend } from "./state.ts";
 
 export interface KernelOptions {
-    /** Sink for errors thrown by fire-and-forget listeners and disposers. */
+    /** Sink for errors reported through `scope.onError` and background activations. */
     onError?: (error: unknown) => void;
 }
 
+/** Runtime view of anything wireable: a leaf plugin or a nested composition. */
+interface RuntimeUnit {
+    readonly name: string;
+    activate(input: unknown, scope: Scope, config: unknown): Promise<unknown>;
+}
+
+interface Entry {
+    readonly unit: RuntimeUnit;
+    /** The namespace key the unit's output is stored under (`as` ?? name). */
+    readonly key: string;
+    readonly visible: boolean;
+    readonly mapping: ((ctx: Record<string, unknown>) => unknown) | undefined;
+    readonly config: unknown;
+}
+
+const defaultOnError = (error: unknown): void => console.error("[lambdot]", error);
+
+function makeScope(disposers: Disposer[], onError: (error: unknown) => void): Scope {
+    return {
+        onDispose: (disposer) => {
+            disposers.push(disposer);
+        },
+        onError,
+    };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
 /**
- * The runtime context. Untyped internally; the kernel exposes it through
- * {@link ContextView} parameterized by the folded type arguments.
+ * A leaf plugin at runtime. The composition methods seed an artifact chain
+ * with the plugin itself as the first entry, so a lone plugin is runnable.
  */
-class RuntimeContext {
-    readonly bus: EventBus;
-    private readonly outputs = new Map<
-        string,
-        { send(to: never, content: never): void | Promise<void> }
-    >();
-    private readonly provided = new Map<string, unknown>();
-    /** Events are processed sequentially, in ingestion order. */
-    private queue: Promise<void> = Promise.resolve();
-    onProvideChange: (name: string, available: boolean) => void = () => {};
-
-    constructor(private readonly onError: (error: unknown) => void) {
-        this.bus = new EventBus(onError);
-    }
+class PluginRuntime implements RuntimeUnit {
+    private artifact: CompositeRuntime | undefined;
 
-    on(kind: string, listener: never, options?: OnOptions): Disposer {
-        return this.bus.on(kind, listener, options);
+    constructor(private readonly spec: PluginSpec<any, any, any, string>) {
+        this.name = spec.name;
     }
 
-    emit(kind: string, event: unknown): void {
-        this.bus.emit(kind, event);
-    }
+    readonly name: string;
 
-    parallel(kind: string, event: unknown): Promise<void> {
-        return this.bus.parallel(kind, event);
+    get Config(): PluginSpec<any, any, any, string>["Config"] {
+        return this.spec.Config;
     }
 
-    serial(kind: string, event: unknown): Promise<unknown> {
-        return this.bus.serial(kind, event);
+    apply(input: unknown, scope: Scope, config: unknown): Promise<unknown> {
+        return this.activate(input, scope, config);
     }
 
-    waterfall(
-        kind: string,
-        event: unknown,
-        inner: (event: any) => Promise<unknown>,
-    ): Promise<unknown> {
-        return this.bus.waterfall(kind, event, inner);
+    async activate(input: unknown, scope: Scope, config: unknown): Promise<unknown> {
+        const validated = this.spec.Config
+            ? await validateConfig(this.spec.name, this.spec.Config, config)
+            : config;
+        return await this.spec.apply(input, scope, validated);
     }
 
-    async send(to: { platform: string }, content: unknown): Promise<void> {
-        const output = this.outputs.get(to.platform);
-        if (!output) throw new Error(`no output registered for platform "${to.platform}"`);
-        await output.send(to as never, content as never);
+    use(unit: RuntimeUnit, options?: WireOptions): CompositeRuntime {
+        return this.asArtifact().use(unit, options);
     }
 
-    registerOutput(
-        platform: string,
-        output: { send(to: never, content: never): void | Promise<void> },
-    ): Disposer {
-        if (this.outputs.has(platform))
-            throw new Error(`duplicate output for platform "${platform}"`);
-        this.outputs.set(platform, output);
-        return () => {
-            this.outputs.delete(platform);
-        };
+    bind(unit: RuntimeUnit, options?: WireOptions): CompositeRuntime {
+        return this.asArtifact().bind(unit, options);
     }
 
-    readonly state = {
-        for: (plugin: string) => {
-            // State has no dedicated runtime slot: a state plugin is an
-            // ordinary feature plugin that provides its backend as the
-            // (runtime-gated) "state" capability.
-            const backend = this.provided.get("state") as StateBackend | undefined;
-            if (!backend)
-                throw new Error(
-                    'no state backend active — register a state plugin and add `inject: ["state"]`',
-                );
-            return createStateAccessor(backend, plugin);
-        },
-    };
-
-    provide(name: string, value?: unknown): Disposer {
-        if (this.provided.has(name)) throw new Error(`capability "${name}" is already provided`);
-        this.provided.set(name, value);
-        const defined = value !== undefined && !(name in this);
-        if (defined) {
-            Object.defineProperty(this, name, { value, configurable: true });
-        }
-        this.onProvideChange(name, true);
-        return () => {
-            this.provided.delete(name);
-            if (defined) {
-                delete (this as Record<string, unknown>)[name];
-            }
-            this.onProvideChange(name, false);
-        };
+    start(input?: unknown): Promise<void> {
+        return this.asArtifact().start(input);
     }
 
-    isProvided(name: string): boolean {
-        return this.provided.has(name);
+    async stop(): Promise<void> {
+        await this.artifact?.stop();
     }
 
-    ingest(kind: string, payload: unknown, address: unknown): Promise<void> {
-        const event: BotEvent = { kind, payload, address, id: crypto.randomUUID(), at: Date.now() };
-        const run = this.queue.then(() => this.process(event));
-        // A failing event rejects its own caller but never jams the queue.
-        this.queue = run.catch(this.onError);
-        return run;
+    get ctx(): Record<string, unknown> {
+        return this.asArtifact().ctx;
     }
 
-    private async process(event: BotEvent): Promise<void> {
-        await this.bus.waterfall(INGRESS, event, async (current: BotEvent) => {
-            await this.bus.parallel(current.kind, current);
-        });
+    private asArtifact(): CompositeRuntime {
+        if (!this.artifact) {
+            this.artifact = new CompositeRuntime(
+                [
+                    {
+                        unit: this,
+                        key: this.spec.name,
+                        visible: true,
+                        mapping: undefined,
+                        config: undefined,
+                    },
+                ],
+                {},
+                this.spec.name,
+            );
+        }
+        return this.artifact;
     }
 }
 
-interface FiberEntry {
-    readonly plugin: AnyPlugin;
-    readonly config: unknown;
-    readonly fiber: Fiber;
+interface WireOptions {
+    readonly mapping?: (ctx: Record<string, unknown>) => unknown;
+    readonly option?: unknown;
+    readonly as?: string;
 }
 
 /**
- * The kernel. Stateless: it owns no conversational data, only the fiber
- * registry and the runtime wiring. Every `use()` folds the plugin's type
- * contribution into the kernel's type parameters — the context type your
- * plugins see is computed from the plugins you registered.
+ * A composition at runtime. Inert while built: `start` activates the entries
+ * in composition order — resolve the mapping (or identity-wire the visible
+ * context), activate the unit, stash its output under its namespace key —
+ * and `stop` disposes in reverse. Activation order is definition order;
+ * ordering mistakes are compile errors in the mappings, not runtime states.
  */
-export class Kernel<
-    TEvents extends EventMap = {},
-    TOutputs extends OutputContractMap = {},
-    TCaps extends object = {},
-    TState extends object = {},
-> {
-    /** The typed context. This is the fold of everything registered so far. */
-    readonly ctx: ContextView<TEvents, TOutputs, TState, TCaps> & TCaps;
-
-    private readonly runtime: RuntimeContext;
-    private readonly entries: FiberEntry[] = [];
-    private readonly onError: (error: unknown) => void;
-    private readonly inflightActivations = new Set<Promise<void>>();
+class CompositeRuntime implements RuntimeUnit {
+    readonly ctx: Record<string, unknown> = {};
+    private readonly hidden: Record<string, unknown> = {};
+    private readonly activated: { entry: Entry; disposers: Disposer[] }[] = [];
+    private inputRecord: Record<string, unknown> = {};
     private started = false;
+    private readonly onError: (error: unknown) => void;
 
-    constructor(options: KernelOptions = {}) {
-        this.onError = options.onError ?? ((error) => console.error("[lambdot]", error));
-        this.runtime = new RuntimeContext(this.onError);
-        this.runtime.onProvideChange = (name, available) => {
-            if (!available) void this.deactivateDependents(name).catch(this.onError);
-            if (available) void this.activateEligible().catch(this.onError);
-        };
-        this.ctx = this.runtime as unknown as ContextView<TEvents, TOutputs, TState, TCaps> & TCaps;
+    constructor(
+        private readonly entries: Entry[],
+        options: KernelOptions,
+        readonly name: string,
+    ) {
+        this.onError = options.onError ?? defaultOnError;
+    }
+
+    /** Set by `expose`: composing onto a sealed chain is a runtime error. */
+    private exposed: string | undefined;
+
+    use(unit: RuntimeUnit, options?: WireOptions): this {
+        return this.add(unit, options, true);
+    }
+
+    bind(unit: RuntimeUnit, options?: WireOptions): this {
+        return this.add(unit, options, false);
+    }
+
+    /** Seal the chain and return it as a named engine — the final artifact. */
+    expose(name: string): EngineRuntime {
+        // Explicit undefined check: "" is a valid name and must still seal.
+        if (this.exposed !== undefined)
+            throw new Error(`kernel already exposed as engine "${this.exposed}"`);
+        this.exposed = name;
+        return new EngineRuntime(this, name);
     }
 
-    /**
-     * Register a plugin. Gated at compile time: every event kind a feature
-     * handles, every output platform it sends through, and every typed
-     * capability it injects must already be in the fold.
-     */
-    use<TPlugin extends AnyPlugin>(
-        plugin: TPlugin & Validate<TPlugin, TEvents, TOutputs, TCaps>,
-        ...config: Spread<ConfigOf<TPlugin>>
-    ): Kernel<
-        TEvents & EventsOf<TPlugin>,
-        TOutputs & OutputsOf<TPlugin>,
-        TCaps & CapsOf<TPlugin>,
-        TState & StateOf<TPlugin>
-    > {
-        const entry: FiberEntry = {
-            plugin,
-            config: config[0],
-            fiber: new Fiber(plugin, config[0]),
+    private add(unit: RuntimeUnit, options: WireOptions | undefined, visible: boolean): this {
+        if (this.exposed !== undefined)
+            throw new Error(`cannot compose onto a kernel exposed as engine "${this.exposed}"`);
+        const entry: Entry = {
+            unit,
+            key: options?.as ?? unit.name,
+            visible,
+            mapping: options?.mapping,
+            config: options?.option,
         };
         this.entries.push(entry);
-        if (this.started) void this.activateEligible().catch(this.onError);
-        return this as unknown as Kernel<
-            TEvents & EventsOf<TPlugin>,
-            TOutputs & OutputsOf<TPlugin>,
-            TCaps & CapsOf<TPlugin>,
-            TState & StateOf<TPlugin>
-        >;
+        // Composing onto a running artifact activates in the background —
+        // same fire-and-report semantics as composition before `start`.
+        if (this.started) void this.activateEntry(entry).catch(this.onError);
+        return this;
+    }
+
+    /** RuntimeUnit: run as a nested unit, torn down with the parent. */
+    async activate(input: unknown, scope: Scope, _config: unknown): Promise<unknown> {
+        scope.onDispose(() => this.stop());
+        await this.start(input);
+        return this.ctx;
     }
 
-    /** Activate all plugins whose `inject` requirements are satisfiable. */
-    async start(): Promise<void> {
+    async start(input?: unknown): Promise<void> {
         if (this.started) return;
         this.started = true;
-        await this.activateEligible();
-        const stuck = this.entries
-            .filter((entry) => entry.fiber.state === "pending")
-            .map((entry) => entry.plugin.name);
-        if (stuck.length > 0)
-            console.warn(`[lambdot] plugins pending on missing capabilities: ${stuck.join(", ")}`);
+        this.inputRecord = isRecord(input) ? input : {};
+        try {
+            for (const entry of this.entries) {
+                if (this.activated.some((done) => done.entry === entry)) continue;
+                await this.activateEntry(entry);
+            }
+        } catch (error) {
+            await this.stop();
+            throw error;
+        }
     }
 
-    /** Dispose every active fiber in reverse registration order. */
     async stop(): Promise<void> {
         this.started = false;
-        for (const entry of [...this.entries].reverse()) {
-            await entry.fiber.dispose("disposed", this.onError);
+        for (const { entry, disposers } of this.activated.splice(0).reverse()) {
+            await runDisposers(disposers, this.onError);
+            if (entry.visible) delete this.ctx[entry.key];
+            else delete this.hidden[entry.key];
         }
     }
 
-    private eligible(plugin: AnyPlugin): boolean {
-        return (plugin.inject ?? []).every((name) => this.runtime.isProvided(name));
+    private async activateEntry(entry: Entry): Promise<void> {
+        if (entry.key in this.ctx || entry.key in this.hidden)
+            throw new Error(`duplicate namespace "${entry.key}"`);
+        const disposers: Disposer[] = [];
+        // Identity wiring hands over the whole visible context; the unit's
+        // declared input type narrows the view at compile time.
+        const wireCtx = { ...this.inputRecord, ...this.hidden, ...this.ctx };
+        const input = entry.mapping ? entry.mapping(wireCtx) : wireCtx;
+        const output = await entry.unit.activate(
+            input,
+            makeScope(disposers, this.onError),
+            entry.config,
+        );
+        if (entry.visible) this.ctx[entry.key] = output;
+        else this.hidden[entry.key] = output;
+        this.activated.push({ entry, disposers });
     }
+}
 
-    private async activateEligible(): Promise<void> {
-        if (!this.started) return;
-        let progressed = true;
-        while (progressed) {
-            progressed = false;
-            for (const entry of this.entries) {
-                if (entry.fiber.state !== "pending" || !this.eligible(entry.plugin)) continue;
-                await this.activate(entry);
-                progressed = true;
-            }
-        }
-        // Nested passes (triggered by `provide` during activation) may still
-        // have activations in flight; wait for quiescence so `start()` and
-        // `stop()` only observe settled fibers.
-        while (this.inflightActivations.size > 0) {
-            await Promise.allSettled(this.inflightActivations);
-        }
-    }
+/**
+ * The runtime behind `Composite.expose`: a thin, sealed façade over the
+ * chain. Lifecycle delegates to the inner composition; as a nested unit it
+ * activates exactly like the chain itself — the only difference is the name
+ * and the erased type.
+ */
+class EngineRuntime implements RuntimeUnit {
+    constructor(
+        private readonly inner: CompositeRuntime,
+        readonly name: string,
+    ) {}
 
-    private activate(entry: FiberEntry): Promise<void> {
-        // Mark the fiber synchronously so a nested `activateEligible` pass
-        // cannot pick it up again while activation is in flight.
-        entry.fiber.state = "activating";
-        const activation = this.completeActivation(entry);
-        this.inflightActivations.add(activation);
-        const settled = () => this.inflightActivations.delete(activation);
-        activation.then(settled, settled);
-        return activation;
+    /** Public contract: apply the engine directly, like any other unit. */
+    apply(input: unknown, scope: Scope, config: unknown): Promise<unknown> {
+        return this.activate(input, scope, config);
     }
 
-    private async completeActivation(entry: FiberEntry): Promise<void> {
-        const { plugin, fiber } = entry;
-        let config = entry.config;
-        try {
-            if (plugin.Config) config = await validateConfig(plugin.name, plugin.Config, config);
-        } catch (error) {
-            fiber.state = "pending";
-            throw error;
-        }
-        // The kernel may have stopped, or a required capability may have been
-        // withdrawn, while we awaited; mid-activation fibers are invisible to
-        // `deactivateDependents` and `stop`.
-        if (!this.started || !this.eligible(plugin)) {
-            fiber.state = "pending";
-            return;
-        }
-
-        // Role-specific registration happens before `apply` so plugin code
-        // can rely on its own capability being live.
-        if (plugin.role === "output") {
-            fiber.state = "active";
-            fiber.addDisposer(this.runtime.registerOutput(plugin.platform, plugin));
-        } else {
-            fiber.state = "active";
-        }
+    activate(input: unknown, scope: Scope, _config: unknown): Promise<unknown> {
+        return this.inner.activate(input, scope, undefined);
+    }
 
-        if ("apply" in plugin && plugin.apply) {
-            await collectEffect(plugin.apply(this.runtime as never, config as never), (disposer) =>
-                fiber.addDisposer(disposer),
-            );
-        }
+    start(input?: unknown): Promise<void> {
+        return this.inner.start(input);
+    }
 
-        const provides = plugin.provide ? [plugin.provide].flat() : [];
-        for (const name of provides) {
-            fiber.addDisposer(this.runtime.provide(name));
-        }
+    stop(): Promise<void> {
+        return this.inner.stop();
     }
 
-    private async deactivateDependents(capability: string): Promise<void> {
-        for (const entry of [...this.entries].reverse()) {
-            if (entry.fiber.state !== "active") continue;
-            if (!(entry.plugin.inject ?? []).includes(capability)) continue;
-            await entry.fiber.dispose("pending", this.onError);
-        }
+    get ctx(): Record<string, unknown> {
+        return this.inner.ctx;
     }
 }
 
-/** Create an empty kernel. Fold plugins in with `.use(...)`. */
-export function createKernel(options?: KernelOptions): Kernel {
-    return new Kernel(options);
+/**
+ * Author a plugin. The spec is just `name`, optional `Config` schema, and
+ * `apply`; the returned plugin carries the composition methods (`use`,
+ * `bind`, `start`, `stop`, `ctx`).
+ */
+export function definePlugin<
+    TIn = void,
+    TOut = void,
+    TConfig = void,
+    TName extends string = string,
+>(spec: PluginSpec<TIn, TOut, TConfig, TName>): Plugin<TIn, TOut, TConfig, TName> {
+    return new PluginRuntime(spec) as never;
+}
+
+/** Create an empty composition. Wire plugins in with `.use(...)` / `.bind(...)`. */
+export function createKernel(options?: KernelOptions): Composite<void, {}, {}, "kernel"> {
+    return new CompositeRuntime([], options ?? {}, "kernel") as never;
 }

package/src/message.ts

@@ -0,0 +1,37 @@
+/**
+ * The envelope flowing through streams: a payload plus its return address.
+ * The core never inspects the address beyond the `platform` routing tag.
+ */
+export interface Address<TPlatform extends string = string> {
+    readonly platform: TPlatform;
+}
+
+/**
+ * One inbound event. `payload` and `address` are platform-defined; `id` and
+ * `at` are minted by the producing input (see {@link message}).
+ */
+export interface Message<TPayload = unknown, TAddress = unknown> {
+    readonly payload: TPayload;
+    readonly address: TAddress;
+    /** Unique id for dedup and tracing. */
+    readonly id: string;
+    /** Unix epoch milliseconds. */
+    readonly at: number;
+}
+
+/** Mint a message envelope with a fresh id and timestamp. */
+export function message<TPayload, TAddress>(
+    payload: TPayload,
+    address: TAddress,
+): Message<TPayload, TAddress> {
+    return { payload, address, id: crypto.randomUUID(), at: Date.now() };
+}
+
+/**
+ * One outbound reply: content addressed back through the platform that owns
+ * the address. Features emit streams of these; output plugins consume them.
+ */
+export interface Command<TAddress = unknown, TContent = unknown> {
+    readonly address: TAddress;
+    readonly content: TContent;
+}