@telorun/analyzer 0.42.0 → 0.43.0

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAoB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA8xB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA81BvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAmBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAqB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA8xB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAw2BvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAmBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -16,6 +16,7 @@ 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, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
+import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity } from "./types.js";
 import { extractCelRegionScopes, extractContextsFromSchema, getManifestItem, pathMatchesScope, resolveContextAnnotations, resolveTypeFieldToSchema, } from "./validate-cel-context.js";
 import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
@@ -1143,7 +1144,12 @@ export class StaticAnalyzer {
                 const celIssues = collectCelTypeIssues(m, schema, "", definition, m, baseTypedEnv, this.celEnv, moduleManifest);
                 // Phase 2+3: AJV on substituted data — CEL fields replaced with typed placeholders
                 const ajvIssues = validateAgainstSchema(substituteCelFields(m, schema), schema);
-                const issues = [...celIssues, ...ajvIssues];
+                // Phase 4: value slots that must satisfy a type declared elsewhere on
+                // the resource (`x-telo-value-schema-from`) — e.g. every row of a
+                // decision table against its declared `outputType`, so a mistyped branch
+                // is caught here rather than on the one input that selects it.
+                const valueSchemaIssues = collectValueSchemaIssues(m, schema, allManifests);
+                const issues = [...celIssues, ...ajvIssues, ...valueSchemaIssues];
                 for (const issue of issues) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
@@ -1178,7 +1184,7 @@ export class StaticAnalyzer {
                     }
                     const viaRoot = aliases.resolveKind(kind);
                     return viaRoot ? defs.resolve(viaRoot) : undefined;
-                }));
+                }, allManifests));
             }
             // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
         }

package/dist/reference-field-map.js

