@telorun/kernel 0.49.0 → 0.51.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-transport.ts

@@ -2,6 +2,7 @@ import {
   DEFAULT_MANIFEST_FILENAME,
   IntegrityError,
   sha256Base64Url,
+  splitIntegrity,
   verifyIntegrity,
   type ManifestSource,
 } from "@telorun/analyzer";
@@ -126,6 +127,21 @@ export class OciTransport implements Transport {
     return tags;
   }
 
+  refVersion(ref: string): string | null {
+    // The reference (tag or `sha256:` digest) is what `@` separates. An implicit
+    // `latest` (no `@`) is not an upgradeable pin, so return null there; a digest
+    // reference flows through raw and the caller's SemVer check skips it.
+    const { base } = splitIntegrity(ref);
+    if (!base.startsWith(OCI_SCHEME)) return null;
+    const at = base.lastIndexOf("@");
+    return at > 0 ? base.slice(at + 1) : null;
+  }
+
+  withVersion(ref: string, version: string): string {
+    const { host, repo } = parseOciRef(ref);
+    return `${OCI_SCHEME}${host}/${repo}@${version}`;
+  }
+
   async digest(ref: string): Promise<string | null> {
     const { host, repo, reference } = parseOciRef(ref);
     return new OciClient(host, repo).headManifest(reference);

package/src/transports/registry-transport.ts

@@ -173,6 +173,20 @@ export class RegistryTransport implements Transport {
     return Array.isArray(body.versions) ? body.versions : [];
   }
 
+  refVersion(ref: string): string | null {
+    // Only bare `namespace/name@version` refs carry an upgradeable version — a
+    // direct `https://` URL has no version segment to bump.
+    if (!isRegistryRef(ref)) return null;
+    const { base } = splitIntegrity(ref);
+    const at = base.lastIndexOf("@");
+    return at > 0 ? base.slice(at + 1) : null;
+  }
+
+  withVersion(ref: string, version: string): string {
+    const { modulePath } = parseModuleRef(ref);
+    return `${modulePath}@${version}`;
+  }
+
   /** Mirrors the sources' fetch-URL derivation: a direct URL points at (or
    *  contains) the YAML file; a bare registry ref folds into the registry
    *  layout. `null` when this transport does not own the ref's shape. */

package/src/transports/transport.ts

@@ -83,6 +83,23 @@ export interface Transport {
    *  by `telo upgrade`. */
   listVersions(ref: string): Promise<string[] | null>;
 
+  /** The version segment currently named in `ref` — a registry `@version`, an
+   *  OCI tag, or an OCI digest reference (`sha256:…`), returned raw (the caller
+   *  applies its own SemVer validation). Returns `null` when the ref carries no
+   *  upgradeable version at all — a bare `https://` URL, or an OCI ref with no
+   *  explicit reference. The integrity fragment is ignored. Used by `telo
+   *  upgrade` to read the current pin. Paired with {@link withVersion}, which
+   *  owns the scheme-specific reconstruction, so `upgrade` never branches on
+   *  ref shape. */
+  refVersion(ref: string): string | null;
+
+  /** `ref` rewritten to name `version`, dropping any integrity fragment (the
+   *  caller re-pins the result). Scheme-specific reconstruction — registry
+   *  `<ns>/<name>@version`, OCI `oci://host/repo@version`. Only called for refs
+   *  {@link refVersion} classified as versioned, so it may assume a parseable
+   *  ref. Used by `telo upgrade`. */
+  withVersion(ref: string, version: string): string;
+
   /** Retrieve the full artifact for `ref` — the `telo.yaml` and its `files:`
    *  payload — verifying the manifest against the inline hash and the payload
    *  against the manifest's `filesIntegrity`. Used by `telo install`; subsumes