@telorun/analyzer 0.11.0 → 0.12.1

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;
 }
 
@@ -139,6 +146,10 @@ export function validateAgainstSchema(data: unknown, schema: Record<string, any>
       validate = ajv.compile(schema);
       compiledSchemaValidators.set(schema, validate);
     } catch {
+      // A schema that won't compile is reported loudly (once, on the owning
+      // definition) by the analyzer's definition-schema compile check
+      // (`DefinitionRegistry.schemaCompileError`), so returning `[]` here does
+      // not silently accept resources of that kind.
       return [];
     }
   }
@@ -266,7 +277,7 @@ 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> {
+export 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];
@@ -276,7 +287,7 @@ function resolveRef(schema: Record<string, any>, root: Record<string, any>): Rec
 }
 
 /** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
-function collectProperties(schema: Record<string, any>): Record<string, any> {
+export 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) {
@@ -301,6 +312,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

@@ -119,6 +119,11 @@ export function pathMatchesScope(exprPath: string, scope: string): boolean {
  *   `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.
+ *
  * - `x-telo-context-ref-from`: existing form — reads `{kind, name}` object from
  *   `manifestItem.<path>`, looks up the named manifest, returns its `<subpath>` field.
  *
@@ -153,8 +158,16 @@ export function resolveContextAnnotations(
   }
 
   const fromRoot = schema["x-telo-context-from-root"] as string | undefined;
-  const fromRefKind = schema["x-telo-context-from-ref-kind"] as string | undefined;
-  if (fromRoot || fromRefKind) {
+  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>
@@ -163,22 +176,22 @@ export function resolveContextAnnotations(
         return resolved;
       }
     }
-    if (fromRefKind && defs) {
-      const hashIdx = fromRefKind.indexOf("#");
-      if (hashIdx > 0) {
+    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) {
-          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;
-          }
+        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;
         }
       }
     }

package/src/validate-nested-inline.ts

@@ -0,0 +1,158 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { collectRefs, isInlineResource } from "./reference-field-map.js";
+import {
+  collectProperties,
+  resolveRef,
+  substituteCelFields,
+  validateAgainstSchema,
+} from "./schema-compat.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** Minimal view of a definition needed to validate an inline resource's config. */
+export interface InlineDefinitionLookup {
+  (kind: string): { schema?: Record<string, any> } | undefined;
+}
+
+/**
+ * Validates inline resources nested inside a resource body against their kind's
+ * config schema. The per-resource walk in `analyze()` validates a resource's
+ * own top-level config; inline resources at `x-telo-ref` slots reachable only
+ * through a local `$ref` (notably `Run.Sequence`'s `steps[].invoke`, hidden
+ * behind `#/$defs/step`) never reach the reference field map, so they would
+ * otherwise escape schema validation — e.g. `invoke: { kind: Console.ReadLine,
+ * prompt: "…" }`, where `prompt` belongs in the step's `inputs`, not the config.
+ *
+ * Walks the manifest data together with its definition schema, resolving local
+ * `$ref`s (so step trees of arbitrary depth are covered). At each `x-telo-ref`
+ * slot holding an inline resource, the inline's config is validated against its
+ * own kind's schema, then recursed into so inline resources nested inside
+ * inline resources are covered.
+ *
+ * Non-mutating: reads `manifest` and emits diagnostics anchored to its identity
+ * and a concrete dotted path matching the position-index key format;
+ * `rewriteSyntheticOrigins` reroutes those on inline-extracted (synthetic)
+ * manifests back to the root doc.
+ */
+export function validateNestedInlineResources(
+  manifest: ResourceManifest,
+  rootSchema: Record<string, any>,
+  lookupDefinition: InlineDefinitionLookup,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+  const resource = { kind: manifest.kind, name: manifest.metadata?.name as string };
+  const filePath = (manifest.metadata as { source?: string } | undefined)?.source;
+
+  function validateInline(inline: Record<string, any>, path: string): void {
+    const kind = inline.kind as string;
+    const def = lookupDefinition(kind);
+    // Unknown kind: these `$ref`-hidden slots are invisible to the field-map
+    // driven reference checks too, so nothing else would flag it — report here.
+    if (!def) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "UNDEFINED_KIND",
+        source: SOURCE,
+        message: `${resource.kind}/${resource.name}: inline ${kind} at '${path}': No Telo.Definition found for kind '${kind}'.`,
+        data: { resource, filePath, path: `${path}.kind` },
+      });
+      return;
+    }
+    // Kind exists but declares no config schema (e.g. a pure Telo.Type): no
+    // config to validate and no schema-declared slots to nest resources in.
+    if (!def.schema) return;
+    const schema = def.schema;
+    // `kind` / `metadata` are implicit on every resource; inject them so a
+    // strict `additionalProperties: false` config schema doesn't reject them.
+    const effectiveSchema =
+      schema.additionalProperties === false
+        ? {
+            ...schema,
+            properties: {
+              kind: { type: "string" },
+              metadata: { type: "object" },
+              ...schema.properties,
+            },
+          }
+        : schema;
+    // Inline resources omit `metadata` — it is synthesized when the kernel
+    // registers them (and by `normalizeInlineResources` for extracted slots,
+    // which assigns a derived `metadata.name`). Config schemas conventionally
+    // declare `required: ["metadata", …]` with `metadata.name` required, so add
+    // a placeholder before validating to mirror the post-registration shape.
+    const existingMeta =
+      inline.metadata && typeof inline.metadata === "object"
+        ? (inline.metadata as Record<string, unknown>)
+        : {};
+    const data = { ...inline, metadata: { name: "__inline__", ...existingMeta } };
+    const substituted = substituteCelFields(data, effectiveSchema, effectiveSchema);
+    for (const issue of validateAgainstSchema(substituted, effectiveSchema)) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "SCHEMA_VIOLATION",
+        source: SOURCE,
+        message: `${resource.kind}/${resource.name}: inline ${kind} at '${path}': ${issue.message}`,
+        data: { resource, filePath, path: issue.path ? `${path}.${issue.path}` : path },
+      });
+    }
+    // Recurse into the inline body against its own schema so deeper inline
+    // resources (e.g. an inline Run.Sequence's own steps) are validated too.
+    walk(inline, schema, schema, path);
+  }
+
+  function walk(
+    data: unknown,
+    schema: Record<string, any> | undefined,
+    schemaRoot: Record<string, any>,
+    path: string,
+  ): void {
+    if (!schema || typeof schema !== "object") return;
+    const resolved = resolveRef(schema, schemaRoot);
+
+    // Reference slot: the value is either a named reference (`{kind, name}`,
+    // validated as its own manifest) or an inline resource to validate here.
+    if (collectRefs(resolved).length > 0) {
+      if (
+        data &&
+        typeof data === "object" &&
+        !Array.isArray(data) &&
+        isInlineResource(data as Record<string, unknown>)
+      ) {
+        validateInline(data as Record<string, any>, path);
+      }
+      return;
+    }
+
+    if (Array.isArray(data)) {
+      const itemSchema = resolved.items as Record<string, any> | undefined;
+      if (!itemSchema) return;
+      for (let i = 0; i < data.length; i++) {
+        walk(data[i], itemSchema, schemaRoot, `${path}[${i}]`);
+      }
+      return;
+    }
+
+    if (data && typeof data === "object") {
+      const props = collectProperties(resolved);
+      const additional =
+        resolved.additionalProperties &&
+        typeof resolved.additionalProperties === "object" &&
+        !Array.isArray(resolved.additionalProperties)
+          ? (resolved.additionalProperties as Record<string, any>)
+          : undefined;
+      // Descend only where the schema declares structure. Freeform fields
+      // (`additionalProperties: true`, e.g. step `inputs`) carry caller data
+      // that may coincidentally look like `{kind: …}`; not descending there
+      // keeps the inline-resource detection anchored to real ref slots.
+      for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+        const propSchema = props[key] ?? additional;
+        if (!propSchema) continue;
+        walk(value, propSchema as Record<string, any>, schemaRoot, path ? `${path}.${key}` : key);
+      }
+    }
+  }
+
+  walk(manifest, rootSchema, rootSchema, "");
+  return diagnostics;
+}

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;
+}