@telorun/analyzer 0.57.0 → 0.59.0

package/dist/value-type-keyword.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-type-keyword.d.ts","sourceRoot":"","sources":["../src/value-type-keyword.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;+EAqB+E;AAG/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,KAAK,CAAC;AAiB7C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,ueAsBtB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CA+BpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IACxC,UAAU,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACzD,GAAG,IAAI,CAGP"}

package/dist/value-type-keyword.js

@@ -0,0 +1,119 @@
+/** 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 { VALUE_TYPE_BINDINGS, X_TELO_TYPE, readValueTypeSlot, } from "@telorun/sdk";
+const ajvExports = AjvNS.default ?? AjvNS;
+const codegen = ajvExports._ ?? AjvNS._;
+/**
+ * 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",
+];
+/**
+ * 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() {
+    return {
+        keyword: X_TELO_TYPE,
+        // Both spellings: a bare name, or the object form carrying type arguments.
+        schemaType: ["string", "object"],
+        code(cxt) {
+            const entry = 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) => {
+                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`;
+            },
+        },
+    };
+}
+/**
+ * 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) {
+    for (const keyword of ANNOTATION_KEYWORDS)
+        ajv.addKeyword(keyword);
+    ajv.addKeyword(valueTypeKeyword());
+}

package/dist/yaml-source-edit.d.ts

@@ -0,0 +1,56 @@
+/** Writing a value back into YAML SOURCE — the two primitives every in-place
+ *  repair is built from, and the one place their rules are stated.
+ *
+ *  A repair is a byte splice over the author's own text, never
+ *  `Document.toString()`: re-serializing re-folds block scalars, drops
+ *  quote-style hints and reflows long strings, so a one-key edit would arrive
+ *  as a whole-file diff. That leaves two questions every writer has to answer
+ *  identically — how a value is re-quoted to occupy a span, and how overlapping
+ *  spans are spliced — and three surfaces asking them: the editors' quick fix
+ *  (`@telorun/ide-support`), `telo migrate` (the migration driver), and
+ *  `telo upgrade`'s pin rewrite.
+ *
+ *  They live HERE, in the lowest package of the three, because they are pure
+ *  string work with no Node dependency and because a copy per surface is a
+ *  silent-divergence risk of exactly the kind Telo's cross-cutting primitives
+ *  rule exists to prevent: two writers editing the same file from two copies of
+ *  a subtle quoting rule will eventually quote one value two ways, and nothing
+ *  would catch it. Same precedent as `ref-slot.ts` / `binary-slot.ts` — a rule
+ *  several surfaces must agree on gets one reader. */
+/** Whether `value` can be written as a plain scalar without changing meaning. */
+export declare function isPlainSafe(value: string): boolean;
+/** Quote style of the source text a repair is replacing. */
+export type QuoteStyle = "double" | "single" | "plain";
+export declare function quoteStyleOf(source: string): QuoteStyle;
+/** Render `replacement` so it occupies `originalSource`'s span as the same
+ *  scalar the author would have written by hand, or `undefined` when the span
+ *  cannot be rewritten safely.
+ *
+ *  A plain original is kept plain when it can be — rewriting `Run.Sequenc` to
+ *  `"Run.Sequence"` would be a correct but noisy diff on a kind name — and
+ *  promoted to double quotes when the new value would not survive unquoted.
+ *
+ *  **A multi-line span is refused.** A block scalar's span covers its `|`/`>-`
+ *  indicator AND its trailing newline, so writing a single-line scalar over it
+ *  deletes the line break that ended the mapping entry and glues the next key
+ *  onto the value — the document stops parsing. Re-emitting a block scalar
+ *  correctly needs the node's indentation, which no consumer of this function
+ *  has. A multi-line REPLACEMENT is refused for the mirror reason: its
+ *  continuation lines would land at column 0, which is not a legal mapping
+ *  value. A quick fix promises a repair that can be applied without review, so
+ *  the only honest answer for these is no repair. */
+export declare function renderFixReplacement(originalSource: string, replacement: string): string | undefined;
+/** A splice over a source file: replace `[start, end)` with `newText`. An empty
+ *  span is a pure insertion. */
+export interface TextEdit {
+    /** Byte offset of the first replaced character (inclusive). */
+    readonly start: number;
+    /** Byte offset one past the last replaced character. */
+    readonly end: number;
+    readonly newText: string;
+}
+/** Splice `edits` into `text`, right to left so earlier offsets stay valid.
+ *  Callers are responsible for edits not overlapping; two splices contending
+ *  for the same bytes cannot both be honoured, and this does not arbitrate. */
+export declare function applyTextEdits(text: string, edits: readonly TextEdit[]): string;
+//# sourceMappingURL=yaml-source-edit.d.ts.map

