@telorun/kernel 0.24.1 → 0.25.0

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

@@ -1,4 +1,4 @@
-import { AnalysisRegistry, DiagnosticSeverity, StaticAnalyzer } from "@telorun/analyzer";
+import { AnalysisRegistry, DiagnosticSeverity, parseExportEntry, StaticAnalyzer } from "@telorun/analyzer";
 import type { ResourceInstance } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import type { BuiltinControllerContext } from "../../internal-context.js";
@@ -108,12 +108,27 @@ export async function create(
   validateRequiredInputs(moduleManifest.variables ?? {}, resource.variables ?? {}, "variables");
   validateRequiredInputs(moduleManifest.secrets ?? {}, resource.secrets ?? {}, "secrets");
 
-  // Create child context with the imported variables/secrets baked in, so that
-  // ${{ variables.x }} / ${{ secrets.y }} templates resolve correctly at runtime.
+  // Evaluate the import's variables/secrets ONCE against the IMPORTER's config
+  // scope, instead of baking the raw compiled-value objects verbatim. Resolution
+  // is eager and per-hop: each importer resolves its child's inputs from its own
+  // already-settled config, so config flows app -> lib -> lib at any nesting depth
+  // and a leaf reads `variables.X` as an O(1) concrete lookup with no chain-walk.
+  // The single concrete result seeds both the child scope and the snapshot value-
+  // flow surface, so they can never diverge.
+  //
+  // NOTE: `expandValue` evaluates against the importer's FULL context (variables /
+  // secrets, plus env/resources for a root app). The config-only import contract —
+  // 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>) ?? {};
   const childCtx = new ModuleContext(
     ctx.moduleContext.source,
-    (resource.variables as Record<string, unknown>) ?? {},
-    (resource.secrets as Record<string, unknown>) ?? {},
+    importVariables,
+    importSecrets,
     {},
     [],
     ctx.moduleContext.createInstance,
@@ -157,8 +172,26 @@ export async function create(
   // Throws if resources.X is not yet populated — the kernel retry loop catches this and retries.
   // const evaluatedExports: any = child.expand(moduleManifest.exports ?? {});
 
-  const exportedKinds: string[] = moduleManifest.exports?.kinds ?? [];
-  const exportedResourceNames: string[] = moduleManifest.exports?.resources ?? [];
+  // `exports.kinds` entries are a bare kind name (locally defined) or `Alias.Kind` (a re-export
+  // of an imported library's kind). `parseExportEntry` (shared with the analyzer) yields
+  // `{name, alias?}` — `name` is the exported kind suffix, `alias` (when set) names this
+  // library's own import it re-exports from.
+  const kindEntries = ((moduleManifest.exports?.kinds ?? []) as string[]).map(parseExportEntry);
+  const exportedKindSuffixes = kindEntries.map((k) => k.name);
+  // `exports.resources` entries are a bare name (`Db`, a locally-owned export) or a dotted
+  // `Alias.Name` (re-export of an imported instance, under name `Name`) — same grammar as
+  // `exports.kinds`.
+  const exportEntries = ((moduleManifest.exports?.resources ?? []) as unknown[]).map((e) => {
+    if (typeof e !== "string") {
+      throw new RuntimeError(
+        "ERR_INVALID_EXPORT",
+        `Library '${targetModule}' exports.resources entries must be plain names ('Name' or ` +
+          `'Alias.Name'); the '!ref' tag is not allowed in exports.resources.`,
+      );
+    }
+    return parseExportEntry(e);
+  });
+  const exportedResourceNames = exportEntries.map((e) => e.name);
   for (const name of exportedResourceNames) {
     if (name === "variables" || name === "secrets") {
       throw new RuntimeError(
@@ -167,30 +200,22 @@ export async function create(
       );
     }
   }
-  ctx.registerModuleImport(alias, targetModule, exportedKinds);
+  ctx.registerModuleImport(alias, targetModule, exportedKindSuffixes);
 
   // Publish the child's exported instances to the parent so cross-module `!ref Alias.name`
   // (Phase 5 injection / boot targets) and `${{ resources.Alias.name }}` (CEL value-flow)
-  // resolve. The gate is `exports.resources`; the lookup is lazy — instances exist after
-  // this import's init() has run child.initializeResources().
+  // resolve. The gate is `exports.resources`; the child's terminal getter is read lazily —
+  // it exists after this import's init() built the child's export table. Handing the parent
+  // the child's TERMINAL getter (not a wrapper) keeps resolution O(1) across re-export hops.
   (ctx.moduleContext as ModuleContext).registerImportedScope(
     alias,
     exportedResourceNames,
-    (name) => {
-      const entry = childCtx.resourceInstances.get(name);
-      if (!entry) return undefined;
-      // Canonicalize the authored kind to `<module>.<Kind>` so the cross-module ref shape and
-      // event naming are scope-independent. Exported instances are authored `Self.<Kind>` —
-      // the only case the std modules use, and the only one canonicalized here; it maps to the
-      // owning module directly, matching the analyzer's rule in resolve-ref-sentinels.ts. A
-      // re-exported foreign kind (authored via another import alias) is a future case with no
-      // current consumer and is left verbatim.
-      const rawKind = entry.resource.kind as string;
-      const kind = rawKind.startsWith("Self.")
-        ? `${targetModule}.${rawKind.slice("Self.".length)}`
-        : rawKind;
-      return { kind, instance: entry.instance };
-    },
+    (name) => childCtx.getTerminalExport(name),
+  );
+  // Same for kinds: `kind: Alias.Kind` resolves through the child's exported-kind table,
+  // covering both locally-defined and transitively re-exported kinds in O(1).
+  (ctx.moduleContext as ModuleContext).registerImportedKindScope(alias, (suffix) =>
+    childCtx.getExportedKind(suffix),
   );
 
   // Return a ResourceInstance whose snapshot() surfaces the exported values under
@@ -201,19 +226,24 @@ export async function create(
     snapshot: async () => {
       const exported: Record<string, unknown> = {};
       for (const name of exportedResourceNames) {
-        const inst = childCtx.resourceInstances.get(name)?.instance;
+        const inst = childCtx.getExported(name)?.instance;
         if (inst && typeof inst.snapshot === "function") {
           exported[name] = await Promise.resolve(inst.snapshot());
         }
       }
       return {
-        variables: ctx.expandValue(resource.variables, {}) ?? {},
-        secrets: ctx.expandValue(resource.secrets, {}) ?? {},
+        variables: importVariables,
+        secrets: importSecrets,
         ...exported,
       };
     },
     init: async () => {
       await child.initializeResources();
+      // Build this import's flattened export tables now that its own imports are
+      // registered (leaves-first), so a re-export (`!ref Alias.name` / `Alias.Kind`)
+      // copies the source import's terminal getter / canonical kind by reference —
+      // O(1) resolution at any depth.
+      childCtx.buildExportTable(exportEntries, kindEntries, targetModule);
     },
     teardown: async () => {
       await child.teardownResources();

package/src/evaluation-context.ts

@@ -501,10 +501,13 @@ export class EvaluationContext implements IEvaluationContext {
     // the resolved entry for event topics and error messages.
     const effectiveKind = kind || (entry.resource.kind as string);
 
-    if (typeof entry.instance.invoke !== "function") {
+    if (
+      typeof entry.instance.invoke !== "function" &&
+      typeof entry.instance.run !== "function"
+    ) {
       throw new RuntimeError(
         "ERR_RESOURCE_NOT_INVOKABLE",
-        `Resource ${effectiveKind}.${name} does not have an invoke method`,
+        `Resource ${effectiveKind}.${name} does not have an invoke or run method`,
       );
     }
 
@@ -524,10 +527,10 @@ export class EvaluationContext implements IEvaluationContext {
     inputs: TInputs,
     ctx?: InvokeContext,
   ): Promise<any> {
-    if (typeof instance.invoke !== "function") {
+    if (typeof instance.invoke !== "function" && typeof instance.run !== "function") {
       throw new RuntimeError(
         "ERR_RESOURCE_NOT_INVOKABLE",
-        `Resource ${kind}.${name} does not have an invoke method`,
+        `Resource ${kind}.${name} does not have an invoke or run method`,
       );
     }
     return this.runInvoke(kind, name, instance, inputs, ctx);
@@ -560,8 +563,15 @@ export class EvaluationContext implements IEvaluationContext {
     try {
       // Only (re)establish the ALS scope when the token differs from the ambient
       // one — nested invokes that inherited it skip the redundant `run`.
+      // A step / boot-target slot may reference a pure Runnable (the schema
+      // allows `telo#Runnable` alongside `telo#Invocable`); dispatch it via
+      // `run()` — side effects only, no outputs. Prefer `invoke()` when both
+      // exist so a dual-capability instance (e.g. Run.Sequence) keeps invoke
+      // semantics and returns its `steps`/`outputs`.
       const call = () =>
-        (instance.invoke as (i: any, c?: InvokeContext) => any)(inputs as any, invokeCtx);
+        typeof instance.invoke === "function"
+          ? (instance.invoke as (i: any, c?: InvokeContext) => any)(inputs as any, invokeCtx)
+          : (instance.run as (c?: InvokeContext) => any)(invokeCtx);
       const outputs = await (invokeCtx === ambient
         ? call()
         : cancellationStore.run(invokeCtx, call));

package/src/kernel.ts

@@ -41,7 +41,11 @@ import {
   writeAnalysisStamp,
 } from "./manifest-sources/analysis-stamp.js";
 import { resolveEntryDir } from "./manifest-sources/local-manifest-cache-source.js";
-import { resolveApplicationEnv } from "./application-env.js";
+import {
+  precompileApplicationEnvSchemas,
+  precompileDefinitionSchemas,
+  resolveApplicationEnv,
+} from "./application-env.js";
 import { policyFingerprint } from "./runtime-registry.js";
 import { SchemaValidator } from "./schema-validator.js";
 
@@ -305,8 +309,17 @@ export class Kernel implements IKernel {
    * Load a manifest by URL. The URL is dispatched through the registered
    * `ManifestSource` chain (file://, http://, pkg:, memory://, …); URL-shape
    * normalization is each source's responsibility.
+   *
+   * `analyzeOnly` runs the static-analysis pre-flight and persists its
+   * caches (the `.validated.json` analysis stamp and the compiled
+   * `__validators/` schema cache) but stops before module instantiation,
+   * target wiring, and application-env/secret resolution. Build steps
+   * (`telo install`) use it to bake those caches into a prebuilt image on a
+   * writable filesystem, so the runtime `load()` — which runs on a read-only
+   * 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): Promise<void> {
+  async load(url: string, options?: { analyzeOnly?: boolean }): Promise<void> {
     const sourceUrl = await this.loader.resolveEntryPoint(url);
     this._entryUrl = sourceUrl;
     // Point the shared schema validator at the entry-anchored cache so
@@ -417,6 +430,43 @@ export class Kernel implements IKernel {
       }
     }
 
+    // Build-time warm pass: the analysis caches are now on disk. Also bake the
+    // application-env residual validators — the runtime `resolveApplicationEnv`
+    // (below) compiles these on EVERY boot regardless of the stamp, so without
+    // pre-compiling them here an app with `variables`/`secrets`/`ports` would
+    // still hit the read-only `__validators` write on a baked image. Then stop
+    // before module instantiation / target wiring / application-env value
+    // resolution — those need a running environment (e.g. session secrets) the
+    // build does not have, and the runtime `load()` performs them anyway.
+    if (options?.analyzeOnly) {
+      if (rootModuleDoc?.kind === "Telo.Application") {
+        precompileApplicationEnvSchemas(
+          rootModuleDoc as Record<string, any>,
+          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;
+    }
+
     // Load runtime configuration — root module gets access to host env.
     // Imports are loaded separately via the import-controller; this load is
     // entry-only with compile-time CEL.

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/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,6 +78,39 @@ 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[]>();
@@ -194,7 +227,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);