@telorun/kernel 0.60.0 → 0.62.0

package/src/bundle/module-artifact.ts

@@ -26,6 +26,17 @@ export interface MaterializedLayer {
   files: string[];
 }
 
+/** A materialized controller layer plus whether reaching it cost a transfer.
+ *
+ *  `transferred` is out of band rather than a field on `MaterializedLayer`
+ *  because it describes THIS call, not the layer: the value is memoized and
+ *  shared, so a flag on it would be meaningless to every other caller. Only the
+ *  controller path reports progress, so only it asks. */
+export interface ResolvedControllerLayer {
+  layer: MaterializedLayer;
+  transferred: boolean;
+}
+
 /**
  * Map Node's platform vocabulary onto the canonical OCI/GOOS names selectors are
  * published with. Node says `win32`/`x64`; OCI descriptors say
@@ -123,8 +134,11 @@ export class ModuleArtifact {
   private readonly transports: TransportRegistry;
   private readonly log: Logger;
   /** In-flight / completed materializations, keyed by blob digest. Rejections
-   *  are dropped so a transient fetch failure retries on the next ask. */
-  private readonly inFlight = new Map<string, Promise<MaterializedLayer>>();
+   *  are dropped so a transient fetch failure retries on the next ask. Each
+   *  records whether the work it wraps transferred the layer or read it off
+   *  disk — the memoized entry is shared, so a joining caller reads the flag
+   *  but never claims it. */
+  private readonly inFlight = new Map<string, Promise<ResolvedControllerLayer>>();
 
   constructor(opts: {
     pinnedRef: string;
@@ -165,14 +179,23 @@ export class ModuleArtifact {
    * Returns `undefined` when the artifact ships no layer for this selector, which
    * is how a loader learns to fall through to the next candidate.
    */
-  async materializeController(selector: ArtifactSelector): Promise<MaterializedLayer | undefined> {
+  async materializeController(
+    selector: ArtifactSelector,
+  ): Promise<ResolvedControllerLayer | undefined> {
     const key = selectorKey(selector);
     const layer = this.layers.find(
       (l) => l.role === "controller" && l.selector !== undefined && selectorKey(l.selector) === key,
     );
     if (!layer) return undefined;
-    await this.materializeCommon();
-    return this.materialize(layer);
+    const common = await this.materializeCommonTracked();
+    const controller = await this.materializeTracked(layer);
+    // Either half is a transfer the caller waited on: the common layer's bytes
+    // come down on this call too, so they are as much of a wait as the
+    // controller layer's.
+    return {
+      layer: controller.layer,
+      transferred: controller.transferred || (common?.transferred ?? false),
+    };
   }
 
   /**
@@ -197,8 +220,15 @@ export class ModuleArtifact {
 
   /** Materialize the `common` layer, if the module ships one. */
   async materializeCommon(): Promise<MaterializedLayer | undefined> {
+    return (await this.materializeCommonTracked())?.layer;
+  }
+
+  /** As `materializeCommon`, reporting whether this call transferred it — the
+   *  controller path rides the common layer along and has to count its bytes as
+   *  part of the wait. One lookup, so "common comes too" is encoded once. */
+  private async materializeCommonTracked(): Promise<ResolvedControllerLayer | undefined> {
     const layer = singletonLayer(this.layers, "common");
-    return layer ? this.materialize(layer) : undefined;
+    return layer ? this.materializeTracked(layer) : undefined;
   }
 
   /**
@@ -226,9 +256,21 @@ export class ModuleArtifact {
       .join(", ");
   }
 
-  private materialize(layer: ArtifactLayer): Promise<MaterializedLayer> {
+  private async materialize(layer: ArtifactLayer): Promise<MaterializedLayer> {
+    return (await this.materializeTracked(layer)).layer;
+  }
+
+  /**
+   * As `materialize`, but also reporting whether THIS call transferred the layer.
+   *
+   * A caller that joins work already in flight reports `false`: several
+   * controller candidates of one module share a layer, and attributing the
+   * transfer to all of them would print one progress line per candidate for a
+   * single download. The call that started the work owns the report.
+   */
+  private materializeTracked(layer: ArtifactLayer): Promise<ResolvedControllerLayer> {
     const pending = this.inFlight.get(layer.blob);
-    if (pending) return pending;
+    if (pending) return pending.then((r) => ({ layer: r.layer, transferred: false }));
     const work = this.materializeUncached(layer).catch((err) => {
       // Drop the rejection so a transient fetch failure is retried rather than
       // cached for the lifetime of the module.
@@ -247,10 +289,10 @@ export class ModuleArtifact {
     return path.join(this.dir, `.telo-layer-${layer.role}-${short}`);
   }
 
-  private async materializeUncached(layer: ArtifactLayer): Promise<MaterializedLayer> {
+  private async materializeUncached(layer: ArtifactLayer): Promise<ResolvedControllerLayer> {
     const marker = this.markerPath(layer);
     if (existsSync(marker)) {
-      return { dir: this.dir, files: await readMarker(marker) };
+      return { layer: { dir: this.dir, files: await readMarker(marker) }, transferred: false };
     }
 
     return withDirectoryLock(
@@ -260,7 +302,7 @@ export class ModuleArtifact {
         // Re-check inside the lock: a peer may have extracted this layer between
         // the fast-path miss and our acquisition.
         if (existsSync(marker)) {
-          return { dir: this.dir, files: await readMarker(marker) };
+          return { layer: { dir: this.dir, files: await readMarker(marker) }, transferred: false };
         }
 
         const files = await this.transports.fetchLayer(this.pinnedRef, layer.blob);
@@ -283,7 +325,7 @@ export class ModuleArtifact {
           "telo.layer.role": layer.role,
           "telo.layer.files": written.length,
         });
-        return { dir: this.dir, files: written };
+        return { layer: { dir: this.dir, files: written }, transferred: true };
       },
       this.log,
     );

package/src/controller-loader.ts

@@ -8,10 +8,13 @@ import { ControllerPolicy, DEFAULT_POLICY, POLICY_WILDCARD } from "./runtime-reg
 export type { ControllerPolicy } from "./runtime-registry.js";
 
 /**
- * Which branch the per-scheme loader actually took. Cache/local hits resolve
- * in milliseconds; `npm-install` and `cargo-build` are the only branches that
- * do real (network or compile) work. The CLI uses this to decide whether a
- * "downloading…" line was honest or should be erased.
+ * Which branch the per-scheme loader actually took. Cache/local hits resolve in
+ * milliseconds; `npm-install`, `cargo-build` and `bundle` are the branches that
+ * do real (network or compile) work — `bundle` is reported only when the resolve
+ * fetched the module's controller layer, never when it found it already
+ * extracted. The CLI uses this to decide whether a "downloading…" line was
+ * honest or should be erased, so a source that names work no one waited for
+ * turns every warm start into noise.
  */
 export type ControllerResolveSource =
   | "local"

package/src/controller-loaders/bundle-loader.ts

@@ -220,17 +220,22 @@ export class BundleControllerLoader {
     // fetched here: the artifact handle owns the pinned ref and the verified
     // layer index, so an `oci://` module ref never reaches this loader as a path.
     let bundleDir: string;
+    // What this resolve actually cost. A module already on disk is `local`; an
+    // artifact layer found extracted is `cache`; only a layer this call pulled
+    // down reports `bundle`, the branch that made the user wait.
+    let source: ControllerResolveSource = "local";
     if (artifact) {
       // By its own selector, not by re-matching the host: this candidate IS one
       // selector, and it is exactly the key of the layer that carries it.
-      const layer = await artifact.materializeController(selector);
-      if (!layer) {
+      const resolved = await artifact.materializeController(selector);
+      if (!resolved) {
         throw new ControllerEnvMissingError(
           `pkg:telo controller "${purl}": the module artifact ships no layer for ` +
             `${describeSelector(selector)} (has: ${artifact.describeLayers()})`,
         );
       }
-      bundleDir = layer.dir;
+      bundleDir = resolved.layer.dir;
+      source = resolved.transferred ? "bundle" : "cache";
     } else {
       // No artifact: a module already on disk (local development, or a manifest
       // served from the on-disk cache). Its files sit next to the manifest.
@@ -258,7 +263,7 @@ export class BundleControllerLoader {
 
     const fragment = parsed.subpath;
     return {
-      source: "bundle",
+      source,
       importInstance: async () => {
         // A broken bundle (syntax / failed import) is a real user-code failure —
         // let it propagate rather than masking it as env-missing.

package/src/controller-loaders/npm-loader.ts

@@ -149,7 +149,7 @@ export class NpmControllerLoader {
    * same spec share one `npm install <spec>` invocation rather than each
    * acquiring the fs-lock and reinstalling.
    */
-  private readonly inFlight = new Map<string, Promise<void>>();
+  private readonly inFlight = new Map<string, Promise<boolean>>();
 
   /**
    * Promise that resolves when the install root has been materialized
@@ -264,15 +264,20 @@ export class NpmControllerLoader {
       dependencies[name] = `file:${resolvedPkgRoot}`;
     }
 
-    const packageJson = {
-      name: "telo-runtime-install",
-      private: true,
-      version: "0.0.0",
-      dependencies,
-    };
     const packageJsonPath = path.join(installRoot, "package.json");
     const stateFile = path.join(installRoot, ".telo-state.json");
-    const newHash = sha256(JSON.stringify(packageJson));
+    // Keyed on the realm deps alone — the only part this function owns. The
+    // controller aliases below join the file but never the identity: they are
+    // added one `--save` at a time, so hashing them would make every controller
+    // install invalidate the root and trigger another root install.
+    const newHash = sha256(
+      JSON.stringify({
+        name: "telo-runtime-install",
+        private: true,
+        version: "0.0.0",
+        dependencies,
+      }),
+    );
 
     await fs.mkdir(installRoot, { recursive: true });
 
@@ -301,7 +306,25 @@ export class NpmControllerLoader {
         return;
       }
 
-      await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+      // Rewrite the root's package.json REALM DEPS ONLY, keeping every
+      // controller alias a previous `installPackage --save` recorded. Writing a
+      // fresh file instead drops them, and the install below then prunes their
+      // `node_modules` folders — so a realm change (a different kernel checkout,
+      // e.g. a globally installed CLI and a repo one addressing the same app)
+      // evicted every controller and reinstalled the lot, on every switch.
+      const existingDeps = (await readPackageDeps(installRoot)) ?? {};
+      const merged: Record<string, string> = {
+        ...(await liveControllerDeps(existingDeps, installRoot)),
+        ...dependencies,
+      };
+      await fs.writeFile(
+        packageJsonPath,
+        JSON.stringify(
+          { name: "telo-runtime-install", private: true, version: "0.0.0", dependencies: merged },
+          null,
+          2,
+        ) + "\n",
+      );
       await runPackageManager(installRoot, [
         "install",
         "--no-audit",
@@ -414,8 +437,11 @@ export class NpmControllerLoader {
       }
     }
 
+    // Resolves to whether the package manager actually ran: the re-check below
+    // routinely wins the race, and reporting an install that never happened
+    // makes the CLI print a "downloading…" line nobody waited for.
     const work = (async () => {
-      await withDirectoryLock(installRoot, "controller install", async () => {
+      return withDirectoryLock(installRoot, "controller install", async () => {
         // Re-check inside the lock: a peer process may have installed the
         // spec between the fast-path miss and our acquisition.
         if (kind === "registry") {
@@ -424,7 +450,7 @@ export class NpmControllerLoader {
             installedVersion !== null &&
             (requestedVersion === null || requestedVersion === installedVersion)
           ) {
-            return;
+            return false;
           }
         } else {
           // Normalize the on-disk record to absolute form before comparing —
@@ -436,7 +462,7 @@ export class NpmControllerLoader {
             (await pathExists(targetPath))
           ) {
             this.rootDeps[alias] = lockedSpec;
-            return;
+            return false;
           }
         }
 
@@ -458,16 +484,21 @@ export class NpmControllerLoader {
         const written = await readDepSpec(installRoot, alias);
         if (written !== undefined) this.rootDeps[alias] = written;
         else this.rootDeps[alias] = spec;
+        return true;
       }, this.log);
     })();
 
     this.inFlight.set(cacheKey, work);
+    let installed: boolean;
     try {
-      await work;
+      installed = await work;
     } finally {
       this.inFlight.delete(cacheKey);
     }
     this.installedSpecs.add(cacheKey);
+    // A peer that won the lock had already put the package there, so nothing
+    // was installed — that is a cache hit, whatever the fast path thought.
+    if (!installed) return "cache";
     // First-touch local installs report `local` (silenced in CLI progress);
     // fresh registry installs report `npm-install` (the only branch a
     // user-facing "downloading…" line should ever surface for).
@@ -693,6 +724,37 @@ function normalizeFileSpec(spec: string, installRoot: string): string {
  * Returns null when the file is missing or unreadable; callers decide whether
  * to seed from a synthesized map instead.
  */
+/**
+ * The subset of a root's recorded dependencies still worth carrying into a
+ * rewrite: the package manager has to resolve every entry, so one dead record
+ * fails the whole install.
+ *
+ * Dropped: a `file:` spec whose target no longer exists (the app was run from a
+ * checkout that has since moved, or the app directory was copied without it),
+ * and an alias with no folder in `node_modules`. Both are free to drop —
+ * `installPackage` reinstalls a controller the moment something asks for it —
+ * and keeping them is not: a dangling `file:` dep makes the root install fail
+ * with an ENOENT that names nothing in the manifest, and since the state file is
+ * only written after a successful install, every later run repeats it. This is
+ * also what stops aliases accumulating forever now that the rewrite preserves
+ * them: a version an app has moved off drops out on the next root install.
+ */
+async function liveControllerDeps(
+  deps: Record<string, string>,
+  installRoot: string,
+): Promise<Record<string, string>> {
+  const live: Record<string, string> = {};
+  for (const [name, spec] of Object.entries(deps)) {
+    if (spec.startsWith("file:")) {
+      const target = normalizeFileSpec(spec, installRoot).slice("file:".length);
+      if (!(await pathExists(target))) continue;
+    }
+    if (!(await pathExists(path.join(installRoot, "node_modules", name)))) continue;
+    live[name] = spec;
+  }
+  return live;
+}
+
 async function readPackageDeps(installRoot: string): Promise<Record<string, string> | null> {
   try {
     const text = await fs.readFile(path.join(installRoot, "package.json"), "utf8");

package/src/controllers/resource-definition/resource-inherited-controller.ts

@@ -66,33 +66,89 @@ function resolveRefSlot(value: unknown, ctx: ResourceContext): ResourceInstance
   return instance ?? undefined;
 }
 
-/** Expand a `base:` node against `self`. Self-only CEL resolves to literals now;
- *  a pure `self.<path>` access is navigated directly so live instances pass
- *  through. */
-function expandBaseNode(value: unknown, self: Record<string, unknown>, ctx: EvaluationContext): unknown {
+/** Expand a mapping node against a CEL scope. `self`-only CEL resolves to
+ *  literals now; a pure `self.<path>` access is navigated directly so live
+ *  instances pass through (CEL's output type checker rejects them). Shared by
+ *  `base:` (construction, scope `{ self }`) and the dispatch mappings
+ *  `inputs:` / `result:` (scope `{ self, inputs }` / `{ self, result }`). */
+function expandMappingNode(
+  value: unknown,
+  scope: Record<string, unknown>,
+  ctx: EvaluationContext,
+): unknown {
   if (isCompiledValue(value)) {
     const src = typeof value.source === "string" ? value.source.trim() : "";
     const m = src.match(SELF_PATH);
     if (m) {
-      let cur: unknown = self;
+      let cur: unknown = scope.self;
       for (const key of m[1].split(".").slice(1)) {
         cur = (cur as Record<string, unknown> | undefined)?.[key];
       }
       return cur;
     }
-    return ctx.expandWith(value, { self });
+    return ctx.expandWith(value, scope);
   }
-  if (Array.isArray(value)) return value.map((v) => expandBaseNode(v, self, ctx));
+  if (Array.isArray(value)) return value.map((v) => expandMappingNode(v, scope, ctx));
   if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
     const out: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      out[k] = expandBaseNode(v, self, ctx);
+      out[k] = expandMappingNode(v, scope, ctx);
     }
     return out;
   }
   return value;
 }
 
+/**
+ * Bind the dispatch mappings of a child that REPLACED its inherited contract.
+ *
+ * A contract resolves to the nearest declaration along `extends` and never
+ * merges, so a child declaring `inputType` presents a signature the inherited
+ * controller has never heard of. `inputs:` is the adapter that turns the child's
+ * signature into the parent's call, and `result:` turns the parent's result back
+ * into the child's declared output — the same top-level-sibling factoring a
+ * template definition uses for `invoke:`.
+ *
+ * Bound onto the parent instance rather than wrapping it, so the child still IS
+ * a parent instance: `init`, `snapshot`, `teardown` and status plumbing are
+ * untouched, and nothing new appears in a declared ref slot. It composes with
+ * the kernel's contract binding by position — the parent's contract was bound
+ * when the parent instance was produced, this mapping goes on next, and the
+ * child's own contract is bound outermost by the caller. One dispatch therefore
+ * checks the child's inputs, maps, checks the parent's inputs, runs, checks the
+ * parent's result, maps back, and checks the child's result.
+ */
+function bindDispatchMapping(
+  instance: ResourceInstance,
+  definition: ResourceDefinition,
+  self: Record<string, unknown>,
+  ctx: EvaluationContext,
+): void {
+  const body = definition as unknown as { inputs?: unknown; result?: unknown };
+  const inputsMapping = body.inputs;
+  const resultMapping = body.result;
+  if (inputsMapping == null && resultMapping == null) return;
+  if (typeof instance.invoke !== "function") return;
+
+  // Every argument is forwarded — the mapping rewrites `inputs`, while the
+  // InvokeContext (cancellation, tracing) in later parameters belongs to the
+  // caller and must reach the inherited controller untouched.
+  const original = instance.invoke.bind(instance) as (
+    inputs: any,
+    ...rest: unknown[]
+  ) => Promise<unknown>;
+  instance.invoke = async (inputs: any, ...rest: unknown[]) => {
+    const mappedInputs =
+      inputsMapping != null
+        ? (expandMappingNode(inputsMapping, { self, inputs }, ctx) as Record<string, unknown>)
+        : inputs;
+    const result = await original(mappedInputs, ...rest);
+    return resultMapping != null
+      ? expandMappingNode(resultMapping, { self, result }, ctx)
+      : result;
+  };
+}
+
 /**
  * Controller for a definition that inherits its controller by delegation — it
  * `extends` a concrete kind, declares no own `controllers:` / template body, and
@@ -143,7 +199,7 @@ export function createInheritedController(
       // instances in `self`), minus the reserved keys.
       let parentConfig: Record<string, unknown>;
       if (base != null) {
-        parentConfig = expandBaseNode(base, self, definingContext) as Record<string, unknown>;
+        parentConfig = expandMappingNode(base, { self }, definingContext) as Record<string, unknown>;
       } else {
         const { kind: _kind, metadata: _metadata, name: _name, ...config } = self;
         parentConfig = config;
@@ -159,7 +215,10 @@ export function createInheritedController(
           `Telo.Definition '${definition.metadata.name}': inherited controller requires a ResourceContext host that implements createInheritedInstance().`,
         );
       }
-      return host.createInheritedInstance(definingContext, parentResource);
+      const instance = await host.createInheritedInstance(definingContext, parentResource);
+      if (!instance) return null;
+      bindDispatchMapping(instance, definition, self, definingContext);
+      return instance;
     },
   };
 }

package/src/controllers/type/json-schema-controller.ts

@@ -0,0 +1,114 @@
+import { evaluate } from "@marcbachmann/cel-js";
+import type {
+  ResourceContext,
+  ResourceInstance,
+  ResourceManifest,
+  TypeRule,
+} from "@telorun/sdk";
+import { canonicalTypeSchemaId, mergeTypeSchemas, RuntimeError } from "@telorun/sdk";
+
+/**
+ * `Telo.JsonSchema` — a named data shape.
+ *
+ * It lives in the kernel rather than in an installable module for the same
+ * reason the mandatory log sinks do: declaring a shape is not optional. Every
+ * kind that carries an invocation contract needs one, so requiring an import to
+ * write `inputType:` would tax the exact thing contracts want authors to do —
+ * and a library declaring its own contract would have to import a module purely
+ * to describe itself.
+ *
+ * `type.JsonSchema` is retained as a deprecated alias with the same behaviour, so
+ * published manifests keep resolving.
+ */
+class JsonSchemaType {
+  constructor(
+    private readonly qualifiedName: string,
+    private readonly rules: TypeRule[],
+    /** The fully-resolved (post-`extends`), self-contained JSON Schema. Read by
+     *  consumers that need the effective shape — e.g. a templated resource
+     *  threading `${{ self.model.schema }}` into a request validation schema. */
+    readonly schema: Record<string, unknown>,
+  ) {}
+
+  /**
+   * Validate data against this type's CEL rules — the invariant layer on top of
+   * the schema itself, which AJV enforces through the schema registry.
+   */
+  validateRules(data: unknown): void {
+    for (const rule of this.rules) {
+      let result: unknown;
+      try {
+        result = evaluate(rule.condition, { this: data });
+      } catch (err) {
+        throw new RuntimeError(
+          "ERR_TYPE_VALIDATION_FAILED",
+          `Type "${this.qualifiedName}" rule evaluation failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      if (result !== true) {
+        throw new RuntimeError(
+          rule.code,
+          rule.message ??
+            `Type "${this.qualifiedName}" validation failed: rule "${rule.code}" not satisfied`,
+        );
+      }
+    }
+  }
+}
+
+/** A type resource is pure declaration: it registers a schema and holds the
+ *  resolved shape, implementing none of the lifecycle verbs. `ResourceInstance`
+ *  is entirely optional members, so a class with none of them satisfies it only
+ *  by assertion — the same shape the module-loaded controller had, where the
+ *  dynamic-import boundary erased the type instead of asserting it. */
+export async function create(
+  resource: ResourceManifest,
+  ctx: ResourceContext,
+): Promise<ResourceInstance | null> {
+  const qualifiedName = `${resource.metadata.module}.${resource.metadata.name}`;
+  const ownSchema = resource.schema as Record<string, unknown>;
+
+  let schema: Record<string, unknown> = ownSchema;
+
+  const extendsField = resource.extends as string | string[] | undefined;
+  if (extendsField) {
+    const parents = Array.isArray(extendsField) ? extendsField : [extendsField];
+
+    const parentSchemas: Record<string, unknown>[] = [];
+    for (const parent of parents) {
+      const parentSchema = ctx.lookupSchema(parent);
+      // Defer if any parent schema isn't registered yet (multi-pass resolution).
+      if (!parentSchema) return null;
+      parentSchemas.push(parentSchema as Record<string, unknown>);
+    }
+
+    // Each parent's registered schema is itself already resolved, so merging
+    // them makes inheritance transitive through grandparents with no `$ref`s
+    // left in the result.
+    schema = mergeTypeSchemas([...parentSchemas, ownSchema]);
+  }
+
+  const rules = (Array.isArray(resource.rules) ? resource.rules : []) as TypeRule[];
+
+  ctx.registerSchema(qualifiedName, schema);
+  ctx.registerTypeRules(qualifiedName, rules);
+
+  // Also register under the short name so types can be referenced without a
+  // module prefix.
+  const shortName = resource.metadata.name;
+  if (shortName !== qualifiedName) {
+    ctx.registerSchema(shortName, schema);
+    ctx.registerTypeRules(shortName, rules);
+  }
+
+  // Canonical module-scoped id — the target of `$ref: "telo://Self/<name>"` (and
+  // `telo://<Alias>/<name>` across imports) once the loader resolves the
+  // authority to this module. Authority-free, so a validator can actually
+  // resolve the reference; see `canonicalTypeSchemaId`.
+  const moduleName = resource.metadata.module as string | undefined;
+  if (moduleName) {
+    ctx.registerSchema(canonicalTypeSchemaId(moduleName, shortName), schema);
+  }
+
+  return new JsonSchemaType(qualifiedName, rules, schema) as unknown as ResourceInstance;
+}