@telorun/analyzer 0.10.1 → 0.12.0

package/src/residual-schema.ts

@@ -0,0 +1,49 @@
+/**
+ * Build the residual JSON Schema for a `variables` / `secrets` entry.
+ *
+ * For Telo.Application env-binding entries (those with an `env:` key), strips
+ * the kernel-specific wrapper keys `env` and `default` — `default` here is
+ * the *fallback host value* the kernel coerces when the env var is unset, not
+ * a JSON Schema annotation, so it must not leak into the validator.
+ *
+ * For Telo.Library entries (no `env:`), passes the entry through unchanged.
+ * Library `default:` is a standard JSON Schema annotation and stays.
+ *
+ * Single source of truth for "residual schema" referenced by both the
+ * analyzer's CEL globals normalization and the kernel's runtime env-var
+ * resolver — keeping them aligned prevents the two surfaces from drifting.
+ */
+export function residualEntrySchema(
+  entry: Record<string, unknown> | null | undefined,
+): Record<string, unknown> {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return { type: "object", additionalProperties: true };
+  }
+  const isAppEnvBinding = "env" in entry;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(entry)) {
+    if (isAppEnvBinding && (key === "env" || key === "default")) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Apply `residualEntrySchema` to every entry in a `variables` / `secrets` map.
+ * Returns a property-map suitable for use as the inner schema of CEL's
+ * `variables` / `secrets` namespaces.
+ */
+export function residualEntrySchemaMap(
+  entries: Record<string, unknown> | null | undefined,
+): Record<string, Record<string, unknown>> {
+  const out: Record<string, Record<string, unknown>> = {};
+  if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+    return out;
+  }
+  for (const [name, value] of Object.entries(entries)) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      out[name] = residualEntrySchema(value as Record<string, unknown>);
+    }
+  }
+  return out;
+}

package/src/resolve-ref-sentinels.ts

@@ -0,0 +1,127 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { isRefEntry } from "./reference-field-map.js";
+import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+
+/**
+ * Walks every `x-telo-ref` slot in every non-system resource and rewrites
+ * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ *
+ * The downstream pipeline (inline normalization, dependency graph, kernel
+ * controllers) expects every ref-slot value to be either a `{kind, name}`
+ * object, an inline-definition object, or a legacy bare string — resolving
+ * sentinels here keeps that contract intact so each consumer doesn't need
+ * its own sentinel branch.
+ *
+ * The walker assigns `kind` by name lookup (resource names are unique
+ * within a manifest scope). When the name doesn't resolve in the local
+ * `byName` map, the sentinel is left in place so `validateReferences`
+ * can emit the `UNRESOLVED_REFERENCE` diagnostic with full context.
+ *
+ * Mutation strategy: the field-path walker descends the resource tree
+ * directly and replaces the sentinel on its parent container. Re-parsing
+ * a string-encoded concrete path (the earlier shape) coupled the writer
+ * to the path-encoding rules of `resolveFieldEntries` — any new path
+ * marker would silently break this writer. Descending directly avoids
+ * that coupling.
+ */
+export function resolveRefSentinels(
+  resources: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases?: AliasResolver,
+  aliasesByModule?: Map<string, AliasResolver>,
+): void {
+  const byName = new Map<string, ResourceManifest>();
+  for (const r of resources) {
+    if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) {
+      byName.set(r.metadata.name as string, r);
+    }
+  }
+
+  for (const r of resources) {
+    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
+
+    const fieldMap =
+      aliases && aliasesByModule
+        ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
+        : registry.getFieldMapForKind(r.kind, aliases);
+    if (!fieldMap) continue;
+
+    for (const [fieldPath, entry] of fieldMap) {
+      if (!isRefEntry(entry)) continue;
+      replaceSentinelsAtPath(r as Record<string, unknown>, fieldPath, byName);
+    }
+  }
+}
+
+/** Walks `obj` along `fieldPath` (dot notation with `[]` for arrays and
+ *  `{}` for additionalProperties-typed maps) and replaces any `!ref`
+ *  sentinel value at the terminal slot with `{kind, name}` looked up
+ *  via `byName`. Mutates the parent container in place; no string-path
+ *  round-trip. */
+function replaceSentinelsAtPath(
+  obj: Record<string, unknown>,
+  fieldPath: string,
+  byName: Map<string, ResourceManifest>,
+): void {
+  const parts = fieldPath.split(".");
+  descend(obj, parts, byName);
+}
+
+function descend(
+  obj: unknown,
+  parts: string[],
+  byName: Map<string, ResourceManifest>,
+): void {
+  if (obj == null || typeof obj !== "object" || parts.length === 0) return;
+  const [head, ...rest] = parts;
+
+  // Map iteration: descend into every value of the current object.
+  if (head === "{}") {
+    const container = obj as Record<string, unknown>;
+    for (const key of Object.keys(container)) {
+      const child = container[key];
+      if (rest.length === 0) {
+        if (isRefSentinel(child)) {
+          const target = byName.get(child.source);
+          if (target) container[key] = { kind: target.kind as string, name: child.source };
+        }
+      } else {
+        descend(child, rest, byName);
+      }
+    }
+    return;
+  }
+
+  const isArr = head.endsWith("[]");
+  const key = isArr ? head.slice(0, -2) : head;
+  const container = obj as Record<string, unknown>;
+  const val = container[key];
+  if (val == null) return;
+
+  if (isArr) {
+    if (!Array.isArray(val)) return;
+    for (let i = 0; i < val.length; i++) {
+      if (rest.length === 0) {
+        const elem = val[i];
+        if (isRefSentinel(elem)) {
+          const target = byName.get(elem.source);
+          if (target) val[i] = { kind: target.kind as string, name: elem.source };
+        }
+      } else {
+        descend(val[i], rest, byName);
+      }
+    }
+  } else {
+    if (rest.length === 0) {
+      if (isRefSentinel(val)) {
+        const target = byName.get(val.source);
+        if (target) container[key] = { kind: target.kind as string, name: val.source };
+      }
+    } else {
+      descend(val, rest, byName);
+    }
+  }
+}

