@telorun/kernel 0.24.2 → 0.26.0

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,8 +40,14 @@ import {
   readAnalysisStamp,
   writeAnalysisStamp,
 } from "./manifest-sources/analysis-stamp.js";
-import { resolveEntryDir } from "./manifest-sources/local-manifest-cache-source.js";
-import { precompileApplicationEnvSchemas, resolveApplicationEnv } from "./application-env.js";
+import {
+  resolveCacheRoot,
+} from "./manifest-sources/local-manifest-cache-source.js";
+import {
+  precompileApplicationEnvSchemas,
+  precompileDefinitionSchemas,
+  resolveApplicationEnv,
+} from "./application-env.js";
 import { policyFingerprint } from "./runtime-registry.js";
 import { SchemaValidator } from "./schema-validator.js";
 
@@ -165,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.
@@ -315,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,
@@ -389,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,
@@ -412,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`,
@@ -441,6 +465,25 @@ export class Kernel implements IKernel {
           this.sharedSchemaValidator,
         );
       }
+      // Bake the per-kind resource-config validators too. `_createInstance`
+      // compiles `controller.schema` (which falls back to the definition's own
+      // `schema`) for every resource at runtime — work this analyze-only pass
+      // otherwise skips because it stops before instantiation, leaving the
+      // runtime to recompile and fail to persist them on a read-only image.
+      // Pre-compiling every `Telo.Definition` schema here writes them into the
+      // same content-addressed `__validators/` cache the runtime reads.
+      precompileDefinitionSchemas(staticManifests, this.sharedSchemaValidator);
+      // Framework/builtin controller schemas (`Telo.Import`, `Telo.Definition`,
+      // the module controller, …) aren't in the static manifests but are
+      // validated per-resource at runtime just the same. They're registered by
+      // `loadBuiltinDefinitions` above, so bake them from the registry.
+      precompileDefinitionSchemas(
+        this.controllers.getControllerSchemas().map((schema) => ({
+          kind: "Telo.Definition",
+          schema,
+        })),
+        this.sharedSchemaValidator,
+      );
       return;
     }
 
@@ -721,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/module-context.ts

@@ -103,15 +103,41 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   /** Maps import alias → its child context's exported instances. Registered by the
    *  Telo.Import controller; read when resolving a cross-module `!ref Alias.name`
    *  reference (Phase 5 injection and boot targets). `names` is the import's
-   *  `exports.resources` gate — only listed instances are reachable. */
+   *  `exports.resources` gate — only listed instances are reachable. `terminal`
+   *  returns the child's pre-flattened terminal getter for a name (a closure that
+   *  points directly at the OWNING context's instance, however many re-export hops
+   *  away), so resolution stays O(1) regardless of re-export depth. */
   private readonly importedScopes = new Map<
     string,
     {
       names: Set<string>;
-      get: (name: string) => { kind: string; instance: ResourceInstance } | undefined;
+      terminal: (
+        name: string,
+      ) => (() => { kind: string; instance: ResourceInstance } | undefined) | undefined;
     }
   >();
 
+  /** This module's flattened export table: export name → terminal getter. A local
+   *  export's getter reads this context's own `resourceInstances`; a re-export
+   *  (`!ref Alias.name`) holds the SAME closure object as the owner's entry, copied
+   *  by reference at build time so depth adds no resolution hops. Built once by the
+   *  Telo.Import controller after this module's own imports have initialized. */
+  private readonly exportedGetters = new Map<
+    string,
+    () => { kind: string; instance: ResourceInstance } | undefined
+  >();
+
+  /** This module's flattened exported-KIND table: exported kind suffix → canonical
+   *  `<owningModule>.<Kind>`. A local exported kind maps to `<thisModule>.<Kind>`; a
+   *  re-export (`exports.kinds: [Alias.Kind]`) copies the source import's already-canonical
+   *  string, so depth adds no resolution hops. Built by `buildExportTable`. */
+  private readonly exportedKinds = new Map<string, string>();
+
+  /** Maps import alias → a resolver into that import's exported-kind table. Registered by the
+   *  Telo.Import controller; consulted by `resolveKind` so an imported library's kinds — local
+   *  OR transitively re-exported — resolve to their true owning module in O(1). */
+  private readonly importedKindResolvers = new Map<string, (suffix: string) => string | undefined>();
+
   /**
    * Resolved controller-selection policy for this module's `Telo.Definition`s.
    * Stamped by the parent `Telo.Import` controller from the import's `runtime:`
@@ -202,24 +228,127 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   }
 
   /** Register an import alias's exported instances for cross-module reference resolution.
-   *  `names` is the gate (the import's `exports.resources`); `get` reads the child context's
-   *  live instance + its canonical kind lazily — they exist only after the import's `init()`
-   *  runs. */
+   *  `names` is the gate (the import's `exports.resources`); `terminal` returns the child
+   *  context's pre-flattened terminal getter for a name (existing only after the import's
+   *  `init()` built the child's export table). */
   registerImportedScope(
     alias: string,
     names: string[],
-    get: (name: string) => { kind: string; instance: ResourceInstance } | undefined,
+    terminal: (
+      name: string,
+    ) => (() => { kind: string; instance: ResourceInstance } | undefined) | undefined,
   ): void {
-    this.importedScopes.set(alias, { names: new Set(names), get });
+    this.importedScopes.set(alias, { names: new Set(names), terminal });
+  }
+
+  /** This module's terminal getter for an exported `name`, or undefined. Read by a parent
+   *  import building its own (re-)export table — copying this closure by reference flattens
+   *  the chain so resolution never walks hops. */
+  getTerminalExport(
+    name: string,
+  ): (() => { kind: string; instance: ResourceInstance } | undefined) | undefined {
+    return this.exportedGetters.get(name);
+  }
+
+  /** O(1) resolution of an exported instance owned or re-exported by this module. */
+  getExported(name: string): { kind: string; instance: ResourceInstance } | undefined {
+    return this.exportedGetters.get(name)?.();
+  }
+
+  /** Register an import alias's exported-kind resolver (the child's `getExportedKind`). */
+  registerImportedKindScope(alias: string, resolve: (suffix: string) => string | undefined): void {
+    this.importedKindResolvers.set(alias, resolve);
+  }
+
+  /** This module's canonical kind for an exported suffix (local or re-exported), or undefined. */
+  getExportedKind(suffix: string): string | undefined {
+    return this.exportedKinds.get(suffix);
+  }
+
+  /** Build this module's flattened export tables from `exports.resources` / `exports.kinds`.
+   *  A resource entry is a local export (no alias) or a re-export `Alias.Name` (alias set); a
+   *  kind entry is a local kind (no alias) or a re-export `Alias.Kind` (alias set). A local
+   *  export gets a fresh terminal getter / `<module>.<Kind>` canonical; a re-export copies the
+   *  source import's terminal getter / already-canonical kind by reference, collapsing the chain
+   *  to a single hop. Called once by the Telo.Import controller after this module's own imports
+   *  have initialized (leaves-first), so re-export sources are already registered — an
+   *  unresolvable re-export is therefore a permanent misconfiguration and throws here. */
+  buildExportTable(
+    entries: ReadonlyArray<{ name: string; alias?: string }>,
+    kindEntries: ReadonlyArray<{ name: string; alias?: string }>,
+    moduleName: string,
+  ): void {
+    for (const entry of entries) {
+      const name = entry.name;
+      if (entry.alias && entry.alias !== "Self") {
+        // A re-export resolves against this module's own imports, which have all initialized
+        // by now (leaves-first) — so an unresolved source is a permanent misconfiguration, not
+        // a transient miss. Surface it instead of silently dropping the export.
+        const scope = this.importedScopes.get(entry.alias);
+        if (!scope) {
+          throw new RuntimeError(
+            "ERR_INVALID_REEXPORT",
+            `Library '${moduleName}' re-exports '${entry.alias}.${name}' but declares no import ` +
+              `aliased '${entry.alias}'. Add it to this library's 'imports', or remove the ` +
+              `'exports.resources' entry.`,
+          );
+        }
+        const terminal = scope.terminal(name);
+        if (!terminal) {
+          throw new RuntimeError(
+            "ERR_INVALID_REEXPORT",
+            `Library '${moduleName}' re-exports '${entry.alias}.${name}', but the imported ` +
+              `library '${entry.alias}' exports no instance named '${name}'.`,
+          );
+        }
+        this.exportedGetters.set(name, terminal);
+        continue;
+      }
+      this.exportedGetters.set(name, () => {
+        const inst = this.resourceInstances.get(name);
+        if (!inst) return undefined;
+        // Canonicalize the authored kind to `<module>.<Kind>` so the cross-module ref shape
+        // and event naming are scope-independent (matches resolve-ref-sentinels.ts).
+        const rawKind = inst.resource.kind as string;
+        const kind = rawKind.startsWith("Self.")
+          ? `${moduleName}.${rawKind.slice("Self.".length)}`
+          : rawKind;
+        return { kind, instance: inst.instance };
+      });
+    }
+    for (const k of kindEntries) {
+      if (k.alias && k.alias !== "Self") {
+        const resolver = this.importedKindResolvers.get(k.alias);
+        if (!resolver) {
+          throw new RuntimeError(
+            "ERR_INVALID_REEXPORT",
+            `Library '${moduleName}' re-exports kind '${k.alias}.${k.name}' but declares no ` +
+              `import aliased '${k.alias}'. Add it to this library's 'imports', or remove the ` +
+              `'exports.kinds' entry.`,
+          );
+        }
+        const canonical = resolver(k.name);
+        if (!canonical) {
+          throw new RuntimeError(
+            "ERR_INVALID_REEXPORT",
+            `Library '${moduleName}' re-exports kind '${k.alias}.${k.name}', but the imported ` +
+              `library '${k.alias}' exports no kind named '${k.name}'.`,
+          );
+        }
+        this.exportedKinds.set(k.name, canonical);
+        continue;
+      }
+      this.exportedKinds.set(k.name, `${moduleName}.${k.name}`);
+    }
   }
 
   /** Resolve `Alias.name` to a live exported instance, gated by `exports.resources`.
    *  Returns undefined when the alias is unknown, the name isn't exported, or the import
-   *  hasn't initialized its instances yet (the injection path defers and retries). */
+   *  hasn't built its export table yet (the injection path defers and retries). O(1). */
   override resolveImportedInstance(alias: string, name: string): ResourceInstance | undefined {
     const scope = this.importedScopes.get(alias);
     if (!scope || !scope.names.has(name)) return undefined;
-    return scope.get(name)?.instance;
+    return scope.terminal(name)?.()?.instance;
   }
 
   /** Like `resolveImportedInstance`, but returns the `{kind, name}` ref (canonical kind)
@@ -228,7 +357,7 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   resolveImportedRef(alias: string, name: string): { kind: string; name: string } | undefined {
     const scope = this.importedScopes.get(alias);
     if (!scope || !scope.names.has(name)) return undefined;
-    const entry = scope.get(name);
+    const entry = scope.terminal(name)?.();
     return entry ? { kind: entry.kind, name } : undefined;
   }
 
@@ -292,6 +421,14 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
           `Exported kinds: ${[...allowed].join(", ")}`,
       );
     }
+    // Re-export override: if this import's exported-kind table maps the suffix to a DIFFERENT
+    // owning module, the kind is transitively re-exported (`exports.kinds: [Alias.Kind]`) —
+    // resolve to its true owner. A local kind maps to `${realModule}.${suffix}` (no override),
+    // and a module without `exports.kinds` has an empty table (unrestricted, unchanged). Built
+    // deferred, so before the import inits this returns the un-overridden kind, whose controller
+    // miss makes the init loop retry until the table is ready.
+    const reExported = this.importedKindResolvers.get(prefix)?.(suffix);
+    if (reExported && reExported !== `${realModule}.${suffix}`) return reExported;
     return `${realModule}.${suffix}`;
   }
 
@@ -363,7 +500,12 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
         await this.run(target, ctx);
         continue;
       }
-      if ("invoke" in target && target.invoke !== undefined) {
+      // A bare `!ref Alias.name` boot target is Phase-5-injected into the live
+      // instance, which for a Run.Sequence exposes both `run()` and `invoke()`.
+      // Guard against treating such an instance as an authored inline-invoke
+      // 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) {
         const step: InvokeStep = {
           name: target.name ?? `Target${i}`,
           when: target.when,

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

@@ -1,5 +1,5 @@
 import { evaluate } from "@marcbachmann/cel-js";
-import { DataValidator, RuntimeError, TypeRule } from "@telorun/sdk";
+import { DataValidator, isCompiledValue, RuntimeError, TypeRule } from "@telorun/sdk";
 import AjvModule, { type ValidateFunction } from "ajv";
 import standaloneCodeMod from "ajv/dist/standalone/index.js";
 import addFormats from "ajv-formats";
@@ -8,7 +8,7 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { formatAjvErrors } from "./manifest-schemas.js";
-import { ManifestRootSchema, normalizeRefSlots } from "@telorun/templating";
+import { isTaggedSentinel, ManifestRootSchema, normalizeRefSlots } from "@telorun/templating";
 
 const Ajv = AjvModule.default ?? AjvModule;
 // AJV's standalone subpath is CJS — the default export shows up as either
@@ -78,12 +78,50 @@ function verifyAndExtractBody(text: string): string | null {
   return actual === match[1] ? body : null;
 }
 
+/** Deep-clone `value` collapsing every CEL/template sentinel to its original
+ *  `source` string, for use as the validator cache *key* only.
+ *
+ *  The same `Telo.Definition` schema reaches `compile()` in two forms: the
+ *  build-time validator warm feeds the raw analysis graph (parse-time
+ *  `{__tagged, engine, source}` sentinels, or plain `${{ }}` strings for inline
+ *  templates), while the runtime feeds the compile-loader output (`{__compiled,
+ *  source, parts}`). A `!cel` / `!sql` tag embedded anywhere in a schema — most
+ *  commonly inside `examples` / `description`, but the loader rewrites them at
+ *  any position — therefore serialises differently between the two, so without
+ *  normalisation the same kind hashes differently and the runtime misses the
+ *  warmed cache (and fails to persist it read-only). Both sentinel shapes carry
+ *  the same original `source`, so collapsing each to that string converges them.
+ *
+ *  This rewrites only the hash key — AJV still compiles the full `injected`
+ *  schema. Unlike dropping keys by name, it never removes a structural node, so
+ *  a property literally named `description` / `examples` keeps its schema in the
+ *  key and two genuinely different shapes never collide. */
+function normalizeSentinelsForHash(value: unknown): unknown {
+  if (isCompiledValue(value) || isTaggedSentinel(value)) {
+    return typeof value.source === "string" ? value.source : { __teloSentinel: true };
+  }
+  if (Array.isArray(value)) return value.map(normalizeSentinelsForHash);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = normalizeSentinelsForHash(v);
+    }
+    return out;
+  }
+  return value;
+}
+
 export class SchemaValidator {
   private ajv: InstanceType<typeof Ajv>;
   private typeRules = new Map<string, TypeRule[]>();
   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
@@ -150,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 {
@@ -194,7 +233,12 @@ export class SchemaValidator {
     const injected = normalizeRefSlots(withImplicit) as typeof withImplicit;
 
     const hash = createHash("sha256")
-      .update(JSON.stringify({ runtime: VALIDATOR_RUNTIME_TAG, schema: injected }))
+      .update(
+        JSON.stringify({
+          runtime: VALIDATOR_RUNTIME_TAG,
+          schema: normalizeSentinelsForHash(injected),
+        }),
+      )
       .digest("hex")
       .slice(0, 32);
     const cachedByHash = this.hashCache.get(hash);
@@ -277,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");