@telorun/kernel 0.73.0 → 0.75.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -61,9 +61,9 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.58.0",
+    "@telorun/analyzer": "0.60.0",
     "@telorun/glob": "0.2.0",
-    "@telorun/templating": "0.14.0",
+    "@telorun/templating": "0.16.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "packageurl-js": "^2.0.1",
@@ -75,7 +75,7 @@
     "@types/tar-stream": "^3.1.3",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.73.0"
+    "@telorun/sdk": "0.75.0"
   },
   "optionalDependencies": {
     "esbuild": "^0.25.12"

package/src/controller-loaders/source-bundle-builder.ts

@@ -254,6 +254,29 @@ export async function buildControllerFromSource(
   return work;
 }
 
+/**
+ * The bundle for `entryFile` **and the file set that produced it**.
+ *
+ * The publish and release paths need both halves of one build: the bytes become
+ * the module's controller layer, and the metafile inputs become the release
+ * edge graph — which module's source got inlined into whose artifact. Asking for
+ * them separately would either build twice or read an index written by a
+ * different build.
+ *
+ * Unlike the loader's path there is **no fallthrough here**. A host without
+ * esbuild raises `ControllerEnvMissingError` from the build, and this caller
+ * must let it: selecting the prebuilt `path=` file instead would digest and ship
+ * bytes other than the source it claims to be built from, which is the one
+ * outcome the whole release design exists to prevent.
+ */
+export async function buildControllerBundle(
+  entryFile: string,
+  cacheRoot: string,
+): Promise<{ path: string; inputs: string[] }> {
+  const path = await buildControllerFromSource(entryFile, cacheRoot);
+  return { path, inputs: await lastBuildInputs(entryFile, cacheRoot) };
+}
+
 async function build(entryFile: string, cacheDir: string): Promise<string> {
   const esbuild = await loadEsbuild();
   if (!esbuild) {

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

@@ -1,4 +1,4 @@
-import { AnalysisRegistry, DiagnosticSeverity, foldIntegrity, parseExportEntry, StaticAnalyzer } from "@telorun/analyzer";
+import { AnalysisRegistry, DiagnosticSeverity, authoredModuleMetadata, foldIntegrity, parseExportEntry, StaticAnalyzer } from "@telorun/analyzer";
 import type { ResourceInstance } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import { publishedPropsOf } from "../../evaluation-context.js";
@@ -166,6 +166,13 @@ export async function create(
     ctx.moduleContext.createInstance,
     ctx.moduleContext.emit,
   );
+  // `module.<field>` inside the library reads the LIBRARY's own metadata. Its
+  // version is its own — carrying the importer's would make a library reporting
+  // `module.version` report whatever happened to import it.
+  childCtx.setModuleMetadata(
+    authoredModuleMetadata(moduleManifest.metadata as Record<string, unknown> | undefined),
+  );
+
   const child = ctx.moduleContext.spawnChild(childCtx);
 
   // A library references its own kinds via `Self.<Kind>` (e.g. when it declares an

package/src/index.ts

@@ -35,7 +35,11 @@ export {
   type ResolvedControllerLayer,
 } from "./bundle/module-artifact.js";
 export { readOwnerManifest, type OwnerManifest } from "./bundle/module-manifest.js";
-export { lastBuildInputs } from "./controller-loaders/source-bundle-builder.js";
+export {
+  buildControllerBundle,
+  canBuildFromSource,
+  lastBuildInputs,
+} from "./controller-loaders/source-bundle-builder.js";
 export type {
   PayloadLayer,
   PublishBundle,

package/src/invocation-contract-binding.ts

@@ -1,5 +1,8 @@
 import {
   type ContractDirection,
+  declaredScalarPaths,
+  type DeclaredScalarForm,
+  type DeclaredScalarPath,
   defaultBearingPaths,
   effectiveContractField,
   type DefResolver,
@@ -63,6 +66,10 @@ export interface BoundContract {
   /** Paths a default can be written to — how far the caller's value must be
    *  copied before validation runs. Empty when the contract declares none. */
   defaultPaths(): string[][];
+  /** Paths whose declared type fixes a scalar representation — the leaves a
+   *  value is normalized at, in either direction. Empty when the contract
+   *  declares none. */
+  scalarPaths(): DeclaredScalarPath[];
 }
 
 const CONTRACT_ERROR: Record<ContractDirection, string> = {
@@ -123,6 +130,7 @@ export function resolveBoundContract(
 
   let compiled: { validate(value: unknown): void } | undefined;
   let paths: string[][] | undefined;
+  let scalars: DeclaredScalarPath[] | undefined;
 
   const resolve = (): { validate(value: unknown): void } => {
     if (compiled !== undefined) return compiled;
@@ -140,6 +148,7 @@ export function resolveBoundContract(
     }
     const stripped = withLiveValuesSkipped(schema, factory.resolveRef);
     paths = defaultBearingPaths(stripped, factory.resolveRef);
+    scalars = declaredScalarPaths(stripped, factory.resolveRef);
     // Compile by NAME whenever the declaration is one, so the type's CEL
     // `rules:` are composed in — including when a stream had to be stripped, in
     // which case the stream-bearing properties are dropped from the schema the
@@ -159,6 +168,10 @@ export function resolveBoundContract(
       resolve();
       return paths ?? [];
     },
+    scalarPaths: () => {
+      resolve();
+      return scalars ?? [];
+    },
   };
 }
 
@@ -214,6 +227,91 @@ function copyAlong(node: unknown, segments: readonly string[]): unknown {
   return node;
 }
 
+/**
+ * `value` with every leaf normalized to the representation its declaration
+ * names, copied along the containers above each one so the producer's own object
+ * is not rewritten under it.
+ *
+ * A declared shape says what the value IS, not only what it must pass — the same
+ * service a JSON Schema gives an HTTP response serializer. Telo's CEL layer
+ * takes the declaration literally: `integer` types as CEL `int` and a CEL int is
+ * a BigInt, so a controller handing back a plain JS number at an `integer` slot
+ * makes the contract a lie that surfaces nowhere until an expression composes it
+ * — `result.n + 1` type-checking statically and then dying at dispatch with
+ * `no such overload: dyn<double> + int`. Normalizing at the boundary that
+ * already knows the declared shape closes it for every kind at once, instead of
+ * once per module after each report.
+ *
+ * BOTH DIRECTIONS, deliberately. A controller cannot be written correctly
+ * against a slot that hands it a JS number when the manifest wrote a literal and
+ * a BigInt when CEL computed the same value — it would have to accept either at
+ * every declared-integer field, which is what `typeof x === "number"` guards
+ * around the standard library were quietly relying on. One representation per
+ * declaration is what makes the declared type something a controller can read.
+ *
+ * Only an EXACT conversion is performed: an integral number becomes an int64,
+ * and a BigInt becomes a double only when the round-trip is lossless. A
+ * fractional number at an integer slot, a string, a null, a magnitude no double
+ * can hold — all are left exactly as they arrived, so a value that genuinely
+ * violates the contract is still rejected rather than quietly repaired into
+ * something that passes, and a 64-bit integer is never truncated to reach a
+ * `number` slot (which is the `double(...)` defect this whole line of work
+ * exists to retire).
+ */
+export function normalizeDeclaredScalars(
+  value: unknown,
+  paths: readonly DeclaredScalarPath[],
+): unknown {
+  if (paths.length === 0 || !value || typeof value !== "object") return value;
+  let out: unknown = value;
+  for (const { path, form } of paths) out = normalizeAlong(out, path, form);
+  return out;
+}
+
+function normalizeAlong(
+  node: unknown,
+  segments: readonly string[],
+  form: DeclaredScalarForm,
+): unknown {
+  if (!node || typeof node !== "object") return node;
+  const [head, ...rest] = segments;
+
+  if (head === "[]") {
+    if (!Array.isArray(node)) return node;
+    let changed = false;
+    const next = node.map((item) => {
+      const value = rest.length === 0 ? asForm(item, form) : normalizeAlong(item, rest, form);
+      if (value !== item) changed = true;
+      return value;
+    });
+    return changed ? next : node;
+  }
+
+  const container = node as Record<string, unknown>;
+  if (!(head! in container)) return node;
+  const child = container[head!];
+  const next = rest.length === 0 ? asForm(child, form) : normalizeAlong(child, rest, form);
+  if (next === child) return node;
+  // Copy-on-write, and only once a leaf actually moved: a producer may hand back
+  // an object it retains (a cached record, a live config), and rewriting it in
+  // place would change what it holds.
+  const copy = shallowCopy(container);
+  copy[head!] = next;
+  return copy;
+}
+
+function asForm(value: unknown, form: DeclaredScalarForm): unknown {
+  if (form === "int64") {
+    return typeof value === "number" && Number.isInteger(value) ? BigInt(value) : value;
+  }
+  if (typeof value !== "bigint") return value;
+  const asNumber = Number(value);
+  // Lossless only. Past the safe range a double cannot hold the integer, and
+  // handing back a silently-rounded one is the precision loss the int64 work
+  // exists to remove.
+  return BigInt(asNumber) === value ? asNumber : value;
+}
+
 /**
  * Raise a contract violation as a structured {@link InvokeError}.
  *
@@ -306,11 +404,19 @@ export function bindContract(instance: ResourceInstance, binding: ContractBindin
       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.
+        // caller still holds. Making the value READABLE to a JSON Schema
+        // validator regardless of representation is the validator's own concern
+        // and is applied there (`bigint-schema-view.ts`).
+        //
+        // Deliberately NOT normalized on this side. Normalization states what a
+        // value IS to whoever reads it next, and on the way in that reader is a
+        // controller written in the host language — a declared `integer` reaching
+        // one as an int64 is a change to the authoring surface of every module,
+        // not a repair to a lie. On the way OUT the reader is CEL, which already
+        // types the declaration as `int`, so there the declaration and the value
+        // genuinely disagree. The asymmetry is the point: a controller still sees
+        // whatever the call site produced and must accept both, which is what
+        // `bigint-schema-view.ts` documents.
         effective = copyForDefaults(inputs, input.defaultPaths());
         try {
           input.validate(effective);
@@ -325,6 +431,12 @@ export function bindContract(instance: ResourceInstance, binding: ContractBindin
         } catch (error) {
           throw contractViolation("outputType", describeTarget, error);
         }
+        // AFTER validation, not before: the validator fills declared defaults,
+        // and a default written as a plain YAML number is exactly the leaf that
+        // has to come out normalized too. Validation itself is indifferent to
+        // which representation arrives (`bigint-schema-view.ts`), so ordering
+        // costs nothing there.
+        return normalizeDeclaredScalars(result, output.scalarPaths());
       }
       return result;
     };
@@ -339,7 +451,7 @@ export function bindContract(instance: ResourceInstance, binding: ContractBindin
       } catch (error) {
         throw contractViolation("outputType", describeTarget, error);
       }
-      return result;
+      return normalizeDeclaredScalars(result, output.scalarPaths());
     };
   }
 }

package/src/kernel.ts

@@ -1,5 +1,6 @@
 import {
   AnalysisRegistry,
+  authoredModuleMetadata,
   buildEvalPaths,
   collectZoneModuleDocuments,
   flattenForAnalyzer,
@@ -689,6 +690,14 @@ export class Kernel implements IKernel {
           }
         });
         this.rootContext.setTargets(rawTargets as BootTarget[]);
+        // `module.<field>` — the module doc's own metadata, so a manifest reads
+        // its version instead of restating it in a second place nothing keeps in
+        // sync. Set from the module doc rather than the application specifically:
+        // an imported library's context gets its own, which is the only reading
+        // that is true of the resources inside it.
+        this.rootContext.setModuleMetadata(
+          authoredModuleMetadata(manifest.metadata as Record<string, unknown> | undefined),
+        );
         if (manifest.kind === "Telo.Application") {
           rootApplicationManifest = manifest;
           this._appName = (manifest.metadata as { name?: string } | undefined)?.name;

package/src/manifest-schemas.ts

@@ -5,15 +5,19 @@ import addFormats from "ajv-formats";
 import { OBSERVED_STATE_SCHEMA, registerTeloKeywords } from "@telorun/analyzer";
 const Ajv = AjvModule.default ?? AjvModule;
 
-// Re-export the shared ResourceRef fragment from the templating package
-// so consumers that pull it from the kernel manifest-schemas surface keep
-// working. The canonical home is `@telorun/templating` because the
-// fragment describes the parsed shape of the `!ref` tag's TaggedSentinel.
+// Re-export the shared manifest fragments so consumers reaching them through the
+// kernel's surface keep working. The canonical home is `@telorun/analyzer`: they
+// describe manifest STRUCTURE, and the editor validates in a browser through the
+// analyzer, which must not depend on this package — a fragment here would exist
+// only at runtime, invisible to `telo check` and to the editor.
 export {
+  InvokeStepSchema,
   MANIFEST_SCHEMA_URI,
   ManifestRootSchema,
+  manifestFragmentRef,
   ResourceRefSchema,
-} from "@telorun/templating";
+  RetryPolicySchema,
+} from "@telorun/analyzer";
 
 const metadataSchema = {
   type: "object",

package/src/module-context.ts

@@ -1,4 +1,10 @@
-import { deriveContext, executeInvokeStep, getRefIdentity, RuntimeError } from "@telorun/sdk";
+import {
+  deriveContext,
+  executeInvokeStep,
+  getRefIdentity,
+  type InlineInvokeTarget,
+  RuntimeError,
+} from "@telorun/sdk";
 import type { ScopeConfig } from "./logging/scope-config.js";
 import type {
   BootTarget,
@@ -69,6 +75,11 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
    *  populated on the root context from the Application's `ports` block;
    *  imported child modules keep this empty. */
   private _ports: Record<string, unknown> = {};
+  /** The module doc's own `metadata`, published as `module.<field>` so a
+   *  manifest can read its own version instead of restating it. Per module, not
+   *  per application: an imported library's resources read the LIBRARY's
+   *  metadata, which is the only reading that is true of them. */
+  private _module: Record<string, unknown> = {};
 
   /** Maps import alias → real module name for kind resolution. */
   private readonly importAliases = new Map<string, string>();
@@ -175,6 +186,10 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     return this._ports;
   }
 
+  get module(): Record<string, unknown> {
+    return this._module;
+  }
+
   setVariables(vars: Record<string, unknown>): void {
     this._variables = vars;
     this._rebuildContext();
@@ -185,6 +200,11 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     this._rebuildContext();
   }
 
+  setModuleMetadata(metadata: Record<string, unknown>): void {
+    this._module = metadata;
+    this._rebuildContext();
+  }
+
   setTargets(vars: BootTarget[]): void {
     this.targets = vars;
   }
@@ -515,6 +535,7 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       secrets,
       resources: this._resources,
       ports: this._ports,
+      module: this._module,
     };
   }
 
@@ -524,6 +545,7 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       secrets: this._secrets,
       resources: this._resources,
       ports: this._ports,
+      module: this._module,
     };
     this._secretValues = collectSecretValues(this._secrets);
   }
@@ -647,16 +669,22 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       // step — only a structural `{ invoke: <ref>, inputs }` spec (no `run`)
       // belongs here; the live instance falls through to the runnable branch.
       if (!isRunnableInstance(target) && "invoke" in target && target.invoke !== undefined) {
+        // SPREAD, not field-by-field. A dispatch site is one kernel-owned shape,
+        // and rebuilding it here by hand is what silently dropped `retry:` —
+        // the schema admitted the field and this reconstruction threw it away, so
+        // a boot target asking for three attempts got one. Forwarding the entry
+        // keeps this correct the next time the shape grows.
+        // A cross-module `!ref Alias.name` stays a `{kind, name, alias}` ref; the leaf's
+        // alias branch resolves it via `resolveImportedInstance` and dispatches through
+        // `invokeResolved` so invocation events and error wrapping still fire.
         const step: InvokeStep = {
+          ...(target as InlineInvokeTarget),
           name: target.name ?? `Target${i}`,
-          when: target.when,
-          // A cross-module `!ref Alias.name` stays a `{kind, name, alias}` ref; the leaf's
-          // alias branch resolves it via `resolveImportedInstance` and dispatches through
-          // `invokeResolved` so invocation events and error wrapping still fire.
           invoke: target.invoke,
-          inputs: target.inputs,
         };
-        await executeInvokeStep(step, stepCtx, { steps });
+        // The boot cancellation, so a target parked in a retry backoff ends on
+        // SIGINT rather than sitting out the remaining delay.
+        await executeInvokeStep(step, stepCtx, { steps, invokeCtx: ctx });
         continue;
       }
       if ("ref" in target && target.ref != null) {

package/src/schema-compiled-values.ts

@@ -1,4 +1,5 @@
 import { isCompiledValue } from "@telorun/sdk";
+import { selectUnionBranch } from "@telorun/analyzer";
 
 /** Returns a schema-appropriate placeholder value for a CompiledValue field. */
 function placeholderForSchema(schema: Record<string, unknown>): unknown {
@@ -9,6 +10,19 @@ function placeholderForSchema(schema: Record<string, unknown>): unknown {
   // 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];
+  // A union with no `type` of its own: take the first branch that yields a
+  // placeholder, so a whole-field CEL leaf at an `anyOf` slot is not handed the
+  // `""` fallback that only a string branch would accept. Mirrors the analyzer's
+  // `celPlaceholderForSchema`, which makes the same substitution for the static
+  // half — the two must agree or one rejects what the other passes.
+  if (schema.type === undefined) {
+    const branches = (schema.anyOf ?? schema.oneOf) as Record<string, unknown>[] | undefined;
+    if (Array.isArray(branches)) {
+      for (const branch of branches) {
+        if (branch && typeof branch === "object") return placeholderForSchema(branch);
+      }
+    }
+  }
   switch (schema.type) {
     case "integer":
     case "number":
@@ -113,7 +127,20 @@ export function stripCompiledValues(
   // that merely appears twice is still stripped both times.
   const ancestors = new Set<object>();
 
-  const walk = (value: unknown, nodeSchema: Record<string, unknown>): unknown => {
+  const walk = (value: unknown, rawNodeSchema: Record<string, unknown>): unknown => {
+    // A UNION carries no `type` / `items` / `properties` of its own, so descending
+    // through one hands every CEL leaf underneath the schema-unaware `""`
+    // placeholder — which the branches then reject, reporting violations against
+    // a value the author never wrote (`/success/1 must be integer` for a `!cel`
+    // inside a list). Resolving the branch first is what lets the leaves be
+    // placed. Shared with the analyzer rather than reimplemented: the static and
+    // dispatch halves must choose the same branch, or one reports what the other
+    // accepts.
+    const nodeSchema = selectUnionBranch(
+      resolveSchemaRef(rawNodeSchema, root),
+      value,
+      root as Record<string, any>,
+    ) as Record<string, unknown>;
     const resolved = resolveSchemaRef(nodeSchema, root);
 
     if (isCompiledValue(value)) return placeholderForSchema(resolved);

package/src/schema-validator.ts

@@ -7,7 +7,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
-import { registerTeloKeywords } from "@telorun/analyzer";
+import { ManifestRootSchema, registerTeloKeywords } from "@telorun/analyzer";
 import { X_TELO_TYPE } from "@telorun/sdk";
 import { mergeFilledDefaults, withBigIntsAsNumbers } from "./bigint-schema-view.js";
 import { formatAjvErrors } from "./manifest-schemas.js";
@@ -25,7 +25,6 @@ function describeValue(data: unknown): string {
 import {
   EXACT_TEMPLATE_REGEX,
   isTaggedSentinel,
-  ManifestRootSchema,
 } from "@telorun/templating";
 
 const Ajv = AjvModule.default ?? AjvModule;