@telorun/analyzer 0.60.0 → 0.62.0

package/src/analyzer.ts

@@ -8,7 +8,7 @@ import {
   plainChainOf,
   type CelSurface,
 } from "@telorun/templating";
-import type { DiagnosticFix } from "./types.js";
+import type { DiagnosticData, DiagnosticFix } from "./types.js";
 import {
   AliasResolver,
   moduleScopedDefResolver,
@@ -89,17 +89,19 @@ import {
   BINDINGS_ANNOTATION,
   bindingContextProperties,
   bindingPathChain,
-  CEL_RESERVED_WORDS,
   findBindingSites,
   resolveBindingOrder,
   schemaAtChain,
   type BindingSites,
 } from "./cel-bindings.js";
+import { CEL_RESERVED_WORDS, checkName } from "./identifier-name.js";
+import { validateIdentifierNames } from "./validate-identifier-names.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateLogging } from "./validate-logging.js";
 import { validateModuleArtifact } from "./validate-module-artifact.js";
 import { validateIncludePlacement } from "./validate-include-placement.js";
 import { validateModuleMetadata } from "./validate-module-metadata.js";
+import { validateRequires } from "./validate-requires.js";
 import { validateBaseMapping } from "./validate-base-mapping.js";
 import { validateInvocationContract } from "./validate-invocation-contract.js";
 import { collectStepInputIssues } from "./validate-step-inputs.js";
@@ -1029,6 +1031,86 @@ export interface StaticAnalyzerOptions {
   celHandlers?: CelHandlers;
 }
 
+/**
+ * Files belonging to a module this runtime declared itself unable to read.
+ *
+ * Attribution is by FILE rather than by resource identity, the same choice
+ * `remapMigratedPaths` makes and for the same reason: a diagnostic carries at
+ * most two routing facts and routinely only one, so indexing by resource would
+ * leave every diagnostic without `data.resource` unreachable.
+ *
+ * **A module NAME is not a graph-unique key.** Names are module-scoped, so two
+ * libraries may both be called `Store` — CLAUDE.md names this exact hazard for
+ * migration provenance ("two libraries declaring a Store would share one
+ * bucket"), where the answer is to narrow or not remap at all. Same answer here:
+ * the gated doc's own `metadata.source` is always suppressed, and a name is used
+ * to reach its `include:` partials only when that name identifies exactly ONE
+ * module doc in the set. Where it does not, the partials keep their diagnostics
+ * rather than risk silencing an unrelated library's — a stray extra diagnostic is
+ * a far cheaper failure than a hidden one.
+ *
+ * A module doc with no `source` contributes nothing — suppressing on a guess
+ * would hide diagnostics belonging to files nobody named.
+ */
+function filesOfUnreadableModules(
+  manifests: ResourceManifest[],
+  requiresDiagnostics: AnalysisDiagnostic[],
+): ReadonlySet<string> {
+  const files = new Set<string>();
+  const gatedNames = new Set<string>();
+
+  for (const d of requiresDiagnostics) {
+    if (d.code !== "MODULE_REQUIRES_NEWER_RUNTIME") continue;
+    const data = d.data as DiagnosticData | undefined;
+    // The gated document itself, addressed by the file it was declared in.
+    if (typeof data?.filePath === "string" && data.filePath) files.add(data.filePath);
+    const name = data?.resource?.name;
+    if (typeof name === "string") gatedNames.add(name);
+  }
+  if (files.size === 0 && gatedNames.size === 0) return files;
+
+  // How many module docs answer to each gated name — the ambiguity test.
+  const docsPerName = new Map<string, number>();
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Application" && m.kind !== "Telo.Library") continue;
+    const name = (m.metadata as { name?: string } | undefined)?.name;
+    if (typeof name === "string" && gatedNames.has(name)) {
+      docsPerName.set(name, (docsPerName.get(name) ?? 0) + 1);
+    }
+  }
+
+  for (const m of manifests) {
+    const metadata = (m.metadata ?? {}) as Record<string, unknown>;
+    const owner = metadata.module;
+    if (typeof owner !== "string" || !gatedNames.has(owner)) continue;
+    if (docsPerName.get(owner) !== 1) continue; // ambiguous — do not guess
+    if (typeof metadata.source === "string" && metadata.source) files.add(metadata.source);
+  }
+  return files;
+}
+
+/**
+ * Drop every diagnostic anchored in a file whose module this runtime cannot
+ * read, except the gate diagnostic itself.
+ *
+ * A filter rather than a guard on each validator: threading "skip this module"
+ * through thirty validators would make each one responsible for a rule none of
+ * them owns, and a validator added later would silently opt out of it. A
+ * diagnostic with no `filePath` is KEPT — suppression must never be the default
+ * for something it cannot attribute.
+ */
+function suppressUnreadableModuleDiagnostics(
+  diagnostics: AnalysisDiagnostic[],
+  unreadableFiles: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  if (unreadableFiles.size === 0) return diagnostics;
+  return diagnostics.filter((d) => {
+    if (d.code === "MODULE_REQUIRES_NEWER_RUNTIME") return true;
+    const filePath = (d.data as DiagnosticData | undefined)?.filePath;
+    return typeof filePath !== "string" || !unreadableFiles.has(filePath);
+  });
+}
+
 export class StaticAnalyzer {
   private readonly celEnv: Environment;
 
@@ -1527,6 +1609,25 @@ export class StaticAnalyzer {
         });
       }
     }
