@telorun/analyzer 0.1.2 → 0.1.3

package/dist/schema-compat.js

@@ -11,6 +11,7 @@ export function createAjv() {
     return instance;
 }
 const ajv = createAjv();
+const compiledSchemaValidators = new WeakMap();
 /** Conservative structural JSON Schema compatibility check.
  *  Only flags definite mismatches: missing required fields and primitive type conflicts.
  *  Ambiguous cases (anyOf/oneOf/etc.) are treated as compatible. */
@@ -93,12 +94,15 @@ function ajvErrorToPath(err) {
 }
 /** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
 export function validateAgainstSchema(data, schema) {
-    let validate;
-    try {
-        validate = ajv.compile(schema);
-    }
-    catch {
-        return [];
+    let validate = compiledSchemaValidators.get(schema);
+    if (!validate) {
+        try {
+            validate = ajv.compile(schema);
+            compiledSchemaValidators.set(schema, validate);
+        }
+        catch {
+            return [];
+        }
     }
     if (validate(data))
         return [];
@@ -234,24 +238,49 @@ export function celPlaceholderForSchema(schema) {
     }
 }
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
+/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
+function resolveRef(schema, root) {
+    if (schema.$ref && typeof schema.$ref === "string" && schema.$ref.startsWith("#/$defs/")) {
+        const defName = schema.$ref.slice("#/$defs/".length);
+        const resolved = root.$defs?.[defName];
+        if (resolved)
+            return resolved;
+    }
+    return schema;
+}
+/** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
+function collectProperties(schema) {
+    const props = { ...(schema.properties ?? {}) };
+    for (const sub of schema.oneOf ?? schema.anyOf ?? []) {
+        if (sub && typeof sub === "object" && sub.properties) {
+            for (const [k, v] of Object.entries(sub.properties)) {
+                if (!(k in props))
+                    props[k] = v;
+            }
+        }
+    }
+    return props;
+}
 /** Deep-clone `data`, replacing every pure CEL template string (`${{ expr }}`) with a
  *  schema-appropriate placeholder so AJV can validate non-CEL fields without false positives. */
-export function substituteCelFields(data, schema) {
+export function substituteCelFields(data, schema, rootSchema) {
+    const root = rootSchema ?? schema;
+    const resolved = resolveRef(schema, root);
     if (typeof data === "string" && CEL_PURE_RE.test(data)) {
-        return celPlaceholderForSchema(schema);
+        return celPlaceholderForSchema(resolved);
     }
     if (Array.isArray(data)) {
-        const itemSchema = (schema.items ?? {});
-        return data.map((item) => substituteCelFields(item, itemSchema));
+        const itemSchema = resolveRef((resolved.items ?? {}), root);
+        return data.map((item) => substituteCelFields(item, itemSchema, root));
     }
     if (data !== null && typeof data === "object") {
-        const props = (schema.properties ?? {});
-        const addlProps = schema.additionalProperties && typeof schema.additionalProperties === "object"
-            ? schema.additionalProperties
+        const props = collectProperties(resolved);
+        const addlProps = resolved.additionalProperties && typeof resolved.additionalProperties === "object"
+            ? resolved.additionalProperties
             : undefined;
         const result = {};
         for (const [k, v] of Object.entries(data)) {
-            result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}));
+            result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}), root);
         }
         return result;
     }

package/dist/types.d.ts

@@ -7,6 +7,8 @@ export declare const DiagnosticSeverity: {
     readonly Hint: 4;
 };
 export type DiagnosticSeverity = (typeof DiagnosticSeverity)[keyof typeof DiagnosticSeverity];
