@lambdot/core 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

package/README.md

@@ -48,6 +48,14 @@ as })` feeds a plugin from the namespaces visible so far and exposes its
   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
 
@@ -111,7 +119,8 @@ Types, grouped by theme:
 - **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), `AnyUnit`.
+  `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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdot/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Embers-of-the-Fire/lambdot",

package/src/index.ts

@@ -5,6 +5,7 @@ export type {
     AnyUnit,
     Composite,
     ConfigOf,
+    Engine,
     InOf,
     Kernel,
     NameOf,

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" });
+});

package/src/kernel.ts

@@ -134,6 +134,9 @@ class CompositeRuntime implements RuntimeUnit {
         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);
     }
@@ -142,7 +145,18 @@ class CompositeRuntime implements RuntimeUnit {
         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);
+    }
+
     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,
@@ -207,6 +221,40 @@ class CompositeRuntime implements RuntimeUnit {
     }
 }
 
+/**
+ * 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,
+    ) {}
+
+    /** 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);
+    }
+
+    activate(input: unknown, scope: Scope, _config: unknown): Promise<unknown> {
+        return this.inner.activate(input, scope, undefined);
+    }
+
+    start(input?: unknown): Promise<void> {
+        return this.inner.start(input);
+    }
+
+    stop(): Promise<void> {
+        return this.inner.stop();
+    }
+
+    get ctx(): Record<string, unknown> {
+        return this.inner.ctx;
+    }
+}
+
 /**
  * Author a plugin. The spec is just `name`, optional `Config` schema, and
  * `apply`; the returned plugin carries the composition methods (`use`,

package/src/plugin.ts

@@ -73,12 +73,42 @@ export interface Composite<TIn = void, TVisible = {}, THidden = {}, TName extend
         ...args: WireArgs<TUnit, InputPart<TIn> & TVisible & THidden, TAs>
     ): Composite<TIn, TVisible, THidden & { [K in TAs]: OutOf<TUnit> }, TName>;
 
+    /**
+     * Seal the chain into a final artifact under a new name. The engine's
+     * type is exactly `Engine<TIn, TVisible, TAlias>`: the external input
+     * requirement is preserved, the `bind`-encapsulated internals
+     * (`THidden`) and the chain's own name are erased. Composing onto an
+     * exposed chain throws at runtime.
+     */
+    expose<const TAlias extends string>(name: TAlias): Engine<TIn, TVisible, TAlias>;
+
     start(...args: StartArgs<TIn>): Promise<void>;
     stop(): Promise<void>;
     readonly ctx: TVisible;
 }
 
-export type AnyUnit = Plugin<any, any, any, any> | Composite<any, any, any, any>;
+/**
+ * A sealed composition — what {@link Composite.expose} returns. Structurally
+ * a unit (`name` + `apply`), so it wires into a supervisor kernel like any
+ * plugin, but the composition methods are gone: an engine is final. Its
+ * output is the chain's visible context; its input is the chain's external
+ * requirement. Internal (`bind`ed) namespaces exist only at runtime, never
+ * in the type.
+ */
+export interface Engine<TIn = void, TOut = {}, TName extends string = string> {
+    readonly name: TName;
+    apply(input: TIn, scope: Scope, config: void): Promise<TOut>;
+
+    start(...args: StartArgs<TIn>): Promise<void>;
+    stop(): Promise<void>;
+    /** The exposed namespaces. Populated during `start`; typed regardless. */
+    readonly ctx: TOut;
+}
+
+export type AnyUnit =
+    | Plugin<any, any, any, any>
+    | Composite<any, any, any, any>
+    | Engine<any, any, any>;
 
 /** The kernel is a composition seeded empty: `createKernel().use(...)`. */
 export type Kernel<TVisible = {}, THidden = {}> = Composite<void, TVisible, THidden, "kernel">;