package/src/rewrite-synthetic-origins.ts

@@ -0,0 +1,75 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AnalysisDiagnostic } from "./types.js";
+
+interface XTeloOrigin {
+  parentKind: string;
+  parentName: string;
+  pathFromParent: string;
+}
+
+function readOrigin(manifest: ResourceManifest | undefined): XTeloOrigin | undefined {
+  if (!manifest) return undefined;
+  const origin = (manifest.metadata as { xTeloOrigin?: XTeloOrigin } | undefined)?.xTeloOrigin;
+  if (
+    !origin ||
+    typeof origin.parentKind !== "string" ||
+    typeof origin.parentName !== "string" ||
+    typeof origin.pathFromParent !== "string"
+  ) {
+    return undefined;
+  }
+  return origin;
+}
+
+/** Diagnostics emitted on synthetic manifests (resources extracted by
+ *  `normalizeInlineResources`) carry the synthetic's identity in
+ *  `data.resource`, which has no YAML source. Rewrite each such diagnostic
+ *  back to the chain root: walk up `metadata.xTeloOrigin` until a manifest
+ *  with no origin is reached, and prepend each hop's `pathFromParent` to
+ *  `data.path` so position-index lookups against the root doc resolve. */
+export function rewriteSyntheticOrigins(
+  diagnostics: AnalysisDiagnostic[],
+  manifests: ResourceManifest[],
+): AnalysisDiagnostic[] {
+  const byName = new Map<string, ResourceManifest>();
+  for (const m of manifests) {
+    const name = m.metadata?.name;
+    if (typeof name === "string") byName.set(name, m);
+  }
+
+  return diagnostics.map((d) => {
+    const data = d.data as
+      | { resource?: { kind?: string; name?: string }; path?: string; filePath?: string }
+      | undefined;
+    if (!data?.resource?.name) return d;
+
+    let current = byName.get(data.resource.name);
+    let origin = readOrigin(current);
+    if (!origin) return d;
+
+    let accumPath = typeof data.path === "string" ? data.path : "";
+    let rootKind: string = origin.parentKind;
+    let rootName: string = origin.parentName;
+
+    while (origin) {
+      accumPath = accumPath ? `${origin.pathFromParent}.${accumPath}` : origin.pathFromParent;
+      rootKind = origin.parentKind;
+      rootName = origin.parentName;
+      current = byName.get(origin.parentName);
+      origin = readOrigin(current);
+    }
+
+    const rootFilePath =
+      (current?.metadata as { source?: string } | undefined)?.source ?? data.filePath;
+
+    return {
+      ...d,
+      data: {
+        ...data,
+        resource: { kind: rootKind, name: rootName },
+        filePath: rootFilePath,
+        path: accumPath,
+      },
+    };
+  });
+}