+/** Default entry-point filename when a directory is given instead of a file. */
+export declare const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
 export interface Position {
     /** 0-based line number */
     line: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CACzD;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;IAClC,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0DAA0D;IAC1D,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;CACrE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CACzD;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;IAClC,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0DAA0D;IAC1D,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;CACrE"}

package/dist/types.js

@@ -6,3 +6,5 @@ export const DiagnosticSeverity = {
     Information: 3,
     Hint: 4,
 };
+/** Default entry-point filename when a directory is given instead of a file. */
+export const DEFAULT_MANIFEST_FILENAME = "telo.yaml";

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA6C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAoPtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA6C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAgQtB"}

package/dist/validate-references.js

@@ -111,9 +111,21 @@ export function validateReferences(resources, context) {
                 if (!val)
                     continue;
                 // Name-only reference (plain string) — look up by name to validate.
+                // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
+                // extract the resource name from the last dot segment.
                 if (typeof val === "string") {
-                    const target = byName.get(val) ?? visibleScopeManifests.find((m) => m.metadata?.name === val);
+                    const lastDot = val.lastIndexOf(".");
+                    const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
+                    const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
+                    const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
                     if (!target) {
+                        // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
+                        // The resource lives in the imported module's scope and can't be validated here.
+                        // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
+                        // kinds — those must be validated.
+                        if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
+                            continue;
+                        }
                         diagnostics.push({
                             severity: DiagnosticSeverity.Error,
                             code: "UNRESOLVED_REFERENCE",

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.1.2",
+  "version": "0.1.3",
+  "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
+  "keywords": [
+    "telo",
+    "analyzer",
+    "validator",
+    "manifest",
+    "yaml"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "analyzer/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -22,7 +41,7 @@
     "ajv-formats": "^3.0.1",
     "yaml": "^2.8.3",
     "jsonpath-plus": "^10.3.0",
-    "@telorun/sdk": "0.2.7"
+    "@telorun/sdk": "0.2.8"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/adapters/http-adapter.ts

@@ -1,4 +1,4 @@
-import type { ManifestAdapter } from "../types.js";
+import { DEFAULT_MANIFEST_FILENAME, type ManifestAdapter } from "../types.js";
 
 export class HttpAdapter implements ManifestAdapter {
   supports(url: string): boolean {
@@ -6,7 +6,7 @@ export class HttpAdapter implements ManifestAdapter {
   }
 
   async read(url: string): Promise<{ text: string; source: string }> {
-    const fetchUrl = url.includes(".yaml") ? url : `${url}/module.yaml`;
+    const fetchUrl = url.includes(".yaml") ? url : `${url}/${DEFAULT_MANIFEST_FILENAME}`;
     const response = await fetch(fetchUrl);
     if (!response.ok) {
       throw new Error(

package/src/adapters/node-adapter.ts

@@ -1,6 +1,6 @@
 import * as fs from "fs/promises";
 import * as path from "path";
-import type { ManifestAdapter } from "../types.js";
+import { DEFAULT_MANIFEST_FILENAME, type ManifestAdapter } from "../types.js";
 
 /** Node.js fs-based ManifestAdapter for local files. Not browser-compatible. */
 export class NodeAdapter implements ManifestAdapter {
@@ -20,7 +20,7 @@ export class NodeAdapter implements ManifestAdapter {
     const filePath = url.startsWith("file://") ? new URL(url).pathname : url;
     const stat = await fs.stat(filePath).catch(() => null);
     const resolvedPath =
-      stat?.isDirectory() ? path.join(filePath, "module.yaml") : filePath;
+      stat?.isDirectory() ? path.join(filePath, DEFAULT_MANIFEST_FILENAME) : filePath;
     const text = await fs.readFile(resolvedPath, "utf8");
     return { text, source: resolvedPath };
   }

package/src/adapters/registry-adapter.ts

@@ -1,4 +1,4 @@
-import type { ManifestAdapter } from "../types.js";
+import { DEFAULT_MANIFEST_FILENAME, type ManifestAdapter } from "../types.js";
 
 const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
 
@@ -40,7 +40,7 @@ export class RegistryAdapter implements ManifestAdapter {
   }
 
   private toRegistryUrl(moduleRef: string): string {
-    return `${this.toRegistryModuleBase(moduleRef)}/module.yaml`;
+    return `${this.toRegistryModuleBase(moduleRef)}/${DEFAULT_MANIFEST_FILENAME}`;
   }
 
   private parseModuleRef(moduleRef: string): { modulePath: string; version: string } {

package/src/analyzer.ts

@@ -4,6 +4,7 @@ import { AnalysisRegistry } from "./analysis-registry.js";
 import { buildTypedCelEnvironment, celEnvironment } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
+import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kernel-globals.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import {
   celTypeSatisfiesJsonSchema,
@@ -317,6 +318,10 @@ export class StaticAnalyzer {
       }
     }
 
+    // Build typed kernel globals schema so x-telo-context chain validation
+    // recognises variables, secrets, resources, env automatically
+    const kernelGlobals = buildKernelGlobalsSchema(allManifests);
+
     // Validate each non-definition, non-system resource
     for (const m of allManifests) {
       if (!m.kind || !m.metadata?.name) {
@@ -463,11 +468,12 @@ export class StaticAnalyzer {
         const manifestItem = matchedScope
           ? getManifestItem(path, matchedScope, m as Record<string, any>)
           : (m as Record<string, any>);
-        const effectiveContext = resolveContextAnnotations(
+        const resolvedContext = resolveContextAnnotations(
           matchedContext,
           manifestItem,
           allManifests as Record<string, any>[],
         );
+        const effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
 
         for (const chain of accessChains) {
           const err = validateChainAgainstSchema(chain, effectiveContext);

package/src/cel-environment.ts

@@ -20,8 +20,11 @@ export const celEnvironment = new Environment({ unlistedVariablesAreDyn: true })
  *
  *  - `variables`: typed from the manifest's `variables` field if it is a schema map
  *    (only `Kernel.Module` resources carry this); otherwise registered as `map` (dyn).
- *  - `secrets`, `resources`, `imports`, `env`: always `map` (dyn — output schemas unknown).
- *  - `extraContextSchema`: additional variables from an `x-telo-context` annotation. */
+ *  - `secrets`, `resources`, `env`: always `map` (dyn — output schemas unknown).
+ *  - `extraContextSchema`: additional variables from an `x-telo-context` annotation.
+ *
+ *  NOTE: The set of kernel globals registered here must match `KERNEL_GLOBAL_NAMES`
+ *  in kernel-globals.ts, which is used for chain-access validation. */
 export function buildTypedCelEnvironment(
   manifest: ResourceManifest,
   extraContextSchema?: Record<string, any> | null,
@@ -50,7 +53,6 @@ export function buildTypedCelEnvironment(
 
     env.registerVariable("secrets", "map");
     env.registerVariable("resources", "map");
-    env.registerVariable("imports", "map");
     env.registerVariable("env", "map");
 
     if (extraContextSchema?.properties) {

package/src/index.ts

@@ -4,7 +4,7 @@ export { RegistryAdapter } from "./adapters/registry-adapter.js";
 export { AnalysisRegistry } from "./analysis-registry.js";
 export { StaticAnalyzer } from "./analyzer.js";
 export { Loader } from "./manifest-loader.js";
-export { DiagnosticSeverity } from "./types.js";
+export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type {
     AnalysisDiagnostic,
     AnalysisOptions, LoaderInitOptions, LoadOptions, ManifestAdapter,

package/src/kernel-globals.ts

@@ -0,0 +1,110 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+/**
+ * Kernel global names available in every CEL evaluation context at runtime.
+ * Both `buildKernelGlobalsSchema` (chain-access validation) and
+ * `buildTypedCelEnvironment` in cel-environment.ts (CEL type-checking)
+ * must stay in sync with this list.
+ *
+ * Note: `env` is only available in the root module context. Child modules
+ * loaded via Kernel.Import do not receive host environment variables.
+ * There is no `imports` namespace at runtime — import snapshots are stored
+ * under `resources.<alias>`.
+ */
+export const KERNEL_GLOBAL_NAMES = ["variables", "secrets", "resources", "env"] as const;
+
+const SYSTEM_KINDS = new Set([
+  "Kernel.Definition",
+  "Kernel.Module",
+  "Kernel.Abstract",
+]);
+
+/**
+ * Build a typed JSON Schema describing the kernel globals available in the
+ * given manifest set. Used to merge into `x-telo-context` schemas so that
+ * chain-access validation recognises kernel globals without module authors
+ * having to re-declare them.
+ *
+ * - `variables` / `secrets`: typed from the `Kernel.Module` declaration
+ * - `resources`: enumerates all non-system resource names
+ * - `env`: dynamic (runtime env vars, root module only)
+ */
+export function buildKernelGlobalsSchema(
+  manifests: ResourceManifest[],
+): Record<string, any> {
+  const moduleManifest = manifests.find((m) => m.kind === "Kernel.Module") as
+    | Record<string, any>
+    | undefined;
+
+  const resourceProps: Record<string, any> = {};
+  for (const m of manifests) {
+    const name = m.metadata?.name as string | undefined;
+    if (!name || !m.kind) continue;
+    // Kernel.Import snapshots are stored under resources.<alias> at runtime,
+    // so they appear here alongside regular resources.
+    if (!SYSTEM_KINDS.has(m.kind)) {
+      resourceProps[name] = { type: "object", additionalProperties: true };
+    }
+  }
+
+  return {
+    type: "object",
+    properties: {
+      variables: buildSchemaMapSchema(moduleManifest?.variables),
+      secrets: buildSchemaMapSchema(moduleManifest?.secrets),
+      resources: {
+        type: "object",
+        properties: resourceProps,
+        additionalProperties: false,
+      },
+      env: { type: "object", additionalProperties: true },
+    },
+  };
+}
+
+/** Wrap a JSON Schema property map (like `Kernel.Module.variables`) into a
+ *  closed object schema suitable for chain-access validation. Falls back to
+ *  an open map when the module declares no variables/secrets. */
+function buildSchemaMapSchema(
+  schemaMap: Record<string, any> | null | undefined,
+): Record<string, any> {
+  if (!schemaMap || typeof schemaMap !== "object" || Array.isArray(schemaMap)) {
+    return { type: "object", additionalProperties: true };
+  }
+  const props: Record<string, any> = {};
+  for (const [key, value] of Object.entries(schemaMap)) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      props[key] = value;
+    }
+  }
+  if (Object.keys(props).length === 0) {
+    return { type: "object", additionalProperties: true };
+  }
+  return {
+    type: "object",
+    properties: props,
+    additionalProperties: false,
+  };
+}
+
+/**
+ * Merge kernel globals into an `x-telo-context` schema so chain-access
+ * validation recognises `variables`, `secrets`, `resources`, `env`
+ * without module authors having to re-declare them.
+ *
+ * Context-specific properties take precedence over globals (spread order).
+ * The original `additionalProperties` setting is preserved.
+ */
+export function mergeKernelGlobalsIntoContext(
+  contextSchema: Record<string, any>,
+  globalsSchema: Record<string, any>,
+): Record<string, any> {
+  return {
+    ...contextSchema,
+    properties: {
+      ...globalsSchema.properties,
+      ...(contextSchema.properties ?? {}),
+    },
+    additionalProperties: contextSchema.additionalProperties ?? false,
+  };
+}

package/src/manifest-loader.ts

@@ -1,4 +1,4 @@
-import type { ResourceManifest } from "@telorun/sdk";
+import { isCompiledValue, type ResourceManifest } from "@telorun/sdk";
 import { isMap, isPair, isScalar, isSeq, parseAllDocuments, type Document } from "yaml";
 import { HttpAdapter } from "./adapters/http-adapter.js";
 import { RegistryAdapter } from "./adapters/registry-adapter.js";
@@ -12,6 +12,11 @@ import type {
 } from "./types.js";
 
 export class Loader {
+  private static readonly moduleCache = new Map<
+    string,
+    { text: string; manifests: ResourceManifest[] }
+  >();
+
   protected adapters: ManifestAdapter[];
 
   constructor(extraAdaptersOrOptions: ManifestAdapter[] | LoaderInitOptions = []) {
@@ -49,6 +54,12 @@ export class Loader {
 
   async loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]> {
     const { text, source } = await this.pick(url).read(url);
+    const cacheKey = `${options?.compile ? "compiled" : "raw"}:${source}`;
+    const cached = Loader.moduleCache.get(cacheKey);
+    if (cached && cached.text === text) {
+      return cloneManifestArray(cached.manifests);
+    }
+
     const parsedDocuments = parseAllDocuments(text);
     const rawDocs = parsedDocuments.map((d) => d.toJSON());
     const offsets = documentLineOffsets(text);
@@ -117,7 +128,8 @@ export class Loader {
       }
     }
 
-    return resolved;
+    Loader.moduleCache.set(cacheKey, { text, manifests: resolved });
+    return cloneManifestArray(resolved);
   }
 
   async loadModuleGraph(
@@ -215,6 +227,32 @@ export class Loader {
   }
 }
 
+function cloneManifestArray(manifests: ResourceManifest[]): ResourceManifest[] {
+  return manifests.map((manifest) => cloneManifestValue(manifest));
+}
+
+function cloneManifestValue<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneManifestValue(entry)) as T;
+  }
+  if (isCompiledValue(value)) {
+    return value;
+  }
+  if (value !== null && typeof value === "object") {
+    const source = value as Record<string, unknown>;
+    const clone: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(source)) {
+      clone[key] = cloneManifestValue(entry);
+    }
+    const positionIndex = Object.getOwnPropertyDescriptor(source, "positionIndex");
+    if (positionIndex) {
+      Object.defineProperty(clone, "positionIndex", positionIndex);
+    }
+    return clone as T;
+  }
+  return value;
+}
+
 function documentLineOffsets(text: string): number[] {
   const offsets = [0];
   const lines = text.split("\n");

package/src/schema-compat.ts

@@ -14,6 +14,7 @@ export function createAjv(): InstanceType<typeof Ajv> {
 }
 
 const ajv = createAjv();
+const compiledSchemaValidators = new WeakMap<Record<string, any>, ReturnType<typeof ajv.compile>>();
 
 export interface CompatibilityResult {
   compatible: boolean;
@@ -131,11 +132,14 @@ export interface SchemaIssue {
 
 /** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
 export function validateAgainstSchema(data: unknown, schema: Record<string, any>): SchemaIssue[] {
-  let validate: ReturnType<typeof ajv.compile>;
-  try {
-    validate = ajv.compile(schema);
-  } catch {
-    return [];
+  let validate = compiledSchemaValidators.get(schema);
+  if (!validate) {
+    try {
+      validate = ajv.compile(schema);
+      compiledSchemaValidators.set(schema, validate);
+    } catch {
+      return [];
+    }
   }
   if (validate(data)) return [];
   return (validate.errors ?? []).map((err: any) => ({
@@ -260,25 +264,55 @@ export function celPlaceholderForSchema(schema: Record<string, any>): unknown {
 
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 
+/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
+function resolveRef(schema: Record<string, any>, root: Record<string, any>): Record<string, any> {
+  if (schema.$ref && typeof schema.$ref === "string" && schema.$ref.startsWith("#/$defs/")) {
+    const defName = schema.$ref.slice("#/$defs/".length);
+    const resolved = root.$defs?.[defName];
+    if (resolved) return resolved;
+  }
+  return schema;
+}
+
+/** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
+function collectProperties(schema: Record<string, any>): Record<string, any> {
+  const props: Record<string, any> = { ...(schema.properties ?? {}) };
+  for (const sub of schema.oneOf ?? schema.anyOf ?? []) {
+    if (sub && typeof sub === "object" && sub.properties) {
+      for (const [k, v] of Object.entries(sub.properties as Record<string, any>)) {
+        if (!(k in props)) props[k] = v;
+      }
+    }
+  }
+  return props;
+}
+
 /** Deep-clone `data`, replacing every pure CEL template string (`${{ expr }}`) with a
  *  schema-appropriate placeholder so AJV can validate non-CEL fields without false positives. */
-export function substituteCelFields(data: unknown, schema: Record<string, any>): unknown {
+export function substituteCelFields(
+  data: unknown,
+  schema: Record<string, any>,
+  rootSchema?: Record<string, any>,
+): unknown {
+  const root = rootSchema ?? schema;
+  const resolved = resolveRef(schema, root);
+
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
-    return celPlaceholderForSchema(schema);
+    return celPlaceholderForSchema(resolved);
   }
   if (Array.isArray(data)) {
-    const itemSchema = (schema.items ?? {}) as Record<string, any>;
-    return data.map((item) => substituteCelFields(item, itemSchema));
+    const itemSchema = resolveRef((resolved.items ?? {}) as Record<string, any>, root);
+    return data.map((item) => substituteCelFields(item, itemSchema, root));
   }
   if (data !== null && typeof data === "object") {
-    const props = (schema.properties ?? {}) as Record<string, any>;
+    const props = collectProperties(resolved);
     const addlProps =
-      schema.additionalProperties && typeof schema.additionalProperties === "object"
-        ? (schema.additionalProperties as Record<string, any>)
+      resolved.additionalProperties && typeof resolved.additionalProperties === "object"
+        ? (resolved.additionalProperties as Record<string, any>)
         : undefined;
     const result: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
-      result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}) as Record<string, any>);
+      result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}) as Record<string, any>, root);
     }
     return result;
   }

package/src/types.ts

@@ -8,6 +8,9 @@ export const DiagnosticSeverity = {
 } as const;
 export type DiagnosticSeverity = (typeof DiagnosticSeverity)[keyof typeof DiagnosticSeverity];
 
+/** Default entry-point filename when a directory is given instead of a file. */
+export const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
+
 export interface Position {
   /** 0-based line number */
   line: number;

package/src/validate-references.ts

@@ -134,10 +134,22 @@ export function validateReferences(
         if (!val) continue;
 
         // Name-only reference (plain string) — look up by name to validate.
+        // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
+        // extract the resource name from the last dot segment.
         if (typeof val === "string") {
+          const lastDot = val.lastIndexOf(".");
+          const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
+          const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
           const target =
-            byName.get(val) ?? visibleScopeManifests.find((m) => m.metadata?.name === val);
+            byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
           if (!target) {
+            // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
+            // The resource lives in the imported module's scope and can't be validated here.
+            // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
+            // kinds — those must be validated.
+            if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
+              continue;
+            }
             diagnostics.push({
               severity: DiagnosticSeverity.Error,
               code: "UNRESOLVED_REFERENCE",