@telorun/kernel 0.49.0 → 0.50.0

package/src/module-context.ts

@@ -1,4 +1,5 @@
 import { executeInvokeStep, getRefIdentity, RuntimeError } from "@telorun/sdk";
+import type { ScopeConfig } from "./logging/scope-config.js";
 import type {
   BootTarget,
   ControllerPolicy,
@@ -128,6 +129,20 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
    */
   private _controllerPolicy: ControllerPolicy | undefined;
 
+  /**
+   * The effective logging configuration for this module context — threshold,
+   * redaction, sampling, and the dotted import-alias path that identifies it.
+   *
+   * Stamped by the parent `Telo.Import` controller, which merges the import's
+   * own `logging:` block over its parent's *once*, when the import graph is
+   * built. Resolution therefore happens at load and the result is a plain value:
+   * there is no per-record lookup and no walk up the import chain at emit time,
+   * and it is the same scalar a guest runtime caches across an FFI boundary, so
+   * scoping and the FFI threshold cache are one mechanism rather than two.
+   * See kernel/specs/logging.md §12.2 and §9.
+   */
+  private _loggingConfig: ScopeConfig | undefined;
+
   constructor(
     source: string,
     variables: Record<string, unknown> = {},
@@ -192,6 +207,14 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     return this._controllerPolicy;
   }
 
+  setLoggingConfig(config: ScopeConfig | undefined): void {
+    this._loggingConfig = config;
+  }
+
+  getLoggingConfig(): ScopeConfig | undefined {
+    return this._loggingConfig;
+  }
+
   protected override onResourceSnapshotted(name: string, snap: Record<string, unknown>): void {
     this.setResource(name, snap);
   }

package/src/resource-context.ts

@@ -12,6 +12,7 @@ import {
   type InvokeContext,
   type LoadOptions,
   type ModuleContext,
+  type Logger,
   type OpenSpan,
   type OpenSpanOptions,
   type ParsedArgs,
@@ -19,6 +20,14 @@ import {
 } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
 import { hostEnv } from "./host-env.js";
+import type { LoggingHost } from "./logging/logging-host.js";
+import type { ScopeConfig } from "./logging/scope-config.js";
+
+/** The kernel's `ModuleContext` as far as logging is concerned. Declared
+ *  structurally rather than imported to avoid a module cycle. */
+interface KernelModuleContext {
+  getLoggingConfig?(): ScopeConfig | undefined;
+}
 import { stripCompiledValues } from "./schema-compiled-values.js";
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
@@ -44,6 +53,45 @@ export class ResourceContextImpl implements ResourceContext {
    *  and stamps the owner on the child context it registers them into. */
   readonly ownerPrefix: string;
 
+  /** Built lazily: most resources never log, and constructing the scoped logger
+   *  eagerly for every context would allocate per resource for nothing. */
+  #log: Logger | undefined;
+
+  /**
+   * The resource's structured logger, stamped with its identity, module, and
+   * import-alias scope so a record identifies *which instance* emitted it — the
+   * distinction `module` alone cannot make when the same library is imported
+   * twice (§7.3).
+   */
+  get log(): Logger {
+    if (!this.#log) {
+      const kind = this.metadata?.kind as string | undefined;
+      const name = this.metadata?.metadata?.name as string | undefined;
+      const resource =
+        kind && name
+          ? { kind, name, id: `${this.ownerPrefix}${kind}.${name}` }
+          : undefined;
+      // The runtime value is always the kernel's `ModuleContext`, which carries
+      // the resolved per-scope config; the field is typed as the SDK's narrower
+      // interface, which deliberately does not expose kernel-internal state.
+      const scope = (
+        this.moduleContext as unknown as KernelModuleContext
+      ).getLoggingConfig?.();
+      this.#log = this.kernel.logging.createLogger(scope, resource);
+    }
+    return this.#log;
+  }
+
+  /** The sink-facing half of the pipeline. Only the built-in sink controllers
+   *  reach for it; every other controller uses {@link log}. */
+  get logging(): LoggingHost {
+    return this.kernel.logging.host;
+  }
+
+  kernelLoggingRootScope(): ScopeConfig {
+    return this.kernel.logging.rootScope;
+  }
+
   constructor(
     readonly kernel: Kernel,
     readonly moduleContext: ModuleContext,

package/src/schema-compiled-values.ts

@@ -3,6 +3,12 @@ import { isCompiledValue } from "@telorun/sdk";
 /** Returns a schema-appropriate placeholder value for a CompiledValue field. */
 function placeholderForSchema(schema: Record<string, unknown>): unknown {
   if (schema.default !== undefined) return schema.default;
+  // An enum-constrained field needs a placeholder drawn from the enum: the
+  // type-based fallbacks below satisfy `type` but violate `enum`, so any CEL
+  // expression feeding an enum field would fail validation against a value the
+  // author never wrote. Mirrors `celPlaceholderForSchema` in the analyzer, which
+  // performs the same substitution for the static half.
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
   switch (schema.type) {
     case "integer":
     case "number":

package/src/schema-validator.ts

@@ -1,5 +1,5 @@
 import { evaluate } from "@marcbachmann/cel-js";
-import { DataValidator, isCompiledValue, RuntimeError, TypeRule } from "@telorun/sdk";
+import { DataValidator, isCompiledValue, NOOP_LOGGER, RuntimeError, TypeRule, type Logger } from "@telorun/sdk";
 import AjvModule, { type ValidateFunction } from "ajv";
 import standaloneCodeMod from "ajv/dist/standalone/index.js";
 import addFormats from "ajv-formats";
@@ -148,6 +148,16 @@ export class SchemaValidator {
    *  process — `compiledValidators` is keyed by object identity and would
    *  miss those cases. */
   private hashCache = new Map<string, DataValidator>();
+  /** Where cache-failure diagnostics go. Injected rather than reached for
+   *  globally: this class is constructed outside the kernel's stdio scope, and
+   *  §13.1 forbids the kernel writing to `process.stderr` directly. Defaults to
+   *  a no-op so a standalone construction (tests, tooling) stays silent. */
+  private log: Logger = NOOP_LOGGER;
+
+  /** Route cache diagnostics through the kernel's logger. */
+  setLogger(log: Logger): void {
+    this.log = log;
+  }
 
   constructor() {
     this.ajv = new Ajv({
@@ -172,6 +182,7 @@ export class SchemaValidator {
       "x-telo-step-context",
       "x-telo-widget",
       "x-telo-type",
+      "x-telo-inline",
     ]) {
       this.ajv.addKeyword(kw);
     }
@@ -342,8 +353,10 @@ export class SchemaValidator {
         // stale file with a fresh hash header.
       } catch (err) {
         if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
-          process.stderr.write(
-            `[telo:kernel] validator cache load failed (${hash}): ${err instanceof Error ? err.message : String(err)}\n`,
+          this.log.warn(
+            "validator cache load failed",
+            { "telo.validator.hash": hash },
+            { error: err },
           );
         }
       }
@@ -358,8 +371,10 @@ export class SchemaValidator {
         fs.mkdirSync(cacheDir, { recursive: true });
         fs.writeFileSync(path.join(cacheDir, `${hash}.cjs`), payload, "utf-8");
       } catch (err) {
-        process.stderr.write(
-          `[telo:kernel] validator cache write failed (${hash}): ${err instanceof Error ? err.message : String(err)}\n`,
+        this.log.warn(
+          "validator cache write failed",
+          { "telo.validator.hash": hash },
+          { error: err },
         );
       }
     }