@telorun/analyzer 0.62.0 → 0.63.0

package/src/analyzer.ts

@@ -51,8 +51,39 @@ import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
 import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
 import { resolveSchemaRefKinds, type RefConstraintIssue } from "./resolve-schema-ref-kinds.js";
 import { runZoneAnalysis, type ZoneExportCache } from "./resolve-zone-requirements.js";
+import { validateDurableRegions } from "./validate-durable-regions.js";
+import { validateZoneViolations } from "./validate-zone-violations.js";
 import { MANIFEST_SCHEMA_URI, ManifestRootSchema } from "./manifest-schemas.js";
 import { validateZoneSlotDeclarations, type ZoneSlotIssue } from "./validate-zone-slots.js";
+import {
+  validateSchemaProjection,
+  type SchemaProjectionIssue,
+} from "./validate-schema-projection.js";
+import {
+  evaluateResourceRules,
+  reportResourceRules,
+  reportUnexercisedRule,
+  ruleExercised,
+  validateResourceRuleDeclarations,
+  type ResourceRuleDiagnostic,
+  type ResourceRuleIssue,
+} from "./validate-resource-rules.js";
+import { readResourceRules, type ResourceRule } from "./resource-rule.js";
+import { readReferrerRules, type ReferrerRule } from "./referrer-rule.js";
+import {
+  evaluateReferrerRules,
+  referrerRuleExercised,
+  reportReferrerRules,
+  reportUnexercisedReferrerRule,
+  validateReferrerRuleDeclarations,
+  type Referrer,
+  type ReferrerRuleDiagnostic,
+  type ReferrerRuleIssue,
+} from "./validate-referrer-rules.js";
+import {
+  describeProjectionFailure,
+  type ProjectionFailure,
+} from "./schema-projection.js";
 import {
   validateDynamicSelectors,
   validateRefSlotDeclarations,
@@ -111,6 +142,7 @@ import { validateReferences } from "./validate-references.js";
 import { validateReferenceForms } from "./validate-reference-forms.js";
 import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
+import { readStepSlot } from "./step-slot.js";
 
 const SELF_PREFIX = "Self.";
 
@@ -373,7 +405,7 @@ export function gatherPropertySchemas(
 }
 
 /**
- * Generic, role-driven walk over an `x-telo-step-context` step array. Calls
+ * Generic, role-driven walk over a step array. Calls
  * `visit(step, stepPath)` for every step — top-level and nested through the
  * `x-telo-topology-role` forms (`branch`, `branch-list`, `case-map`). This is
  * the single definition of how steps nest, shared by `buildStepContextSchema`
@@ -440,7 +472,7 @@ export function walkStepArray(
 }
 
 /**
- * Build a `steps` context schema from `x-telo-step-context` annotation.
+ * Build a `steps` context schema for a kind's step body.
  * Walks each step in the manifest array, resolves the invoked resource's output
  * contract, and builds `steps.<name>.result` context entries.
  *
@@ -461,7 +493,7 @@ export function walkStepArray(
  *                    sub-properties (e.g. elseif: [{ if, then }]).
  *   - `case-map`   — value is an object whose values are step arrays (e.g. cases).
  * No specific Run.Sequence field name is hardcoded; any kind that uses
- * `x-telo-step-context` and tags its branch fields with these roles works.
+ * a step body and tags its branch fields with these roles works.
  */
 function buildStepContextSchema(
   manifest: Record<string, any>,
@@ -478,7 +510,7 @@ function buildStepContextSchema(
   const readingModule = (manifest.metadata as { module?: string } | undefined)?.module;
 
   for (const [fieldName, fieldSchema] of Object.entries(props)) {
-    const stepCtx = fieldSchema["x-telo-step-context"] as Record<string, string> | undefined;
+    const stepCtx = readStepSlot(fieldSchema);
     if (!stepCtx) continue;
 
     const invokeField = stepCtx.invoke;
@@ -647,7 +679,7 @@ const NO_ENTRY_POINT_CAPABILITIES = new Set([
 ]);
 
 /**
- * Validate `x-telo-step-context` step `invoke` references (e.g. `Run.Sequence`
+ * Validate step `invoke` references (e.g. `Run.Sequence`
  * steps).
  *
  * The reference field map deliberately does NOT descend into step `invoke`
@@ -666,7 +698,7 @@ const NO_ENTRY_POINT_CAPABILITIES = new Set([
  *     contract has no entry point → `REFERENCE_KIND_MISMATCH` (runtime
  *     `ERR_RESOURCE_NOT_INVOKABLE`).
  *
- * Generic and topology-driven — it walks steps via the same `x-telo-step-context`
+ * Generic and topology-driven — it walks steps via the same step-slot
  * / `x-telo-topology-role` annotations `buildStepContextSchema` uses (through the
  * shared `walkStepArray`), so nested branches (then/else/do/catch/cases) are
  * covered and no `Run.Sequence` field name is hardcoded. The cross-module
@@ -795,8 +827,7 @@ function validateStepInvokeReferences(
     for (const [fieldName, fieldSchema] of Object.entries(
       defSchema.properties as Record<string, any>,
     )) {
-      const stepCtx = fieldSchema["x-telo-step-context"] as Record<string, string> | undefined;
-      const invokeField = stepCtx?.invoke;
+      const invokeField = readStepSlot(fieldSchema)?.invoke;
       if (!invokeField) continue;
       const steps = m[fieldName];
       if (!Array.isArray(steps)) continue;
@@ -1253,14 +1284,18 @@ export class StaticAnalyzer {
           }
           seen.add(alias);
         }
-        if (alias && source) {
-          const targetModule =
-            resolvedModuleName ?? source.split("/").filter(Boolean).pop() ?? source;
+        // An import whose target identity was never established registers NO
+        // alias. The name is never guessed from the source string: a guess that
+        // is usually right is what turned "this import did not resolve" into an
+        // assertion that a published dependency was malformed, naming a module
+        // no registry could ever hold. With no alias, every use degrades to
+        // "cannot resolve alias '<X>'" — which points at the import the author
+        // has to fix, and which the loader has already reported on its own line.
+        if (alias && source && resolvedModuleName) {
+          const targetModule = resolvedModuleName;
           // Module identity is registered globally so x-telo-ref resolution sees
           // transitively-imported modules regardless of which scope brought them in.
-          if (resolvedModuleName) {
-            defs.registerModuleIdentity(resolvedNamespace ?? null, resolvedModuleName);
-          }
+          defs.registerModuleIdentity(resolvedNamespace ?? null, resolvedModuleName);
           // `metadata.reExportedKinds` (stamped by flattenForAnalyzer / the editor projection)
           // maps an exported suffix to the true owning module's canonical kind for kinds this
           // import transitively re-exports (`exports.kinds: [Alias.Kind]`).
@@ -1318,6 +1353,61 @@ export class StaticAnalyzer {
     const refConstraintIssues: RefConstraintIssue[] = [];
     const refSlotIssues: RefSlotIssue[] = [];
     const zoneSlotIssues: ZoneSlotIssue[] = [];
+    // One place a rule report becomes a diagnostic. The pass decided WHAT and
+    // WHERE; this only carries it across to the diagnostic shape.
+    const SEVERITY = {
+      error: DiagnosticSeverity.Error,
+      warning: DiagnosticSeverity.Warning,
+      information: DiagnosticSeverity.Information,
+    } as const;
+    const resourceRuleDiagnostic = (report: ResourceRuleDiagnostic): AnalysisDiagnostic => ({
+      severity: SEVERITY[report.severity],
+      code: report.code,
+      source: SOURCE,
+      message: report.message,
+      data: {
+        resource: {
+          kind: report.manifest.kind,
+          name: report.manifest.metadata?.name as string,
+        },
+        filePath: (report.manifest.metadata as { source?: string } | undefined)?.source,
+        path: report.path,
+        rule: report.rule,
+      },
+    });
+    const referrerRuleDiagnostic = (report: ReferrerRuleDiagnostic): AnalysisDiagnostic => ({
+      severity: SEVERITY[report.severity],
+      code: report.code,
+      source: SOURCE,
+      message: report.message,
+      data: {
+        resource: {
+          kind: report.manifest.kind,
+          name: report.manifest.metadata?.name as string,
+        },
+        filePath: (report.manifest.metadata as { source?: string } | undefined)?.source,
+        path: report.path,
+        rule: report.rule,
+      },
+    });
+    const projectionIssues: SchemaProjectionIssue[] = [];
+    const resourceRuleIssues: ResourceRuleIssue[] = [];
+    const referrerRuleIssues: ReferrerRuleIssue[] = [];
+    // A rule that never had anything to iterate is never proven — the second way
+    // coverage varies invisibly, beside the dynamic-leaf skip. Tracked across the
+    // whole run and reported once, since "empty on every resource" is not a fact
+    // any single resource can establish.
+    const ruleExercise = new Map<
+      string,
+      { manifest: ResourceManifest; rule: ResourceRule; exercised: boolean; seen: boolean }
+    >();
+    // Same for a referrer rule, where "never exercised" means nothing the
+    // `referrer:` filter matches ever referenced a resource of the kind — which
+    // is exactly what a typo in that filter looks like from the outside.
+    const referrerRuleExercise = new Map<
+      string,
+      { manifest: ResourceManifest; rule: ReferrerRule; exercised: boolean; seen: boolean }
+    >();
     // `x-telo-type` is checked on EVERY manifest, not only on definition docs: a
     // schema fragment is written wherever a kind declares a schema-valued field,
     // so an inline `inputType:` on an ordinary resource carries one just as a
@@ -1350,6 +1440,35 @@ export class StaticAnalyzer {
         refConstraintIssues.push(...issues);
         refSlotIssues.push(...validateRefSlotDeclarations(m as unknown as ResourceManifest));
         zoneSlotIssues.push(...validateZoneSlotDeclarations(m as unknown as ResourceManifest));
+        projectionIssues.push(...validateSchemaProjection(m as unknown as ResourceManifest));
+        // Checked against the MERGED schema, so an `in:` pointer naming an
+        // inherited field resolves — which is what lets a rule shared by every
+        // backend be declared once on the abstract they extend.
+        resourceRuleIssues.push(
+          ...validateResourceRuleDeclarations(
+            m as unknown as ResourceManifest,
+            effectiveAuthorSchema(m as any, (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k)),
+          ),
+        );
+        referrerRuleIssues.push(
+          ...validateReferrerRuleDeclarations(m as unknown as ResourceManifest),
+        );
+        for (const rule of readReferrerRules((m as Record<string, unknown>).schema)) {
+          referrerRuleExercise.set(`${m.metadata?.module}.${m.metadata?.name}#${rule.code}`, {
+            manifest: m as unknown as ResourceManifest,
+            rule,
+            exercised: false,
+            seen: false,
+          });
+        }
+        for (const rule of readResourceRules((m as Record<string, unknown>).schema)) {
+          ruleExercise.set(`${m.metadata?.module}.${m.metadata?.name}#${rule.code}`, {
+            manifest: m as unknown as ResourceManifest,
+            rule,
+            exercised: false,
+            seen: false,
+          });
+        }
       }
       const resolvedCapability = def.capability
         ? (scopeResolver.resolveKind(def.capability) ?? def.capability)
@@ -1407,6 +1526,25 @@ export class StaticAnalyzer {
         };
         const filePath = (issue.manifest.metadata as { source?: string } | undefined)?.source;
         const data = { resource, filePath, path: issue.path };
+        if (issue.annotation === "referrer") {
+          // Mirrors ZONE_PROVIDER_UNRESOLVED: a filter naming no kind matches no
+          // referrer, so the rule would pass on every manifest while checking
+          // nothing — reported at the kind that wrote it, since the consumer
+          // cannot see that the check is inert.
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "REFERRER_RULE_INVALID",
+            source: SOURCE,
+            message:
+              `x-telo-referrer-rules 'referrer: ${issue.ref}' at '${issue.path}' names no kind. ` +
+              `The prefix must be an import alias declared in this file's 'imports:' map, ` +
+              `'Self' for a kind in this library, or 'Telo' for a built-in. A filter that ` +
+              `matches nothing leaves the rule inert. Known aliases: ` +
+              `${issue.knownAliases?.join(", ") || "(none)"}.`,
+            data,
+          });
+          continue;
+        }
         if (issue.annotation === "zone") {
           // Mirrors X_TELO_REF_UNRESOLVED: an unresolvable provider kind would
           // leave the requirement silently unenforced — no provider ever
@@ -1493,6 +1631,57 @@ export class StaticAnalyzer {
       // OPPOSITE directions — a dropped requirement is silently unenforced, a
       // dropped provision invents failures — so neither can be left to
       // leniency.
+      // A projection nothing can read does not fail — it stops typing the
+      // consumers counting on it, which puts a misspelled field back where the
+      // projection exists to catch it earlier.
+      for (const issue of resourceRuleIssues) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: issue.code,
+          source: SOURCE,
+          message: issue.message,
+          data: {
+            resource: {
+              kind: issue.manifest.kind,
+              name: issue.manifest.metadata?.name as string,
+            },
+            filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+            path: issue.path,
+          },
+        });
+      }
+      for (const issue of referrerRuleIssues) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: issue.code,
+          source: SOURCE,
+          message: issue.message,
+          data: {
+            resource: {
+              kind: issue.manifest.kind,
+              name: issue.manifest.metadata?.name as string,
+            },
+            filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+            path: issue.path,
+          },
+        });
+      }
+      for (const issue of projectionIssues) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: issue.code,
+          source: SOURCE,
+          message: issue.message,
+          data: {
+            resource: {
+              kind: issue.manifest.kind,
+              name: issue.manifest.metadata?.name as string,
+            },
+            filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+            path: issue.path,
+          },
+        });
+      }
       for (const issue of zoneSlotIssues) {
         diagnostics.push({
           severity: DiagnosticSeverity.Error,
@@ -1532,6 +1721,57 @@ export class StaticAnalyzer {
         aliasesByModule,
       }));
 
+    /**
+     * Whether a referrer of `kind` satisfies a referrer rule's `referrer:`
+     * filter, which is canonical by the time it gets here (`resolveSchemaRefKinds`
+     * rewrote it in the DECLARING module's scope). The referring manifest's own
+     * `kind:` is not — it is whatever alias its author imported the kind under —
+     * so it is resolved the same way every other kind comparison in this pass
+     * resolves one. Liskov-substitutable, matching `checkKind`: a child of the
+     * named kind is one.
+     */
+    const kindMatches = (filter: string, kind: string): boolean => {
+      const resolved = aliases.resolveKind(kind) ?? kind;
+      if (resolved === filter) return true;
+      return defs
+        .getByExtends(filter)
+        .some((d) => `${d.metadata.module}.${d.metadata.name}` === resolved);
+    };
+
+    /**
+     * The resources that reach `manifest`, with the slot each one reaches it
+     * through. A step's edge is attributed to the resource whose body declares
+     * it: a step is not a manifest, and the requirement is about the resource
+     * that has to declare something.
+     *
+     * Deduplication is the evaluation's, not this function's — a referrer
+     * reaching one resource through two slots is two sites, and which one anchors
+     * the diagnostic is a reporting decision.
+     */
+    const referrersOf = (
+      manifest: ResourceManifest,
+      graph: ReturnType<typeof buildCallGraph>,
+    ): Referrer[] => {
+      const name = manifest.metadata?.name as string | undefined;
+      if (!name) return [];
+      const node = graph.resource(manifest.kind, name) ?? graph.resourceByName(name);
+      if (!node) return [];
+      const out: Referrer[] = [];
+      for (const edge of graph.edgesTo(node.id)) {
+        const from = graph.nodes.get(edge.from);
+        if (!from) continue;
+        const owner = from.type === "step" ? graph.nodes.get(from.owner) : from;
+        if (!owner || owner.type !== "resource") continue;
+        out.push({
+          manifest: owner.manifest,
+          kind: owner.kind,
+          name: owner.name,
+          path: edge.path,
+        });
+      }
+      return out;
+    };
+
     // A `use` case map's selector written in CEL is a hard diagnostic — a call
     // graph known only at runtime is not statically analyzable, and no fallback
     // is conservative for every consumer. Scoped to the entry's own modules:
@@ -1567,6 +1807,32 @@ export class StaticAnalyzer {
           cache: zoneExportCache,
         }),
       );
+
+      // Durable regions — the SAME graph again, walked DOWNWARD this time.
+      // Every rule here keys off a zone attribute rather than off any kind, so
+      // a backend that ships its own workflow kind is covered without the
+      // analyzer knowing it exists: going native costs a module, not a change
+      // here.
+      const resolveRegionDef = (kind: string, module?: string) => {
+        const scope = (module ? aliasesByModule.get(module) : undefined) ?? aliases;
+        const canonical = scope.resolveKind(kind);
+        return defs.resolve(kind) ?? (canonical ? defs.resolve(canonical) : undefined);
+      };
+      diagnostics.push(
+        ...validateDurableRegions({
+          graph: getCallGraph(),
+          resolveDef: resolveRegionDef,
+          reportModules: rootModules,
+        }),
+        // The same walk once more, over EVERY attribute rather than the two
+        // durability names — a region must not contain a resource that declares
+        // it cannot honour what the region promises.
+        ...validateZoneViolations({
+          graph: getCallGraph(),
+          resolveDef: resolveRegionDef,
+          reportModules: rootModules,
+        }),
+      );
     }
 
     // Phase 2.6: register each named `Telo.Type` resource's schema under its
@@ -1963,6 +2229,69 @@ export class StaticAnalyzer {
         }
       }
 
