@telorun/kernel 0.69.0 → 0.72.0

package/src/resolve-include-sentinels.ts

@@ -0,0 +1,219 @@
+import { readFile, stat } from "fs/promises";
+import { fileURLToPath } from "url";
+import { RuntimeError, type ResourceManifest } from "@telorun/sdk";
+import {
+  INCLUDE_BYTES_ENGINE,
+  isIncludeSentinel,
+  isTaggedSentinel,
+  normalizeIncludePath,
+  type TaggedSentinel,
+} from "@telorun/templating";
+import { resolveModuleFileUri, type ModuleArtifactLookup } from "./module-file-resolution.js";
+
+/**
+ * Ceiling on one embedded file.
+ *
+ * A resolved embed is an ordinary manifest value, retained for as long as the
+ * resource holding it, so there is no point at which a large one is released.
+ * Streaming a payload is a different primitive with a different lifetime, which
+ * is what the error points at.
+ */
+export const MAX_INCLUDE_BYTES = 32 * 1024 * 1024;
+
+/** Reads keyed by resolved URI. Two resources embedding the same font read it
+ *  once — the values are retained by those resources anyway, so the cache adds
+ *  deduplication rather than retention. */
+export type IncludeCache = Map<string, Uint8Array>;
+
+/** Manifest objects already walked. Keyed by identity and weakly held, so this
+ *  is a gate on repeated work rather than a lifetime extension. */
+const resolved = new WeakSet<object>();
+
+async function readIncluded(
+  uri: string,
+  displayPath: string,
+  cache: IncludeCache,
+): Promise<Uint8Array> {
+  const cached = cache.get(uri);
+  if (cached) return cached;
+
+  if (!uri.startsWith("file:")) {
+    throw new RuntimeError(
+      "ERR_INCLUDE_UNREADABLE",
+      `Cannot embed '${displayPath}': it resolved to '${uri}', which this runtime cannot read ` +
+        `as a file. An embedded file must ship inside the module's own artifact.`,
+    );
+  }
+  const filePath = fileURLToPath(uri);
+
+  // Size is checked before reading, so an oversized file is reported rather
+  // than loaded to discover it was too big.
+  let size: number;
+  try {
+    const info = await stat(filePath);
+    if (!info.isFile()) {
+      throw new RuntimeError(
+        "ERR_INCLUDE_UNREADABLE",
+        `Cannot embed '${displayPath}': '${filePath}' is not a file.`,
+      );
+    }
+    size = info.size;
+  } catch (error) {
+    if (error instanceof RuntimeError) throw error;
+    throw new RuntimeError(
+      "ERR_INCLUDE_FILE_NOT_FOUND",
+      `Cannot embed '${displayPath}': no such file at '${filePath}'. The path is relative to ` +
+        `the module root — the directory holding telo.yaml — not to the file the tag was ` +
+        `written in.`,
+    );
+  }
+  if (size > MAX_INCLUDE_BYTES) {
+    // Megabytes, not raw bytes: the limit is a round number chosen for a human,
+    // and this message is aimed at one.
+    const mb = (n: number) => `${Math.round((n / (1024 * 1024)) * 10) / 10} MB`;
+    throw new RuntimeError(
+      "ERR_INCLUDE_FILE_TOO_LARGE",
+      `Cannot embed '${displayPath}': it is ${mb(size)}, over the ${mb(MAX_INCLUDE_BYTES)} ` +
+        `limit for a file embedded into a manifest value. Read it at runtime with Fs.File ` +
+        `instead, which does not retain it for the life of the resource.`,
+    );
+  }
+
+  const bytes = new Uint8Array(await readFile(filePath));
+  cache.set(uri, bytes);
+  return bytes;
+}
+
+async function resolveSentinel(
+  sentinel: TaggedSentinel,
+  moduleSource: string,
+  lookup: ModuleArtifactLookup,
+  cache: IncludeCache,
+): Promise<string | Uint8Array> {
+  // Re-checked here rather than trusted from `telo check`: the kernel does not
+  // require that check to have run, and confinement is the one property whose
+  // absence is a security question rather than a broken build.
+  const { path: relative, diagnostic } = normalizeIncludePath(sentinel.source);
+  if (!relative) {
+    throw new RuntimeError(
+      "ERR_INCLUDE_PATH_INVALID",
+      `Invalid \`!${sentinel.engine}\` path: ${diagnostic?.message ?? "not a module-relative path."}`,
+    );
+  }
+
+  const uri = await resolveModuleFileUri(relative, moduleSource, lookup);
+  const bytes = await readIncluded(uri, relative, cache);
+  if (sentinel.engine === INCLUDE_BYTES_ENGINE) return bytes;
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+
+/**
+ * Replace every `!include-text` / `!include-bytes` sentinel in a resource's
+ * config with the file's contents, in place.
+ *
+ * Called at resource creation — the kernel's single instance-production site —
+ * and NOT during manifest load. The artifact spec gives `telo.yaml` a layer of
+ * its own precisely so that reading a manifest cannot pull the whole artifact;
+ * resolving at load would defeat that just as thoroughly, because loading an app
+ * loads every imported library's manifest and would fetch every library's assets
+ * layer whether or not anything used it. Resolving here bounds the cost to
+ * modules whose resources actually instantiate, and a `with:`-scoped resource
+ * pays only when its scope runs.
+ *
+ * It runs BEFORE the resource's schema validation, so a resolved value is what
+ * the schema sees: bytes reach an `x-telo-binary` slot as the `Uint8Array` that
+ * annotation demands, and an unresolved marker never reaches a controller.
+ *
+ * In place, like `resolveRefSentinels` — which also makes it idempotent, so a
+ * scoped resource created once per scope run reads its files once.
+ */
+export async function resolveIncludeSentinels(
+  resource: ResourceManifest,
+  moduleSource: string,
+  lookup: ModuleArtifactLookup,
+  cache: IncludeCache,
+): Promise<void> {
+  // A resource that defers across init passes reaches `create()` more than once,
+  // and a `with:`-scoped one is created per scope run — the walk is idempotent
+  // either way, so repeating it is pure cost on the init loop. One walk per
+  // manifest object is enough: resolution rewrites it in place.
+  if (resolved.has(resource)) return;
+
+  const pending: Array<Promise<void>> = [];
+
+  /** A nested resource DECLARATION — an inline `{ kind, … }`, whether it sits in
+   *  a `with:` scope or in a step's `invoke:`. Its embeds belong to it, not to
+   *  the resource that encloses it, and it reaches `create()` in its own right.
+   *  Phase-5 injection draws the same line for `!ref`s inside a scope. */
+  const isNestedDeclaration = (value: unknown): boolean =>
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof (value as { kind?: unknown }).kind === "string";
+
+  const take = (item: unknown, assign: (resolved: string | Uint8Array) => void): void => {
+    if (isIncludeSentinel(item)) {
+      pending.push(resolveSentinel(item, moduleSource, lookup, cache).then(assign));
+      return;
+    }
+    // Another engine's sentinel is opaque; a nested declaration is resolved when
+    // that resource is created, which is what keeps a scoped resource's files
+    // unread until its scope actually runs.
+    if (!isTaggedSentinel(item) && !isNestedDeclaration(item)) walk(item);
+  };
+
+  const walk = (value: unknown): void => {
+    if (value === null || typeof value !== "object") return;
+    // A compiled CEL node is opaque and carries no sentinels of its own.
+    if ((value as { __compiled?: unknown }).__compiled) return;
+    // Only PLAIN containers are descended into. A template kind expands
+    // `${{ self.connection }}` to a LIVE ResourceInstance, whose object graph
+    // reaches back into contexts and the kernel and contains cycles — walking it
+    // overflows the stack, and nothing in it could be a manifest value anyway.
+    // Same rule `compileWalker` and `precompileDoc` follow.
+    if (!Array.isArray(value)) {
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) return;
+    }
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        const index = i;
+        take(value[index], (resolved) => {
+          value[index] = resolved;
+        });
+      }
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    for (const key of Object.keys(obj)) {
+      take(obj[key], (resolved) => {
+        obj[key] = resolved;
+      });
+    }
+  };
+
+  // The resource being created is itself a `{ kind, … }` declaration, so the walk
+  // starts INSIDE it rather than at it — only the ones nested below are deferred.
+  walk(resource as Record<string, unknown>);
+  // Reads run concurrently and every failure surfaces: one unreadable file must
+  // not be hidden by another failing first.
+  const settled = await Promise.allSettled(pending);
+  const failures = settled.flatMap((r) => (r.status === "rejected" ? [r.reason] : []));
+  resolved.add(resource);
+  if (failures.length === 0) return;
+  // The FIRST failure is rethrown, carrying its own code and its own cause.
+  // Wrapping several into one generic error made the reported code depend on how
+  // many files happened to fail — two missing files became ERR_INCLUDE_UNREADABLE
+  // rather than ERR_INCLUDE_FILE_NOT_FOUND — so a caller matching on the code was
+  // misled by an artefact of the batch, and the individual errors were flattened
+  // into a string nothing could branch on. The rest are attached as `causes`, and
+  // named in the message so none is hidden.
+  const [first, ...rest] = failures as Error[];
+  if (rest.length > 0 && first instanceof RuntimeError) {
+    (first as RuntimeError & { causes?: unknown[] }).causes = rest;
+    first.message += ` (${rest.length} more embed${rest.length === 1 ? "" : "s"} also failed: ${rest
+      .map((f) => f.message)
+      .join("; ")})`;
+  }
+  throw first;
+}

