@telorun/kernel 0.26.1 → 0.27.0

package/dist/schema-compiled-values.d.ts

@@ -0,0 +1,7 @@
+/** Replaces CompiledValue wrappers with schema-appropriate placeholders for schema validation.
+ *  Template strings were compiled from YAML at load time; this restores a shape
+ *  that AJV can validate without evaluating expressions. When no schema is
+ *  supplied every compiled value collapses to `""` (the `default` branch of
+ *  `placeholderForSchema`), matching the schema-unaware strip. */
+export declare function stripCompiledValues(v: unknown, schema?: Record<string, unknown>, rootSchema?: Record<string, unknown>): unknown;
+//# sourceMappingURL=schema-compiled-values.d.ts.map

package/dist/schema-compiled-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-compiled-values.d.ts","sourceRoot":"","sources":["../src/schema-compiled-values.ts"],"names":[],"mappings":"AAyDA;;;;kEAIkE;AAClE,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,OAAO,EACV,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,OAAO,CAkBT"}

package/dist/schema-compiled-values.js

@@ -0,0 +1,72 @@
+import { isCompiledValue } from "@telorun/sdk";
+/** Returns a schema-appropriate placeholder value for a CompiledValue field. */
+function placeholderForSchema(schema) {
+    if (schema.default !== undefined)
+        return schema.default;
+    switch (schema.type) {
+        case "integer":
+        case "number":
+            return schema.minimum ?? 0;
+        case "boolean":
+            return false;
+        case "array":
+            return [];
+        case "object":
+            return {};
+        default:
+            return "";
+    }
+}
+/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
+function resolveSchemaRef(schema, root) {
+    if (schema.$ref &&
+        typeof schema.$ref === "string" &&
+        schema.$ref.startsWith("#/$defs/")) {
+        const defName = schema.$ref.slice("#/$defs/".length);
+        const defs = root.$defs;
+        const resolved = defs?.[defName];
+        if (resolved)
+            return resolved;
+    }
+    return schema;
+}
+/** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
+function collectSchemaProperties(schema) {
+    const props = {
+        ...(schema.properties ?? {}),
+    };
+    for (const sub of (schema.oneOf ?? schema.anyOf ?? [])) {
+        if (sub && typeof sub === "object" && sub.properties) {
+            for (const [k, v] of Object.entries(sub.properties)) {
+                if (!(k in props))
+                    props[k] = v;
+            }
+        }
+    }
+    return props;
+}
+/** Replaces CompiledValue wrappers with schema-appropriate placeholders for schema validation.
+ *  Template strings were compiled from YAML at load time; this restores a shape
+ *  that AJV can validate without evaluating expressions. When no schema is
+ *  supplied every compiled value collapses to `""` (the `default` branch of
+ *  `placeholderForSchema`), matching the schema-unaware strip. */
+export function stripCompiledValues(v, schema = {}, rootSchema) {
+    const root = rootSchema ?? schema;
+    const resolved = resolveSchemaRef(schema, root);
+    if (isCompiledValue(v))
+        return placeholderForSchema(resolved);
+    if (Array.isArray(v)) {
+        const itemSchema = resolveSchemaRef((resolved.items ?? {}), root);
+        return v.map((item) => stripCompiledValues(item, itemSchema, root));
+    }
+    if (v !== null && typeof v === "object") {
+        const props = collectSchemaProperties(resolved);
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            out[k] = stripCompiledValues(val, props[k] ?? {}, root);
+        }
+        return out;
+    }
+    return v;
+}
+//# sourceMappingURL=schema-compiled-values.js.map

package/dist/schema-compiled-values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-compiled-values.js","sourceRoot":"","sources":["../src/schema-compiled-values.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",

package/src/cel-handlers.ts

