@telorun/kernel 0.12.0 → 0.13.0

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

@@ -1,26 +1,14 @@
 import { DiagnosticSeverity, StaticAnalyzer } from "@telorun/analyzer";
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { ResourceInstance } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
+import type { BuiltinControllerContext } from "../../internal-context.js";
 import { ModuleContext } from "../../module-context.js";
 import { isDefaultPolicy, normalizeRuntime } from "../../runtime-registry.js";
 
-const importAnalysisCache = new Map<
-  string,
-  { signature: string; errors: string[] }
->();
-
-// Only resolve relative/absolute-path sources against the importer's URL. Registry refs
-// (std/foo@1.2.3) and absolute URLs (https://, file://) must pass through unchanged so the
-// loader's source chain can dispatch them — otherwise `new URL("std/foo@1", "file:///srv/telo.yaml")`
-// turns a registry ref into a bogus file path and LocalFileSource ENOENTs on it.
-function resolveImportSource(source: string, baseSource: string): string {
-  if (source.startsWith(".") || source.startsWith("/")) {
-    return new URL(source, baseSource).toString();
-  }
-  return source;
-}
-
-export async function create(resource: any, ctx: ResourceContext): Promise<ResourceInstance> {
+export async function create(
+  resource: any,
+  ctx: BuiltinControllerContext,
+): Promise<ResourceInstance> {
   const alias = resource.metadata.name as string;
 
   const moduleSource: string = resource.module ?? resource.source;
@@ -36,27 +24,36 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
   // Validate the imported module and all its transitive imports before loading for runtime.
   // loadManifests() follows Telo.Import chains so definitions from sub-imports are present,
   // preventing false UNDEFINED_KIND errors for kinds that come from the module's own imports.
-  const resolvedUrl = resolveImportSource(moduleSource, base);
-  const analysisManifests = await ctx.loadManifests(resolvedUrl);
-  const signature = JSON.stringify(analysisManifests);
-  const cached = importAnalysisCache.get(resolvedUrl);
-  let errors: string[];
-
-  if (cached && cached.signature === signature) {
-    errors = cached.errors;
-  } else {
+  //
+  // Route URL resolution through the kernel/loader's own helper rather than
+  // a hand-rolled `new URL(...).toString()`. For LocalFileSource the
+  // outputs match; for any custom `ManifestSource` with a non-trivial
+  // `resolveRelative`, only this path produces the canonical URL the
+  // loader keyed its caches under — without which fast paths like
+  // `isImportValidatedAtLoad` silently miss.
+  const resolvedUrl = ctx.resolveImportUrl(base, moduleSource);
+
+  // Fast path: when the kernel's load-time `analyzeErrors` already covered
+  // this import's subtree (the common case — every Telo.Import declared in
+  // the entry graph is walked by `loadGraph` and validated by
+  // `kernel.load`), skip the redundant per-import StaticAnalyzer pass.
+  // Falls through to the full analysis for URLs that arrived
+  // programmatically after `load()` (e.g. dynamically constructed imports
+  // in tests). Two Telo.Imports with the same source but distinct
+  // metadata.name would each re-run analysis here — a memoisation hook
+  // can be reintroduced if that turns into a measurable cost.
+  if (!ctx.isImportValidatedAtLoad(resolvedUrl)) {
+    const analysisManifests = await ctx.loadManifests(resolvedUrl);
     const diagnostics = new StaticAnalyzer().analyze(analysisManifests);
-    errors = diagnostics
+    const errors = diagnostics
       .filter((d) => d.severity === DiagnosticSeverity.Error)
       .map((d) => d.message);
-    importAnalysisCache.set(resolvedUrl, { signature, errors });
-  }
-
-  if (errors.length > 0) {
-    throw new RuntimeError(
-      "ERR_MANIFEST_VALIDATION_FAILED",
-      errors.join("\n"),
-    );
+    if (errors.length > 0) {
+      throw new RuntimeError(
+        "ERR_MANIFEST_VALIDATION_FAILED",
+        errors.join("\n"),
+      );
+    }
   }
 
   // Load target module manifests for runtime. Inject variables/secrets as compile context so

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

@@ -18,6 +18,7 @@ type ResourceDefinitionResource = RuntimeResource & {
   schema: Record<string, any>;
   capability?: string;
   controllers?: Array<string>;
+  provide?: unknown;
 };
 
 /**
@@ -31,6 +32,11 @@ class ResourceDefinition implements ResourceInstance {
 
   async init(ctx: ResourceContext) {
     if (!this.resource.controllers?.length) {
+      if (this.resource.capability === "Telo.Provider" && this.resource.provide == null) {
+        throw new Error(
+          `Telo.Definition '${this.resource.metadata.name}': 'capability: Telo.Provider' requires either 'controllers:' (TS-backed) or 'provide:' (template-backed).`,
+        );
+      }
       const controllerInstance = createTemplateController(this.resource as any);
       ctx.registerDefinition(this.resource);
       await ctx.registerController(

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

@@ -1,12 +1,32 @@
 import type { ControllerInstance, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import { isCompiledValue } from "@telorun/sdk";
 
+/** Reports the resources: entries available to dispatch against, by expanded
+ *  name and kind. Used in error messages to guide the developer back to the
+ *  template's `resources:` array when a dispatch target doesn't match. */
+function describeAvailableTargets(
+  ctx: ResourceContext,
+  resources: any[] | undefined,
+  self: Record<string, unknown>,
+): string {
+  if (!resources || resources.length === 0) return "<none>";
+  return resources
+    .map((r) => {
+      const expanded = ctx.moduleContext.expandWith(r?.metadata?.name ?? "", { self }) as string;
+      const kind = typeof r?.kind === "string" ? r.kind : "<unknown-kind>";
+      return `'${expanded || "<unnamed>"}' (${kind})`;
+    })
+    .join(", ");
+}
+
 export function createTemplateController(definition: {
   schema: Record<string, any>;
   resources?: any[];
   invoke?: string | { kind?: string; name: string };
   inputs?: Record<string, any>;
   run?: string;
+  provide?: { kind: string; name: string };
+  result?: Record<string, any>;
 }): ControllerInstance {
   return {
     schema: definition.schema ?? { type: "object", additionalProperties: true },
@@ -32,6 +52,9 @@ export function createTemplateController(definition: {
       const runTarget = definition.run
         ? (ctx.moduleContext.expandWith(definition.run, { self }) as string)
         : null;
+      const provideTarget = definition.provide?.name
+        ? (ctx.moduleContext.expandWith(definition.provide.name, { self }) as string)
+        : null;
 
       const persistentManifests: any[] = [];
       let ephemeralTemplate: any = null;
@@ -40,7 +63,10 @@ export function createTemplateController(definition: {
         const expandedName = ctx.moduleContext.expandWith(template.metadata?.name ?? "", {
           self,
         }) as string;
-        const isTarget = expandedName === invokeTarget || expandedName === runTarget;
+        const isTarget =
+          expandedName === invokeTarget ||
+          expandedName === runTarget ||
+          expandedName === provideTarget;
         if (isTarget) {
           ephemeralTemplate = template;
         } else {
@@ -84,7 +110,8 @@ export function createTemplateController(definition: {
           invoke: async (inputs: any) => {
             if (!ephemeralTemplate) {
               throw new Error(
-                `Template '${resource.metadata.name}': no ephemeral resource for invoke target '${invokeTarget}'`,
+                `Template '${resource.metadata.name}': 'invoke:' targets '${invokeTarget}' ` +
+                  `but no entry in 'resources:' has that metadata.name. Available: ${describeAvailableTargets(ctx, definition.resources, self)}.`,
               );
             }
             const extraContext = { self, inputs };
@@ -95,7 +122,13 @@ export function createTemplateController(definition: {
             return withEphemeral(expanded, async (name) => {
               const entry = ctx.moduleContext.resourceInstances.get(name);
               if (!entry?.instance?.invoke) {
-                throw new Error(`Ephemeral resource '${name}' is not invocable`);
+                const targetKind = (entry?.resource?.kind ?? expanded?.kind ?? "<unknown-kind>") as string;
+                const targetDef = ctx.moduleContext.getDefinition?.(targetKind);
+                const actualCap = typeof targetDef?.capability === "string" ? targetDef.capability : "<unknown>";
+                throw new Error(
+                  `Template '${resource.metadata.name}': 'invoke:' target '${targetKind}/${invokeTarget}' ` +
+                    `has capability '${actualCap}', not Telo.Invocable. Update 'invoke:' to a Telo.Invocable kind, or change the target's kind in 'resources:'.`,
+                );
               }
               // Top-level `inputs:` (sibling of `invoke:`) carries the values passed
               // to the dispatch target's invoke(). When absent, fall back to the
@@ -108,7 +141,13 @@ export function createTemplateController(definition: {
                     extraContext,
                   )
                 : expanded.inputs ?? inputs;
-              return entry.instance.invoke(invokeInputs);
+              const raw = await entry.instance.invoke(invokeInputs);
+              if (definition.result == null) return raw;
+              const resultContext = { self, result: raw };
+              return ctx.moduleContext.expandWith(
+                ctx.moduleContext.expandWith(definition.result, resultContext),
+                resultContext,
+              );
             });
           },
         }),
@@ -117,24 +156,73 @@ export function createTemplateController(definition: {
           run: async () => {
             if (!ephemeralTemplate) {
               throw new Error(
-                `Template '${resource.metadata.name}': no ephemeral resource for run target '${runTarget}'`,
+                `Template '${resource.metadata.name}': 'run:' targets '${runTarget}' ` +
+                  `but no entry in 'resources:' has that metadata.name. Available: ${describeAvailableTargets(ctx, definition.resources, self)}.`,
               );
             }
             const extraContext = { self };
             const expanded = ctx.moduleContext.expandWith(
               ctx.moduleContext.expandWith(ephemeralTemplate, extraContext),
               extraContext,
-            );
+            ) as any;
             return withEphemeral(expanded, async (name) => {
               const entry = ctx.moduleContext.resourceInstances.get(name);
               if (!entry?.instance?.run) {
-                throw new Error(`Ephemeral resource '${name}' is not runnable`);
+                const targetKind = (entry?.resource?.kind ?? expanded?.kind ?? "<unknown-kind>") as string;
+                const targetDef = ctx.moduleContext.getDefinition?.(targetKind);
+                const actualCap = typeof targetDef?.capability === "string" ? targetDef.capability : "<unknown>";
+                throw new Error(
+                  `Template '${resource.metadata.name}': 'run:' target '${targetKind}/${runTarget}' ` +
+                    `has capability '${actualCap}', not Telo.Runnable. Update 'run:' to a Telo.Runnable kind, or change the target's kind in 'resources:'.`,
+                );
               }
               return entry.instance.run();
             });
           },
         }),
 
+        ...(provideTarget && {
+          provide: async () => {
+            if (!ephemeralTemplate) {
+              throw new Error(
+                `Template '${resource.metadata.name}': 'provide:' targets '${provideTarget}' ` +
+                  `but no entry in 'resources:' has that metadata.name. Available: ${describeAvailableTargets(ctx, definition.resources, self)}.`,
+              );
+            }
+            const extraContext = { self };
+            const expanded = ctx.moduleContext.expandWith(
+              ctx.moduleContext.expandWith(ephemeralTemplate, extraContext),
+              extraContext,
+            ) as any;
+            return withEphemeral(expanded, async (name) => {
+              const entry = ctx.moduleContext.resourceInstances.get(name);
+              if (!entry?.instance?.invoke) {
+                const targetKind = (entry?.resource?.kind ?? expanded?.kind ?? "<unknown-kind>") as string;
+                const targetDef = ctx.moduleContext.getDefinition?.(targetKind);
+                const actualCap = typeof targetDef?.capability === "string" ? targetDef.capability : "<unknown>";
+                throw new Error(
+                  `Template '${resource.metadata.name}': 'provide:' target '${targetKind}/${provideTarget}' ` +
+                    `has capability '${actualCap}', not Telo.Invocable. Update 'provide:' to a Telo.Invocable kind, or change the target's kind in 'resources:'.`,
+                );
+              }
+              const provideInputs: any =
+                definition.inputs != null
+                  ? ctx.moduleContext.expandWith(
+                      ctx.moduleContext.expandWith(definition.inputs, extraContext),
+                      extraContext,
+                    )
+                  : {};
+              const raw = await entry.instance.invoke(provideInputs);
+              if (definition.result == null) return raw;
+              const resultContext = { self, result: raw };
+              return ctx.moduleContext.expandWith(
+                ctx.moduleContext.expandWith(definition.result, resultContext),
+                resultContext,
+              );
+            });
+          },
+        }),
+
         teardown: async () => {
           await childContext.teardownResources();
         },

package/src/internal-context.ts

@@ -0,0 +1,25 @@
+import type { ResourceContext } from "@telorun/sdk";
+
+/**
+ * Context interface used by built-in kernel controllers (Telo.Application /
+ * Telo.Library / Telo.Import / Telo.Definition / Telo.Abstract) that need
+ * privileged access to load-time graph identity. These methods are
+ * intentionally *not* on the public `ResourceContext` exposed to module
+ * authors — they couple the caller to the kernel's load-time view of the
+ * world, and the import-controller is the only consumer today.
+ *
+ * `ResourceContextImpl` in this package implements both interfaces, so a
+ * controller authored against this type still works under the generic
+ * `controller.create(resource, ctx)` dispatch — the kernel just types it
+ * locally as `BuiltinControllerContext` instead of `ResourceContext`.
+ */
+export interface BuiltinControllerContext extends ResourceContext {
+  /** True when `url` resolved (via the loader's URL → canonical-source
+   *  map) to a module that was part of the entry graph successfully
+   *  analyzed during `Kernel.load()`. */
+  isImportValidatedAtLoad(url: string): boolean;
+  /** Resolve `importSource` against `fromSource` through the loader's
+   *  source-chain `resolveRelative`. Identical to what `loadGraph` used
+   *  internally — so the produced URL agrees with the loader's caches. */
+  resolveImportUrl(fromSource: string, importSource: string): string;
+}

package/src/kernel.ts

@@ -5,6 +5,7 @@ import {
   isModuleKind,
   Loader,
   StaticAnalyzer,
+  type LoadedGraph,
   type ManifestSource,
 } from "@telorun/analyzer";
 import {
@@ -30,6 +31,13 @@ import { EventStream } from "./event-stream.js";
 import { EventBus } from "./events.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
+import {
+  computeAnalysisSignature,
+  readAnalysisStamp,
+  writeAnalysisStamp,
+} from "./manifest-sources/analysis-stamp.js";
+import { resolveEntryDir } from "./manifest-sources/local-manifest-cache-source.js";
+import { resolveApplicationEnv } from "./application-env.js";
 import { policyFingerprint } from "./runtime-registry.js";
 import { SchemaValidator } from "./schema-validator.js";
 
@@ -117,6 +125,7 @@ export class Kernel implements IKernel {
   private rootContext!: ModuleContext;
   private staticManifests: ResourceManifest[] = [];
   private _entryUrl?: string;
+  private _loadedGraph?: LoadedGraph;
   // Lifecycle state — guards boot/runTargets/teardown/invoke transitions.
   // teardown() is the only idempotent method; everything else throws on misuse.
   private _bootCalled = false;
@@ -185,6 +194,37 @@ export class Kernel implements IKernel {
     return this.registry;
   }
 
+  /** The full LoadedGraph captured during `load()`. Used by the CLI to
+   *  feed `writeManifestCache` so a successful `telo run` populates
+   *  `<entry-dir>/.telo/manifests/` for subsequent runs — the same on-disk
+   *  layout `telo install` writes. Undefined before `load()` has been
+   *  called or if it threw before the graph was captured. */
+  getLoadedGraph(): LoadedGraph | undefined {
+    return this._loadedGraph;
+  }
+
+  /** True when `url` resolves (via the loader's URL → canonical-source map)
+   *  to a module that was already part of the entry graph successfully
+   *  analyzed during `load()`. The import-controller uses it to skip its
+   *  per-import `analyze()` pass when the kernel's load-time validation
+   *  already covered the same subtree. */
+  isImportValidatedAtLoad(url: string): boolean {
+    if (!this._loadedGraph) return false;
+    const canonical = this.loader.canonicalize(url);
+    if (!canonical) return false;
+    return this._loadedGraph.modules.has(canonical);
+  }
+
+  /** Resolve a `Telo.Import.source` against the importing file's URL
+   *  through the same source-chain `resolveRelative` the loader used at
+   *  graph-walk time. The import-controller routes through here so its
+   *  `resolveImportSource` no longer second-guesses the loader for
+   *  custom `ManifestSource`s — `isImportValidatedAtLoad` etc. only hit
+   *  when both sides agree on the canonical URL. */
+  resolveImportUrl(fromSource: string, importSource: string): string {
+    return this.loader.resolveImportUrl(fromSource, importSource);
+  }
+
   /**
    * Load built-in Runtime definitions (e.g., Telo.Application, Telo.Library).
    * Also declares all known module namespaces upfront so that resources can be
@@ -225,6 +265,16 @@ export class Kernel implements IKernel {
   async load(url: string): 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);
+    this.sharedSchemaValidator.setCacheDir(
+      validatorCacheDir
+        ? `${validatorCacheDir}/.telo/manifests/__validators`
+        : undefined,
+    );
     this.rootContext = new ModuleContext(
       sourceUrl,
       {},
@@ -253,6 +303,7 @@ export class Kernel implements IKernel {
     if (analysisGraph.errors.length > 0) {
       throw analysisGraph.errors[0].error;
     }
+    this._loadedGraph = analysisGraph;
     const staticManifests = flattenForAnalyzer(analysisGraph);
     this.staticManifests = staticManifests;
 
@@ -275,7 +326,22 @@ export class Kernel implements IKernel {
       }
     }
 
-    const errors = this.analyzer.analyzeErrors(staticManifests, {}, this.registry);
+    // Hash-keyed analysis cache: when the entry's full LoadedGraph matches
+    // a previously-stamped successful run (same file bytes, same stamp
+    // protocol version), skip the per-resource validation walk inside
+    // `analyzeErrors`. Registration of identities / aliases / definitions
+    // 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 skipValidation = stamp?.signature === analysisSignature;
+    const errors = this.analyzer.analyzeErrors(
+      staticManifests,
+      { skipValidation },
+      this.registry,
+    );
     if (errors.length > 0) {
       throw new RuntimeError(
         "ERR_MANIFEST_VALIDATION_FAILED",
@@ -290,6 +356,19 @@ export class Kernel implements IKernel {
         })),
       );
     }
+    if (entryDir && !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.
+      try {
+        await writeAnalysisStamp(entryDir, analysisSignature);
+      } catch (err) {
+        this.stderr.write(
+          `[telo:kernel] analysis stamp write failed: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+      }
+    }
 
     // Load runtime configuration — root module gets access to host env.
     // Imports are loaded separately via the import-controller; this load is
@@ -304,15 +383,54 @@ export class Kernel implements IKernel {
     const normalizedManifests = this.analyzer.normalize(allManifests, this.registry);
     this.staticManifests = normalizedManifests;
 
+    let rootApplicationManifest: ResourceManifest | undefined;
     for (const manifest of normalizedManifests) {
       if (isModuleKind(manifest.kind)) {
-        // Root is always Telo.Application (Library root rejected above). Applications
-        // have no variables/secrets fields — those are a Library-only contract, populated
-        // by importers, not by the root manifest itself.
-        this.rootContext.setTargets(manifest.targets ?? []);
+        // Root is always Telo.Application (Library root rejected above).
+        // Application-level `variables` / `secrets` declarations carry an `env:`
+        // mapping per field; the kernel populates the root scope from
+        // `process.env` after the manifest loop so imports can read
+        // `${{ variables.X }}` during their own init.
+        //
+        // Targets normalize down to bare names regardless of source surface.
+        // The analyzer's `resolveRefSentinels` pass already substituted any
+        // `!ref <name>` to `{kind, name}`; bare-string forms pass through.
+        // Anything else (e.g. an unresolved sentinel because the analyzer
+        // couldn't see it, or a malformed manifest) is a hard error —
+        // silently dropping the entry would leave the user staring at a
+        // "no targets ran" outcome with no signal where it went wrong.
+        const rawTargets = (manifest.targets ?? []) as unknown[];
+        const targetNames = rawTargets.map((t, index) => {
+          if (typeof t === "string") return t;
+          if (t && typeof t === "object" && typeof (t as { name?: unknown }).name === "string") {
+            return (t as { name: string }).name;
+          }
+          throw new RuntimeError(
+            "ERR_INVALID_VALUE",
+            `Telo.Application '${(manifest.metadata as { name?: string } | undefined)?.name ?? "(unnamed)"}' targets[${index}] could not be normalized to a resource name. Got: ${JSON.stringify(t)}`,
+          );
+        });
+        this.rootContext.setTargets(targetNames);
+        if (manifest.kind === "Telo.Application") {
+          rootApplicationManifest = manifest;
+        }
       }
       this.rootContext.registerManifest(manifest);
     }
+
+    if (rootApplicationManifest) {
+      const { variables, secrets } = resolveApplicationEnv(
+        rootApplicationManifest as Record<string, any>,
+        this.env,
+        this.sharedSchemaValidator,
+      );
+      if (Object.keys(variables).length > 0) {
+        this.rootContext.setVariables(variables);
+      }
+      if (Object.keys(secrets).length > 0) {
+        this.rootContext.setSecrets(secrets);
+      }
+    }
   }
 
   /**
@@ -419,6 +537,13 @@ export class Kernel implements IKernel {
     if (this.rootContext) {
       await this.rootContext.teardownResources();
     }
+    // Drop the load-time graph so a teardown'd kernel doesn't pin every
+    // manifest file's text in memory (LoadedFile retains the parsed
+    // documents + the original YAML bytes). Reusing the kernel after
+    // teardown is a hard error elsewhere, so this is purely a memory
+    // hygiene step.
+    this._loadedGraph = undefined;
+    this.staticManifests = [];
     await this.eventBus.emit("Kernel.Stopped", { exitCode: this._exitCode });
   }
 

package/src/manifest-schemas.ts

@@ -1,15 +1,16 @@
-import { Type } from "@sinclair/typebox";
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
 const Ajv = AjvModule.default ?? AjvModule;
 
-export const RuntimeResourceSchema = Type.Object(
-  {
-    kind: Type.String(),
-    metadata: Type.Object({ name: Type.String() }, { additionalProperties: true }),
-  },
-  { additionalProperties: true },
-);
+// 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.
+export {
+  MANIFEST_SCHEMA_URI,
+  ManifestRootSchema,
+  ResourceRefSchema,
+} from "@telorun/templating";
 
 const metadataSchema = {
   type: "object",
@@ -149,9 +150,28 @@ export const ResourceAbstractSchema = {
 const ajv = new Ajv({ allErrors: true, strict: false });
 addFormats.default(ajv);
 
-export const validateRuntimeResource = ajv.compile(RuntimeResourceSchema);
-export const validateResourceDefinition = ajv.compile(ResourceDefinitionSchema);
-export const validateResourceAbstract = ajv.compile(ResourceAbstractSchema);
+// Lazy-compile validator: the AJV codegen cost (≈10–15 ms for these
+// schemas) is only paid when a definition / abstract actually needs
+// validating. A hello-world that loads no Telo.Definition or
+// Telo.Abstract documents never triggers either compile; apps that
+// do see them only pay once per process.
+interface LazyValidator {
+  (data: unknown): boolean | Promise<unknown>;
+  errors?: any[] | null;
+}
+function lazyValidator(schema: object): LazyValidator {
+  let compiled: ReturnType<typeof ajv.compile> | undefined;
+  const fn: LazyValidator = (data: unknown) => {
+    if (!compiled) compiled = ajv.compile(schema);
+    const ok = compiled(data);
+    fn.errors = compiled.errors as any[] | null | undefined;
+    return ok;
+  };
+  return fn;
+}
+
+export const validateResourceDefinition = lazyValidator(ResourceDefinitionSchema);
+export const validateResourceAbstract = lazyValidator(ResourceAbstractSchema);
 
 export function formatAjvErrors(errors: any[] | null | undefined): string {
   if (!errors || errors.length === 0) return "Unknown schema error";