@telorun/analyzer 0.70.0 → 0.72.0

package/src/types.ts

@@ -1,6 +1,6 @@
 import type { HostVersions } from "./requires-block.js";
 
-import type { ZoneModuleDocuments } from "./zone-module-documents.js";
+import type { ModuleDocuments } from "./module-documents.js";
 /** Matches LSP DiagnosticSeverity values exactly.
  *  https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticSeverity */
 export const DiagnosticSeverity = {
@@ -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;
 }
@@ -142,10 +160,10 @@ export interface AnalysisOptions {
   /** Imported libraries' FULL document sets, for the zone stage's per-library
    *  export derivation — the flattened analysis view forwards only each
    *  library's export surface, never its internal dispatch chain. Collected
-   *  from a LoadedGraph via `collectZoneModuleDocuments`. Omitting it skips
+   *  from a LoadedGraph via `collectModuleDocuments`. Omitting it skips
    *  the derivation (the under-approximating direction — the runtime check
    *  remains the enforcement). */
-  moduleDocuments?: ZoneModuleDocuments[];
+  moduleDocuments?: ModuleDocuments[];
   /** 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

package/src/validate-identifier-names.ts

@@ -1,8 +1,13 @@
-import type { ResourceManifest } from "@telorun/sdk";
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 
-import type { AliasResolver } from "./alias-resolver.js";
+import {
+  moduleScopedDefResolver,
+  type AliasResolver,
+  type ModuleScopes,
+} from "./alias-resolver.js";
 import type { CallGraph } from "./call-graph.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { inheritedCapability, type DefResolver } from "./extends-resolution.js";
 import {
   TYPE_LEVEL_DOC_KINDS,
   checkName,
@@ -44,8 +49,10 @@ export function validateIdentifierNames(
   aliases: AliasResolver,
   rootModules: Set<string>,
   graph: CallGraph,
+  scopes: ModuleScopes,
 ): AnalysisDiagnostic[] {
   const out: AnalysisDiagnostic[] = [];
+  const resolveDef = moduleScopedDefResolver<ResourceDefinition>(registry, aliases, scopes);
 
   for (const manifest of manifests) {
     const metadata = manifest.metadata as Record<string, unknown> | undefined;
@@ -65,7 +72,7 @@ export function validateIdentifierNames(
     const ownModule = metadata?.module as string | undefined;
     if (ownModule && !rootModules.has(ownModule)) continue;
 
-    const level = levelFor(manifest, registry, aliases);
+    const level = levelFor(manifest, resolveDef, ownModule);
     push(out, checkName(name, level, surfaceFor(manifest.kind)), {
       kind: manifest.kind,
       name,
@@ -126,20 +133,32 @@ export function validateIdentifierNames(
  * a resource. Capability-driven rather than by kind name, so no resource kind
  * is hardcoded here.
  *
+ * **The capability is the INHERITED one**, not the leaf declaration. Capability
+ * is inherited and immutable along `extends` — a kind omits it to take its
+ * ancestor's — so reading the leaf answers `undefined` for every kind that does,
+ * and the fallback then calls a type a value. That is not hypothetical: it is
+ * exactly `Type.JsonSchema`, a pure alias of the built-in (`extends:
+ * Telo.JsonSchema`, no `capability:` of its own), so a shape declared through
+ * the deprecated spelling was reported as miscased while the identical
+ * declaration written as `kind: Telo.JsonSchema` was not. Renaming on that
+ * report is worse than the warning: `extends:` between two named shapes is not a
+ * reference slot, so the inheritance edge does not move with the name.
+ *
  * An unresolvable kind falls back to value level — the honest default, since
  * `UNDEFINED_KIND` already reports the real problem and guessing type level
  * would stack a case error on top of it.
  */
 function levelFor(
   manifest: ResourceManifest,
-  registry: DefinitionRegistry,
-  aliases: AliasResolver,
+  resolveDef: DefResolver & { in(kind: string, module?: string): ResourceDefinition | undefined },
+  ownModule: string | undefined,
 ): NameLevel {
   if (TYPE_LEVEL_DOC_KINDS.has(manifest.kind as string)) return "type";
-  // The root resolver is the right one unconditionally: every manifest
-  // reaching here belongs to a root module, the others having been skipped.
-  const canonical = aliases.resolveKind(manifest.kind as string) ?? (manifest.kind as string);
-  return registry.resolve(canonical)?.capability === "Telo.Type" ? "type" : "value";
+  // The top-level lookup is in the module that WROTE the `kind:` — a root one,
+  // the others having been skipped above — while the chain walk re-scopes at
+  // every hop, since an `extends` alias belongs to the file declaring it.
+  const def = resolveDef.in(manifest.kind as string, ownModule);
+  return inheritedCapability(def, resolveDef) === "Telo.Type" ? "type" : "value";
 }
 
 /** The noun phrase a diagnostic uses as its subject. */

package/src/validate-invocation-contract.ts

@@ -2,13 +2,17 @@ import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
+  ancestorChain,
   type ContractDirection,
   type DefResolver,
   effectiveContractField,
   mappingFieldFor,
   needsContractMapping,
 } from "./extends-resolution.js";