+      // Resource rules — relationships between this resource's own fields that
+      // JSON Schema cannot state, declared by the kind as CEL over `self` and
+      // `this`. Read off the AUTHOR-FACING schema, so an `extends` child without
+      // `base:` inherits its parent's rules and one that declares its own
+      // replaces them, exactly as the rest of the config contract merges.
+      // The finding→diagnostic mapping lives with the finding vocabulary in
+      // `validate-resource-rules.ts`, the shape every neighbouring pass uses:
+      // issues out, one emit here.
+      const ruleDeclarer = (definition.metadata as { module?: string } | undefined)?.module;
+      for (const report of reportResourceRules(
+        m as unknown as ResourceManifest,
+        definition as unknown as ResourceManifest,
+        evaluateResourceRules(m as unknown as ResourceManifest, authorSchema),
+        !ruleDeclarer || rootModules.has(ruleDeclarer),
+      )) {
+        diagnostics.push(resourceRuleDiagnostic(report));
+      }
+      for (const rule of readResourceRules(authorSchema)) {
+        const key = `${definition.metadata?.module}.${definition.metadata?.name}#${rule.code}`;
+        const tracked = ruleExercise.get(key);
+        if (!tracked) continue;
+        tracked.seen = true;
+        if (ruleExercised(m as unknown as ResourceManifest, rule)) tracked.exercised = true;
+      }
+
+      // Referrer rules — what must be true of whoever REFERENCES this resource,
+      // declared by the kind that has the requirement rather than by the kind
+      // that must satisfy it. The subject is chosen by the EDGE, so no kind
+      // literal appears on the referring side, where the spelling would be the
+      // consumer's import alias rather than anything the rule's author controls.
+      // A consumer of the shared call graph, never a second traversal.
+      const referrerRules = readReferrerRules(authorSchema);
+      if (referrerRules.length > 0) {
+        const referrers = referrersOf(m as unknown as ResourceManifest, getCallGraph());
+        for (const report of reportReferrerRules(
+          m as unknown as ResourceManifest,
+          definition as unknown as ResourceManifest,
+          evaluateReferrerRules(
+            m as unknown as ResourceManifest,
+            authorSchema,
+            referrers,
+            kindMatches,
+          ),
+          !ruleDeclarer || rootModules.has(ruleDeclarer),
+        )) {
+          // A VIOLATION is the referrer's data, so it is reported only when that
+          // manifest is the entry's own — the same direction a resource-rule
+          // violation takes, one hop further out.
+          const owner = (report.manifest.metadata as { module?: string } | undefined)?.module;
+          if (report.code === "REFERRER_RULE_VIOLATED" && owner && !rootModules.has(owner)) {
+            continue;
+          }
+          diagnostics.push(referrerRuleDiagnostic(report));
+        }
+        for (const rule of referrerRules) {
+          const key = `${definition.metadata?.module}.${definition.metadata?.name}#${rule.code}`;
+          const tracked = referrerRuleExercise.get(key);
+          if (!tracked) continue;
+          tracked.seen = true;
+          if (referrerRuleExercised(rule, referrers, kindMatches)) tracked.exercised = true;
+        }
+      }
+
       // Validate inline resources nested inside this resource's body (e.g. a
       // Run.Sequence step's `invoke: { kind, ...config }`). These sit at
       // x-telo-ref slots reached only through local `$ref`s, which the
