@telorun/analyzer 0.47.0 → 0.49.0

package/src/index.ts

@@ -38,15 +38,27 @@ export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolve
 export type { ModuleScopes } from "./alias-resolver.js";
 export {
   ancestorChain,
+  contractDeclarer,
   controllerBearingAncestor,
   effectiveAuthorSchema,
+  effectiveContractField,
   effectiveStatusSchema,
   hasOwnControllerOrTemplate,
   inheritedCapability,
   isInheritedDelegation,
+  mappingFieldFor,
+  needsContractMapping,
   resolveParent,
 } from "./extends-resolution.js";
-export type { DefResolver } from "./extends-resolution.js";
+export type { ContractDirection, DefResolver } from "./extends-resolution.js";
+export {
+  defaultBearingPaths,
+  PERMISSIVE_CONTRACT,
+  resolveContract,
+  resolveContractSchema,
+  withStreamPropertiesSkipped,
+} from "./invocation-contract.js";
+export type { ContractOrigin, ContractScope, ResolvedContract } from "./invocation-contract.js";
 export {
   hasIntermediateWildcard,
   parseRedactionPath,
@@ -120,6 +132,31 @@ export {
   urlManifestCacheCoords,
 } from "./sources/manifest-cache.js";
 export type { ManifestCacheCoords } from "./sources/manifest-cache.js";
+export {
+  LAYER_ROLES,
+  PLATFORM_AXES,
+  ArtifactSelectorError,
+  describeSelector,
+  isLayerRole,
+  normalizeSelector,
+  selectorFromQualifiers,
+  selectorKey,
+  selectorMatches,
+} from "./artifact-selector.js";
+export type {
+  ArtifactSelector,
+  LayerRole,
+  PlatformAxis,
+  PlatformTarget,
+} from "./artifact-selector.js";
+export {
+  LayerIndexError,
+  matchControllerLayers,
+  parseLayerIndex,
+  singletonLayer,
+} from "./artifact-layer-index.js";
+export type { ArtifactLayer } from "./artifact-layer-index.js";
+export { validateModuleArtifact } from "./validate-module-artifact.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";

package/src/invocation-contract.ts

@@ -0,0 +1,275 @@
+import type { ResourceDefinition } from "@telorun/sdk";
+import {
+  type ContractDirection,
+  contractDeclarer,
+  type DefResolver,
+  effectiveContractField,
+} from "./extends-resolution.js";
+import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+
+export type { ContractDirection };
+
+/**
+ * The one answer to "what is this target's input / output schema".
+ *
+ * Both halves of Telo consume it: `telo check` validates call sites against it,
+ * and the kernel binds it to the instance at creation. It lives here rather than
+ * in the kernel because it must be browser-safe and because a second
+ * implementation would drift — the same split already used for
+ * `buildEvalPaths` / `evalPathCovers` and the redaction path parser. Before this
+ * there were three one-hop lookups (the analysis registry's editor helpers, the
+ * template-body `inputs` typing, the step-context definition fallback) and a
+ * runtime that consulted only an explicitly-passed type ref, so static analysis
+ * and dispatch could disagree about the very contract they were both checking.
+ */
+
+/** Where a resolved contract was declared. Instance-level declarations let one
+ *  call site narrow a kind's contract (`JS.Script` does this); kind-level ones
+ *  are the kind's own signature. */
+export type ContractOrigin = "instance" | "kind";
+
+export interface ResolvedContract {
+  /** The JSON Schema a value is validated against. */
+  schema: Record<string, any>;
+  origin: ContractOrigin;
+  /** The definition that declared it, when `origin` is `"kind"` — the scope its
+   *  named type references resolved in, and what a diagnostic should name. */
+  declaredBy?: ResourceDefinition;
+}
+
+export interface ContractScope {
+  /** Resolves a kind to its definition. Must be scoped to the module that
+   *  DECLARED the definition being walked — `extends` aliases are lexical, so a
+   *  chain crossing module boundaries re-scopes at each hop. */
+  resolveDefinition: DefResolver;
+  /**
+   * Manifests a named `telo#Type` reference resolves against, given the
+   * definition that DECLARED the type field.
+   *
+   * The parameter exists for a caller that keeps types per module. The analyzer
+   * does not: it works from one flattened list where names are already unique
+   * per module, so it ignores the argument and returns that list. A caller
+   * holding several scopes uses it to avoid resolving a bare name against the
+   * wrong module's type of the same name.
+   */
+  typeManifestsFor(def: ResourceDefinition | undefined): Record<string, any>[];
+}
+
+/** The fallback for a target that declares no contract: anything goes. Not
+ *  `additionalProperties: false` — an undeclared contract is an absence of a
+ *  claim, not a claim of emptiness. */
+export const PERMISSIVE_CONTRACT: Record<string, any> = {
+  type: "object",
+  additionalProperties: true,
+};
+
+/**
+ * Resolve a dispatch target's contract, layering:
+ *   1. the **instance manifest's** own `inputType:` / `outputType:` — per-call-site
+ *      narrowing, opted into simply by the kind declaring the property;
+ *   2. the **kind's** contract, resolved to the nearest declaration along
+ *      `extends` (see {@link effectiveContractField} — nearest wins, no merge);
+ *   3. undefined — the caller decides whether that means permissive.
+ *
+ * Returns undefined rather than {@link PERMISSIVE_CONTRACT} so a caller can tell
+ * "declared nothing" from "declared anything", which the wiring rule and the
+ * `run()` guard both need.
+ */
+export function resolveContract(
+  direction: ContractDirection,
+  manifest: Record<string, any> | undefined,
+  definition: ResourceDefinition | undefined,
+  scope: ContractScope,
+): ResolvedContract | undefined {
+  const own = manifest?.[direction];
+  if (own !== undefined && own !== null) {
+    const schema = resolveTypeFieldToSchema(own, scope.typeManifestsFor(definition));
+    if (schema) return { schema, origin: "instance" };
+  }
+
+  const declared = effectiveContractField(definition, scope.resolveDefinition, direction);
+  if (declared === undefined || declared === null) return undefined;
+  const declarer = contractDeclarer(definition, scope.resolveDefinition, direction);
+  const schema = resolveTypeFieldToSchema(declared, scope.typeManifestsFor(declarer));
+  if (!schema) return undefined;
+  return { schema, origin: "kind", declaredBy: declarer };
+}
+
+/** {@link resolveContract}, falling back to {@link PERMISSIVE_CONTRACT}. For
+ *  callers that need a schema unconditionally (CEL context typing), as opposed
+ *  to needing to know whether one was declared. */
+export function resolveContractSchema(
+  direction: ContractDirection,
+  manifest: Record<string, any> | undefined,
+  definition: ResourceDefinition | undefined,
+  scope: ContractScope,
+): Record<string, any> {
+  return resolveContract(direction, manifest, definition, scope)?.schema ?? PERMISSIVE_CONTRACT;
+}
+
+/**
+ * A copy of `schema` with every `x-telo-stream`-marked property removed from
+ * `properties` and `required`, for validating a runtime value against.
+ *
+ * Streams travel in BOTH directions — `Codec.Encoder` marks `input` on its
+ * `inputType` and lists it in `required`, and `Record.Stream`, `Ai`, `Tar` and
+ * `Console` do the same — so a one-directional skip would walk a live `Stream`
+ * with AJV on the hottest path in the runtime. That is the same defect as
+ * `stripCompiledValues` walking a live `ResourceInstance` in a ref slot: a live
+ * object in a declared slot is not data to be traversed. The annotation already
+ * marks exactly the properties to leave alone.
+ *
+ * Structural (returns a new object, never mutates), and shared so the analyzer
+ * and the kernel exempt the same set.
+ */
+export function withStreamPropertiesSkipped(
+  schema: Record<string, any>,
+  /** Resolves a `$ref` to the schema it names. Required to see through the
+   *  reference form the runtime deliberately KEEPS intact for its validator: a
+   *  contract written as `{ $ref: "telo:mod/Type" }` has none of its own
+   *  properties, so a walk that cannot follow the reference exempts nothing and
+   *  the stream is traversed after all. */
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
+): Record<string, any> {
+  return stripStreams(schema, [], resolveRef);
+}
+
+function stripStreams(
+  node: unknown,
+  // A PATH-scoped guard, not a global memo: a schema object reached twice from
+  // different parents must be stripped twice (a global `seen` would hand the
+  // second parent the unstripped original), while a cycle must still terminate.
+  path: readonly object[],
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
+): any {
+  if (Array.isArray(node)) {
+    let changed = false;
+    const items = node.map((item) => {
+      const next = stripStreams(item, path, resolveRef);
+      if (next !== item) changed = true;
+      return next;
+    });
+    return changed ? items : node;
+  }
+  if (!node || typeof node !== "object") return node;
+  let schema = node as Record<string, any>;
+  if (path.includes(schema)) return schema;
+
+  // Follow a whole-document reference to SEE the annotations behind it, but
+  // return the original node when nothing behind it was stripped. Substituting
+  // the resolved target unconditionally would break schema identity — the
+  // compiled-validator cache is keyed on it — and would move the target out of
+  // the document whose `$defs` its own internal `$ref`s resolve against.
+  if (resolveRef && typeof schema.$ref === "string") {
+    const target = resolveRef(schema.$ref);
+    if (target && !path.includes(target)) {
+      const stripped = stripStreams(target, [...path, schema], resolveRef);
+      if (stripped === target) return node;
+      const { $ref: _ref, ...siblings } = schema;
+      return Object.keys(siblings).length > 0 ? { ...stripped, ...siblings } : stripped;
+    }
+  }
+  const here = [...path, schema];
+
+  let out: Record<string, any> = schema;
+  const properties = schema.properties as Record<string, any> | undefined;
+  if (properties) {
+    // A stream can be contributed by an `allOf` branch too (how type inheritance
+    // is expressed before the branches are merged), so the marked set is read
+    // from the folded view while the removal is applied here.
+    const streamed = Object.keys(properties).filter(
+      (key) => (properties[key] as Record<string, any> | undefined)?.["x-telo-stream"],
+    );
+    if (streamed.length > 0) {
+      const kept: Record<string, any> = {};
+      for (const [key, value] of Object.entries(properties)) {
+        if (!streamed.includes(key)) kept[key] = value;
+      }
+      // The key stays DECLARED but unconstrained, rather than being deleted.
+      // Deleting it would force `additionalProperties: false` open, and a closed
+      // contract would stop rejecting unknown keys the moment it grew a stream —
+      // trading one exemption for a hole across the whole shape.
+      for (const key of streamed) kept[key] = {};
+      out = { ...schema, properties: kept };
+    }
+  }
+
+  // Recurse: a stream one level down (an item, a branch, a nested object) is as
+  // live as one at the root, and walking it with AJV is the same defect.
+  //
+  // `properties` and `$defs` are MAPS of schemas, not schemas — descending into
+  // them as if they were would visit nothing, since a map has none of the
+  // keywords this walk looks for.
+  let changed = out !== schema;
+  const result: Record<string, any> = { ...out };
+  for (const key of ["properties", "$defs"] as const) {
+    const map = out[key] as Record<string, any> | undefined;
+    if (!map || typeof map !== "object") continue;
+    let mapChanged = false;
+    const next: Record<string, any> = {};
+    for (const [name, child] of Object.entries(map)) {
+      const stripped = stripStreams(child, here, resolveRef);
+      if (stripped !== child) mapChanged = true;
+      next[name] = stripped;
+    }
+    if (mapChanged) {
+      result[key] = next;
+      changed = true;
+    }
+  }
+  for (const key of ["items", "allOf", "anyOf", "oneOf"] as const) {
+    const child = out[key];
+    if (child === undefined) continue;
+    const next = stripStreams(child, here, resolveRef);
+    if (next !== child) {
+      result[key] = next;
+      changed = true;
+    }
+  }
+  return changed ? result : schema;
+}
+
+/** Every property path in `schema` that can receive a `default:` — the paths a
+ *  defaults pass may write to, and therefore exactly how far the caller's inputs
+ *  must be copied before AJV's `useDefaults` runs. A flat shallow copy would not
+ *  do: `useDefaults` writes at every level it finds a default, so a nested
+ *  default would mutate the structure the caller still holds. Bounded by the
+ *  schema's defaults rather than by the size of the payload. */
+export function defaultBearingPaths(
+  schema: Record<string, any>,
+  /** See {@link withStreamPropertiesSkipped} — a contract kept in `$ref` form
+   *  declares its defaults behind the reference, and a walk that cannot follow
+   *  it would report none, leaving the caller's data shared where a fill lands. */
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
+): string[][] {
+  const out: string[][] = [];
+
+  // Path-scoped, for the same reason as the stream walk: a shared subschema
+  // reached from two parents contributes a path under each.
+  const walk = (node: unknown, path: string[], chain: readonly object[]): void => {
+    if (!node || typeof node !== "object") return;
+    let s = node as Record<string, any>;
+    if (chain.includes(s)) return;
+    if (resolveRef && typeof s.$ref === "string") {
+      const target = resolveRef(s.$ref);
+      if (!target || chain.includes(target)) return;
+      s = { ...target, ...s, $ref: undefined };
+    }
+    const here = [...chain, node as object];
+
+    if ("default" in s && path.length > 0) out.push(path);
+
+    const properties = s.properties as Record<string, any> | undefined;
+    if (properties) {
+      for (const [key, child] of Object.entries(properties)) walk(child, [...path, key], here);
+    }
+    for (const branch of ["allOf", "anyOf", "oneOf"] as const) {
+      const list = s[branch];
+      if (Array.isArray(list)) for (const child of list) walk(child, path, here);
+    }
+    if (s.items) walk(s.items, [...path, "[]"], here);
+  };
+
+  walk(schema, [], []);
+  return out;
+}

package/src/schema-compat.ts

@@ -306,7 +306,71 @@ export function celTypeSatisfiesJsonSchema(celType: string, schema: Record<strin
 }
 
 /** Return a literal placeholder value of the correct schema type for AJV. */
-export function celPlaceholderForSchema(schema: Record<string, any>): unknown {
+/** A number inside the schema's declared bounds. The placeholder stands in for a
+ *  value only known at runtime, so its single job is to be ACCEPTABLE — a bare 0
+ *  into an `exclusiveMinimum: 0` field (a scale, a positive dimension) would
+ *  report a violation against a value the author never wrote. Bounds are read in
+ *  the order that pins the value: an inclusive minimum is usable as-is, an
+ *  exclusive one needs a step past it, and a wholly-negative range needs the
+ *  maximum end instead. */
+function numericPlaceholder(schema: Record<string, any>): number {
+  const isInteger = schema.type === "integer";
+  // One step past an exclusive bound. Integral for both `integer` and `number`:
+  // any value inside the band will do, and a whole number is inside it whenever
+  // a fractional one is (the narrow-band case below handles when it is not).
+  const step = 1;
+  if (typeof schema.minimum === "number") return schema.minimum;
+  if (typeof schema.exclusiveMinimum === "number") {
+    const candidate = schema.exclusiveMinimum + step;
+    if (typeof schema.maximum === "number" && candidate > schema.maximum) {
+      // A narrow band (0 < x <= 0.5) has no integral step; take the midpoint,
+      // which the band's own definition guarantees is inside it.
+      return isInteger ? schema.maximum : (schema.exclusiveMinimum + schema.maximum) / 2;
+    }
+    return candidate;
+  }
+  if (typeof schema.maximum === "number" && schema.maximum < 0) return schema.maximum;
+  if (typeof schema.exclusiveMaximum === "number" && schema.exclusiveMaximum <= 0) {
+    return schema.exclusiveMaximum - step;
+  }
+  return 0;
+}
+
+/** The constraints a placeholder must satisfy, folded across `allOf` branches.
+ *  Inheritance between types is expressed by intersecting `allOf`, so a bound a
+ *  parent declared lives in a branch rather than on the property itself — a
+ *  placeholder that reads only the top level would violate it and report against
+ *  a value the author never wrote. The tightest bound wins, which is what the
+ *  intersection means. */
+function foldedConstraints(schema: Record<string, any>): Record<string, any> {
+  const branches = Array.isArray(schema.allOf) ? (schema.allOf as Record<string, any>[]) : [];
+  if (branches.length === 0) return schema;
+  const out: Record<string, any> = { ...schema };
+  for (const branch of branches) {
+    const folded = foldedConstraints(branch);
+    for (const key of ["minimum", "exclusiveMinimum", "minLength", "minItems"] as const) {
+      if (typeof folded[key] === "number" && (typeof out[key] !== "number" || folded[key] > out[key])) {
+        out[key] = folded[key];
+      }
+    }
+    for (const key of ["maximum", "exclusiveMaximum"] as const) {
+      if (typeof folded[key] === "number" && (typeof out[key] !== "number" || folded[key] < out[key])) {
+        out[key] = folded[key];
+      }
+    }
+    if (out.type === undefined && folded.type !== undefined) out.type = folded.type;
+    if (out.enum === undefined && folded.enum !== undefined) out.enum = folded.enum;
+    if (out.default === undefined && folded.default !== undefined) out.default = folded.default;
+    if (folded.required) {
+      out.required = [...new Set([...(out.required ?? []), ...folded.required])];
+    }
+    if (folded.properties) out.properties = { ...folded.properties, ...(out.properties ?? {}) };
+  }
+  return out;
+}
+
+export function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown {
+  const schema = foldedConstraints(rawSchema);
   if (schema.default !== undefined) return schema.default;
   // An enum-constrained field needs a placeholder drawn from the enum: the
   // type-based fallbacks below ("" for a string, 0 for a number) satisfy `type`
@@ -318,20 +382,49 @@ export function celPlaceholderForSchema(schema: Record<string, any>): unknown {
   switch (schema.type) {
     case "integer":
     case "number":
-      return schema.minimum ?? 0;
+      return numericPlaceholder(schema);
     case "string":
-      return "";
+      // `minLength` is the string analogue of `minimum`: a bare "" into a
+      // `minLength: 1` field would report a violation against a value the author
+      // never wrote. Any string of the right length will do.
+      return typeof schema.minLength === "number" && schema.minLength > 0
+        ? "x".repeat(schema.minLength)
+        : "";
     case "boolean":
       return false;
     case "array":
-      return [];
+      // `minItems` is the array analogue of `minimum` / `minLength`: an empty
+      // array into a `minItems: 1` field would report a violation against a
+      // value the author never wrote.
+      return typeof schema.minItems === "number" && schema.minItems > 0
+        ? Array.from({ length: schema.minItems }, () =>
+            celPlaceholderForSchema((schema.items ?? {}) as Record<string, any>),
+          )
+        : [];
     case "object":
-      return {};
+      return objectPlaceholder(schema);
     default:
       return null;
   }
 }
 
+/** An object satisfying the schema's `required` list. A bare `{}` would report
+ *  every required property as missing against a value the author never wrote —
+ *  the case where a whole map is produced by one expression (`inputs: !cel
+ *  "buildRequest(...)"`), which is exactly when the analyzer knows least and
+ *  should say least. Members are filled recursively by the same rule, so a
+ *  required nested object is satisfied too. */
+function objectPlaceholder(schema: Record<string, any>): Record<string, unknown> {
+  const required = Array.isArray(schema.required) ? (schema.required as string[]) : [];
+  if (required.length === 0) return {};
+  const properties = (schema.properties ?? {}) as Record<string, Record<string, any>>;
+  const out: Record<string, unknown> = {};
+  for (const key of required) {
+    out[key] = celPlaceholderForSchema(properties[key] ?? {});
+  }
+  return out;
+}
+
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 
 /** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
@@ -345,8 +438,76 @@ export function resolveRef(schema: Record<string, any>, root: Record<string, any
 }
 
 /** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
+/**
+ * The `oneOf` / `anyOf` branch a value is written against, when exactly one fits.
+ *
+ * A union carries no `type` / `properties` / `items` of its own, so a walker that
+ * ignores it descends with an empty schema and hands every CEL leaf underneath a
+ * `null` placeholder — which then fails every branch and reports a pile of
+ * violations against a value that is perfectly valid. Picking the branch first
+ * is what lets the leaves be typed.
+ *
+ * Selection is structural and conservative: a branch must agree with the data's
+ * kind, and for an object every `required` key must be present (which is what
+ * separates a `{type, text}` part from a `{type, data, mediaType}` one). If that
+ * leaves anything other than exactly one branch, the union is returned unchanged
+ * — an ambiguous union is one the analyzer should not resolve on the author's
+ * behalf.
+ */
+function selectUnionBranch(
+  schema: Record<string, any>,
+  data: unknown,
+  root: Record<string, any>,
+): Record<string, any> {
+  const branches = (schema.oneOf ?? schema.anyOf) as Record<string, any>[] | undefined;
+  if (!Array.isArray(branches) || branches.length === 0) return schema;
+  if (schema.type !== undefined || schema.properties !== undefined) return schema;
+
+  const kind = Array.isArray(data)
+    ? "array"
+    : data === null
+      ? "null"
+      : typeof data === "object"
+        ? "object"
+        : typeof data === "string"
+          ? "string"
+          : typeof data === "number"
+            ? "number"
+            : typeof data === "boolean"
+              ? "boolean"
+              : undefined;
+  if (!kind) return schema;
+
+  const fits = branches
+    .map((b) => resolveRef(b, root))
+    .filter((b) => {
+      const types = Array.isArray(b.type) ? b.type : b.type ? [b.type] : [];
+      if (types.length > 0 && !types.includes(kind)) return false;
+      if (kind === "object" && Array.isArray(b.required)) {
+        const keys = Object.keys(data as Record<string, unknown>);
+        if (!(b.required as string[]).every((r) => keys.includes(r))) return false;
+      }
+      return true;
+    });
+  return fits.length === 1 ? fits[0]! : schema;
+}
+
 export function collectProperties(schema: Record<string, any>): Record<string, any> {
   const props: Record<string, any> = { ...(schema.properties ?? {}) };
+  // `allOf` INTERSECTS, so a branch constraining a property constrains the
+  // property itself — type inheritance expresses an inherited bound exactly this
+  // way (`allOf: [{ properties: { score: { minimum: 10 } } }]`). Merging the
+  // branch's constraints into the property is what lets a placeholder for that
+  // property be built from the bound the value must actually satisfy; reading
+  // only the top level would produce one that violates it.
+  for (const sub of (schema.allOf ?? []) as Record<string, any>[]) {
+    if (!sub || typeof sub !== "object" || !sub.properties) continue;
+    for (const [k, v] of Object.entries(sub.properties as Record<string, any>)) {
+      props[k] = k in props ? { ...(props[k] as object), ...(v as object) } : v;
+    }
+  }
+  // `oneOf` / `anyOf` are alternatives, not constraints: a property seen in one
+  // branch is contributed only when no branch already declared it.
   for (const sub of schema.oneOf ?? schema.anyOf ?? []) {
     if (sub && typeof sub === "object" && sub.properties) {
       for (const [k, v] of Object.entries(sub.properties as Record<string, any>)) {
@@ -363,11 +524,24 @@ export function substituteCelFields(
   data: unknown,
   schema: Record<string, any>,
   rootSchema?: Record<string, any>,
+  /** Called with the dotted path of every value replaced by a placeholder.
+   *
+   *  A placeholder is a stand-in for something only known at runtime, so its
+   *  VALUE says nothing: a caller that judges constraints at these paths reports
+   *  against a value no author wrote. Some constraints cannot be satisfied by
+   *  construction at all (`pattern`, `format`, a `oneOf` of unrelated shapes),
+   *  so making every placeholder acceptable is not achievable in general —
+   *  knowing where not to look is. Structural findings survive because they are
+   *  located at the CONTAINER, not at the substituted leaf. */
+  onSubstitute?: (path: string) => void,
+  path = "",
 ): unknown {
   const root = rootSchema ?? schema;
-  const resolved = resolveRef(schema, root);
+  const resolved = selectUnionBranch(resolveRef(schema, root), data, root);
+  const mark = () => onSubstitute?.(path);
 
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
+    mark();
     return celPlaceholderForSchema(resolved);
   }
   // `!ref <name>` sentinels are identity markers, not runtime values —
@@ -381,11 +555,14 @@ export function substituteCelFields(
     return data;
   }
   if (isTaggedSentinel(data)) {
+    mark();
     return celPlaceholderForSchema(resolved);
   }
   if (Array.isArray(data)) {
     const itemSchema = resolveRef((resolved.items ?? {}) as Record<string, any>, root);
-    return data.map((item) => substituteCelFields(item, itemSchema, root));
+    return data.map((item, i) =>
+      substituteCelFields(item, itemSchema, root, onSubstitute, `${path}[${i}]`),
+    );
   }
   if (data !== null && typeof data === "object") {
     const props = collectProperties(resolved);
@@ -395,7 +572,13 @@ export function substituteCelFields(
         : undefined;
     const result: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
-      result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}) as Record<string, any>, root);
+      result[k] = substituteCelFields(
+        v,
+        (props[k] ?? addlProps ?? {}) as Record<string, any>,
+        root,
+        onSubstitute,
+        path ? `${path}.${k}` : k,
+      );
     }
     return result;
   }

package/src/validate-base-mapping.ts

@@ -92,6 +92,16 @@ interface CheckCtx {
   filePath: string | undefined;
 }
 
+/** Keys the inherited controller supplies itself when it builds the parent
+ *  manifest (`{ kind, metadata, ...base }`), so `base:` neither has to set them
+ *  nor may. Without this exclusion a parent whose schema lists `metadata` in
+ *  `required` — `JS.Script` does, the most natural parent for a remapping child —
+ *  is unusable: omitting it is BASE_MISSING_REQUIRED and setting it is
+ *  BASE_UNKNOWN_FIELD, since `metadata` is required but never a declared
+ *  property. Only at the top level; a nested `metadata` field is the parent's
+ *  own and is checked normally. */
+const CONTROLLER_SUPPLIED_KEYS = new Set(["kind", "metadata"]);
+
 function checkObject(
   value: Record<string, unknown>,
   schema: Record<string, any>,
@@ -99,7 +109,10 @@ function checkObject(
   ctx: CheckCtx,
 ): void {
   const properties = (schema.properties ?? {}) as Record<string, Record<string, any>>;
-  const required = Array.isArray(schema.required) ? (schema.required as string[]) : [];
+  const isRoot = path === "base";
+  const required = (Array.isArray(schema.required) ? (schema.required as string[]) : []).filter(
+    (name) => !(isRoot && CONTROLLER_SUPPLIED_KEYS.has(name)),
+  );
   const additionalFalse = schema.additionalProperties === false;
 
   for (const req of required) {