@telorun/analyzer 0.70.0 → 0.72.0

package/src/analyzer.ts

@@ -24,6 +24,7 @@ import {
   type CelHandlers,
 } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
+import { readDeprecation } from "./deprecation.js";
 import { type ContractDirection, effectiveAuthorSchema } from "./extends-resolution.js";
 import {
   analyzerContractScope,
@@ -47,6 +48,7 @@ import {
 } from "./validate-observed-state.js";
 import { computeSuggestKind } from "./kind-suggest.js";
 import { visitManifest } from "./manifest-visitor.js";
+import { declaringModuleScope, moduleAliasScope } from "./module-alias-scope.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
@@ -124,7 +126,12 @@ import {
   type SchemaIssue,
 } from "./schema-compat.js";
 import { collectValueSchemaIssues } from "./validate-value-schema.js";
-import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
+import {
+  DiagnosticSeverity,
+  DiagnosticTag,
+  type AnalysisDiagnostic,
+  type AnalysisOptions,
+} from "./types.js";
 import {
   extractAccessChains,
   extractContextsFromSchema,
@@ -999,10 +1006,10 @@ export class StaticAnalyzer {
       if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
       const def = m as unknown as ResourceDefinition;
       const ownModule = (def.metadata as { module?: string } | undefined)?.module;
-      const scopeResolver =
-        ownModule && !rootModules.has(ownModule)
-          ? (aliasesByModule.get(ownModule) ?? new AliasResolver())
-          : aliases;
+      const scopeResolver = declaringModuleScope(ownModule, aliases, {
+        aliasesByModule,
+        rootModules,
+      });
       // Canonicalize alias-form `x-telo-ref` constraints in the DECLARING module's
       // scope, before the schema reaches `register()` and the lazily-built field
       // maps. Same pre-resolution `capability` / `extends` get below.
@@ -1425,7 +1432,7 @@ export class StaticAnalyzer {
       // 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 scope = moduleAliasScope({ module }, aliases, aliasesByModule);
         const canonical = scope.resolveKind(kind);
         return defs.resolve(kind) ?? (canonical ? defs.resolve(canonical) : undefined);
       };
@@ -1456,8 +1463,10 @@ export class StaticAnalyzer {
       if (!ownModule || !m.metadata?.name || typeof m.schema !== "object" || m.schema === null) {
         continue;
       }
-      const scopeResolver =
-        rootModules.has(ownModule) ? aliases : (aliasesByModule.get(ownModule) ?? new AliasResolver());
+      const scopeResolver = declaringModuleScope(ownModule, aliases, {
+        aliasesByModule,
+        rootModules,
+      });
       const canonicalKind = scopeResolver.resolveKind(m.kind as string) ?? (m.kind as string);
       if (defs.resolve(canonicalKind)?.capability !== "Telo.Type") continue;
       const typeName = m.metadata.name as string;
@@ -1532,6 +1541,7 @@ export class StaticAnalyzer {
           aliases,
           rootModules,
           getCallGraph(),
+          { aliasesByModule, rootModules },
         ),
       );
       // A file embed resolves at resource creation, so one written on a doc that
@@ -1877,6 +1887,83 @@ export class StaticAnalyzer {
         continue;
       }
 
+      // An abstract names a CONTRACT for reference slots, not something to
+      // instantiate — the kernel refuses it outright at `create()`. Reported
+      // here, at the declaration, because that is the line the author has to
+      // change and because a runtime-only refusal is exactly the shape static
+      // analysis exists to remove. The hint mirrors the kernel's: the concrete
+      // implementations this analysis holds, or the reason there are none.
+      //
+      // Injected declarations never reach this loop (skipped above), which is
+      // what keeps a `resources:` entry — kind-only and routinely abstract by
+      // design — out of it.
+      if (definition.kind === "Telo.Abstract") {
+        const canonical = resolvedKind ?? m.kind;
+        const impls = defs
+          .getByExtends(canonical)
+          .filter((d) => d.kind !== "Telo.Abstract")
+          .map((d) => `${d.metadata.module}.${d.metadata.name}`);
+        const kindInfo =
+          canonical !== m.kind ? `'${m.kind}' (resolved to '${canonical}')` : `'${m.kind}'`;
+        const hint = impls.length
+          ? `instantiate a concrete implementation: ${impls.join(", ")}`
+          : "no concrete implementations are registered — import a module that provides one";
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "ABSTRACT_KIND_INSTANTIATED",
+          source: SOURCE,
+          message: `Kind ${kindInfo} is abstract and cannot be instantiated directly; ${hint}.`,
+          data: { resource, filePath, path: "kind" },
+        });
+        continue;
+      }
+
+      // A kind its own author marked `metadata.deprecated` still works exactly as
+      // it did — the manifest is valid and keeps running — so this is a WARNING,
+      // reported at the declaration because `kind:` is the line that has to
+      // change. Emitted here rather than in a pass of its own so it reads the
+      // kind THIS walk resolved: the resolution is alias- and gate-aware and
+      // scope-dependent, and a second implementation of it would eventually
+      // disagree about which definition a name means.
+      //
+      // Entry-module-scoped, like every other "not the consumer's to fix" check:
+      // a library's internal use of a kind its own author deprecated is that
+      // author's concern, and reporting it floods a consumer with lines they
+      // cannot act on.
+      //
+      // No `DiagnosticFix`. `replacedBy` names a kind through the DECLARING
+      // module's aliases; writing it into the consumer's file would produce a
+      // prefix that resolves to nothing there — and a kind swap is not a
+      // whole-value replacement anyway, since the successor needs its own import
+      // and usually a different configuration.
+      const deprecation = readDeprecation(definition.metadata);
+      if (deprecation && (!ownModule || rootModules.has(ownModule))) {
+        // Quoted CANONICALLY, not verbatim: `Self.Thing` is how the declaring
+        // library names its own kind and means nothing where the warning lands.
+        const declaringScope =
+          scopeResolverForModule(
+            (definition.metadata as { module?: string } | undefined)?.module,
+            rootModules,
+            aliasesByModule,
+          ) ?? aliases;
+        const replacement = deprecation.replacedBy
+          ? (declaringScope.resolveKind(deprecation.replacedBy) ?? deprecation.replacedBy)
+          : undefined;
+        diagnostics.push({
+          severity: DiagnosticSeverity.Warning,
+          code: "DEPRECATED_KIND",
+          source: SOURCE,
+          // Warning-grade AND a deprecation: the severity says it must
+          // eventually be dealt with, the tag says what it is, and an editor
+          // strikes the kind through on the strength of the second.
+          tags: [DiagnosticTag.Deprecated],
+          message:
+            `Kind '${m.kind}' is deprecated: ${deprecation.reason}` +
+            (replacement ? ` Use '${replacement}' instead.` : ""),
+          data: { resource, filePath, path: "kind" },
+        });
+      }
+
       // Validate resource config against the definition's AUTHOR-FACING schema —
       // inheritance-resolved, with `kind` / `metadata` injected. See
       // `validationSchemaFor`, which is where both derivations and the reason
@@ -2690,9 +2777,25 @@ export class StaticAnalyzer {
     // Validate provider coherence rules for `provide:` template-target definitions.
     diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
 
-    // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
+    // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7).
+    // The library document sets collected for the zone stage serve here too: a
+    // library's exported entry point is forwarded into the flat set while the
+    // siblings it invokes are not, so without them the walk stops at the
+    // boundary and reports an empty union for a body that plainly throws.
+    const libraryManifests = new Map<string, ResourceManifest[]>();
+    for (const doc of options?.moduleDocuments ?? []) {
+      libraryManifests.set(doc.module, doc.manifests);
+    }
     diagnostics.push(
-      ...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv, aliasesByModule, rootModules),
+      ...validateThrowsCoverage(
+        allManifests,
+        defs,
+        aliases,
+        this.celEnv,
+        aliasesByModule,
+        rootModules,
+        libraryManifests,
+      ),
     );
 
     // Warn about declared variables / secrets / ports that no CEL references.
@@ -2710,7 +2813,8 @@ export class StaticAnalyzer {
         defs,
         aliases,
         rootModules,
-        (supplied, required) => kindSatisfies(supplied, required, defs),
+        (supplied, required, isDeclaration) =>
+          kindSatisfies(supplied, required, defs, isDeclaration),
       ),
     );
 

