@telorun/analyzer 0.56.1 → 0.58.0

package/src/schema-compat.ts

@@ -1,7 +1,20 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isRefSentinel, isTaggedSentinel, ManifestRootSchema, normalizeRefSlots } from "@telorun/templating";
-import { binaryKeyword, isBinarySlot } from "./binary-slot.js";
+import {
+  isRefSentinel,
+  isTaggedSentinel,
+  ManifestRootSchema,
+  producedTypeOf,
+} from "@telorun/templating";
+import {
+  celBaseOfValueType,
+  celTypeOfValueType,
+  readValueTypeSlot,
+  valueBrandBases,
+  valueTypeOf,
+  valueTypePlaceholder,
+} from "@telorun/sdk";
+import { registerTeloKeywords } from "./value-type-keyword.js";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
 
@@ -18,10 +31,11 @@ export function createAjv(): InstanceType<typeof Ajv> {
   (addFormats as any).default
     ? (addFormats as any).default(instance)
     : (addFormats as any)(instance);
-  // Bytes have no JSON Schema type, so the annotation carries the check. Registered
-  // here and in the kernel's validators from one definition, so a literal at a byte
-  // slot is rejected statically and at dispatch by the identical rule.
-  instance.addKeyword(binaryKeyword());
+  // One registration site for every Telo keyword — the annotations as no-ops and
+  // `x-telo-type` as the one that checks. Registered here and in the kernel's
+  // validators from one definition, so a literal at an instance-typed slot is
+  // rejected statically and at dispatch by the identical rule.
+  registerTeloKeywords(instance);
   instance.addSchema(ManifestRootSchema);
   return instance;
 }
@@ -34,62 +48,170 @@ export interface CompatibilityResult {
   issues: string[];
 }
 
-/** Conservative structural JSON Schema compatibility check.
- *  Only flags definite mismatches: missing required fields and primitive type conflicts.
- *  Ambiguous cases (anyOf/oneOf/etc.) are treated as compatible. */
+/**
+ * Conservative structural JSON Schema compatibility check — is a value shaped
+ * like `source` acceptable where `target` is declared?
+ *
+ * COVARIANT, because the values this compares are consumed by reading: a
+ * narrower element satisfies a slot declaring a wider one. Only DEFINITE
+ * mismatches are flagged — a missing required field, a primitive type conflict,
+ * a disagreeing type argument. Anything ambiguous (`anyOf` / `oneOf` / `allOf`,
+ * an absent `type`, an undeclared argument) is treated as compatible, so an
+ * unmigrated producer and consumer keep checking exactly as they did.
+ *
+ * The traversal is written here rather than reused: the function this replaced
+ * compared only `type` for the names in `target.required` and descended only
+ * into objects, so a stream of arrays of strings and a stream of arrays of
+ * integers both read as `array` and passed — leaving argument checking inert on
+ * exactly the nested shapes it exists for. What survives from it is its posture.
+ *
+ * `resolveRef` sees through a named shape. Declaring a shape once and
+ * referencing it is the sanctioned way to reuse one, so without it two such
+ * arguments present as opaque nodes carrying no information — the same reason
+ * {@link withLiveValuesSkipped} takes one.
+ */
 export function checkSchemaCompatibility(
   source: Record<string, any>,
   target: Record<string, any>,
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
 ): CompatibilityResult {
   const issues: string[] = [];
-  checkObject(source, target, "", issues);
+  compare(source, target, "", issues, resolveRef, new Set());
   return { compatible: issues.length === 0, issues };
 }
 