package/src/resource-context.ts

@@ -33,7 +33,9 @@ import { isRefSentinel } from "@telorun/templating";
 import { ZoneContext } from "./zone-context.js";
 import * as path from "path";
 import { pathToFileURL } from "url";
+import { withBigIntsAsNumbers } from "./bigint-schema-view.js";
 import type { ModuleArtifact } from "./bundle/module-artifact.js";
+import { resolveModuleFileUri } from "./module-file-resolution.js";
 import { hostEnv } from "./host-env.js";
 import type { LoggingHost } from "./logging/logging-host.js";
 import type { ScopeConfig } from "./logging/scope-config.js";
@@ -74,6 +76,12 @@ export class ResourceContextImpl implements ResourceContext {
    *  eagerly for every context would allocate per resource for nothing. */
   #log: Logger | undefined;
 
+  /** The resolved kind. It cannot come from `metadata`, which is the resource's
+   *  metadata BLOCK — `kind` is its sibling, not its member, so reading
+   *  `metadata.kind` yielded `undefined` and every controller record went out
+   *  with no resource identity at all (§7.3). */
+  #resolvedKind: string | undefined;
+
   /**
    * The resource's structured logger, stamped with its identity, module, and
    * import-alias scope so a record identifies *which instance* emitted it — the
@@ -82,8 +90,8 @@ export class ResourceContextImpl implements ResourceContext {
    */
   get log(): Logger {
     if (!this.#log) {
-      const kind = this.metadata?.kind as string | undefined;
-      const name = this.metadata?.metadata?.name as string | undefined;
+      const kind = this.#resolvedKind;
+      const name = this.metadata?.name as string | undefined;
       const resource =
         kind && name
           ? { kind, name, id: `${this.ownerPrefix}${kind}.${name}` }
@@ -150,7 +158,17 @@ export class ResourceContextImpl implements ResourceContext {
      * dispatch fails.
      */
     private readonly owningContext: IEvaluationContext = moduleContext,
+    /**
+     * The resolved kind, known long before `create()` runs. Passed here rather
+     * than waited for at `bindResourceIdentity` so `ctx.log` carries resource
+     * identity from the moment the context exists: a controller that captures
+     * `ctx.log` in its constructor — the natural thing to do when the logger is
+     * handed to a helper — would otherwise hold an identity-less logger for the
+     * resource's whole life, and nothing would report that it had.
+     */
+    resolvedKind?: string,
   ) {
+    this.#resolvedKind = resolvedKind;
     // `ctx.env` is the sanctioned host-env channel for controllers — always the
     // real environment (kernel passes its snapshot), never the locked Proxy.
     this.env = env ?? hostEnv();
@@ -313,7 +331,11 @@ export class ResourceContextImpl implements ResourceContext {
             additionalProperties: false,
           },
     );
-    const isValid = validate(stripCompiledValues(value));
+    // A BigInt-normalized view: AJV reads `integer` as `typeof == "number"`, so a
+    // CEL integer (int64) would be rejected at a slot it satisfies. This validator
+    // runs without `useDefaults` and already checks a derived value, so there is
+    // nothing to merge back. See `bigint-schema-view.ts`.
+    const isValid = validate(withBigIntsAsNumbers(stripCompiledValues(value)));
     if (!isValid) {
       throw new RuntimeError(
         "ERR_INVALID_VALUE",
@@ -343,6 +365,10 @@ export class ResourceContextImpl implements ResourceContext {
     manifest: Record<string, unknown>,
   ): void {
     this.#self = handle;
+    // The kind is NOT restated here. It is set at construction — the single
+    // production site always has it — and `#log` is memoized on first access, so
+    // a late assignment could not reach a logger a controller already holds. A
+    // fallback here would read as a guarantee it cannot provide.
     this.#zones = new ZoneContext({
       resourceName: (this.metadata?.name as string) ?? "<unnamed>",
       resolvedKind,
@@ -420,10 +446,16 @@ export class ResourceContextImpl implements ResourceContext {
     // settlement is already observed here.
     const tracked = this.owningContext
       .runDetached(fn) // bare scope-detach primitive
-      .catch(async (err: unknown) => {
-        const detail =
-          err instanceof Error ? { name: err.name, message: err.message } : { message: String(err) };
-        await this.emitEvent("background.task.error", { resource: this.metadata.name, error: detail });
+      .catch((err: unknown) => {
+        // A detached task has no caller to throw to, so this record is the only
+        // report. It replaces the bus event rather than joining it: `eventName`
+        // IS the bridge to the event bus (§4), and a record already reaches every
+        // sink including the debug wire, so emitting both would ship two copies
+        // of one fact with two payload shapes to keep in step.
+        this.log.error("Detached task failed", undefined, {
+          error: err,
+          eventName: "background.task.error",
+        });
       })
       .finally(() => {
         this.pendingDetached.delete(tracked);
@@ -448,10 +480,12 @@ export class ResourceContextImpl implements ResourceContext {
     await Promise.race([Promise.allSettled([...this.pendingDetached]), timeout]);
     if (timer) clearTimeout(timer);
     if (this.pendingDetached.size > 0) {
-      await this.emitEvent("background.task.abandoned", {
-        resource: this.metadata.name,
-        count: this.pendingDetached.size,
-      });
+      this.log.warn(
+        `Abandoned ${this.pendingDetached.size} background task(s) after waiting ` +
+          `${DETACHED_DRAIN_TIMEOUT_MS}ms for them to drain`,
+        { "telo.detached.abandoned": this.pendingDetached.size },
+        { eventName: "background.task.abandoned" },
+      );
     }
   }
 
@@ -761,40 +795,7 @@ export class ResourceContextImpl implements ResourceContext {
    * rebased onto the module directory.
    */
   async resolveModuleFile(relative: string): Promise<string> {
-    // An absolute URI names its own location; a bare absolute path is already
-    // resolved and must not be rebased onto the module directory.
-    if (/^[a-z][a-z0-9+.-]*:/i.test(relative)) return relative;
-    if (path.isAbsolute(relative)) return pathToFileURL(relative).href;
-
-    const source = this.moduleContext.source;
-    const artifact = this.kernel.getModuleArtifact(source);
-    if (artifact) {
-      // Both the `assets` layer and `common` — the sink rule puts a file the
-      // author did not claim via `assets:` into `common`, and a module that ships
-      // static files with no bundled controller has no other route to its payload.
-      // Fetching only assets would leave such a module resolving into an empty
-      // directory.
-      await artifact.materializeModuleFiles();
-      return new URL(relative, pathToFileURL(path.join(artifact.directory, "/")).href).href;
-    }
-    // No artifact means no payload to fetch. That is normal for a module already
-    // on disk (development) or one that ships no files — but for a module reached
-    // over a non-local scheme it means the artifact carries no layer index, i.e. it
-    // predates layers. Raise the actionable error here rather than leaving each
-    // caller to invent its own message from a URI it cannot open.
-    if (!source.startsWith("file://") && !path.isAbsolute(source)) {
-      throw new RuntimeError(
-        "ERR_MODULE_FILES_UNAVAILABLE",
-        `Cannot resolve '${relative}' against module '${source}': the module's artifact ` +
-          `carries no layer index, so its files cannot be located. It was published by an ` +
-          `older Telo that wrote a single-blob artifact — republish the module, or import it ` +
-          `from a local path during development.`,
-      );
-    }
-    // Local module: resolve against the manifest URL, the same rule `include:`
-    // and sibling imports follow.
-    const base = source.startsWith("file://") ? source : pathToFileURL(source).href;
-    return new URL(relative, base).href;
+    return resolveModuleFileUri(relative, this.moduleContext.source, this.kernel);
   }
 
   on(event: string, handler: (payload?: any) => void | Promise<void>): void {

package/src/runtime-seam.ts

@@ -2,8 +2,10 @@ import {
   Loader,
   StaticAnalyzer,
   collectZoneModuleDocuments,
+  diagnosticFix,
   flattenForAnalyzer,
   type AnalysisDiagnostic,
+  type DiagnosticData,
   type ManifestSource,
   type ZoneModuleDocuments,
 } from "@telorun/analyzer";
@@ -116,6 +118,12 @@ const SEVERITY_NAMES: Record<number, CheckDiagnosticSeverity> = {
  *  read by kernels that speak no LSP. An unlabelled severity is an error: the
  *  analyzer's own default, and the safe reading for a caller gating on it. */
 function toCheckDiagnostic(diagnostic: AnalysisDiagnostic): CheckDiagnostic {
+  // The repair is read through the analyzer's accessor rather than by casting
+  // `data`, so the stamp's shape stays owned by one module. `resource` / `path`
+  // ride along because a repair replaces the value AT `path`; forwarding the
+  // fix without its anchor gives a consumer something it cannot apply.
+  const fix = diagnosticFix(diagnostic);
+  const stamp = diagnostic.data as DiagnosticData | undefined;
   return {
     code: String(diagnostic.code ?? ""),
     message: diagnostic.message,
@@ -123,6 +131,9 @@ function toCheckDiagnostic(diagnostic: AnalysisDiagnostic): CheckDiagnostic {
     source: diagnostic.source,
     line: diagnostic.range?.start?.line,
     column: diagnostic.range?.start?.character,
+    ...(stamp?.resource ? { resource: `${stamp.resource.kind}/${stamp.resource.name}` } : {}),
+    ...(stamp?.path ? { path: stamp.path } : {}),
+    ...(fix ? { fix: { replacement: fix.replacement } } : {}),
   };
 }
 

package/src/schema-validator.ts

@@ -8,17 +8,15 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { binaryKeyword, X_TELO_BINARY } from "@telorun/analyzer";
+import { mergeFilledDefaults, withBigIntsAsNumbers } from "./bigint-schema-view.js";
 import { formatAjvErrors } from "./manifest-schemas.js";
 
-/** Render a value for an error message without ever throwing.
- *
- *  `JSON.stringify` refuses BigInt, and CEL evaluates an integer literal to one —
- *  so serializing the offending data threw from inside the message template and
- *  the thrown stringify error REPLACED the validation failure. The author was
- *  told "cannot serialize BigInt" instead of which field was wrong. */
+/** Render a value for an error message without ever throwing — the offending
+ *  data may be cyclic, and a throw here would REPLACE the validation failure
+ *  with an unrelated error naming no field. */
 function describeValue(data: unknown): string {
   try {
-    return JSON.stringify(data, (_k, v) => (typeof v === "bigint" ? `${v}` : v)) ?? String(data);
+    return JSON.stringify(data) ?? String(data);
   } catch {
     return String(data);
   }
@@ -399,19 +397,32 @@ export class SchemaValidator {
     const validate = this.compileAjvOrLoadCached(sanitized, hash, persist);
     if (persist) this.persistedHashes.add(hash);
 
+    // AJV's type check is `typeof data == "number"`, so a CEL integer — a BigInt —
+    // is rejected at an `integer` slot no matter what the author writes. Check a
+    // normalized VIEW instead and merge the `useDefaults` fills back, so the value
+    // that reaches the controller keeps its 64-bit range. `withBigIntsAsNumbers`
+    // returns the same reference when there was nothing to normalize, which is what
+    // keeps the BigInt-free path byte-identical to a plain `validate(data)`.
+    const check = (data: any): boolean => {
+      const view = withBigIntsAsNumbers(data);
+      const ok = validate(view);
+      if (ok && view !== data) mergeFilledDefaults(data, view);
+      return ok;
+    };
+
     const validator = {
       validate: (data: any) => {
-        const isValid = validate(data);
-        if (!isValid) {
+        if (!check(data)) {
+          // Reports `data`, not the normalized view: the view renders a wide
+          // integer through a double, so the digits it prints for the offending
+          // value would not be the ones the author wrote.
           throw new RuntimeError(
             "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED",
             `Invalid value passed: ${describeValue(data)}. Error: ${formatAjvErrors(validate.errors)}`,
           );
         }
       },
-      isValid: (data: any) => {
-        return validate(data);
-      },
+      isValid: (data: any) => check(data),
     };
 
     this.hashCache.set(hash, validator);