@telorun/analyzer 0.10.1 → 0.12.0

package/src/analyzer.ts

@@ -14,6 +14,9 @@ import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kerne
 import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
+import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
+import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
+import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import {
   celTypeSatisfiesJsonSchema,
   substituteCelFields,
@@ -28,11 +31,45 @@ import {
   resolveTypeFieldToSchema,
 } from "./validate-cel-context.js";
 import { validateExtends } from "./validate-extends.js";
+import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
 const SELF_PREFIX = "Self.";
 
+/**
+ * `StaticAnalyzer.analyze()` requires `metadata.source` (non-empty) and
+ * `metadata.sourceLine` (number) on every non-system manifest — see the
+ * JSDoc on `analyze()`. Production callers stamp these via the `Loader` /
+ * `flattenForAnalyzer` / `emitDocsFor` paths; programmatic callers (tests,
+ * scripts) should pre-process inputs with `withSyntheticPositions(...)`.
+ * Surfacing the violation here turns silent dedup misbehaviour into a
+ * loud, actionable error.
+ */
+function assertManifestPositions(manifests: ResourceManifest[]): void {
+  for (let i = 0; i < manifests.length; i++) {
+    const m = manifests[i];
+    if (REF_VALIDATION_SKIP_KINDS.has(m.kind)) continue;
+    const meta = m.metadata as { source?: string; sourceLine?: number } | undefined;
+    const okSource = typeof meta?.source === "string" && meta.source.length > 0;
+    const okLine = typeof meta?.sourceLine === "number";
+    if (okSource && okLine) continue;
+    const label = `${m.kind}/${m.metadata?.name ?? "(unnamed)"}`;
+    const missing = [
+      !okSource ? "metadata.source" : null,
+      !okLine ? "metadata.sourceLine" : null,
+    ]
+      .filter(Boolean)
+      .join(" and ");
+    throw new Error(
+      `StaticAnalyzer.analyze(): manifest #${i} (${label}) is missing ${missing}. ` +
+        `Real callers stamp positions automatically; programmatic callers ` +
+        `(tests, ad-hoc scripts) should pass inputs through ` +
+        `\`withSyntheticPositions(manifests)\` before calling analyze().`,
+    );
+  }
+}
+
 /** Resolve an alias-prefixed kind value (e.g. `Self.Encoder` or `Ai.Model`)
  *  to its canonical form. `Self.<Name>` resolves to `<ownModule>.<Name>` —
  *  the magic alias for "this library's own module" — and other prefixes
@@ -68,14 +105,108 @@ function lookupDefinitionTypeField(
 
 const SOURCE = "telo-analyzer";
 
+/** Build a closed JSON Schema for the `self` CEL variable available inside a
+ *  `Telo.Definition` template body. Mirrors the runtime template controller's
+ *  `const self = { ...resource, name: resource.metadata.name };` — every
+ *  property the user declared in `schema:` plus synthetic `name` / `kind` and
+ *  the metadata sub-object (kept open since metadata legitimately carries
+ *  arbitrary user-added fields). */
+function buildSelfSchema(definition: Record<string, any>): Record<string, any> {
+  const userSchema = (definition.schema ?? {}) as Record<string, any>;
+  const userProps = (userSchema.properties ?? {}) as Record<string, any>;
+  const userRequired = Array.isArray(userSchema.required) ? userSchema.required : [];
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      ...userProps,
+      name: { type: "string" },
+      kind: { type: "string" },
+      metadata: {
+        type: "object",
+        additionalProperties: true,
+        properties: { name: { type: "string" } },
+      },
+    },
+    required: [...userRequired, "name", "kind"],
+  };
+}
+
+/** Build the JSON Schema for the `inputs` CEL variable available inside an
+ *  invocable template body. Three-layer fallback mirroring the runtime's
+ *  caller-supplied inputs:
+ *    1. The definition's own `inputType:` field (preferred).
+ *    2. The `extends:`-declared abstract's `inputType:` (so a concrete
+ *       definition inheriting a contract gets typed inputs without
+ *       redeclaring them).
+ *    3. Undefined — caller signals opaque `map<string, dyn>` upstream. */
+function lookupTemplateInputsSchema(
+  definition: Record<string, any>,
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  allManifests: Record<string, any>[],
+): Record<string, any> | undefined {
+  const own = resolveTypeFieldToSchema(definition.inputType, allManifests);
+  if (own) return own;
+  const ext = definition.extends as string | undefined;
+  if (typeof ext === "string" && ext.length > 0) {
+    const canonical = aliases.resolveKind(ext) ?? ext;
+    const abstractDef = defs.resolve(canonical);
+    if (abstractDef) {
+      const inherited = resolveTypeFieldToSchema(
+        (abstractDef as unknown as Record<string, unknown>).inputType,
+        allManifests,
+      );
+      if (inherited) return inherited;
+    }
+  }
+  return undefined;
+}
+
+/** Returns a "resolver-facing" view of the manifest where the fields used as
+ *  navigation roots by Telo.Definition's `x-telo-context-from-root` annotations
+ *  have been pre-augmented:
+ *    - `schema`     → augmented `self` schema (synthetic `name`/`kind`/metadata).
+ *    - `inputType`  → resolved with extends fallback when the field isn't
+ *                     declared directly on the definition.
+ *
+ *  For non-definition manifests the original object is returned. */
+function manifestRootForResolver(
+  m: Record<string, any>,
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  allManifests: Record<string, any>[],
+): Record<string, any> {
+  if (m.kind !== "Telo.Definition") return m;
+  const inputs = lookupTemplateInputsSchema(m, defs, aliases, allManifests);
+  return {
+    ...m,
+    schema: buildSelfSchema(m),
+    ...(inputs ? { inputType: inputs } : {}),
+  };
+}
+
 /**
  * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
  * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
  * the same format the analyzer uses for CEL context validation.
+ *
+ * Result is sorted by scope specificity (longer scope first) so that the
+ * per-expression resolver's first-match-wins logic picks the most-specific
+ * context. Without this, a broader ancestor scope (e.g. `$.resources[*]`)
+ * could shadow a narrower descendant scope whose activation differs.
  */
 function extractContextsFromSchema(
   schema: Record<string, any>,
   path = "$",
+): Array<{ scope: string; schema: Record<string, any> }> {
+  const all = collectContexts(schema, path);
+  return all.sort((a, b) => b.scope.length - a.scope.length);
+}
+
+function collectContexts(
+  schema: Record<string, any>,
+  path: string,
 ): Array<{ scope: string; schema: Record<string, any> }> {
   if (!schema || typeof schema !== "object") return [];
   const results: Array<{ scope: string; schema: Record<string, any> }> = [];
@@ -86,18 +217,18 @@ function extractContextsFromSchema(
 
   if (schema.properties) {
     for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
-      results.push(...extractContextsFromSchema(value, `${path}.${key}`));
+      results.push(...collectContexts(value, `${path}.${key}`));
     }
   }
 
   if (schema.items && typeof schema.items === "object") {
-    results.push(...extractContextsFromSchema(schema.items, `${path}[*]`));
+    results.push(...collectContexts(schema.items, `${path}[*]`));
   }
 
   for (const key of ["oneOf", "anyOf", "allOf"] as const) {
     if (Array.isArray(schema[key])) {
       for (const subschema of schema[key]) {
-        results.push(...extractContextsFromSchema(subschema, path));
+        results.push(...collectContexts(subschema, path));
       }
     }
   }
@@ -399,11 +530,27 @@ export class StaticAnalyzer {
     this.celEnv = buildCelEnvironment(options.celHandlers);
   }
 
+  /**
+   * Run static analysis over a flattened manifest list.
+   *
+   * **Contract**: every non-system manifest (anything outside `Telo.Definition`,
+   * `Telo.Abstract`) must carry `metadata.source` (non-empty string) and
+   * `metadata.sourceLine` (number). The dedup that backs
+   * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
+   * apart from a genuine collision, and downstream diagnostic positioning
+   * depends on them too. Real callers stamp positions already (the `Loader`,
+   * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+   * extension). Programmatic callers — tests, ad-hoc scripts — should pass
+   * their inputs through `withSyntheticPositions(...)` before calling
+   * `analyze()`. A missing position throws a clear error rather than
+   * silently producing wrong diagnostics.
+   */
   analyze(
     manifests: ResourceManifest[],
     options?: AnalysisOptions,
     registry?: AnalysisRegistry,
   ): AnalysisDiagnostic[] {
+    assertManifestPositions(manifests);
     const diagnostics: AnalysisDiagnostic[] = [];
 
     // Use pre-seeded registries from the provided AnalysisRegistry, or create fresh ones.
@@ -527,6 +674,22 @@ export class StaticAnalyzer {
     // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
     const allManifests = normalizeInlineResources(manifests, defs, aliases, aliasesByModule);
 
+    // Phase 2.5: resolve `!ref <name>` sentinels at every ref slot to canonical
+    // {kind, name} objects so downstream phases (validation, dependency graph,
+    // kernel controllers) see a uniform shape. Runs after normalize so both
+    // original and inline-extracted manifests have their sentinels resolved.
+    resolveRefSentinels(allManifests, defs, aliases, aliasesByModule);
+
+    // Trusted-input fast path: when the caller has already attested that
+    // this exact manifest set passes analysis (e.g. via the kernel's
+    // hash-stamped `.validated.json` cache), skip the validation walk.
+    // Registration of identities / aliases / definitions and inline-resource
+    // normalisation have already run above; that's all downstream
+    // consumers (prepare, init loop) require.
+    if (options?.skipValidation) {
+      return diagnostics;
+    }
+
     // Build a name→manifest map for looking up referenced resources
     const byName = new Map<string, ResourceManifest>();
     for (const m of allManifests) {
@@ -535,6 +698,35 @@ export class StaticAnalyzer {
       }
     }
 
+    // Library env: rejection — `env:` on a Library `variables` / `secrets`
+    // entry is forbidden. The Library entry schema is otherwise open so that
+    // any JSON Schema property schema is valid; this targeted check produces
+    // a clear diagnostic instead of a generic "additional property" error.
+    for (const m of allManifests) {
+      if (m.kind !== "Telo.Library") continue;
+      const filePath = (m.metadata as { source?: string } | undefined)?.source;
+      const moduleName = m.metadata?.name as string | undefined;
+      const resource = moduleName ? { kind: m.kind, name: moduleName } : undefined;
+      for (const block of ["variables", "secrets"] as const) {
+        const entries = (m as Record<string, any>)[block];
+        if (!entries || typeof entries !== "object" || Array.isArray(entries)) continue;
+        for (const [entryName, entry] of Object.entries(entries)) {
+          if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+          if ("env" in (entry as Record<string, unknown>)) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "LIBRARY_ENV_KEY_REJECTED",
+              source: SOURCE,
+              message:
+                `Telo.Library ${block}/${entryName}: 'env:' is only permitted on Telo.Application entries. ` +
+                `Libraries must receive values from importers via the parent manifest's variables / secrets block.`,
+              data: { resource, filePath, path: `${block}.${entryName}.env` },
+            });
+          }
+        }
+      }
+    }
+
     // Build typed kernel globals schema so x-telo-context chain validation
     // recognises variables, secrets, resources, env automatically
     const kernelGlobals = buildKernelGlobalsSchema(allManifests);
