@telorun/analyzer 0.72.0 → 0.74.0

package/src/artifact-selector.ts

@@ -3,7 +3,8 @@
  * 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`.
+ * A selector is `format` plus the optional platform axes, whose vocabulary is
+ * data (`analyzer/artifact-axes/axes.json`, generated into `PLATFORM_AXES`).
  * 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
@@ -25,11 +26,20 @@
  * published into OCI descriptors.
  */
 
-/** The role a layer plays in a module artifact. `controller` and `library` layers
- *  carry a selector; `assets` and `common` are singletons and carry none. */
-export type LayerRole = "controller" | "library" | "assets" | "common";
+import { AXIS_VALUE_FORMS, PLATFORM_AXES, type PlatformAxis } from "./artifact-axes.js";
 
-export const LAYER_ROLES: readonly LayerRole[] = ["controller", "library", "assets", "common"];
+/** The role a layer plays in a module artifact. `controller`, `library` and
+ *  `native` layers carry a selector; `assets` and `common` are singletons and
+ *  carry none. */
+export type LayerRole = "controller" | "library" | "native" | "assets" | "common";
+
+export const LAYER_ROLES: readonly LayerRole[] = [
+  "controller",
+  "library",
+  "native",
+  "assets",
+  "common",
+];
 
 export function isLayerRole(value: unknown): value is LayerRole {
   return typeof value === "string" && (LAYER_ROLES as readonly string[]).includes(value);
@@ -42,33 +52,28 @@ export function isLayerRole(value: unknown): value is LayerRole {
  *  A singleton would be wrong the moment a second runtime ships. */
 export const CODE_LAYER_ROLES: readonly LayerRole[] = ["controller", "library"];
 
+/** Every role keyed by a selector, one layer per selector: the code roles, plus
+ *  `native` — a platform-specific file the runtime does not import as code,
+ *  declared in the module doc's `native:` block. */
+const SELECTOR_LAYER_ROLES: readonly LayerRole[] = [...CODE_LAYER_ROLES, "native"];
+
 export function roleCarriesSelector(role: LayerRole): boolean {
-  return (CODE_LAYER_ROLES as readonly string[]).includes(role);
+  return (SELECTOR_LAYER_ROLES as readonly string[]).includes(role);
 }
 
-/** 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 { PLATFORM_AXES, type PlatformAxis };
 
-export type PlatformAxis = (typeof PLATFORM_AXES)[number];
-
-export interface ArtifactSelector {
+export interface ArtifactSelector extends Partial<Record<PlatformAxis, string>> {
   /** 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 {
+ *  target `telo install` 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 extends Partial<Record<PlatformAxis, string>> {
   format?: string;
-  os?: string;
-  arch?: string;
-  libc?: string;
 }
 
 export class ArtifactSelectorError extends Error {
@@ -84,7 +89,9 @@ export class ArtifactSelectorError extends Error {
  *  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 {
+/** Validate and normalize one selector value: the shared token grammar, plus the
+ *  axis's own value form where the vocabulary declares one. */
+export function normalizeAxisValue(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}.`,
@@ -97,6 +104,13 @@ function normalizeToken(axis: string, raw: unknown, describe: string): string {
         `Use lowercase letters, digits, '.', '-' or '_', starting with a letter or digit.`,
     );
   }
+  const valueForm = AXIS_VALUE_FORMS[axis as PlatformAxis];
+  if (valueForm && !valueForm.pattern.test(value)) {
+    throw new ArtifactSelectorError(
+      `${describe}: ${axis} value '${raw}' must have the form ${valueForm.form}, ` +
+        `e.g. ${valueForm.examples.map((e) => `'${e}'`).join(" or ")}.`,
+    );
+  }
   return value;
 }
 
@@ -111,35 +125,38 @@ export function selectorFromQualifiers(
   describe = "controller selector",
 ): ArtifactSelector {
   const selector: ArtifactSelector = {
-    format: normalizeToken("format", format, describe),
+    format: normalizeAxisValue("format", format, describe),
   };
   for (const axis of PLATFORM_AXES) {
     const raw = qualifiers?.[axis];
     if (raw === undefined || raw === "") continue;
-    selector[axis] = normalizeToken(axis, raw, describe);
+    selector[axis] = normalizeAxisValue(axis, raw, describe);
   }
   return selector;
 }
 