@@ -0,0 +1,24 @@
+import { createHash, createHmac } from "node:crypto";
+
+/** Node implementations of the host-injected CEL functions (`crypto` / `Buffer`).
+ *  The kernel wires these into the analyzer + loader; the CLI reuses them for
+ *  `telo cel eval` so its results match a real run. */
+export const nodeCelHandlers = {
+  sha256: (s: string) => createHash("sha256").update(s).digest("hex"),
+  md5: (s: string) => createHash("md5").update(s).digest("hex"),
+  sha1: (s: string) => createHash("sha1").update(s).digest("hex"),
+  sha512: (s: string) => createHash("sha512").update(s).digest("hex"),
+  hmac: (algorithm: string, key: string, message: string) =>
+    createHmac(algorithm, key).update(message).digest("hex"),
+  base64Encode: (s: string) => Buffer.from(s, "utf8").toString("base64"),
+  base64Decode: (s: string) => Buffer.from(s, "base64").toString("utf8"),
+  // cel-js represents int / uint as BigInt — JSON.stringify throws on BigInts,
+  // so coerce them down to Number unconditionally. CEL int is i64 and JS Number
+  // is f64, so values outside ±2^53 lose precision; that's accepted behaviour
+  // for Telo manifests, which never carry > 2^53 integer values in practice.
+  // JSON.stringify returns undefined for top-level undefined / function / symbol
+  // — the CEL signature is `json(dyn): string`, so coerce that to "null" rather
+  // than break the contract. (CEL `null` already serializes to "null".)
+  json: (value: unknown) =>
+    JSON.stringify(value, (_k, v) => (typeof v === "bigint" ? Number(v) : v)) ?? "null",
+};

package/src/dependency-injection.ts

@@ -0,0 +1,96 @@
+import { ResourceInstance, ResourceManifest, RuntimeError } from "@telorun/sdk";
+
+/**
+ * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal,
+ * `{}` = map traversal). For each leaf value that looks like a {kind, name}
+ * reference, calls getInstance(name) and replaces the value in-place with the
+ * returned live ResourceInstance. Values where getInstance returns undefined are
+ * left unchanged.
+ */
+export function injectAtPath(
+  resource: ResourceManifest,
+  fieldPath: string,
+  getInstance: (name: string, alias?: string) => ResourceInstance | undefined,
+): void {
+  const parts = fieldPath.split(".");
+
+  // Resolve a {kind, name, alias?} reference to its live instance. A non-`Self` alias is a
+  // cross-module reference into an import's published exports; if that import hasn't
+  // finished init() yet the instance is absent, so we throw to defer this resource to a
+  // later pass of the multi-pass init loop (which catches and retries) rather than leaving
+  // the ref unresolved. Local refs (no alias) that miss are left for topo ordering / later
+  // diagnostics, matching prior behaviour.
+  function resolveInto(ref: Record<string, unknown>): ResourceInstance | undefined {
+    const alias = typeof ref.alias === "string" ? ref.alias : undefined;
+    const instance = getInstance(ref.name as string, alias);
+    if (!instance && alias && alias !== "Self") {
+      throw new RuntimeError(
+        "ERR_CROSS_MODULE_REF_PENDING",
+        `Cross-module reference '${alias}.${String(ref.name)}' is not available yet (import not initialized)`,
+      );
+    }
+    return instance;
+  }
+
+  function traverse(obj: unknown, partsLeft: string[]): void {
+    if (!obj || typeof obj !== "object" || partsLeft.length === 0) return;
+    const [head, ...rest] = partsLeft;
+
+    // Map iteration: descend into every value of the current object (used for
+    // schema fields with `additionalProperties` like `content[mime]`).
+    if (head === "{}") {
+      const container = obj as Record<string, unknown>;
+      for (const mapKey of Object.keys(container)) {
+        const elem = container[mapKey];
+        if (!elem || typeof elem !== "object") continue;
+        if (rest.length === 0) {
+          const ref = elem as Record<string, unknown>;
+          if (typeof ref.kind === "string" && typeof ref.name === "string") {
+            const instance = resolveInto(ref);
+            if (instance) container[mapKey] = instance;
+          }
+        } else {
+          traverse(elem, rest);
+        }
+      }
+      return;
+    }
+
+    const isArr = head.endsWith("[]");
+    const key = isArr ? head.slice(0, -2) : head;
+    const container = obj as Record<string, unknown>;
+    const val = container[key];
+    if (val == null) return;
+
+    if (isArr) {
+      if (!Array.isArray(val)) return;
+      for (let i = 0; i < val.length; i++) {
+        const elem = val[i];
+        if (!elem || typeof elem !== "object") continue;
+        if (rest.length === 0) {
+          const ref = elem as Record<string, unknown>;
+          if (typeof ref.kind === "string" && typeof ref.name === "string") {
+            const instance = resolveInto(ref);
+            if (instance) val[i] = instance;
+          }
+        } else {
+          traverse(elem, rest);
+        }
+      }
+    } else {
+      if (rest.length === 0) {
+        if (val && typeof val === "object" && !Array.isArray(val)) {
+          const ref = val as Record<string, unknown>;
+          if (typeof ref.kind === "string" && typeof ref.name === "string") {
+            const instance = resolveInto(ref);
+            if (instance) container[key] = instance;
+          }
+        }
+      } else {
+        traverse(val, rest);
+      }
+    }
+  }
+
+  traverse(resource, parts);
+}