@@ -552,7 +744,11 @@ export class StaticAnalyzer {
         });
         continue;
       }
-      if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") {
+      // Abstracts carry only inputType / outputType schema fields and no template
+      // body — nothing for the per-resource walk to validate. Definitions are now
+      // walked: their template bodies (`resources` / `invoke` / `run` / `provide`)
+      // contain CEL that must be checked against `self` / `inputs` / `result`.
+      if (m.kind === "Telo.Abstract") {
         continue;
       }
 
@@ -612,6 +808,97 @@ export class StaticAnalyzer {
       // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
     }
 
+    // Template-body structural validations: check that template entry-points produce
+    // values matching the contract of their dispatch target and (for `provide:`)
+    // the abstract this definition `extends`. CEL fields inside the templated
+    // values are replaced with type-appropriate placeholders before AJV runs —
+    // same pattern as the per-resource schema validation above.
+    for (const m of allManifests) {
+      if (m.kind !== "Telo.Definition") continue;
+      const filePath = (m.metadata as { source?: string } | undefined)?.source;
+      const name = (m.metadata as any)?.name as string | undefined;
+      if (!name) continue;
+      const resource = { kind: m.kind, name };
+      const md = m as Record<string, any>;
+
+      const emitTargetMismatch = (
+        targetKind: string,
+        valueSchema: Record<string, any>,
+        value: unknown,
+        path: string,
+      ) => {
+        const substituted = substituteCelFields(value, valueSchema);
+        const issues = validateAgainstSchema(substituted, valueSchema);
+        for (const issue of issues) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "TEMPLATE_TARGET_MISMATCH",
+            source: SOURCE,
+            message: `${m.kind}/${name}: ${path} does not satisfy ${targetKind}'s contract: ${issue.message}`,
+            data: { resource, filePath, path: issue.path ? `${path}.${issue.path}` : path },
+          });
+        }
+      };
+
+      // Resolve the dispatch target's kind, if statically known. Object-form
+      // `invoke: { kind, name }` and `provide: { kind, name }` carry it; the
+      // string-form `invoke: "name"` does not (the matching resource entry would
+      // need to be located by expanded name — out of scope here).
+      const invoke = md.invoke;
+      const provide = md.provide;
+      let dispatchKind: string | undefined;
+      if (invoke && typeof invoke === "object" && !Array.isArray(invoke) && typeof invoke.kind === "string") {
+        dispatchKind = invoke.kind;
+      } else if (
+        provide &&
+        typeof provide === "object" &&
+        !Array.isArray(provide) &&
+        typeof provide.kind === "string"
+      ) {
+        dispatchKind = provide.kind;
+      }
+
+      // Top-level `inputs:` (sibling of `invoke:` / `provide:`) carries the
+      // values passed to the dispatch target's invoke(). Validate against the
+      // target's declared `inputType` when both sides have one.
+      if (dispatchKind && md.inputs && typeof md.inputs === "object") {
+        const targetSchema = lookupDefinitionTypeField(
+          dispatchKind,
+          "inputType",
+          defs,
+          aliases,
+          allManifests as Record<string, any>[],
+        );
+        if (targetSchema) {
+          emitTargetMismatch(dispatchKind, targetSchema, md.inputs, "inputs");
+        }
+      }
+
+      // Top-level `result:` is a post-call mapping that must satisfy the abstract
+      // this definition `extends` (`outputType`). It's a sibling of whichever
+      // dispatch entry-point declared a kind-typed target (`provide:` or
+      // `invoke:`). The target's outputType lives on the dispatcher's `kind`
+      // and is what `result` is typed against *inside* CEL — separate role.
+      const hasDispatchObject =
+        (provide && typeof provide === "object" && !Array.isArray(provide)) ||
+        (invoke && typeof invoke === "object" && !Array.isArray(invoke));
+      if (hasDispatchObject && md.result && typeof md.result === "object") {
+        const extendsValue = md.extends as string | undefined;
+        if (typeof extendsValue === "string" && extendsValue.length > 0) {
+          const abstractSchema = lookupDefinitionTypeField(
+            extendsValue,
+            "outputType",
+            defs,
+            aliases,
+            allManifests as Record<string, any>[],
+          );
+          if (abstractSchema) {
+            emitTargetMismatch(extendsValue, abstractSchema, md.result, "result");
+          }
+        }
+      }
+    }
+
     // Validate CEL syntax and context variable access in all manifests
     for (const m of allManifests) {
       const resource = { kind: m.kind, name: m.metadata?.name as string };
@@ -670,11 +957,18 @@ export class StaticAnalyzer {
           const manifestItem = matchedScope
             ? getManifestItem(path, matchedScope, m as Record<string, any>)
             : (m as Record<string, any>);
-          const resolvedContext = resolveContextAnnotations(
-            matchedContext,
-            manifestItem,
+          const rootForResolver = manifestRootForResolver(
+            m as Record<string, any>,
+            defs,
+            aliases,
             allManifests as Record<string, any>[],
           );
+          const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, {
+            manifestRoot: rootForResolver,
+            defs,
+            aliases,
+            allManifests: allManifests as Record<string, any>[],
+          });
           effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
         }
 
@@ -722,10 +1016,15 @@ export class StaticAnalyzer {
     // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
     diagnostics.push(...validateExtends(allManifests, defs, aliases));
 
+    // Validate provider coherence rules for `provide:` template-target definitions.
+    diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
+
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
 
-    return diagnostics;
+    // Reroute diagnostics on synthetic (inline-extracted) resources back to
+    // the chain root so position-index lookups land on the parent doc.
+    return rewriteSyntheticOrigins(diagnostics, allManifests);
   }
 
   analyzeErrors(
@@ -740,12 +1039,17 @@ export class StaticAnalyzer {
 
   normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[] {
     const ctx = registry._context();
-    return normalizeInlineResources(
+    const normalized = normalizeInlineResources(
       manifests,
       ctx.definitions!,
       ctx.aliases,
       ctx.aliasesByModule,
     );
+    // Resolve !ref sentinels after normalize so both the original and
+    // inline-extracted manifests get their refs canonicalized to
+    // {kind, name} for the kernel that consumes this output.
+    resolveRefSentinels(normalized, ctx.definitions!, ctx.aliases, ctx.aliasesByModule);
+    return normalized;
   }
 
   prepare(

package/src/builtins.ts

@@ -40,7 +40,126 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
     kind: "Telo.Definition",
     metadata: { name: "Definition", module: "Telo" },
     capability: "Telo.Template",
-    schema: { type: "object" },
+    // Top-level shape stays open (`additionalProperties: true`) so this change
+    // attaches x-telo-context annotations to known template-body fields without
+    // tightening the Telo.Definition shape itself. The annotations drive
+    // static CEL validation of expressions inside `resources:` / `invoke:` /
+    // `run:` / `provide:` / top-level `inputs:` / top-level `result:` against
+    // `self` (typed from `schema:`) and `inputs` (typed from `inputType:`,
+    // falling back to the extends-declared abstract).
+    //
+    // `inputs:` and `result:` live as top-level siblings of `invoke:` / `provide:`,
+    // matching how Run.Sequence steps factor dispatch from data. The dispatch
+    // entry-point (`invoke` / `provide` / `run`) determines how `inputs`/`result`
+    // are interpreted at runtime. See analyzer/nodejs/plans/template-internal-cel-validation.md.
+    schema: {
+      type: "object",
+      additionalProperties: true,
+      properties: {
+        resources: {
+          type: "array",
+          items: {
+            type: "object",
+            additionalProperties: true,
+            "x-telo-context": {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                self: { "x-telo-context-from-root": "schema" },
+                inputs: { "x-telo-context-from-root": "inputType" },
+              },
+            },
+          },
+        },
+        invoke: {
+          oneOf: [
+            {
+              type: "string",
+              "x-telo-context": {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  self: { "x-telo-context-from-root": "schema" },
+                },
+              },
+            },
+            {
+              type: "object",
+              additionalProperties: true,
+              properties: {
+                kind: { type: "string" },
+                name: {
+                  type: "string",
+                  "x-telo-context": {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                      self: { "x-telo-context-from-root": "schema" },
+                    },
+                  },
+                },
+              },
+            },
+          ],
+        },
+        provide: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            kind: { type: "string" },
+            name: {
+              type: "string",
+              "x-telo-context": {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  self: { "x-telo-context-from-root": "schema" },
+                },
+              },
+            },
+          },
+        },
+        run: {
+          type: "string",
+          "x-telo-context": {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              self: { "x-telo-context-from-root": "schema" },
+            },
+          },
+        },
+        inputs: {
+          type: "object",
+          additionalProperties: true,
+          "x-telo-context": {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              self: { "x-telo-context-from-root": "schema" },
+              inputs: { "x-telo-context-from-root": "inputType" },
+            },
+          },
+        },
+        result: {
+          type: "object",
+          additionalProperties: true,
+          "x-telo-context": {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              self: { "x-telo-context-from-root": "schema" },
+              result: {
+                "x-telo-context-from-ref-kind": [
+                  "provide/kind#outputType",
+                  "invoke/kind#outputType",
+                ],
+              },
+            },
+          },
+        },
+      },
+    },
   },
   {
     kind: "Telo.Definition",
@@ -101,6 +220,20 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             anyOf: [
               { type: "string", "x-telo-ref": "telo#Runnable" },
               { type: "string", "x-telo-ref": "telo#Service" },
+              // Post-resolution shape that `resolveRefSentinels`
+              // substitutes a `!ref <name>` sentinel into. The
+              // adjacent `x-telo-ref` constraints govern the kind
+              // check; this branch only admits the structural form so
+              // AJV doesn't reject a resolved ref.
+              {
+                type: "object",
+                required: ["kind", "name"],
+                properties: {
+                  kind: { type: "string" },
+                  name: { type: "string" },
+                },
+                additionalProperties: true,
+              },
             ],
           },
         },