-/** Validate and normalize a selector read off a published layer index. */
+/**
+ * Validate and normalize a selector read off a published layer index.
+ *
+ * Returns undefined when the selector carries an axis this runtime does not
+ * know: the layer is for a newer runtime, and the caller skips it whole. The
+ * unknown axis is never dropped — two layers differing only in it would then
+ * claim one address. The known axes are still validated, since their grammar
+ * does not change with the axis set.
+ */
 export function normalizeSelector(
   value: unknown,
   describe = "layer selector",
-): ArtifactSelector {
+): ArtifactSelector | undefined {
   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(
+  const selector = selectorFromQualifiers(record.format, record, describe);
+  const carriesUnknownAxis = Object.keys(record).some(
     (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);
+  return carriesUnknownAxis ? undefined : selector;
 }
 
 /**
@@ -180,3 +197,61 @@ export function selectorMatches(selector: ArtifactSelector, target: PlatformTarg
   }
   return true;
 }
+
+/**
+ * The axes `selector` constrains and `target` leaves undetermined, when those
+ * alone keep the two from matching — what a warm skips for want of a value rather
+ * than because the selector is for another platform. `undefined` when the
+ * selector matches, or differs on a determined axis.
+ */
+export function undeterminedAxesBlockingMatch(
+  selector: ArtifactSelector,
+  target: PlatformTarget,
+): PlatformAxis[] | undefined {
+  if (target.format !== undefined && selector.format !== target.format) return undefined;
+  const axes: PlatformAxis[] = [];
+  for (const axis of PLATFORM_AXES) {
+    const constraint = selector[axis];
+    if (constraint === undefined) continue;
+    if (target[axis] === undefined) axes.push(axis);
+    else if (target[axis] !== constraint) return undefined;
+  }
+  return axes.length > 0 ? axes : undefined;
+}
+
+/** A selector that no host can match as its author meant it. */
+export interface SelectorContradiction {
+  /** Suffix of the diagnostic code; each surface prefixes its own. */
+  readonly rule: "NAPI_ABI_FORBIDDEN" | "LIBC_OFF_LINUX";
+  readonly axis: PlatformAxis;
+  readonly detail: string;
+}
+
+/**
+ * The combinations of axes the grammar accepts and no host can mean: an N-API
+ * addon stating a runtime ABI, and a libc on an os that has none. Shared by every
+ * surface that authors a selector — `native:` entries, controller candidates and
+ * `exports.code:` entries — so each reports the same rule under its own prefix.
+ */
+export function selectorContradictions(selector: ArtifactSelector): SelectorContradiction[] {
+  const out: SelectorContradiction[] = [];
+  if (selector.format === "napi" && selector.abi !== undefined) {
+    out.push({
+      rule: "NAPI_ABI_FORBIDDEN",
+      axis: "abi",
+      detail:
+        `an N-API addon is ABI-stable across runtime releases and states no abi — remove ` +
+        `abi ${selector.abi}, which would keep it from loading anywhere else.`,
+    });
+  }
+  if (selector.libc !== undefined && selector.os !== undefined && selector.os !== "linux") {
+    out.push({
+      rule: "LIBC_OFF_LINUX",
+      axis: "libc",
+      detail:
+        `libc is only determined on linux, so a selector for os '${selector.os}' that states ` +
+        `libc ${selector.libc} could never match a host. Remove libc.`,
+    });
+  }
+  return out;
+}

package/src/builtins.ts

@@ -1,3 +1,4 @@
+import { PLATFORM_AXES } from "./artifact-axes.js";
 import { manifestFragment, manifestFragmentRef, withSchemaFragments } from "./manifest-schemas.js";
 
 /** A slot holding author-written JSON Schema. Localized and hoisted by
@@ -23,6 +24,62 @@ const observedStateSlot = {
     "What a resource of this kind reports while running, published at `resources.<name>.status.<field>`.",
   $ref: manifestFragmentRef("JsonSchema7"),
 };
+
+/** The `self`-only CEL scope a dispatch slot's name template is written in. */
+const dispatchSelfContext = {
+  type: "object",
+  additionalProperties: false,
+  properties: { self: { "x-telo-context-from-root": "schema" } },
+};
+
+/**
+ * A `Telo.Definition` dispatch slot: which `resources:` entry receives the call.
+ *
+ * Three shapes, and the union is what keeps the slot CONSTRAINED for manifests
+ * no pass walks — `validate-template-body` resolves the target and its
+ * capability, but it is entry-scoped, so a dependency's definition would
+ * otherwise have nothing checking this slot at all. An array or a number fails
+ * every branch here, which is the floor AJV used to provide.
+ *
+ * `anyOf`, never `oneOf`: a `!ref` sentinel is an object, so it would match both
+ * the sentinel branch and any permissive object branch and then fail for
+ * matching twice. That is also how the sentinel used to pass — the legacy object
+ * branch required nothing, so it accepted one by accident; here it is a branch
+ * of its own that says so.
+ */
+function dispatchSlot(title: string, description: string): Record<string, unknown> {
+  return {
+    title,
+    description,
+    anyOf: [
+      // `!ref <entry>` — the spelling to write.
+      {
+        type: "object",
+        required: ["__tagged", "engine", "source"],
+        properties: {
+          __tagged: { const: true },
+          engine: { const: "ref" },
+          source: { type: "string", minLength: 1 },
+        },
+        additionalProperties: false,
+      },
+      // Legacy: a name template expanded against `self`. Read forever, because
+      // published artifacts carry it; `DEPRECATED_TEMPLATE_DISPATCH_FORM` is
+      // what moves an author off it.
+      { type: "string", "x-telo-context": dispatchSelfContext },
+      // Legacy: `{ kind?, name }`, where `name` is that same template.
+      {
+        type: "object",
+        required: ["name"],
+        properties: {
+          kind: { type: "string" },
+          name: { type: "string", "x-telo-context": dispatchSelfContext },
+        },
+        additionalProperties: true,
+      },
+    ],
+  };
+}
 import type { ResourceDefinition } from "@telorun/sdk";
 
 /** Descriptive provenance a module declares about itself, shared by
@@ -101,9 +158,70 @@ const LIBRARY_CANDIDATES_SCHEMA = {
       format: { type: "string" },
       path: { type: "string" },
       source: { type: "string" },
-      os: { type: "string" },
-      arch: { type: "string" },
-      libc: { type: "string" },
+      ...Object.fromEntries(PLATFORM_AXES.map((axis) => [axis, { type: "string" }])),
+    },
+    additionalProperties: false,
+  },
+};
+
+/** `native:` — the module's platform-specific files, one entry per logical name
+ *  per platform tuple. Closed, so a mistyped axis is a schema violation rather
+ *  than a platform-neutral entry. Grammar and rules live in
+ *  `analyzer/nodejs/src/native-entries.ts` and `validate-native-entries.ts`. */
+const NATIVE_ENTRIES_SCHEMA = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["name", "format", "os", "arch", "path"],
+    properties: {
+      name: { type: "string" },
+      format: { type: "string" },
+      path: { type: "string" },
+      ...Object.fromEntries(PLATFORM_AXES.map((axis) => [axis, { type: "string" }])),
+    },
+    additionalProperties: false,
+  },
+};
+
+/** `sources:` — where every staged file comes from, keyed by source name, each
+ *  entry keyed by the module-relative path it produces. Closed at every level.
+ *  An entry is a file (`upstream` + `member`, pinned with `sha256` +
+ *  `executable`) or a link (`target`); a mix of the two, and every other rule,
+ *  is reported by `analyzer/nodejs/src/validate-source-entries.ts`. `archive`
+ *  names the upstream's format. A source built in the repo names its build under
+ *  `build`, keyed by build system (`cargo: <crate dir>`), with the digest of its
+ *  build inputs (`inputs`). */
+const SOURCES_SCHEMA = {
+  type: "object",
+  additionalProperties: {
+    type: "object",
+    required: ["version", "url", "archive", "notices", "entries"],
+    properties: {
+      version: { type: "string" },
+      url: { type: "string" },
+      archive: { enum: ["tar.gz"] },
+      notices: { type: "array", minItems: 1, items: { type: "string" } },
+      build: {
+        type: "object",
+        required: ["cargo"],
+        properties: { cargo: { type: "string" }, inputs: { type: "string" } },
+        additionalProperties: false,
+      },
+      entries: {
+        type: "object",
+        additionalProperties: {
+          type: "object",
+          anyOf: [{ required: ["upstream", "member"] }, { required: ["target"] }],
+          properties: {
+            upstream: { type: "string" },
+            member: { type: "string" },
+            sha256: { type: "string" },
+            executable: { type: "boolean" },
+            target: { type: "string" },
+          },
+          additionalProperties: false,
+        },
+      },
     },
     additionalProperties: false,
   },
@@ -113,25 +231,18 @@ const LIBRARY_CANDIDATES_SCHEMA = {
  *  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`. */
+ *  that enforces them is `artifact-layer-index.ts`. `role` stays open and
+ *  `selector` unconstrained: an entry for a newer runtime is skipped, not
+ *  rejected, and its selector is not examined (spec §3.1). A known role's
+ *  selector is validated by the parser, which `telo check` runs. */
 const LAYER_INDEX_SCHEMA = {
   type: "array",
   items: {
     type: "object",
     required: ["role", "blob", "integrity"],
     properties: {
-      role: { type: "string", enum: ["controller", "library", "assets", "common"] },
-      selector: {
-        type: "object",
-        required: ["format"],
-        properties: {
-          format: { type: "string" },
-          os: { type: "string" },
-          arch: { type: "string" },
-          libc: { type: "string" },
-        },
-        additionalProperties: false,
-      },
+      role: { type: "string", minLength: 1 },
+      selector: {},
       blob: { type: "string", pattern: "^sha256:[0-9a-f]{64}$" },
       integrity: { type: "string", pattern: "^sha256-[A-Za-z0-9_-]{43}$" },
     },
@@ -480,99 +591,31 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             },
           },
         },
-        invoke: {
-          oneOf: [
-            {
-              type: "string",
-              "x-telo-context": {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                  self: { "x-telo-context-from-root": "schema" },
-                },
-              },
-            },
-            {
-              type: "object",
-              additionalProperties: true,
-              properties: {
-                kind: { type: "string" },
-                name: {
-                  type: "string",
-                  "x-telo-context": {
-                    type: "object",
-                    additionalProperties: false,
-                    properties: {
-                      self: { "x-telo-context-from-root": "schema" },
-                    },
-                  },
-                },
-              },
-            },
-          ],
-        },
-        provide: {
-          type: "object",
-          additionalProperties: true,
-          properties: {
-            kind: { type: "string" },
-            name: {
-              type: "string",
-              "x-telo-context": {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                  self: { "x-telo-context-from-root": "schema" },
-                },
-              },
-            },
-          },
-        },
-        run: {
-          type: "string",
-          "x-telo-context": {
-            type: "object",
-            additionalProperties: false,
-            properties: {
-              self: { "x-telo-context-from-root": "schema" },
-            },
-          },
-        },
-        // Mount dispatch: names the `resources:` entry (a Telo.Mount, e.g. an
-        // Http.Api) whose `register()` this definition delegates to. Same
-        // string / { kind, name } grammar as `invoke:`. The named child stays
-        // persistent so the produced mount's routes can `!ref` its siblings.
-        mount: {
-          oneOf: [
-            {
-              type: "string",
-              "x-telo-context": {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                  self: { "x-telo-context-from-root": "schema" },
-                },
-              },
-            },
-            {
-              type: "object",
-              additionalProperties: true,
-              properties: {
-                kind: { type: "string" },
-                name: {
-                  type: "string",
-                  "x-telo-context": {
-                    type: "object",
-                    additionalProperties: false,
-                    properties: {
-                      self: { "x-telo-context-from-root": "schema" },
-                    },
-                  },
-                },
-              },
-            },
-          ],
-        },
+        // A dispatch slot names the `resources:` entry that receives the call,
+        // as `!ref <entry>` — the one spelling every reference in Telo has. The
+        // string and `{ kind, name }` forms it used to admit (a CEL name
+        // template matched against CEL-named entries) were the removed
+        // reference object surviving in the one place nothing resolved it;
+        // `validate-template-body` is what resolves this slot, so the schema
+        // stays open here rather than reporting the same defect twice.
+        invoke: dispatchSlot(
+          "Invoke target",
+          "The `resources:` entry whose `invoke()` this kind dispatches to, as `!ref <entry>`.",
+        ),
+        provide: dispatchSlot(
+          "Provide target",
+          "The `resources:` entry whose `invoke()` produces this provider's value, as `!ref <entry>`.",
+        ),
+        run: dispatchSlot(
+          "Run target",
+          "The `resources:` entry whose `run()` this kind dispatches to, as `!ref <entry>`.",
+        ),
+        // The named child stays persistent so the produced mount's routes can
+        // `!ref` its siblings.
+        mount: dispatchSlot(
+          "Mount target",
+          "The `resources:` entry (a Telo.Mount, e.g. an Http.Api) whose `register()` this kind delegates to, as `!ref <entry>`.",
+        ),
         inputs: {
           type: "object",
           additionalProperties: true,
@@ -593,11 +636,11 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             additionalProperties: false,
             properties: {
               self: { "x-telo-context-from-root": "schema" },
+              // Typed from the dispatch target's declared output: the slot
+              // holds a `!ref` to a `resources:` entry, resolved to that
+              // entry's kind (or its own `outputType`, where it narrows one).
               result: {
-                "x-telo-context-from-ref-kind": [
-                  "provide/kind#outputType",
-                  "invoke/kind#outputType",
-                ],
+                "x-telo-context-from-ref-kind": ["provide#outputType", "invoke#outputType"],
               },
             },
           },
@@ -763,6 +806,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           items: { type: "string" },
         },
         assets: ASSETS_FILES_SCHEMA,
+        native: NATIVE_ENTRIES_SCHEMA,
+        sources: SOURCES_SCHEMA,
         layers: LAYER_INDEX_SCHEMA,
         filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // Inline imports — name-keyed map sugar for separate `Telo.Import`
@@ -936,6 +981,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           items: { type: "string" },
         },
         assets: ASSETS_FILES_SCHEMA,
+        native: NATIVE_ENTRIES_SCHEMA,
+        sources: SOURCES_SCHEMA,
         layers: LAYER_INDEX_SCHEMA,
         filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // Inline imports — same name-keyed map sugar as Telo.Application; the

package/src/call-graph.ts

@@ -53,6 +53,7 @@ import {
   possibleUses,
   readRefSlot,
   transfersControl,
+  type RefSlot,
   type RefUse,
   type RefUseCases,
 } from "./ref-slot.js";
@@ -399,6 +400,35 @@ function resolveUseAtSite(
   return { use: possibleUses(slot), unresolved: entry.useCases, unresolvedReason };
 }
 
+/**
+ * A slot's use at one concrete site of one resource, for a consumer that walks
+ * the kind's schema itself rather than reading the graph's edges.
+ *
+ * The same rule the graph applies to a resource-level edge — the same enclosing
+ * object, the same schema default — so a consumer and an edge cannot disagree
+ * about which case of a case map holds. `concretePath` is the site
+ * (`routes[0].handler`); `fieldPath` is the declaration it resolved from
+ * (`routes[].handler`), which is what the schema default is read against.
+ */
+export function resolveSlotUseAt(
+  slot: RefSlot,
+  resource: unknown,
+  rootSchema: Record<string, any> | undefined,
+  concretePath: string,
+  fieldPath: string,
+): Pick<CallGraphEdge, "use" | "unresolved" | "unresolvedReason"> {
+  const entry: RefFieldEntry = {
+    refs: slot.kinds,
+    uses: slot.uses,
+    isArray: false,
+    ...(slot.useCases ? { useCases: slot.useCases } : {}),
+  };
+  const schemaDefault = rootSchema
+    ? schemaDefaultOf(enclosingSchemaOf(rootSchema, fieldPath))
+    : NO_DEFAULT;
+  return resolveUseAtSite(entry, resource, concretePath, schemaDefault);
+}
+
 /** A resolved plain reference value (`{kind, name}`, optionally `alias`) — the
  *  shape `resolveRefSentinels` leaves at a ref site. NOT a step: a bare boot
  *  target written `!ref X` must not mint a step node. */

package/src/catch-scope.ts

@@ -86,7 +86,7 @@ export function buildEnclosers(
     const definition = definitionOf(manifest);
     if (!definition?.schema) continue;
     forEachDrivenSlot(definition.schema, manifest, (driven) => {
-      if (driven.kind !== "ref" || !driven.slot.throwsThrough) return;
+      if (driven.kind !== "ref" || !driven.slots.some(({ slot }) => slot.throwsThrough)) return;
       const target = resolveRefManifest(driven.data, ctx, moduleOf(manifest));
       if (!target || target === manifest) return;
       const list = enclosers.get(target);

package/src/cel-scope-query.ts

@@ -21,6 +21,7 @@ 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 { kindAtPath } from "./validate-cel-context.js";
 import { findManifest } from "./find-manifest.js";
 import { resolveLocalRef, walkStepArray } from "./schema-walk.js";
 import { readStepSlot } from "./step-slot.js";
@@ -269,14 +270,27 @@ export class CelScopeQuery {
     }
 
     // A kind's own declaration: the target is the `Telo.Definition` document,
-    // which is an ordinary manifest in the set.
+    // which is an ordinary manifest in the set. The slot holds a `!ref` to a
+    // `resources:` entry; the entry's own field wins where it narrows one, else
+    // the declaration is the entry's KIND. The first slot that resolves to an
+    // entry is the one the type resolver reads, so it is the one navigated.
     const fromRefKind = annotated["x-telo-context-from-ref-kind"];
-    const first = Array.isArray(fromRefKind) ? fromRefKind[0] : fromRefKind;
-    if (typeof first === "string") {
-      const hash = first.indexOf("#");
-      if (hash <= 0) return undefined;
-      const kindValue = navigateConcretePath(root, first.slice(0, hash).split("/").join("."));
-      if (typeof kindValue !== "string") return undefined;
+    const slots = Array.isArray(fromRefKind) ? fromRefKind : [fromRefKind];
+    for (const slotSpec of slots) {
+      if (typeof slotSpec !== "string") continue;
+      const hash = slotSpec.indexOf("#");
+      // `continue`, never `return`: a malformed spec is one entry of a list the
+      // type resolver walks to the end, and aborting here made the two answer
+      // differently for the same annotation.
+      if (hash <= 0) continue;
+      const field = slotSpec.slice(hash + 1);
+      const namedKind = kindAtPath(root, slotSpec.slice(0, hash));
+      if (!namedKind) continue;
+      if (namedKind.entry?.[field] !== undefined) {
+        const index = (root.resources as unknown[]).indexOf(namedKind.entry);
+        return { manifest: resource, path: `resources[${index}].${field}`, propertyMap: false };
+      }
+      const kindValue = namedKind.kind;
       // 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);
@@ -300,9 +314,14 @@ export class CelScopeQuery {
         (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 };
+      // Fall through to the next spec when this one names no kind, or names one
+      // that does not declare the field — the same order the TYPE resolver
+      // takes, so go-to-declaration lands where the type came from instead of on
+      // a field the target never had.
+      if (!target || target[field] === undefined) continue;
+      return { manifest: target, path: field, propertyMap: false };
     }
+    if (slots.some((s) => typeof s === "string")) return undefined;
 
     // `x-telo-context-element-from` / `-collection-from` type a binding from an
     // EXPRESSION, so there is no declaration to navigate to.

package/src/cel-scope.ts

@@ -651,6 +651,7 @@ export class CelScopeResolver {
       manifestRoot: rootForResolver,
       defs,
       aliases,
+      aliasesByModule: scopes?.aliasesByModule,
       allManifests: allManifests as Record<string, any>[],
     });
     return mergeKernelGlobalsIntoContext(