@telorun/kernel 0.2.7 → 0.2.8

package/README.md

@@ -0,0 +1,100 @@
+# Telo Kernel
+
+**Target:** Node.js (Rust/Go ports planned)
+
+**Input:** A module manifest YAML file or a directory of YAML files
+
+## 1. Core Concepts
+
+The Telo Kernel is a **declarative execution host**. You describe resources in YAML; the kernel loads them, wires up controllers, and keeps the process alive until all work is done.
+
+The kernel performs three functions:
+
+- **Loader:** Reads YAML files, compiles them through the CEL-YAML templating engine, and resolves controller entrypoints.
+- **Registry:** Indexes resource instances by a composite key of `module.Kind.name`.
+- **Kernel:** Orchestrates the boot sequence, manages the event bus, and routes invocations.
+
+**Module loading and resource discovery** happen during the load phase, before any resource is initialized.
+
+---
+
+## 2. Resource Definitions
+
+Every resource in a manifest is an instance of a `Kernel.Definition`. A definition declares several orthogonal facets:
+
+| Facet         | Field          | Purpose                                                                             |
+| ------------- | -------------- | ----------------------------------------------------------------------------------- |
+| `capability`  | Lifecycle role | One of `Runnable`, `Service`, `Invocable`, `Mount`, `Provider` — mutually exclusive |
+| `topology`    | Composition    | How the kind is structured internally: `Sequence`, `Router`, `Workflow`             |
+| `extends`     | Inheritance    | Abstract interface this kind fulfills (cross-module plugin pattern)                 |
+| `controllers` | Execution      | PURL-referenced controller implementations                                          |
+
+### Capability
+
+`capability` assigns a single lifecycle role. The kernel uses it to determine when to call `init()`, `run()`, or `invoke()` on the controller. A definition declares exactly one capability.
+
+→ [docs/capabilities.md](docs/capabilities.md)
+
+### Topology
+
+`topology` names the structural composition pattern of a kind — how it is assembled internally from steps, routes, or nodes. It drives built-in execution when no controller is declared, structural validation in the analyzer, and canvas rendering in the editor.
+
+→ [docs/topology.md](docs/topology.md) _(design proposal — not yet implemented)_
+
+### Inheritance
+
+`extends` declares that a definition fulfills an abstract interface (`Kernel.Abstract`) declared by another module. This is the plugin pattern for subsystems like workflow backends.
+
+→ [docs/inheritance.md](docs/inheritance.md)
+
+For the complete `Kernel.Definition` field reference, see [docs/resource-definition.md](docs/resource-definition.md).
+
+---
+
+## 3. CEL-YAML Templating
+
+Before a manifest object is processed, it is compiled by the **CEL-YAML templating engine** (`@telorun/yaml-cel-templating`). This runs as part of loading — any compilation error halts the boot sequence immediately.
+
+The compile step provides `{ env: process.env }` as the initial context, so environment variables are available everywhere:
+
+```yaml
+resources:
+  - ${{ env.MY_MANIFEST_PATH }}
+```
+
+### Interpolation
+
+- `${{ expr }}` — the interpolation syntax used throughout Telo
+
+When the entire string is a single interpolation, the result preserves the CEL type (integer, boolean, etc.). Mixed strings are coerced to string.
+
+**See [../yaml-cel-templating/README.md](../yaml-cel-templating/README.md) for full directive reference.**
+
+---
+
+## 4. Kernel.Definition
+
+Modules declare the resource kinds they handle using `Kernel.Definition`:
+
+```yaml
+kind: Kernel.Definition
+metadata:
+  name: Server # fully-qualified kind: Http.Server
+  module: Http
+capability: Service # one of: Runnable, Service, Invocable, Mount, Provider, Template
+schema: # JSON Schema — validated against each resource before create()
+  type: object
+  properties:
+    port: { type: integer }
+    host: { type: string }
+  required: [port]
+controllers:
+  # Ordered list of Package URL (PURL) candidates — first match for the current runtime is used
+  - pkg:npm/@telorun/run@>=1.0.0?local_path=./nodejs#sequence
+  - pkg:cargo/telorun-run@>=1.0.0?local_path=./rust#sequence
+  - pkg:golang/github.com/telorun/run@>=1.0.0?local_path=./go#sequence
+```
+
+When a `Kernel.Definition` instance initializes, it resolves and loads the controller module
+and registers it with the kernel. For the full resolution algorithm (local path, host
+node_modules, registry cache) and PURL format, see [controllers.md](docs/controllers.md).