@@ -108,6 +241,44 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
+        // Application-level environment contract. Each entry layers `env:`
+        // (required, names the source env var) and `default:` (optional, used
+        // when the env var is unset) on top of an open JSON Schema property
+        // schema. `type:` constrains the coercion rule applied to the raw env
+        // string (scalars per-type; `object` / `array` via JSON.parse with the
+        // matching top-level type). All other JSON Schema keywords are passed
+        // through unchanged and applied to the coerced value via the standard
+        // schema validator. See kernel/nodejs/src/application-env.ts.
+        variables: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            required: ["env", "type"],
+            properties: {
+              env: { type: "string" },
+              type: {
+                type: "string",
+                enum: ["string", "integer", "number", "boolean", "object", "array"],
+              },
+              default: {},
+            },
+          },
+        },
+        secrets: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            required: ["env", "type"],
+            properties: {
+              env: { type: "string" },
+              type: {
+                type: "string",
+                enum: ["string", "integer", "number", "boolean", "object", "array"],
+              },
+              default: {},
+            },
+          },
+        },
       },
       required: ["metadata"],
       additionalProperties: false,

package/src/definition-registry.ts

@@ -80,6 +80,21 @@ export class DefinitionRegistry {
    *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.
    *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
   registerModuleIdentity(namespace: string | null, moduleName: string): void {
+    // The "telo" identity is reserved for the Telo built-in module and gets
+    // populated automatically when a Telo.Abstract definition registers (see
+    // `register` below). A user app / library without a namespace must NOT
+    // claim it — silently overwriting the built-in entry breaks every
+    // x-telo-ref that resolves through "telo#…". Concretely, the
+    // `Http.Api.routes[].handler` slot in the http-server schema carries
+    // `x-telo-ref: "telo#Invocable"`. If the entry application is, say,
+    // `Telo.Application/HelloApi` (no namespace), this method previously
+    // overwrote `"telo" → "Telo"` with `"telo" → "HelloApi"`. The handler's
+    // ref then resolved to a nonexistent `HelloApi.Invocable`, the
+    // kind-mismatch check inside `validate-references.ts` short-circuited
+    // on partial context, and the analyzer reported zero issues for a
+    // manifest that explodes at runtime. Skip non-Telo no-namespace modules;
+    // they have no x-telo-ref identity to declare anyway.
+    if (!namespace && moduleName !== "Telo") return;
     const identity = namespace ? `${namespace}/${moduleName}` : "telo";
     this.identityMap.set(identity, moduleName);
     this.reverseIdentityMap.set(moduleName, identity);