@lambdot/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/core-v0.0.1...core-v0.1.0) (2026-08-29)
+
+
+### Miscellaneous Chores
+
+* **core:** Synchronize lambdot versions

package/package.json

@@ -0,0 +1,11 @@
+{
+    "name": "@lambdot/core",
+    "version": "0.1.0",
+    "type": "module",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/context.ts

@@ -0,0 +1,120 @@
+import type { Disposer } from "./effect.ts";
+import type { BotEvent, EventMap, IngressListener, Listener, OnOptions } from "./events.ts";
+import { INGRESS } from "./events.ts";
+import type { StateView } from "./state.ts";
+
+/**
+ * A typed return address. Produced by the input half of a platform pair,
+ * consumed by the output half. The core never inspects it beyond the
+ * `platform` routing tag.
+ */
+export interface Address<TPlatform extends string = string> {
+    readonly platform: TPlatform;
+}
+
+/** An output platform's contract: the addresses it accepts and the content it can send. */
+export interface OutputContract<TAddress = unknown, TContent = unknown> {
+    address: TAddress;
+    content: TContent;
+}
+
+/** platform → contract. Folded across all registered output plugins. */
+export type OutputContractMap = Record<string, OutputContract<any, any>>;
+
+type AllAddresses<TOutputs extends OutputContractMap> = TOutputs[keyof TOutputs]["address"];
+
+/**
+ * Content types accepted for a given address: the union of `content` from
+ * every registered output whose address type accepts `TAddress`. Resolves to
+ * `never` when no output matches — with no outputs registered at all,
+ * `send` is simply uncallable.
+ */
+export type ContentFor<TOutputs extends OutputContractMap, TAddress> = {
+    [K in keyof TOutputs]: TAddress extends TOutputs[K]["address"] ? TOutputs[K]["content"] : never;
+}[keyof TOutputs];
+
+/**
+ * The typed surface every plugin sees. Parameterized by the plugin's own
+ * declared needs (event kinds it handles, output platforms it sends to,
+ * state schema it owns) — the kernel checks at `use()` time that the fold
+ * so far satisfies them — plus the capabilities it provides (`TProvides`),
+ * which makes `provide` type-checked for declared names.
+ */
+export interface ContextView<
+    TEvents extends EventMap,
+    TOutputs extends OutputContractMap,
+    TState extends object,
+    TProvides extends object = {},
+> {
+    /** Subscribe to ingress middleware (waterfall over every event). */
+    on(kind: typeof INGRESS, listener: IngressListener<TEvents>, options?: OnOptions): Disposer;
+    /** Subscribe to a specific event kind. */
+    on<TKind extends keyof TEvents & string>(
+        kind: TKind,
+        listener: Listener<BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>>,
+        options?: OnOptions,
+    ): Disposer;
+
+    emit<TKind extends keyof TEvents & string>(
+        kind: TKind,
+        event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
+    ): void;
+    parallel<TKind extends keyof TEvents & string>(
+        kind: TKind,
+        event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
+    ): Promise<void>;
+    serial<TKind extends keyof TEvents & string>(
+        kind: TKind,
+        event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
+    ): Promise<unknown>;
+    waterfall<TKind extends keyof TEvents & string>(
+        kind: TKind,
+        event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
+        inner: (
+            event: BotEvent<TKind, TEvents[TKind]["payload"], TEvents[TKind]["address"]>,
+        ) => Promise<unknown>,
+    ): Promise<unknown>;
+
+    /**
+     * Send content through the output platform that owns `to`'s address
+     * type. Compile error if the content doesn't match that platform's
+     * contract — or if the platform's output plugin was never registered.
+     */
+    send<TAddress extends AllAddresses<TOutputs>>(
+        to: TAddress,
+        content: ContentFor<TOutputs, TAddress>,
+    ): Promise<void>;
+
+    /**
+     * Typed per-plugin state. `never` unless some plugin declared a state
+     * schema; usable at runtime only while a state backend plugin is active.
+     */
+    readonly state: StateView<TState>;
+
+    /**
+     * Provide a named capability for `inject` gating. Names declared in the
+     * plugin's `TProvides` require a value of the declared type (the value is
+     * attached to the context — the dashboard-plugin pattern — and read back
+     * typed through the kernel's capability fold). Undeclared names take an
+     * optional untyped value: the runtime-only capability path. Returns the
+     * unregistering disposer.
+     */
+    provide<TName extends string>(
+        name: TName,
+        ...value: TName extends keyof TProvides & string
+            ? [value: TProvides[TName]]
+            : [value?: unknown]
+    ): Disposer;
+}
+
+/** Context seen by input plugins: adds the ability to push events into the pipeline. */
+export interface InputContext<
+    TEvents extends EventMap,
+    TProvides extends object = {},
+> extends ContextView<TEvents, {}, {}, TProvides> {
+    ingest<TKind extends keyof TEvents & string>(
+        kind: TKind,
+        payload: TEvents[TKind]["payload"],
+        address: TEvents[TKind]["address"],
+    ): Promise<void>;
+}

package/src/effect.ts

@@ -0,0 +1,50 @@
+/**
+ * A function that undoes a registration or allocation. Collected by the
+ * fiber that owns the plugin instance and run on unload/shutdown.
+ */
+export type Disposer = () => void | Promise<void>;
+
+/**
+ * Non-promise effect results. Kept separate from {@link Effect} so the
+ * promise variant stays non-recursive and easy for TS to flatten.
+ */
+export type EffectResult = void | Disposer | Iterable<Disposer> | AsyncIterable<Disposer>;
+
+/**
+ * The result of a plugin's `apply`. Everything a plugin contributes is an
+ * effect: disposers returned (or yielded) here are collected by the plugin's
+ * fiber and run when the plugin unloads. There are no lifecycle hooks.
+ */
+export type Effect = EffectResult | Promise<EffectResult>;
+
+/** Collect every disposer an effect produces into `sink`. */
+export async function collectEffect(
+    effect: Effect,
+    sink: (disposer: Disposer) => void,
+): Promise<void> {
+    const result = await effect;
+    if (!result) return;
+    if (typeof result === "function") {
+        sink(result);
+        return;
+    }
+    if (Symbol.asyncIterator in result) {
+        for await (const disposer of result) sink(disposer);
+        return;
+    }
+    for (const disposer of result) sink(disposer);
+}
+
+/** Run disposers in reverse registration order, isolating failures. */
+export async function runDisposers(
+    disposers: readonly Disposer[],
+    onError: (error: unknown) => void,
+): Promise<void> {
+    for (const dispose of [...disposers].reverse()) {
+        try {
+            await dispose();
+        } catch (error) {
+            onError(error);
+        }
+    }
+}

package/src/events.ts

@@ -0,0 +1,147 @@
+/**
+ * An event kind's contract: the payload an input produces and the typed
+ * return address that routes replies back through a matching output.
+ */
+export interface EventDef<TPayload = unknown, TAddress = unknown> {
+    payload: TPayload;
+    address: TAddress;
+}
+
+/** kind → contract. Folded across all registered input plugins. */
+export type EventMap = Record<string, EventDef<any, any>>;
+
+/**
+ * The single unit that flows through the framework. The core envelope is
+ * deliberately free of platform semantics: no reply references, no channel
+ * vocabulary — `address` is opaque to the core and meaningful only to the
+ * output whose platform produced it.
+ */
+export interface BotEvent<TKind extends string = string, TPayload = unknown, TAddress = unknown> {
+    readonly kind: TKind;
+    readonly payload: TPayload;
+    readonly address: TAddress;
+    /** Unique id for dedup and tracing. */
+    readonly id: string;
+    /** Unix epoch milliseconds. */
+    readonly at: number;
+}
+
+/** Union over every registered event kind, narrowing `payload`/`address` per kind. */
+export type AnyBotEvent<TEvents extends EventMap> = {
+    [K in keyof TEvents & string]: BotEvent<K, TEvents[K]["payload"], TEvents[K]["address"]>;
+}[keyof TEvents & string];
+
+/** Reserved kind: every ingested event passes through this waterfall first. */
+export const INGRESS = "bot/ingress" as const;
+
+/** Continue a waterfall chain. Call with no argument to pass the event through unchanged. */
+export type NextFn<TEvent> = (event?: TEvent) => Promise<unknown>;
+
+/**
+ * A listener. Plain observation listeners simply ignore `next`; waterfall
+ * (middleware) listeners MUST call `next()` to delegate — returning without
+ * calling it short-circuits the chain.
+ */
+export type Listener<TEvent> = (event: TEvent, next: NextFn<TEvent>) => unknown;
+
+/** Listener for the ingress waterfall; receives the union of all registered event kinds. */
+export type IngressListener<TEvents extends EventMap> = Listener<AnyBotEvent<TEvents>>;
+
+export interface OnOptions {
+    /** Run before ordinary (non-prepended) registrations. */
+    prepend?: boolean;
+}
+
+interface Registration {
+    listener: Listener<any>;
+}
+
+const noopNext: NextFn<any> = () => Promise.resolve(undefined);
+
+/**
+ * The runtime event bus. Untyped internally; the typed surface is layered on
+ * by the kernel's context view. Modes:
+ *
+ * - `emit`      fire-and-forget observation
+ * - `parallel`  await all listeners (rejects with AggregateError)
+ * - `serial`    await in order until a listener returns a non-undefined bail value
+ * - `waterfall` around-middleware: each listener receives `next`
+ */
+export class EventBus {
+    private readonly listeners = new Map<string, Registration[]>();
+
+    constructor(private readonly onError: (error: unknown) => void) {}
+
+    on(kind: string, listener: Listener<any>, options?: OnOptions): () => void {
+        const regs = this.listeners.get(kind) ?? [];
+        const reg: Registration = { listener };
+        if (options?.prepend) regs.unshift(reg);
+        else regs.push(reg);
+        this.listeners.set(kind, regs);
+        return () => {
+            const current = this.listeners.get(kind);
+            if (!current) return;
+            const index = current.indexOf(reg);
+            if (index >= 0) current.splice(index, 1);
+            if (current.length === 0) this.listeners.delete(kind);
+        };
+    }
+
+    emit(kind: string, event: unknown): void {
+        const regs = this.listeners.get(kind);
+        if (!regs) return;
+        // snapshot: listeners may unregister themselves during dispatch
+        for (const reg of regs.slice()) {
+            try {
+                const result = reg.listener(event, noopNext);
+                if (result instanceof Promise) result.catch(this.onError);
+            } catch (error) {
+                this.onError(error);
+            }
+        }
+    }
+
+    async parallel(kind: string, event: unknown): Promise<void> {
+        const regs = this.listeners.get(kind);
+        if (!regs) return;
+        const results = await Promise.allSettled(
+            [...regs].map((reg) => reg.listener(event, noopNext)),
+        );
+        const errors = results
+            .filter((result): result is PromiseRejectedResult => result.status === "rejected")
+            .map((result) => result.reason);
+        if (errors.length > 0)
+            throw new AggregateError(errors, `parallel dispatch of "${kind}" failed`);
+    }
+
+    async serial(kind: string, event: unknown): Promise<unknown> {
+        const regs = this.listeners.get(kind);
+        if (!regs) return undefined;
+        // snapshot: listeners may unregister themselves during dispatch
+        for (const reg of regs.slice()) {
+            const result = await reg.listener(event, noopNext);
+            if (result !== undefined) return result;
+        }
+        return undefined;
+    }
+
+    async waterfall(
+        kind: string,
+        event: unknown,
+        inner: (event: any) => Promise<unknown>,
+    ): Promise<unknown> {
+        const regs = this.listeners.get(kind);
+        if (!regs || regs.length === 0) return inner(event);
+        const stack = [...regs];
+        const dispatch = (index: number, current: unknown): Promise<unknown> => {
+            const reg = stack[index];
+            if (!reg) return inner(current);
+            return Promise.resolve(
+                reg.listener(current, (nextEvent?: unknown) =>
+                    dispatch(index + 1, nextEvent ?? current),
+                ),
+            );
+        };
+        return dispatch(0, event);
+    }
+}

package/src/fiber.ts

@@ -0,0 +1,41 @@
+import { runDisposers, type Disposer } from "./effect.ts";
+import type { AnyPlugin } from "./plugin.ts";
+
+export type FiberState = "pending" | "activating" | "active" | "disposed";
+
+/**
+ * One plugin application. Owns the disposers the plugin's effects produced.
+ * A fiber whose injected capabilities disappear is disposed back to
+ * `pending`, and reactivates when they return — activation order is derived
+ * from `inject`, never from boot sequencing.
+ */
+export class Fiber {
+    state: FiberState = "pending";
+    private readonly disposers: Disposer[] = [];
+
+    constructor(
+        readonly plugin: AnyPlugin,
+        readonly config: unknown,
+    ) {}
+
+    get name(): string {
+        return this.plugin.name;
+    }
+
+    addDisposer(disposer: Disposer): void {
+        if (this.state !== "active") {
+            throw new Error(`cannot register disposer on ${this.state} fiber "${this.name}"`);
+        }
+        this.disposers.push(disposer);
+    }
+
+    async dispose(
+        nextState: "pending" | "disposed",
+        onError: (error: unknown) => void,
+    ): Promise<void> {
+        if (this.state !== "active") return;
+        this.state = nextState;
+        const disposers = this.disposers.splice(0);
+        await runDisposers(disposers, onError);
+    }
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export type { Disposer, Effect, EffectResult } from "./effect.ts";
+export type {
+    AnyBotEvent,
+    BotEvent,
+    EventDef,
+    EventMap,
+    IngressListener,
+    Listener,
+    NextFn,
+    OnOptions,
+} from "./events.ts";
+export { INGRESS } from "./events.ts";
+export type {
+    Address,
+    ContentFor,
+    ContextView,
+    InputContext,
+    OutputContract,
+    OutputContractMap,
+} from "./context.ts";
+export type {
+    AnyPlugin,
+    CapsOf,
+    ConfigOf,
+    EventsOf,
+    FeaturePlugin,
+    InputPlugin,
+    InjectsOf,
+    OutputPlugin,
+    OutputsOf,
+    PluginMeta,
+    Spread,
+    StateOf,
+    Validate,
+} from "./plugin.ts";
+export { definePlugin } from "./plugin.ts";
+export type { StandardSchemaV1 } from "./schema.ts";
+export { ConfigValidationError } from "./schema.ts";
+export type { StateAccessor, StateBackend, StateView } from "./state.ts";
+export type { FiberState } from "./fiber.ts";
+export type { KernelOptions } from "./kernel.ts";
+export { createKernel, Kernel } from "./kernel.ts";

package/src/kernel.ts

@@ -0,0 +1,306 @@
+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 { 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. */
+    onError?: (error: unknown) => void;
+}
+
+/**
+ * The runtime context. Untyped internally; the kernel exposes it through
+ * {@link ContextView} parameterized by the folded type arguments.
+ */
+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);
+    }
+
+    on(kind: string, listener: never, options?: OnOptions): Disposer {
+        return this.bus.on(kind, listener, options);
+    }
+
+    emit(kind: string, event: unknown): void {
+        this.bus.emit(kind, event);
+    }
+
+    parallel(kind: string, event: unknown): Promise<void> {
+        return this.bus.parallel(kind, event);
+    }
+
+    serial(kind: string, event: unknown): Promise<unknown> {
+        return this.bus.serial(kind, event);
+    }
+
+    waterfall(
+        kind: string,
+        event: unknown,
+        inner: (event: any) => Promise<unknown>,
+    ): Promise<unknown> {
+        return this.bus.waterfall(kind, event, inner);
+    }
+
+    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);
+    }
+
+    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);
+        };
+    }
+
+    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);
+        };
+    }
+
+    isProvided(name: string): boolean {
+        return this.provided.has(name);
+    }
+
+    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;
+    }
+
+    private async process(event: BotEvent): Promise<void> {
+        await this.bus.waterfall(INGRESS, event, async (current: BotEvent) => {
+            await this.bus.parallel(current.kind, current);
+        });
+    }
+}
+
+interface FiberEntry {
+    readonly plugin: AnyPlugin;
+    readonly config: unknown;
+    readonly fiber: Fiber;
+}
+
+/**
+ * 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.
+ */
+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>>();
+    private started = false;
+
+    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;
+    }
+
+    /**
+     * 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]),
+        };
+        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>
+        >;
+    }
+
+    /** Activate all plugins whose `inject` requirements are satisfiable. */
+    async start(): 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(", ")}`);
+    }
+
+    /** 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);
+        }
+    }
+
+    private eligible(plugin: AnyPlugin): boolean {
+        return (plugin.inject ?? []).every((name) => this.runtime.isProvided(name));
+    }
+
+    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);
+        }
+    }
+
+    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;
+    }
+
+    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";
+        }
+
+        if ("apply" in plugin && plugin.apply) {
+            await collectEffect(plugin.apply(this.runtime as never, config as never), (disposer) =>
+                fiber.addDisposer(disposer),
+            );
+        }
+
+        const provides = plugin.provide ? [plugin.provide].flat() : [];
+        for (const name of provides) {
+            fiber.addDisposer(this.runtime.provide(name));
+        }
+    }
+
+    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);
+        }
+    }
+}
+
+/** Create an empty kernel. Fold plugins in with `.use(...)`. */
+export function createKernel(options?: KernelOptions): Kernel {
+    return new Kernel(options);
+}

package/src/plugin.ts

@@ -0,0 +1,225 @@
+import type {
+    Address,
+    ContextView,
+    InputContext,
+    OutputContract,
+    OutputContractMap,
+} from "./context.ts";
+import type { Effect } from "./effect.ts";
+import type { EventMap } from "./events.ts";
+import type { StandardSchemaV1 } from "./schema.ts";
+
+/**
+ * The `inject` requirement: once a plugin declares typed capability needs
+ * (`TInjects`), the runtime `inject` array is restricted to exactly those
+ * names — the runtime gate and the type-level gate cannot drift apart.
+ * Plugins with no declared needs keep the loose string form (the
+ * runtime-only capability path, e.g. `inject: ["state"]`).
+ */
+type InjectNames<TInjects extends object> = [keyof TInjects & string] extends [never]
+    ? readonly string[]
+    : readonly (keyof TInjects & string)[];
+
+/** Metadata understood by the kernel, shared by all plugin roles. */
+export interface PluginMeta<TConfig, TInjects extends object = {}> {
+    readonly name: string;
+    /** Capabilities that must be provided before this plugin activates. */
+    readonly inject?: InjectNames<TInjects>;
+    /**
+     * Capability names this plugin provides once active. Provided valueless
+     * by the kernel after `apply`; to provide a typed value, declare
+     * `TProvides` and call `ctx.provide(name, value)` in `apply` instead.
+     */
+    readonly provide?: string | readonly string[];
+    /** Standard-Schema validator applied to config before `apply` runs. */
+    readonly Config?: StandardSchemaV1<unknown, TConfig>;
+}
+
+/**
+ * Produces events of the kinds in `TEvents`. Knows how to listen, nothing
+ * else. May declare typed capabilities it provides (`TProvides`) and
+ * consumes (`TInjects` — folded into its `apply` context, gated at `use()`).
+ */
+export interface InputPlugin<
+    TEvents extends EventMap = EventMap,
+    TConfig = void,
+    TName extends string = string,
+    TProvides extends object = {},
+    TInjects extends object = {},
+> extends PluginMeta<TConfig, TInjects> {
+    readonly role: "input";
+    readonly name: TName;
+    apply(ctx: InputContext<TEvents, TProvides> & TInjects, config: TConfig): Effect;
+}
+
+/** Consumes addresses of its platform. Reply semantics live in `TContent`, not the core. */
+export interface OutputPlugin<
+    TPlatform extends string = string,
+    TAddress extends Address<TPlatform> = Address<TPlatform>,
+    TContent = unknown,
+    TConfig = void,
+    TName extends string = string,
+    TProvides extends object = {},
+    TInjects extends object = {},
+> extends PluginMeta<TConfig, TInjects> {
+    readonly role: "output";
+    readonly name: TName;
+    readonly platform: TPlatform;
+    send(to: TAddress, content: TContent): void | Promise<void>;
+    apply?(ctx: ContextView<{}, {}, {}, TProvides> & TInjects, config: TConfig): Effect;
+}
+
+/**
+ * A unit of behavior. Declares the event kinds it handles (`TNeeds`), the
+ * output platforms it sends through (`TSends`), and optionally a state
+ * schema (`TStateSchema`) and typed capabilities: `TProvides` (read back
+ * through `CapsOf` at the kernel fold; `provide` is type-checked against
+ * it) and `TInjects` (folded into the `apply` context; the kernel checks
+ * at `use()` time that the fold so far provides them).
+ */
+export interface FeaturePlugin<
+    TNeeds extends EventMap = {},
+    TSends extends OutputContractMap = {},
+    TStateSchema = undefined,
+    TConfig = void,
+    TName extends string = string,
+    TProvides extends object = {},
+    TInjects extends object = {},
+> extends PluginMeta<TConfig, TInjects> {
+    readonly role?: "feature";
+    readonly name: TName;
+    apply(
+        ctx: ContextView<
+            TNeeds,
+            TSends,
+            TStateSchema extends undefined ? {} : { [K in TName]: TStateSchema },
+            TProvides
+        > &
+            TInjects,
+        config: TConfig,
+    ): Effect;
+}
+
+export type AnyPlugin =
+    | InputPlugin<any, any, any, any, any>
+    | OutputPlugin<any, any, any, any, any, any, any>
+    | FeaturePlugin<any, any, any, any, any, any, any>;
+
+/* ------------------------------------------------------------------ */
+/* Type-level fold: how each plugin shapes the kernel's type params    */
+/* ------------------------------------------------------------------ */
+
+export type EventsOf<TPlugin> =
+    TPlugin extends InputPlugin<infer TEvents, any, any, any, any> ? TEvents : {};
+
+export type OutputsOf<TPlugin> =
+    TPlugin extends OutputPlugin<
+        infer TPlatform,
+        infer TAddress,
+        infer TContent,
+        any,
+        any,
+        any,
+        any
+    >
+        ? { [K in TPlatform]: OutputContract<TAddress, TContent> }
+        : {};
+
+export type StateOf<TPlugin> =
+    TPlugin extends FeaturePlugin<any, any, infer TStateSchema, any, infer TName, any, any>
+        ? TStateSchema extends undefined
+            ? {}
+            : { [K in TName]: TStateSchema }
+        : {};
+
+/** Typed capabilities a plugin provides, folded into the kernel's `TCaps`. */
+export type CapsOf<TPlugin> =
+    TPlugin extends FeaturePlugin<any, any, any, any, any, infer TProvides, any>
+        ? TProvides
+        : TPlugin extends InputPlugin<any, any, any, infer TProvides, any>
+          ? TProvides
+          : TPlugin extends OutputPlugin<any, any, any, any, any, infer TProvides, any>
+            ? TProvides
+            : {};
+
+/** Typed capabilities a plugin consumes, gated against the fold at `use()`. */
+export type InjectsOf<TPlugin> =
+    TPlugin extends FeaturePlugin<any, any, any, any, any, any, infer TInjects>
+        ? TInjects
+        : TPlugin extends InputPlugin<any, any, any, any, infer TInjects>
+          ? TInjects
+          : TPlugin extends OutputPlugin<any, any, any, any, any, any, infer TInjects>
+            ? TInjects
+            : {};
+
+/** Config type: from the schema if present, else from `apply`'s second parameter. */
+export type ConfigOf<TPlugin> = TPlugin extends { Config: StandardSchemaV1<any, infer TOutput> }
+    ? TOutput
+    : TPlugin extends { apply: (ctx: any, config: infer TConfig) => any }
+      ? unknown extends TConfig
+          ? void
+          : TConfig
+      : void;
+
+/** Makes the config argument optional exactly when `void` is assignable to it. */
+export type Spread<T> = [T] extends [void] ? [config?: T] : [config: T];
+
+type NeedsOf<TPlugin> =
+    TPlugin extends FeaturePlugin<infer TNeeds, any, any, any, any, any, any> ? TNeeds : {};
+type SendsOf<TPlugin> =
+    TPlugin extends FeaturePlugin<any, infer TSends, any, any, any, any, any> ? TSends : {};
+
+type MissingKeys<TDeclared extends object, TRegistered extends object> = Exclude<
+    keyof TDeclared & string,
+    keyof TRegistered & string
+>;
+
+/** Declared capability keys whose value types don't match the folded capability. */
+type MismatchedKeys<TDeclared extends object, TRegistered extends object> = {
+    [K in keyof TDeclared & string]: K extends keyof TRegistered & string
+        ? TDeclared[K] extends TRegistered[K]
+            ? never
+            : K
+        : never;
+}[keyof TDeclared & string];
+
+/**
+ * Compile-time gate on `use()`: a plugin can only be registered once every
+ * event kind it handles, every output platform it sends through, and every
+ * typed capability it injects is already in the fold — with a compatible
+ * value type.
+ */
+export type Validate<
+    TPlugin,
+    TEvents extends EventMap,
+    TOutputs extends OutputContractMap,
+    TCaps extends object,
+> = [MissingKeys<NeedsOf<TPlugin>, TEvents>] extends [never]
+    ? [MissingKeys<SendsOf<TPlugin>, TOutputs>] extends [never]
+        ? [MissingKeys<InjectsOf<TPlugin>, TCaps>] extends [never]
+            ? [MismatchedKeys<InjectsOf<TPlugin>, TCaps>] extends [never]
+                ? unknown
+                : {
+                      readonly "mismatched capability types": MismatchedKeys<
+                          InjectsOf<TPlugin>,
+                          TCaps
+                      >;
+                  }
+            : { readonly "unprovided capabilities": MissingKeys<InjectsOf<TPlugin>, TCaps> }
+        : { readonly "unregistered output platforms": MissingKeys<SendsOf<TPlugin>, TOutputs> }
+    : { readonly "unregistered event kinds": MissingKeys<NeedsOf<TPlugin>, TEvents> };
+
+/** Identity helper for authoring feature plugins with precise generics. */
+export function definePlugin<
+    TNeeds extends EventMap = {},
+    TSends extends OutputContractMap = {},
+    TStateSchema = undefined,
+    TConfig = void,
+    TName extends string = string,
+    TProvides extends object = {},
+    TInjects extends object = {},
+>(
+    plugin: FeaturePlugin<TNeeds, TSends, TStateSchema, TConfig, TName, TProvides, TInjects>,
+): typeof plugin {
+    return plugin;
+}

package/src/schema.ts

@@ -0,0 +1,46 @@
+/**
+ * Minimal structural copy of the Standard Schema v1 interface
+ * (https://standardschema.dev). Types-only: any compliant validator
+ * (zod, valibot, arktype, schemastery, ...) plugs in without a runtime
+ * dependency on the framework.
+ */
+export interface StandardSchemaV1<TInput = unknown, TOutput = TInput> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<TOutput> | Promise<Result<TOutput>>;
+        readonly types?: { input: TInput; output: TOutput } | undefined;
+    };
+}
+
+export type Result<TOutput> =
+    | { readonly value: TOutput; readonly issues?: undefined }
+    | { readonly issues: readonly Issue[] };
+
+export interface Issue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[] | undefined;
+}
+
+export class ConfigValidationError extends Error {
+    constructor(
+        readonly plugin: string,
+        readonly issues: readonly Issue[],
+    ) {
+        super(
+            `invalid config for plugin "${plugin}":\n${issues.map((issue) => `  - ${issue.message}`).join("\n")}`,
+        );
+        this.name = "ConfigValidationError";
+    }
+}
+
+/** Validate `value` against a plugin's schema, throwing on failure. */
+export async function validateConfig(
+    plugin: string,
+    schema: StandardSchemaV1<unknown, unknown>,
+    value: unknown,
+): Promise<unknown> {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues) throw new ConfigValidationError(plugin, result.issues);
+    return result.value;
+}

package/src/state.ts

@@ -0,0 +1,58 @@
+/**
+ * Pluggable state. The framework core is stateless; state is an ordinary
+ * feature plugin providing its backend as the `"state"` capability (at most
+ * one may be active). Plugins declare their schema at the type level and
+ * receive a typed accessor namespaced to their plugin name.
+ */
+export interface StateBackend {
+    get(namespace: string, key: string): Promise<unknown>;
+    set(namespace: string, key: string, value: unknown, ttlMs?: number): Promise<void>;
+    delete(namespace: string, key: string): Promise<void>;
+}
+
+/** Typed view of one plugin's state, bound to its namespace. */
+export interface StateAccessor<TSchema> {
+    get<TKey extends keyof TSchema & string>(key: TKey): Promise<TSchema[TKey] | undefined>;
+    set<TKey extends keyof TSchema & string>(
+        key: TKey,
+        value: TSchema[TKey],
+        ttlMs?: number,
+    ): Promise<void>;
+    delete(key: keyof TSchema & string): Promise<void>;
+}
+
+/**
+ * Marker type for `ctx.state` when no plugin declared a state schema —
+ * "stateless by default" is enforced at compile time. Any access errors with
+ * this type's name in the message.
+ */
+export interface NoStateDeclared {
+    readonly "no state schema declared": "register a feature plugin with a TStateSchema to enable ctx.state";
+}
+
+/**
+ * `ctx.state`. Folds to {@link NoStateDeclared} when no plugin declared a
+ * state schema.
+ */
+export type StateView<TState extends object> = keyof TState extends never
+    ? NoStateDeclared
+    : {
+          for<TName extends keyof TState & string>(plugin: TName): StateAccessor<TState[TName]>;
+      };
+
+export function createStateAccessor<TSchema>(
+    backend: StateBackend,
+    namespace: string,
+): StateAccessor<TSchema> {
+    return {
+        async get(key) {
+            return (await backend.get(namespace, key)) as TSchema[typeof key] | undefined;
+        },
+        async set(key, value, ttlMs) {
+            await backend.set(namespace, key, value, ttlMs);
+        },
+        async delete(key) {
+            await backend.delete(namespace, key);
+        },
+    };
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "include": ["src"]
+}