package/src/call-graph.ts

@@ -40,6 +40,7 @@
  */
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import { refSentinelTarget } from "./ref-sentinel-target.js";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
@@ -63,6 +64,7 @@ import {
   type RefFieldEntry,
 } from "./reference-field-map.js";
 import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 export interface ResourceGraphNode {
   type: "resource";
@@ -693,8 +695,7 @@ export function buildCallGraph(
   const definitionFor = (manifest: ResourceManifest): ResourceDefinition | undefined => {
     const direct = registry.resolve(manifest.kind as string);
     if (direct) return direct;
-    const module = (manifest.metadata as { module?: string } | undefined)?.module;
-    const scope = (module ? options.aliasesByModule?.get(module) : undefined) ?? options.aliases;
+    const scope = moduleAliasScope(manifest.metadata, options.aliases, options.aliasesByModule);
     const canonical = scope?.resolveKind(manifest.kind as string);
     return canonical ? registry.resolve(canonical) : undefined;
   };
@@ -962,7 +963,12 @@ export function buildCallGraph(
  *  here: an unresolved `!ref <name>` sentinel and the `{kind, name}` object
  *  `resolveRefSentinels` rewrites it into. */
 function refTargetName(value: unknown): string | undefined {
-  if (isRefSentinel(value)) return value.source;
+  // An edge's target is taken VERBATIM — `resolveScopedName` and the node index
+  // are what resolve it, and a cross-module `Alias.name` is a target this graph
+  // legitimately carries unresolved. That is this pass's reduction over the
+  // shared parse, not a second reading of the tag.
+  const sentinel = refSentinelTarget(value);
+  if (sentinel) return sentinel.source;
   if (!value || typeof value !== "object") return undefined;
   const name = (value as Record<string, unknown>).name;
   return typeof name === "string" ? name : undefined;

package/src/catch-scope.ts

@@ -0,0 +1,157 @@
+/**
+ * Which `catches:` lists answer for one dispatch site.
+ *
+ * A catch list is one rung of a SCOPE LADDER — a route's, its router's, its
+ * server's — and every rule over those lists needs the same two answers: what
+ * a scope list is checked against, and which scopes enclose a given site. This
+ * module owns that model; the rule checks in `validate-throws-coverage.ts` read
+ * one answer instead of rebuilding it beside four unrelated jobs.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { DefinitionRegistry } from "./definition-registry.js";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { ResourceManifest } from "@telorun/sdk";
+import { visitManifest } from "./manifest-visitor.js";
+import { forEachDrivenSlot } from "./schema-walk.js";
+import { resolveRefManifest, type ResolveCtx } from "./resolve-throws-union.js";
+
+/** What a list proves it renders: the codes its coverage-proving `when:` clauses
+ *  name, and whether it ends in a catch-all.
+ *
+ *  Unfiltered by any denominator, because this is also what an enclosing scope
+ *  contributes DOWNWARD — a server entry naming a code the server's own closure
+ *  could not enumerate still renders it for the route that throws it. Filtering
+ *  the local answer against the declared union happens where that answer is
+ *  used, and subtracting from the declared set makes the two equivalent there. */
+export interface ProvenCoverage {
+  codes: Set<string>;
+  hasCatchAll: boolean;
+}
+
+export const NO_COVERAGE: ProvenCoverage = { codes: new Set(), hasCatchAll: false };
+
+/** A declaration inside another resource's `x-telo-scope` array, kept with the
+ *  resource that encloses it and the path it is written at in that resource's
+ *  document. Both are needed: the owner is the only place its kind's alias scope
+ *  can be found, and the only document position lookup can reach. */
+export interface ScopedManifest {
+  manifest: ResourceManifest;
+  owner: ResourceManifest;
+  /** Concrete owner-relative path of the declaration (`with[0]`). */
+  path: string;
+}
+
+/** Every `with:`-scoped declaration in the set, once each.
+ *
+ *  Scoped resources are absent from the flat manifest list, so every check that
+ *  iterates it skips them — and standing a server up around a test is exactly
+ *  that shape, so the sanctioned pattern was the one the pass could not see.
+ *  Discovered through the shared visitor rather than a second scope walk. */
+export function collectScopedManifests(
+  manifests: ResourceManifest[],
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  aliasesByModule: Map<string, AliasResolver>,
+  rootModules: Set<string>,
+): ScopedManifest[] {
+  const scoped: ScopedManifest[] = [];
+  visitManifest(
+    manifests,
+    defs,
+    {
+      onScope: (event) => {
+        for (const { manifest, path } of event.declarations) {
+          if (!manifest?.kind || !manifest.metadata?.name) continue;
+          scoped.push({ manifest, owner: event.source, path });
+        }
+      },
+    },
+    { aliases, aliasesByModule, rootModules },
+  );
+  return scoped;
+}
+
+/** Which resources each resource's scope list encloses, along the slots that
+ *  declare `throwsThrough` — one fact stated once, since the edge a throws
+ *  closure crosses is the edge a catch scope encloses through. */
+export function buildEnclosers(
+  manifests: ResourceManifest[],
+  definitionOf: (m: ResourceManifest) => { schema?: Record<string, any> } | undefined,
+  moduleOf: (m: ResourceManifest) => string | undefined,
+  ctx: ResolveCtx,
+): Map<ResourceManifest, ResourceManifest[]> {
+  const enclosers = new Map<ResourceManifest, ResourceManifest[]>();
+  for (const manifest of manifests) {
+    const definition = definitionOf(manifest);
+    if (!definition?.schema) continue;
+    forEachDrivenSlot(definition.schema, manifest, (driven) => {
+      if (driven.kind !== "ref" || !driven.slot.throwsThrough) return;
+      const target = resolveRefManifest(driven.data, ctx, moduleOf(manifest));
+      if (!target || target === manifest) return;
+      const list = enclosers.get(target);
+      if (list) list.push(manifest);
+      else enclosers.set(target, [manifest]);
+    });
+  }
+  return enclosers;
+}
+
+/**
+ * What every scope enclosing a resource is guaranteed to render for it.
+ *
+ * **Across enclosers this INTERSECTS, and that is the whole correctness of the
+ * reduction.** Coverage claims that a throw cannot escape unrendered, so it holds
+ * only when EVERY path to the site renders it — a router mounted on a public
+ * server with a catch-all and an internal one without is covered on one path and
+ * bare on the other, and unioning the two reported it as fully covered while the
+ * internal server answered with the built-in envelope. A resource with no
+ * encloser contributes nothing rather than everything: the empty set is the
+ * identity for the site's own coverage, and treating "no paths" as "all paths
+ * agree" would assert coverage no list provides.
+ *
+ * A resource's OWN scope list is unioned in, because it applies on every path.
+ *
+ * Memoized, and a cycle among `throwsThrough` edges resolves to what has been
+ * accumulated so far rather than raising: this answers what a scope renders, and
+ * no cycle makes that answer larger.
+ */
+export function enclosingCoverage(
+  manifest: ResourceManifest,
+  ownScope: Map<ResourceManifest, ProvenCoverage>,
+  enclosers: Map<ResourceManifest, ResourceManifest[]>,
+  memo: Map<ResourceManifest, ProvenCoverage> = new Map(),
+  walking: Set<ResourceManifest> = new Set(),
+): ProvenCoverage {
+  const cached = memo.get(manifest);
+  if (cached) return cached;
+  if (walking.has(manifest)) return NO_COVERAGE;
+  walking.add(manifest);
+  try {
+    const own = ownScope.get(manifest);
+    const result: ProvenCoverage = {
+      codes: new Set(own?.codes ?? []),
+      hasCatchAll: own?.hasCatchAll ?? false,
+    };
+
+    const outer = (enclosers.get(manifest) ?? []).map((e) =>
+      enclosingCoverage(e, ownScope, enclosers, memo, walking),
+    );
+    if (outer.length > 0) {
+      const [first, ...rest] = outer;
+      const shared = new Set(first.codes);
+      let everyCatchAll = first.hasCatchAll;
+      for (const other of rest) {
+        for (const code of [...shared]) if (!other.codes.has(code)) shared.delete(code);
+        everyCatchAll &&= other.hasCatchAll;
+      }
+      for (const code of shared) result.codes.add(code);
+      if (everyCatchAll) result.hasCatchAll = true;
+    }
+
+    memo.set(manifest, result);
+    return result;
+  } finally {
+    walking.delete(manifest);
+  }
+}

package/src/cel-scope-query.ts

@@ -18,6 +18,7 @@ import { buildCelEnvironment } from "./cel-environment.js";
 import { CelScopeResolver, type CelScope } from "./cel-scope.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { buildKernelGlobalsIndex } from "./kernel-globals.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import { isModuleKind } from "./module-kinds.js";
 import { navigateConcretePath } from "./manifest-path.js";
 import { findManifest } from "./find-manifest.js";
@@ -41,6 +42,12 @@ export interface ContextDeclarationSite {
   kind: string;
   name: string;
   path: string;
+  /** The declaring module, when the manifest carries one. Part of the identity,
+   *  not decoration: a resource name is unique inside its module and not across a
+   *  flattened set, so `(kind, name)` alone lets a host locating this site land on
+   *  another library's same-named document — which for go-to-declaration means
+   *  jumping to the wrong file with nothing to indicate it. */
+  module?: string;
 }
 
 /** Join a concrete path segment, tolerating an empty base (the manifest root). */
@@ -210,9 +217,14 @@ export class CelScopeQuery {
       base = hit;
     }
 
-    const metadata = origin.manifest.metadata as { name?: string } | undefined;
+    const metadata = origin.manifest.metadata as { name?: string; module?: string } | undefined;
     if (!origin.manifest.kind || !metadata?.name) return undefined;
-    return { kind: origin.manifest.kind, name: metadata.name, path: base };
+    return {
+      kind: origin.manifest.kind,
+      name: metadata.name,
+      path: base,
+      ...(metadata.module === undefined ? {} : { module: metadata.module }),
+    };
   }
 
   /** The manifest and path an annotated context property is derived from, and
@@ -265,13 +277,29 @@ export class CelScopeQuery {
       if (hash <= 0) return undefined;
       const kindValue = navigateConcretePath(root, first.slice(0, hash).split("/").join("."));
       if (typeof kindValue !== "string") return undefined;
-      const canonical = this.ctx.aliases.resolveKind(kindValue) ?? kindValue;
-      const suffix = canonical.slice(canonical.indexOf(".") + 1);
-      const target = this.manifests.find(
+      // The kind was read off THIS resource, so it is spelled in the alias scope
+      // of the module that declared it — not the entry's.
+      const scope = moduleAliasScope(resource.metadata, this.ctx.aliases, this.ctx.aliasesByModule);
+      const canonical = scope.resolveKind(kindValue) ?? kindValue;
+      const dot = canonical.indexOf(".");
+      const owningModule = dot === -1 ? undefined : canonical.slice(0, dot);
+      const suffix = canonical.slice(dot + 1);
+      // Matched by MODULE AND NAME once the canonical form carries a module: a
+      // definition name is unique inside its module and not across a flattened
+      // set, so two libraries each declaring an `Api` would otherwise resolve to
+      // whichever came first — and the editor would type a context region off the
+      // wrong kind's annotations, silently. Falls back to name alone only when the
+      // kind did not resolve to a canonical form, where there is nothing to narrow
+      // by and a best-effort match is still better than none.
+      const named = this.manifests.filter(
         (m) =>
           (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") &&
           (m.metadata as { name?: string } | undefined)?.name === suffix,
-      ) as Record<string, any> | undefined;
+      ) as Record<string, any>[];
+      const target =
+        (owningModule
+          ? named.find((m) => (m.metadata as { module?: string } | undefined)?.module === owningModule)
+          : undefined) ?? (owningModule && named.length > 1 ? undefined : named[0]);
       if (!target) return undefined;
       return { manifest: target, path: first.slice(hash + 1), propertyMap: false };
     }
@@ -313,9 +341,18 @@ export class CelScopeQuery {
     return undefined;
   }
 
+  /** The kind's declaration, resolved in the scope of the module that DECLARED
+   *  this resource — the same rule the manifest visitor applies, and the reason
+   *  it has to be the same one: everything this query offers is read off the
+   *  definition, so resolving a forwarded library resource's `kind: Http.Api`
+   *  through the entry's aliases alone found nothing and the editor silently
+   *  offered no `request` / `result` at a site `telo check` accepts. A
+   *  completion list is a claim that the name it offers will pass the checker,
+   *  so the two must resolve a kind identically. */
   private definitionFor(resource: ResourceManifest): ResourceDefinition | undefined {
-    const { defs, aliases } = this.ctx;
-    const canonical = aliases.resolveKind(resource.kind);
+    const { defs, aliases, aliasesByModule } = this.ctx;
+    const scope = moduleAliasScope(resource.metadata, aliases, aliasesByModule);
+    const canonical = scope.resolveKind(resource.kind);
     return defs.resolve(resource.kind) ?? (canonical ? defs.resolve(canonical) : undefined);
   }
 

package/src/definition-registry.ts

@@ -2,6 +2,7 @@ import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { KERNEL_BUILTINS } from "./builtins.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import {
   buildFieldMapAtPath,
   buildReferenceFieldMap,
@@ -372,9 +373,7 @@ export class DefinitionRegistry {
     // (e.g. `Ai.AgentStream` in a library that imports `Ai`), which the root/global
     // resolver doesn't know — using the global scope here left the base field map
     // unresolved, so Phase-5 injection saw no ref fields and skipped injection.
-    const ownModule = (resource.metadata as { module?: string } | undefined)?.module;
-    const moduleScope =
-      (ownModule ? aliasesByModule.get(ownModule) : undefined) ?? aliases;
+    const moduleScope = moduleAliasScope(resource.metadata, aliases, aliasesByModule);
 
     const baseMap = this.getFieldMapForKind(resource.kind, moduleScope);
     if (!baseMap) return undefined;
@@ -383,9 +382,7 @@ export class DefinitionRegistry {
     const def = this.resolve(resource.kind) ?? this.resolve(resolvedKind);
     // schema-from anchors resolve in the DEFINITION's module scope (where the anchor
     // kind is declared), which may differ from the resource's own module.
-    const ownerModule = (def?.metadata as { module?: string } | undefined)?.module;
-    const ownerScope =
-      (ownerModule ? aliasesByModule.get(ownerModule) : undefined) ?? aliases;
+    const ownerScope = moduleAliasScope(def?.metadata, aliases, aliasesByModule);
 
     const expanded: ReferenceFieldMap = new Map();
     for (const [path, entry] of baseMap) {

package/src/deprecation.ts

@@ -0,0 +1,36 @@
+/**
+ * `metadata.deprecated` — the annotation's single reader.
+ *
+ * Structural validity belongs to `validate-module-metadata.ts` (the strict half,
+ * the `ref-slot.ts` split). This side is deliberately lenient: it reads a
+ * well-formed block and treats everything else as absent, so a malformed
+ * declaration in a published dependency never becomes a warning at a consumer's
+ * use site. The consumer can fix neither one, and reporting the second blames
+ * the wrong author.
+ */
+
+/** A deprecation as declared: why, and optionally what to use instead. */
+export interface Deprecation {
+  /** What a consumer reads to know what to do instead. Always non-empty. */
+  reason: string;
+  /** Alias-qualified kind (kind docs) or module ref (module docs), **as written
+   *  in the declaring file's own scope** — `Self.Thing` means nothing to a
+   *  consumer, so a use site resolves it before quoting it. */
+  replacedBy?: string;
+}
+
+export function readDeprecation(metadata: unknown): Deprecation | undefined {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) return undefined;
+  const block = (metadata as Record<string, unknown>).deprecated;
+  if (block === null || typeof block !== "object" || Array.isArray(block)) return undefined;
+
+  const { reason, replacedBy } = block as Record<string, unknown>;
+  if (typeof reason !== "string" || reason.trim() === "") return undefined;
+
+  return {
+    reason: reason.trim(),
+    ...(typeof replacedBy === "string" && replacedBy.trim() !== ""
+      ? { replacedBy: replacedBy.trim() }
+      : {}),
+  };
+}

package/src/flatten-for-analyzer.ts

@@ -8,7 +8,7 @@ import {
   readResourceInputs,
   type ResourceInput,
 } from "./resource-input.js";
-import type { ZoneModuleDocuments } from "./zone-module-documents.js";
+import type { ModuleDocuments } from "./module-documents.js";
 
 /** One parsed `exports.resources` / `exports.kinds` entry. `name` is the exported
  *  instance name or kind suffix (the part after the dot, or the whole entry); `alias`
@@ -557,8 +557,8 @@ function canonicalizeInputKind(
  *  projection needs the internal dispatch chain to derive an export's open
  *  requirements. Only libraries that actually export instances are included:
  *  a library exporting nothing has no export contract to derive. */
-export function collectZoneModuleDocuments(graph: LoadedGraph): ZoneModuleDocuments[] {
-  const out: ZoneModuleDocuments[] = [];
+export function collectModuleDocuments(graph: LoadedGraph): ModuleDocuments[] {
+  const out: ModuleDocuments[] = [];
   for (const [source, mod] of graph.modules) {
     if (source === graph.rootSource) continue;
     const libDoc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind)) as

package/src/index.ts

@@ -11,7 +11,7 @@ export type {
     ParseError,
 } from "./loaded-types.js";
 export {
-    collectZoneModuleDocuments,
+    collectModuleDocuments,
     flattenForAnalyzer,
     flattenLoadedModule,
     forwardReExportManifests,
@@ -185,6 +185,8 @@ export {
 export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
 export { isStepSlot, readStepSlot, STEP_FRAGMENT } from "./step-slot.js";
 export type { StepSlot } from "./step-slot.js";
+export { readDeprecation } from "./deprecation.js";
+export type { Deprecation } from "./deprecation.js";
 export {
   ANNOTATION_KEYWORDS,
   registerTeloKeywords,
@@ -246,7 +248,7 @@ export type {
   ZoneExportRequirements,
   ZoneRequirementSpec,
 } from "./resolve-zone-requirements.js";
-export type { ZoneModuleDocuments } from "./zone-module-documents.js";
+export type { ModuleDocuments } from "./module-documents.js";
 export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
 export {
   RESOURCE_RULES_ANNOTATION,
@@ -489,7 +491,12 @@ export type { CelScopeQueryContext, ContextDeclarationSite } from "./cel-scope-q
 export { navigateConcretePath } from "./manifest-path.js";
 export { ManifestAnalysis } from "./manifest-analysis.js";
 export type { ManifestRef } from "./manifest-analysis.js";
-export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
+export {
+  DEFAULT_MANIFEST_FILENAME,
+  DiagnosticSeverity,
+  DiagnosticTag,
+  diagnosticFix,
+} from "./types.js";
 export type {
     AnalysisDiagnostic,
     AnalysisOptions,