@lambdot/core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- [#12](https://github.com/Embers-of-the-Fire/lambdot/pull/12) [`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7) Thanks [@Embers-of-the-Fire](https://github.com/Embers-of-the-Fire)! - Add `Composite.expose(name)`: seal a kernel chain into a final, named `Engine` artifact. The engine preserves the chain's external input requirement, erases `bind`-encapsulated internals from its type, drops the composition methods (`use`/`bind` throw at runtime once exposed), and wires into a supervisor kernel under its new name.
+
+### Patch Changes
+
+- [#12](https://github.com/Embers-of-the-Fire/lambdot/pull/12) [`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7) Thanks [@Embers-of-the-Fire](https://github.com/Embers-of-the-Fire)! - Implement `Engine.apply` on the runtime behind `Composite.expose`: the sealed engine now delegates to its inner composition, so calling `engine.apply(input, scope, config)` directly works instead of throwing `TypeError: engine.apply is not a function`.
+
+## 0.1.1
+
+### Patch Changes
+
+- [#10](https://github.com/Embers-of-the-Fire/lambdot/pull/10) [`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355) Thanks [@Embers-of-the-Fire](https://github.com/Embers-of-the-Fire)! - Switch inter-package dependency pins from exact versions to `workspace:*` so workspace members always resolve against local sources during development; pnpm rewrites the protocol to exact versions at pack/publish time.
+
 ## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/core-v0.0.1...core-v0.1.0) (2026-08-29)
 
 

package/README.md

@@ -0,0 +1,144 @@
+# @lambdot/core
+
+The lambdot kernel: a stateless, serverless, non-context-aware composition
+runtime for chatbots. It owns no conversational data and no platform
+semantics — inputs, outputs, state backends, and features are all plugins,
+composed through TypeScript's type system. A plugin is a function:
+`apply(input, scope, config)` maps a declared input record to an output
+value. Every `use(...)`/`bind(...)` wires the next plugin's input with a
+`mapping` from the namespaces visible so far, so wiring a plugin before its
+dependencies is a compile error. Published on npm as `@lambdot/core`.
+
+## Concepts
+
+- **A plugin is a function.** `apply(input, scope, config)` receives exactly
+  the input record it declares and returns the output value it emits. There
+  are no plugin roles and no lifecycle hooks: `scope.onDispose(d)` collects
+  teardown (run in reverse on `stop()`), `scope.onError(e)` sinks background
+  errors. Config is validated through any Standard Schema validator
+  (`Config`), with failures surfacing as `ConfigValidationError`.
+- **Composition is function application.** `use(plugin, { mapping, option,
+as })` feeds a plugin from the namespaces visible so far and exposes its
+  output on the final `ctx` under its name. `bind(...)` feeds it the same
+  way but keeps the output internal to the chain — visible to later
+  `mapping`s, absent from `ctx`. `mapping` is omitted when the plugin's
+  input keys already match visible namespaces (identity wiring); `option`
+  carries config, required exactly when the config type is non-void; `as`
+  renames the namespace.
+- **Streams are the message-flow primitive.** `Stream<T>` is an
+  `AsyncIterable` with broadcast semantics — every consumer sees every item,
+  in order, at its own pace. Inputs push from callbacks through `channel()`
+  and emit a `shareStream` view; features transform with
+  `mapStream`/`filterStream`/`mergeStreams`; outputs consume command streams
+  with `pumpStream`. A feature handling two platforms merges their streams;
+  a command stream serving two platforms is filtered per output by
+  `address.platform` in the wiring `mapping`.
+- **The envelope is free of platform semantics.** `Message` is `payload` +
+  `address` (+ `id`/`at`, minted by `message()`); `Command` is `address` +
+  `content`. `address` is opaque to the core and meaningful only to the
+  platform that produced it.
+- **Platform-specific services are ordinary namespace values.** A REST
+  client, a webhook handler, a database connection — anything a plugin emits
+  lands on `ctx` (or stays internal via `bind`) with its type intact.
+- **State is a plugin.** The core is stateless; a state plugin emits a
+  `StateBackend` as its namespace value, and a stateful feature declares the
+  backend in its input and builds a typed accessor namespaced to its own
+  name via `createStateAccessor(backend, name)`.
+- **Activation order is definition order.** `start()` activates in
+  composition order — resolve mapping, validate config, `apply` — and
+  `stop()` disposes in reverse. Ordering mistakes are compile errors in the
+  mappings, not runtime states.
+- **`expose(name)` seals a chain into a final engine.** The engine is the
+  chain as an artifact: named, runnable (`start`/`stop`/`ctx`), and wireable
+  into a supervisor kernel under its new name — but no longer composable
+  (`use`/`bind` are gone from the type and throw at runtime). Its type is
+  exactly `Engine<TIn, TVisible, TName>`: the chain's external input
+  requirement survives, while the `bind`-encapsulated internals and the
+  chain's own name are erased. This is how N instances of one bot stack nest
+  into a supervisor without name tags or leaked internals.
+
+## Usage
+
+```ts
+import { consolePlatform, type ConsoleLine } from "@lambdot/console";
+import type { Stream } from "@lambdot/core";
+import { createKernel, definePlugin, mapStream } from "@lambdot/core";
+
+const echo = definePlugin({
+    name: "echo",
+    apply(input: { "console/lines": Stream<ConsoleLine> }) {
+        return mapStream(input["console/lines"], (event) => ({
+            address: event.address,
+            content: `echo: ${event.payload}`,
+        }));
+    },
+});
+
+const cli = consolePlatform();
+
+const kernel = createKernel()
+    .use(cli.lines) // exposes ctx["console/lines"]: Stream<ConsoleLine>
+    .use(echo) // identity wiring: the input keys already match
+    .bind(cli.printer, { mapping: (ctx) => ({ replies: ctx.echo }) });
+
+await kernel.start();
+process.on("SIGINT", () => void kernel.stop().then(() => process.exit(0)));
+```
+
+`use(cli.lines)` exposes the line stream under `"console/lines"`. `use(echo)`
+needs no `mapping`: its declared input `{ "console/lines": ... }` is already
+satisfied by the visible ctx. The printer declares `{ replies: ... }`, which
+no namespace provides — so the `mapping` is required, and its `ctx`
+parameter is typed as exactly what's visible so far; referencing a
+not-yet-composed namespace is a compile error. The printer is `bind`ed, so
+`ctx["console/printer"]` does not typecheck.
+
+## API overview
+
+Runtime values:
+
+| Export                               | What it is                                                               |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| `createKernel(options?)`             | Creates an empty composition; `options.onError` sinks background errors. |
+| `definePlugin(spec)`                 | Authors a plugin from `{ name, Config?, apply }`.                        |
+| `message(payload, address)`          | Mints a `Message` envelope with a fresh `id`/`at`.                       |
+| `channel()`                          | Push-side bridge from callbacks into the pull world.                     |
+| `shareStream(stream)`                | Multicasts a stream to any number of consumers.                          |
+| `mapStream`                          | Per-item transform (async mapper allowed; items stay sequential).        |
+| `filterStream`                       | Per-item filter; the type-guard form narrows the item type.              |
+| `mergeStreams`                       | Interleaves several streams in arrival order.                            |
+| `pumpStream`                         | Background sequential consumer; errors go to `onError`.                  |
+| `createStateAccessor(backend, name)` | Typed, namespaced view over a `StateBackend`.                            |
+| `ConfigValidationError`              | Thrown when a plugin's `Config` schema rejects its config.               |
+
+Types, grouped by theme:
+
+- **Messages** — `Message` (the inbound envelope: `payload`, `address`,
+  `id`, `at`), `Command` (the outbound pair: `address`, `content`),
+  `Address` (the `platform` routing tag).
+- **Streams** — `Stream`, `Channel`.
+- **Plugins** — `Plugin` (name, `Config`, `apply`, plus the composition
+  methods), `PluginSpec` (the author-facing half), `Scope` (`onDispose` /
+  `onError`), `Composite` (a composed chain — itself wireable), `Engine`
+  (a chain sealed by `expose`: final, named, internals erased), `AnyUnit`.
+- **The composition types** — `InOf`, `OutOf`, `ConfigOf`, `NameOf`,
+  `WireArgs` (the `use`/`bind` options: `mapping` required when identity
+  wiring fails, `option` required when config is non-void, `as` to rename),
+  `StartArgs`, `Kernel` (a `Composite` seeded empty).
+- **Config** — `StandardSchemaV1` (structural copy of the Standard Schema v1
+  interface; zod, valibot, arktype, … plug in with no runtime dependency).
+- **State** — `StateBackend` (`get`/`set`/`delete` over namespace + key,
+  optional `ttlMs`), `StateAccessor`.
+- **Lifecycle** — `Disposer`.
+- **Kernel options** — `KernelOptions`.
+
+## Examples
+
+The worked walkthroughs live in the repository's `examples/` directory:
+`echo-bot` (the minimal bot above, plus compile-time composition tests in
+`type-test.ts`), `counter-bot` (the pluggable-state walkthrough), and
+`websocket-bot` (the transport-wiring walkthrough).
+
+## License
+
+Dual-licensed under [Apache-2.0](../../../LICENSE-APACHE) and [MIT](../../../LICENSE-MIT).

package/package.json

@@ -1,11 +1,16 @@
 {
-    "name": "@lambdot/core",
-    "version": "0.1.0",
-    "type": "module",
-    "exports": {
-        ".": "./src/index.ts"
-    },
-    "publishConfig": {
-        "access": "public"
-    }
-}
+  "name": "@lambdot/core",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Embers-of-the-Fire/lambdot",
+    "directory": "packages/core/core"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/effect.ts

@@ -1,40 +1,9 @@
 /**
- * A function that undoes a registration or allocation. Collected by the
- * fiber that owns the plugin instance and run on unload/shutdown.
+ * A function that undoes a registration or allocation. Collected through
+ * `scope.onDispose` and run when the owning plugin unloads.
  */
 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[],

package/src/index.ts

@@ -1,42 +1,33 @@
-export type { Disposer, Effect, EffectResult } from "./effect.ts";
+export type { Disposer } from "./effect.ts";
+export type { Address, Command, Message } from "./message.ts";
+export { message } from "./message.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,
+    AnyUnit,
+    Composite,
     ConfigOf,
-    EventsOf,
-    FeaturePlugin,
-    InputPlugin,
-    InjectsOf,
-    OutputPlugin,
-    OutputsOf,
-    PluginMeta,
-    Spread,
-    StateOf,
-    Validate,
+    Engine,
+    InOf,
+    Kernel,
+    NameOf,
+    OutOf,
+    Plugin,
+    PluginSpec,
+    Scope,
+    StartArgs,
+    WireArgs,
 } 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 { StateAccessor, StateBackend } from "./state.ts";
+export { createStateAccessor } from "./state.ts";
+export type { Channel, Stream } from "./stream.ts";
+export {
+    channel,
+    filterStream,
+    mapStream,
+    mergeStreams,
+    pumpStream,
+    shareStream,
+} from "./stream.ts";
 export type { KernelOptions } from "./kernel.ts";
-export { createKernel, Kernel } from "./kernel.ts";
+export { createKernel, definePlugin } from "./kernel.ts";

package/src/kernel.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { Disposer, Scope } from "./index.ts";
+import { createKernel, definePlugin } from "./index.ts";
+
+function makeScope(disposers: Disposer[]): Scope {
+    return {
+        onDispose: (disposer) => {
+            disposers.push(disposer);
+        },
+        onError: () => {},
+    };
+}
+
+void test("engine.apply activates the chain and returns its visible context", async () => {
+    const greet = definePlugin<void, string>({
+        name: "greet",
+        apply: () => "hello",
+    });
+    const engine = createKernel().use(greet).expose("greeter");
+
+    const disposers: Disposer[] = [];
+    const output = await engine.apply(undefined, makeScope(disposers), undefined);
+    assert.deepEqual(output, { greet: "hello" });
+    assert.deepEqual(engine.ctx, { greet: "hello" });
+
+    // Applying the engine registered its teardown with the caller's scope.
+    for (const dispose of disposers.splice(0)) await dispose();
+    assert.deepEqual(engine.ctx, {});
+});
+
+void test("engine.apply feeds the external input through the chain", async () => {
+    const echo = definePlugin<{ value: string }, string>({
+        name: "echo",
+        apply: (input) => input.value.toUpperCase(),
+    });
+    const engine = createKernel()
+        .use(echo, { mapping: (ctx) => ctx as unknown as { value: string } })
+        .expose("upper");
+
+    const output = await engine.apply({ value: "hi" } as unknown as void, makeScope([]), undefined);
+    assert.deepEqual(output, { echo: "HI" });
+});