package/dist/yaml-source-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-source-edit.d.ts","sourceRoot":"","sources":["../src/yaml-source-edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;sDAkBsD;AAStD,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAUlD;AAED,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAIvD;AAED;;;;;;;;;;;;;;;;qDAgBqD;AACrD,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAcpB;AAED;gCACgC;AAChC,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;+EAE+E;AAC/E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAO/E"}

package/dist/yaml-source-edit.js

@@ -0,0 +1,93 @@
+/** Writing a value back into YAML SOURCE — the two primitives every in-place
+ *  repair is built from, and the one place their rules are stated.
+ *
+ *  A repair is a byte splice over the author's own text, never
+ *  `Document.toString()`: re-serializing re-folds block scalars, drops
+ *  quote-style hints and reflows long strings, so a one-key edit would arrive
+ *  as a whole-file diff. That leaves two questions every writer has to answer
+ *  identically — how a value is re-quoted to occupy a span, and how overlapping
+ *  spans are spliced — and three surfaces asking them: the editors' quick fix
+ *  (`@telorun/ide-support`), `telo migrate` (the migration driver), and
+ *  `telo upgrade`'s pin rewrite.
+ *
+ *  They live HERE, in the lowest package of the three, because they are pure
+ *  string work with no Node dependency and because a copy per surface is a
+ *  silent-divergence risk of exactly the kind Telo's cross-cutting primitives
+ *  rule exists to prevent: two writers editing the same file from two copies of
+ *  a subtle quoting rule will eventually quote one value two ways, and nothing
+ *  would catch it. Same precedent as `ref-slot.ts` / `binary-slot.ts` — a rule
+ *  several surfaces must agree on gets one reader. */
+/** Characters that make a plain (unquoted) YAML scalar reparse as something
+ *  else. `-` and `?` are indicators only when followed by a space, so they are
+ *  handled by the leading-token check rather than listed here. */
+const PLAIN_UNSAFE_LEAD = new Set([
+    "&", "*", "!", "|", ">", "%", "@", "`", "#", "'", '"', "{", "[", "}", "]", ",",
+]);
+/** Whether `value` can be written as a plain scalar without changing meaning. */
+export function isPlainSafe(value) {
+    if (value === "" || value.trim() !== value)
+        return false;
+    if (PLAIN_UNSAFE_LEAD.has(value[0]))
+        return false;
+    // `-`/`?`/`:` lead only matter when a space follows — `-x` is a scalar,
+    // `- x` is a sequence entry.
+    if (/^[-?:]\s/.test(value))
+        return false;
+    // A colon-space anywhere opens a mapping; a space-hash opens a comment.
+    if (value.includes(": ") || value.includes(" #"))
+        return false;
+    if (value.endsWith(":"))
+        return false;
+    return !/[\n\r]/.test(value);
+}
+export function quoteStyleOf(source) {
+    if (source.length >= 2 && source.startsWith('"') && source.endsWith('"'))
+        return "double";
+    if (source.length >= 2 && source.startsWith("'") && source.endsWith("'"))
+        return "single";
+    return "plain";
+}
+/** Render `replacement` so it occupies `originalSource`'s span as the same
+ *  scalar the author would have written by hand, or `undefined` when the span
+ *  cannot be rewritten safely.
+ *
+ *  A plain original is kept plain when it can be — rewriting `Run.Sequenc` to
+ *  `"Run.Sequence"` would be a correct but noisy diff on a kind name — and
+ *  promoted to double quotes when the new value would not survive unquoted.
+ *
+ *  **A multi-line span is refused.** A block scalar's span covers its `|`/`>-`
+ *  indicator AND its trailing newline, so writing a single-line scalar over it
+ *  deletes the line break that ended the mapping entry and glues the next key
+ *  onto the value — the document stops parsing. Re-emitting a block scalar
+ *  correctly needs the node's indentation, which no consumer of this function
+ *  has. A multi-line REPLACEMENT is refused for the mirror reason: its
+ *  continuation lines would land at column 0, which is not a legal mapping
+ *  value. A quick fix promises a repair that can be applied without review, so
+ *  the only honest answer for these is no repair. */
+export function renderFixReplacement(originalSource, replacement) {
+    if (/[\n\r]/.test(originalSource) || /[\n\r]/.test(replacement))
+        return undefined;
+    const style = quoteStyleOf(originalSource);
+    if (style === "single") {
+        // A single-quoted YAML scalar escapes only the quote, by doubling it. CEL
+        // string literals use single quotes constantly, so this is the common case
+        // for an expression written in a single-quoted scalar.
+        return `'${replacement.replaceAll("'", "''")}'`;
+    }
+    if (style === "double" || !isPlainSafe(replacement)) {
+        return `"${replacement.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+    }
+    return replacement;
+}
+/** Splice `edits` into `text`, right to left so earlier offsets stay valid.
+ *  Callers are responsible for edits not overlapping; two splices contending
+ *  for the same bytes cannot both be honoured, and this does not arbitrate. */
+export function applyTextEdits(text, edits) {
+    if (edits.length === 0)
+        return text;
+    let out = text;
+    for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+        out = out.slice(0, edit.start) + edit.newText + out.slice(edit.end);
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,13 +43,13 @@
     "jsonpath-plus": "^10.3.0",
     "packageurl-js": "^2.0.1",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.13.0"
+    "@telorun/templating": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.72.0"
+    "@telorun/sdk": "0.74.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analyzer.ts

@@ -5,6 +5,7 @@ import {
   defaultRegistry,
   isRefSentinel,
   isTaggedSentinel,
+  plainChainOf,
   type CelSurface,
 } from "@telorun/templating";
 import type { DiagnosticFix } from "./types.js";
@@ -56,11 +57,17 @@ import {
   validateRefSlotDeclarations,
   type RefSlotIssue,
 } from "./validate-ref-slots.js";
+import {
+  validateValueTypeSlots,
+  type ValueTypeSlotIssue,
+} from "./validate-value-type-slots.js";
 import { resolveSchemaTypeRefs } from "./resolve-schema-type-refs.js";
 import { validateSchemaTypeRefs } from "./validate-schema-type-refs.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import {
   celTypeSatisfiesJsonSchema,
+  checkSchemaCompatibility,
+  navigateSchemaToExprPath,
   substituteCelFields,
   validateAgainstSchema,
   type SchemaIssue,
@@ -1201,6 +1208,18 @@ export class StaticAnalyzer {
     const refConstraintIssues: RefConstraintIssue[] = [];
     const refSlotIssues: RefSlotIssue[] = [];
     const zoneSlotIssues: ZoneSlotIssue[] = [];
+    // `x-telo-type` is checked on EVERY manifest, not only on definition docs: a
+    // schema fragment is written wherever a kind declares a schema-valued field,
+    // so an inline `inputType:` on an ordinary resource carries one just as a
+    // definition's `schema:` does. Same scoping as every other schema issue —
+    // the entry's own modules, since a dependency is not the consumer's to fix.
+    const valueTypeSlotIssues: ValueTypeSlotIssue[] = [];
+    for (const m of manifests) {
+      const declaringModule = (m.metadata as { module?: string } | undefined)?.module;
+      if (!declaringModule || rootModules.has(declaringModule)) {
+        valueTypeSlotIssues.push(...validateValueTypeSlots(m as unknown as ResourceManifest));
+      }
+    }
     for (const m of manifests) {
       if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
       const def = m as unknown as ResourceDefinition;
@@ -1340,6 +1359,26 @@ export class StaticAnalyzer {
       // accessor split; `readRefSlot` stays lenient so surfaces keep working
       // mid-migration, and this reports what leniency would silently absorb.
       for (const issue of refSlotIssues) diagnostics.push(refSlotIssueDiagnostic(issue));
+      // The same split for `x-telo-type`. Its reader returns a slot with no
+      // entry for a name it does not know, which is what an unrecognized brand
+      // used to do SILENTLY — the slot simply lost its identity.
+      for (const issue of valueTypeSlotIssues) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: issue.code,
+          source: SOURCE,
+          message: issue.message,
+          data: {
+            resource: {
+              kind: issue.manifest.kind,
+              name: issue.manifest.metadata?.name as string,
+            },
+            filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+            path: issue.path,
+            ...(issue.fix ? { fix: issue.fix } : {}),
+          },
+        });
+      }
       // Same split for the two zone annotations. Unreadable ones fail in
       // OPPOSITE directions — a dropped requirement is silently unenforced, a
       // dropped provision invents failures — so neither can be left to
@@ -1625,6 +1664,11 @@ export class StaticAnalyzer {
       filePath?: string;
     })[] = [];
     const celTypeByPath = new Map<ResourceManifest, Map<string, string>>();
+    // The schema an expression RESOLVES TO, beside the CEL type it carries. Both
+    // are needed and neither replaces the other: the CEL type answers "does this
+    // fit the slot at all", the schema answers "do their type arguments agree",
+    // which cel-js cannot express because it types by constructor identity.
+    const celSourceSchemaByPath = new Map<ResourceManifest, Map<string, Record<string, any>>>();
     // Context-free typed environments, one per manifest. Reused across every
     // expression in it — see the build site for why a matched context opts out.
     const typedEnvByManifest = new Map<ResourceManifest, Environment>();
@@ -1962,12 +2006,15 @@ export class StaticAnalyzer {
               defs,
               aliases,
               { aliasesByModule, rootModules },
+              celStepContextSchema,
             )) {
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
-                code: "CONTRACT_INPUTS_MISMATCH",
+                code: issue.code ?? "CONTRACT_INPUTS_MISMATCH",
                 source: SOURCE,
-                message: `${m.kind}/${stepName}: inputs at '${issue.path}' do not satisfy ${issue.targetLabel}'s declared inputType: ${issue.message}`,
+                message: issue.code
+                  ? `${m.kind}/${stepName}: inputs at '${issue.path}' flow into ${issue.targetLabel} with disagreeing type arguments: ${issue.message}`
+                  : `${m.kind}/${stepName}: inputs at '${issue.path}' do not satisfy ${issue.targetLabel}'s declared inputType: ${issue.message}`,
                 data: {
                   resource: { kind: m.kind, name: stepName ?? "" },
                   filePath: stepFile,
@@ -2260,6 +2307,30 @@ export class StaticAnalyzer {
             byPath.set(path, result.type);
           }
 
+          // The producer half of the type-argument check. A CEL type is a bare
+          // name — cel-js types by constructor identity, so a byte stream and a
+          // string stream are one CEL type and always will be — so the argument
+          // comparison is a parallel pass over the SCHEMAS the analyzer already
+          // walks. This is where the producer's schema is in hand: navigating
+          // the expression's chain into its context schema is exactly "the
+          // producer's outputType at the expression's tail".
+          //
+          // Only a PLAIN CHAIN is navigated — `steps.encode.result.output`, the
+          // shape a wiring site actually takes. An expression that computes
+          // rather than names has no schema to read off the context, so it
+          // records nothing and no argument check fires: silence where the
+          // analyzer knows least is the conservative direction, and the same one
+          // `x-telo-step-context`'s pure-`value` typing takes.
+          const chain = effectiveContext ? plainChainOf(`\${{${expr}}}`) : undefined;
+          if (chain) {
+            const produced = navigateSchemaToExprPath(effectiveContext!, chain);
+            if (produced) {
+              let byPath = celSourceSchemaByPath.get(m);
+              if (!byPath) celSourceSchemaByPath.set(m, (byPath = new Map()));
+              byPath.set(path, produced);
+            }
+          }
+
           // A non-deterministic call in a compile-eval field is baked once at
           // load: `nowIso()` there freezes at boot. Sometimes that is the
           // intent (a boot timestamp, a run id), so it warns rather than
@@ -2331,13 +2402,35 @@ export class StaticAnalyzer {
     for (const slot of celReturnSlots) {
       const type = celTypeByPath.get(slot.manifest)?.get(slot.path);
       if (type === undefined) continue;
-      if (celTypeSatisfiesJsonSchema(type.split("<")[0]!, slot.schema)) continue;
-      const expected = slot.schema["x-telo-type"] ?? slot.schema.type ?? "unknown";
+      if (!celTypeSatisfiesJsonSchema(type.split("<")[0]!, slot.schema)) {
+        const expected = slot.schema["x-telo-type"] ?? slot.schema.type ?? "unknown";
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "CEL_TYPE_ERROR",
+          source: SOURCE,
+          message: `${slot.resource.kind}/${slot.resource.name}: CEL at '${slot.path}' returns '${type}' but the field expects '${expected}'.`,
+          data: { resource: slot.resource, filePath: slot.filePath, path: slot.path },
+        });
+        continue;
+      }
+      // The type fits; do its ARGUMENTS agree? Covariant and gradual — an
+      // omitted argument is *any* in both directions, so an unmigrated producer
+      // or consumer is never reported, and only a definite conflict is.
+      const produced = celSourceSchemaByPath.get(slot.manifest)?.get(slot.path);
+      if (!produced) continue;
+      const { compatible, issues } = checkSchemaCompatibility(
+        produced,
+        slot.schema,
+        (ref: string) => defs.schemaForId(ref),
+      );
+      if (compatible) continue;
       diagnostics.push({
         severity: DiagnosticSeverity.Error,
-        code: "CEL_TYPE_ERROR",
+        code: "CEL_TYPE_ARGUMENT_MISMATCH",
         source: SOURCE,
-        message: `${slot.resource.kind}/${slot.resource.name}: CEL at '${slot.path}' returns '${type}' but the field expects '${expected}'.`,
+        message:
+          `${slot.resource.kind}/${slot.resource.name}: CEL at '${slot.path}' produces a value ` +
+          `whose type arguments disagree with the field's: ${issues.join("; ")}.`,
         data: { resource: slot.resource, filePath: slot.filePath, path: slot.path },
       });
     }

package/src/cel-environment.ts

@@ -3,10 +3,13 @@ import type { ResourceManifest } from "@telorun/sdk";
 import { jsonSchemaToCelType, VALUE_BRAND_BASE } from "./schema-compat.js";
 
 /** Transport protocol on a `ports` entry → the nominal CEL brand its resolved
- *  value carries. Mirrors the `protocol` enum in the Application schema. */
+ *  value carries. Mirrors the `protocol` enum in the Application schema, and
+ *  names the value types by their canonical `Telo.`-qualified names — the same
+ *  spelling an author writes at `x-telo-type`, so a branded port and a branded
+ *  field are comparable by name with nothing in between to translate. */
 const PORT_PROTOCOL_BRAND: Record<string, string> = {
-  tcp: "TcpPort",
-  udp: "UdpPort",
+  tcp: "Telo.TcpPort",
+  udp: "Telo.UdpPort",
 };
 
 export { buildCelEnvironment } from "@telorun/templating";

package/src/definition-registry.ts

@@ -127,6 +127,16 @@ export class DefinitionRegistry {
     return this.registeredSchemaIds.has(id) || this.ajv.getSchema(id) !== undefined;
   }
 
+  /** The schema registered under `id`, for a structural comparison that must see
+   *  THROUGH a named shape. Declaring a shape once and referencing it is the
+   *  sanctioned way to reuse one, so a comparator that cannot follow the
+   *  reference judges two opaque nodes and learns nothing. */
+  schemaForId(id: string): Record<string, any> | undefined {
+    const compiled = this.ajv.getSchema(id);
+    const schema = compiled?.schema;
+    return schema && typeof schema === "object" ? (schema as Record<string, any>) : undefined;
+  }
+
   /** Validates data against a schema using this registry's AJV instance, which has all
    *  registered definition schemas loaded — enabling cross-module $ref resolution.
    *  A compile failure returns `[]` here; it is surfaced loudly (once, on the

package/src/index.ts

@@ -62,12 +62,19 @@ export {
 export type { ContractDirection, DefResolver } from "./extends-resolution.js";
 export {
   defaultBearingPaths,
+  declaredScalarPaths,
   PERMISSIVE_CONTRACT,
   resolveContract,
   resolveContractSchema,
-  withStreamPropertiesSkipped,
+  withLiveValuesSkipped,
+} from "./invocation-contract.js";
+export type {
+  ContractOrigin,
+  ContractScope,
+  DeclaredScalarForm,
+  DeclaredScalarPath,
+  ResolvedContract,
 } from "./invocation-contract.js";
-export type { ContractOrigin, ContractScope, ResolvedContract } from "./invocation-contract.js";
 export {
   hasIntermediateWildcard,
   parseRedactionPath,
@@ -97,7 +104,18 @@ export {
   transfersControl,
 } from "./ref-slot.js";
 export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
-export { binaryKeyword, isBinarySlot, X_TELO_BINARY } from "./binary-slot.js";
+export {
+  ANNOTATION_KEYWORDS,
+  registerTeloKeywords,
+  valueTypeKeyword,
+} from "./value-type-keyword.js";
+export {
+  applyTextEdits,
+  isPlainSafe,
+  quoteStyleOf,
+  renderFixReplacement,
+} from "./yaml-source-edit.js";
+export type { QuoteStyle, TextEdit } from "./yaml-source-edit.js";
 export {
   hasProvidesZone,
   hasRequiresZone,
@@ -123,6 +141,10 @@ export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
 export type { ZoneSlotIssue } from "./validate-zone-slots.js";
 export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validate-ref-slots.js";
 export type { RefSlotIssue } from "./validate-ref-slots.js";
+export { validateValueTypeSlots } from "./validate-value-type-slots.js";
+export type { ValueTypeSlotIssue } from "./validate-value-type-slots.js";
+export { checkSchemaCompatibility, selectUnionBranch } from "./schema-compat.js";
+export type { CompatibilityResult } from "./schema-compat.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {
     CelSiteEvent,
@@ -139,6 +161,15 @@ export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";
 export { parseLoadedFile } from "./parse-loaded-file.js";
 export type { ParseOptions } from "./parse-loaded-file.js";
+export {
+  CORE_MIGRATIONS,
+  migrateFileText,
+  migrateManifests,
+  NO_MIGRATIONS,
+  parseMigrationEntry,
+  remapMigratedPaths,
+} from "./migrations/index.js";
+export type { FileMigrations, MigrationEntry, MigrationRewrite } from "./migrations/index.js";
 export { desugarLoadedFile, inlineImportManifests } from "./inline-imports.js";
 export type { SyntheticImport } from "./inline-imports.js";
 export {