@telorun/analyzer 0.71.0 → 0.73.0

package/src/release/workspace-schema.ts

@@ -0,0 +1,99 @@
+/**
+ * The shape of `telo-workspace.yaml`, declared as data.
+ *
+ * One declaration read by two consumers — the strict half that reports what a
+ * marker got wrong, and the editor's completion list. Two hand-maintained key
+ * lists drift, and the drift is silent in the worst direction: an editor
+ * offering a key the checker rejects.
+ *
+ * Written as JSON Schema because that is what the shape *is*, and because the
+ * `description` a completion item shows and the type a diagnostic names are the
+ * same two facts a schema already carries. It is not compiled by AJV — the
+ * strict half walks it, which is what lets a wrong value say `'registry' must be
+ * the publish destination base, as a string` instead of a keyword trace.
+ */
+
+export interface WorkspaceKeySchema {
+  readonly type: "string" | "string[]" | "entry[]";
+  readonly description: string;
+  /** Values worth offering at this key when nothing better is known. */
+  readonly examples?: readonly string[];
+}
+
+export interface WorkspaceBlockSchema {
+  readonly description: string;
+  readonly properties: Readonly<Record<string, WorkspaceKeySchema>>;
+}
+
+/**
+ * Every block, and every key in it, is optional — a marker whose whole content
+ * is comments is valid, and is what a runner seeds for the cache anchor alone.
+ */
+export const WORKSPACE_SCHEMA: Readonly<Record<string, WorkspaceBlockSchema>> = {
+  release: {
+    description: "How `telo release` behaves: where modules are, where they publish, and which of their paths are not release-relevant.",
+    properties: {
+      registry: {
+        type: "string",
+        description:
+          "Publish destination base. A module's ref is `<registry>/<its own directory name>`. Omitted: --registry, then TELO_OCI_REGISTRY, then the base each module's own ledger entry recorded.",
+        examples: ["oci://ghcr.io/telorun"],
+      },
+      ignore: {
+        type: "string[]",
+        description:
+          "Paths under a module whose changes are not release-relevant, so no changelog fragment is asked for. Module-relative, gitignore-style. Declaring it replaces the built-in default; [] ignores nothing.",
+        examples: ["**/tests/**", "**/docs/**", "**/plans/**", "**/README.md", "**/CHANGELOG.md"],
+      },
+      modules: {
+        type: "entry[]",
+        description:
+          "The subtrees that may hold modules — a place to look, never a module: what makes a directory a module is its telo.yaml. Workspace-relative, gitignore-style, last match wins. A bare string is an entry with no overrides.",
+      },
+    },
+  },
+  env: {
+    description: "How `telo run` resolves a manifest's environment.",
+    properties: {
+      roots: {
+        type: "string[]",
+        description:
+          "How far up the .env walk may climb. Workspace-relative, gitignore-style, matched against each ancestor directory; the nearest match stops the walk. Omitted: the walk stops at this file.",
+      },
+      files: {
+        type: "string[]",
+        description:
+          "Which files are collected in each directory, later winning within one directory. Filenames only — a / or a glob is an error. Declaring it replaces the default; [] collects none.",
+        examples: [".env", ".env.local"],
+      },
+    },
+  },
+};
+
+/** Keys a `release.modules` entry may carry in its object form. `path` is the
+ *  pattern; the rest override the block's own keys, key-wise. */
+export const MODULE_ENTRY_KEYS: Readonly<Record<string, WorkspaceKeySchema>> = {
+  path: {
+    type: "string",
+    description: "The gitignore-style pattern this entry matches modules with.",
+  },
+  registry: WORKSPACE_SCHEMA.release.properties.registry,
+  ignore: WORKSPACE_SCHEMA.release.properties.ignore,
+};
+
+export const WORKSPACE_BLOCKS: readonly string[] = Object.keys(WORKSPACE_SCHEMA);
+
+/** Built-in when `release.ignore` is absent. Every pattern carries `**\/` — the
+ *  anchoring at a module root is the defect this replaced, so anchoring some and
+ *  not others would reproduce it partially. */
+export const DEFAULT_RELEASE_IGNORE: readonly string[] = [
+  "**/tests/**",
+  "**/docs/**",
+  "**/plans/**",
+  "**/README.md",
+  "**/CHANGELOG.md",
+];
+
+/** Built-in when `env.files` is absent — the pair the walk hardcoded before it
+ *  was authorable, in the order it applied them. */
+export const DEFAULT_ENV_FILES: readonly string[] = [".env", ".env.local"];

