@telorun/analyzer 0.62.1 → 0.64.0

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,
     };
   });

package/src/index.ts

@@ -110,6 +110,8 @@ export {
   transfersControl,
 } from "./ref-slot.js";
 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 {
   ANNOTATION_KEYWORDS,
   registerTeloKeywords,
@@ -131,6 +133,8 @@ export type {
   RequiresIssue,
   RequiresVerdict,
 } from "./requires-block.js";
+export { manifestCompatibility } from "./module-compatibility.js";
+export type { ModuleCompatibility } from "./module-compatibility.js";
 export { TELO_SURFACE_VERSION } from "./telo-version.js";
 export { validateRequires } from "./validate-requires.js";
 export type { ValidateRequiresOptions } from "./validate-requires.js";
@@ -150,8 +154,10 @@ export type {
 export {
   hasProvidesZone,
   hasRequiresZone,
+  providedZoneAttributes,
   readProvidesZone,
   readRequiresZone,
+  readViolatesZone,
   rewriteRequiresZoneKind,
 } from "./zone-slot.js";
 export type { ProvidesZoneSlot, RequiresZoneSlot } from "./zone-slot.js";
@@ -169,6 +175,73 @@ export type {
 } from "./resolve-zone-requirements.js";
 export type { ZoneModuleDocuments } from "./zone-module-documents.js";
 export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
+export {
+  RESOURCE_RULES_ANNOTATION,
+  readResourceRules,
+  readRawResourceRules,
+  resolveRuleSubjects,
+  findDynamicLeaf,
+  type ResourceRule,
+  type ResourceRuleSeverity,
+  type RuleSubject,
+} from "./resource-rule.js";
+export {
+  validateResourceRuleDeclarations,
+  evaluateResourceRules,
+  ruleExercised,
+  RESOURCE_RULE_BUDGET_MS,
+  type ResourceRuleIssue,
+  type ResourceRuleFinding,
+} from "./validate-resource-rules.js";
+export {
+  REFERRER_RULES_ANNOTATION,
+  readReferrerRules,
+  readRawReferrerRules,
+  hasReferrerRules,
+  rewriteReferrerRuleKinds,
+  type ReferrerRule,
+} from "./referrer-rule.js";
+export {
+  validateReferrerRuleDeclarations,
+  evaluateReferrerRules,
+  referrerRuleExercised,
+  reportReferrerRules,
+  reportUnexercisedReferrerRule,
+  type Referrer,
+  type ReferrerRuleIssue,
+  type ReferrerRuleFinding,
+  type ReferrerRuleDiagnostic,
+} from "./validate-referrer-rules.js";
+export { RULE_BUDGET_MS } from "./rule-condition.js";
+export {
+  readSchemaProjection,
+  readSchemaMap,
+  readProjectionFrom,
+  readProjectionRef,
+  manifestListScope,
+  projectionKeyMap,
+  projectEntries,
+  resolveSchemaProjections,
+  describeProjectionFailure,
+  type SchemaProjection,
+  type SchemaMap,
+  type ProjectionRef,
+  type ProjectionLookup,
+  type ProjectionScope,
+  type ProjectionFailure,
+} from "./schema-projection.js";
+export { validateSchemaProjection, type SchemaProjectionIssue } from "./validate-schema-projection.js";
+export { validateDurableRegions } from "./validate-durable-regions.js";
+export { validateZoneViolations } from "./validate-zone-violations.js";
+export {
+  containmentIndex,
+  findZoneRegions,
+  regionManifests,
+  type ContainedNode,
+  type DefinitionLookup,
+  type RegionBoundary,
+  type ZoneRegion,
+} from "./resolve-zone-containment.js";
 export type { ZoneSlotIssue } from "./validate-zone-slots.js";
 export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validate-ref-slots.js";
 export type { RefSlotIssue } from "./validate-ref-slots.js";
@@ -297,6 +370,19 @@ export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";
 export { CelParseError, buildCelSegments, wrapCelAst } from "./cel-ast.js";
 export type { CelNode, CelSegment } from "./cel-ast.js";
+
+// The CEL scope rule, and the way into it from outside the analysis pass. What
+// completes, what hovers and what type-checks are one answer because they are
+// one function.
+export { CelScopeResolver } from "./cel-scope.js";
+export type { CelScope, CelScopeInputs, CelSiteRef } from "./cel-scope.js";
+export { CelScopeQuery } from "./cel-scope-query.js";
+export type { CelScopeQueryContext, ContextDeclarationSite } from "./cel-scope-query.js";
+// The pairing of a registry and the manifests it analyzed — the one seam a host
+// threads for every question that needs both.
+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 type {
     AnalysisDiagnostic,

package/src/invocation-contract.ts

@@ -1,4 +1,6 @@
 import { isLiveSlot, type ResourceDefinition, valueTypeOf } from "@telorun/sdk";
+import { AliasResolver, moduleScopedDefResolver, type ModuleScopes } from "./alias-resolver.js";
+import { DefinitionRegistry } from "./definition-registry.js";
 import {
   type ContractDirection,
   contractDeclarer,
@@ -6,9 +8,34 @@ import {
   effectiveContractField,
 } from "./extends-resolution.js";
 import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+import {
+  manifestListScope,
+  resolveSchemaProjections,
+  type ProjectionFailure,
+} from "./schema-projection.js";
 
 export type { ContractDirection };
 
+/** The {@link ContractScope} the analyzer resolves invocation contracts in: kinds
+ *  resolve in the module that declared the definition they were read off (so an
+ *  `extends` chain crossing module boundaries re-scopes at every hop), and named
+ *  `telo#Type` references resolve against the flattened manifest list. `resolveIn`
+ *  is the top-level entry point, where the kind was written by the READING
+ *  module and there is no declaring definition yet. */
+export function analyzerContractScope(
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  scopes: ModuleScopes,
+  allManifests: Record<string, any>[],
+): ContractScope & { resolveIn(kind: string, module?: string): ResourceDefinition | undefined } {
+  const resolve = moduleScopedDefResolver<ResourceDefinition>(defs, aliases, scopes);
+  return {
+    resolveDefinition: resolve,
+    resolveIn: resolve.in,
+    typeManifestsFor: () => allManifests,
+  };
+}
+
 /**
  * The one answer to "what is this target's input / output schema".
  *
@@ -80,11 +107,20 @@ export function resolveContract(
   manifest: Record<string, any> | undefined,
   definition: ResourceDefinition | undefined,
   scope: ContractScope,
+  /** Collects declaration-derived slots that could not be projected. Omitted by
+   *  every caller that only wants the schema; the one pass that REPORTS them
+   *  passes an array. */
+  projectionFailures?: ProjectionFailure[],
 ): ResolvedContract | undefined {
   const own = manifest?.[direction];
   if (own !== undefined && own !== null) {
     const schema = resolveTypeFieldToSchema(own, scope.typeManifestsFor(definition));
-    if (schema) return { schema, origin: "instance" };
+    if (schema) {
+      return {
+        schema: projectionResolved(schema, manifest, scope, definition, projectionFailures),
+        origin: "instance",
+      };
+    }
   }
 
   const declared = effectiveContractField(definition, scope.resolveDefinition, direction);
@@ -92,7 +128,36 @@ export function resolveContract(
   const declarer = contractDeclarer(definition, scope.resolveDefinition, direction);
   const schema = resolveTypeFieldToSchema(declared, scope.typeManifestsFor(declarer));
   if (!schema) return undefined;
-  return { schema, origin: "kind", declaredBy: declarer };
+  return {
+    schema: projectionResolved(schema, manifest, scope, declarer, projectionFailures),
+    origin: "kind",
+    declaredBy: declarer,
+  };
+}
+
+/**
+ * A contract may be DECLARATION-derived: a kind whose `outputType` projects the
+ * declaration of a resource it references (a repository typing its rows from
+ * the table it reads). The manifest is in hand here and nowhere later, so this
+ * is where the projection is resolved — and it is resolved for a kind-declared
+ * contract and an instance-declared one alike, since either may carry one.
+ */
+function projectionResolved(
+  schema: Record<string, any>,
+  manifest: Record<string, any> | undefined,
+  scope: ContractScope,
+  declarer: ResourceDefinition | undefined,
+  failures?: ProjectionFailure[],
+): Record<string, any> {
+  return resolveSchemaProjections(
+    schema,
+    manifest,
+    manifestListScope(
+      scope.typeManifestsFor(declarer),
+      (kind) => scope.resolveDefinition(kind) as Record<string, any> | undefined,
+    ),
+    failures,
+  ) as Record<string, any>;
 }
 
 /** {@link resolveContract}, falling back to {@link PERMISSIVE_CONTRACT}. For

package/src/loaded-types.ts

@@ -70,9 +70,11 @@ export interface ImportEdge {
    *  this (minus its version), since it names the module's location
    *  independently of what the module declares about itself. */
   targetRef: string;
-  /** Target library's `metadata.name`, or `null` when the target had no
-   *  Telo.Library doc (an error case captured in `LoadedGraph.errors`). */
-  targetModuleName: string | null;
+  /** Target library's `metadata.name`. Never absent: an import whose target
+   *  names no library identity registers no edge at all and is reported in
+   *  `LoadedGraph.errors`, so an edge that exists is one every consumer can
+   *  resolve a kind through. */
+  targetModuleName: string;
   /** DEPRECATED. Target library's `metadata.namespace`, or `null` when it
    *  declares none. Feeds only the legacy `<namespace>/<module>#<Kind>` form
    *  of `x-telo-ref`; nothing else reads it. */
@@ -137,5 +139,12 @@ export interface GraphLoadError {
   alias?: string;
   /** Line of the `Telo.Import` doc in `fromSource`, for position fallback. */
   sourceLine?: number;
+  /** Why this import is unusable. `"unresolved"` (the default) means the target
+   *  was never obtained — an unreachable or unrecognizable source, which the
+   *  author fixes in their own file. `"unusable-target"` means it WAS obtained
+   *  and is not an importable library, which is a defect in the target module.
+   *  Kept apart because the two call for different actions; consumers phrase
+   *  them differently rather than asserting one cause for both. */
+  reason?: "unresolved" | "unusable-target";
   error: Error;
 }

package/src/manifest-analysis.ts

@@ -0,0 +1,132 @@
+/**
+ * **One analyzed manifest set, and the questions asked of it.**
+ *
+ * Several answers a host needs require the SAME two things: the registry's
+ * definitions and aliases, and the manifest set they were resolved against. The
+ * registry deliberately holds no manifests — it is populated per analysis and
+ * reused across them — so each such answer would otherwise become another
+ * factory on the registry and another optional parameter on every IDE entry
+ * point. Four of those arrived in short order (CEL scope, step declarations,
+ * context-binding declarations, invocation contracts) and the next one is not
+ * hypothetical.
+ *
+ * So the pairing is named once and the questions hang off it. A host threads ONE
+ * object and gains later questions for free; each facet keeps its own honest
+ * name rather than accreting onto whichever one happened to exist first.
+ *
+ * Nothing here re-implements an answer. `contractFor` is the shared
+ * {@link resolveContract} — the one `telo check` runs and the kernel binds at
+ * dispatch — given the scope to run in; `celScope` is the same
+ * {@link CelScopeQuery} the analysis pass's rule is built from. That is the
+ * whole point: a completion list is a claim about what the checker accepts, and
+ * a second implementation of any of these could not be held to it.
+ */
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { AliasResolver, type ModuleScopes } from "./alias-resolver.js";
+import { CelScopeQuery, type CelScopeQueryContext } from "./cel-scope-query.js";
+import { DefinitionRegistry } from "./definition-registry.js";
+import type { ContractDirection } from "./extends-resolution.js";
+import { analyzerContractScope, resolveContract } from "./invocation-contract.js";
+import { findManifest } from "./find-manifest.js";
+import { isModuleKind } from "./module-kinds.js";
+
+/**
+ * A reference as the loader leaves it — the internal `{kind, name, alias?}`
+ * shape `resolveRefSentinels` rewrites `!ref` into.
+ */
+export interface ManifestRef {
+  kind?: string;
+  name?: string;
+  alias?: string;
+}
+
+export class ManifestAnalysis {
+  private readonly scopes: ModuleScopes;
+  private celScopeQuery: CelScopeQuery | undefined;
+
+  constructor(
+    readonly manifests: ResourceManifest[],
+    private readonly ctx: CelScopeQueryContext,
+  ) {
+    const rootModules = new Set<string>();
+    for (const m of manifests) {
+      if (isModuleKind(m.kind) && m.metadata?.name) rootModules.add(m.metadata.name as string);
+    }
+    this.scopes = { aliasesByModule: ctx.aliasesByModule, rootModules };
+  }
+
+  /** What CEL sees, per site. Built on first use — its indices are a function of
+   *  the whole set, and a host that never opens a CEL body should not pay for
+   *  them. */
+  get celScope(): CelScopeQuery {
+    return (this.celScopeQuery ??= new CelScopeQuery(this.manifests, this.ctx));
+  }
+
+  /** The manifest a `(kind, name)` pair addresses. */
+  resourceFor(kind: string | undefined, name: string | undefined): ResourceManifest | undefined {
+    return findManifest(this.manifests, kind, name);
+  }
+
+  /**
+   * The invocation contract of the resource a reference names.
+   *
+   * The shared resolver, so an editor offering a target's input keys is offering
+   * exactly what `telo check` validates that call site against and what the
+   * kernel binds at dispatch. Layered instance-first: a resource declaring its
+   * own `inputType:` narrows the kind's, which is the common case for a
+   * `Run.Sequence` used as a handler.
+   */
+  contractFor(ref: ManifestRef, direction: ContractDirection): Record<string, any> | undefined {
+    const target = this.resolveRef(ref);
+    const definition = ref.kind ? this.definitionFor(ref.kind) : undefined;
+    if (!target && !definition) return undefined;
+    return resolveContract(
+      direction,
+      target as Record<string, any> | undefined,
+      definition,
+      analyzerContractScope(
+        this.ctx.defs,
+        this.ctx.aliases,
+        this.scopes,
+        this.manifests as Record<string, any>[],
+      ),
+    )?.schema;
+  }
+
+  /**
+   * The manifest a reference names.
+   *
+   * An ALIAS narrows before the name does: a flattened set carries every
+   * imported library's exported instances, so two libraries exporting a `store`
+   * are two manifests with one name. Matching the alias to its target module
+   * picks the right one; where the alias resolves to nothing the name alone is
+   * used, which is what a local reference needs anyway.
+   */
+  private resolveRef(ref: ManifestRef): ResourceManifest | undefined {
+    if (!ref.name) return undefined;
+    const byName = this.manifests.filter(
+      (m) => (m.metadata as { name?: string } | undefined)?.name === ref.name,
+    );
+    if (byName.length === 0) return undefined;
+    if (byName.length === 1) return byName[0];
+
+    const targetModule = ref.alias ? this.ctx.aliases.moduleForAlias?.(ref.alias) : undefined;
+    if (targetModule) {
+      const scoped = byName.find(
+        (m) => (m.metadata as { module?: string } | undefined)?.module === targetModule,
+      );
+      if (scoped) return scoped;
+    }
+    // Several candidates and nothing to choose between them: refusing is the
+    // honest answer, since typing a call site against the wrong resource's
+    // contract is worse than typing it against none.
+    return ref.kind ? byName.find((m) => m.kind === ref.kind) : undefined;
+  }
+
+  private definitionFor(kind: string): ResourceDefinition | undefined {
+    const canonical = this.ctx.aliases.resolveKind(kind);
+    return this.ctx.defs.resolve(kind) ?? (canonical ? this.ctx.defs.resolve(canonical) : undefined);
+  }
+}
+
+export type { CelScopeQueryContext, AliasResolver, DefinitionRegistry };

package/src/manifest-loader.ts

@@ -57,6 +57,62 @@ function collectMigrationDiagnostics(entry: LoadedModule): AnalysisDiagnostic[]
   return diagnostics;
 }
 
+/** The identity an import target contributes to its importer, or the reason it
+ *  contributes none.
+ *
+ *  Every way an import can be unusable answers here, in one place and without
+ *  throwing: the target is an application, it carries no library document at
+ *  all, or it carries one that never names itself. A name is not decoration —
+ *  it is the kind prefix every `Alias.Kind` in the importer resolves through —
+ *  so a target that has none is as unusable as one that was never fetched, and
+ *  is reported the same way rather than left to surface later as an invented
+ *  module nobody declared. */
+type ImportTargetIdentity =
+  | { name: string; namespace: string | null }
+  | { unusable: string };
+
+function importTargetIdentity(target: LoadedModule, importSource: string): ImportTargetIdentity {
+  const library = target.owner.manifests.find((m) => m?.kind === "Telo.Library");
+  const application = target.owner.manifests.find((m) => m?.kind === "Telo.Application");
+
+  if (!library && application) {
+    return {
+      unusable:
+        `Telo.Import target '${importSource}' is a Telo.Application. ` +
+        `Only Telo.Library modules may be imported. Applications are run directly, not imported. ` +
+        `Point this import at a library, or drop it and run that application on its own.`,
+    };
+  }
+
+  if (!library) {
+    const kinds = target.owner.manifests
+      .map((m) => m?.kind)
+      .filter((k): k is string => typeof k === "string");
+    const detail = kinds.length
+      ? `Fetched ${target.owner.manifests.length} document(s) with kinds [${kinds.join(", ")}].`
+      : `Fetched manifest contained no recognizable Telo documents — check that the source ` +
+        `serves a Telo.Library manifest and not an upstream error page.`;
+    return {
+      unusable:
+        `Telo.Import target '${importSource}' did not resolve to a Telo.Library. ` +
+        `Fetched from: ${target.owner.source}. ${detail}`,
+    };
+  }
+
+  const name = library.metadata?.name;
+  if (typeof name !== "string" || name === "") {
+    return {
+      unusable:
+        `Telo.Import target '${importSource}' resolved to a Telo.Library that declares no ` +
+        `'metadata.name'. Fetched from: ${target.owner.source}. A library's name is the kind ` +
+        `prefix its importers reference, so it cannot be imported until the target declares one.`,
+    };
+  }
+
+  const namespace = (library.metadata as { namespace?: string | null } | undefined)?.namespace;
+  return { name, namespace: typeof namespace === "string" ? namespace : null };
+}
+
 const SYSTEM_KINDS = new Set([
   "Telo.Application",
   "Telo.Library",
@@ -320,10 +376,10 @@ export class Loader {
           // Resolve the file we'll fetch through the source chain to get the
           // canonical `source` URL — same identity used as the modules-map key.
           let targetCanonical: string;
-          let targetModule: LoadedModule | undefined;
+          let targetModule: LoadedModule;
           if (modules.has(resolvedTarget)) {
             targetCanonical = resolvedTarget;
-            targetModule = modules.get(resolvedTarget);
+            targetModule = modules.get(resolvedTarget)!;
           } else {
             try {
               const loaded = await this.loadModule(resolvedTarget, options);
@@ -332,7 +388,7 @@ export class Loader {
                 modules.set(targetCanonical, loaded);
                 targetModule = loaded;
               } else {
-                targetModule = modules.get(targetCanonical);
+                targetModule = modules.get(targetCanonical)!;
               }
             } catch (err) {
               const e = err instanceof Error ? err : new Error(String(err));
@@ -349,32 +405,42 @@ export class Loader {
             }
           }
 
-          // Resolve target identity from its Telo.Library doc and stamp it
-          // on the edge — flattenForAnalyzer reads from the edge directly,
-          // never re-deriving from manifest.metadata.
-          let targetModuleName: string | null = null;
-          let targetNamespace: string | null = null;
-          if (targetModule) {
-            const lib = targetModule.owner.manifests.find(
-              (d) => d?.kind === "Telo.Library",
-            );
-            const libName = lib?.metadata?.name;
-            if (typeof libName === "string") targetModuleName = libName;
-            const libNs = (lib?.metadata as { namespace?: string | null } | undefined)
-              ?.namespace;
-            if (typeof libNs === "string") targetNamespace = libNs;
+          // Resolve target identity from its Telo.Library doc and stamp it on
+          // the edge — flattenForAnalyzer reads from the edge directly, never
+          // re-deriving from manifest.metadata.
+          //
+          // Checked per IMPORT rather than per distinct target: an import
+          // pointing at a module something else already reached (the entry
+          // application above all) would otherwise skip the check entirely and
+          // register a nameless edge. An unusable target is recorded exactly
+          // like an unfetchable one — an error against this import, no edge,
+          // and the rest of the graph still loads — so no consumer has to know
+          // the difference between the two ways an import can fail.
+          const identity = importTargetIdentity(targetModule, importSource);
+          if ("unusable" in identity) {
+            const e = new Error(identity.unusable);
+            (e as { sourceLine?: number }).sourceLine = sourceLine;
+            errors.push({
+              url: targetCanonical,
+              source: importSource,
+              fromSource: file.source,
+              alias,
+              sourceLine,
+              reason: "unusable-target",
+              error: e,
+            });
+            continue;
           }
 
           aliases.set(alias, {
             targetSource: targetCanonical,
             targetRef: importSource,
-            targetModuleName,
-            targetNamespace,
+            targetModuleName: identity.name,
+            targetNamespace: identity.namespace,
           });
 
-          if (targetModule && !visited.has(targetCanonical)) {
+          if (!visited.has(targetCanonical)) {
             visited.add(targetCanonical);
-            this.assertImportTargetIsLibrary(targetModule, importSource, sourceLine);
             queue.push(targetModule);
           }
         }
@@ -444,40 +510,6 @@ export class Loader {
     }
   }
 
-  private assertImportTargetIsLibrary(
-    target: LoadedModule,
-    importSource: string,
-    sourceLine: number,
-  ): void {
-    const importedLibrary = target.owner.manifests.find((m) => m?.kind === "Telo.Library");
-    const importedApplication = target.owner.manifests.find(
-      (m) => m?.kind === "Telo.Application",
-    );
-    if (importedApplication) {
-      const e = new Error(
-        `Telo.Import target '${importSource}' is a Telo.Application. ` +
-          `Only Telo.Library modules may be imported. Applications are run directly, not imported.`,
-      );
-      (e as { sourceLine?: number }).sourceLine = sourceLine;
-      throw e;
-    }
-    if (!importedLibrary) {
-      const kinds = target.owner.manifests
-        .map((m) => m?.kind)
-        .filter((k): k is string => typeof k === "string");
-      const detail = kinds.length
-        ? `Fetched ${target.owner.manifests.length} document(s) with kinds [${kinds.join(", ")}].`
-        : `Fetched manifest contained no recognizable Telo documents — check that the source ` +
-          `serves a Telo.Library manifest and not an upstream error page.`;
-      const e = new Error(
-        `Telo.Import target '${importSource}' did not resolve to a Telo.Library. ` +
-          `Fetched from: ${target.owner.source}. ${detail}`,
-      );
-      (e as { sourceLine?: number }).sourceLine = sourceLine;
-      throw e;
-    }
-  }
-
   private async resolveIncludes(
     ownerSource: string,
     patterns: string[],

package/src/manifest-path.ts

@@ -0,0 +1,34 @@
+/**
+ * Navigating a MANIFEST by a concrete path (`routes[0].request.schema.query`).
+ *
+ * The counterpart to `schema-walk.ts`, which navigates a schema: this addresses
+ * the author's own document, indices and all. Its own module because three
+ * places needed it independently — the CEL scope query resolving a context
+ * binding's declaration, the call-site checker resolving an argument map, and
+ * the IDE resolving the same map for completion — and three copies of one
+ * traversal is exactly what the shared-answer rule exists to prevent.
+ */
+
+/**
+ * The value at `path`, or `undefined` when any segment is absent.
+ *
+ * Absence is what makes a candidate path a CHECK rather than a guess: a caller
+ * offering several possible shapes can try each and know a hit is a real node.
+ */
+export function navigateConcretePath(root: Record<string, any>, path: string): unknown {
+  let current: unknown = root;
+  for (const segment of path.split(".")) {
+    if (!segment) continue;
+    const match = segment.match(/^([^[]*)((?:\[\d+\])*)$/);
+    if (!match) return undefined;
+    if (match[1]) {
+      if (current === null || typeof current !== "object") return undefined;
+      current = (current as Record<string, unknown>)[match[1]];
+    }
+    for (const index of match[2].matchAll(/\[(\d+)\]/g)) {
+      if (!Array.isArray(current)) return undefined;
+      current = current[Number(index[1])];
+    }
+  }
+  return current;
+}