@telorun/kernel 0.75.0 → 0.76.0

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

@@ -15,6 +15,7 @@ import {
   type DefResolver,
 } from "@telorun/analyzer";
 import type { ModuleArtifact } from "../../bundle/module-artifact.js";
+import type { SiblingLibraryMap } from "../../controller-loaders/sibling-libraries.js";
 import { ControllerLoader } from "../../controller-loader.js";
 import { formatAjvErrors, validateResourceDefinition } from "../../manifest-schemas.js";
 import { createTemplateController } from "./resource-template-controller.js";
@@ -166,6 +167,10 @@ class ResourceDefinition implements ResourceInstance {
     // ref and the verified layer index, so the loader picks a candidate and asks
     // it for that selector's directory rather than fetching anything itself.
     const artifact = host.getModuleArtifact?.(this.resource.metadata.source);
+    // The libraries of the module that declared this kind, for the same reason:
+    // a bundle's bare `@telorun/kv-store` means whatever THAT module's imports
+    // say it means, never the consumer's.
+    const libraries = host.getSiblingLibraries?.(this.resource.metadata.source);
     ctx.registerDefinition(this.resource);
 
     const moduleName = this.resource.metadata.module;
@@ -187,7 +192,7 @@ class ResourceDefinition implements ResourceInstance {
       kindName,
       async () => {
         const resolved = await loader
-          .resolve(controllers, source, policy, artifact)
+          .resolve(controllers, source, policy, artifact, libraries)
           .catch((err) => {
             if (err instanceof RuntimeError) {
               throw new RuntimeError(err.code, `kind '${moduleName}.${kindName}': ${err.message}`);
@@ -229,6 +234,7 @@ class ResourceDefinition implements ResourceInstance {
  */
 interface KernelResourceContext {
   getModuleArtifact?(source: string | undefined): ModuleArtifact | undefined;
+  getSiblingLibraries?(source: string | undefined): SiblingLibraryMap | undefined;
   getCacheRoot?(): string | undefined;
   registerLazyController(
     moduleName: string,

package/src/index.ts

@@ -39,6 +39,7 @@ export {
   buildControllerBundle,
   canBuildFromSource,
   lastBuildInputs,
+  type SiblingLibrary,
 } from "./controller-loaders/source-bundle-builder.js";
 export type {
   PayloadLayer,

package/src/kernel.ts

@@ -64,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,
@@ -159,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.
@@ -1014,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
@@ -1038,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
@@ -1067,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-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/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.