@@ -1998,6 +2327,24 @@ export class StaticAnalyzer {
       // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
     }
 
+    // A rule whose collection was empty on every resource of its kind is a rule
+    // nothing proved. `check()` types `self` only shallowly (cel-js takes a flat
+    // field map, so `columns` is `map`), which means a typo below the first level
+    // survives declaration validation and is caught only by evaluation — so a
+    // rule that never evaluated has been verified by nothing at all. Reported
+    // only when the kind HAS resources here: a kind nobody instantiated in this
+    // workspace says nothing about the rule.
+    for (const tracked of ruleExercise.values()) {
+      if (!tracked.seen || tracked.exercised) continue;
+      diagnostics.push(resourceRuleDiagnostic(reportUnexercisedRule(tracked.manifest, tracked.rule)));
+    }
+    for (const tracked of referrerRuleExercise.values()) {
+      if (!tracked.seen || tracked.exercised) continue;
+      diagnostics.push(
+        referrerRuleDiagnostic(reportUnexercisedReferrerRule(tracked.manifest, tracked.rule)),
+      );
+    }
+
     // Template-body structural validations: check that template entry-points produce
     // values matching the contract of their dispatch target and (for `provide:`)
     // the abstract this definition `extends`. CEL fields inside the templated
@@ -2092,6 +2439,40 @@ export class StaticAnalyzer {
       }
     }
 