package/dist/controllers/module/import-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-controller.d.ts","sourceRoot":"","sources":["../../../src/controllers/module/import-controller.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAItE,wBAAsB,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuG3F;AAeD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBlB,CAAC"}
+{"version":3,"file":"import-controller.d.ts","sourceRoot":"","sources":["../../../src/controllers/module/import-controller.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAUtE,wBAAsB,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiH3F;AAeD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBlB,CAAC"}

package/dist/controllers/module/import-controller.js

@@ -1,6 +1,8 @@
 import { DiagnosticSeverity, Loader, StaticAnalyzer } from "@telorun/analyzer";
-import { EvaluationContext, RuntimeError } from "@telorun/sdk";
+import { RuntimeError } from "@telorun/sdk";
+import { ModuleContext } from "../../module-context.js";
 import { LocalFileAdapter } from "../../manifest-adapters/local-file-adapter.js";
+const importAnalysisCache = new Map();
 export async function create(resource, ctx) {
     const alias = resource.metadata.name;
     const loader = new Loader([new LocalFileAdapter()]);
@@ -10,10 +12,21 @@ export async function create(resource, ctx) {
     // preventing false UNDEFINED_KIND errors for kinds that come from the module's own imports.
     const resolvedUrl = new URL(moduleSource, ctx.moduleContext.source).toString();
     const analysisManifests = await loader.loadManifests(resolvedUrl);
-    const diagnostics = new StaticAnalyzer().analyze(analysisManifests);
-    const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
+    const signature = JSON.stringify(analysisManifests);
+    const cached = importAnalysisCache.get(resolvedUrl);
+    let errors;
+    if (cached && cached.signature === signature) {
+        errors = cached.errors;
+    }
+    else {
+        const diagnostics = new StaticAnalyzer().analyze(analysisManifests);
+        errors = diagnostics
+            .filter((d) => d.severity === DiagnosticSeverity.Error)
+            .map((d) => d.message);
+        importAnalysisCache.set(resolvedUrl, { signature, errors });
+    }
     if (errors.length > 0) {
-        throw new RuntimeError("ERR_MANIFEST_VALIDATION_FAILED", errors.map((d) => d.message).join("\n"));
+        throw new RuntimeError("ERR_MANIFEST_VALIDATION_FAILED", errors.join("\n"));
     }
     // Load target module manifests for runtime. Inject variables/secrets as compile context so
     // that ${{ variables.x }} / ${{ secrets.y }} templates in the child module resolve correctly.
@@ -32,11 +45,7 @@ export async function create(resource, ctx) {
     validateRequiredInputs(moduleManifest.secrets ?? {}, resource.secrets ?? {}, "secrets");
     // Create child context with the imported variables/secrets baked in, so that
     // ${{ variables.x }} / ${{ secrets.y }} templates resolve correctly at runtime.
-    const child = ctx.moduleContext.spawnChild(new EvaluationContext(ctx.moduleContext.source, {
-        variables: resource.variables ?? {},
-        secrets: resource.secrets ?? {},
-        resources: {},
-    }, ctx.moduleContext.createInstance, ctx.moduleContext.secretValues, ctx.moduleContext.emit));
+    const child = ctx.moduleContext.spawnChild(new ModuleContext(ctx.moduleContext.source, resource.variables ?? {}, resource.secrets ?? {}, {}, [], ctx.moduleContext.createInstance, ctx.moduleContext.emit));
     for (const manifest of manifests) {
         child.registerManifest(manifest);
     }

package/dist/controllers/module/import-controller.js.map

@@ -1 +1 @@
-{"version":3,"file":"import-controller.js","sourceRoot":"","sources":["../../../src/controllers/module/import-controller.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"import-controller.js","sourceRoot":"","sources":["../../../src/controllers/module/import-controller.ts"],"names":[],"mappings":"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"}

package/dist/evaluation-context.d.ts

@@ -1,16 +1,7 @@
-import type { ResourceInstance, ResourceManifest } from "@telorun/sdk";
-/** Four-stage resource lifecycle defined in resource-lifecycle.md */
-export type LifecycleState = "Pending" | "Validated" | "Initialized" | "Draining" | "Teardown";
+import { resourceKey, type EvaluationContext as IEvaluationContext, type EmitEvent, type InstanceFactory, type LifecycleState, type PreInitHook, type ResourceInstance, type ResourceManifest, type ScopeHandle } from "@telorun/sdk";
+export { resourceKey };
 /**
- * Creates a ResourceInstance for the given manifest, or returns null if not yet
- * ready (e.g. a dependency is still initializing). Injected at construction so
- * every EvaluationContext node owns its full resource lifecycle.
- */
-export type InstanceFactory = (resource: ResourceManifest) => Promise<ResourceInstance | null>;
-/** Canonical key for a resource instance: "<module>.<kind>.<name>" */
-export declare function resourceKey(r: ResourceManifest): string;
-/**
- * Base class for all evaluation contexts. Owns CEL evaluation, template
+ * Base class for all evaluation contexts. Owns template
  * expansion, secrets redaction, and the generic resource lifecycle tree.
  *
  * Every EvaluationContext node can:
@@ -20,13 +11,16 @@ export declare function resourceKey(r: ResourceManifest): string;
  *   - Run a multi-pass initialization loop (initializeResources)
  *   - Cascade teardown depth-first through the tree (teardownResources)
  */
-export declare class EvaluationContext {
+export declare class EvaluationContext implements IEvaluationContext {
+    readonly source: string;
+    readonly id: string;
     protected _context: Record<string, unknown>;
     protected _secretValues: Set<string>;
     protected _createInstance: InstanceFactory;
+    readonly emit: EmitEvent;
     /** Position in the lifecycle tree. */
-    parent: EvaluationContext | undefined;
-    readonly children: EvaluationContext[];
+    parent: IEvaluationContext | undefined;
+    readonly children: IEvaluationContext[];
     /** Current lifecycle state of this context node. */
     state: LifecycleState;
     /** Resource instances owned by this context node, keyed by resourceKey(). */
@@ -34,58 +28,102 @@ export declare class EvaluationContext {
         resource: ResourceManifest;
         instance: ResourceInstance;
     }>;
+    /** Resources that have been created but not yet initialized (between phases). */
+    protected readonly createdInstances: Map<string, {
+        resource: ResourceManifest;
+        instance: ResourceInstance;
+        ctx: any;
+    }>;
     /** Resources queued for initialization on this context node. */
-    readonly pendingResources: ResourceManifest[];
-    constructor(context: Record<string, unknown>, createInstance?: InstanceFactory, secretValues?: Set<string>);
+    private pendingResources;
+    /**
+     * Optional hook called between create() and init() for each resource.
+     * Set by the kernel to inject live instances into reference fields.
+     */
+    preInitHook?: PreInitHook;
+    constructor(source: string, context: Record<string, unknown>, createInstance: InstanceFactory | undefined, secretValues: Set<string>, emit: EmitEvent);
     get createInstance(): InstanceFactory;
+    /** Called after init() when a resource snapshot is available. Overridden by ModuleContext. */
+    protected onResourceSnapshotted(_name: string, _snap: Record<string, unknown>): void;
     get context(): Record<string, unknown>;
     get secretValues(): Set<string>;
+    /**
+     * Reorder pending resources to match the given name sequence (topo order from Phase 4).
+     * Resources not present in `names` are left at the end in their original order.
+     * Call before initializeResources() so the create/init sub-phases run in dependency order,
+     * guaranteeing that Phase 5 injection always finds initialized dependencies.
+     */
+    setInitOrder(names: string[]): void;
     /**
      * Queue a resource manifest for initialization on this context.
      */
+    hasManifest(name: string): boolean;
     registerManifest(resource: ResourceManifest): void;
     /**
      * Attach a child context to this node. The child's parent is set to this
      * context and the child is registered under the given name.
      */
-    spawnChild<T extends EvaluationContext>(child: T): T;
+    spawnChild<T extends IEvaluationContext>(child: T): T;
     /**
-     * Multi-pass initialization loop. Processes pendingResources by calling the
-     * supplied instantiator for each resource, retrying failures across up to 10
-     * passes (handles dependency ordering without explicit topological sort).
+     * Interleaved create/init loop.
+     *
+     * Each pass has two sub-phases run back-to-back:
+     *   1. Create sub-phase: call controller.create() for each pending resource that
+     *      hasn't been created yet. Successful results go into createdInstances.
+     *   2. Init sub-phase: call instance.init(ctx) for each created-but-not-inited
+     *      resource. Successful results go into resourceInstances.
      *
-     * ERR_VISIBILITY_DENIED errors are fatal and re-thrown immediately.
+     * Interleaving is necessary because some resources' create() depends on effects
+     * produced by other resources' init() (e.g. Kernel.Import.init() runs
+     * child.initializeResources() which registers controllers needed by sibling
+     * resources' create()). Running both sub-phases each pass lets those effects
+     * propagate before the next create attempt.
+     *
+     * Each resource is created at most once and inited at most once.
+     * ERR_VISIBILITY_DENIED is fatal and re-thrown immediately.
      * All other errors are tracked and retried until no progress is made.
      */
     initializeResources(): Promise<void>;
     withManifests<T>(manifests: any[], fn: () => T): T;
+    /**
+     * Returns a ScopeHandle that initializes `manifests` in a fresh child context each time
+     * `run()` is called, executes the callback with a ScopeContext, and tears down when done.
+     *
+     * The child inherits the parent's preInitHook (if any), extended so that `getInstance`
+     * also checks the parent's already-initialized singleton instances. This lets scoped
+     * resources hold x-telo-ref slots pointing to outer resources — those deps are already
+     * live when the scope opens.
+     */
+    createScopeHandle(manifests: ResourceManifest[]): ScopeHandle;
     /**
      * Cascade teardown depth-first through the tree:
      *   1. Tear down child contexts in reverse registration order.
-     *   2. Tear down own resource instances in reverse registration order.
-     *
-     * Note: Kernel-level events (e.g. Teardown events) are NOT emitted here —
-     * they remain the Kernel's responsibility.
+     *   2. Tear down own resource instances in reverse registration order,
+     *      emitting a Teardown event for each via the injected emit callback.
      */
     teardownResources(): Promise<void>;
+    transientChild(context: Record<string, any>): EvaluationContext;
     /**
-     * Evaluate a single CEL expression string against the context.
-     * Secret values are redacted from any thrown error message.
+     * Invoke a resource by kind and name within this context's resourceInstances.
+     * Emits a scoped Invoked event via the injected emit callback after invocation.
      */
-    evaluate(expression: string): unknown;
+    invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any>;
+    run(name: string): Promise<void>;
     /**
-     * Expand a value that may contain ${{ }} templates.
-     * Works recursively over strings, arrays, and objects.
-     * Templates whose identifiers are not present in the context are left
-     * unchanged (deferred) — they will be resolved at execution time when a
-     * richer ExecutionContext is available. All other CEL errors are propagated.
+     * Expand a value that may contain precompiled ${{ }} templates.
+     * Works recursively over CompiledValues, arrays, and objects.
      */
     expand(value: unknown): unknown;
     /**
-     * Merge another context on top of this one.
-     * Returns a new base EvaluationContext — 'other' wins on key conflict.
+     * Expand a value using this context merged with additional properties.
+     * Equivalent to merge(extraContext).expand(value) without allocating a context object.
      */
-    merge(other: EvaluationContext | Record<string, unknown>): EvaluationContext;
-    private expandString;
+    expandWith(value: unknown, extraContext: Record<string, unknown>): unknown;
+    /**
+       * Expand specific dot-paths within an object. '**' expands the entire object.
+       * Paths listed in excludePaths are left untouched (runtime takes precedence).
+       * Always throws if an expression cannot be resolved.
+       */
+    expandPaths(value: Record<string, unknown>, paths: string[], excludePaths?: string[]): Record<string, unknown>;
 }
 //# sourceMappingURL=evaluation-context.d.ts.map

package/dist/evaluation-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluation-context.d.ts","sourceRoot":"","sources":["../src/evaluation-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOvE,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AAE/F;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,gBAAgB,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;AAE/F,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAEvD;AAYD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,SAAS,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrC,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC;IAE3C,sCAAsC;IACtC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAa;IAClD,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,EAAE,CAAM;IAE5C,oDAAoD;IACpD,KAAK,EAAE,cAAc,CAAa;IAElC,6EAA6E;IAC7E,QAAQ,CAAC,iBAAiB;kBAEZ,gBAAgB;kBAAY,gBAAgB;OACtD;IAEJ,gEAAgE;IAChE,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,CAAM;gBAGjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,cAAc,GAAE,eAAkC,EAClD,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC;IAO5B,IAAI,cAAc,IAAI,eAAe,CAEpC;IAED,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErC;IAED,IAAI,YAAY,IAAI,GAAG,CAAC,MAAM,CAAC,CAE9B;IAED;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIlD;;;OAGG;IACH,UAAU,CAAC,CAAC,SAAS,iBAAiB,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC;IAMpD;;;;;;;OAOG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD1C,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAiBlD;;;;;;;OAOG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAaxC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAUrC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAiB/B;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB;IAY5E,OAAO,CAAC,YAAY;CAkBrB"}
+{"version":3,"file":"evaluation-context.d.ts","sourceRoot":"","sources":["../src/evaluation-context.ts"],"names":[],"mappings":"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"}