@telorun/analyzer 0.57.0 → 0.59.0

package/src/validate-cel-context.ts

@@ -1,5 +1,10 @@
 export { extractAccessChains, validateChainAgainstSchema } from "@telorun/templating";
-import { mergeTypeSchemas } from "@telorun/sdk";
+import {
+  elementSchemaOf,
+  isLiveSlot,
+  mergeTypeSchemas,
+  parseCanonicalTypeSchemaId,
+} from "@telorun/sdk";
 import { KERNEL_BUILTINS } from "./builtins.js";
 
 export interface ContextResolveOpts {
@@ -89,6 +94,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 +134,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);
     }
@@ -173,23 +211,73 @@ function schemaAtChain(
   return cur && typeof cur === "object" ? cur : undefined;
 }
 
-/** The element schema of a sibling collection expression, when statically known.
- *  Resolves `inputs.*` chains against the resource's `inputs:` contract and
- *  returns the array's `items`. Returns undefined for non-chain or untyped
- *  collections (caller substitutes `dyn`). */
-function resolveCollectionElementSchema(
+/**
+ * The schema of a sibling collection expression, when statically known.
+ *
+ * Resolves `inputs.*` chains against the resource's DECLARED contract, falling
+ * back to the legacy `inputs:` property map some kinds still carry. Reading the
+ * contract is what makes this work at all for a kind that declares `inputType:`
+ * — resolving only the property map left `item` untyped in every such kind,
+ * silently, which reads as "element typing is permissive here" rather than as a
+ * gap. Returns undefined for a non-chain or untyped collection, and the caller
+ * substitutes `dyn` rather than inventing an element type.
+ */
+function resolveCollectionSchema(
   manifestRoot: Record<string, any>,
   field: string,
+  allManifests: Record<string, any>[] | undefined,
 ): Record<string, any> | undefined {
   const chain = purePathChain(manifestRoot?.[field]);
   if (!chain || chain[0] !== "inputs") return undefined;
-  const contract = manifestRoot.inputs;
-  if (!contract || typeof contract !== "object") return undefined;
-  const terminal = schemaAtChain(chain.slice(1), { type: "object", properties: contract });
-  if (terminal && terminal.type === "array" && terminal.items && typeof terminal.items === "object") {
-    return terminal.items as Record<string, any>;
+  const declared = resolveTypeFieldToSchema(manifestRoot.inputType, allManifests ?? []);
+  const root =
+    declared && typeof declared === "object"
+      ? declared
+      : manifestRoot.inputs && typeof manifestRoot.inputs === "object"
+        ? { type: "object", properties: manifestRoot.inputs }
+        : undefined;
+  if (!root) return undefined;
+  return schemaAtChain(chain.slice(1), root);
+}
+
+/**
+ * What ITERATING a collection schema yields.
+ *
+ * An array answers with `items`; anything else answers through the value-type
+ * vocabulary, which is where "what is the element of this" is declared. No type
+ * is named here on purpose: a future iterable value type is covered by declaring
+ * `element` on one of its parameters, with nothing to change in the analyzer.
+ */
+function elementOfCollection(
+  collection: Record<string, any> | undefined,
+): Record<string, any> | undefined {
+  if (!collection || typeof collection !== "object") return undefined;
+  if (collection.type === "array") {
+    return collection.items && typeof collection.items === "object"
+      ? (collection.items as Record<string, any>)
+      : undefined;
   }
-  return undefined;
+  const element = elementSchemaOf(collection);
+  return element && typeof element === "object" ? (element as Record<string, any>) : undefined;
+}
+
+/**
+ * True when a context binding naming this collection must NOT be bound.
+ *
+ * A binding that re-exposes the collection can only hand over the value the
+ * consumer is already draining, and passing that on is an ordinary
+ * pass-through no member-access rule catches — so the drain is silent. `live` is
+ * exactly the property that makes a value unsafe to re-expose, and it is already
+ * in the vocabulary, so no consumer names a type to decide this.
+ */
+function collectionBindingWithheld(
+  schema: Record<string, any>,
+  manifestRoot: Record<string, any>,
+  allManifests: Record<string, any>[] | undefined,
+): boolean {
+  const from = schema?.["x-telo-context-collection-from"] as string | undefined;
+  if (!from) return false;
+  return isLiveSlot(resolveCollectionSchema(manifestRoot, from, allManifests));
 }
 
 /**
@@ -309,10 +397,20 @@ export function resolveContextAnnotations(
   // untyped sources fall back to `dyn` so a wrong element type is never invented.
   const elementFrom = schema["x-telo-context-element-from"] as string | undefined;
   if (elementFrom) {
-    const items = resolveCollectionElementSchema(manifestRoot, elementFrom);
+    const items = elementOfCollection(resolveCollectionSchema(manifestRoot, elementFrom, allManifests));
     return items ?? {};
   }
 
+  // The collection itself, as opposed to its element. Typed from whatever the
+  // sibling resolves to, so an array binding keeps the precision it has today
+  // instead of degrading to `dyn` now that the slot admits more than one shape.
+  // A `live` collection never reaches here — the property is dropped before
+  // recursion, so the name is simply not in scope.
+  const collectionFrom = schema["x-telo-context-collection-from"] as string | undefined;
+  if (collectionFrom) {
+    return resolveCollectionSchema(manifestRoot, collectionFrom, allManifests) ?? {};
+  }
+
   const fromRoot = schema["x-telo-context-from-root"] as string | undefined;
   const fromRefKindRaw = schema["x-telo-context-from-ref-kind"] as
     | string
@@ -412,6 +510,10 @@ export function resolveContextAnnotations(
   if (schema.properties) {
     const props: Record<string, any> = {};
     for (const [k, v] of Object.entries(schema.properties)) {
+      // Withholding happens HERE rather than inside the child resolver, because
+      // this is the only level that owns the property map — a child can return a
+      // schema but cannot remove itself from one.
+      if (collectionBindingWithheld(v as Record<string, any>, manifestRoot, allManifests)) continue;
       props[k] = resolveContextAnnotations(v as Record<string, any>, manifestItem, normalizedOpts);
     }
     return { ...schema, properties: props };

package/src/validate-step-inputs.ts

@@ -2,7 +2,14 @@ import type { AliasResolver, ModuleScopes } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import type { ContractDirection } from "./extends-resolution.js";
 import { resolveContract } from "./invocation-contract.js";
-import { substituteCelFields, validateAgainstSchema } from "./schema-compat.js";
+import {
+  checkSchemaCompatibility,
+  navigateSchemaToExprPath,
+  substituteCelFields,
+  validateAgainstSchema,
+} from "./schema-compat.js";
+import { plainChainOf } from "@telorun/templating";
+import { valueTypeOf } from "@telorun/sdk";
 import {
   analyzerContractScope,
   containerOf,
@@ -16,8 +23,12 @@ export interface StepInputIssue {
   path: string;
   targetLabel: string;
   message: string;
+  /** Set when the issue is a type-argument disagreement rather than a contract
+   *  shape violation — the two read differently and deserve their own code. */
+  code?: "CEL_TYPE_ARGUMENT_MISMATCH";
 }
 
+
 /**
  * Validate every step's `inputs:` against the invoked target's declared input
  * contract — the static half of what the kernel enforces at dispatch.
@@ -40,6 +51,10 @@ export function collectStepInputIssues(
   defs: DefinitionRegistry,
   aliases: AliasResolver,
   scopes: ModuleScopes,
+  /** The typed `steps.<name>.result` context for this resource. Supplied by the
+   *  caller because building it is analyzer state; without it the contract check
+   *  still runs and only the type-argument comparison is skipped. */
+  stepContext?: Record<string, any>,
 ): StepInputIssue[] {
   const out: StepInputIssue[] = [];
   const props = defSchema.properties as Record<string, any> | undefined;
@@ -97,6 +112,46 @@ export function collectStepInputIssues(
       const substituted = substituteCelFields(values, contract.schema, undefined, (p) =>
         celPaths.add(p),
       );
+      // The type-argument check, at the one site where a produced value's schema
+      // meets a consuming slot's. A CEL leaf's placeholder says nothing about
+      // what the expression yields, so AJV above is silent here by design — and
+      // that silence is exactly where a stream of the wrong element used to
+      // flow. The comparison is covariant and gradual: an omitted argument is
+      // *any* in both directions, so only a definite conflict is reported.
+      if (stepContext) {
+        for (const [inputName, inputValue] of Object.entries(values)) {
+          const chain = plainChainOf(inputValue);
+          // The step context is rooted at the STEP MAP, so a `steps.` prefix is
+          // the namespace name and not a property of it. Only that namespace is
+          // navigated: `inputs.` and a named binding resolve elsewhere, and
+          // guessing at a root this does not hold would compare the wrong schema.
+          if (!chain?.startsWith("steps.")) continue;
+          const produced = navigateSchemaToExprPath(stepContext, chain.slice("steps.".length));
+          const slotSchema = (contract.schema.properties as Record<string, any> | undefined)?.[
+            inputName
+          ];
+          if (!produced || !slotSchema) continue;
+          // ONLY a type-argument disagreement, which is what the code says. The
+          // comparator is a general structural comparison, so running it on any
+          // pair would report a missing required property as "disagreeing type
+          // arguments" — and would turn every plain-chain wiring site into a
+          // broad new Error-severity check hidden behind an argument-specific
+          // name. Both sides must declare a value type for the question to be
+          // about arguments at all.
+          if (!valueTypeOf(produced) || !valueTypeOf(slotSchema)) continue;
+          const { compatible, issues } = checkSchemaCompatibility(produced, slotSchema, (ref) =>
+            defs.schemaForId(ref),
+          );
+          if (compatible) continue;
+          out.push({
+            path: `${stepPath}.${inputsField}.${inputName}`,
+            targetLabel: invokedName ?? invokedKind ?? "the invoked resource",
+            message: issues.join("; "),
+            code: "CEL_TYPE_ARGUMENT_MISMATCH",
+          });
+        }
+      }
+
       for (const issue of validateAgainstSchema(substituted, contract.schema)) {
         if (celPaths.has(issue.path)) continue;
         // A missing-required issue names the property that ISN'T there, so

package/src/validate-value-type-slots.ts

@@ -0,0 +1,182 @@
+/**
+ * Static validation of the `x-telo-type` annotation itself — the strict half of
+ * the accessor split, and the `validate-ref-slots.ts` precedent.
+ *
+ * `readValueTypeSlot` is deliberately lenient: it reports whatever it can read,
+ * returning a slot with no `entry` for a name it does not know. That leniency is
+ * what lets every surface keep working; this pass is what stops it becoming
+ * silence. Before the unification an unrecognized brand simply resolved to
+ * `undefined` and the slot quietly lost its identity — the same class of failure
+ * `X_TELO_REF_INVALID_USE` exists to prevent for `use` tokens.
+ *
+ * The vocabulary is CLOSED and `Telo.`-qualified, so there is nothing here to
+ * resolve against an alias scope: a name is a built-in or it is a mistake. A
+ * SHAPE is a different thing entirely and is named with the reference tag, which
+ * carries its own resolution and its own diagnostics — this pass never sees one,
+ * because `resolveSchemaTypeRefs` has already turned it into a `$ref`.
+ *
+ * Scoping follows `X_TELO_REF_UNRESOLVED`: reported only for manifests in the
+ * entry's own modules, since a published dependency is not the consumer's to fix.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import { readValueTypeSlot, VALUE_TYPES, X_TELO_TYPE, type ResourceManifest } from "@telorun/sdk";
+import { distance } from "./levenshtein.js";
+import { isInSchemaRegion } from "./schema-region.js";
+
+export interface ValueTypeSlotIssue {
+  code: "X_TELO_TYPE_UNKNOWN" | "X_TELO_TYPE_ARGUMENT_UNKNOWN";
+  manifest: ResourceManifest;
+  /** Dotted path to the annotated schema node, e.g. `schema.properties.body`. */
+  path: string;
+  message: string;
+  /** The whole-value replacement that repairs it, when one is derivable. A
+   *  misspelled name has a single correct spelling and the annotation's value is
+   *  that name, so the repair is the primitive `DiagnosticFix` already carries —
+   *  computing a suggestion and printing it in prose alone leaves the author to
+   *  retype what the analyzer already knows. Only for the bare-name spelling: the
+   *  object form's name is nested, and a whole-value replacement there would
+   *  discard the type arguments beside it. */
+  fix?: { replacement: string };
+}
+
+/** Schema regions are reached by ANCESTRY, not by root key — see
+ *  `schema-region.ts`. Walking a manifest's root fields covers only a fraction of
+ *  the sites an author writes a schema at: an API route's `request.schema.body`
+ *  sits under `routes`, and a check that never reaches it is a hole in exactly
+ *  the diagnostic that exists to stop an unknown name degrading silently. */
+
+/** The closest declared type name within an edit-distance threshold, or
+ *  undefined. Mirrors `computeSuggestKind`: case-sensitive, and silent on a tie,
+ *  because a coin-flip suggestion is worse than none. */
+function suggestValueType(name: string): string | undefined {
+  if (!name) return undefined;
+  const threshold = Math.min(3, Math.floor(name.length / 3));
+  if (threshold < 1) return undefined;
+  let best: string | undefined;
+  let bestDist = threshold + 1;
+  let tied = false;
+  for (const candidate of VALUE_TYPES.keys()) {
+    const d = distance(name, candidate);
+    if (d < bestDist) {
+      best = candidate;
+      bestDist = d;
+      tied = false;
+    } else if (d === bestDist) {
+      tied = true;
+    }
+  }
+  return !best || bestDist > threshold || tied ? undefined : best;
+}
+
+function declaredNames(): string {
+  return [...VALUE_TYPES.keys()].join(", ");
+}
+
+/** Report the annotation on one schema node. */
+function checkNode(
+  node: Record<string, unknown>,
+  manifest: ResourceManifest,
+  path: string,
+  issues: ValueTypeSlotIssue[],
+): void {
+  const slot = readValueTypeSlot(node);
+  if (!slot) return;
+
+  if (!slot.entry) {
+    const suggestion = suggestValueType(slot.name);
+    // Only the bare-name spelling can carry the repair: it IS the annotation's
+    // whole value, which is the only shape `DiagnosticFix` describes.
+    const bareName = typeof (node as Record<string, unknown>)[X_TELO_TYPE] === "string";
+    issues.push({
+      code: "X_TELO_TYPE_UNKNOWN",
+      manifest,
+      path,
+      message:
+        `'${slot.name || "(missing name)"}' is not a value type. ` +
+        (suggestion ? `Did you mean '${suggestion}'? ` : "") +
+        `Declared types: ${declaredNames()}. A value type names how a value is ` +
+        `REPRESENTED and is kernel-owned; to name a shape, reference it with !ref.`,
+      ...(suggestion && bareName ? { fix: { replacement: suggestion } } : {}),
+    });
+    return;
+  }
+
+  const declared = new Set(slot.entry.parameters.map((p) => p.name));
+  for (const argument of Object.keys(slot.args)) {
+    if (declared.has(argument)) continue;
+    issues.push({
+      code: "X_TELO_TYPE_ARGUMENT_UNKNOWN",
+      manifest,
+      path,
+      message:
+        `'${slot.entry.name}' declares no type parameter '${argument}'. ` +
+        (declared.size > 0
+          ? `Its parameters: ${[...declared].join(", ")}.`
+          : `It takes no type parameters.`),
+    });
+  }
+}
+
+/** Walk a schema value, reporting every annotation it carries.
+ *
+ *  Descends through every container rather than through a keyword list: a value
+ *  type is legal at any schema position — a property, an item, a union branch, a
+ *  `$defs` entry, a type argument — and enumerating positions is how a check
+ *  ends up not covering the one an author used. */
+function walk(
+  value: unknown,
+  manifest: ResourceManifest,
+  path: string,
+  segments: (string | number)[],
+  seen: Set<object>,
+  issues: ValueTypeSlotIssue[],
+): void {
+  if (value === null || typeof value !== "object") return;
+  if (seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, i) =>
+      walk(item, manifest, `${path}[${i}]`, [...segments, i], seen, issues),
+    );
+    return;
+  }
+  const node = value as Record<string, unknown>;
+  // Report only inside a schema region. The walk itself is unbounded — reporting
+  // is safe anywhere, unlike a rewrite — but an `x-telo-type` key sitting in a
+  // resource's own configuration is not a schema annotation and is not this
+  // check's to judge.
+  if (isInSchemaRegion([...segments, X_TELO_TYPE])) {
+    checkNode(node, manifest, path, issues);
+  }
+  for (const [key, child] of Object.entries(node)) {
+    // The annotation's own value is read by `checkNode`; descending into it
+    // would report the type ARGUMENTS as if they were annotated nodes of their
+    // own. Their turn comes below, as ordinary schema nodes.
+    if (key === X_TELO_TYPE) {
+      // Walk the NORMALIZED arguments, so a bare-name argument (`of: Telo.Bytes`)
+      // is checked exactly as its expanded form is — the sugar must not be a
+      // hole in the check that exists to catch a misspelled name.
+      const slot = readValueTypeSlot(node);
+      for (const [argName, argValue] of Object.entries(slot?.args ?? {})) {
+        walk(
+          argValue,
+          manifest,
+          `${path}.${X_TELO_TYPE}.${argName}`,
+          [...segments, X_TELO_TYPE, argName],
+          seen,
+          issues,
+        );
+      }
+      continue;
+    }
+    walk(child, manifest, path ? `${path}.${key}` : key, [...segments, key], seen, issues);
+  }
+}
+
+/** Every `x-telo-type` problem in one manifest, wherever a schema is written. */
+export function validateValueTypeSlots(manifest: ResourceManifest): ValueTypeSlotIssue[] {
+  const issues: ValueTypeSlotIssue[] = [];
+  walk(manifest, manifest, "", [], new Set<object>(), issues);
+  return issues;
+}