+    // A consumer's slot typed from a referenced declaration
+    // (`x-telo-schema-projection-from`) fails in the direction that is hardest
+    // to notice: the contract silently reopens, so a misspelled field passes
+    // `telo check` exactly as it did before the projection existed. That is the
+    // failure the projection exists to move earlier, so it is reported here
+    // rather than left to degrade. Entry-module-scoped, like
+    // `X_TELO_REF_UNRESOLVED` — a published dependency's slot is not the
+    // consumer's to fix.
+    for (const m of allManifests) {
+      const md = m as Record<string, any>;
+      if (typeof md.kind !== "string" || md.kind.startsWith("Telo.")) continue;
+      const ownModule = (md.metadata as { module?: string } | undefined)?.module;
+      if (ownModule && !rootModules.has(ownModule)) continue;
+      const definition = contractScope.resolveIn(md.kind, ownModule);
+      if (!definition) continue;
+      const failures: ProjectionFailure[] = [];
+      for (const direction of ["inputType", "outputType"] as const) {
+        resolveContract(direction, md, definition, contractScope, failures);
+      }
+      for (const failure of failures) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "SCHEMA_PROJECTION_FROM_UNRESOLVED",
+          source: SOURCE,
+          message: `${md.kind}: ${describeProjectionFailure(failure)}`,
+          data: {
+            resource: { kind: md.kind, name: (md.metadata as any)?.name as string },
+            filePath: (md.metadata as { source?: string } | undefined)?.source,
+            path: failure.pointer.replace(/^\//, ""),
+          },
+        });
+      }
+    }
+
     // Validate CEL syntax and context variable access in all manifests. The
     // walker discovers every compiled CEL node by scanning the value tree and
     // hands back the `x-telo-context` schema matched at the enclosing path; the

