@telorun/kernel 0.69.0 → 0.72.0

package/src/bigint-schema-view.ts

@@ -0,0 +1,76 @@
+/**
+ * The BigInt-normalized VIEW a JSON Schema validator can check, and merging its
+ * default-fills back onto the real value.
+ *
+ * CEL evaluates an integer to a BigInt, which AJV does not recognise as `integer`
+ * or `number` — `typeof data == "number"` is the whole of its type check. So a
+ * computed integer reaching a declared integer slot is rejected for a reason the
+ * author cannot act on, and cannot fix without casting the value to a float. The
+ * value is not wrong; the validator cannot see it.
+ *
+ * Validating a normalized view rather than coercing in place is what keeps that a
+ * validator concern: the dispatched value keeps its BigInts, since a controller may
+ * need the full 64-bit range, and serialization emits them exactly (see
+ * `enableBigIntJson` in `@telorun/sdk`). A value beyond the safe-integer range loses
+ * precision in the VIEW, which can only affect a bound check at the extremes.
+ */
+
+/** A structural copy of `value` with every BigInt rendered as a Number. Returns
+ *  the SAME reference when there was nothing to change, which is what lets a
+ *  caller skip the merge-back entirely on the common path. Non-plain objects (a
+ *  live `Stream`, a resource instance) pass through by reference — they are not
+ *  data to be walked. */
+export function withBigIntsAsNumbers(value: unknown): unknown {
+  if (typeof value === "bigint") return Number(value);
+  if (Array.isArray(value)) {
+    let changed = false;
+    const items = value.map((item) => {
+      const next = withBigIntsAsNumbers(item);
+      if (next !== item) changed = true;
+      return next;
+    });
+    return changed ? items : value;
+  }
+  if (!value || typeof value !== "object") return value;
+  if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+  let changed = false;
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    const next = withBigIntsAsNumbers(item);
+    if (next !== item) changed = true;
+    out[key] = next;
+  }
+  return changed ? out : value;
+}
+
+/** Copy keys an AJV `useDefaults` fill added to `view` back onto `target`.
+ *  Only ADDITIONS are taken: a key already present came from the caller and its
+ *  original (possibly BigInt) value is the one to keep.
+ *
+ *  Arrays are walked index-wise, not treated as leaves: AJV writes a default at
+ *  every level it finds one, including inside `items`, and `Collection.Sort`'s
+ *  `orderBy[].descending` is exactly that shape. Bailing at the array boundary
+ *  would drop those fills silently — a worse failure than the throw it replaced,
+ *  because the call then succeeds with the default missing. This mirrors the
+ *  copy side, where `copyForDefaults` already fans out through an `[]` segment. */
+export function mergeFilledDefaults(target: unknown, view: unknown): unknown {
+  if (target === view) return target;
+  if (!target || typeof target !== "object") return target;
+  if (!view || typeof view !== "object") return target;
+
+  if (Array.isArray(target)) {
+    if (!Array.isArray(view)) return target;
+    for (let i = 0; i < target.length && i < view.length; i++) {
+      target[i] = mergeFilledDefaults(target[i], view[i]);
+    }
+    return target;
+  }
+  if (Array.isArray(view)) return target;
+
+  const out = target as Record<string, unknown>;
+  for (const [key, filled] of Object.entries(view as Record<string, unknown>)) {
+    if (!(key in out)) out[key] = filled;
+    else out[key] = mergeFilledDefaults(out[key], filled);
+  }
+  return out;
+}

package/src/cel-handlers.ts

@@ -12,13 +12,10 @@ export const nodeCelHandlers = {
     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",
+  // An int / uint is a BigInt here and serializes as its exact digits — see
+  // `enableBigIntJson` in `@telorun/sdk`, installed at boot. 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) ?? "null",
 };

package/src/controllers/module/import-controller.ts

@@ -144,7 +144,20 @@ export async function create(
     moduleManifest.secrets ?? {},
   );
   const childCtx = new ModuleContext(
-    ctx.moduleContext.source,
+    // The LIBRARY's own manifest URL, not the importer's. `source` is what every
+    // module-relative file reference is measured from — `ctx.resolveModuleFile`
+    // for a controller, an `!include-*` embed for a manifest value — so carrying
+    // the parent's here made a library read the CONSUMER's directory. That is
+    // worse than a hard error: a consumer who happens to have a file at the same
+    // relative path gets theirs silently. It also contradicted packaging, which
+    // is per-module and had already put the library's file in the library's own
+    // artifact.
+    //
+    // The MANIFEST URL, stamped by the loader — not `resolvedUrl`, which is the
+    // import source as written (`./lib`, a directory). Resolving `assets/x` against
+    // a directory URL with no trailing slash drops its last segment, which is how
+    // the consumer's directory got read in the first place.
+    ((moduleManifest.metadata as { source?: string } | undefined)?.source ?? resolvedUrl),
     importVariables,
     importSecrets,
     {},

package/src/evaluation-context.ts

@@ -317,7 +317,14 @@ function compileWalker(value: unknown): Walker {
       return out;
     };
   }