+    // Declared runtime requirements, FIRST among the validators and suppressing
+    // the rest for any module this runtime cannot read. A module that adopted
+    // newer syntax also produces the vocabulary errors that syntax causes here —
+    // an unknown `use` token, an object where a zone annotation expects a
+    // pointer, an `additionalProperties` violation against a kernel-owned
+    // schema — every one of which is true and blames the module's author for a
+    // version skew. Reporting them beside the gate would bury the one message
+    // that names the actual cause and the actual fix.
+    const requiresDiagnostics = validateRequires(allManifests as unknown as ResourceManifest[], {
+      teloVersion: options?.teloVersion,
+      hostVersions: options?.hostVersions,
+      entryModules: rootModules,
+    });
+    const unreadableFiles = filesOfUnreadableModules(
+      allManifests as unknown as ResourceManifest[],
+      requiresDiagnostics,
+    );
+    diagnostics.push(...requiresDiagnostics);
+
     if (!options?.skipValidation) {
       diagnostics.push(
         ...validateSchemaTypeRefs(allManifests, defs, aliases, aliasesByModule, rootModules),
@@ -1543,6 +1644,19 @@ export class StaticAnalyzer {
       // these fields, which is precisely why they need a check: a mistyped one
       // has no runtime failure mode that would ever surface it.
       diagnostics.push(...validateModuleMetadata(allManifests, defs, aliases));
+      // Every author-written name. Telo has no lexer, so a name's shape is
+      // unchecked where it is declared and its consequences land at whichever
+      // CEL site reads it — for a hyphen, sometimes as silent arithmetic. Takes
+      // the call graph for step names rather than re-walking the step arrays.
+      diagnostics.push(
+        ...validateIdentifierNames(
+          allManifests as unknown as ResourceManifest[],
+          defs,
+          aliases,
+          rootModules,
+          getCallGraph(),
+        ),
+      );
       // A file embed resolves at resource creation, so one written on a doc that
       // is never instantiated is read by nothing and would ship silently.
       diagnostics.push(...validateIncludePlacement(allManifests));
@@ -1556,7 +1670,7 @@ export class StaticAnalyzer {
     // normalisation have already run above; that's all downstream
     // consumers (prepare, init loop) require.
     if (options?.skipValidation) {
-      return diagnostics;
+      return suppressUnreadableModuleDiagnostics(diagnostics, unreadableFiles);
     }
 
     // Build a name→manifest map for looking up referenced resources
@@ -2109,14 +2223,33 @@ export class StaticAnalyzer {
 
               for (const name of Object.keys(declared)) {
                 const shadows = inScope.has(name);
-                if (!shadows && !keywords.has(name)) continue;
+                if (shadows || keywords.has(name)) {
+                  diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "BINDING_NAME_RESERVED",
+                    source: SOURCE,
+                    message: shadows
+                      ? `${m.kind}/${bindingsName}: binding '${name}' shadows a variable already in scope here (${[...inScope].sort().join(", ")}). Rename the binding — a scope variable always wins, so this one would never be read.`
+                      : `${m.kind}/${bindingsName}: binding '${name}' is a CEL keyword, so no expression can read it as a reference. Rename the binding.`,
+                    data: {
+                      resource: resourceRef,
+                      filePath: bindingsFile,
+                      path: `${celBindingSites.field}.${name}`,
+                    },
+                  });
+                  continue;
+                }
+                // A binding is read by bare name, so it lives in the same
+                // identifier space as a resource or step name and breaks the
+                // same way. The keyword tier is unreachable here — the check
+                // above owns it, and can also say what is being shadowed.
+                const violation = checkName(name, "value", "binding name");
+                if (!violation) continue;
                 diagnostics.push({
-                  severity: DiagnosticSeverity.Error,
-                  code: "BINDING_NAME_RESERVED",
+                  severity: violation.severity,
+                  code: violation.code,
                   source: SOURCE,
-                  message: shadows
-                    ? `${m.kind}/${bindingsName}: binding '${name}' shadows a variable already in scope here (${[...inScope].sort().join(", ")}). Rename the binding — a scope variable always wins, so this one would never be read.`
-                    : `${m.kind}/${bindingsName}: binding '${name}' is a CEL keyword, so no expression can read it as a reference. Rename the binding.`,
+                  message: `${m.kind}/${bindingsName}: ${violation.message}`,
                   data: {
                     resource: resourceRef,
                     filePath: bindingsFile,
@@ -2514,7 +2647,10 @@ export class StaticAnalyzer {
 
     // Reroute diagnostics on synthetic (inline-extracted) resources back to
     // the chain root so position-index lookups land on the parent doc.
-    return rewriteSyntheticOrigins(diagnostics, allManifests);
+    return rewriteSyntheticOrigins(
+      suppressUnreadableModuleDiagnostics(diagnostics, unreadableFiles),
+      allManifests,
+    );
   }
 
   analyzeErrors(

package/src/artifact-layer-index.ts

@@ -29,8 +29,10 @@
  */
 
 import {
+  LAYER_ROLES,
   isLayerRole,
   normalizeSelector,
+  roleCarriesSelector,
   selectorKey,
   selectorMatches,
   type ArtifactSelector,
@@ -46,7 +48,7 @@ const CONTENT_DIGEST = /^sha256-[A-Za-z0-9_-]{43}$/;
 
 export interface ArtifactLayer {
   role: LayerRole;
-  /** Present on `controller` layers only. */
+  /** Present on the code-bearing roles (`controller`, `library`) only. */
   selector?: ArtifactSelector;
   /** OCI blob digest — addresses the layer and verifies the transfer. */
   blob: string;
@@ -97,25 +99,35 @@ export function parseLayerIndex(value: unknown, describe = "layers"): ArtifactLa
       throw new LayerIndexError(`${where}: expected an object.`);
     }
     const entry = raw as Record<string, unknown>;
-    if (!isLayerRole(entry.role)) {
+    if (typeof entry.role !== "string" || entry.role === "") {
       throw new LayerIndexError(
-        `${where}: role must be one of 'controller', 'assets', 'common'; got ` +
-          `${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`,
+        `${where}: role is required and must be one of ${LAYER_ROLES.map((r) => `'${r}'`).join(", ")}; ` +
+          `got ${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`,
       );
     }
+    // A role this runtime does not know is SKIPPED, never rejected. Roles are
+    // added over time, and a runtime that cannot name one cannot need it — while
+    // throwing would make the whole manifest unreadable, so a module gaining a
+    // layer for a newer runtime would stop loading on an older one entirely
+    // rather than merely lacking that layer. The error stays for a structurally
+    // invalid entry, which is a malformed index rather than a newer one.
+    if (!isLayerRole(entry.role)) return;
     const role = entry.role;
 
     let selector: ArtifactSelector | undefined;
-    if (role === "controller") {
+    if (roleCarriesSelector(role)) {
       if (entry.selector === undefined) {
-        throw new LayerIndexError(`${where}: a controller layer must declare a selector.`);
+        throw new LayerIndexError(`${where}: a ${role} layer must declare a selector.`);
       }
       selector = normalizeSelector(entry.selector, where);
-      const key = selectorKey(selector);
+      // Scoped by role: a module's `js` controller layer and its `js` library
+      // layer are different layers with the same selector, and only a collision
+      // *within* one role means two layers claim one address.
+      const key = `${role}\0${selectorKey(selector)}`;
       if (seenSelectors.has(key)) {
         throw new LayerIndexError(
-          `${where}: a second controller layer claims the selector ${key}. ` +
-            `Each selector addresses exactly one layer.`,
+          `${where}: a second ${role} layer claims the selector ${selectorKey(selector)}. ` +
+            `Each selector addresses exactly one layer of a role.`,
         );
       }
       seenSelectors.add(key);
@@ -145,18 +157,39 @@ export function parseLayerIndex(value: unknown, describe = "layers"): ArtifactLa
 /** The singleton layer for a role, or undefined when the artifact has none. */
 export function singletonLayer(
   layers: readonly ArtifactLayer[],
-  role: Exclude<LayerRole, "controller">,
+  role: Exclude<LayerRole, "controller" | "library">,
 ): ArtifactLayer | undefined {
   return layers.find((l) => l.role === role);
 }
 
-/** Every controller layer matching `target`, in declaration order. Used by
- *  `telo install` to warm a cache for one platform. */
-export function matchControllerLayers(
+/** The layer of one code role carrying exactly `selector`, or undefined.
+ *
+ *  By exact key rather than by re-matching a host: the candidate being resolved
+ *  already *is* one selector, and it is by construction the key of the layer
+ *  that carries it. */
+export function codeLayerFor(
+  layers: readonly ArtifactLayer[],
+  role: Extract<LayerRole, "controller" | "library">,
+  selector: ArtifactSelector,
+): ArtifactLayer | undefined {
+  const key = selectorKey(selector);
+  return layers.find(
+    (l) => l.role === role && l.selector !== undefined && selectorKey(l.selector) === key,
+  );
+}
+
+/** Every code layer — controller and library alike — matching `target`, in
+ *  declaration order. Used by `telo install` to warm a cache for one platform:
+ *  a library layer is as much a prerequisite of an offline run as the controller
+ *  layer that imports it. */
+export function matchCodeLayers(
   layers: readonly ArtifactLayer[],
   target: PlatformTarget,
 ): ArtifactLayer[] {
   return layers.filter(
-    (l) => l.role === "controller" && l.selector !== undefined && selectorMatches(l.selector, target),
+    (l) =>
+      (l.role === "controller" || l.role === "library") &&
+      l.selector !== undefined &&
+      selectorMatches(l.selector, target),
   );
 }

package/src/artifact-selector.ts

@@ -25,16 +25,27 @@
  * 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";
+/** 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";
 
-export const LAYER_ROLES: readonly LayerRole[] = ["controller", "assets", "common"];
+export const LAYER_ROLES: readonly LayerRole[] = ["controller", "library", "assets", "common"];
 
 export function isLayerRole(value: unknown): value is LayerRole {
   return typeof value === "string" && (LAYER_ROLES as readonly string[]).includes(value);
 }
 
+/** The roles that hold executable code, and are therefore per format rather than
+ *  singletons. A `library` layer is per selector for the same reason a
+ *  `controller` layer is: a module's JS entry point and its future Rust one are
+ *  different files, and a consumer resolves the one its own runtime can import.
+ *  A singleton would be wrong the moment a second runtime ships. */
+export const CODE_LAYER_ROLES: readonly LayerRole[] = ["controller", "library"];
+
+export function roleCarriesSelector(role: LayerRole): boolean {
+  return (CODE_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;

package/src/builtins.ts

@@ -1,6 +1,29 @@
-import { manifestFragment } from "./manifest-schemas.js";
+import { manifestFragment, manifestFragmentRef, withSchemaFragments } from "./manifest-schemas.js";
+
+/** A slot holding author-written JSON Schema. Localized and hoisted by
+ *  {@link withSchemaFragments} on the enclosing schema, which is what makes the
+ *  `#/$defs` pointer resolve inside whatever AJV compiles.
+ *
+ *  `KindSchema` and `JsonSchema7` share a body; the name is the discriminator
+ *  the IDE reads off the `x-telo-fragment` stamp to decide whether the
+ *  `x-telo-*` vocabulary belongs here. A kind's own `schema:` is where it does;
+ *  a `status:` block or an `inputType:` describes plain data, where it does not. */
+const kindSchemaSlot = {
+  title: "Schema",
+  description: "Configuration this kind accepts, as JSON Schema plus `x-telo-*` annotations.",
+  $ref: manifestFragmentRef("KindSchema"),
+};
+
+/** Observed state a kind reports while running, as a data schema. `required:` is
+ *  rejected separately by `validateObservedStateDeclarations`, which can say why
+ *  and what to write instead. */
+const observedStateSlot = {
+  title: "Observed state",
+  description:
+    "What a resource of this kind reports while running, published at `resources.<name>.status.<field>`.",
+  $ref: manifestFragmentRef("JsonSchema7"),
+};
 import type { ResourceDefinition } from "@telorun/sdk";
-import { OBSERVED_STATE_SCHEMA } from "./validate-observed-state.js";
 
 /** Descriptive provenance a module declares about itself, shared by
  *  `Telo.Application` and `Telo.Library`.
@@ -24,6 +47,32 @@ const PROVENANCE_METADATA = {
   documentation: { type: "string" },
 };
 
+/** The declared runtime requirements block, shared by `Telo.Application` and
+ *  `Telo.Library` — the two module kinds, whose schemas are otherwise
+ *  independent and would drift.
+ *
+ *  **Deliberately says only "these are objects", and nothing about the values.**
+ *  The grammar belongs to `requires-block.ts`, which is the single reader, and
+ *  every rule that matters — `^` and `~` refused, a bare version refused, bounds
+ *  that must not exclude each other, an upper bound that must name a version that
+ *  exists — needs a parse and a comparison, not a schema. Adding `type: "string"`
+ *  here bought nothing and cost a duplicate: `telo: 80` then produced BOTH a
+ *  `SCHEMA_VIOLATION` and a `REQUIRES_INVALID` for one node, one of them phrased
+ *  by a layer that does not know what the value is for.
+ *
+ *  Left open at both tiers for the same reason. An unrecognized axis is reported
+ *  by the reader with the vocabulary it knows — a far better message than AJV's —
+ *  and, critically, is SUPPRESSED while the `telo` requirement is itself unmet,
+ *  since an older runtime not knowing a newer axis is a consequence of the
+ *  version skew rather than a second defect. AJV cannot express that ordering. */
+const REQUIRES_SCHEMA = {
+  type: "object",
+  properties: {
+    host: { type: "object" },
+  },
+  additionalProperties: true,
+};
+
 /** 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
@@ -33,6 +82,33 @@ const ASSETS_FILES_SCHEMA = {
   items: { type: "string" },
 };
 
+/** `exports.code` — the entry point a sibling module's controller bundle resolves
+ *  this library's bare specifier to, one per format.
+ *
+ *  Data rather than a package URL: `controllers:` needs a PURL because it can name
+ *  an ecosystem fetch (`pkg:npm`, `pkg:cargo`), while this always names a file the
+ *  module already ships, so the type/namespace segments would be constant noise —
+ *  and a query string is one opaque box to the visual editor. `format` plus the
+ *  platform axes build the same `ArtifactSelector` a controller candidate does.
+ *  Semantics and diagnostics live in `analyzer/nodejs/src/module-library.ts`. */
+const LIBRARY_CANDIDATES_SCHEMA = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["specifier", "format", "path"],
+    properties: {
+      specifier: { type: "string" },
+      format: { type: "string" },
+      path: { type: "string" },
+      source: { type: "string" },
+      os: { type: "string" },
+      arch: { type: "string" },
+      libc: { type: "string" },
+    },
+    additionalProperties: false,
+  },
+};
+
 /** 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
@@ -44,7 +120,7 @@ const LAYER_INDEX_SCHEMA = {
     type: "object",
     required: ["role", "blob", "integrity"],
     properties: {
-      role: { type: "string", enum: ["controller", "assets", "common"] },
+      role: { type: "string", enum: ["controller", "library", "assets", "common"] },
       selector: {
         type: "object",
         required: ["format"],
@@ -251,13 +327,13 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
     // kernel registers this controller directly at boot, before any lazy
     // resolution — it states truthfully who provides it.
     controllers: [{ runtime: "kernel", entry: "Telo.JsonSchema" }],
-    schema: {
+    schema: withSchemaFragments({
       type: "object",
       properties: {
         schema: {
           title: "Schema",
           description: "JSON Schema definition for the declared data type.",
-          type: "object",
+          $ref: manifestFragmentRef("JsonSchema7"),
         },
         extends: {
           title: "Extends",
@@ -292,13 +368,13 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
       },
       required: ["schema"],
       additionalProperties: false,
-    },
+    }),
   },
   {
     kind: "Telo.Definition",
     metadata: { name: "Abstract", module: "Telo" },
     capability: "Telo.Template",
-    schema: {
+    schema: withSchemaFragments({
       type: "object",
       properties: {
         kind: { type: "string" },
@@ -309,15 +385,15 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           additionalProperties: true,
         },
         capability: { type: "string" },
-        schema: { type: "object", additionalProperties: true },
-        status: OBSERVED_STATE_SCHEMA,
+        schema: kindSchemaSlot,
+        status: observedStateSlot,
       },
       required: ["metadata"],
       // Telo.Abstract is an extension point by design — it must accept forward-compatible
       // fields (e.g. inputType/outputType from the typed-abstracts plan) without requiring
       // the analyzer to enumerate them here.
       additionalProperties: true,
-    },
+    }),
   },
   {
     kind: "Telo.Definition",
@@ -335,11 +411,17 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
     // matching how Run.Sequence steps factor dispatch from data. The dispatch
     // entry-point (`invoke` / `provide` / `run`) determines how `inputs`/`result`
     // are interpreted at runtime. See analyzer/nodejs/plans/template-internal-cel-validation.md.
-    schema: {
+    schema: withSchemaFragments({
       type: "object",
       additionalProperties: true,
       properties: {
-        status: OBSERVED_STATE_SCHEMA,
+        // The kind's own configuration contract. Declared as a slot for the
+        // first time here: it was reachable only as an unnamed extra property,
+        // so nothing could say what belonged in it — no completion inside a
+        // `schema:` block, and a misspelled keyword surviving to a runtime
+        // failure that named a different field.
+        schema: kindSchemaSlot,
+        status: observedStateSlot,
         resources: {
           type: "array",
           items: {
@@ -509,7 +591,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           },
         },
       },
-    },
+    }),
   },
   {
     kind: "Telo.Definition",
@@ -760,6 +842,9 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
         // CLI flag — so a level derived from the host environment goes through a
         // `variables:` entry read with `!cel`. See kernel/specs/logging.md §12.
         logging: ROOT_LOGGING_SCHEMA,
+        // The runtime range this module is verified against. See
+        // `analyzer/nodejs/src/requires-block.ts`.
+        requires: REQUIRES_SCHEMA,
       },
       required: ["metadata"],
       additionalProperties: false,
@@ -846,9 +931,13 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
               type: "array",
               items: { type: "string", not: { enum: ["variables", "secrets"] } },
             },
+            code: LIBRARY_CANDIDATES_SCHEMA,
           },
           additionalProperties: true,
         },
+        // The runtime range this module is verified against. See
+        // `analyzer/nodejs/src/requires-block.ts`.
+        requires: REQUIRES_SCHEMA,
       },
       required: ["metadata"],
       additionalProperties: false,

package/src/cel-bindings.ts

@@ -20,34 +20,9 @@ export interface BindingSites {
   scopeNames: Set<string>;
 }
 
-/**
- * CEL keywords. A binding named after one is unreachable — `true` lexes as a
- * literal, `in` as an operator — so it is reserved alongside the scope names,
- * which turns silence into a diagnostic.
- */
-export const CEL_RESERVED_WORDS: readonly string[] = [
-  "as",
-  "break",
-  "const",
-  "continue",
-  "else",
-  "false",
-  "for",
-  "function",
-  "if",
-  "import",
-  "in",
-  "let",
-  "loop",
-  "namespace",
-  "null",
-  "package",
-  "return",
-  "true",
-  "var",
-  "void",
-  "while",
-];
+// CEL keywords live in `identifier-name.ts` — a binding named after one is
+// unreachable for exactly the reason a resource or step named after one is, so
+// the list belongs to the identifier vocabulary rather than to this file.
 
 /** Locate a kind's bindings field and the scope names its annotated contexts
  *  declare. Returns undefined for a kind that declares no bindings region. */

package/src/definition-registry.ts

@@ -116,11 +116,36 @@ export class DefinitionRegistry {
   registerNamedTypeSchema(id: string, schema: Record<string, any>): boolean {
     if (this.definitionSchemaIds.has(id)) return false;
     if (this.registeredSchemaIds.has(id) || this.ajv.getSchema(id)) return true;
-    this.ajv.addSchema(schema, id);
+    if (!this.tryAddSchema(schema, id)) return true;
     this.registeredSchemaIds.add(id);
     return true;
   }
 
+  /**
+   * Register a schema, surviving one AJV refuses.
+   *
+   * `addSchema` META-VALIDATES and THROWS, and a throw here escapes the whole
+   * analyze pass: one author schema with `minimum: "3"` in it aborted the run
+   * with AJV's own unanchored text and took every other diagnostic in the file
+   * down with it — including the anchored one that says exactly which keyword is
+   * wrong. Registration is a lookup table for `$ref` resolution, so failing to
+   * fill one entry costs a reference that could not have resolved anyway.
+   *
+   * Nothing is swallowed: an unregisterable schema is invalid, and the two
+   * checks that report it both run afterwards and both anchor on the offending
+   * line — `SCHEMA_VIOLATION` from the `KindSchema` / `JsonSchema7` fragment the
+   * slot points at, and `SCHEMA_COMPILE_ERROR` from {@link schemaCompileError},
+   * which wraps `compile` for this same reason.
+   */
+  private tryAddSchema(schema: Record<string, any>, id: string): boolean {
+    try {
+      this.ajv.addSchema(schema, id);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   /** True when a schema is registered under `id` (a canonical `telo://` type id
    *  or a definition `$id`). Used to flag schema `$ref`s that resolve to nothing. */
   hasSchemaId(id: string): boolean {
@@ -187,7 +212,10 @@ export class DefinitionRegistry {
     if (this.ajv.getSchema(id)) {
       throw new Error(`Duplicate definition schema $id: "${id}" is already registered`);
     }
-    this.ajv.addSchema(schema, id);
+    // A schema AJV refuses is left unregistered rather than aborting the pass —
+    // see {@link tryAddSchema}. The id stays claimed either way, so a later
+    // named type cannot quietly take a kind's place.
+    this.tryAddSchema(schema, id);
     this.registeredSchemaIds.add(id);
     this.definitionSchemaIds.add(id);
   }