@telorun/kernel 0.74.0 → 0.76.0

package/src/kernel.ts

@@ -1,5 +1,6 @@
 import {
   AnalysisRegistry,
+  authoredModuleMetadata,
   buildEvalPaths,
   collectZoneModuleDocuments,
   flattenForAnalyzer,
@@ -63,12 +64,17 @@ import {
   resolveCacheRoot,
   resolveEntryDir,
 } from "./manifest-sources/local-manifest-cache-source.js";
-import { readOwnerManifest } from "./bundle/module-manifest.js";
+import { readOwnerManifest, type OwnerManifest } from "./bundle/module-manifest.js";
 import {
   moduleArtifactFor,
   moduleDirectoryFor,
   type ModuleArtifact,
 } from "./bundle/module-artifact.js";
+import {
+  NO_SIBLING_LIBRARIES,
+  buildSiblingLibraries,
+  type SiblingLibraryMap,
+} from "./controller-loaders/sibling-libraries.js";
 import { defaultTransportRegistry } from "./transports/transport-registry.js";
 import {
   collectDeclaredEnvKeys,
@@ -158,6 +164,10 @@ export class Kernel implements IKernel {
   /** Per-module artifact handles, keyed by canonical manifest source. Rebuilt on
    *  every `load()`; empty for a graph of purely local / manifest-only modules. */
   private readonly moduleArtifacts = new Map<string, ModuleArtifact>();
+  /** Per-module sibling-library resolution, keyed by the same canonical manifest
+   *  source: which bare specifiers this module's controller bundles import, and
+   *  which module's library layer each resolves to. Rebuilt on every `load()`. */
+  private readonly siblingLibraries = new Map<string, SiblingLibraryMap>();
   private _loadedGraph?: LoadedGraph;
   // Lifecycle state — guards boot/runTargets/teardown/invoke transitions.
   // teardown() is the only idempotent method; everything else throws on misuse.
@@ -689,6 +699,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;
@@ -1005,7 +1023,9 @@ export class Kernel implements IKernel {
   }
 
   /**
-   * Build one {@link ModuleArtifact} per loaded module that ships a payload.
+   * Read every loaded module's owner manifest once, and build from it the two
+   * things a controller resolution needs: the module's artifact, and the sibling
+   * libraries its bundles import by bare specifier.
    *
    * Here, and not inside a controller loader, because this is the only point
    * where both halves are in hand: the **pinned** ref the importer wrote
@@ -1029,26 +1049,48 @@ export class Kernel implements IKernel {
    */
   private buildModuleArtifacts(graph: LoadedGraph, manifestsDir: string | undefined): void {
     this.moduleArtifacts.clear();
+    this.siblingLibraries.clear();
     const transports = defaultTransportRegistry(this.registryUrl);
     const entryDir = this._entryUrl ? resolveEntryDir(this._entryUrl) ?? "" : "";
+    // Parsed once per module and shared with the sibling-library join below: a
+    // `telo.yaml` is a large multi-document file, and re-reading each target's
+    // once per import edge put dozens of redundant full-YAML parses on the boot
+    // path of every standard-library app.
+    const owners = new Map<string, OwnerManifest>();
+    const directories = new Map<string, string | undefined>();
     for (const [, module] of graph.modules) {
       const file = module.owner;
-      if (this.moduleArtifacts.has(file.source)) continue;
+      if (owners.has(file.source)) continue;
+      const owner = readOwnerManifest(file.text);
+      owners.set(file.source, owner);
+      const moduleDir = moduleDirectoryFor(
+        file.requestedUrl,
+        file.source,
+        entryDir,
+        this.registryUrl,
+        manifestsDir,
+      );
+      directories.set(file.source, moduleDir ?? undefined);
       const artifact = moduleArtifactFor({
         pinnedRef: file.requestedUrl,
-        layers: readOwnerManifest(file.text).layers,
-        moduleDir: moduleDirectoryFor(
-          file.requestedUrl,
-          file.source,
-          entryDir,
-          this.registryUrl,
-          manifestsDir,
-        ),
+        layers: owner.layers,
+        moduleDir,
         transports,
         log: this.logging.kernelLogger(),
       });
       if (artifact) this.moduleArtifacts.set(file.source, artifact);
     }
+
+    // The sibling-library join is a pure function of the graph and these three
+    // lookups; it lives beside the model it produces (`sibling-libraries.ts`).
+    for (const [source, map] of buildSiblingLibraries(graph, {
+      ownerManifests: owners,
+      artifactFor: (source) => this.moduleArtifacts.get(source),
+      directoryFor: (source) => directories.get(source),
+      log: this.logging.kernelLogger(),
+    })) {
+      this.siblingLibraries.set(source, map);
+    }
   }
 
   /** The artifact of the module whose manifest resolved from `source`, or
@@ -1058,6 +1100,12 @@ export class Kernel implements IKernel {
     return source ? this.moduleArtifacts.get(source) : undefined;
   }
 
+  /** The module-owned libraries the module at `source` imports by bare
+   *  specifier. Empty for a module that imports none. */
+  getSiblingLibraries(source: string | undefined): SiblingLibraryMap {
+    return (source ? this.siblingLibraries.get(source) : undefined) ?? NO_SIBLING_LIBRARIES;
+  }
+
   /** Authored `kind` of a declared resource by name, from the static manifest
    *  set. Init-order-independent (unlike `resourceInstances`), so a controller
    *  resolving a `!ref <name>` sentinel before the target initializes can still

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/manifest-sources/local-manifest-cache-source.ts

@@ -179,13 +179,29 @@ export async function writeManifestCache(
   return written;
 }
 
+/** Matches a URL scheme, as distinct from a Windows drive letter. `D:\src`
+ *  satisfies RFC 3986's scheme grammar, so the second character is required:
+ *  no registered scheme is one letter, and every drive is. */
+const URL_SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]+:/;
+
 /** Resolve the entry-anchor directory for the manifest cache.
  *
  * For a file path or `file://` URL: returns the containing directory.
  * For a directory path: returns the directory itself.
- * For an HTTP(S) URL: returns `null` (no local anchor; cache writes skipped). */
+ * For ANY other scheme: returns `null` (no local anchor; cache writes skipped).
+ *
+ * The rule is the scheme, not a list of known ones. Testing only for http(s)
+ * left every other scheme falling through to `path.resolve`, which reads it as
+ * a relative path: a `memory://app/telo.yaml` entry anchored its cache at
+ * `<cwd>/memory:/app/.telo`. On POSIX that is a legal directory name, so the
+ * kernel silently created one inside whatever directory it was run from and the
+ * cache appeared to work; on Windows `:` is illegal in a filename, so the same
+ * load failed at `mkdir`. A transient source has no local anchor by
+ * construction — that is what the whole-scheme test says, and it now covers
+ * `oci://` and any scheme added later without another edit here. */
 export function resolveEntryDir(entryPath: string): string | null {
-  if (entryPath.startsWith("http://") || entryPath.startsWith("https://")) {
+  const scheme = URL_SCHEME.exec(entryPath)?.[0];
+  if (scheme !== undefined && scheme !== "file:") {
     return null;
   }
   let absolute: string;
@@ -208,7 +224,8 @@ export function resolveEntryDir(entryPath: string): string | null {
  *
  *  `TELO_CACHE_DIR` (the relocated root a prebuilt image bakes its deps into)
  *  wins; otherwise the root sits beside the entry at `<entry-dir>/.telo`.
- *  Returns `null` for http(s) entries with no local anchor (disk cache skipped).
+ *  Returns `null` for an entry with no local anchor — an http(s), `memory://`
+ *  or any other non-`file:` scheme — in which case the disk cache is skipped.
  *  Consumers append the conventional subdirs: `manifests/`, `manifests/__validators/`,
  *  `npm/`. */
 export function resolveCacheRoot(entryPath: string): string | null {

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/resource-context.ts

@@ -35,6 +35,7 @@ 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 type { SiblingLibraryMap } from "./controller-loaders/sibling-libraries.js";
 import { resolveModuleFileUri } from "./module-file-resolution.js";
 import { hostEnv } from "./host-env.js";
 import type { LoggingHost } from "./logging/logging-host.js";
@@ -781,6 +782,13 @@ export class ResourceContextImpl implements ResourceContext {
     return this.kernel.getModuleArtifact(source);
   }
 
+  /** The module-owned libraries the module at `source` imports by bare specifier
+   *  — how a controller bundle's `@telorun/kv-store` finds the module that owns
+   *  it. Kernel-only, on the same seam as {@link getModuleArtifact}. */
+  getSiblingLibraries(source: string | undefined): SiblingLibraryMap {
+    return this.kernel.getSiblingLibraries(source);
+  }
+
   /**
    * Resolve a module-relative reference against the declaring module's own
    * directory, materializing the layers that could carry it on first use.

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;