@telorun/analyzer 0.58.0 → 0.60.0

package/src/schema-compat.ts

@@ -3,7 +3,6 @@ import addFormats from "ajv-formats";
 import {
   isRefSentinel,
   isTaggedSentinel,
-  ManifestRootSchema,
   producedTypeOf,
 } from "@telorun/templating";
 import {
@@ -14,6 +13,7 @@ import {
   valueTypeOf,
   valueTypePlaceholder,
 } from "@telorun/sdk";
+import { ManifestRootSchema } from "./manifest-schemas.js";
 import { registerTeloKeywords } from "./value-type-keyword.js";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
@@ -48,6 +48,16 @@ export interface CompatibilityResult {
   issues: string[];
 }
 
+/** The alternatives a union node declares, or undefined when it is not one.
+ *  `anyOf` and `oneOf` are one question here — which branches could accept this
+ *  value — and their difference (exactly-one vs at-least-one) is a validation
+ *  rule, not a compatibility one. */
+function unionBranches(schema: Record<string, any>): Record<string, any>[] | undefined {
+  const branches = schema.anyOf ?? schema.oneOf;
+  if (!Array.isArray(branches) || branches.length === 0) return undefined;
+  return branches.filter((b) => b && typeof b === "object") as Record<string, any>[];
+}
+
 /**
  * Conservative structural JSON Schema compatibility check — is a value shaped
  * like `source` acceptable where `target` is declared?
@@ -115,6 +125,38 @@ function compare(
   const source = deref(rawSource, resolveRef);
   const target = deref(rawTarget, resolveRef);
 
+  // A union is ALTERNATIVES, so it is compared by distributing over branches on
+  // both sides: a definite conflict is one where no source-branch/target-branch
+  // pair agrees. Returning silently the moment either side was a union — which
+  // is what this did — switched the whole comparison off for any slot that
+  // accepts more than one shape, and those are exactly the slots where a value
+  // type carries the only information distinguishing the branches.
+  //
+  // `allOf` is a conjunction rather than a choice, so it keeps the old posture:
+  // it says too little to judge and stays compatible.
+  if (source.allOf || target.allOf) return;
+  const sourceBranches = unionBranches(source);
+  const targetBranches = unionBranches(target);
+  if (sourceBranches || targetBranches) {
+    const lefts = sourceBranches ?? [source];
+    const rights = targetBranches ?? [target];
+    const reasons: string[] = [];
+    for (const left of lefts) {
+      for (const right of rights) {
+        const probe: string[] = [];
+        // A fresh `seen` per probe: a pair rejected on one branch must not mark
+        // a reference pair visited for the next, which would silently pass it.
+        compare(left, right, path, probe, resolveRef, new Set(seen));
+        if (probe.length === 0) return;
+        reasons.push(...probe);
+      }
+    }
+    issues.push(
+      `${path || "/"}: no alternative matches — ${[...new Set(reasons)].join("; ")}`,
+    );
+    return;
+  }
+
   // Value types first: an `instance` representation has no JSON `type` to
   // compare, so its identity IS the comparison — and its arguments are where the
   // real information lives.
@@ -180,8 +222,6 @@ function compare(
     );
     return;
   }
-  if (source.anyOf || source.oneOf || source.allOf) return;
-  if (target.anyOf || target.oneOf || target.allOf) return;
 
   // An array's element, which the old comparison never looked at — so every
   // nested shape passed regardless of what it contained.
@@ -425,7 +465,14 @@ export function celTypeSatisfiesJsonSchema(celType: string, schema: Record<strin
     return true;
   }
   if (!schema.type && !schema.anyOf && !schema.oneOf && !schema.allOf) return true;
-  if (schema.anyOf || schema.oneOf || schema.allOf) return true;
+  // `allOf` is a conjunction and says too little to judge from a single CEL
+  // type. A union is a CHOICE, so it is satisfied by satisfying any branch —
+  // distributed for the same reason `compare` does it: accepting every union
+  // outright turns the check off for exactly the slots that admit more than one
+  // shape, and those are the ones where the branches carry the information.
+  if (schema.allOf) return true;
+  const branches = unionBranches(schema);
+  if (branches) return branches.some((branch) => celTypeSatisfiesJsonSchema(celType, branch));
   const schemaTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
   const accepted: Record<string, string[]> = {
     int: ["integer", "number"],
@@ -528,6 +575,23 @@ export function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown
   // member chosen is irrelevant — only its acceptability to AJV matters, since
   // the real value is checked at runtime once the expression resolves.
   if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
+  // A UNION with no `type` of its own. Without this, a whole-field CEL leaf at
+  // such a slot gets `null`, which every branch then rejects — so a field
+  // declared `anyOf: [array, boolean]` could not be written as an expression at
+  // all, while one whose union happens to contain a `live` branch escaped by
+  // accident (nothing validates a live value, so `null` passed). The first
+  // branch that yields a placeholder wins: the same conservative posture
+  // `selectUnionBranch` takes, and enough for AJV, whose question is only
+  // whether SOME branch accepts the stand-in.
+  if (schema.type === undefined) {
+    const branches = unionBranches(schema);
+    if (branches) {
+      for (const branch of branches) {
+        const candidate = celPlaceholderForSchema(branch);
+        if (candidate !== null) return candidate;
+      }
+    }
+  }
   switch (schema.type) {
     case "integer":
     case "number":
@@ -603,7 +667,7 @@ export function resolveRef(schema: Record<string, any>, root: Record<string, any
  * — an ambiguous union is one the analyzer should not resolve on the author's
  * behalf.
  */
-function selectUnionBranch(
+export function selectUnionBranch(
   schema: Record<string, any>,
   data: unknown,
   root: Record<string, any>,

package/src/validate-cel-context.ts

@@ -1,5 +1,10 @@
 export { extractAccessChains, validateChainAgainstSchema } from "@telorun/templating";
-import { mergeTypeSchemas, parseCanonicalTypeSchemaId } from "@telorun/sdk";
+import {
+  elementSchemaOf,
+  isLiveSlot,
+  mergeTypeSchemas,
+  parseCanonicalTypeSchemaId,
+} from "@telorun/sdk";
 import { KERNEL_BUILTINS } from "./builtins.js";
 
 export interface ContextResolveOpts {
@@ -206,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));
 }
 
 /**
@@ -342,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
@@ -445,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

@@ -9,7 +9,8 @@ import {
   validateAgainstSchema,
 } from "./schema-compat.js";
 import { plainChainOf } from "@telorun/templating";
-import { valueTypeOf } from "@telorun/sdk";
+import { isLiveSlot, valueTypeOf } from "@telorun/sdk";
+import { manifestFragmentOf } from "./manifest-schemas.js";
 import {
   analyzerContractScope,
   containerOf,
@@ -25,7 +26,7 @@ export interface StepInputIssue {
   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";
+  code?: "CEL_TYPE_ARGUMENT_MISMATCH" | "LIVE_VALUE_RETRIED";
 }
 
 
@@ -118,15 +119,30 @@ export function collectStepInputIssues(
       // 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) {
+      // The roots a plain chain may name here, each paired with the schema it is
+      // navigated against. `steps.` is the step map (analyzer state, supplied by
+      // the caller). `inputs.` is the ENCLOSING kind's own declared inputType,
+      // which is how a value produced OUTSIDE this resource reaches a step at
+      // all: an HTTP route maps `request.body` into its handler's inputs, and the
+      // handler forwards `inputs.body` onward — the shape a live value most often
+      // arrives in, and the one covering only `steps.` missed entirely. A root
+      // this cannot resolve contributes nothing rather than guessing at a schema.
+      const roots: Array<[string, Record<string, any>]> = [];
+      if (stepContext) roots.push(["steps.", stepContext]);
+      const ownContract = resolveContract(
+        "inputType",
+        manifest,
+        contractScope.resolveIn(manifest.kind as string, readingModule),
+        contractScope,
+      );
+      if (ownContract) roots.push(["inputs.", ownContract.schema]);
+
+      if (roots.length > 0) {
         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 root = chain ? roots.find(([prefix]) => chain.startsWith(prefix)) : undefined;
+          if (!chain || !root) continue;
+          const produced = navigateSchemaToExprPath(root[1], chain.slice(root[0].length));
           const slotSchema = (contract.schema.properties as Record<string, any> | undefined)?.[
             inputName
           ];
@@ -138,6 +154,28 @@ export function collectStepInputIssues(
           // 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.
+          // A LIVE value is consumed by reading, so it exists exactly once —
+          // that is what `live` says in the vocabulary, and re-attempting a
+          // dispatch that already read it re-sends nothing. Reported here rather
+          // than through a slot-specific annotation because both facts are
+          // already declared: the value's liveness by its value type, and the
+          // re-attempt by the retry policy. No kind is named.
+          if (isLiveSlot(produced)) {
+            const retry = declaredRetry(step, stepItemSchema, invokedManifest, invokedDef);
+            if (retry !== undefined) {
+              out.push({
+                path: `${stepPath}.${inputsField}.${inputName}`,
+                targetLabel: invokedName ?? invokedKind ?? "the invoked resource",
+                message:
+                  `'${inputName}' is a live value, which is consumed by reading and so exists ` +
+                  `once — but ${retry} re-attempts the dispatch, and a re-attempt would pass ` +
+                  `nothing. Collect it to a value first, or chunk the work so each attempt ` +
+                  `carries its own replayable piece.`,
+                code: "LIVE_VALUE_RETRIED",
+              });
+              continue;
+            }
+          }
           if (!valueTypeOf(produced) || !valueTypeOf(slotSchema)) continue;
           const { compatible, issues } = checkSchemaCompatibility(produced, slotSchema, (ref) =>
             defs.schemaForId(ref),
@@ -170,3 +208,65 @@ export function collectStepInputIssues(
   return out;
 }
 
+/**
+ * Where a re-attempt is declared for this dispatch, described for a diagnostic,
+ * or undefined when none is.
+ *
+ * A field declares one when its schema was expanded from a shared retry fragment
+ * — the shape the author pointed at, rather than a marker they had to remember to
+ * write beside it. Which fragment also says WHERE the budget is, so the two
+ * spellings a kind may carry (a policy object, or the deprecated bare count) need
+ * no guessing between them and no rule about which one wins.
+ *
+ * Two sites are consulted because there are two real ones: the STEP's own policy
+ * — `retry` on the kernel-owned dispatch site — and the TARGET's, a field on an
+ * arbitrary kind, because `Http.Request` re-attempts inside its own `invoke()`
+ * where only it can tell a 429 from a 500. A live value is equally doomed by
+ * either. EVERY retry-bearing field at a site is checked, not the first, since
+ * `Http.Request` carries both spellings and property order must not decide which
+ * is seen.
+ *
+ * Only a STATICALLY KNOWN non-zero budget counts. An `attempts` written as CEL
+ * says nothing here, and guessing would report a conflict against a manifest that
+ * may never retry — the same posture the `use` case-map selector takes.
+ */
+function declaredRetry(
+  step: Record<string, any>,
+  stepItemSchema: Record<string, any> | undefined,
+  invokedManifest: Record<string, any> | undefined,
+  invokedDef: Record<string, any> | undefined,
+): string | undefined {
+  for (const [field, budget] of retryFields(stepItemSchema)) {
+    if (budget(step?.[field]) > 0) return `the step's \`${field}\``;
+  }
+  for (const [field, budget] of retryFields(invokedDef?.schema as Record<string, any>)) {
+    if (budget(invokedManifest?.[field]) > 0) return `the target's \`${field}\``;
+  }
+  return undefined;
+}
+
+/** How each shared retry fragment carries its budget. Keyed on fragment name —
+ *  the analyzer's own built-ins, never a module's kind — so a kind that adopts a
+ *  shape is covered without naming it here. */
+const RETRY_BUDGET: Record<string, (value: unknown) => number> = {
+  RetryPolicy: (value) => {
+    if (!value || typeof value !== "object") return 0;
+    const attempts = (value as Record<string, unknown>).attempts;
+    return typeof attempts === "number" ? attempts : 0;
+  },
+  RetryAttempts: (value) => (typeof value === "number" ? value : 0),
+};
+
+/** Every property of `schema` whose shape came from a retry fragment, paired with
+ *  the reader for that fragment's budget. */
+function retryFields(
+  schema: Record<string, any> | undefined,
+): Array<[string, (value: unknown) => number]> {
+  if (!schema) return [];
+  const out: Array<[string, (value: unknown) => number]> = [];
+  for (const [key, sub] of gatherPropertySchemas(schema)) {
+    const budget = RETRY_BUDGET[manifestFragmentOf(sub) ?? ""];
+    if (budget) out.push([key, budget]);
+  }
+  return out;
+}