+import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import { buildReferenceFieldMap, isRefEntry } from "./reference-field-map.js";
+import { checkSchemaCompatibility } from "./schema-compat.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -29,6 +33,11 @@ const SOURCE = "telo-analyzer";
  *    whose input contract is now `inputType:`.
  *  - CONTRACT_TYPE_NOT_FOUND: a contract names a type that is not declared in
  *    scope, so every call through it would fail at dispatch.
+ *  - CONTRACT_NOT_SUBSTITUTABLE: a definition replaces an ancestor's contract
+ *    with a shape that cannot stand in for it. The one check nothing else makes:
+ *    contracts resolve to the nearest declaration in BOTH halves, so a child that
+ *    declares its own is compared against its abstract by neither the analyzer
+ *    nor dispatch.
  *
  * Deliberately NOT diagnosed: an input that is neither `required:` nor
  * defaulted. It is indistinguishable from a genuinely optional one — `Ai.Text`
@@ -45,8 +54,7 @@ export function validateInvocationContract(
 ): AnalysisDiagnostic[] {
   const diagnostics: AnalysisDiagnostic[] = [];
   const resolveDef: DefResolver = (kind, from) => {
-    const module = (from?.metadata as { module?: string } | undefined)?.module;
-    const scope = (module ? aliasesByModule.get(module) : undefined) ?? aliases;
+    const scope = moduleAliasScope(from?.metadata, aliases, aliasesByModule);
     return registry.resolve(kind) ?? registry.resolve(scope.resolveKind(kind) ?? kind);
   };
 
@@ -73,6 +81,7 @@ export function validateInvocationContract(
     if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") {
       checkMappingRequired(m, resource, filePath, resolveDef, diagnostics);
       checkContractResolves(m, md, manifests, resource, filePath, diagnostics);
+      checkAncestorSubstitutability(m, md, manifests, resource, filePath, resolveDef, diagnostics);
       continue;
     }
 
@@ -360,6 +369,123 @@ function namedTypeReference(value: unknown): string | undefined {
   return typeof ref.name === "string" ? ref.name : undefined;
 }
 
+/**
+ * A REPLACING CONTRACT MUST STILL STAND IN FOR THE ONE IT REPLACES.
+ *
+ * Contracts resolve to the NEAREST declaration and never merge, which is right —
+ * a call signature is not additive, and a backend narrowing `status` to the
+ * states it actually has could not express that through a merge. But the
+ * consequence is that an abstract's contract binds only the children that
+ * declare none of their own: a child that declares one is checked against
+ * nothing, statically or at dispatch, since `resolveBoundContract` stops at the
+ * same nearest declaration. So an abstract could state a floor every
+ * implementation must answer with (`Durable.Run`'s `runId` / `status`, the
+ * identity every later question about a run is asked by) and have that floor hold
+ * for exactly the implementations that declared nothing — while the real ones,
+ * which all declare their own, escaped it. A slot typed by the abstract would
+ * then be typed by a promise nothing kept.
+ *
+ * The rule is substitutability, and its direction differs per contract because
+ * one is produced and the other consumed:
+ *
+ *  - `outputType` is COVARIANT — a consumer written against the ancestor reads
+ *    the ancestor's shape, so the child's output must be acceptable where the
+ *    ancestor's is declared. Dropping a required property is what breaks it.
+ *  - `inputType` is CONTRAVARIANT — a caller written against the ancestor sends
+ *    the ancestor's shape, so the ancestor's input must be acceptable where the
+ *    child's is declared. Requiring an input the ancestor never mentions is what
+ *    breaks it: no such caller could satisfy it.
+ *
+ * **Only an ABSTRACT ancestor's contract is a contract**, and that narrowing is a
+ * decision rather than an oversight. Extending a CONCRETE kind is how a friendlier
+ * schema is put over an existing controller — `base:` reshapes its config and
+ * `inputs:` / `result:` translate its call signature — so a child there is
+ * SUPPOSED to present different inputs, and demanding substitutability would
+ * reject the pattern the standard library and every custom-kind example are built
+ * on. An abstract has no implementation to reshape: extending one is a claim to
+ * BE the thing, its contract is written for implementors, and a slot typed by it
+ * is polymorphic by construction — which is exactly where an unkept promise has
+ * nowhere to be caught.
+ *
+ * A direction the child BRIDGES (`inputs:` for inputs, `result:` for outputs) is
+ * skipped for the same reason one hop down: the mapping is the author saying the
+ * shapes differ deliberately and are translated.
+ *
+ * The comparison is {@link checkSchemaCompatibility}, which reports only DEFINITE
+ * mismatches — a union, an absent `type`, an undeclared argument all read as
+ * compatible — so narrowing a value's type, adding an optional property or
+ * restricting an enum stays legal, which is the whole point of letting a child
+ * replace the contract at all.
+ */
+function checkAncestorSubstitutability(
+  m: ResourceManifest,
+  md: Record<string, unknown>,
+  manifests: ResourceManifest[],
+  resource: { kind: string; name: string },
+  filePath: string | undefined,
+  resolveDef: DefResolver,
+  diagnostics: AnalysisDiagnostic[],
+): void {
+  const def = m as unknown as ResourceDefinition;
+
+  for (const direction of ["inputType", "outputType"] as ContractDirection[]) {
+    const own = md[direction];
+    if (own === undefined || own === null) continue;
+    // A declared bridge says the shapes differ on purpose and are translated.
+    if (md[mappingFieldFor(direction)] != null) continue;
+
+    // The nearest ANCESTOR that declares it — the contract this one replaces.
+    // Walking past self is the whole question: `contractDeclarer` would answer
+    // "this one", which is what nothing checks.
+    const ancestor = ancestorChain(def, resolveDef).find((a) => {
+      const inherited = (a as unknown as Record<string, unknown>)[direction];
+      return inherited !== undefined && inherited !== null;
+    });
+    if (!ancestor || ancestor.kind !== "Telo.Abstract") continue;
+    const inherited = (ancestor as unknown as Record<string, unknown>)[direction];
+
+    // The WHOLE manifest set, which is what `analyzerContractScope`'s
+    // `typeManifestsFor` hands `resolveContract` — so this resolves a named type
+    // exactly as the resolver the kernel binds with does. Filtering to the
+    // declaring module looked more careful and was strictly worse: a contract
+    // naming a shape from a shared module resolved to nothing, and an
+    // unresolvable side is skipped, so the check silently switched itself off for
+    // precisely the libraries that factor their shapes out. Nothing else caught
+    // it either — `CONTRACT_TYPE_NOT_FOUND` finds the type through its own global
+    // fallback, so such a kind passed `telo check` with no diagnostic at all.
+    const ownSchema = resolveTypeFieldToSchema(own, manifests);
+    const ancestorSchema = resolveTypeFieldToSchema(inherited, manifests);
+    // An unresolvable side says nothing about compatibility; CONTRACT_TYPE_NOT_FOUND
+    // is what reports a contract that names a type nothing declares.
+    if (!ownSchema || !ancestorSchema) continue;
+
+    const { compatible, issues } =
+      direction === "outputType"
+        ? checkSchemaCompatibility(ownSchema, ancestorSchema)
+        : checkSchemaCompatibility(ancestorSchema, ownSchema);
+    if (compatible) continue;
+
+    const ancestorName = `${(ancestor.metadata as { module?: string } | undefined)?.module ?? ""}.${
+      ancestor.metadata?.name ?? "?"
+    }`.replace(/^\./, "");
+    const why =
+      direction === "outputType"
+        ? `every caller that holds this through '${ancestorName}' reads the shape that kind declares`
+        : `a caller that holds this through '${ancestorName}' sends the shape that kind declares`;
+    diagnostics.push({
+      severity: DiagnosticSeverity.Error,
+      code: "CONTRACT_NOT_SUBSTITUTABLE",
+      source: SOURCE,
+      message:
+        `${m.kind}/${resource.name}: \`${direction}\` replaces the one declared by '${ancestorName}' ` +
+        `with a shape that cannot stand in for it — ${issues.join("; ")}. Contracts replace rather ` +
+        `than merge, so nothing re-checks this at dispatch: ${why}. Restate the fields ` +
+        `'${ancestorName}' declares, or drop \`${direction}\` to inherit the contract unchanged.`,
+      data: { resource, filePath, path: direction },
+    });
+  }
+}
+
 /** A child that inherits its controller and REPLACES a contract must bridge it:
  *  contracts resolve to the nearest declaration and never merge, so the
  *  inherited controller only understands its own shape. Without the mapping the

package/src/validate-logging.ts

@@ -3,6 +3,7 @@ import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { parseRedactionPath, RedactionPathError } from "./redaction-path.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 const SOURCE = "telo-analyzer";
 
@@ -124,9 +125,7 @@ function isSinkKind(
 ): boolean {
   if (typeof manifest.kind !== "string") return false;
   if (manifest.kind === "Telo.ConsoleSink" || manifest.kind === "Telo.FileSink") return true;
-  const ownModule = (manifest.metadata as { module?: string } | undefined)?.module;
-  const resolver =
-    (ownModule ? aliasesByModule?.get(ownModule) : undefined) ?? aliases;
+  const resolver = moduleAliasScope(manifest.metadata, aliases, aliasesByModule);
   const canonical = resolver.resolveKind(manifest.kind) ?? manifest.kind;
   return registry.resolve(canonical)?.capability === "Telo.Sink";
 }

package/src/validate-ref-slots.ts

@@ -38,7 +38,9 @@ export interface RefSlotIssue {
     | "X_TELO_REF_MISSING_USE"
     | "X_TELO_REF_MISSING_KIND"
     | "X_TELO_REF_USE_CONFLICT"
-    | "X_TELO_REF_DYNAMIC_SELECTOR";
+    | "X_TELO_REF_DYNAMIC_SELECTOR"
+    | "X_TELO_REF_UNKNOWN_KEY"
+    | "X_TELO_REF_INVALID_THROWS_THROUGH";
   /** The definition (schema issues) or resource (selector issues) at fault. */
   manifest: ResourceManifest;
   /** Schema path of the slot (schema issues) or concrete value path of the
@@ -140,9 +142,47 @@ function checkAnnotation(
     }
   }
 
+  // `throwsThrough` is read as `=== true`, so anything else is silently absent —
+  // and absent means the declaring resource's catch scope stops enclosing what
+  // it holds, so every route under it starts reporting UNCOVERED_THROW_CODE with
+  // nothing naming the cause. The same failure `X_TELO_REF_INVALID_USE` exists
+  // to prevent, one key over.
+  if (obj.throwsThrough !== undefined && typeof obj.throwsThrough !== "boolean") {
+    issues.push({
+      code: "X_TELO_REF_INVALID_THROWS_THROUGH",
+      manifest,
+      path,
+      message:
+        `x-telo-ref at '${path}' declares 'throwsThrough: ${JSON.stringify(obj.throwsThrough)}', ` +
+        `which is not a boolean. Only 'true' declares that throws from this slot's target ` +
+        `surface through the declaring resource; anything else reads as absent, which ` +
+        `silently stops its catch list from enclosing what it holds.`,
+    });
+  }
+
+  // Closed, for the reason the token sets are: a misspelled key is indexed by
+  // nothing and read by nothing, so it validates, ships, and does exactly what
+  // omitting it would.
+  for (const key of Object.keys(obj)) {
+    if (REF_ANNOTATION_KEYS.has(key)) continue;
+    issues.push({
+      code: "X_TELO_REF_UNKNOWN_KEY",
+      manifest,
+      path,
+      message:
+        `x-telo-ref at '${path}' declares unrecognized key '${key}'. Known keys: ` +
+        `${[...REF_ANNOTATION_KEYS].sort().join(", ")}. An unrecognized key is read by nothing, ` +
+        `so it has exactly the effect of leaving it out.`,
+    });
+  }
+
   return declaredUses(use);
 }
 
+/** Every key the structured `x-telo-ref` form accepts — the write side of
+ *  `readRefSlot`'s read side. Adding one belongs in both. */
+const REF_ANNOTATION_KEYS = new Set(["kind", "use", "inputs", "throwsThrough"]);
+
 /** True when a node is a reference slot: it carries `x-telo-ref` directly or on
  *  an `anyOf`/`oneOf` branch. */
 function carriesRefAnnotation(obj: Record<string, unknown>): boolean {

package/src/validate-references.ts

@@ -14,6 +14,8 @@ import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisContext } from "./types.js";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
+import { isInjectedDeclaration } from "./resource-input.js";
 
 const SOURCE = "telo-analyzer";
 
@@ -27,20 +29,31 @@ const SOURCE = "telo-analyzer";
  *
  * A value satisfies the slot when it transitively extends the target kind, or —
  * for a CONCRETE target — IS that kind; `getByExtends` is the same transitive
- * subtype index for both, and an abstract is satisfied only by an implementer,
- * never by the abstract itself (which is non-instantiable). Accepts a constraint
- * that resolves to nothing, and an abstract with no loaded implementations:
- * partial context, where a rejection would be a guess.
+ * subtype index for both. Accepts a constraint that resolves to nothing, and an
+ * abstract with no loaded implementations: partial context, where a rejection
+ * would be a guess.
+ *
+ * An abstract is satisfied only by an implementer, never by the abstract itself,
+ * because a resource declared `kind: <some abstract>` is refused at `create()`
+ * and reported as `ABSTRACT_KIND_INSTANTIATED` at its declaration — so accepting
+ * it here would leave the reference sites silent about a manifest that cannot
+ * run. `isDeclaration` is the ONE exception and it is not an instance: a
+ * library's `resources:` entry is constrained by kind alone, so its kind-only
+ * stand-in routinely IS an abstract (`connection: {kind: Sql.Connection}`), and
+ * every use of that name inside the library is a reference to it.
  */
 export function kindSatisfies(
   resolved: string,
   targetKind: string,
   registry: DefinitionRegistry,
+  /** The referent is a kind-only stand-in for a `resources:` entry rather than a
+   *  resource anything instantiates, so identity satisfies an abstract slot. */
+  isDeclaration = false,
 ): boolean {
   const canonical = registry.resolveRef(targetKind) ?? targetKind;
   const targetDef = registry.resolve(canonical);
   if (!targetDef) return true;
-  if (targetDef.kind !== "Telo.Abstract" && resolved === canonical) return true;
+  if ((targetDef.kind !== "Telo.Abstract" || isDeclaration) && resolved === canonical) return true;
   const subtypes = registry.getByExtends(canonical);
   if (subtypes.some((d) => `${d.metadata.module}.${d.metadata.name}` === resolved)) return true;
   // Leniency is about the CANDIDATE, not about the population, and it is the
@@ -70,6 +83,8 @@ function checkKind(
   entry: RefFieldEntry,
   registry: DefinitionRegistry,
   aliases: AliasResolver,
+  /** See {@link kindSatisfies}: the referent is a `resources:` stand-in. */
+  isDeclaration = false,
 ): string[] {
   const resolved = aliases.resolveKind(kind) ?? kind;
   // A qualified kind whose prefix names no import in this scope is a bad NAME
@@ -92,7 +107,7 @@ function checkKind(
     if (!targetKind) return [];
     const targetDef = registry.resolve(targetKind);
     if (!targetDef) return [];
-    if (!unknownAlias && kindSatisfies(resolved, targetKind, registry)) return [];
+    if (!unknownAlias && kindSatisfies(resolved, targetKind, registry, isDeclaration)) return [];
     const subtypes = registry.getByExtends(targetKind);
     const subtypeKinds = new Set(subtypes.map((d) => `${d.metadata.module}.${d.metadata.name}`));
     if (targetDef.kind === "Telo.Abstract") {
@@ -335,7 +350,13 @@ export function validateReferences(
             });
             return;
           }
-          const kindErrors = checkKind(target.kind as string, entry, registry, aliases);
+          const kindErrors = checkKind(
+            target.kind as string,
+            entry,
+            registry,
+            aliases,
+            isInjectedDeclaration(target),
+          );
           if (kindErrors.length > 0) {
             diagnostics.push({
               severity: DiagnosticSeverity.Error,
@@ -385,7 +406,18 @@ export function validateReferences(
         }
 
         // 2. Kind check
-        const kindErrors = checkKind(refVal.kind, entry, registry, aliases);
+        const objectTarget =
+          typeof refVal.name === "string"
+            ? (visibleScopeManifests.find((m) => m.metadata?.name === refVal.name) ??
+              byName.get(refVal.name))
+            : undefined;
+        const kindErrors = checkKind(
+          refVal.kind,
+          entry,
+          registry,
+          aliases,
+          isInjectedDeclaration(objectTarget),
+        );
         if (kindErrors.length > 0) {
           diagnostics.push({
             severity: DiagnosticSeverity.Error,
@@ -484,9 +516,7 @@ export function validateReferences(
           const resolvedResourceKind = aliases.resolveKind(r.kind) ?? r.kind;
           const resourceDef =
             registry.resolve(r.kind) ?? registry.resolve(resolvedResourceKind);
-          const owningModule = (resourceDef?.metadata as { module?: string } | undefined)?.module;
-          const ownerScope =
-            (owningModule ? aliasesByModule?.get(owningModule) : undefined) ?? aliases;
+          const ownerScope = moduleAliasScope(resourceDef?.metadata, aliases, aliasesByModule);
 
           const targetKind = ownerScope.resolveKind(anchorName);
           if (!targetKind) {
@@ -532,14 +562,44 @@ export function validateReferences(
 
           for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
             if (fieldValue == null) continue;
-            const issues = registry.validateWithRefs(fieldValue, subSchema as Record<string, any>);
+            // CEL leaves become schema-shaped placeholders first, exactly as the
+            // sibling-ref branch below does and for the same reason: a slot
+            // anchored at a shared value-shape is overwhelmingly written as
+            // expressions, so validating it raw reports every one of them as a
+            // type error and the check fires only on the literal case nobody
+            // writes. Omitting it here made one annotation mean two different
+            // things depending on which branch resolved it — a `when:` typed
+            // `boolean` accepted a `!cel` at a route's inline slot and rejected
+            // the identical expression at a slot anchored on the carrier that
+            // declares that very shape.
+            const substituted = substituteCelFields(
+              fieldValue,
+              subSchema as Record<string, any>,
+            );
+            // Anchored at the offending node INSIDE the value, not at the slot:
+            // a `returns:` list is an array of entries, and reporting every one
+            // of its issues on the `returns:` line puts three diagnostics on one
+            // line and none on the entry that is wrong.
+            const issues = registry.validateResourceConfig(
+              substituted,
+              subSchema as Record<string, any>,
+            );
             for (const issue of issues) {
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
                 code: "DEPENDENT_SCHEMA_MISMATCH",
                 source: SOURCE,
-                message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
-                data: { resource: resourceData, filePath, path: concretePath },
+                message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue.message}`,
+                data: {
+                  resource: resourceData,
+                  filePath,
+                  // An index-first sub-path (`[0].content`) joins with no dot.
+                  path: !issue.path
+                    ? concretePath
+                    : issue.path.startsWith("[")
+                      ? `${concretePath}${issue.path}`
+                      : `${concretePath}.${issue.path}`,
+                },
               });
             }
           }

package/src/validate-resource-inputs.ts

@@ -3,7 +3,11 @@ import { isRefSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { findDynamicLeaf } from "./resource-rule.js";
-import { readResourceInputs, readSuppliedResources } from "./resource-input.js";
+import {
+  isInjectedDeclaration,
+  readResourceInputs,
+  readSuppliedResources,
+} from "./resource-input.js";
 import { type AnalysisDiagnostic, DiagnosticSeverity } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -38,6 +42,9 @@ type RequiredResources = Record<string, string>;
  *
  * Browser-safe.
  */
+const declaringModule = (m: ResourceManifest): string | undefined =>
+  (m.metadata as { module?: string } | undefined)?.module;
+
 export function validateResourceInputs(
   manifests: ResourceManifest[],
   registry: DefinitionRegistry,
@@ -46,7 +53,11 @@ export function validateResourceInputs(
   /** Kind acceptance, transitively — the `checkKind` rule `validate-references`
    *  applies at an ordinary ref slot, passed in rather than re-derived so the
    *  two cannot disagree about what satisfies a constraint. */
-  acceptsKind: (suppliedKind: string, requiredKind: string) => boolean,
+  acceptsKind: (
+    suppliedKind: string,
+    requiredKind: string,
+    suppliedIsDeclaration: boolean,
+  ) => boolean,
 ): AnalysisDiagnostic[] {
   const out: AnalysisDiagnostic[] = [];
 
@@ -220,7 +231,19 @@ export function validateResourceInputs(
       const suppliedKind = (value as { kind?: unknown }).kind;
       if (typeof suppliedKind !== "string") continue;
       const canonical = aliases.resolveKind(suppliedKind) ?? suppliedKind;
-      if (acceptsKind(canonical, entry)) continue;
+      // A library forwarding an input it was itself handed supplies a kind-only
+      // stand-in, whose kind is routinely the abstract the target declares. That
+      // is identity against an abstract, which an ordinary reference is refused
+      // — the referent there would be a resource nothing can instantiate, while
+      // here it is another declaration.
+      const suppliedName = (value as { name?: unknown }).name;
+      const supplied =
+        typeof suppliedName === "string"
+          ? manifests.find(
+              (c) => c.metadata?.name === suppliedName && isOwn(declaringModule(c)),
+            )
+          : undefined;
+      if (acceptsKind(canonical, entry, isInjectedDeclaration(supplied))) continue;
       out.push({
         severity: DiagnosticSeverity.Error,
         code: "RESOURCE_INPUT_KIND_MISMATCH",

package/src/validate-schema-type-refs.ts

@@ -3,6 +3,7 @@ import { canonicalTypeSchemaId, parseTeloTypeRef } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 const SOURCE = "telo-analyzer";
 const SCHEMA_FIELDS = ["schema", "inputType", "outputType"] as const;
@@ -38,7 +39,7 @@ export function validateSchemaTypeRefs(
     // Only validate refs authored in a root module's scope; imported defs are
     // validated against their own library when it's analyzed as a root.
     if (ownModule && !rootModules.has(ownModule)) continue;
-    const resolver = (ownModule ? aliasesByModule.get(ownModule) : undefined) ?? aliases;
+    const resolver = moduleAliasScope(m.metadata, aliases, aliasesByModule);
     const filePath = (m.metadata as { source?: string } | undefined)?.source;
     const label = `${m.kind}/${name}`;