@telorun/analyzer 0.1.1

package/src/normalize-inline-resources.ts

@@ -0,0 +1,170 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefEntry, isScopeEntry, isInlineResource } from "./reference-field-map.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import type { AliasResolver } from "./alias-resolver.js";
+
+const SYSTEM_KINDS = new Set(["Kernel.Definition", "Kernel.Module", "Kernel.Import"]);
+
+/** Replaces characters outside [a-zA-Z0-9_] with underscores. */
+function sanitizeName(raw: string): string {
+  return raw.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+/**
+ * Phase 2 — Inline resource normalization.
+ *
+ * After all manifests and definitions are loaded, walks every non-system resource's
+ * x-telo-ref slots. For each inline resource value (has keys beyond kind/name/metadata),
+ * assigns a deterministic name, extracts it as a first-class manifest, and replaces
+ * the inline value in-place with `{kind, name}`. Newly extracted resources are enqueued
+ * so nested inlines are resolved in the same pass.
+ *
+ * Naming scheme:
+ *   {parentName}_{pathSegment}[_{itemName|index}]_{fieldName}
+ *   e.g. TestBasicAddition_steps_AddTwoNumbers_invoke
+ *        TestBasicAddition_steps_0_invoke  (when step has no name)
+ *
+ * Returns a new array containing the original manifests (mutated in-place) plus all
+ * extracted manifests. The original array is not mutated.
+ */
+export function normalizeInlineResources(
+  resources: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases?: AliasResolver,
+): ResourceManifest[] {
+  const result = [...resources];
+
+  // Queue: all non-system resources with a name. Extracted resources are appended.
+  const queue = resources.filter(
+    (r): r is ResourceManifest & { metadata: { name: string } } =>
+      typeof r.metadata?.name === "string" && !!r.kind && !SYSTEM_KINDS.has(r.kind),
+  );
+
+  let i = 0;
+  while (i < queue.length) {
+    const resource = queue[i++];
+    const fieldMap = registry.getFieldMapForKind(resource.kind, aliases);
+    if (!fieldMap) continue;
+
+    const parentName = resource.metadata.name as string;
+    const parentModule = resource.metadata.module as string | undefined;
+
+    // Collect scope visibility prefixes so we can route extracted resources correctly.
+    const scopePrefixes: string[] = [];
+    for (const [, entry] of fieldMap) {
+      if (!isScopeEntry(entry)) continue;
+      const paths = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
+      for (const p of paths) {
+        scopePrefixes.push(p.replace(/^\//, "").replace(/\//g, "."));
+      }
+    }
+
+    for (const [fieldPath, entry] of fieldMap) {
+      if (!isRefEntry(entry)) continue;
+
+      const inScope = scopePrefixes.some(
+        (prefix) =>
+          fieldPath === prefix ||
+          fieldPath.startsWith(prefix + ".") ||
+          fieldPath.startsWith(prefix + "["),
+      );
+
+      const invocationContext = isRefEntry(entry) ? entry.context : undefined;
+      const extracted = extractInlinesAtPath(resource, fieldPath, parentName, parentModule, invocationContext);
+      for (const manifest of extracted) {
+        result.push(manifest);
+        queue.push(manifest as ResourceManifest & { metadata: { name: string } });
+        // TODO Phase 5: when inScope, add to parent's scope array instead of outer set
+        void inScope;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal).
+ * Mutates the resource in-place: replaces each inline value with `{kind, name}`.
+ * Returns the extracted manifests.
+ */
+function extractInlinesAtPath(
+  resource: ResourceManifest,
+  fieldPath: string,
+  parentName: string,
+  parentModule: string | undefined,
+  invocationContext?: Record<string, any>,
+): ResourceManifest[] {
+  const extracted: ResourceManifest[] = [];
+  const parts = fieldPath.split(".");
+
+  function traverse(obj: unknown, partsLeft: string[], nameParts: string[]): void {
+    if (!obj || typeof obj !== "object" || partsLeft.length === 0) return;
+
+    const [head, ...rest] = partsLeft;
+    const isArr = head.endsWith("[]");
+    const key = isArr ? head.slice(0, -2) : head;
+    const container = obj as Record<string, unknown>;
+    const val = container[key];
+    if (val == null) return;
+
+    if (isArr) {
+      if (!Array.isArray(val)) return;
+      for (let idx = 0; idx < val.length; idx++) {
+        const elem = val[idx];
+        if (!elem || typeof elem !== "object") continue;
+        const elemId =
+          typeof (elem as Record<string, unknown>).name === "string"
+            ? ((elem as Record<string, unknown>).name as string)
+            : String(idx);
+
+        if (rest.length === 0) {
+          // Array element itself is the ref slot
+          if (isInlineResource(elem as Record<string, unknown>)) {
+            const name = sanitizeName([parentName, ...nameParts, key, elemId].join("_"));
+            extracted.push(buildManifest(elem as Record<string, unknown>, name, parentModule, invocationContext));
+            val[idx] = { kind: (elem as Record<string, unknown>).kind, name };
+          }
+        } else {
+          traverse(elem, rest, [...nameParts, key, elemId]);
+        }
+      }
+    } else {
+      if (rest.length === 0) {
+        // val is the ref slot
+        if (val && typeof val === "object" && !Array.isArray(val) && isInlineResource(val as Record<string, unknown>)) {
+          const name = sanitizeName([parentName, ...nameParts, key].join("_"));
+          extracted.push(buildManifest(val as Record<string, unknown>, name, parentModule, invocationContext));
+          container[key] = { kind: (val as Record<string, unknown>).kind, name };
+        }
+      } else {
+        traverse(val, rest, [...nameParts, key]);
+      }
+    }
+  }
+
+  traverse(resource, parts, []);
+  return extracted;
+}
+
+function buildManifest(
+  inline: Record<string, unknown>,
+  name: string,
+  parentModule: string | undefined,
+  invocationContext?: Record<string, any>,
+): ResourceManifest {
+  const existingMeta =
+    inline.metadata && typeof inline.metadata === "object"
+      ? (inline.metadata as Record<string, unknown>)
+      : {};
+  return {
+    ...inline,
+    metadata: {
+      ...existingMeta,
+      name,
+      // Inherit parent module only if the inline doesn't already declare one
+      ...(parentModule && !existingMeta.module ? { module: parentModule } : {}),
+      ...(invocationContext ? { xTeloInvocationContext: invocationContext } : {}),
+    },
+  } as ResourceManifest;
+}

package/src/precompile.ts

@@ -0,0 +1,54 @@
+import type { CompiledValue } from "@telorun/sdk";
+import { celEnvironment } from "./cel-environment.js";
+
+const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
+const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+
+/**
+ * Walks a raw YAML document and replaces all "${{ expr }}" strings with
+ * CompiledValue wrappers. Throws on CEL syntax errors.
+ * Intended to be called once per document at load time.
+ * Kernel.Definition documents are returned unchanged — their schema fields
+ * are static metadata and must not be treated as CEL templates.
+ */
+export function precompileDoc(doc: unknown): unknown {
+  if (typeof doc === "string") return compileString(doc);
+  if (Array.isArray(doc)) return doc.map(precompileDoc);
+  // Only recurse into plain objects. Class instances (ResourceInstance, ScopeHandle, etc.)
+  // are returned as-is — their prototype methods must not be lost by object reconstruction.
+  if (doc !== null && typeof doc === "object" && Object.getPrototypeOf(doc) === Object.prototype) {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(doc as Record<string, unknown>)) {
+      result[k] = precompileDoc(v);
+    }
+    return result;
+  }
+  return doc;
+}
+
+function compileString(s: string): unknown {
+  if (!s.includes("${{")) return s;
+
+  const exact = s.match(EXACT_TEMPLATE_REGEX);
+  if (exact) {
+    const fn = celEnvironment.parse(exact[1].trim());
+    return { __compiled: true, call: (ctx: Record<string, unknown>) => fn(ctx) } satisfies CompiledValue;
+  }
+
+  // Interpolated template — collect literal parts + compiled sub-expressions
+  const parts: Array<string | CompiledValue> = [];
+  let last = 0;
+  for (const m of s.matchAll(TEMPLATE_REGEX)) {
+    if (m.index! > last) parts.push(s.slice(last, m.index));
+    const fn = celEnvironment.parse(m[1].trim());
+    parts.push({ __compiled: true, call: (ctx: Record<string, unknown>) => fn(ctx) } satisfies CompiledValue);
+    last = m.index! + m[0].length;
+  }
+  if (last < s.length) parts.push(s.slice(last));
+
+  return {
+    __compiled: true,
+    call: (ctx: Record<string, unknown>) =>
+      parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
+  } satisfies CompiledValue;
+}

package/src/reference-field-map.ts

@@ -0,0 +1,147 @@
+/** An entry for a field that carries one or more x-telo-ref constraints. */
+export interface RefFieldEntry {
+  /** One or more canonical ref strings ("namespace/module#TypeName" or "kernel#TypeName").
+   *  Multiple entries arise from anyOf branches. */
+  refs: string[];
+  /** True when the field path traversed through at least one array (path contains "[]"). */
+  isArray: boolean;
+  /** x-telo-context schema declared on this ref slot, if any. Describes the CEL invocation
+   *  context available to resources placed in this slot. */
+  context?: Record<string, any>;
+}
+
+/** An entry for a field that declares an execution scope (x-telo-scope). */
+export interface ScopeFieldEntry {
+  /** JSON Pointer(s) (RFC 6901) declaring where x-telo-ref slots within this field can
+   *  resolve to the scoped resources. */
+  scope: string | string[];
+}
+
+/** An entry for a field whose schema is resolved dynamically from a referenced resource's
+ *  definition schema (x-telo-schema-from). */
+export interface SchemaFromFieldEntry {
+  /** Full path expression as written in the schema, e.g.:
+   *  - "backend/$defs/NodeOptions"   (relative: sibling x-telo-ref property)
+   *  - "/backend/$defs/NodeOptions"  (absolute: root-level x-telo-ref property) */
+  schemaFrom: string;
+}
+
+export type FieldMapEntry = RefFieldEntry | ScopeFieldEntry | SchemaFromFieldEntry;
+
+/** Map from field path to its reference or scope metadata.
+ *  Paths use dot notation; array traversal is denoted by `[]` (e.g. "steps[].invoke"). */
+export type ReferenceFieldMap = Map<string, FieldMapEntry>;
+
+export function isRefEntry(entry: FieldMapEntry): entry is RefFieldEntry {
+  return "refs" in entry;
+}
+
+export function isScopeEntry(entry: FieldMapEntry): entry is ScopeFieldEntry {
+  return "scope" in entry;
+}
+
+export function isSchemaFromEntry(entry: FieldMapEntry): entry is SchemaFromFieldEntry {
+  return "schemaFrom" in entry;
+}
+
+/** Keys that a named reference object may have. Values beyond these indicate an inline resource. */
+export const REFERENCE_KEYS = new Set(["kind", "name", "metadata"]);
+
+/** True when `val` is an inline resource definition rather than a named reference.
+ *  A named reference (has string `name`) may carry extra keys (e.g. `inputs`) that
+ *  are runtime call parameters — those are never inline resources. */
+export function isInlineResource(val: Record<string, unknown>): boolean {
+  if (typeof val.name === "string") return false;
+  return Object.keys(val).some((k) => !REFERENCE_KEYS.has(k));
+}
+
+/** Resolves all values at a field map path in a resource config.
+ *  `[]` in a path segment means "iterate array at this key". */
+export function resolveFieldValues(obj: unknown, path: string): unknown[] {
+  const parts = path.split(".");
+  let current: unknown[] = [obj];
+  for (const part of parts) {
+    const isArray = part.endsWith("[]");
+    const key = isArray ? part.slice(0, -2) : part;
+    const next: unknown[] = [];
+    for (const item of current) {
+      if (!item || typeof item !== "object") continue;
+      const val = (item as Record<string, unknown>)[key];
+      if (val == null) continue;
+      if (isArray && Array.isArray(val)) next.push(...val);
+      else if (!isArray) next.push(val);
+    }
+    current = next;
+  }
+  return current;
+}
+
+/**
+ * Traverses a definition's JSON Schema once and returns a field map recording every
+ * x-telo-ref slot and every x-telo-scope slot.
+ *
+ * - A node with `x-telo-ref` → RefFieldEntry with refs: [that value]
+ * - A node with `anyOf` whose branches have `x-telo-ref` → RefFieldEntry with all branch refs
+ * - A node with `x-telo-scope` → ScopeFieldEntry
+ * - A node with `type: array` + `items` → recurse into items with path "fieldName[]"
+ * - A node with `properties` → recurse into each property
+ */
+export function buildReferenceFieldMap(schema: Record<string, any>): ReferenceFieldMap {
+  const map: ReferenceFieldMap = new Map();
+  if (schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      traverseNode(propSchema as Record<string, any>, key, map);
+    }
+  }
+  return map;
+}
+
+function collectRefs(node: Record<string, any>): string[] {
+  const refs: string[] = [];
+  if (typeof node["x-telo-ref"] === "string") {
+    refs.push(node["x-telo-ref"]);
+  }
+  if (Array.isArray(node.anyOf)) {
+    for (const branch of node.anyOf) {
+      if (branch && typeof branch["x-telo-ref"] === "string") {
+        refs.push(branch["x-telo-ref"]);
+      }
+    }
+  }
+  return refs;
+}
+
+function traverseNode(node: Record<string, any>, path: string, map: ReferenceFieldMap): void {
+  // Scope slot — record and stop; do not recurse into scope contents
+  if ("x-telo-scope" in node) {
+    map.set(path, { scope: node["x-telo-scope"] });
+    return;
+  }
+
+  // Schema-from slot — record and stop; no further traversal needed
+  if ("x-telo-schema-from" in node) {
+    map.set(path, { schemaFrom: node["x-telo-schema-from"] });
+    return;
+  }
+
+  // Reference slot (direct or via anyOf)
+  const refs = collectRefs(node);
+  if (refs.length > 0) {
+    const entry: RefFieldEntry = { refs, isArray: path.includes("[]") };
+    if (node["x-telo-context"]) entry.context = node["x-telo-context"] as Record<string, any>;
+    map.set(path, entry);
+    return;
+  }
+
+  // Array — recurse into items
+  if (node.type === "array" && node.items) {
+    traverseNode(node.items as Record<string, any>, path + "[]", map);
+  }
+
+  // Object — recurse into properties
+  if (node.properties) {
+    for (const [key, propSchema] of Object.entries(node.properties)) {
+      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map);
+    }
+  }
+}

package/src/schema-compat.ts

@@ -0,0 +1,264 @@
+import AjvModule from "ajv";
+import addFormats from "ajv-formats";
+
+const Ajv = (AjvModule as any).default ?? AjvModule;
+
+/** Creates a configured AJV instance (allErrors, strict: false, with formats).
+ *  Called once for the module-level instance and once per DefinitionRegistry instance. */
+export function createAjv(): InstanceType<typeof Ajv> {
+  const instance = new Ajv({ allErrors: true, strict: false });
+  (addFormats as any).default
+    ? (addFormats as any).default(instance)
+    : (addFormats as any)(instance);
+  return instance;
+}
+
+const ajv = createAjv();
+
+export interface CompatibilityResult {
+  compatible: boolean;
+  issues: string[];
+}
+
+/** Conservative structural JSON Schema compatibility check.
+ *  Only flags definite mismatches: missing required fields and primitive type conflicts.
+ *  Ambiguous cases (anyOf/oneOf/etc.) are treated as compatible. */
+export function checkSchemaCompatibility(
+  source: Record<string, any>,
+  target: Record<string, any>,
+): CompatibilityResult {
+  const issues: string[] = [];
+  checkObject(source, target, "", issues);
+  return { compatible: issues.length === 0, issues };
+}
+
+function checkObject(
+  source: Record<string, any>,
+  target: Record<string, any>,
+  path: string,
+  issues: string[],
+): void {
+  const targetRequired: string[] = target.required ?? [];
+  const sourceProps: Record<string, any> = source.properties ?? {};
+  const targetProps: Record<string, any> = target.properties ?? {};
+
+  for (const field of targetRequired) {
+    if (!(field in sourceProps)) {
+      issues.push(`${path}/${field}: required by target but missing from source`);
+      continue;
+    }
+    const srcProp = sourceProps[field];
+    const tgtProp = targetProps[field];
+    if (tgtProp && srcProp) {
+      checkProperty(srcProp, tgtProp, `${path}/${field}`, issues);
+    }
+  }
+}
+
+function checkProperty(
+  source: Record<string, any>,
+  target: Record<string, any>,
+  path: string,
+  issues: string[],
+): void {
+  // Only flag definite primitive type clashes; skip anyOf/oneOf/allOf
+  if (
+    source.type &&
+    target.type &&
+    typeof source.type === "string" &&
+    typeof target.type === "string" &&
+    source.type !== target.type
+  ) {
+    issues.push(
+      `${path}: type mismatch — source is '${source.type}', target expects '${target.type}'`,
+    );
+    return;
+  }
+  if (target.type === "object" && source.type === "object") {
+    checkObject(source, target, path, issues);
+  }
+}
+
+export function formatSingleError(err: any): string {
+  const p = err.instancePath || "/";
+  return `${p} ${err.message ?? "is invalid"}`;
+}
+
+export function formatAjvErrors(errors: any[] | null | undefined): string {
+  if (!errors || errors.length === 0) return "Unknown schema error";
+  return errors.map(formatSingleError).join("; ");
+}
+
+/** Converts an AJV error object to a dotted path string compatible with PositionIndex keys.
+ *  e.g. instancePath "/config/routes/0/handler" → "config.routes[0].handler"
+ *  For "required" keyword errors, appends the missing property to the parent path. */
+function ajvErrorToPath(err: any): string {
+  const instancePath = (err.instancePath ?? "") as string;
+  const parts = instancePath.split("/").filter((p) => p !== "");
+  let result = "";
+  for (const part of parts) {
+    if (/^\d+$/.test(part)) {
+      result += `[${part}]`;
+    } else {
+      result += result ? `.${part}` : part;
+    }
+  }
+  if (err.keyword === "required" && err.params?.missingProperty) {
+    const missing = err.params.missingProperty as string;
+    result += result ? `.${missing}` : missing;
+  }
+  return result;
+}
+
+/** A schema validation issue with a dotted-path pointer to the offending field. */
+export interface SchemaIssue {
+  message: string;
+  /** Dotted path to the field (e.g. "config.handler"). Empty string means root. */
+  path: string;
+}
+
+/** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
+export function validateAgainstSchema(data: unknown, schema: Record<string, any>): SchemaIssue[] {
+  let validate: ReturnType<typeof ajv.compile>;
+  try {
+    validate = ajv.compile(schema);
+  } catch {
+    return [];
+  }
+  if (validate(data)) return [];
+  return (validate.errors ?? []).map((err: any) => ({
+    message: formatSingleError(err),
+    path: ajvErrorToPath(err),
+  }));
+}
+
+/** Resolves a JSON Pointer (RFC 6901, must start with "/") into a schema object.
+ *  Returns undefined when any segment along the path is missing or not an object. */
+export function navigateJsonPointer(schema: unknown, pointer: string): unknown {
+  const segments = pointer.split("/").slice(1); // drop leading empty string from "/"
+  let current: unknown = schema;
+  for (const seg of segments) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[seg];
+  }
+  return current;
+}
+
+/** Navigate a JSON Schema following a `walkCelExpressions`-style path
+ *  (e.g. `port`, `routes[0].handler.when`).
+ *  Dot-separated segments navigate `properties`; `[N]` indices navigate `items`.
+ *  Stops and returns the current node when a union type (`anyOf`/`oneOf`) is reached.
+ *  Returns `undefined` if any segment cannot be resolved. */
+export function navigateSchemaToExprPath(
+  schema: Record<string, any>,
+  path: string,
+): Record<string, any> | undefined {
+  if (!path) return schema;
+  let current: Record<string, any> = schema;
+  for (const part of path.split(".")) {
+    if (!current || typeof current !== "object") return undefined;
+    if (current.anyOf || current.oneOf) return current;
+    const m = part.match(/^([a-zA-Z_][a-zA-Z0-9_]*)((?:\[\d+\])*)$/);
+    if (!m) return undefined;
+    const [, ident, indices] = m as [string, string, string];
+    const props = current.properties as Record<string, any> | undefined;
+    if (!props || !(ident in props)) return undefined;
+    current = props[ident] as Record<string, any>;
+    if (!current) return undefined;
+    const indexCount = (indices.match(/\[/g) ?? []).length;
+    for (let i = 0; i < indexCount; i++) {
+      if (!current || typeof current !== "object") return undefined;
+      if (current.anyOf || current.oneOf) return current;
+      if (!current.items) return undefined;
+      current = current.items as Record<string, any>;
+    }
+  }
+  return current;
+}
+
+/** Map a JSON Schema type annotation to a CEL type string. */
+export function jsonSchemaToCelType(schema: Record<string, any> | undefined): string {
+  if (!schema || typeof schema !== "object") return "dyn";
+  if (schema.anyOf || schema.oneOf || schema.allOf) return "dyn";
+  if (Array.isArray(schema.type)) return "dyn";
+  switch (schema.type) {
+    case "integer": return "int";
+    case "number": return "double";
+    case "string": return "string";
+    case "boolean": return "bool";
+    case "array": return "list";
+    case "object": return "map";
+    case "null": return "null_type";
+  }
+  if (schema.properties) return "map";
+  if (schema.items) return "list";
+  return "dyn";
+}
+
+/** Check whether a CEL return type is compatible with a JSON Schema type constraint. */
+export function celTypeSatisfiesJsonSchema(
+  celType: string,
+  schema: Record<string, any>,
+): boolean {
+  if (celType === "dyn") return true;
+  if (!schema.type && !schema.anyOf && !schema.oneOf && !schema.allOf) return true;
+  if (schema.anyOf || schema.oneOf || schema.allOf) return true;
+  const schemaTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const accepted: Record<string, string[]> = {
+    int: ["integer", "number"],
+    uint: ["integer", "number"],
+    double: ["number"],
+    string: ["string"],
+    bool: ["boolean"],
+    list: ["array"],
+    map: ["object"],
+    null_type: ["null"],
+    timestamp: ["string"],
+    duration: ["string"],
+    bytes: ["string"],
+  };
+  const compatibleWith = accepted[celType];
+  if (!compatibleWith) return true; // unknown CEL type — don't flag
+  return compatibleWith.some((t) => schemaTypes.includes(t));
+}
+
+/** Return a literal placeholder value of the correct schema type for AJV. */
+export function celPlaceholderForSchema(schema: Record<string, any>): unknown {
+  if (schema.default !== undefined) return schema.default;
+  switch (schema.type) {
+    case "integer":
+    case "number": return schema.minimum ?? 0;
+    case "string": return "";
+    case "boolean": return false;
+    case "array": return [];
+    case "object": return {};
+    default: return null;
+  }
+}
+
+const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
+
+/** Deep-clone `data`, replacing every pure CEL template string (`${{ expr }}`) with a
+ *  schema-appropriate placeholder so AJV can validate non-CEL fields without false positives. */
+export function substituteCelFields(data: unknown, schema: Record<string, any>): unknown {
+  if (typeof data === "string" && CEL_PURE_RE.test(data)) {
+    return celPlaceholderForSchema(schema);
+  }
+  if (Array.isArray(data)) {
+    const itemSchema = (schema.items ?? {}) as Record<string, any>;
+    return data.map((item) => substituteCelFields(item, itemSchema));
+  }
+  if (data !== null && typeof data === "object") {
+    const props = (schema.properties ?? {}) as Record<string, any>;
+    const addlProps =
+      schema.additionalProperties && typeof schema.additionalProperties === "object"
+        ? (schema.additionalProperties as Record<string, any>)
+        : 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>);
+    }
+    return result;
+  }
+  return data;
+}

package/src/scope-resolver.ts

@@ -0,0 +1,13 @@
+import { JSONPath } from "jsonpath-plus";
+
+/** Evaluate a JSON Path (RFC 9535) expression against a resource config and return the
+ *  string values found. These are the referenced resource names at that call site.
+ *  Returns [] when the path matches nothing or yields non-string values. Never throws. */
+export function resolveScope(config: Record<string, any>, scope: string): string[] {
+  try {
+    const results: unknown[] = JSONPath({ path: scope, json: config, resultType: "value" });
+    return results.filter((v): v is string => typeof v === "string");
+  } catch {
+    return [];
+  }
+}