-  if (value !== null && typeof value === "object") {
+  // Only PLAIN objects are rebuilt. Anything else — a `Uint8Array` embedded by
+  // `!include-bytes`, a class instance — is opaque and passes through by
+  // reference, the same rule `precompileDoc` follows. Rebuilding from
+  // `Object.entries` would turn a byte buffer into `{"0":137,…}` silently, with
+  // no error anywhere: the bytes would simply arrive at the controller as the
+  // wrong shape.
+  const proto = value !== null && typeof value === "object" ? Object.getPrototypeOf(value) : false;
+  if (proto === Object.prototype || proto === null) {
     const entries = Object.entries(value as Record<string, unknown>).map(
       ([k, v]) => [k, compileWalker(v)] as const,
     );

package/src/index.ts

@@ -44,6 +44,7 @@ export type {
 } from "./transports/transport.js";
 export { ExecutionContext } from "./execution-context.js";
 export { Kernel, type KernelOptions } from "./kernel.js";
+export { enableBigIntJson } from "./bigint-json.js";
 export { nodeCelHandlers } from "./cel-handlers.js";
 export { ModuleContext } from "./module-context.js";
 export { ManifestRegistry as Registry } from "./registry.js";

package/src/invocation-contract-binding.ts

@@ -305,27 +305,23 @@ export function bindContract(instance: ResourceInstance, binding: ContractBindin
     instance.invoke = async (inputs: any, ...rest: unknown[]) => {
       let effective = inputs;
       if (input) {
+        // Copied only so the validator's default-fill cannot mutate what the
+        // caller still holds. The BigInt normalization a JSON Schema validator
+        // needs (CEL evaluates an integer to one, which AJV does not recognise
+        // as `integer`) belongs to the validator and is applied there — see
+        // `bigint-schema-view.ts`. Doing it here as well would walk every input
+        // tree twice per dispatch, and split one concern across two layers.
         effective = copyForDefaults(inputs, input.defaultPaths());
-        // Validate a BIGINT-NORMALIZED view, not the values themselves. CEL
-        // evaluates an integer literal to a BigInt, which a JSON Schema
-        // validator does not recognise as `integer` — so every computed integer
-        // reaching a declared integer input would be rejected for a reason the
-        // author cannot act on. The dispatched values keep their BigInts, since
-        // a controller may need the full 64-bit range.
-        const view = withBigIntsAsNumbers(effective);
         try {
-          input.validate(view);
+          input.validate(effective);
         } catch (error) {
           throw contractViolation("inputType", describeTarget, error);
         }
-        // Defaults are additive, so anything the validator filled into the view
-        // is a key the caller omitted — copy exactly those back.
-        effective = mergeFilledDefaults(effective, view);
       }
       const result = await original(effective, ...rest);
       if (output) {
         try {
-          output.validate(withBigIntsAsNumbers(result));
+          output.validate(result);
         } catch (error) {
           throw contractViolation("outputType", describeTarget, error);
         }
@@ -339,7 +335,7 @@ export function bindContract(instance: ResourceInstance, binding: ContractBindin
     instance.provide = async (...args: unknown[]) => {
       const result = await original(...args);
       try {
-        output.validate(withBigIntsAsNumbers(result));
+        output.validate(result);
       } catch (error) {
         throw contractViolation("outputType", describeTarget, error);
       }
@@ -348,45 +344,3 @@ export function bindContract(instance: ResourceInstance, binding: ContractBindin
   }
 }
 
-/** A structural copy with every BigInt rendered as a Number, for validation
- *  only. A value beyond the safe-integer range loses precision in the VIEW,
- *  which can only affect a bound check at the extremes; the dispatched value is
- *  untouched. Non-plain objects (a live `Stream`, a resource instance) pass
- *  through by reference — they are not data to be walked. */
-export function withBigIntsAsNumbers(value: unknown): unknown {
-  if (typeof value === "bigint") return Number(value);
-  if (Array.isArray(value)) {
-    let changed = false;
-    const items = value.map((item) => {
-      const next = withBigIntsAsNumbers(item);
-      if (next !== item) changed = true;
-      return next;
-    });
-    return changed ? items : value;
-  }
-  if (!value || typeof value !== "object") return value;
-  if (Object.getPrototypeOf(value) !== Object.prototype) return value;
-  let changed = false;
-  const out: Record<string, unknown> = {};
-  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
-    const next = withBigIntsAsNumbers(item);
-    if (next !== item) changed = true;
-    out[key] = next;
-  }
-  return changed ? out : value;
-}
-
-/** Copy keys the validator's default-fill added to `view` back onto `target`.
- *  Only ADDITIONS are taken: a key already present came from the caller and its
- *  original (possibly BigInt) value is the one to dispatch. */
-function mergeFilledDefaults(target: unknown, view: unknown): unknown {
-  if (target === view) return target;
-  if (!target || typeof target !== "object" || Array.isArray(target)) return target;
-  if (!view || typeof view !== "object" || Array.isArray(view)) return target;
-  const out = target as Record<string, unknown>;
-  for (const [key, filled] of Object.entries(view as Record<string, unknown>)) {
-    if (!(key in out)) out[key] = filled;
-    else out[key] = mergeFilledDefaults(out[key], filled);
-  }
-  return out;
-}

package/src/kernel.ts

@@ -38,6 +38,7 @@ import {
 import { parseArgs } from "util";
 import { ControllerRegistry } from "./controller-registry.js";
 import { EventBus } from "./events.js";
+import { enableBigIntJson } from "./bigint-json.js";
 import { hostEnv, lockControllerEnv } from "./host-env.js";
 import { KernelTracer } from "./tracing.js";
 import { KernelLogging, type LoggingManifestBlock } from "./logging/kernel-logging.js";
@@ -51,6 +52,7 @@ import { nodeCelHandlers } from "./cel-handlers.js";
 import { parseRef, seedInvokeSource } from "./invoke-dispatch.js";
 import { stripCompiledValues } from "./schema-compiled-values.js";
 import { injectAtPath } from "./dependency-injection.js";
+import { resolveIncludeSentinels, type IncludeCache } from "./resolve-include-sentinels.js";
 import {
   computeAnalysisSignature,
   readAnalysisStamp,
@@ -136,6 +138,10 @@ export class Kernel implements IKernel {
   private idleResolvers: Array<() => void> = [];
   private _exitCode = 0;
   private readonly sharedSchemaValidator = new SchemaValidator();
+  /** `!include-*` reads, keyed by resolved URI, so two resources embedding the
+   *  same asset read it once. Kernel-scoped: the values are retained by the
+   *  resources holding them anyway, so this deduplicates rather than retains. */
+  private readonly includeCache: IncludeCache = new Map();
   private rootContext!: ModuleContext;
   private staticManifests: ResourceManifest[] = [];
   private _entryUrl?: string;
@@ -761,6 +767,13 @@ export class Kernel implements IKernel {
     }
     this._bootCalled = true;
 
+    // Make a CEL integer JSON-serializable before any controller runs. CEL
+    // models `int` as int64 (a JS BigInt here), and `JSON.stringify` throws on
+    // one — so every JSON boundary a manifest can reach, in this kernel and in
+    // any module, needs the answer installed before the first value crosses it.
+    // Process-global and idempotent, like the env guardrail below.
+    enableBigIntJson();
+
     // Lock the ambient host environment before any controller runs: a key the
     // manifest binds via `variables`/`secrets`/`ports` must be read through
     // `ctx.env` or the declared binding, never the raw `process.env` var. Every
@@ -1145,6 +1158,7 @@ export class Kernel implements IKernel {
     args?: ParsedArgs,
     ownerPrefix = "",
     owningContext?: IEvaluationContext,
+    resolvedKind?: string,
   ): ResourceContext {
     return new ResourceContextImpl(
       this,
@@ -1158,6 +1172,7 @@ export class Kernel implements IKernel {
       args,
       ownerPrefix,
       owningContext ?? moduleContext,
+      resolvedKind,
     );
   }
 
@@ -1275,6 +1290,19 @@ export class Kernel implements IKernel {
     const compile = [...parentEval.compile, ...ownEval.compile];
     const runtime = [...parentEval.runtime, ...ownEval.runtime];
 
+    // Embedded files are read here, at the single instance-production site, and
+    // not at manifest load: `telo.yaml` is its own artifact layer so that reading
+    // a manifest cannot pull the payload, and an app loads every imported
+    // library's manifest. Before schema validation, so the schema sees the
+    // resolved value — bytes arrive at an `x-telo-binary` slot as the
+    // `Uint8Array` that annotation demands.
+    await resolveIncludeSentinels(
+      resource,
+      this.findModuleContext(evalContext).source,
+      this,
+      this.includeCache,
+    );
+
     // Schema validation runs before CEL evaluation so it sees the original manifest
     // shape. CompiledValue wrappers (from load-time precompilation) are stripped,
     // restoring the pre-CEL string view that the schema expects.
@@ -1308,6 +1336,7 @@ export class Kernel implements IKernel {
       // Snapshot publication targets the context that OWNS the instance — for a
       // `with:`-scoped resource that is the per-run scope child, not the module.
       evalContext,
+      resolvedKind,
     );
     const instance = await controller.create(processedResource, ctx);
     if (!instance) return null;

package/src/logging/encode-json.ts

@@ -1,4 +1,4 @@
-import { formatUnixNano, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
+import { bigIntAt, formatUnixNano, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
 
 /**
  * The `json` encoding — `kernel/specs/logging.md` §11.1. One JSON object per
@@ -83,16 +83,21 @@ function sortKeysDeep(value: AnyValue): AnyValue {
 }
 
 function makeReplacer(encodeBytes: BytesEncoder) {
-  return function replacer(this: unknown, _key: string, value: unknown): unknown {
-    if (typeof value === "bigint") {
-      // Values beyond 2^53 lose precision in a JS receiver, so they degrade to a
-      // decimal string rather than to a wrong number — the same reasoning OTLP
-      // gives for quoting its 64-bit fields.
-      return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)
-        ? Number(value)
-        : value.toString();
+  return function replacer(this: unknown, key: string, value: unknown): unknown {
+    // Read the BigInt off the HOLDER, not off `value`: `BigInt.prototype.toJSON`
+    // has already rewritten it to the exact-digits form every other JSON boundary
+    // wants (see `enableBigIntJson`). A log record is the one destination where
+    // that is wrong — a value beyond 2^53 loses precision in a JS receiver, so it
+    // degrades to a decimal string rather than to a wrong number, the same
+    // reasoning OTLP gives for quoting its 64-bit fields.
+    const source = bigIntAt(this, key);
+    if (source !== undefined) {
+      return source >= MIN_SAFE && source <= MAX_SAFE ? Number(source) : source.toString();
     }
     if (value instanceof Uint8Array) return encodeBytes(value);
     return value;
   };
 }
+
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);

package/src/logging/encode-pretty.ts

@@ -1,4 +1,4 @@
-import { severityFloor, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
+import { bigIntAt, severityFloor, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
 
 /**
  * The `pretty` encoding — `kernel/specs/logging.md` §11.2. For humans on a
@@ -90,8 +90,17 @@ function quoteIfNeeded(text: string): string {
   return /[\s"=]/.test(text) ? JSON.stringify(text) : text;
 }
 
-function jsonSafe(_key: string, value: unknown): unknown {
-  if (typeof value === "bigint") return value.toString();
+function jsonSafe(this: unknown, key: string, value: unknown): unknown {
+  // Read the integer off the HOLDER, not off `value`: `BigInt.prototype.toJSON`
+  // (see `enableBigIntJson`) runs BEFORE a replacer, so by the time this is
+  // called a wide integer is already the exact-digits form every wire encoding
+  // wants. This console encoding renders it as a decimal string instead, and
+  // matching on `typeof value === "bigint"` would silently stop doing so —
+  // a changed encoding, not an error. Reading the holder keeps the rendering
+  // identical whether or not the patch is installed, which matters because a
+  // test can call this encoder outside a booted kernel.
+  const source = bigIntAt(this, key);
+  if (source !== undefined) return source.toString();
   if (value instanceof Uint8Array) return `<${value.byteLength} bytes>`;
   return value;
 }

package/src/module-file-resolution.ts

@@ -0,0 +1,64 @@
+import * as path from "path";
+import { pathToFileURL } from "url";
+import { RuntimeError } from "@telorun/sdk";
+import type { ModuleArtifact } from "./bundle/module-artifact.js";
+
+/** The slice of the kernel this module needs: a module's artifact, when it has
+ *  one. A module already on disk has none — that is normal, not an error. */
+export interface ModuleArtifactLookup {
+  getModuleArtifact(source: string | undefined): ModuleArtifact | undefined;
+}
+
+/**
+ * Resolve a module-relative reference against the declaring module's own
+ * directory, materializing the layers that could carry it on first use.
+ *
+ * A URI, not a filesystem path: the SDK is cross-runtime, and a path is only
+ * what *this* kernel happens to return for a module whose files are local. An
+ * already-absolute URI (one with a scheme) passes through untouched; a bare
+ * absolute filesystem path is returned as a `file://` URI rather than being
+ * rebased onto the module directory.
+ *
+ * Shared by `ctx.resolveModuleFile` and by `!include-*` resolution, so a file
+ * reached by a controller and a file embedded by a tag are located by one rule
+ * — including which layers get materialized on the way.
+ */
+export async function resolveModuleFileUri(
+  relative: string,
+  source: string,
+  lookup: ModuleArtifactLookup,
+): 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 artifact = lookup.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;
+}