@telorun/kernel 0.48.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 },
         );
       }
     }

package/src/transports/oci/oci-client.ts

@@ -1,3 +1,4 @@
+import { fetchOrThrow } from "@telorun/sdk";
 import { createHash } from "node:crypto";
 
 import { assertPublicEgress } from "../egress-guard.js";
@@ -109,7 +110,10 @@ export class OciClient {
     };
 
     const cached = this.tokenByScope.get(scope);
-    let res = await fetch(url, withToken(cached));
+    let res = await fetchOrThrow(url, withToken(cached), {
+      operation: "OCI registry request",
+      setting: "the oci:// ref host",
+    });
     if (res.status !== 401) return res;
 
     const challenge = res.headers.get("www-authenticate");
@@ -119,7 +123,10 @@ export class OciClient {
     this.tokenByScope.set(scope, token);
     // Drain the 401 body so the connection can be reused.
     await res.text().catch(() => {});
-    return fetch(url, withToken(token));
+    return fetchOrThrow(url, withToken(token), {
+      operation: "OCI registry request",
+      setting: "the oci:// ref host",
+    });
   }
 
   /** Exchange a bearer challenge for a token, authenticating to the token
@@ -141,7 +148,10 @@ export class OciClient {
       const basic = Buffer.from(`${cred.username}:${cred.password}`).toString("base64");
       headers.set("authorization", `Basic ${basic}`);
     }
-    const res = await fetch(tokenUrl.href, { headers });
+    const res = await fetchOrThrow(tokenUrl.href, { headers }, {
+      operation: "OCI registry auth",
+      setting: "the oci:// ref host",
+    });
     if (!res.ok) return null;
     const body = (await res.json()) as { token?: string; access_token?: string };
     return body.token ?? body.access_token ?? null;

package/src/transports/registry-transport.ts

@@ -9,6 +9,7 @@ import {
   splitIntegrity,
   type ManifestSource,
 } from "@telorun/analyzer";
+import { fetchOrThrow } from "@telorun/sdk";
 import { createHash } from "crypto";
 
 import { computeFilesIntegrity, injectFilesIntegrity } from "../bundle/files-integrity.js";
@@ -159,7 +160,11 @@ export class RegistryTransport implements Transport {
     const { modulePath } = parseModuleRef(ref);
     const url = `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}`;
     await assertPublicEgress(url);
-    const res = await fetch(url, { headers: { accept: "application/json" } });
+    const res = await fetchOrThrow(
+      url,
+      { headers: { accept: "application/json" } },
+      { operation: "Registry version list", setting: "--registry / TELO_REGISTRY" },
+    );
     if (res.status === 404) return null;
     if (!res.ok) {
       throw new Error(`Registry returned ${res.status} ${res.statusText} for ${modulePath}`);
@@ -189,7 +194,10 @@ export class RegistryTransport implements Transport {
     const fetchUrl = this.manifestUrl(ref);
     if (!fetchUrl) return null;
     await assertPublicEgress(fetchUrl);
-    const res = await fetch(fetchUrl);
+    const res = await fetchOrThrow(fetchUrl, undefined, {
+      operation: "Registry manifest read",
+      setting: "--registry / TELO_REGISTRY",
+    });
     if (res.status === 404) return null;
     if (!res.ok) {
       throw new Error(`Registry returned ${res.status} ${res.statusText} for ${fetchUrl}`);
@@ -206,7 +214,10 @@ export class RegistryTransport implements Transport {
       throw new Error(`cannot hash non-remote import '${ref}'`);
     }
     await assertPublicEgress(fetchUrl);
-    const res = await fetch(fetchUrl);
+    const res = await fetchOrThrow(fetchUrl, undefined, {
+      operation: "Registry manifest hash",
+      setting: "--registry / TELO_REGISTRY",
+    });
     if (!res.ok) {
       throw new Error(`fetch ${fetchUrl}: ${res.status} ${res.statusText}`);
     }
@@ -223,7 +234,10 @@ export class RegistryTransport implements Transport {
     // The payload rides beside the manifest as `module.tar.gz`.
     const tarUrl = source.replace(/\/telo\.yaml$/, "/module.tar.gz");
     await assertPublicEgress(tarUrl);
-    const res = await fetch(tarUrl);
+    const res = await fetchOrThrow(tarUrl, undefined, {
+      operation: "Module payload download",
+      setting: "--registry / TELO_REGISTRY",
+    });
     if (!res.ok) {
       throw new Error(`could not fetch bundle ${tarUrl}: ${res.status} ${res.statusText}`);
     }
@@ -285,7 +299,11 @@ export class RegistryTransport implements Transport {
     for (let attempt = 1; attempt <= MAX_PUSH_ATTEMPTS; attempt++) {
       networkErr = null;
       try {
-        res = await fetch(url, { method: "PUT", headers, body });
+        res = await fetchOrThrow(
+          url,
+          { method: "PUT", headers, body },
+          { operation: "Registry publish", setting: "--registry / TELO_REGISTRY" },
+        );
       } catch (err) {
         networkErr = err;
         res = null;