package/src/value-type-keyword.ts

@@ -0,0 +1,135 @@
+/** The AJV half of `x-telo-type`, and the single place any Telo keyword is
+ *  registered on an AJV instance.
+ *
+ *  WHY CODEGEN RATHER THAN A `validate` FUNCTION. The kernel compiles standalone
+ *  validators and caches them on disk; a function-valued keyword does not survive
+ *  that serialization, so the check would silently be absent from exactly the
+ *  validators the runtime uses. Codegen inlines instead.
+ *
+ *  WHY THE CODEGEN LIVES HERE AND THE VOCABULARY DOES NOT. The SDK cannot depend
+ *  on ajv, and an entry declares a REPRESENTATION rather than a code fragment —
+ *  which is what lets one JSON file be read by a Rust kernel that has no AJV at
+ *  all. The split is the whole point: `sdk/value-types/*.json` says *what a value
+ *  is*, `sdk/nodejs/src/value-type.ts` says *what that means in this runtime*,
+ *  and this file turns the pair into a check.
+ *
+ *  ONE REGISTRATION SITE. {@link registerTeloKeywords} replaced five drifted
+ *  ones — the analyzer's `createAjv` and the kernel's `schema-validator`,
+ *  `resource-context`, `observed-state` and `manifest-schemas` — which registered
+ *  overlapping lists of twelve, four, one and one. Drift there is not cosmetic: a
+ *  no-op registration is what keeps `strict` mode quiet about an annotation, and
+ *  a keyword that emits code is missing entirely from any instance that forgot
+ *  it, so the same schema validated two ways depending on which AJV saw it. */
+
+import * as AjvNS from "ajv";
+import type { KeywordDefinition } from "ajv";
+import {
+  VALUE_TYPE_BINDINGS,
+  X_TELO_TYPE,
+  readValueTypeSlot,
+  type ValueTypeEntry,
+} from "@telorun/sdk";
+
+// AJV's codegen template tag. The package is consumed in both ESM and CJS interop
+// shapes, so the named export may sit on the namespace or behind `.default` —
+// the same fallback `schema-compat` uses to reach the constructor. Skipping it
+// would leave `codegen` undefined under a loader that does not detect AJV's named
+// CJS re-exports, and the keyword would throw on its first compile.
+type CodegenTag = (s: TemplateStringsArray, ...a: unknown[]) => unknown;
+const ajvExports = (AjvNS as any).default ?? AjvNS;
+const codegen: CodegenTag = ajvExports._ ?? (AjvNS as any)._;
+
+/**
+ * Annotations that carry no validation at all: analyzer, editor and topology
+ * metadata. Registered as no-ops so AJV does not treat them as unknown keywords,
+ * and listed in one place so an instance cannot know about half of them.
+ *
+ * `x-telo-type` is deliberately absent — it is the one that emits code.
+ */
+export const ANNOTATION_KEYWORDS = [
+  "x-telo-bindings-from",
+  "x-telo-catches-for",
+  "x-telo-context",
+  "x-telo-context-element-from",
+  "x-telo-context-from",
+  "x-telo-context-from-ref-kind",
+  "x-telo-context-from-root",
+  "x-telo-context-ref-from",
+  "x-telo-error-context",
+  "x-telo-eval",
+  "x-telo-inline",
+  "x-telo-outcome-list",
+  "x-telo-provides-zone",
+  "x-telo-ref",
+  "x-telo-requires-zone",
+  "x-telo-schema-from",
+  "x-telo-scope",
+  "x-telo-step-context",
+  "x-telo-topology-role",
+  "x-telo-value-schema-from",
+  "x-telo-widget",
+] as const;
+
+/**
+ * The `x-telo-type` keyword.
+ *
+ * Three postures, decided by the entry and never by this code:
+ *
+ *  - a `json` representation validates through its own declared schema, so the
+ *    keyword emits nothing — the name carries nominal identity for static wiring
+ *    and has no runtime existence at all;
+ *  - a `live` instance is EXEMPT: its value is never traversed, because iterating
+ *    a stream to check it is precisely what the exemption is for;
+ *  - every other instance is ASSERTED against the constructor its binding names.
+ *
+ * An unknown name emits nothing here. It is a hard diagnostic in the analyzer
+ * (`X_TELO_TYPE_UNKNOWN`), which is where a name can be reported against the
+ * manifest that wrote it; failing compilation instead would take out every
+ * validator in a module for one typo in one slot.
+ */
+export function valueTypeKeyword(): KeywordDefinition {
+  return {
+    keyword: X_TELO_TYPE,
+    // Both spellings: a bare name, or the object form carrying type arguments.
+    schemaType: ["string", "object"],
+    code(cxt: any) {
+      const entry: ValueTypeEntry | undefined = readValueTypeSlot({
+        [X_TELO_TYPE]: cxt.schema,
+      })?.entry;
+      if (!entry || entry.representation !== "instance" || entry.live) return;
+      const binding = VALUE_TYPE_BINDINGS[entry.binding!];
+      if (!binding) return;
+      // The constructor reaches generated code through AJV's value scope, which
+      // is what keeps this general: `Uint8Array` happens to be a global, but a
+      // binding may name a class that is not, and inlining a bare identifier
+      // would compile to a reference that does not resolve.
+      const ctor = cxt.gen.scopeValue("obj", {
+        ref: binding.constructor,
+        code: codegen`require("@telorun/sdk").VALUE_TYPE_BINDINGS[${entry.binding!}].constructor`,
+      });
+      cxt.pass(codegen`${cxt.data} instanceof ${ctor}`);
+    },
+    error: {
+      message: (cxt: any) => {
+        const entry = readValueTypeSlot({ [X_TELO_TYPE]: cxt.schema })?.entry;
+        return entry?.binding === "bytes"
+          ? "must be raw bytes (a Uint8Array) — bytes cannot be written inline in a manifest"
+          : `must be a ${entry?.name ?? "declared value type"} — this value is not writable inline in a manifest`;
+      },
+    },
+  } as KeywordDefinition;
+}
+
+/**
+ * Register every Telo keyword on an AJV instance: the annotations as no-ops and
+ * `x-telo-type` as the one that checks.
+ *
+ * Every AJV instance in the runtime and the analyzer goes through this, so a
+ * schema means the same thing wherever it is validated.
+ */
+export function registerTeloKeywords(ajv: {
+  addKeyword: (keyword: any, definition?: any) => unknown;
+}): void {
+  for (const keyword of ANNOTATION_KEYWORDS) ajv.addKeyword(keyword);
+  ajv.addKeyword(valueTypeKeyword());
+}