@telorun/kernel 0.25.0 → 0.26.1

package/src/controller-loader.ts

@@ -55,6 +55,10 @@ export interface ControllerLoaderOptions {
    * (cargo loader has its own per-crate cache and does not need this).
    */
   entryUrl?: string;
+  /** Explicit npm install root (`<cache-root>/npm`), threaded from the kernel's
+   *  single `resolveCacheRoot`. Overrides the entry-anchored default so a
+   *  relocated `TELO_CACHE_DIR` is honoured. */
+  installRoot?: string;
 }
 
 /**
@@ -82,7 +86,10 @@ export class ControllerLoader {
 
   constructor(options: ControllerLoaderOptions = {}) {
     this.emit = options.emit;
-    this.npmLoader = new NpmControllerLoader({ entryUrl: options.entryUrl });
+    this.npmLoader = new NpmControllerLoader({
+      entryUrl: options.entryUrl,
+      installRoot: options.installRoot,
+    });
     this.napiLoader = new NapiControllerLoader();
     this.bundleLoader = new BundleControllerLoader();
   }

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

@@ -97,6 +97,14 @@ export interface NpmControllerLoaderOptions {
    * `pkg-name` cli command resolves it from its argument.
    */
   entryUrl?: string;
+  /**
+   * Explicit install root, threaded from the kernel's single `resolveCacheRoot`
+   * (`<cache-root>/npm`). When set it overrides the entry-anchored
+   * `computeInstallRoot`, so a relocated `TELO_CACHE_DIR` (e.g. a prebuilt
+   * image baking deps at `/telo-cache`) is honoured without this loader reading
+   * the env itself.
+   */
+  installRoot?: string;
 }
 
 /**
@@ -127,6 +135,8 @@ export interface NpmControllerLoaderOptions {
  */
 export class NpmControllerLoader {
   private readonly entryUrl?: string;
+  /** Threaded install root (`<cache-root>/npm`); overrides `computeInstallRoot`. */
+  private readonly installRootOverride?: string;
 
   /**
    * Per-process cache of "this controller's package + version is already
@@ -164,6 +174,7 @@ export class NpmControllerLoader {
 
   constructor(options: NpmControllerLoaderOptions = {}) {
     this.entryUrl = options.entryUrl;
+    this.installRootOverride = options.installRoot;
   }
 
   async load(purl: string, baseUri: string): Promise<NpmLoadResult> {
@@ -219,7 +230,7 @@ export class NpmControllerLoader {
       );
     }
     const entryUrlStr = this.entryUrl;
-    const installRoot = computeInstallRoot(entryUrlStr);
+    const installRoot = this.installRootOverride ?? computeInstallRoot(entryUrlStr);
 
     // Build the install-root package.json: kernel-runtime deps as `file:` refs
     // pointing at the kernel-side realpath. Modules declare these names as

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

@@ -121,10 +121,22 @@ export async function create(
   // no resources/env/ports in import inputs — is enforced by the analyzer, not here;
   // a `${{ resources.X }}` slipping past analysis (skipValidation / programmatic
   // load) would evaluate at runtime rather than being rejected.
-  const importVariables =
-    (ctx.expandValue(resource.variables, {}) as Record<string, unknown>) ?? {};
-  const importSecrets =
-    (ctx.expandValue(resource.secrets, {}) as Record<string, unknown>) ?? {};
+  // Defaults declared on the library's own `variables` / `secrets` contract fill
+  // any input the importer didn't override — the import-time analogue of the root
+  // Application's env defaulting (`resolveApplicationEnv`). Child modules are
+  // isolated from the host environment, so there is no env lookup here: the value
+  // is the importer's override, else the library default. Without this a contract
+  // var with a default but no override reaches a `${{ variables.X }}` template as
+  // a missing key, even though analysis validated the reference against the
+  // (defaulted) contract.
+  const importVariables = applyDefaults(
+    (ctx.expandValue(resource.variables, {}) as Record<string, unknown>) ?? {},
+    moduleManifest.variables ?? {},
+  );
+  const importSecrets = applyDefaults(
+    (ctx.expandValue(resource.secrets, {}) as Record<string, unknown>) ?? {},
+    moduleManifest.secrets ?? {},
+  );
   const childCtx = new ModuleContext(
     ctx.moduleContext.source,
     importVariables,
@@ -159,6 +171,30 @@ export async function create(
     child.registerManifest(manifest);
   }
 
+  // Initialize the child's resources in dependency order, mirroring the root
+  // context (kernel.boot → setInitOrder). Without this, an imported library's
+  // resources init in registration order, so a dependent can run Phase 5
+  // injection before its dependency exists — e.g. an Http.Api whose inline route
+  // handler is appended after it during inline-resource extraction would init,
+  // and inject, before the handler is created, leaving the handler ref
+  // unresolved. The order is computed in the library's OWN scope (childRegistry),
+  // so an anonymous child resolves against the declaring library, not the
+  // consumer. setInitOrder ignores names it doesn't recognize, so a partial order
+  // is safe. A cycle purely among a library's own resources is invisible to the
+  // root graph (which stops at the import boundary), so this is the only place it
+  // surfaces — throw it the same way the root does rather than silently falling
+  // back to registration order (which would re-manifest as a confusing runtime
+  // ERR_RESOURCE_NOT_INVOKABLE). `prepare` returns null order on a ref-validation
+  // error too (already reported by analyze above); those we leave to fall back.
+  const { order, cycleError } = analyzer.prepare(manifests, childRegistry);
+  if (cycleError) {
+    throw new RuntimeError(
+      "ERR_CIRCULAR_DEPENDENCY",
+      `Circular dependency in imported library '${targetModule}': ${cycleError}`,
+    );
+  }
+  if (order) (child as ModuleContext).setInitOrder(order);
+
   // Link the target module context as a child of the declaring module context in
   // the lifecycle tree. This enables cascading teardown (parent → child order)
   // and makes the import hierarchy visible at runtime.
@@ -251,6 +287,26 @@ export async function create(
   };
 }
 
+/**
+ * Fill in library-declared `default:` values for any input the importer left
+ * unset. Mirrors the root Application's env defaulting: a provided value (incl.
+ * an explicit `null`) wins; otherwise the contract default applies. Returns a new
+ * object — the resolved input map is never mutated in place.
+ */
+function applyDefaults(
+  provided: Record<string, unknown>,
+  schemaDefs: Record<string, any>,
+): Record<string, unknown> {
+  const out = { ...provided };
+  for (const [key, def] of Object.entries(schemaDefs)) {
+    if (typeof def !== "object" || def === null || !("default" in def)) continue;
+    if (out[key] === undefined || out[key] === null) {
+      out[key] = def.default;
+    }
+  }
+  return out;
+}
+
 function validateRequiredInputs(
   schemaDefs: Record<string, any>,
   provided: Record<string, unknown>,

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

@@ -54,6 +54,7 @@ class ResourceDefinition implements ResourceInstance {
     const loader = new ControllerLoader({
       emit: (e) => ctx.emit(e.name, e.payload),
       entryUrl: ctx.getEntryUrl(),
+      installRoot: ctx.getInstallRoot(),
     });
     const controllerInstance = await loader.load(
       this.resource.controllers,

package/src/index.ts

@@ -5,6 +5,7 @@ export { LocalFileSource } from "./manifest-sources/local-file-source.js";
 export {
   LocalManifestCacheSource,
   cachePathForCanonical,
+  resolveCacheRoot,
   resolveEntryDir,
   writeManifestCache,
 } from "./manifest-sources/local-manifest-cache-source.js";

package/src/kernel.ts

@@ -40,7 +40,9 @@ import {
   readAnalysisStamp,
   writeAnalysisStamp,
 } from "./manifest-sources/analysis-stamp.js";
-import { resolveEntryDir } from "./manifest-sources/local-manifest-cache-source.js";
+import {
+  resolveCacheRoot,
+} from "./manifest-sources/local-manifest-cache-source.js";
 import {
   precompileApplicationEnvSchemas,
   precompileDefinitionSchemas,
@@ -169,6 +171,9 @@ export class Kernel implements IKernel {
   private rootContext!: ModuleContext;
   private staticManifests: ResourceManifest[] = [];
   private _entryUrl?: string;
+  /** The `.telo` cache root for this load, resolved once in `load()` and
+   *  threaded to the validator, analysis stamp, and npm install root. */
+  private _cacheRoot?: string | null;
   private _loadedGraph?: LoadedGraph;
   // Lifecycle state — guards boot/runTargets/teardown/invoke transitions.
   // teardown() is the only idempotent method; everything else throws on misuse.
@@ -319,18 +324,32 @@ export class Kernel implements IKernel {
    * session rootfs — hits the stamp and skips the validation walk entirely
    * instead of failing to write the caches on every boot.
    */
-  async load(url: string, options?: { analyzeOnly?: boolean }): Promise<void> {
+  async load(
+    url: string,
+    options?: { analyzeOnly?: boolean; cacheDir?: string | null; writeCache?: boolean },
+  ): Promise<void> {
     const sourceUrl = await this.loader.resolveEntryPoint(url);
     this._entryUrl = sourceUrl;
-    // Point the shared schema validator at the entry-anchored cache so
-    // compiled AJV validators are persisted (standalone CJS) under
-    // `<entry-dir>/.telo/manifests/__validators/`. Memory- or HTTP-rooted
-    // entries skip the cache; their schema compiles stay in-process only.
-    const validatorCacheDir = resolveEntryDir(sourceUrl);
+    // Resolve the `.telo` cache root ONCE and thread it to every consumer
+    // (validators, analysis stamp, npm install root) — no consumer re-derives
+    // it or reads the env independently. A caller (the CLI) may pass `cacheDir`
+    // so the env is read exactly once per invocation; otherwise resolve here.
+    const cacheRoot =
+      options?.cacheDir !== undefined ? options.cacheDir : resolveCacheRoot(sourceUrl);
+    this._cacheRoot = cacheRoot;
+    const manifestsDir = cacheRoot ? `${cacheRoot}/manifests` : undefined;
+    // `writeCache: false` (`telo run --no-cache-write`) keeps the cache
+    // READ-only: compiled validators and the analysis stamp are still loaded
+    // from disk, but never written back — so an ephemeral, read-only session
+    // rootfs validates in-memory without touching the baked cache.
+    const writeCache = options?.writeCache !== false;
+    // Point the shared schema validator at the cache so compiled AJV validators
+    // are loaded (and, when writable, persisted) under
+    // `<cache-root>/manifests/__validators/`. Memory-/HTTP-rooted entries skip
+    // the cache; their schema compiles stay in-process only.
     this.sharedSchemaValidator.setCacheDir(
-      validatorCacheDir
-        ? `${validatorCacheDir}/.telo/manifests/__validators`
-        : undefined,
+      manifestsDir ? `${manifestsDir}/__validators` : undefined,
+      { write: writeCache },
     );
     this.rootContext = new ModuleContext(
       sourceUrl,
@@ -393,9 +412,10 @@ export class Kernel implements IKernel {
     // and inline-resource normalisation still runs — only the diagnostic
     // passes are elided. Memory- / HTTP-rooted entries have no
     // local stamp store and always re-validate.
-    const entryDir = resolveEntryDir(sourceUrl);
     const analysisSignature = computeAnalysisSignature(analysisGraph);
-    const stamp = entryDir ? await readAnalysisStamp(entryDir) : undefined;
+    const stamp = manifestsDir
+      ? await readAnalysisStamp("", manifestsDir)
+      : undefined;
     const skipValidation = stamp?.signature === analysisSignature;
     const errors = this.analyzer.analyzeErrors(
       staticManifests,
@@ -416,13 +436,13 @@ export class Kernel implements IKernel {
         })),
       );
     }
-    if (entryDir && !skipValidation) {
+    if (manifestsDir && writeCache && !skipValidation) {
       // Best-effort: stamp the verdict so subsequent loads hit the fast
       // path. A read-only filesystem (baked Docker image) reports the
       // failure on stderr and keeps running — the lookup above will
-      // simply miss next time.
+      // simply miss next time. Skipped under `--no-cache-write`.
       try {
-        await writeAnalysisStamp(entryDir, analysisSignature);
+        await writeAnalysisStamp("", analysisSignature, manifestsDir);
       } catch (err) {
         this.stderr.write(
           `[telo:kernel] analysis stamp write failed: ${err instanceof Error ? err.message : String(err)}\n`,
@@ -744,6 +764,12 @@ export class Kernel implements IKernel {
     return this._entryUrl;
   }
 
+  /** The npm install root for this load (`<cache-root>/npm`), threaded to the
+   *  controller loader so it doesn't re-derive it from the entry URL. */
+  getInstallRoot(): string | undefined {
+    return this._cacheRoot ? `${this._cacheRoot}/npm` : undefined;
+  }
+
   /** 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/analysis-stamp.ts

@@ -136,9 +136,13 @@ export function computeAnalysisSignature(graph: LoadedGraph): string {
  *  reading a newer stamp (or vice versa) discard rather than misparse. */
 export async function readAnalysisStamp(
   entryDir: string,
+  manifestsDir?: string,
 ): Promise<AnalysisStamp | undefined> {
+  const stampPath = manifestsDir
+    ? path.join(manifestsDir, ".validated.json")
+    : path.join(entryDir, ANALYSIS_STAMP_FILE);
   try {
-    const text = await fs.readFile(path.join(entryDir, ANALYSIS_STAMP_FILE), "utf-8");
+    const text = await fs.readFile(stampPath, "utf-8");
     const parsed = JSON.parse(text) as Partial<AnalysisStamp>;
     if (
       parsed?.version === ANALYSIS_STAMP_FORMAT_VERSION &&
@@ -158,12 +162,15 @@ export async function readAnalysisStamp(
 export async function writeAnalysisStamp(
   entryDir: string,
   signature: string,
+  manifestsDir?: string,
 ): Promise<void> {
   const stamp: AnalysisStamp = {
     version: ANALYSIS_STAMP_FORMAT_VERSION,
     signature,
   };
-  const target = path.join(entryDir, ANALYSIS_STAMP_FILE);
+  const target = manifestsDir
+    ? path.join(manifestsDir, ".validated.json")
+    : path.join(entryDir, ANALYSIS_STAMP_FILE);
   await fs.mkdir(path.dirname(target), { recursive: true });
   await fs.writeFile(target, JSON.stringify(stamp), "utf-8");
 }

package/src/manifest-sources/local-manifest-cache-source.ts

@@ -133,8 +133,15 @@ export class LocalManifestCacheSource implements ManifestSource {
   private readonly cacheRoot: string;
   private readonly registryUrl: string;
 
-  constructor(entryDir: string, registryUrl: string = DEFAULT_REGISTRY_URL) {
-    this.cacheRoot = path.join(entryDir, CACHE_SUBDIR);
+  constructor(
+    entryDir: string,
+    registryUrl: string = DEFAULT_REGISTRY_URL,
+    manifestsDir?: string,
+  ) {
+    // `manifestsDir` is the resolved manifest-cache directory threaded from a
+    // single `resolveCacheRoot` (honours `TELO_CACHE_DIR`); when absent we fall
+    // back to the entry-anchored default so library/test callers are unchanged.
+    this.cacheRoot = manifestsDir ?? path.join(entryDir, CACHE_SUBDIR);
     this.registryUrl = registryUrl;
   }
 
@@ -189,8 +196,9 @@ export function cachePathForCanonical(
   canonicalSource: string,
   entryDir: string,
   registryUrl: string,
+  manifestsDir?: string,
 ): string | null {
-  const cacheRoot = path.join(entryDir, CACHE_SUBDIR);
+  const cacheRoot = manifestsDir ?? path.join(entryDir, CACHE_SUBDIR);
   return cachePathForUrl(canonicalSource, cacheRoot, registryUrl);
 }
 
@@ -210,6 +218,7 @@ export async function writeManifestCache(
   graph: LoadedGraph,
   entryDir: string,
   registryUrl: string = DEFAULT_REGISTRY_URL,
+  manifestsDir?: string,
 ): Promise<string[]> {
   const written: string[] = [];
   const seen = new Set<string>();
@@ -220,7 +229,7 @@ export async function writeManifestCache(
       if (seen.has(file.source)) continue;
       seen.add(file.source);
 
-      const target = cachePathForCanonical(file.source, entryDir, registryUrl);
+      const target = cachePathForCanonical(file.source, entryDir, registryUrl, manifestsDir);
       if (!target) continue;
 
       await fs.mkdir(path.dirname(target), { recursive: true });
@@ -254,3 +263,19 @@ export function resolveEntryDir(entryPath: string): string | null {
     return path.dirname(absolute);
   }
 }
+
+/** The single `.telo` cache root for an entry, resolved once and threaded to
+ *  every consumer (manifest cache, compiled validators, analysis stamp, npm
+ *  install root) so none of them re-derive it or read the env independently.
+ *
+ *  `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).
+ *  Consumers append the conventional subdirs: `manifests/`, `manifests/__validators/`,
+ *  `npm/`. */
+export function resolveCacheRoot(entryPath: string): string | null {
+  const override = process.env.TELO_CACHE_DIR;
+  if (override && override.trim()) return path.resolve(override.trim());
+  const entryDir = resolveEntryDir(entryPath);
+  return entryDir ? path.join(entryDir, ".telo") : null;
+}

package/src/resource-context.ts

@@ -344,6 +344,10 @@ export class ResourceContextImpl implements ResourceContext {
     return this.kernel.getEntryUrl();
   }
 
+  getInstallRoot(): string | undefined {
+    return this.kernel.getInstallRoot();
+  }
+
   on(event: string, handler: (payload?: any) => void | Promise<void>): void {
     this.kernel.on(event, handler);
   }

package/src/schema-validator.ts

@@ -117,6 +117,11 @@ export class SchemaValidator {
   private rawSchemas = new Map<string, object>();
   private compiledValidators = new WeakMap<object, DataValidator>();
   private cacheDir: string | undefined;
+  /** When false, the disk cache is read-only: compiled validators are still
+   *  loaded from `cacheDir` but never written back. `telo run --no-cache-write`
+   *  sets this so an ephemeral, read-only session rootfs validates in-memory
+   *  without touching (or failing to write) the baked cache. */
+  private cacheWritable = true;
   /** Tracks (schema-hash → in-memory compiled validator) so two distinct
    *  but content-equal schema objects share one compile across the kernel
    *  process — `compiledValidators` is keyed by object identity and would
@@ -183,8 +188,9 @@ export class SchemaValidator {
    *  kernel anchors this under `<entry-dir>/.telo/manifests/__validators/`
    *  so it lives next to the manifest cache and rides along in
    *  `COPY --from=build /srv /srv` Docker images. */
-  setCacheDir(dir: string | undefined): void {
+  setCacheDir(dir: string | undefined, opts?: { write?: boolean }): void {
     this.cacheDir = dir;
+    this.cacheWritable = opts?.write ?? true;
   }
 
   compile(schema: any): DataValidator {
@@ -315,7 +321,7 @@ export class SchemaValidator {
     }
 
     const validate = this.ajv.compile(schema) as ValidateFunction;
-    if (cacheDir) {
+    if (cacheDir && this.cacheWritable) {
       try {
         const body = standaloneCode(this.ajv, validate);
         const integrity = createHash("sha256").update(body).digest("hex");