package/src/schema-compat.ts

@@ -1,16 +1,23 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isTaggedSentinel } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema } from "@telorun/templating";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
 
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
- *  Called once for the module-level instance and once per DefinitionRegistry instance. */
+ *  Also registers the kernel manifest root schema under `telo://manifest` so
+ *  module YAMLs can `$ref` into the shared `$defs/ResourceRef` (and any future
+ *  shared fragments) from this analyzer's AJV without each module having to
+ *  bundle its own copy.
+ *
+ *  Called once for the module-level instance and once per
+ *  DefinitionRegistry instance. */
 export function createAjv(): InstanceType<typeof Ajv> {
   const instance = new Ajv({ allErrors: true, strict: false });
   (addFormats as any).default
     ? (addFormats as any).default(instance)
     : (addFormats as any)(instance);
+  instance.addSchema(ManifestRootSchema);
   return instance;
 }
 
@@ -301,6 +308,16 @@ export function substituteCelFields(
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
     return celPlaceholderForSchema(resolved);
   }
+  // `!ref <name>` sentinels are identity markers, not runtime values —
+  // schemas that opt into `$ref: "telo://manifest#/$defs/ResourceRef"`
+  // (or `anyOf` it alongside other shapes) need the actual sentinel
+  // object so AJV validates it against ResourceRefSchema. Collapsing it
+  // to a CEL placeholder would either fail the schema (when the slot
+  // expects the ResourceRef shape) or mask validation errors (when the
+  // slot expects something else entirely).
+  if (isRefSentinel(data)) {
+    return data;
+  }
   if (isTaggedSentinel(data)) {
     return celPlaceholderForSchema(resolved);
   }

package/src/system-kinds.ts

@@ -0,0 +1,37 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export const REF_VALIDATION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+]);
+
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export const DEPENDENCY_GRAPH_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Import",
+]);
+
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export const REF_RESOLUTION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+  "Telo.Import",
+]);

package/src/types.ts