@@ -142,7 +142,7 @@ function traverseNode(node, path, map, root, visitedRefs = new Set()) {
     // the kernel's `runInvoke` emit-Invoked path. The walker fix and the
     // dispatcher fix need to land together — see the follow-up in
     // [kernel/nodejs/plans/reference-syntax-unification.md] and the
-    // stopgap in `resource-context.ts:resolveChildren`. `visitedRefs`
+    // stopgap in `resource-context.ts:ensureKindRef`. `visitedRefs`
     // stays as a parameter so the recursive calls below thread the right
     // signature; turning the descent back on is a single-branch change.
     if (typeof node?.$ref === "string")

package/dist/validate-nested-inline.d.ts

@@ -26,5 +26,7 @@ export interface InlineDefinitionLookup {
  * `rewriteSyntheticOrigins` reroutes those on inline-extracted (synthetic)
  * manifests back to the root doc.
  */
-export declare function validateNestedInlineResources(manifest: ResourceManifest, rootSchema: Record<string, any>, lookupDefinition: InlineDefinitionLookup): AnalysisDiagnostic[];
+export declare function validateNestedInlineResources(manifest: ResourceManifest, rootSchema: Record<string, any>, lookupDefinition: InlineDefinitionLookup, 
+/** Needed to resolve a `telo#Type` field a value slot is validated against. */
+allManifests?: Record<string, any>[]): AnalysisDiagnostic[];
 //# sourceMappingURL=validate-nested-inline.d.ts.map

package/dist/validate-nested-inline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-nested-inline.d.ts","sourceRoot":"","sources":["../src/validate-nested-inline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,gBAAgB,EAAE,sBAAsB,GACvC,kBAAkB,EAAE,CAoHtB"}
+{"version":3,"file":"validate-nested-inline.d.ts","sourceRoot":"","sources":["../src/validate-nested-inline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKzE,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,gBAAgB,EAAE,sBAAsB;AACxC,+EAA+E;AAC/E,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAO,GACvC,kBAAkB,EAAE,CA6HtB"}

package/dist/validate-nested-inline.js

@@ -1,6 +1,7 @@
 import { collectRefs, isInlineResource } from "./reference-field-map.js";
 import { collectProperties, resolveRef, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { DiagnosticSeverity } from "./types.js";
+import { collectValueSchemaIssues } from "./validate-value-schema.js";
 const SOURCE = "telo-analyzer";
 /**
  * Validates inline resources nested inside a resource body against their kind's
@@ -22,7 +23,9 @@ const SOURCE = "telo-analyzer";
  * `rewriteSyntheticOrigins` reroutes those on inline-extracted (synthetic)
  * manifests back to the root doc.
  */
-export function validateNestedInlineResources(manifest, rootSchema, lookupDefinition) {
+export function validateNestedInlineResources(manifest, rootSchema, lookupDefinition, 
+/** Needed to resolve a `telo#Type` field a value slot is validated against. */
+allManifests = []) {
     const diagnostics = [];
     const resource = { kind: manifest.kind, name: manifest.metadata?.name };
     const filePath = manifest.metadata?.source;
@@ -68,7 +71,16 @@ export function validateNestedInlineResources(manifest, rootSchema, lookupDefini
             : {};
         const data = { ...inline, metadata: { name: "__inline__", ...existingMeta } };
         const substituted = substituteCelFields(data, effectiveSchema, effectiveSchema);
-        for (const issue of validateAgainstSchema(substituted, effectiveSchema)) {
+        // The same two passes the top-level resource loop runs, so a kind's
+        // guarantees don't depend on whether the author wrote it standalone or
+        // inline (under a step's `invoke:`, or in a `with:` scope). `data` carries
+        // the synthesized metadata; `x-telo-value-schema-from` reads sibling fields
+        // off the resource, which are present either way.
+        const inlineIssues = [
+            ...validateAgainstSchema(substituted, effectiveSchema),
+            ...collectValueSchemaIssues(data, schema, allManifests),
+        ];
+        for (const issue of inlineIssues) {
             diagnostics.push({
                 severity: DiagnosticSeverity.Error,
                 code: "SCHEMA_VIOLATION",

package/dist/validate-value-schema.d.ts

@@ -0,0 +1,13 @@
+import { type SchemaIssue } from "./schema-compat.js";
+/**
+ * Validate every `x-telo-value-schema-from` slot in one resource.
+ *
+ * CEL leaves are replaced with schema-shaped placeholders before AJV runs
+ * (`substituteCelFields`), so an expression is accepted wherever its slot's
+ * declared type would be — a static pass cannot know what it evaluates to. What
+ * this DOES catch is structural disagreement that no runtime value can fix: a
+ * missing required property, an unknown property under
+ * `additionalProperties: false`, or a literal of the wrong type.
+ */
+export declare function collectValueSchemaIssues(manifest: Record<string, any>, defSchema: Record<string, any> | undefined, allManifests: Record<string, any>[]): SchemaIssue[];
+//# sourceMappingURL=validate-value-schema.d.ts.map

package/dist/validate-value-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-value-schema.d.ts","sourceRoot":"","sources":["../src/validate-value-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8C,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2FlG;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAC1C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,WAAW,EAAE,CAoBf"}

package/dist/validate-value-schema.js

@@ -0,0 +1,114 @@
+import { substituteCelFields, validateAgainstSchema } from "./schema-compat.js";
+import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+/**
+ * `x-telo-value-schema-from: "<field>"` — the value written at the annotated
+ * node must satisfy the type declared at the resource's `<field>`.
+ *
+ * The motivating shape is a kind with ONE declared output contract and SEVERAL
+ * places that must each produce it — a decision table's rows, a switch's arms.
+ * Only the branch that wins at runtime gets checked there, so a mistyped branch
+ * ships and fails on the one input that selects it. This annotation checks every
+ * branch statically instead.
+ *
+ * Generic and topology-driven: the analyzer hardcodes no kind. Any definition
+ * with a `telo#Type` field and value-producing slots opts in by annotating those
+ * slots. `<field>` is resolved with the same `telo#Type` semantics as
+ * `inputType` / `outputType` everywhere else, so an inline
+ * `{ kind: Type.JsonSchema, schema: … }` and a named type reference both work.
+ *
+ * A field that resolves to no schema — the common case of an optional
+ * `outputType` left undeclared — is skipped, not reported: declaring the
+ * contract is what opts into the check.
+ */
+const ANNOTATION = "x-telo-value-schema-from";
+/** Walk a definition schema collecting every `x-telo-value-schema-from`, in the
+ *  same scope form the CEL-context walker produces. */
+function collectAnnotations(schema, path) {
+    if (!schema || typeof schema !== "object")
+        return [];
+    const out = [];
+    const from = schema[ANNOTATION];
+    if (typeof from === "string" && from.length > 0)
+        out.push({ scope: path, from });
+    if (schema.properties) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+            out.push(...collectAnnotations(value, `${path}.${key}`));
+        }
+    }
+    if (schema.items && typeof schema.items === "object") {
+        out.push(...collectAnnotations(schema.items, `${path}[*]`));
+    }
+    for (const key of ["oneOf", "anyOf", "allOf"]) {
+        if (Array.isArray(schema[key])) {
+            for (const sub of schema[key])
+                out.push(...collectAnnotations(sub, path));
+        }
+    }
+    return out;
+}
+/** Expand a scope into the concrete values present in this manifest, carrying
+ *  each one's real path so a diagnostic points at the row the author wrote. */
+function resolveScopeValues(manifest, scope) {
+    const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
+    if (!stripped)
+        return [];
+    let frontier = [{ path: "", value: manifest }];
+    // Segments look like `choices[*]` or `default` — a name plus optional wildcard.
+    for (const segment of stripped.split(".")) {
+        const wildcard = segment.endsWith("[*]");
+        const name = wildcard ? segment.slice(0, -3) : segment;
+        const next = [];
+        for (const entry of frontier) {
+            const container = entry.value;
+            if (!container || typeof container !== "object")
+                continue;
+            const child = container[name];
+            if (child === undefined)
+                continue;
+            const childPath = entry.path ? `${entry.path}.${name}` : name;
+            if (!wildcard) {
+                next.push({ path: childPath, value: child });
+                continue;
+            }
+            if (!Array.isArray(child))
+                continue;
+            child.forEach((item, i) => next.push({ path: `${childPath}[${i}]`, value: item }));
+        }
+        frontier = next;
+        if (frontier.length === 0)
+            break;
+    }
+    return frontier;
+}
+/**
+ * Validate every `x-telo-value-schema-from` slot in one resource.
+ *
+ * CEL leaves are replaced with schema-shaped placeholders before AJV runs
+ * (`substituteCelFields`), so an expression is accepted wherever its slot's
+ * declared type would be — a static pass cannot know what it evaluates to. What
+ * this DOES catch is structural disagreement that no runtime value can fix: a
+ * missing required property, an unknown property under
+ * `additionalProperties: false`, or a literal of the wrong type.
+ */
+export function collectValueSchemaIssues(manifest, defSchema, allManifests) {
+    if (!defSchema)
+        return [];
+    const annotations = collectAnnotations(defSchema, "$");
+    if (annotations.length === 0)
+        return [];
+    const issues = [];
+    for (const { scope, from } of annotations) {
+        const target = resolveTypeFieldToSchema(manifest[from], allManifests);
+        if (!target || typeof target !== "object")
+            continue;
+        for (const { path, value } of resolveScopeValues(manifest, scope)) {
+            for (const issue of validateAgainstSchema(substituteCelFields(value, target), target)) {
+                issues.push({
+                    message: `\`${path}\` does not satisfy the type declared at \`${from}\`: ${issue.message}`,
+                    path: issue.path ? `${path}.${issue.path}` : path,
+                });
+            }
+        }
+    }
+    return issues;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -48,7 +48,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.50.0"
+    "@telorun/sdk": "0.54.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analyzer.ts

@@ -29,6 +29,7 @@ import {
   validateAgainstSchema,
   type SchemaIssue,
 } from "./schema-compat.js";
+import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
   extractCelRegionScopes,
@@ -1351,7 +1352,16 @@ export class StaticAnalyzer {
         );
         // Phase 2+3: AJV on substituted data — CEL fields replaced with typed placeholders
         const ajvIssues = validateAgainstSchema(substituteCelFields(m, schema), schema);
-        const issues = [...celIssues, ...ajvIssues];
+        // Phase 4: value slots that must satisfy a type declared elsewhere on
+        // the resource (`x-telo-value-schema-from`) — e.g. every row of a
+        // decision table against its declared `outputType`, so a mistyped branch
+        // is caught here rather than on the one input that selects it.
+        const valueSchemaIssues = collectValueSchemaIssues(
+          m as Record<string, any>,
+          schema,
+          allManifests as Record<string, any>[],
+        );
+        const issues = [...celIssues, ...ajvIssues, ...valueSchemaIssues];
         for (const issue of issues) {
           diagnostics.push({
             severity: DiagnosticSeverity.Error,
@@ -1390,6 +1400,7 @@ export class StaticAnalyzer {
               const viaRoot = aliases.resolveKind(kind);
               return viaRoot ? defs.resolve(viaRoot) : undefined;
             },
+            allManifests as Record<string, any>[],
           ),
         );
       }

package/src/reference-field-map.ts

@@ -210,7 +210,7 @@ function traverseNode(
   // the kernel's `runInvoke` emit-Invoked path. The walker fix and the
   // dispatcher fix need to land together — see the follow-up in
   // [kernel/nodejs/plans/reference-syntax-unification.md] and the
-  // stopgap in `resource-context.ts:resolveChildren`. `visitedRefs`
+  // stopgap in `resource-context.ts:ensureKindRef`. `visitedRefs`
   // stays as a parameter so the recursive calls below thread the right
   // signature; turning the descent back on is a single-branch change.
   if (typeof node?.$ref === "string") return;

package/src/validate-nested-inline.ts

@@ -7,6 +7,7 @@ import {
   validateAgainstSchema,
 } from "./schema-compat.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+import { collectValueSchemaIssues } from "./validate-value-schema.js";
 
 const SOURCE = "telo-analyzer";
 
@@ -39,6 +40,8 @@ export function validateNestedInlineResources(
   manifest: ResourceManifest,
   rootSchema: Record<string, any>,
   lookupDefinition: InlineDefinitionLookup,
+  /** Needed to resolve a `telo#Type` field a value slot is validated against. */
+  allManifests: Record<string, any>[] = [],
 ): AnalysisDiagnostic[] {
   const diagnostics: AnalysisDiagnostic[] = [];
   const resource = { kind: manifest.kind, name: manifest.metadata?.name as string };
@@ -87,7 +90,16 @@ export function validateNestedInlineResources(
         : {};
     const data = { ...inline, metadata: { name: "__inline__", ...existingMeta } };
     const substituted = substituteCelFields(data, effectiveSchema, effectiveSchema);
-    for (const issue of validateAgainstSchema(substituted, effectiveSchema)) {
+    // The same two passes the top-level resource loop runs, so a kind's
+    // guarantees don't depend on whether the author wrote it standalone or
+    // inline (under a step's `invoke:`, or in a `with:` scope). `data` carries
+    // the synthesized metadata; `x-telo-value-schema-from` reads sibling fields
+    // off the resource, which are present either way.
+    const inlineIssues = [
+      ...validateAgainstSchema(substituted, effectiveSchema),
+      ...collectValueSchemaIssues(data, schema, allManifests),
+    ];
+    for (const issue of inlineIssues) {
       diagnostics.push({
         severity: DiagnosticSeverity.Error,
         code: "SCHEMA_VIOLATION",

package/src/validate-value-schema.ts

@@ -0,0 +1,126 @@
+import { substituteCelFields, validateAgainstSchema, type SchemaIssue } from "./schema-compat.js";
+import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+
+/**
+ * `x-telo-value-schema-from: "<field>"` — the value written at the annotated
+ * node must satisfy the type declared at the resource's `<field>`.
+ *
+ * The motivating shape is a kind with ONE declared output contract and SEVERAL
+ * places that must each produce it — a decision table's rows, a switch's arms.
+ * Only the branch that wins at runtime gets checked there, so a mistyped branch
+ * ships and fails on the one input that selects it. This annotation checks every
+ * branch statically instead.
+ *
+ * Generic and topology-driven: the analyzer hardcodes no kind. Any definition
+ * with a `telo#Type` field and value-producing slots opts in by annotating those
+ * slots. `<field>` is resolved with the same `telo#Type` semantics as
+ * `inputType` / `outputType` everywhere else, so an inline
+ * `{ kind: Type.JsonSchema, schema: … }` and a named type reference both work.
+ *
+ * A field that resolves to no schema — the common case of an optional
+ * `outputType` left undeclared — is skipped, not reported: declaring the
+ * contract is what opts into the check.
+ */
+const ANNOTATION = "x-telo-value-schema-from";
+
+interface Annotation {
+  /** JSONPath-ish scope into the manifest, e.g. `$.choices[*].value`. */
+  scope: string;
+  /** Resource field naming the type to validate against, e.g. `outputType`. */
+  from: string;
+}
+
+/** Walk a definition schema collecting every `x-telo-value-schema-from`, in the
+ *  same scope form the CEL-context walker produces. */
+function collectAnnotations(schema: Record<string, any>, path: string): Annotation[] {
+  if (!schema || typeof schema !== "object") return [];
+  const out: Annotation[] = [];
+
+  const from = schema[ANNOTATION];
+  if (typeof from === "string" && from.length > 0) out.push({ scope: path, from });
+
+  if (schema.properties) {
+    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
+      out.push(...collectAnnotations(value, `${path}.${key}`));
+    }
+  }
+  if (schema.items && typeof schema.items === "object") {
+    out.push(...collectAnnotations(schema.items, `${path}[*]`));
+  }
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(schema[key])) {
+      for (const sub of schema[key]) out.push(...collectAnnotations(sub, path));
+    }
+  }
+  return out;
+}
+
+/** Expand a scope into the concrete values present in this manifest, carrying
+ *  each one's real path so a diagnostic points at the row the author wrote. */
+function resolveScopeValues(
+  manifest: Record<string, any>,
+  scope: string,
+): Array<{ path: string; value: unknown }> {
+  const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
+  if (!stripped) return [];
+
+  let frontier: Array<{ path: string; value: unknown }> = [{ path: "", value: manifest }];
+  // Segments look like `choices[*]` or `default` — a name plus optional wildcard.
+  for (const segment of stripped.split(".")) {
+    const wildcard = segment.endsWith("[*]");
+    const name = wildcard ? segment.slice(0, -3) : segment;
+    const next: Array<{ path: string; value: unknown }> = [];
+    for (const entry of frontier) {
+      const container = entry.value as Record<string, unknown> | undefined;
+      if (!container || typeof container !== "object") continue;
+      const child = container[name];
+      if (child === undefined) continue;
+      const childPath = entry.path ? `${entry.path}.${name}` : name;
+      if (!wildcard) {
+        next.push({ path: childPath, value: child });
+        continue;
+      }
+      if (!Array.isArray(child)) continue;
+      child.forEach((item, i) => next.push({ path: `${childPath}[${i}]`, value: item }));
+    }
+    frontier = next;
+    if (frontier.length === 0) break;
+  }
+  return frontier;
+}
+
+/**
+ * Validate every `x-telo-value-schema-from` slot in one resource.
+ *
+ * CEL leaves are replaced with schema-shaped placeholders before AJV runs
+ * (`substituteCelFields`), so an expression is accepted wherever its slot's
+ * declared type would be — a static pass cannot know what it evaluates to. What
+ * this DOES catch is structural disagreement that no runtime value can fix: a
+ * missing required property, an unknown property under
+ * `additionalProperties: false`, or a literal of the wrong type.
+ */
+export function collectValueSchemaIssues(
+  manifest: Record<string, any>,
+  defSchema: Record<string, any> | undefined,
+  allManifests: Record<string, any>[],
+): SchemaIssue[] {
+  if (!defSchema) return [];
+  const annotations = collectAnnotations(defSchema, "$");
+  if (annotations.length === 0) return [];
+
+  const issues: SchemaIssue[] = [];
+  for (const { scope, from } of annotations) {
+    const target = resolveTypeFieldToSchema(manifest[from], allManifests);
+    if (!target || typeof target !== "object") continue;
+
+    for (const { path, value } of resolveScopeValues(manifest, scope)) {
+      for (const issue of validateAgainstSchema(substituteCelFields(value, target), target)) {
+        issues.push({
+          message: `\`${path}\` does not satisfy the type declared at \`${from}\`: ${issue.message}`,
+          path: issue.path ? `${path}.${issue.path}` : path,
+        });
+      }
+    }
+  }
+  return issues;
+}