package/src/resolve-throws-union.ts

@@ -4,7 +4,9 @@ import { scopeResolverForModule, type AliasResolver } from "./alias-resolver.js"
 import { resolveScopedName } from "./call-graph.js";
 import { refSentinelTarget, type RefSentinelTarget } from "./ref-sentinel-target.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { possibleUses, readRefSlot, transfersControl, type RefSlot } from "./ref-slot.js";
 import { readStepSlot } from "./step-slot.js";
+import { forEachDrivenSlot } from "./schema-walk.js";
 
 export interface ThrowsCodeMeta {
   data?: Record<string, any>;
@@ -263,6 +265,16 @@ export function resolveThrowsUnion(
   }
 }
 
+/**
+ * `throws.inherit: true` — the union a composer's own STEP BODIES reach.
+ *
+ * Deliberately steps only, and not every slot the resource drives: `inherit` is
+ * a DECLARATION that a kind's union is the union of what it dispatches, and a
+ * kind that does not make that claim must not have it inferred — a kind holding
+ * a `call` ref it catches internally would silently gain codes it never lets
+ * escape. What a CATCH SCOPE needs is a different question with a different
+ * answer, and it has its own resolver below.
+ */
 function resolveInherited(
   manifest: ResourceManifest,
   definition: ResourceDefinition,
@@ -284,6 +296,66 @@ function resolveInherited(
   return result;
 }
 
+/**
+ * The union a SCOPE-LEVEL `catches:` list can be asked to render — everything
+ * the resource it is written on drives, transitively.
+ *
+ * `x-telo-catches-for: ""` is itself the claim that this is the denominator, so
+ * nothing is inferred from a kind that did not opt in, and no definition has to
+ * declare a `throws:` block to carry a catch scope (the kernel forbids one on a
+ * `Telo.Service` and a `Telo.Mount`, and rightly: what a router renders is not
+ * what a router THROWS).
+ *
+ * Three edges, three answers. A **step body** contributes its own traversal,
+ * subtraction included. A **control-transferring ref** contributes the target's
+ * own declared union — a route handler is a leaf here, and asking what IT drives
+ * would credit this scope with codes the handler catches internally. A
+ * **`throwsThrough` ref** recurses, because the target is another scope on the
+ * same ladder: a server renders what its mounts' routes throw, not what the
+ * mounts themselves declare.
+ */
+export function resolveScopeUnion(
+  manifest: ResourceManifest,
+  definition: ResourceDefinition,
+  ctx: ResolveCtx,
+  seen: Set<ResourceManifest> = new Set(),
+): ThrowsUnion {
+  const result: ThrowsUnion = { codes: new Map(), unbounded: false };
+  if (seen.has(manifest)) return result;
+  seen.add(manifest);
+  const ownerModule = (manifest.metadata as { module?: string } | undefined)?.module;
+
+  forEachDrivenSlot(definition.schema, manifest, (driven) => {
+    if (driven.kind === "step") {
+      unionInto(
+        result,
+        collectStepArrayThrows(driven.data, driven.slot.invoke, undefined, ctx, ownerModule),
+      );
+      return;
+    }
+    if (driven.slot.throwsThrough) {
+      const target = resolveRefManifest(driven.data, ctx, ownerModule);
+      const targetDef = target
+        ? definitionFor(
+            target.kind,
+            ctx.defs,
+            ctx.aliases,
+            scopeResolverFor(ctx, (target.metadata as { module?: string } | undefined)?.module),
+          )
+        : undefined;
+      if (target && targetDef) unionInto(result, resolveScopeUnion(target, targetDef, ctx, seen));
+      // A target that cannot be resolved says nothing about what it throws, so
+      // the scope's union is no longer enumerable.
+      else result.unbounded = true;
+      return;
+    }
+    if (!possibleUses(driven.slot).some(transfersControl)) return;
+    unionInto(result, resolveRefTargetThrows(driven.data, ctx, ownerModule));
+  });
+
+  return result;
+}
+
 function collectStepArrayThrows(
   steps: unknown[],
   invokeField: string,
@@ -410,9 +482,32 @@ function resolveStepInvokeThrows(
   ctx: ResolveCtx,
   ownerModule: string | undefined,
 ): ThrowsUnion {
-  const invokeRef = step[invokeField];
-  if (!invokeRef || typeof invokeRef !== "object") return emptyUnion();
-  const invokedKind = invokeRef.kind as string | undefined;
+  return resolveRefTargetThrows(step[invokeField], ctx, ownerModule, () =>
+    resolvePassthroughAtCallSite(step, enclosingTryCodes),
+  );
+}
+
+/**
+ * The effective throw union behind a resolved reference value.
+ *
+ * Shared by both ways a resource drives another: a step's `invoke:` and a
+ * reference slot that carries throws. The two used to differ only in where the
+ * ref value was read from, and keeping one copy is what stops a router's
+ * denominator and a sequence's from disagreeing about what a name resolves to.
+ *
+ * `onPassthrough` is the one genuine difference: a passthrough kind's union is a
+ * property of the CALL SITE (`inputs.code`), which only a step has. A reference
+ * slot has no such site, so the union is unbounded there rather than guessed.
+ */
+function resolveRefTargetThrows(
+  refValue: unknown,
+  ctx: ResolveCtx,
+  ownerModule: string | undefined,
+  onPassthrough?: () => ThrowsUnion,
+): ThrowsUnion {
+  if (!refValue || typeof refValue !== "object" || Array.isArray(refValue)) return emptyUnion();
+  const ref = refValue as Record<string, any>;
+  const invokedKind = ref.kind as string | undefined;
   // A reference that still carries its parse-time sentinel — a library-internal
   // `!ref` inside a manifest forwarded into a consumer's flat set, where Phase
   // 2.5 had nothing to resolve it against. The target is in the declaring
@@ -422,7 +517,7 @@ function resolveStepInvokeThrows(
   // its consumer and get the consumer's `catches:` rejected for the code the
   // entry point documents.
   if (!invokedKind) {
-    const sentinel = refSentinelTarget(invokeRef);
+    const sentinel = refSentinelTarget(ref);
     if (!sentinel) return emptyUnion();
     const target = findSentinelTarget(ctx, sentinel, ownerModule);
     if (target) return resolveThrowsUnion(target, ctx);
@@ -430,32 +525,19 @@ function resolveStepInvokeThrows(
   }
 
   // The invoked kind's alias resolves in the OWNER manifest's lexical scope (the
-  // composer that declares the step), so a library's step referencing its own
+  // resource that declares the slot), so a library's step referencing its own
   // import resolves against that library, not the consumer.
   const scopeResolver = scopeResolverFor(ctx, ownerModule);
   const definition = definitionFor(invokedKind, ctx.defs, ctx.aliases, scopeResolver);
   if (!definition) return { codes: new Map(), unbounded: true };
 
   if (definition.throws?.passthrough) {
-    return resolvePassthroughAtCallSite(step, enclosingTryCodes);
+    return onPassthrough ? onPassthrough() : { codes: new Map(), unbounded: true };
   }
 
   // Named manifest: resolve the full chain (covers transitive inherit).
-  const invokeName = invokeRef.name as string | undefined;
-  if (invokeName) {
-    const scopedInvokedKind = scopeResolver?.resolveKind(invokedKind);
-    const target = findTarget(
-      ctx,
-      invokeName,
-      ownerModule,
-      (m) =>
-        m.kind === invokedKind ||
-        ctx.aliases.resolveKind(m.kind) === invokedKind ||
-        m.kind === ctx.aliases.resolveKind(invokedKind) ||
-        (scopedInvokedKind !== undefined && m.kind === scopedInvokedKind),
-    );
-    if (target) return resolveThrowsUnion(target, ctx);
-  }
+  const target = resolveRefManifest(ref, ctx, ownerModule);
+  if (target) return resolveThrowsUnion(target, ctx);
 
   // Fall back to the definition's own explicit codes. Mark unbounded when the
   // definition depends on call-site or transitive resolution we couldn't
@@ -466,6 +548,42 @@ function resolveStepInvokeThrows(
   return { codes, unbounded };
 }
 
+/**
+ * The manifest a resolved reference value names, in either shape it arrives in —
+ * a `{kind, name}` pair, or a `!ref` still carrying its parse-time sentinel.
+ *
+ * Exported because the catch-scope enclosure walk asks the same question about
+ * the same values; resolving a name twice by two rules is how two passes end up
+ * disagreeing about which resource a slot points at.
+ */
+export function resolveRefManifest(
+  refValue: unknown,
+  ctx: ResolveCtx,
+  ownerModule: string | undefined,
+): ResourceManifest | undefined {
+  if (!refValue || typeof refValue !== "object" || Array.isArray(refValue)) return undefined;
+  const ref = refValue as Record<string, any>;
+  const kind = ref.kind as string | undefined;
+  if (!kind) {
+    const sentinel = refSentinelTarget(ref);
+    return sentinel ? findSentinelTarget(ctx, sentinel, ownerModule) : undefined;
+  }
+  const name = ref.name as string | undefined;
+  if (!name) return undefined;
+  const scopeResolver = scopeResolverFor(ctx, ownerModule);
+  const scopedKind = scopeResolver?.resolveKind(kind);
+  return findTarget(
+    ctx,
+    name,
+    ownerModule,
+    (m) =>
+      m.kind === kind ||
+      ctx.aliases.resolveKind(m.kind) === kind ||
+      m.kind === ctx.aliases.resolveKind(kind) ||
+      (scopedKind !== undefined && m.kind === scopedKind),
+  );
+}
+
 /** Resolve a passthrough-style invocable at a specific call site. Recognised forms
  *  (see "passthrough: true" in the plan):
  *  - constant literal (no template) → `{ <literal> }`

package/src/schema-compat.ts

@@ -8,6 +8,7 @@ import {
 import {
   celBaseOfValueType,
   celTypeOfValueType,
+  isCompiledValue,
   readValueTypeSlot,
   valueBrandBases,
   valueTypeOf,
@@ -799,6 +800,18 @@ export function substituteCelFields(
     mark();
     return celPlaceholderForSchema(resolved);
   }
+  // The same fact in its third spelling. An expression reaches this walk as a
+  // `${{ … }}` string or a `!cel` sentinel BEFORE `precompileDoc`, and as a
+  // CompiledValue after — so a caller running under `compile: true` (every
+  // `telo run`, unlike `telo check`) handed one to AJV as a plain object, and a
+  // slot typed `boolean` rejected a `when:` the author wrote correctly. The
+  // kernel's `stripCompiledValues` has always substituted here; missing it on
+  // this side made one manifest mean two things depending on which command read
+  // it.
+  if (isCompiledValue(data)) {
+    mark();
+    return celPlaceholderForSchema(resolved);
+  }
   if (Array.isArray(data)) {
     const item = resolveRefIn((resolved.items ?? {}) as Record<string, any>, root, external);
     return data.map((element, i) =>

package/src/schema-error-report.ts

@@ -44,6 +44,13 @@ export interface SchemaIssue {
   message: string;
   /** Dotted path to the field (e.g. "config.handler"). Empty string means root. */
   path: string;
+  /** The AJV keyword that produced it, so a consumer can key on WHAT failed
+   *  rather than on how the sentence reads. Prose is the renderer's to change;
+   *  a caller matching on it breaks silently when it does, and mis-fires on any
+   *  other issue whose text happens to quote the same name. */
+  keyword?: string;
+  /** For `required`, the property that is missing. */
+  missingProperty?: string;
 }
 
 const UNION_KEYWORDS = new Set(["anyOf", "oneOf"]);
@@ -53,10 +60,42 @@ const UNION_KEYWORDS = new Set(["anyOf", "oneOf"]);
  *  further in. These are what make a branch implausible. */
 const SHAPE_KEYWORDS = new Set(["required", "type", "additionalProperties", "enum", "const"]);
 
+/** Keywords that exist to DISCRIMINATE, so a mismatch is positive evidence that
+ *  the value is not this branch — at any depth, not only at the union node.
+ *
+ *  Depth is otherwise the tiebreak, and it inverts exactly here: a branch that
+ *  agreed on the discriminator and failed one constraint reported at the union
+ *  node loses to every branch that disagreed about the discriminator one level
+ *  in. That is how a `capability: Telo.Service` document declaring a forbidden
+ *  key was reported as `/capability must be equal to constant` — naming neither
+ *  the key at fault nor a branch the value could ever have been. */
+const DISCRIMINATOR_KEYWORDS = new Set(["const", "enum"]);
+
+/** RFC 6901 escapes: `~1` is a literal `/` in the key, `~0` a literal `~`.
+ *  Decoded wherever a segment is shown or matched, because encoded it is not the
+ *  key the manifest holds — a content map (`application/json`) anchors nowhere
+ *  and reads wrong in the sentence. `~0` is expanded LAST, or `~01` would decode
+ *  to `/` instead of the literal `~1` it encodes. */
+function unescapeSegment(part: string): string {
+  return part.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** The whole pointer, segment by segment, for prose that quotes it verbatim. */
+function unescapePointer(pointer: string): string {
+  return pointer
+    .split("/")
+    .map((segment, i) => (i === 0 ? segment : unescapeSegment(segment)))
+    .join("/");
+}
+
 /* ------------------------------------------------------------------ prose */
 
 export function formatSingleError(err: AjvErrorLike): string {
-  const p = err.instancePath || "/";
+  // Unescaped for the same reason the path is: a reader acting on this sentence
+  // needs the key the manifest holds (`application/json`), not its RFC 6901
+  // encoding. Reporting one form in `path` and the other in `message` made one
+  // diagnostic disagree with itself.
+  const p = unescapePointer(err.instancePath || "") || "/";
   const params = err.params ?? {};
   switch (err.keyword) {
     case "additionalProperties":
@@ -67,6 +106,16 @@ export function formatSingleError(err: AjvErrorLike): string {
       return `${p} ${err.message ?? "is invalid"} (${(params.allowedValues as unknown[])?.join(" | ")})`;
     case "type":
       return `${p} must be ${params.type}${describeActual(err)}`;
+    // A `false` schema at a property is how a branch forbids a key it otherwise
+    // declares. AJV's own text ("boolean schema is false") describes the schema
+    // rather than the value, and the path is the only part a reader can act on.
+    case "false schema":
+      return `${p} is not allowed here`;
+    // `not:` says a forbidden shape matched, and AJV reports nothing about the
+    // inner schema — so the honest message says where, and no more. A branch
+    // that wants to name the key writes `properties: { <key>: false }` instead.
+    case "not":
+      return `${p} matches a shape that is not allowed here`;
     default:
       return `${p} ${err.message ?? "is invalid"}`;
   }
@@ -130,11 +179,13 @@ function describeAlternatives(errors: AjvErrorLike[], unionInstancePath: string)
 }
 
 /** Is this branch a plausible reading of the value — does it accept the value's
- *  shape at the union node itself, and only disagree further in? */
+ *  shape at the union node itself, and agree with every discriminator it pins? */
 function isPlausible(errors: AjvErrorLike[], unionInstancePath: string): boolean {
-  return !errors.some(
-    (e) => (e.instancePath || "") === unionInstancePath && SHAPE_KEYWORDS.has(e.keyword ?? ""),
-  );
+  return !errors.some((e) => {
+    const keyword = e.keyword ?? "";
+    if (DISCRIMINATOR_KEYWORDS.has(keyword)) return true;
+    return (e.instancePath || "") === unionInstancePath && SHAPE_KEYWORDS.has(keyword);
+  });
 }
 
 /**
@@ -392,7 +443,7 @@ export function ajvErrorToPath(err: AjvErrorLike): string {
   let result = "";
   for (const part of parts) {
     if (/^\d+$/.test(part)) result += `[${part}]`;
-    else result += result ? `.${part}` : part;
+    else result += result ? `.${unescapeSegment(part)}` : unescapeSegment(part);
   }
   if (err.keyword === "required" && err.params?.missingProperty) {
     const missing = err.params.missingProperty as string;
@@ -403,10 +454,15 @@ export function ajvErrorToPath(err: AjvErrorLike): string {
 
 /** Reduced, path-anchored issues — what a diagnostic list is built from. */
 export function schemaIssues(errors: AjvErrorLike[] | null | undefined): SchemaIssue[] {
-  return reduceSchemaErrors(errors).map((err) => ({
-    message: formatSingleError(err),
-    path: ajvErrorToPath(err),
-  }));
+  return reduceSchemaErrors(errors).map((err) => {
+    const missing = (err.params ?? {}).missingProperty;
+    return {
+      message: formatSingleError(err),
+      path: ajvErrorToPath(err),
+      ...(err.keyword ? { keyword: err.keyword } : {}),
+      ...(typeof missing === "string" ? { missingProperty: missing } : {}),
+    };
+  });
 }
 
 /** Reduced, rendered as one sentence — what a thrown runtime error carries. */

package/src/schema-keywords.ts

@@ -386,7 +386,10 @@ export const TELO_SCHEMA_ANNOTATIONS: Record<
   },
   "x-telo-catches-for": {
     title: "Catches for",
-    description: "Names the field whose failures this branch list handles.",
+    description:
+      "Whose failures this catch list renders: a sibling field naming the handler, " +
+      "or the EMPTY string for everything this resource drives — a scope-level list, " +
+      "which owes coverage of nothing itself and answers for every site it encloses.",
     type: "string",
   },
 };

package/src/schema-walk.ts

@@ -9,6 +9,8 @@
  * scope rule is consumed by the IDE, which must not pull the pass in behind it.
  */
 import { MANIFEST_SCHEMA_URI, ManifestRootSchema } from "./manifest-schemas.js";
+import { readRefSlot, type RefSlot } from "./ref-slot.js";
+import { readStepSlot, type StepSlot } from "./step-slot.js";
 
 /** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
  *  Non-refs and unresolved refs pass through unchanged. */
@@ -142,3 +144,57 @@ export function walkStepArray(
     }
   });
 }
+/** A slot through which a resource drives another. */
+export type DrivenSlot =
+  | { kind: "step"; slot: StepSlot; data: unknown[]; path: string }
+  | { kind: "ref"; slot: RefSlot; data: unknown; path: string };
+
+/**
+ * Every slot of one resource through which it drives another, schema and data in
+ * tandem.
+ *
+ * One traversal with two consumers — the inherited union here, and the catch
+ * scope enclosure in `validate-throws-coverage.ts` — because both ask the same
+ * structural question and two copies would eventually disagree about where the
+ * walk stops. It terminates on the manifest's own depth, and it stops AT a step
+ * slot (that traversal owns everything below it, `try`/`catch` subtraction
+ * included) and AT a reference slot (a resolved ref is a leaf, `{kind, name}`,
+ * with nothing beneath it to visit).
+ */
+export function forEachDrivenSlot(
+  schema: unknown,
+  data: unknown,
+  visit: (slot: DrivenSlot) => void,
+  path = "",
+): void {
+  if (!schema || typeof schema !== "object" || data === undefined || data === null) return;
+  const node = schema as Record<string, any>;
+
+  const stepSlot = readStepSlot(node);
+  if (stepSlot) {
+    if (Array.isArray(data)) visit({ kind: "step", slot: stepSlot, data, path });
+    return;
+  }
+
+  const refSlot = readRefSlot(node);
+  if (refSlot) {
+    visit({ kind: "ref", slot: refSlot, data, path });
+    return;
+  }
+
+  const props = node.properties as Record<string, any> | undefined;
+  if (props && typeof data === "object" && !Array.isArray(data)) {
+    const obj = data as Record<string, unknown>;
+    for (const [key, propSchema] of Object.entries(props)) {
+      if (obj[key] === undefined) continue;
+      forEachDrivenSlot(propSchema, obj[key], visit, path ? `${path}.${key}` : key);
+    }
+  }
+
+  if (node.items && Array.isArray(data)) {
+    for (const [i, item] of data.entries()) {
+      forEachDrivenSlot(node.items, item, visit, `${path}[${i}]`);
+    }
+  }
+}
+

package/src/telo-version.ts

@@ -6,4 +6,4 @@
 // written against, and every kernel in every language reports the same scale.
 
 /** The surface generation this analyzer implements. */
-export const TELO_SURFACE_VERSION = "0.87.0";
+export const TELO_SURFACE_VERSION = "0.89.0";

package/src/template-body.ts

@@ -1,4 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import type { ModuleScopes } from "./alias-resolver.js";
@@ -68,6 +69,30 @@ export function templateBodies(
   return out;
 }
 
+/** What a definition's dispatch slot names: the `resources:` entry a `!ref` at
+ *  `slot` (`invoke` / `provide` / `run` / `mount`) resolves to, with its kind.
+ *  The entry is matched by its LITERAL `metadata.name`; a slot holding anything
+ *  but a `!ref`, or naming no entry, resolves to nothing — `validate-template-body`
+ *  is what reports either. `Self.<entry>` is the explicit self-qualifier. */
+export function dispatchTargetOf(
+  definition: Record<string, any>,
+  slot: string,
+): { entry: Record<string, any> | undefined; kind: string; name: string } | undefined {
+  const value = definition[slot];
+  if (!isRefSentinel(value)) return undefined;
+  const source = value.source;
+  const name = source.startsWith("Self.") ? source.slice("Self.".length) : source;
+  const bodies = definition.resources;
+  if (!Array.isArray(bodies)) return undefined;
+  for (const body of bodies) {
+    if (!body || typeof body !== "object") continue;
+    const entry = body as Record<string, any>;
+    if (entry.metadata?.name !== name || typeof entry.kind !== "string") continue;
+    return { entry, kind: entry.kind, name };
+  }
+  return undefined;
+}
+
 /** True when a CEL path lies at or inside a body's own subtree. */
 export function pathInBody(path: string, prefix: string): boolean {
   return (

package/src/types.ts

@@ -11,6 +11,19 @@ export const DiagnosticSeverity = {
 } as const;
 export type DiagnosticSeverity = (typeof DiagnosticSeverity)[keyof typeof DiagnosticSeverity];
 
+/** Matches LSP DiagnosticTag values exactly.
+ *  https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticTag
+ *
+ *  Declared whole rather than trimmed to what Telo emits today, for the reason
+ *  the severity ladder above is: it is someone else's closed vocabulary, and a
+ *  partial copy of one is what drifts. `Unnecessary` (rendered faded) has an
+ *  obvious future consumer in the unused-declaration checks. */
+export const DiagnosticTag = {
+  Unnecessary: 1,
+  Deprecated: 2,
+} as const;
+export type DiagnosticTag = (typeof DiagnosticTag)[keyof typeof DiagnosticTag];
+
 /** Default entry-point filename when a directory is given instead of a file. */
 export const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
 
@@ -70,6 +83,11 @@ export interface AnalysisDiagnostic {
   /** e.g. "telo-analyzer" */
   source?: string;
   message: string;
+  /** What KIND of thing this is, orthogonal to how loudly it asks to be dealt
+   *  with. A deprecation is warning-grade *and* a deprecation; severity alone
+   *  can only say the first, which is why an editor renders a deprecated symbol
+   *  struck through rather than merely yellow. */
+  tags?: DiagnosticTag[];
   /** Telo-specific extras such as { resource: { kind, name }, path } */
   data?: unknown;
 }