@@ -81,6 +81,18 @@ export interface LoaderInitOptions {
 
 export interface AnalysisOptions {
   strictContexts?: boolean;
+  /** When true, `analyze()` runs the state-mutating setup (module identity /
+   *  alias / definition registration plus `normalizeInlineResources`) but
+   *  skips every diagnostic-producing pass — per-resource validation, the
+   *  Library `env:` check, `validateExtends`, `validateProviderCoherence`,
+   *  and `validateThrowsCoverage`. Used by the kernel when a previous load
+   *  has already stamped the manifest set as valid (by content hash), so
+   *  the registry still gets populated without paying the validation walk
+   *  on every cold start. The caller takes responsibility for the
+   *  correctness guarantee — pass this only when something durable
+   *  (on-disk stamp) attests that the manifests passed a real analyze
+   *  pass at the same analyzer / kernel version. */
+  skipValidation?: boolean;
 }
 
 /** Pre-seeded state for incremental analysis. Passed to StaticAnalyzer.analyze() so it does

package/src/validate-cel-context.ts

@@ -1,5 +1,21 @@
 export { extractAccessChains, validateChainAgainstSchema } from "@telorun/templating";
 
+export interface ContextResolveOpts {
+  /** When provided, used to resolve `x-telo-context-from-root` annotations against the
+   *  root manifest. When omitted, defaults to `manifestItem`. */
+  manifestRoot?: Record<string, any>;
+  /** When provided alongside `aliases`, used to resolve `x-telo-context-from-ref-kind`
+   *  annotations: read a kind name from a path on `manifestRoot` and return the
+   *  declared definition's `<field>` schema. */
+  defs?: {
+    resolve(kind: string): Record<string, any> | undefined;
+  };
+  aliases?: {
+    resolveKind(kind: string): string | undefined;
+  };
+  allManifests?: Record<string, any>[];
+}
+
 /**
  * Resolve a type field value (string name, inline type, or raw schema) to a JSON Schema.
  * - String: look up the named type in allManifests (Type.JsonSchema resources)
@@ -70,21 +86,66 @@ export function pathMatchesScope(exprPath: string, scope: string): boolean {
 }
 
 /**
- * Resolves `x-telo-context-from` annotations in a context schema using the concrete
- * manifest item. Navigates the manifest item at the given slash-separated path and merges
- * the result as named properties into the annotated node (locking additionalProperties: false).
+ * Resolves `x-telo-context-*` annotations in a context schema using the concrete
+ * manifest item (per-scope) and the manifest root.
+ *
+ * Annotation forms:
+ *
+ * - `x-telo-context-from`: navigates `manifestItem.<path>` and treats the resolved
+ *   value as a **property map** (keys → sub-schemas) that is merged into the
+ *   annotated node's properties. Used for HTTP-style scopes where the navigated
+ *   value is itself a map of variable names.
+ *
+ *   Example: `x-telo-context-from: "request/schema"` reads `manifestItem.request.schema`
+ *   (= `{ query: {...}, body: {...}, … }`) and merges those keys as named properties
+ *   of the context node.
+ *
+ * - `x-telo-context-from-root`: navigates `manifestRoot.<path>` and **replaces** the
+ *   annotated node's schema with the resolved value. Used on individual property
+ *   schemas (e.g. `properties.self`) where the resolved value is a single variable's
+ *   full schema, not a property map.
+ *
+ *   Example: `properties.self.x-telo-context-from-root: "schema"` reads
+ *   `manifestRoot.schema` and uses it as the schema of the `self` CEL variable.
+ *
+ * - `x-telo-context-from-ref-kind`: reads a kind name from `manifestRoot.<refPath>`,
+ *   resolves it via the definition registry, and returns that kind's `<field>` schema
+ *   (e.g. `outputType`/`inputType`). Used to type `result` against the dispatch
+ *   target's declared output shape.
+ *
+ *   Syntax: `<refPath>#<field>` — slashes traverse the manifest tree.
+ *
+ *   Example: `x-telo-context-from-ref-kind: "provide/kind#outputType"` reads
+ *   `manifestRoot.provide.kind` as a kind name, looks up the kind's Telo.Definition,
+ *   and returns the `outputType` schema.
+ *
+ *   Accepts either a single string or an array of strings. With an array, paths
+ *   are tried in order and the first one that resolves to a usable schema wins —
+ *   used by `result:` to find its dispatch target under whichever entry-point
+ *   field (`provide:` or `invoke:`) the definition declares.
  *
- * Example: `x-telo-context-from: "request/schema"` on the `request` context node replaces
- * the open `request` schema with a closed schema whose properties are the keys of
- * `manifestItem.request.schema` (e.g. `query`, `body`, `params`, `headers`).
+ * - `x-telo-context-ref-from`: existing form — reads `{kind, name}` object from
+ *   `manifestItem.<path>`, looks up the named manifest, returns its `<subpath>` field.
+ *
+ * **Fallback chain.** When both `x-telo-context-from-root` and
+ * `x-telo-context-from-ref-kind` are present on the same node, the resolver tries
+ * `from-root` first; if that produces no usable schema, it falls back to `from-ref-kind`.
+ * This lets a definition declare typing from its own field with a sibling-kind fallback
+ * (e.g. `inputType` direct → `extends`-declared abstract's `inputType`).
  */
 export function resolveContextAnnotations(
   schema: Record<string, any>,
   manifestItem: Record<string, any>,
-  allManifests?: Record<string, any>[],
+  opts?: ContextResolveOpts | Record<string, any>[],
 ): Record<string, any> {
   if (!schema || typeof schema !== "object") return schema;
 
+  // Back-compat: third positional arg used to be `allManifests: Record<string, any>[]`.
+  const normalizedOpts: ContextResolveOpts = Array.isArray(opts)
+    ? { allManifests: opts }
+    : (opts ?? {});
+  const { manifestRoot = manifestItem, defs, aliases, allManifests } = normalizedOpts;
+
   const from = schema["x-telo-context-from"] as string | undefined;
   if (from) {
     const resolved = navigatePath(manifestItem, from.split("/")) as Record<string, any> | undefined;
@@ -96,6 +157,48 @@ export function resolveContextAnnotations(
     };
   }
 
+  const fromRoot = schema["x-telo-context-from-root"] as string | undefined;
+  const fromRefKindRaw = schema["x-telo-context-from-ref-kind"] as
+    | string
+    | string[]
+    | undefined;
+  const fromRefKinds = fromRefKindRaw == null
+    ? []
+    : Array.isArray(fromRefKindRaw)
+      ? fromRefKindRaw
+      : [fromRefKindRaw];
+  if (fromRoot || fromRefKinds.length > 0) {
+    if (fromRoot) {
+      const resolved = navigatePath(manifestRoot, fromRoot.split("/")) as
+        | Record<string, any>
+        | undefined;
+      if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
+        return resolved;
+      }
+    }
+    if (defs) {
+      for (const fromRefKind of fromRefKinds) {
+        const hashIdx = fromRefKind.indexOf("#");
+        if (hashIdx <= 0) continue;
+        const refPath = fromRefKind.slice(0, hashIdx);
+        const field = fromRefKind.slice(hashIdx + 1);
+        const kindValue = navigatePath(manifestRoot, refPath.split("/"));
+        if (typeof kindValue !== "string" || kindValue.length === 0) continue;
+        const canonical = aliases?.resolveKind(kindValue) ?? kindValue;
+        const def = defs.resolve(canonical);
+        const typeField = def
+          ? (def as Record<string, unknown>)[field]
+          : undefined;
+        const resolved = resolveTypeFieldToSchema(typeField, allManifests ?? []);
+        if (resolved && typeof resolved === "object") {
+          return resolved;
+        }
+      }
+    }
+    // Open fallback so unresolved types never produce false-positive CEL diagnostics.
+    return { type: "object", additionalProperties: true };
+  }
+
   const refFrom = schema["x-telo-context-ref-from"] as string | undefined;
   if (refFrom && allManifests) {
     const slashIdx = refFrom.indexOf("/");
@@ -129,7 +232,7 @@ export function resolveContextAnnotations(
   if (schema.properties) {
     const props: Record<string, any> = {};
     for (const [k, v] of Object.entries(schema.properties)) {
-      props[k] = resolveContextAnnotations(v as Record<string, any>, manifestItem, allManifests);
+      props[k] = resolveContextAnnotations(v as Record<string, any>, manifestItem, normalizedOpts);
     }
     return { ...schema, properties: props };
   }

package/src/validate-provider-coherence.ts

@@ -0,0 +1,166 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Validates coherence rules for `Telo.Definition` documents that use the `provide:`
+ * template target, plus the implementation-presence rule on `Telo.Provider`
+ * definitions.
+ *
+ * Diagnostics:
+ *  - PROVIDE_ON_NON_PROVIDER: `provide:` declared on a definition whose
+ *    `capability` is not `Telo.Provider`.
+ *  - PROVIDE_DISPATCHER_CONFLICT: `provide:` co-exists with `invoke:` or `run:`
+ *    on the same definition.
+ *  - PROVIDE_TARGET_UNKNOWN: `provide.name` does not resolve to an entry in
+ *    `resources:`.
+ *  - PROVIDE_TARGET_NOT_INVOCABLE: `provide.name` resolves to a resource whose
+ *    kind is registered but not a `Telo.Invocable`.
+ *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
+ *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
+ */
+export function validateProviderCoherence(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  const importedModules = new Set<string>();
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Import") continue;
+    const resolved = (m.metadata as { resolvedModuleName?: string } | undefined)
+      ?.resolvedModuleName;
+    if (resolved) importedModules.add(resolved);
+  }
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Definition") continue;
+    const name = m.metadata?.name as string | undefined;
+    if (!name) continue;
+    const ownModule = (m.metadata as { module?: string } | undefined)?.module;
+    if (ownModule && importedModules.has(ownModule)) continue;
+    const filePath = (m.metadata as { source?: string } | undefined)?.source;
+    const resource = { kind: m.kind, name };
+    const label = `${m.kind}/${name}`;
+
+    const md = m as Record<string, unknown>;
+    const capability = typeof md.capability === "string" ? md.capability : undefined;
+    const provide = md.provide;
+    const invoke = md.invoke;
+    const run = md.run;
+    const controllers = md.controllers;
+    const resources = md.resources;
+
+    const hasProvide = provide !== undefined && provide !== null;
+    const hasInvoke = invoke !== undefined && invoke !== null;
+    const hasRun = run !== undefined && run !== null;
+    const hasControllers = Array.isArray(controllers) && controllers.length > 0;
+
+    if (hasProvide && capability !== "Telo.Provider") {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDE_ON_NON_PROVIDER",
+        source: SOURCE,
+        message:
+          `${label}: 'provide:' is only valid on definitions with 'capability: Telo.Provider' ` +
+          `(found '${capability ?? "<unset>"}'). Use 'invoke:' or 'run:' for other capabilities.`,
+        data: { resource, filePath, path: "provide" },
+      });
+    }
+
+    if (hasProvide && (hasInvoke || hasRun)) {
+      const conflict = hasInvoke ? "invoke" : "run";
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDE_DISPATCHER_CONFLICT",
+        source: SOURCE,
+        message:
+          `${label}: 'provide:' cannot co-exist with '${conflict}:'. ` +
+          `A definition declares exactly one dispatch entry-point.`,
+        data: { resource, filePath, path: "provide" },
+      });
+    }
+
+    if (hasProvide && typeof provide === "object" && !Array.isArray(provide)) {
+      const provideObj = provide as { kind?: unknown; name?: unknown };
+      const providedName = typeof provideObj.name === "string" ? provideObj.name : undefined;
+      const providedKind = typeof provideObj.kind === "string" ? provideObj.kind : undefined;
+      if (providedName && Array.isArray(resources)) {
+        const match = resources.find((r) => {
+          const meta = (r as { metadata?: { name?: unknown } })?.metadata;
+          return typeof meta?.name === "string" && meta.name === providedName;
+        }) as { kind?: unknown } | undefined;
+        if (!match) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "PROVIDE_TARGET_UNKNOWN",
+            source: SOURCE,
+            message:
+              `${label}: 'provide.name: ${providedName}' does not match any entry's ` +
+              `metadata.name in 'resources:'.`,
+            data: { resource, filePath, path: "provide.name" },
+          });
+        } else if (typeof match.kind === "string") {
+          // `provide.kind` is the type contract the analyzer uses to type
+          // `result` CEL against the target's `outputType`. The runtime
+          // dispatches on `provide.name` and ignores `provide.kind`, so a
+          // mismatch silently degrades `result` typing to an open schema
+          // (and at runtime quietly invokes the actually-matched resource).
+          // Flag the divergence so result-typing never lies.
+          if (providedKind) {
+            const providedCanonical = aliases.resolveKind(providedKind) ?? providedKind;
+            const matchCanonical = aliases.resolveKind(match.kind) ?? match.kind;
+            if (providedCanonical !== matchCanonical) {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDE_KIND_MISMATCH",
+                source: SOURCE,
+                message:
+                  `${label}: 'provide.kind: ${providedKind}' disagrees with the matched ` +
+                  `'resources:' entry's kind '${match.kind}' (matched by metadata.name ` +
+                  `'${providedName}'). The runtime dispatches by name, so 'provide.kind' ` +
+                  `is decorative — but the analyzer types 'result:' against it, and a ` +
+                  `mismatch silently turns off that typing.`,
+                data: { resource, filePath, path: "provide.kind" },
+              });
+            }
+          }
+          const resolvedKind = aliases.resolveKind(match.kind) ?? match.kind;
+          const targetDef = registry.resolve(resolvedKind) ?? registry.resolve(match.kind);
+          if (targetDef && targetDef.kind === "Telo.Definition") {
+            const targetCap = (targetDef as { capability?: unknown }).capability;
+            if (typeof targetCap === "string" && targetCap !== "Telo.Invocable") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDE_TARGET_NOT_INVOCABLE",
+                source: SOURCE,
+                message:
+                  `${label}: 'provide.name: ${providedName}' resolves to a ${match.kind} ` +
+                  `(capability '${targetCap}'); 'provide:' requires a Telo.Invocable target.`,
+                data: { resource, filePath, path: "provide.name" },
+              });
+            }
+          }
+        }
+      }
+    }
+
+    if (capability === "Telo.Provider" && !hasControllers && !hasProvide) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDER_MISSING_IMPLEMENTATION",
+        source: SOURCE,
+        message:
+          `${label}: 'capability: Telo.Provider' requires either 'controllers:' ` +
+          `(TS-backed) or 'provide:' (template-backed) to declare an implementation.`,
+        data: { resource, filePath, path: "capability" },
+      });
+    }
+  }
+
+  return diagnostics;
+}