-function checkObject(
-  source: Record<string, any>,
-  target: Record<string, any>,
+type RefResolver = ((ref: string) => Record<string, any> | undefined) | undefined;
+
+function deref(schema: Record<string, any>, resolveRef: RefResolver): Record<string, any> {
+  if (!resolveRef || typeof schema.$ref !== "string") return schema;
+  return resolveRef(schema.$ref) ?? schema;
+}
+
+function compare(
+  rawSource: Record<string, any>,
+  rawTarget: Record<string, any>,
   path: string,
   issues: string[],
+  resolveRef: RefResolver,
+  seen: Set<string>,
 ): void {
-  const targetRequired: string[] = target.required ?? [];
-  const sourceProps: Record<string, any> = source.properties ?? {};
-  const targetProps: Record<string, any> = target.properties ?? {};
-
-  for (const field of targetRequired) {
-    if (!(field in sourceProps)) {
-      issues.push(`${path}/${field}: required by target but missing from source`);
-      continue;
+  if (!rawSource || !rawTarget || typeof rawSource !== "object" || typeof rawTarget !== "object") {
+    return;
+  }
+  // A recursive shape reached through the same pair of references twice is the
+  // same question again; answering it once terminates and loses nothing.
+  //
+  // The key is the REFERENCE PAIR and deliberately not the path. A path grows on
+  // every descent, so a key containing it is new every time and the guard never
+  // fires — which is a stack overflow on the first self-referential shape, taking
+  // every other diagnostic in the file with it. It also has to be this way to be
+  // correct rather than merely terminating: comparing two schemas gives the same
+  // answer wherever they are reached from, so the second visit has nothing to add.
+  if (typeof rawSource.$ref === "string" && typeof rawTarget.$ref === "string") {
+    const key = `${rawSource.$ref}|${rawTarget.$ref}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+  }
+  const source = deref(rawSource, resolveRef);
+  const target = deref(rawTarget, resolveRef);
+
+  // Value types first: an `instance` representation has no JSON `type` to
+  // compare, so its identity IS the comparison — and its arguments are where the
+  // real information lives.
+  const sourceType = readValueTypeSlot(source);
+  const targetType = readValueTypeSlot(target);
+  if (sourceType && targetType) {
+    if (sourceType.name !== targetType.name) {
+      issues.push(
+        `${path || "/"}: value type mismatch — source is '${sourceType.name}', target expects '${targetType.name}'`,
+      );
+      return;
     }
-    const srcProp = sourceProps[field];
-    const tgtProp = targetProps[field];
-    if (tgtProp && srcProp) {
-      checkProperty(srcProp, tgtProp, `${path}/${field}`, issues);
+    for (const [argument, targetArg] of Object.entries(targetType.args)) {
+      const sourceArg = sourceType.args[argument];
+      // An omitted argument is *any*, in BOTH directions. That is what keeps a
+      // bare `Telo.Stream` flowing into a typed slot and vice versa, so nothing
+      // that does not declare its element is forced to.
+      if (sourceArg === undefined) continue;
+      compare(
+        sourceArg as Record<string, any>,
+        targetArg as Record<string, any>,
+        `${path}<${argument}>`,
+        issues,
+        resolveRef,
+        seen,
+      );
     }
+    return;
   }
-}
 
-function checkProperty(
-  source: Record<string, any>,
-  target: Record<string, any>,
-  path: string,
-  issues: string[],
-): void {
-  // Only flag definite primitive type clashes; skip anyOf/oneOf/allOf
+  // One side declares a value type and the other does not. A `json`
+  // representation refines a base type, so it is compared through that base — a
+  // `Telo.TcpPort` into a plain `integer` slot is gradual typing working. An
+  // `instance` is not JSON at all, so ANY declared JSON type on the other side is
+  // a definite conflict; a side declaring no type at all is still saying nothing
+  // and stays compatible.
+  if (Boolean(sourceType) !== Boolean(targetType)) {
+    const declared = (sourceType ?? targetType)!;
+    const other = sourceType ? target : source;
+    if (declared.entry && typeof other.type === "string") {
+      const base = celBaseOfValueType(declared.entry);
+      const asJson = base === undefined ? undefined : declared.entry.base;
+      if (asJson !== other.type) {
+        issues.push(
+          `${path || "/"}: value type mismatch — ${
+            sourceType ? "source is" : "target expects"
+          } '${declared.name}', ${sourceType ? "target expects" : "source is"} '${other.type}'`,
+        );
+        return;
+      }
+    }
+  }
+
+  // Only flag definite primitive type clashes; an absent or union `type` says
+  // too little to judge.
   if (
-    source.type &&
-    target.type &&
     typeof source.type === "string" &&
     typeof target.type === "string" &&
     source.type !== target.type
   ) {
     issues.push(
-      `${path}: type mismatch — source is '${source.type}', target expects '${target.type}'`,
+      `${path || "/"}: type mismatch — source is '${source.type}', target expects '${target.type}'`,
     );
     return;
   }
-  if (target.type === "object" && source.type === "object") {
-    checkObject(source, target, path, issues);
+  if (source.anyOf || source.oneOf || source.allOf) return;
+  if (target.anyOf || target.oneOf || target.allOf) return;
+
+  // An array's element, which the old comparison never looked at — so every
+  // nested shape passed regardless of what it contained.
+  if (target.items && source.items) {
+    compare(
+      source.items as Record<string, any>,
+      target.items as Record<string, any>,
+      `${path}[]`,
+      issues,
+      resolveRef,
+      seen,
+    );
+  }
+
+  const targetRequired: string[] = Array.isArray(target.required) ? target.required : [];
+  const sourceProps: Record<string, any> = source.properties ?? {};
+  const targetProps: Record<string, any> = target.properties ?? {};
+  for (const field of targetRequired) {
+    if (!(field in sourceProps)) {
+      // Only when the source describes an object at all: a schema with no
+      // `properties` is saying nothing about its shape, not saying it is empty.
+      if (source.properties === undefined) continue;
+      issues.push(`${path}/${field}: required by target but missing from source`);
+      continue;
+    }
+    const srcProp = sourceProps[field];
+    const tgtProp = targetProps[field];
+    if (tgtProp && srcProp) {
+      compare(srcProp, tgtProp, `${path}/${field}`, issues, resolveRef, seen);
+    }
   }
 }
 
@@ -158,13 +280,8 @@ function schemaCompiles(schema: Record<string, any>): boolean {
 export function validateAgainstSchema(data: unknown, schema: Record<string, any>): SchemaIssue[] {
   let validate = compiledSchemaValidators.get(schema);
   if (!validate) {
-    // Normalize outside the try: a fault in our own ref-slot normalization must
-    // surface, never be mistaken for the module author's schema being malformed.
-    // Drop the legacy scalar `type` an older published module may still pin on
-    // its `x-telo-ref` slots so a resolved reference object validates.
-    const normalized = normalizeRefSlots(schema) as Record<string, any>;
     try {
-      validate = ajv.compile(normalized);
+      validate = ajv.compile(schema);
     } catch (err) {
       // The normalized schema didn't compile. If the original schema is itself
       // malformed, that is the module author's error — already surfaced once,
@@ -229,28 +346,36 @@ export function navigateSchemaToExprPath(
 }
 
 /**
- * Recognized `x-telo-type` value brands and the CEL primitive each refines.
+ * Every `json`-represented value type's CEL brand → the primitive it refines.
+ *
  * A brand is a nominal type the analyzer registers (see cel-environment.ts) so
- * structurally-identical values (a `TcpPort` and a `UdpPort` are both integers)
- * stay distinct for static wiring checks. Brands carry no runtime effect — the
- * value flows as its base type. Add new brands here (e.g. `Url: "string"`).
+ * structurally-identical values (a `Telo.TcpPort` and a `Telo.UdpPort` are both
+ * integers) stay distinct for static wiring checks. Brands carry no runtime
+ * effect — the value flows as its base type.
+ *
+ * DERIVED from the value-type vocabulary, never hand-written: a new brand is a
+ * new entry file, and a table here would be a second place to edit that could
+ * silently disagree with the one the runtime reads.
  */
-export const VALUE_BRAND_BASE: Record<string, string> = {
-  TcpPort: "int",
-  UdpPort: "int",
-};
+export const VALUE_BRAND_BASE: Record<string, string> = valueBrandBases();
 
-/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+/** Read a `json`-represented value type's brand off a schema, or undefined.
+ *  An `instance` type is not a brand — it replaces the JSON layer rather than
+ *  refining it, so it carries its binding's CEL type instead. */
 export function brandOfSchema(schema: Record<string, any> | undefined): string | undefined {
-  const brand = schema?.["x-telo-type"];
-  return typeof brand === "string" && brand in VALUE_BRAND_BASE ? brand : undefined;
+  const entry = valueTypeOf(schema);
+  return entry && entry.representation === "json" ? entry.name : undefined;
 }
 
 /** Map a JSON Schema type annotation to a CEL type string. */
 export function jsonSchemaToCelType(schema: Record<string, any> | undefined): string {
   if (!schema || typeof schema !== "object") return "dyn";
-  const brand = brandOfSchema(schema);
-  if (brand) return brand;
+  // A declared value type IS the type — for an `instance` representation it is
+  // the only thing that says so, since bytes and streams have no JSON Schema
+  // type at all. Before the three annotations were unified, a byte slot's
+  // expression typed as `dyn` because nothing here consulted `x-telo-binary`.
+  const entry = valueTypeOf(schema);
+  if (entry) return celTypeOfValueType(entry);
   if (schema.anyOf || schema.oneOf || schema.allOf) return "dyn";
   if (Array.isArray(schema.type)) return "dyn";
   switch (schema.type) {
@@ -289,6 +414,16 @@ export function celTypeSatisfiesJsonSchema(celType: string, schema: Record<strin
     if (fieldBrand) return fieldBrand === celType;
     celType = sourceBase;
   }
+  // An `instance` representation has no JSON Schema type to compare against, so
+  // an expression carrying its binding's CEL type is accepted on that ground
+  // alone. This ADDS a case and never removes one: a mismatch falls through to
+  // the rules below rather than being rejected here, so nothing that checks
+  // today stops checking, and the `bytes` row still accepts a byte expression at
+  // a plain `type: string` slot.
+  const slotEntry = valueTypeOf(schema);
+  if (slotEntry?.representation === "instance" && celTypeOfValueType(slotEntry) === celType) {
+    return true;
+  }
   if (!schema.type && !schema.anyOf && !schema.oneOf && !schema.allOf) return true;
   if (schema.anyOf || schema.oneOf || schema.allOf) return true;
   const schemaTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
@@ -376,11 +511,15 @@ function foldedConstraints(schema: Record<string, any>): Record<string, any> {
 
 export function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown {
   const schema = foldedConstraints(rawSchema);
-  // A byte slot's placeholder must BE bytes: the same keyword validates statically
-  // and at dispatch, so a CEL leaf standing in for a runtime buffer has to satisfy
-  // it. This is what keeps the rule single — a literal is rejected because no YAML
-  // literal is a Uint8Array, while a value arriving by reference passes.
-  if (isBinarySlot(schema)) return new Uint8Array();
+  // An instance-typed slot's placeholder must BE an instance: the same keyword
+  // validates statically and at dispatch, so a CEL leaf standing in for a runtime
+  // value has to satisfy it. This is what keeps the rule single — a literal is
+  // rejected because no YAML literal is a byte buffer, while a value arriving by
+  // reference passes. The stand-in comes from the binding table, so a new
+  // instance type brings its own rather than adding a branch here; a `live` type
+  // declares none, because nothing validates it.
+  const placeholder = valueTypePlaceholder(schema);
+  if (placeholder !== undefined) return placeholder;
   if (schema.default !== undefined) return schema.default;
   // An enum-constrained field needs a placeholder drawn from the enum: the
   // type-based fallbacks below ("" for a string, 0 for a number) satisfy `type`
@@ -564,6 +703,23 @@ export function substituteCelFields(
   if (isRefSentinel(data)) {
     return data;
   }
+  // A tag whose produced type is a CONSTANT of the tag rather than a function of
+  // the slot substitutes a placeholder of THAT type: `!include-text` always
+  // produces a string and `!include-bytes` always produces bytes. Collapsing
+  // them to a slot-shaped placeholder like a CEL expression would make every
+  // slot accept both, so a byte embed at a `type: string` field passed
+  // `telo check` and failed at resource creation — and the reverse did too.
+  // Substituting the real type lets AJV and the `x-telo-type` keyword reject
+  // both directions statically, with no new diagnostic code.
+  //
+  // The engine is what says so. This used to branch on two tag names, which was
+  // the only place a tag's produced type was written down and it was written in
+  // the consumer — so a future tag producing bytes had to be added to a set here
+  // rather than declaring it.
+  if (isTaggedSentinel(data)) {
+    const produced = producedTypeOf(data.engine);
+    if (produced) return celPlaceholderForSchema(produced);
+  }
   if (isTaggedSentinel(data)) {
     mark();
     return celPlaceholderForSchema(resolved);

package/src/schema-region.ts

@@ -0,0 +1,46 @@
+/**
+ * Where author-written JSON Schema lives in a manifest — one definition, read by
+ * every surface that has to bound itself to schema.
+ *
+ * The keys are the KERNEL's own schema-valued manifest keys, which no resource
+ * kind owns. That is what makes the rule generic: a surface using it learns no
+ * resource kind, and a module that invents a schema-bearing field of its own
+ * reaches it through one of these or not at all — against the topology-driven
+ * constraint, an enumeration of the standard library's kinds would be both
+ * incomplete and knowledge the analyzer must not hold.
+ *
+ * A schema fragment is NOT confined to kind documents. An inline `inputType:` /
+ * `outputType:` sits on any kind that declares one, an API route carries
+ * `request.schema.body`, a `Telo.JsonSchema` carries `schema`. So a check that
+ * walks a manifest's ROOT keys covers a fraction of the sites an author writes —
+ * which is a silent hole in exactly the checks that exist to stop a silent
+ * degrade. Containment is by ANCESTRY instead: a node is in a schema region when
+ * some key on the path to it is one of these.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+
+/** The kernel's schema-valued manifest keys. */
+export const SCHEMA_REGION_KEYS: readonly string[] = [
+  "schema",
+  "status",
+  "inputType",
+  "outputType",
+  "itemType",
+];
+
+/**
+ * True when `path` reaches into a schema region — some ANCESTOR segment is a
+ * schema-valued key.
+ *
+ * Ancestors only, so a rule keyed on a region key itself still means "inside a
+ * schema" rather than "is one". `path` is the walk's own segment list; numeric
+ * segments (array indices) never equal a key name, so they need no special case.
+ */
+export function isInSchemaRegion(path: readonly (string | number)[]): boolean {
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    if (typeof segment === "string" && SCHEMA_REGION_KEYS.includes(segment)) return true;
+  }
+  return false;
+}

package/src/types.ts

@@ -31,6 +31,36 @@ export type PositionIndex = Map<string, Range>;
 
 /** LSP-compatible Diagnostic shape. range is optional because parsed YAML may not carry
  *  position info when only the parsed object (not raw text) is available. */
+/** A mechanically applicable repair, carried unchanged from whatever produced
+ *  it (a templating engine, a kind-name suggestion) to every consumer: CLI
+ *  JSON, IDE CodeActions, an agent applying it without re-deriving it from
+ *  prose.
+ *
+ *  `replacement` is the **whole** value at the diagnostic's `path`, corrected —
+ *  never a fragment — so applying it needs no knowledge of the language inside.
+ *  There is deliberately no sub-range: carrying one beside a whole-value
+ *  replacement gives the field two readings, and the minimal-edit reading
+ *  (splice `replacement` at `range`) produces garbage because the two measure
+ *  different strings.
+ *
+ *  One shape rather than one per producer: a `fix` field beside a
+ *  `suggestedKind` field beside a CEL-specific one would leave every host
+ *  wiring a separate action path for what is the same gesture. */
+export interface DiagnosticFix {
+  readonly replacement: string;
+}
+
+/** The `data` stamp diagnostics carry. Loose by design — passes bolt their own
+ *  keys on — but the fields every consumer reads are declared. */
+export interface DiagnosticData {
+  resource?: { kind: string; name: string };
+  filePath?: string;
+  /** Dotted path of the offending value within its resource. */
+  path?: string;
+  fix?: DiagnosticFix;
+  [key: string]: unknown;
+}
+
 export interface AnalysisDiagnostic {
   range?: Range;
   severity?: DiagnosticSeverity;
@@ -42,6 +72,13 @@ export interface AnalysisDiagnostic {
   data?: unknown;
 }
 
+/** Single reader for a diagnostic's fix, so no consumer re-derives the shape
+ *  by hand-casting `data`. */
+export function diagnosticFix(d: AnalysisDiagnostic): DiagnosticFix | undefined {
+  const fix = (d.data as DiagnosticData | undefined)?.fix;
+  return fix && typeof fix.replacement === "string" ? fix : undefined;
+}
+
 export interface ManifestSource {
   supports(url: string): boolean;
   read(url: string): Promise<{ text: string; source: string }>;
@@ -73,12 +110,29 @@ export interface LoadOptions {
    *  pairs manifests to YAML nodes by index. Folded into the file cache key so a
    *  desugared and a raw load of the same file never collide. */
   desugarImports?: boolean;
+  /** When true, the loader's migration phase rewrites legacy spellings in each
+   *  parsed document before anything else reads the tree. On for every resolved
+   *  consumer — the kernel's analysis and runtime loads, `telo check`, the
+   *  analyzer — so one rewrite serves the definition registry, the runtime and
+   *  the editor's analysis alike.
+   *
+   *  **Off for a round-trip view.** The editor pairs manifests to YAML nodes by
+   *  index and writes the pair back on save; migrating one half of that pair
+   *  would silently change the author's file. `telo migrate` is likewise a raw
+   *  consumer — it rewrites the YAML itself and must see the legacy spelling to
+   *  find it. Folded into the file cache key so a migrated and a raw load of
+   *  the same file never collide. */
+  migrate?: boolean;
 }
 
 export interface LoaderInitOptions {
   /** Handlers for CEL stdlib functions (e.g. `sha256`). Analyzer-only callers may
    *  omit this and get throwing stubs; runtime callers (kernel) must supply real impls. */
   celHandlers?: import("./cel-environment.js").CelHandlers;
+  /** Migration set for `LoadOptions.migrate` loads. Defaults to the analyzer's
+   *  own `CORE_MIGRATIONS`. A host supplies its own once module-shipped entries
+   *  are aggregated alongside the core ones. */
+  migrations?: readonly import("./migrations/types.js").MigrationEntry[];
 }
 
 export interface AnalysisOptions {

package/src/validate-cel-context.ts

@@ -1,5 +1,5 @@
 export { extractAccessChains, validateChainAgainstSchema } from "@telorun/templating";
-import { mergeTypeSchemas } from "@telorun/sdk";
+import { mergeTypeSchemas, parseCanonicalTypeSchemaId } from "@telorun/sdk";
 import { KERNEL_BUILTINS } from "./builtins.js";
 
 export interface ContextResolveOpts {
@@ -89,6 +89,38 @@ export function resolveTypeFieldToSchema(
 
   if (typeof value === "object" && value !== null) {
     const obj = value as Record<string, any>;
+    // A canonical, module-scoped id — what `resolveSchemaTypeRefs` normalizes
+    // both the reference tag and the legacy `telo://` authority form into.
+    //
+    // This is the ALIAS-AWARE path, and it is why the canonical form exists:
+    // the id names the OWNING MODULE, so two libraries declaring a shape of the
+    // same name stay distinct. The bare-name lookup below cannot do that — it
+    // matches the first manifest with that `metadata.name` in a flattened list,
+    // which is how an alias got silently dropped.
+    const canonical = parseCanonicalTypeSchemaId(obj.$ref);
+    if (canonical) {
+      if (ancestry.has(obj.$ref)) return undefined;
+      const owned = allManifests.find(
+        (m) =>
+          (m.metadata as any)?.name === canonical.typeName &&
+          (m.metadata as any)?.module === canonical.moduleName &&
+          isTypeKind(m.kind, allManifests) &&
+          typeof m.schema === "object" &&
+          m.schema !== null,
+      );
+      if (owned) {
+        return applyExtends(
+          owned.schema as Record<string, any>,
+          owned.extends,
+          allManifests,
+          new Set(ancestry).add(obj.$ref),
+        );
+      }
+      // A module that is not in this set — a single-file analysis, or an import
+      // whose library was not forwarded. Fall through to the bare name, which is
+      // what this resolved before the canonical form existed.
+      return resolveTypeFieldToSchema(canonical.typeName, allManifests, ancestry);
+    }
     // Inline type resource: { kind: "Type.JsonSchema", schema: {...} }
     if (obj.schema && typeof obj.schema === "object") {
       return applyExtends(obj.schema as Record<string, any>, obj.extends, allManifests, ancestry);
@@ -97,8 +129,9 @@ export function resolveTypeFieldToSchema(
     if (obj.type || obj.properties) {
       return obj;
     }
-    // Named type reference resolved from a `!ref` → { kind, name } — resolve the
-    // named Telo.Type the same way as the bare-string form.
+    // Named type reference resolved from a `!ref` → { kind, name }. Reached only
+    // where the canonical rewrite could not run (a scope whose aliases are not in
+    // hand); resolves by bare name, as it always has.
     if (typeof obj.name === "string") {
       return resolveTypeFieldToSchema(obj.name, allManifests, ancestry);
     }

package/src/validate-include-placement.ts

@@ -0,0 +1,70 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { INCLUDE_ENGINE_NAMES, walkCelExpressions } from "@telorun/templating";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Docs that are never instantiated as resources.
+ *
+ * `Telo.Application` / `Telo.Library` are module declarations, and `Telo.Import`
+ * is a dependency edge — none of the three reaches a controller's `create()`.
+ * `Telo.Definition` and `Telo.Abstract` are deliberately absent: a definition's
+ * template body (`resources:` / `invoke:` / `run:` / `provide:`) DOES become
+ * resources, so an embed there resolves normally.
+ */
+const NEVER_INSTANTIATED: ReadonlySet<string> = new Set([
+  "Telo.Application",
+  "Telo.Library",
+  "Telo.Import",
+]);
+
+/**
+ * An `!include-text` / `!include-bytes` in a doc that is never instantiated is
+ * never read.
+ *
+ * The two tags resolve when the resource owning them is created — deferred so
+ * that loading a manifest does not pull payload layers, which is the property
+ * the artifact spec protects by giving `telo.yaml` a layer of its own. The cost
+ * of that choice is this dead spot: a doc with no `create()` has no moment at
+ * which the file would be read, so the value stays an unresolved marker and
+ * whatever reads it sees a sentinel object instead of the file's contents.
+ *
+ * Nothing else would report it. There is no controller to validate against a
+ * schema and no runtime consumer to fail, so the manifest ships looking correct
+ * — exactly the silent-no-op failure mode that makes a descriptive field worth
+ * checking. Hence an error at the one place that can see it.
+ *
+ * Deliberately narrow: it reports only where the argument is complete ("this
+ * doc is never instantiated"). A JSON-Schema region *inside* a definition —
+ * `schema:`, `inputType:` — is equally unreadable, but that is a general
+ * question about tags in schema metadata rather than one about these two, and
+ * no pass answers it for any tag today.
+ */
+export function validateIncludePlacement(manifests: ResourceManifest[]): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  for (const manifest of manifests) {
+    if (!NEVER_INSTANTIATED.has(manifest.kind)) continue;
+    const name = (manifest.metadata as { name?: string } | undefined)?.name;
+    const filePath = (manifest.metadata as { source?: string } | undefined)?.source;
+    walkCelExpressions(manifest, "", (source, path, engineName) => {
+      if (!INCLUDE_ENGINE_NAMES.has(engineName)) return;
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "INCLUDE_OUTSIDE_RESOURCE",
+        source: SOURCE,
+        message:
+          `${manifest.kind}${name ? `/${name}` : ""}: \`!${engineName} ${source}\` at '${path}' is ` +
+          `never read — a ${manifest.kind} doc is not instantiated, and a file embed is resolved ` +
+          `when the resource holding it is created. Move it onto the resource that needs the ` +
+          `file, or read the file at runtime with Fs.File.`,
+        data: {
+          resource: { kind: manifest.kind, name: name ?? "" },
+          filePath,
+          path,
+        },
+      });
+    });
+  }
+  return out;
+}