package/src/call-graph.ts

@@ -55,6 +55,7 @@ import {
   type RefUse,
   type RefUseCases,
 } from "./ref-slot.js";
+import { isStepSlot } from "./step-slot.js";
 import { isRefEntry, resolveFieldEntries, type RefFieldEntry } from "./reference-field-map.js";
 import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
@@ -292,12 +293,6 @@ function resolveUseAtSite(
   return { use: possibleUses(slot), unresolved: entry.useCases, unresolvedReason };
 }
 
-/** Names the step-list annotation on an array property, if any. */
-function stepContextOf(schema: Record<string, any> | undefined): Record<string, any> | undefined {
-  const annotation = schema?.["x-telo-step-context"];
-  return annotation && typeof annotation === "object" ? annotation : undefined;
-}
-
 /** A resolved plain reference value (`{kind, name}`, optionally `alias`) — the
  *  shape `resolveRefSentinels` leaves at a ref site. NOT a step: a bare boot
  *  target written `!ref X` must not mint a step node. */
@@ -545,8 +540,7 @@ export function buildCallGraph(
     if (!schema) return;
     const collected: StepGraphNode[] = [];
     for (const [key, propSchema] of propertySchemas(schema)) {
-      const annotation = stepContextOf(propSchema);
-      if (!annotation) continue;
+      if (!isStepSlot(propSchema)) continue;
       const value = (node.manifest as Record<string, unknown>)[key];
       if (!Array.isArray(value)) continue;
       walkSteps(value, key, undefined, {

package/src/flatten-for-analyzer.ts

@@ -204,7 +204,7 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
     const alias = m.metadata?.name as string | undefined;
     if (!owner || !alias) continue;
     const edge = graph.importEdges.get(owner)?.get(alias);
-    if (!edge?.targetModuleName) continue;
+    if (!edge) continue;
 
     const newMetadata: Record<string, unknown> = {
       ...m.metadata,

package/src/import-resolution-diagnostics.ts

@@ -20,25 +20,43 @@ function isRecognizedSourceShape(source: string): boolean {
   );
 }
 
-function messageFor(e: GraphLoadError, malformed: boolean): string {
+/** Which of the three failures this is. Kept as one function so the code and
+ *  the sentence can never disagree about which cause was established. */
+function classify(e: GraphLoadError): "INVALID_IMPORT_TARGET" | "INVALID_IMPORT_SOURCE" | "IMPORT_UNRESOLVED" {
+  if (e.reason === "unusable-target") return "INVALID_IMPORT_TARGET";
+  return isRecognizedSourceShape(e.source ?? e.url) ? "IMPORT_UNRESOLVED" : "INVALID_IMPORT_SOURCE";
+}
+
+function messageFor(e: GraphLoadError, code: ReturnType<typeof classify>): string {
   const authored = e.source ?? e.url;
   const via = e.alias ? `import '${e.alias}' → '${authored}'` : `'${authored}'`;
-  if (malformed) {
+  if (code === "INVALID_IMPORT_SOURCE") {
     return (
       `Cannot resolve ${via}: not a recognized module reference. Expected ` +
       `'namespace/name@version', 'oci://host/repo@tag', 'https://…', or a relative path.`
     );
   }
+  // The target WAS obtained, so "cannot resolve" would name the wrong problem —
+  // and the wrong person to fix it. The loader's message already says what was
+  // fetched and why it is not importable.
+  if (code === "INVALID_IMPORT_TARGET") return `Cannot use ${via}: ${e.error.message}`;
   return `Cannot resolve ${via}: ${e.error.message}`;
 }
 
 /**
- * Convert a graph's import-resolution failures (`graph.errors`) into structured,
- * coded diagnostics. This is the single source of truth for surfacing a broken
+ * Convert a graph's import failures (`graph.errors`) into structured, coded
+ * diagnostics. This is the single source of truth for surfacing a broken
  * import — every host (CLI, VS Code, telo-editor) routes these instead of each
  * re-deriving the channel and drifting (the VS Code extension used to drop it
  * entirely, showing nothing for a broken import).
  *
+ * Three codes, because three different people fix them:
+ * `INVALID_IMPORT_SOURCE` (the ref is not a module reference at all),
+ * `IMPORT_UNRESOLVED` (a well-formed ref that could not be obtained), and
+ * `INVALID_IMPORT_TARGET` (obtained, but not an importable library — an
+ * application, no library document, or one that names no module). Collapsing
+ * the last into the second would tell an author to fix a ref that is correct.
+ *
  * The analyzer owns only this raw channel conversion; the *presentation* policy
  * — which analysis cascade to hold back for a compromised file — lives in
  * `@telorun/ide-support`'s `assembleGraphDiagnostics`.
@@ -51,15 +69,15 @@ function messageFor(e: GraphLoadError, malformed: boolean): string {
 export function importResolutionDiagnostics(graph: LoadedGraph): AnalysisDiagnostic[] {
   return graph.errors.map((e) => {
     const filePath = e.fromSource ?? graph.entry.owner.source;
-    const malformed = !isRecognizedSourceShape(e.source ?? e.url);
+    const code = classify(e);
     const data: { filePath: string; path?: string; sourceLine?: number } = { filePath };
     if (e.alias) data.path = `imports.${e.alias}`;
     if (e.sourceLine !== undefined) data.sourceLine = e.sourceLine;
     return {
       severity: DiagnosticSeverity.Error,
-      code: malformed ? "INVALID_IMPORT_SOURCE" : "IMPORT_UNRESOLVED",
+      code,
       source: SOURCE,
-      message: messageFor(e, malformed),
+      message: messageFor(e, code),
       data,
     };
   });