package/src/eval-paths.ts

@@ -0,0 +1,44 @@
+/**
+ * Traverses a definition schema and collects all paths annotated with `x-telo-eval`.
+ * Root-level `x-telo-eval` produces the `"**"` wildcard (expand all fields).
+ * Property-level annotations produce the dot-notation path to that property.
+ */
+export function buildEvalPaths(schema: Record<string, any>): {
+  compile: string[];
+  runtime: string[];
+} {
+  const compile: string[] = [];
+  const runtime: string[] = [];
+
+  if (schema["x-telo-eval"] === "compile") compile.push("**");
+  else if (schema["x-telo-eval"] === "runtime") runtime.push("**");
+
+  if (schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties as Record<string, any>)) {
+      collectEvalPathsNode(propSchema, key, compile, runtime);
+    }
+  }
+
+  return { compile, runtime };
+}
+
+function collectEvalPathsNode(
+  node: Record<string, any>,
+  path: string,
+  compile: string[],
+  runtime: string[],
+): void {
+  if (node["x-telo-eval"] === "compile") {
+    compile.push(path);
+    return;
+  }
+  if (node["x-telo-eval"] === "runtime") {
+    runtime.push(path);
+    return;
+  }
+  if (node.properties) {
+    for (const [key, propSchema] of Object.entries(node.properties as Record<string, any>)) {
+      collectEvalPathsNode(propSchema, `${path}.${key}`, compile, runtime);
+    }
+  }
+}

package/src/evaluation-context.ts

@@ -22,6 +22,53 @@ import { RuntimeError } from "@telorun/sdk";
 
 export { resourceKey };
 
