@telorun/analyzer 0.46.0 → 0.48.0

package/src/artifact-selector.ts

@@ -0,0 +1,171 @@
+/**
+ * The **selector** of `kernel/specs/module-artifact.md` — the tuple a bundled
+ * controller candidate is chosen by, and the key a controller layer of a module
+ * artifact is stored under.
+ *
+ * A selector is `format` plus the optional platform axes `os` / `arch` / `libc`.
+ * Matching is one rule, applied per axis: an axis the selector omits accepts
+ * anything, an axis it states must be equal. That is what lets a `js` controller
+ * be platform-neutral and a `napi` controller be pinned to one triple, with no
+ * special case for either.
+ *
+ * Browser-safe and dependency-free by construction. Three consumers must agree
+ * on this grammar or a published artifact stops loading: `telo publish`
+ * (partitioning files into layers), `telo install --platform` (deciding which
+ * layers to pre-fetch), and the kernel's bundle controller loader (matching a
+ * candidate against the host). Keeping it here — beside the redaction path
+ * parser, for the same reason — means one implementation rather than three that
+ * drift.
+ *
+ * PURL *syntax* is deliberately not parsed here. Callers hand in the format and
+ * an already-decoded qualifier map, so this module owns selector semantics while
+ * the caller owns its own package-URL library. The Node vocabulary is likewise
+ * not known here: `process.platform` / `process.arch` are mapped to the
+ * canonical OCI/GOOS names at the kernel boundary, since these values are
+ * published into OCI descriptors.
+ */
+
+/** The role a layer plays in a module artifact. `controller` layers carry a
+ *  selector; `assets` and `common` are singletons and carry none. */
+export type LayerRole = "controller" | "assets" | "common";
+
+export const LAYER_ROLES: readonly LayerRole[] = ["controller", "assets", "common"];
+
+export function isLayerRole(value: unknown): value is LayerRole {
+  return typeof value === "string" && (LAYER_ROLES as readonly string[]).includes(value);
+}
+
+/** The platform axes, in canonical order. Not a closed vocabulary of *values* —
+ *  new architectures appear without a Telo release — only of axis names. */
+export const PLATFORM_AXES = ["os", "arch", "libc"] as const;
+
+export type PlatformAxis = (typeof PLATFORM_AXES)[number];
+
+export interface ArtifactSelector {
+  /** Bundled controller format: the PURL name segment (`js`, `napi`, `wasm`, …). */
+  format: string;
+  os?: string;
+  arch?: string;
+  libc?: string;
+}
+
+/** What a selector is matched against: the host the kernel runs on, or the
+ *  target `telo install --platform` is warming a cache for. An axis left
+ *  undetermined (a host whose libc cannot be detected) matches no selector that
+ *  constrains it — refusing to load is the safe direction for a native binary. */
+export interface PlatformTarget {
+  format?: string;
+  os?: string;
+  arch?: string;
+  libc?: string;
+}
+
+export class ArtifactSelectorError extends Error {
+  readonly code = "INVALID_ARTIFACT_SELECTOR";
+
+  constructor(detail: string) {
+    super(detail);
+    this.name = "ArtifactSelectorError";
+  }
+}
+
+/** Canonical token shape for every selector value. Lowercase, so the same
+ *  platform written two ways is one layer rather than two. */
+const TOKEN = /^[a-z0-9][a-z0-9_.-]*$/;
+
+function normalizeToken(axis: string, raw: unknown, describe: string): string {
+  if (typeof raw !== "string") {
+    throw new ArtifactSelectorError(
+      `${describe}: ${axis} must be a string, got ${raw === null ? "null" : typeof raw}.`,
+    );
+  }
+  const value = raw.trim().toLowerCase();
+  if (!TOKEN.test(value)) {
+    throw new ArtifactSelectorError(
+      `${describe}: ${axis} value '${raw}' is not a canonical token. ` +
+        `Use lowercase letters, digits, '.', '-' or '_', starting with a letter or digit.`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Build a selector from a controller candidate's format and qualifier map.
+ * Qualifier keys other than the platform axes are ignored — `path` and the
+ * sibling list live in the same map and are not part of the selector.
+ */
+export function selectorFromQualifiers(
+  format: unknown,
+  qualifiers: Readonly<Record<string, unknown>> | undefined,
+  describe = "controller selector",
+): ArtifactSelector {
+  const selector: ArtifactSelector = {
+    format: normalizeToken("format", format, describe),
+  };
+  for (const axis of PLATFORM_AXES) {
+    const raw = qualifiers?.[axis];
+    if (raw === undefined || raw === "") continue;
+    selector[axis] = normalizeToken(axis, raw, describe);
+  }
+  return selector;
+}
+
+/** Validate and normalize a selector read off a published layer index. */
+export function normalizeSelector(
+  value: unknown,
+  describe = "layer selector",
+): ArtifactSelector {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ArtifactSelectorError(`${describe}: expected an object of selector axes.`);
+  }
+  const record = value as Record<string, unknown>;
+  const unknown = Object.keys(record).filter(
+    (k) => k !== "format" && !(PLATFORM_AXES as readonly string[]).includes(k),
+  );
+  if (unknown.length > 0) {
+    throw new ArtifactSelectorError(
+      `${describe}: unknown selector ${unknown.length === 1 ? "axis" : "axes"} ` +
+        `${unknown.map((k) => `'${k}'`).join(", ")}. Known axes: format, ${PLATFORM_AXES.join(", ")}.`,
+    );
+  }
+  return selectorFromQualifiers(record.format, record, describe);
+}
+
+/**
+ * The canonical stable key for a selector: sorted `axis=value` pairs joined by
+ * `;`. Used to group entry points into layers at publish time and to detect two
+ * layers claiming the same selector. Sorted and fully qualified so no two
+ * distinct selectors can collide and no one selector has two spellings.
+ */
+export function selectorKey(selector: ArtifactSelector): string {
+  const pairs: string[] = [`format=${selector.format}`];
+  for (const axis of PLATFORM_AXES) {
+    const value = selector[axis];
+    if (value !== undefined) pairs.push(`${axis}=${value}`);
+  }
+  return pairs.sort().join(";");
+}
+
+/** Human-facing rendering for diagnostics and the publish partition printout. */
+export function describeSelector(selector: ArtifactSelector): string {
+  const platform = PLATFORM_AXES.map((axis) => selector[axis]).filter(
+    (v): v is string => v !== undefined,
+  );
+  return platform.length === 0 ? selector.format : `${selector.format} (${platform.join("/")})`;
+}
+
+/**
+ * The matching rule: every axis the selector states must equal the target's;
+ * every axis it omits accepts anything. A target axis left undetermined matches
+ * only a selector that does not constrain it — a host whose libc is unknown must
+ * not be handed a `libc=gnu` binary on the assumption it will run.
+ */
+export function selectorMatches(selector: ArtifactSelector, target: PlatformTarget): boolean {
+  if (target.format !== undefined && selector.format !== target.format) return false;
+  for (const axis of PLATFORM_AXES) {
+    const constraint = selector[axis];
+    if (constraint === undefined) continue;
+    if (target[axis] !== constraint) return false;
+  }
+  return true;
+}

package/src/builtins.ts

@@ -23,6 +23,53 @@ const PROVENANCE_METADATA = {
   documentation: { type: "string" },
 };
 
+/** Author-declared subset of `files:` that ships in the artifact's lazily
+ *  materialized `assets` layer. Optional: an unclaimed file joins the `common`
+ *  layer, which is pulled alongside any controller layer, so omitting this costs
+ *  laziness rather than correctness. See kernel/specs/module-artifact.md. */
+const ASSETS_FILES_SCHEMA = {
+  type: "array",
+  items: { type: "string" },
+};
+
+/** The published layer index, written by `telo publish` (never hand-authored).
+ *  One entry per layer except the manifest layer, which cannot list its own hash
+ *  inside itself and is pinned by the importer's `#sha256-...` instead. Shape and
+ *  matching rules are normative in kernel/specs/module-artifact.md; the parser
+ *  that enforces them is `artifact-layer-index.ts`. */
+const LAYER_INDEX_SCHEMA = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["role", "blob", "integrity"],
+    properties: {
+      role: { type: "string", enum: ["controller", "assets", "common"] },
+      selector: {
+        type: "object",
+        required: ["format"],
+        properties: {
+          format: { type: "string" },
+          os: { type: "string" },
+          arch: { type: "string" },
+          libc: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+      blob: { type: "string", pattern: "^sha256:[0-9a-f]{64}$" },
+      integrity: { type: "string", pattern: "^sha256-[A-Za-z0-9_-]{43}$" },
+    },
+    additionalProperties: false,
+  },
+};
+
+/** The pre-layers payload digest, superseded by the per-layer `integrity` values
+ *  in `layers:`. Accepted and ignored, for one reason only: a module published in
+ *  the old single-blob shape must reach the *actionable* failure — the controller
+ *  loader's "republish the module" error — instead of dying earlier on
+ *  `must NOT have additional properties`, which tells an author nothing. Nothing
+ *  reads this field. */
+const LEGACY_FILES_INTEGRITY_SCHEMA = { type: "string" };
+
 /** The six named levels of `kernel/specs/logging.md` §5.1. The full 1–24 OTel
  *  range stays valid on the wire; only these are nameable in a manifest. */
 const LOG_LEVEL_ENUM = ["trace", "debug", "info", "warn", "error", "fatal"];
@@ -529,21 +576,18 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
-        // Files bundled alongside `telo.yaml` into the module's registry
-        // artifact (`module.tar.gz`) — static assets served by Http.Static,
-        // templates, etc. Ordered `.gitignore`-style patterns resolved against
-        // the manifest dir at publish time. Analyzer-only role: accept the
-        // field (the schema is additionalProperties:false); the analyzer never
-        // reads the assets. See kernel/nodejs/plans/bundle-controllers.md.
+        // Files bundled alongside `telo.yaml` into the module's artifact —
+        // controller bundles, static assets served by Http.Static, templates,
+        // etc. Ordered `.gitignore`-style patterns resolved against the manifest
+        // dir at publish time. Analyzer-only role: accept the field (the schema
+        // is additionalProperties:false); the analyzer never reads the payload.
         files: {
           type: "array",
           items: { type: "string" },
         },
-        // Integrity hash of the decompressed payload tar (`module.tar.gz`,
-        // telo.yaml excluded), written by `telo publish`. Pinned transitively
-        // by the importer's `#sha256-...` hash over this telo.yaml; verified at
-        // extract time. See plans/federated-registries.md.
-        filesIntegrity: { type: "string" },
+        assets: ASSETS_FILES_SCHEMA,
+        layers: LAYER_INDEX_SCHEMA,
+        filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // Inline imports — name-keyed map sugar for separate `Telo.Import`
         // documents. The key is the PascalCase alias (the import's
         // `metadata.name`). Each value is either a bare source string
@@ -680,18 +724,16 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
-        // Files bundled into the module's registry artifact — same semantics as
-        // the Telo.Application `files` field above (a library may ship bundled
-        // templates, migrations, seed data).
+        // Files bundled into the module's artifact — same semantics as the
+        // Telo.Application `files` field above (a library may ship bundled
+        // controllers, templates, migrations, seed data).
         files: {
           type: "array",
           items: { type: "string" },
         },
-        // Integrity hash of the decompressed payload tar (`module.tar.gz`,
-        // telo.yaml excluded), written by `telo publish`. Pinned transitively
-        // by the importer's `#sha256-...` hash over this telo.yaml; verified at
-        // extract time. See plans/federated-registries.md.
-        filesIntegrity: { type: "string" },
+        assets: ASSETS_FILES_SCHEMA,
+        layers: LAYER_INDEX_SCHEMA,
+        filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // Inline imports — same name-keyed map sugar as Telo.Application; the
         // loader desugars each entry into a synthetic Telo.Import. See the
         // Application schema above and analyzer/nodejs/src/inline-imports.ts.

package/src/index.ts

@@ -120,6 +120,31 @@ export {
   urlManifestCacheCoords,
 } from "./sources/manifest-cache.js";
 export type { ManifestCacheCoords } from "./sources/manifest-cache.js";
+export {
+  LAYER_ROLES,
+  PLATFORM_AXES,
+  ArtifactSelectorError,
+  describeSelector,
+  isLayerRole,
+  normalizeSelector,
+  selectorFromQualifiers,
+  selectorKey,
+  selectorMatches,
+} from "./artifact-selector.js";
+export type {
+  ArtifactSelector,
+  LayerRole,
+  PlatformAxis,
+  PlatformTarget,
+} from "./artifact-selector.js";
+export {
+  LayerIndexError,
+  matchControllerLayers,
+  parseLayerIndex,
+  singletonLayer,
+} from "./artifact-layer-index.js";
+export type { ArtifactLayer } from "./artifact-layer-index.js";
+export { validateModuleArtifact } from "./validate-module-artifact.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";

package/src/resolve-ref-sentinels.ts

@@ -1,8 +1,22 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
+import {
+  isScopeEntry,
+  resolveFieldEntries,
+  type ReferenceFieldMap,
+} from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
+/** The slice of the definition registry this pass needs: a kind's field map, from
+ *  which the `x-telo-scope` slots are read. */
+export interface ScopeFieldMapSource {
+  getFieldMapForKind(
+    kind: string,
+    aliases?: { resolveKind(k: string): string | undefined },
+  ): ReferenceFieldMap | undefined;
+}
+
 /** Resolved ref shape written in place of a `!ref` sentinel. `alias` is set only for
  *  cross-module references (resolved into an imported library's exported instance). */
 type ResolvedRef = { kind: string; name: string; alias?: string };
@@ -52,6 +66,10 @@ export function resolveRefSentinels(
   // pass — which loads the entry module only — can still resolve `!ref Alias.name` against
   // imported libraries' exported instances.
   crossModuleTargets: ResourceManifest[] = [],
+  /** Supplies each kind's `x-telo-scope` slots. Without it a scoped name cannot be
+   *  told from a module-level one, and a shadowed `!ref` resolves to the resource
+   *  it shadows — so both call sites pass it. */
+  defs?: ScopeFieldMapSource,
 ): void {
   const moduleOf = (r: ResourceManifest): string | undefined =>
     (r.metadata as { module?: string } | undefined)?.module;
@@ -109,21 +127,67 @@ export function resolveRefSentinels(
     return undefined;
   };
 
+  /** Names a resource declares in its own execution scopes, read from the kind's
+   *  `x-telo-scope` slots — the analyzer's single definition of "scope", shared
+   *  with `manifest-visitor`. Inferring it structurally instead (any array of
+   *  named inline manifests) would give scope-local shadowing to the first kind
+   *  that happens to carry such an array without asking for it, and this pass is
+   *  shared with the kernel, so the guess would be baked into the runtime tree
+   *  rather than merely reported. */
+  const declaredInScopes = (
+    resource: ResourceManifest,
+  ): Map<string, ResourceManifest> | undefined => {
+    const fieldMap = defs?.getFieldMapForKind(resource.kind, aliases);
+    if (!fieldMap) return undefined;
+    let declared: Map<string, ResourceManifest> | undefined;
+    for (const [fieldPath, entry] of fieldMap) {
+      if (!isScopeEntry(entry)) continue;
+      for (const { value } of resolveFieldEntries(resource, fieldPath)) {
+        for (const element of Array.isArray(value) ? value : [value]) {
+          if (!element || typeof element !== "object" || Array.isArray(element)) continue;
+          const manifest = element as ResourceManifest;
+          const name = (manifest.metadata as { name?: string } | undefined)?.name;
+          if (typeof manifest.kind === "string" && typeof name === "string") {
+            (declared ??= new Map()).set(name, manifest);
+          }
+        }
+      }
+    }
+    return declared;
+  };
+
   // Resolve every `!ref` sentinel in the tree; leave opaque tagged / precompiled
   // nodes (e.g. `!cel`) untouched and don't descend into them.
-  const walk = (value: unknown): unknown => {
+  //
+  // `scoped` carries the names the enclosing resource declares in its `x-telo-scope`
+  // slots, and they SHADOW the module-level ones — the order the runtime resolves
+  // in. Baking the module-level kind into a shadowed reference would label traces
+  // and `getRefIdentity` with a resource that never runs.
+  const walk = (value: unknown, scoped?: Map<string, ResourceManifest>): unknown => {
     if (isRefSentinel(value)) {
-      return resolveTarget(value.source) ?? value;
+      const source = value.source;
+      const bare = source.indexOf(".") === -1;
+      const shadow = bare ? scoped?.get(source) : undefined;
+      if (shadow) return { kind: shadow.kind as string, name: source };
+      return resolveTarget(source) ?? value;
     }
     if (value === null || typeof value !== "object") return value;
     if (isTaggedSentinel(value)) return value;
     if ((value as { __compiled?: unknown }).__compiled) return value;
     if (Array.isArray(value)) {
-      for (let i = 0; i < value.length; i++) value[i] = walk(value[i]);
+      for (let i = 0; i < value.length; i++) value[i] = walk(value[i], scoped);
       return value;
     }
     const obj = value as Record<string, unknown>;
-    for (const key of Object.keys(obj)) obj[key] = walk(obj[key]);
+    // A nested inline resource may declare scopes of its own (a `Run.Sequence`
+    // inside another sequence's `with:`). Collected before descending, so the
+    // declarations are visible to every region of the resource that declares
+    // them — a sequence's `with:` names resolve in its `targets:` and `steps:`
+    // alike, not only inside `with:` itself.
+    const declared =
+      typeof obj.kind === "string" ? declaredInScopes(obj as ResourceManifest) : undefined;
+    const inner = declared ? new Map([...(scoped ?? new Map()), ...declared]) : scoped;
+    for (const key of Object.keys(obj)) obj[key] = walk(obj[key], inner);
     return value;
   };
 

package/src/validate-cel-context.ts

@@ -323,18 +323,37 @@ export function resolveContextAnnotations(
       typeof ref.name === "string" &&
       subpath
     ) {
+      const segments = subpath.split("/");
       const refManifest = allManifests.find(
         (m) => m.kind === ref.kind && (m.metadata as any)?.name === ref.name,
       ) as Record<string, any> | undefined;
       if (refManifest) {
         const resolved = resolveTypeFieldToSchema(
-          navigatePath(refManifest, subpath.split("/")) as unknown,
+          navigatePath(refManifest, segments) as unknown,
           allManifests,
         );
         if (resolved && typeof resolved === "object") {
           return resolved;
         }
       }
+      // The instance declares nothing, so fall back to its KIND's declaration —
+      // the same layering `buildStepContextSchema` applies to `steps.<name>.result`,
+      // so a kind with one fixed output shape (declared once on its Telo.Definition)
+      // types the context, while a kind that exposes the field for per-instance
+      // narrowing keeps winning above.
+      if (defs) {
+        const canonical = aliases?.resolveKind(ref.kind) ?? ref.kind;
+        const def = defs.resolve(canonical) as Record<string, unknown> | undefined;
+        if (def) {
+          const resolved = resolveTypeFieldToSchema(
+            navigatePath(def, segments) as unknown,
+            allManifests,
+          );
+          if (resolved && typeof resolved === "object") {
+            return resolved;
+          }
+        }
+      }
     }
     // Fallback: open schema (no false errors when outputType is not declared)
     return { ...schema, additionalProperties: true };

package/src/validate-module-artifact.ts

@@ -0,0 +1,141 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+import { parseLayerIndex, LayerIndexError } from "./artifact-layer-index.js";
+import {
+  ArtifactSelectorError,
+  PLATFORM_AXES,
+  selectorFromQualifiers,
+} from "./artifact-selector.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Static validation of the module-artifact surface — `kernel/specs/module-artifact.md`.
+ *
+ * Everything here is decidable from the manifest text alone, and every case would
+ * otherwise surface on a *consumer's* machine at controller-resolve time (or, worse,
+ * not at all). That is the whole argument: an author who mistypes a platform axis
+ * gets a platform-neutral candidate, publish emits one layer, and every host
+ * happily loads a binary built for one architecture — silently, forever.
+ *
+ * Two checks. Note that several candidates *sharing* one selector is not among
+ * them: a controller layer holds the entry points of every candidate with that
+ * selector (spec §1), which is what every module with two `js` controllers relies
+ * on.
+ *
+ * 1. **Controller selector qualifiers.** `os` / `arch` / `libc` / `siblings` are
+ *    authored surface. An unknown qualifier is reported rather than ignored, since
+ *    ignoring is what makes a typo invisible; an invalid value is reported here
+ *    instead of throwing from the loader later.
+ * 2. **The published layer index.** The owner doc's JSON Schema covers shape; the
+ *    semantic rules — controller-requires-selector, singletons carry none, no
+ *    duplicate selector, the token grammar (`os: Linux` passes the schema and
+ *    throws at runtime) — live in the parser, so run it.
+ */
+export function validateModuleArtifact(manifests: ResourceManifest[]): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  for (const manifest of manifests) {
+    validateLayerIndex(manifest, out);
+    validateControllerSelectors(manifest, out);
+  }
+  return out;
+}
+
+const KNOWN_QUALIFIERS = new Set<string>(["path", "siblings", ...PLATFORM_AXES]);
+
+/** `pkg:telo/local/<format>?…` — the bundled-controller delivery mode. Parsed by
+ *  hand rather than with a PURL library: the analyzer must stay browser-safe and
+ *  dependency-light, and the only thing needed here is the qualifier map. */
+function parseBundledPurl(
+  purl: string,
+): { format: string; qualifiers: Record<string, string> } | null {
+  if (!purl.startsWith("pkg:telo/local/")) return null;
+  const withoutFragment = purl.split("#")[0];
+  const [head, query = ""] = withoutFragment.split("?");
+  const format = head.slice("pkg:telo/local/".length);
+  if (format === "") return null;
+  const qualifiers: Record<string, string> = {};
+  for (const pair of query.split("&")) {
+    if (pair === "") continue;
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    qualifiers[decodeURIComponent(pair.slice(0, eq))] = decodeURIComponent(pair.slice(eq + 1));
+  }
+  return { format, qualifiers };
+}
+
+function validateControllerSelectors(
+  manifest: ResourceManifest,
+  out: AnalysisDiagnostic[],
+): void {
+  const controllers = (manifest as { controllers?: unknown }).controllers;
+  if (!Array.isArray(controllers)) return;
+  const metadata = manifest.metadata as
+    | { name?: string; module?: string; source?: string }
+    | undefined;
+  const name = metadata?.name;
+  const filePath = metadata?.source;
+  const resource = { kind: manifest.kind, name };
+
+  controllers.forEach((candidate, index) => {
+    if (typeof candidate !== "string") return;
+    const parsed = parseBundledPurl(candidate);
+    if (!parsed) return;
+    const at = `controllers[${index}]`;
+
+    const unknown = Object.keys(parsed.qualifiers).filter((k) => !KNOWN_QUALIFIERS.has(k));
+    for (const key of unknown) {
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "CONTROLLER_UNKNOWN_QUALIFIER",
+        source: SOURCE,
+        message:
+          `${manifest.kind}/${name ?? "(unnamed)"}: bundled controller qualifier '${key}' is not ` +
+          `recognized. Known qualifiers: ${[...KNOWN_QUALIFIERS].sort().join(", ")}. An ` +
+          `unrecognized platform axis is ignored, which would make this candidate ` +
+          `platform-neutral and offer a single-platform binary to every host.`,
+        data: { resource, filePath, path: `${at}?${key}` },
+      });
+    }
+
+    // Validate the selector; the value is not otherwise needed here, since
+    // candidates sharing a selector legitimately share a layer.
+    try {
+      selectorFromQualifiers(parsed.format, parsed.qualifiers, candidate);
+    } catch (err) {
+      if (!(err instanceof ArtifactSelectorError)) throw err;
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "CONTROLLER_INVALID_SELECTOR",
+        source: SOURCE,
+        message: `${manifest.kind}/${name ?? "(unnamed)"}: ${err.message}`,
+        data: { resource, filePath, path: at },
+      });
+    }
+  });
+}
+
+function validateLayerIndex(manifest: ResourceManifest, out: AnalysisDiagnostic[]): void {
+  if (manifest.kind !== "Telo.Application" && manifest.kind !== "Telo.Library") return;
+  const layers = (manifest as { layers?: unknown }).layers;
+  if (layers === undefined) return;
+  const metadata = manifest.metadata as { name?: string; source?: string } | undefined;
+  const name = metadata?.name;
+  try {
+    parseLayerIndex(layers);
+  } catch (err) {
+    if (!(err instanceof LayerIndexError) && !(err instanceof ArtifactSelectorError)) throw err;
+    out.push({
+      severity: DiagnosticSeverity.Error,
+      code: "INVALID_LAYER_INDEX",
+      source: SOURCE,
+      message: `${manifest.kind}/${name ?? "(unnamed)"}: ${err.message}`,
+      data: {
+        resource: { kind: manifest.kind, name },
+        filePath: metadata?.source,
+        path: "layers",
+      },
+    });
+  }
+}

package/src/validate-references.ts

@@ -267,9 +267,15 @@ export function validateReferences(
 
           // Local reference (bare name or explicit `Self.`-qualified).
           const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
+          // Scope-local FIRST, enclosing module as the fallback — the order the
+          // runtime uses at every name-resolution site (`ScopeContext.getInstance`,
+          // `ResourceContext.resolveRef`, and the CEL `resources` layering). Module-first
+          // here would validate a shadowed name against the resource the kernel will
+          // never bind: a false pass when the outer kind fits and the scoped one does
+          // not, a false REFERENCE_KIND_MISMATCH when it is the other way round.
           const target =
-            byName.get(localName) ??
-            visibleScopeManifests.find((m) => m.metadata?.name === localName);
+            visibleScopeManifests.find((m) => m.metadata?.name === localName) ??
+            byName.get(localName);
           if (!target) {
             diagnostics.push({
               severity: DiagnosticSeverity.Error,