+/** An edge in the resource dependency graph: a resolved `!ref` target. */
+type ResourceRef = { kind: string; name: string; alias?: string };
+
+/** A pure resolved reference is a `{ kind, name, alias? }` object and nothing
+ *  else — the shape `resolveRefSentinels` produces (Phase 2.5). An inline
+ *  definition (`{ kind, ...config }`) carries extra keys and is its own node, so
+ *  it is not an edge here; a live `ResourceInstance` (injected at Phase 5) has
+ *  methods, never this exact key set. */
+function isResolvedRef(value: unknown): value is ResourceRef {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.kind !== "string" || typeof v.name !== "string") return false;
+  return Object.keys(v).every((k) => k === "kind" || k === "name" || k === "alias");
+}
+
+/**
+ * Walk a resource manifest's config and collect every resolved `{kind, name,
+ * alias?}` reference it points at — the outbound edges for the dependency graph.
+ * Called at create time, before Phase-5 injection swaps refs for live instances,
+ * so the targets are still inspectable plain objects (and there are no instance
+ * cycles to guard against). `metadata` is skipped (it holds the resource's own
+ * identity, never refs); ref leaves are not descended into. Deduped by alias+name.
+ */
+function collectResourceRefs(resource: ResourceManifest): ResourceRef[] {
+  const found = new Map<string, ResourceRef>();
+  const visit = (value: unknown): void => {
+    if (isResolvedRef(value)) {
+      const key = `${value.alias ?? ""}::${value.name}`;
+      if (!found.has(key)) found.set(key, { kind: value.kind, name: value.name, ...(value.alias ? { alias: value.alias } : {}) });
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+    } else if (value && typeof value === "object") {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        if (k === "metadata") continue;
+        visit(v);
+      }
+    }
+  };
+  for (const [k, v] of Object.entries(resource as Record<string, unknown>)) {
+    if (k === "kind" || k === "metadata") continue;
+    visit(v);
+  }
+  return [...found.values()];
+}
+
 /**
  * Kernel-internal propagation of the current invocation tree's cancellation
  * scope. NEVER the controller-facing contract — controllers always receive the
@@ -270,6 +317,14 @@ export class EvaluationContext implements IEvaluationContext {
             if (idx >= 0) this.pendingResources.splice(idx, 1);
             errors.delete(name);
             progress = true;
+            await this.emit(`${created.resource.kind}.${created.resource.metadata.name}.Created`, {
+              resource: {
+                kind: created.resource.kind,
+                name: created.resource.metadata.name,
+                module: created.resource.metadata.module,
+              },
+              dependencies: collectResourceRefs(created.resource),
+            });
           }
         } catch (error) {
           if (error instanceof RuntimeError && (error.code === "ERR_VISIBILITY_DENIED" || error.code === "ERR_FATAL")) throw error;
@@ -297,6 +352,9 @@ export class EvaluationContext implements IEvaluationContext {
           this.createdInstances.delete(name);
           errors.delete(name);
           progress = true;
+          await this.emit(`${resource.kind}.${resource.metadata.name}.Initialized`, {
+            resource: { kind: resource.kind, name: resource.metadata.name },
+          });
         } catch (error) {
           if (error instanceof RuntimeError && (error.code === "ERR_VISIBILITY_DENIED" || error.code === "ERR_FATAL")) throw error;
           errors.set(name, formatErrorForDiagnostic(error));

package/src/index.ts

@@ -10,9 +10,9 @@ export {
   writeManifestCache,
 } from "./manifest-sources/local-manifest-cache-source.js";
 export { MemorySource } from "./manifest-sources/memory-source.js";
-export { EventStream } from "./event-stream.js";
 export { ExecutionContext } from "./execution-context.js";
-export { Kernel, type KernelOptions, nodeCelHandlers } from "./kernel.js";
+export { Kernel, type KernelOptions } from "./kernel.js";
+export { nodeCelHandlers } from "./cel-handlers.js";
 export { ModuleContext } from "./module-context.js";
 export { ManifestRegistry as Registry } from "./registry.js";
 export { ResourceURI } from "./resource-uri.js";

package/src/invoke-dispatch.ts

@@ -0,0 +1,43 @@
+import {
+  createCancellationSource,
+  RuntimeError,
+  type CancellationSource,
+  type InvokeOptions,
+} from "@telorun/sdk";
+
+/** Translate embedder `InvokeOptions` (external signal / absolute deadline)
+ *  into a seeded cancellation source, or `undefined` when nothing was requested
+ *  so the dispatch path stays on its allocation-free sentinel. The caller
+ *  disposes the returned source once the invoke settles. */
+export function seedInvokeSource(opts?: InvokeOptions): CancellationSource | undefined {
+  if (!opts?.signal && opts?.deadlineAt === undefined) return undefined;
+  const source = createCancellationSource();
+  if (opts.deadlineAt !== undefined) source.cancelAt(opts.deadlineAt);
+  const signal = opts.signal;
+  if (signal && !signal.aborted) {
+    const onAbort = () => source.cancel(String(signal.reason ?? "aborted"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    // Detach from the (possibly long-lived) external signal on dispose so the
+    // listener — which captures the source — doesn't pin it until the signal
+    // eventually aborts (or forever if it never does).
+    const baseDispose = source.dispose.bind(source);
+    source.dispose = () => {
+      signal.removeEventListener("abort", onAbort);
+      baseDispose();
+    };
+  } else if (signal?.aborted) {
+    source.cancel(String(signal.reason ?? "aborted"));
+  }
+  return source;
+}
+
+export function parseRef(ref: string): { kind: string; name: string } {
+  const lastDot = ref.lastIndexOf(".");
+  if (lastDot <= 0 || lastDot === ref.length - 1) {
+    throw new RuntimeError(
+      "ERR_INVALID_VALUE",
+      `Invalid resource reference '${ref}': expected '<Kind>.<Name>' (e.g. 'Http.Server.Main') or pass { kind, name } directly.`,
+    );
+  }
+  return { kind: ref.slice(0, lastDot), name: ref.slice(lastDot + 1) };
+}