typekro 0.10.0 → 0.11.0

package/dist/core/serialization/cel-references.d.ts

@@ -10,6 +10,7 @@
  */
 import type { KubernetesRef } from '../types/common.js';
 import type { SerializationContext } from '../types/serialization.js';
+export declare function normalizeCelArrayIndexPaths(expr: string): string;
 /**
  * Compute the inner CEL path for a {@link KubernetesRef}.
  *
@@ -94,13 +95,7 @@ export declare function inlineNestedStatusRefs(expr: string, nestedStatusCel: Re
  *    `${…}` so KRO recognizes it as an expression to evaluate.
  */
 export declare function finalizeCelForKro(expr: string, nestedStatusCel: Record<string, string> | undefined, context?: SerializationContext): string;
-/**
- * Recursively replace all {@link KubernetesRef} objects with CEL expressions
- * for Kro YAML output.
- *
- * This is the **only** function that should perform this transformation.
- */
-export declare function processResourceReferences(obj: unknown, context?: SerializationContext): unknown;
+export declare function processResourceReferences(obj: unknown, context?: SerializationContext, path?: string): unknown;
 /**
  * Serialize user-defined status mappings to CEL expressions for Kro schema.
  *

package/dist/core/serialization/cel-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cel-references.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/cel-references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAYtE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,MAAM,CAGnE;AA0LD,qFAAqF;AACrF,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAajG;AA6DD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAClD,OAAO,CAIT;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,kBAAkB,GAAE,OAAc,GACjC,MAAM,GAAG,SAAS,CA2EpB;AAmDD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACnD,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,MAAM,CAER;AA2HD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACnD,OAAO,CAAC,EAAE,oBAAoB,GAC7B,MAAM,CAUR;AA0ED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAgE/F;AAMD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACzB,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC,CAkL9D"}
+{"version":3,"file":"cel-references.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/cel-references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAQtE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmDhE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,MAAM,CAGnE;AAwMD,qFAAqF;AACrF,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAajG;AA6DD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAClD,OAAO,CAIT;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,kBAAkB,GAAE,OAAc,GACjC,MAAM,GAAG,SAAS,CAyEpB;AAmDD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACnD,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,MAAM,CAER;AA4HD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACnD,OAAO,CAAC,EAAE,oBAAoB,GAC7B,MAAM,CAYR;AA+mBD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE,oBAAoB,EAC9B,IAAI,SAAK,GACR,OAAO,CAgHT;AAMD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACzB,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC,CA4K9D"}

package/dist/core/serialization/cel-references.js

@@ -8,9 +8,10 @@
  * This module is the **single authority** for KubernetesRef → CEL string
  * conversion.  No other module should duplicate this logic.
  */
-import { isCelExpression, isKubernetesRef } from '../../utils/type-guards.js';
-import { escapeCelString } from '../../utils/cel-escape.js';
 import { KUBERNETES_REF_MARKER_SOURCE } from '../../shared/brands.js';
+import { escapeCelString } from '../../utils/cel-escape.js';
+import { isCelExpression, isKubernetesRef } from '../../utils/type-guards.js';
+import { isValuesMergeExpression } from '../aspects/values-merge.js';
 import { remapVariableNames } from '../composition/nested-status-cel.js';
 import { getComponentLogger } from '../logging/index.js';
 import { copyResourceMetadata } from '../metadata/index.js';
@@ -18,6 +19,52 @@ const logger = getComponentLogger('cel-references');
 function escapeRegExpLiteral(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+export function normalizeCelArrayIndexPaths(expr) {
+    let result = '';
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < expr.length; i++) {
+        const char = expr[i];
+        if (!char)
+            continue;
+        if (quote) {
+            result += char;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === '\\') {
+                escaped = true;
+            }
+            else if (char === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            result += char;
+            continue;
+        }
+        if (char === '.') {
+            const digitStart = i + 1;
+            let digitEnd = digitStart;
+            while (digitEnd < expr.length && /\d/.test(expr[digitEnd] ?? '')) {
+                digitEnd++;
+            }
+            const previous = expr[i - 1] ?? '';
+            const next = expr[digitEnd] ?? '';
+            if (digitEnd > digitStart &&
+                /[A-Za-z_$\]]/.test(previous) &&
+                (next === '' || /[.\])}\s?:,+\-*/<>=!&|]/.test(next))) {
+                result += `[${expr.slice(digitStart, digitEnd)}]`;
+                i = digitEnd - 1;
+                continue;
+            }
+        }
+        result += char;
+    }
+    return result;
+}
 // ---------------------------------------------------------------------------
 // Primitive helpers
 // ---------------------------------------------------------------------------
@@ -32,7 +79,7 @@ function escapeRegExpLiteral(value) {
  */
 export function getInnerCelPath(ref) {
     const resourceId = ref.resourceId === '__schema__' ? 'schema' : ref.resourceId;
-    return `${resourceId}.${ref.fieldPath}`;
+    return normalizeCelArrayIndexPaths(`${resourceId}.${ref.fieldPath}`);
 }
 function resolveResourceIdAlias(resourceId, context) {
     if (resourceId === '__schema__') {
@@ -72,13 +119,17 @@ function resolveResourceIdAlias(resourceId, context) {
  */
 function maybeWrapWithOmit(celPath, stringWrap, omitFields) {
     const value = stringWrap ? `string(${celPath})` : celPath;
+    const guard = optionalSchemaSpecGuard(celPath, omitFields);
+    return guard ? `${guard} ? ${value} : omit()` : value;
+}
+function optionalSchemaSpecGuard(celPath, omitFields) {
     if (!omitFields || omitFields.size === 0)
-        return value;
+        return undefined;
     // Only handle refs rooted at `schema.spec.`.
     const refMatch = /^schema\.spec\.([A-Za-z_$][\w$.]*)$/.exec(celPath);
     const refPath = refMatch?.[1];
     if (!refPath)
-        return value;
+        return undefined;
     // Walk the full path and collect every optional prefix that applies.
     // We chain from the SHALLOWEST optional ancestor through the leaf.
     //
@@ -105,9 +156,9 @@ function maybeWrapWithOmit(celPath, stringWrap, omitFields) {
             const guardPath = `schema.spec.${segments.slice(0, i).join('.')}`;
             guards.push(`has(${guardPath})`);
         }
-        return `${guards.join(' && ')} ? ${value} : omit()`;
+        return guards.join(' && ');
     }
-    return value;
+    return undefined;
 }
 /**
  * Wrap a {@link KubernetesRef} in `${…}` for Kro YAML output.
@@ -133,7 +184,7 @@ function generateCelExpression(ref, context) {
             return finalizeCelForKro(innerExpr, context.nestedStatusCel, context);
         }
     }
-    const expression = `${resolveResourceIdAlias(ref.resourceId, context)}.${ref.fieldPath}`;
+    const expression = normalizeCelArrayIndexPaths(`${resolveResourceIdAlias(ref.resourceId, context)}.${ref.fieldPath}`);
     const body = maybeWrapWithOmit(expression, false, context?.omitFields);
     return `\${${body}}`;
 }
@@ -174,7 +225,7 @@ const MARKER_PATTERN_FULL = new RegExp(`^${MARKER_PATTERN_SOURCE}$`);
  * emits `<resourceId>.<fieldPath>`.
  */
 function markerToCelPath(resourceId, fieldPath, context) {
-    return `${resolveResourceIdAlias(resourceId, context)}.${fieldPath}`;
+    return normalizeCelArrayIndexPaths(`${resolveResourceIdAlias(resourceId, context)}.${fieldPath}`);
 }
 /**
  * Normalize any `__KUBERNETES_REF__` markers in `str` to their bare CEL paths
@@ -545,7 +596,7 @@ function innerExprToYamlSegment(innerExpr, nestedStatusCel, context) {
     }
     if (resolved.includes('${')) {
         // Already a KRO template (from Cel.template) — pass through.
-        return resolved;
+        return normalizeCelArrayIndexPaths(resolved);
     }
     // Bare literal reached via a template-literal coercion — wrap with
     // `string(...)` so KRO evaluates it to a string value. This matches
@@ -575,16 +626,19 @@ function innerExprToYamlSegment(innerExpr, nestedStatusCel, context) {
  *    `${…}` so KRO recognizes it as an expression to evaluate.
  */
 export function finalizeCelForKro(expr, nestedStatusCel, context) {
-    const resolved = resolveNestedCompositionRefs(expr, nestedStatusCel, context?.resourceIds);
+    const resolved = normalizeCelArrayIndexPaths(resolveNestedCompositionRefs(expr, nestedStatusCel, context?.resourceIds));
     if (resolved.includes('__KUBERNETES_REF_')) {
         return convertKubernetesRefMarkersTocel(resolved, context);
     }
     if (resolved.includes('${')) {
         // Already contains KRO template placeholders — pass through.
-        return resolved;
+        return normalizeCelArrayIndexPaths(resolved);
     }
     return `\${${resolved}}`;
 }
+function normalizeSchemaSpecShorthand(expr) {
+    return expr.replace(/(^|[^A-Za-z0-9_$.])spec\./g, '$1schema.spec.');
+}
 // ---------------------------------------------------------------------------
 // __KUBERNETES_REF__ marker → KRO CEL conversion
 // ---------------------------------------------------------------------------
@@ -656,13 +710,363 @@ function convertKubernetesRefMarkersTocel(str, context) {
  *
  * This is the **only** function that should perform this transformation.
  */
-export function processResourceReferences(obj, context) {
+function valueTreePath(path) {
+    return path === 'spec.values' || path.includes('.values.') || path.endsWith('.values');
+}
+function childPath(parent, key) {
+    return parent ? `${parent}.${key}` : key;
+}
+function arrayChildPath(parent, index) {
+    return `${parent}[${index}]`;
+}
+function isPlainSerializableObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function valueTreeSerializationError(path, reason) {
+    return new Error(`Cannot serialize ${path} in graph mode. ${reason} Provide a serializable value or move this logic to a direct-only API.`);
+}
+function unwrapKroExpression(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    if (!value.startsWith('${') || !value.endsWith('}'))
+        return undefined;
+    return value.slice(2, -1);
+}
+function celValueTreeBranch(expression) {
+    return expression.includes(' ? ') && expression.includes(' : ') ? `(${expression})` : expression;
+}
+function celStringTemplateExpression(template) {
+    const parts = [];
+    let lastIndex = 0;
+    for (const match of template.matchAll(/\$\{([^}]+)\}/g)) {
+        const index = match.index ?? 0;
+        if (index > lastIndex) {
+            parts.push(JSON.stringify(template.slice(lastIndex, index)));
+        }
+        const innerExpression = match[1]?.trim();
+        if (innerExpression) {
+            parts.push(innerExpression.startsWith('string(') ? innerExpression : `string(${innerExpression})`);
+        }
+        lastIndex = index + match[0].length;
+    }
+    if (lastIndex < template.length) {
+        parts.push(JSON.stringify(template.slice(lastIndex)));
+    }
+    return parts.length > 0 ? parts.join(' + ') : JSON.stringify(template);
+}
+function celMarkerStringLiteralForValueTree(value, context) {
+    const resolved = resolveNestedRefMarkers(value, context?.nestedStatusCel, context?.resourceIds, context);
+    if (!resolved.includes('__KUBERNETES_REF_')) {
+        return resolved.includes('${') ? celStringTemplateExpression(resolved) : JSON.stringify(resolved);
+    }
+    const parts = [];
+    let lastIndex = 0;
+    for (const match of resolved.matchAll(new RegExp(MARKER_PATTERN_SOURCE, 'g'))) {
+        const index = match.index ?? 0;
+        if (index > lastIndex) {
+            parts.push(JSON.stringify(resolved.slice(lastIndex, index)));
+        }
+        const [, resourceId, fieldPath] = match;
+        if (resourceId && fieldPath) {
+            parts.push(`string(${markerToCelPath(resourceId, fieldPath, context)})`);
+        }
+        else {
+            parts.push(JSON.stringify(match[0]));
+        }
+        lastIndex = index + match[0].length;
+    }
+    if (lastIndex < resolved.length) {
+        parts.push(JSON.stringify(resolved.slice(lastIndex)));
+    }
+    return parts.length > 0 ? parts.join(' + ') : JSON.stringify(resolved);
+}
+function finalizeValueTreeCelForKro(expr, context) {
+    const resolved = normalizeCelArrayIndexPaths(resolveNestedCompositionRefs(expr, context?.nestedStatusCel, context?.resourceIds));
+    return `\${${resolved}}`;
+}
+function celLiteralForValueTree(value, context, path) {
+    if (isValuesMergeExpression(value)) {
+        return celValuesMergeExpression(value.base, value.overlays, context, path);
+    }
+    if (isKubernetesRef(value) || isCelExpression(value)) {
+        const expression = unwrapKroExpression(processResourceReferences(value, context, path)) ?? 'null';
+        return celValueTreeBranch(expression);
+    }
+    if (typeof value === 'string') {
+        return value.includes('__KUBERNETES_REF_') || value.includes('${')
+            ? celMarkerStringLiteralForValueTree(value, context)
+            : JSON.stringify(value);
+    }
+    if (value === null || typeof value === 'number' || typeof value === 'boolean') {
+        return JSON.stringify(value);
+    }
+    if (value === undefined)
+        return 'null';
+    if (Array.isArray(value)) {
+        return `[${value
+            .filter((entry) => entry !== undefined)
+            .map((entry, index) => celLiteralForValueTree(entry, context, arrayChildPath(path, index)))
+            .join(', ')}]`;
+    }
+    if (typeof value === 'object' && isPlainSerializableObject(value)) {
+        const entries = Object.entries(value).flatMap(([key, child]) => {
+            if (child === undefined)
+                return [];
+            return [
+                `${JSON.stringify(key)}: ${celLiteralForValueTree(child, context, childPath(path, key))}`,
+            ];
+        });
+        return `{${entries.join(', ')}}`;
+    }
+    throw valueTreeSerializationError(path, 'Only plain data, refs, CEL expressions, and templates can be merged.');
+}
+function mergeValueTrees(base, overlay, path) {
+    if (overlay === undefined)
+        return base;
+    if (isValuesMergeExpression(overlay)) {
+        let mergedOverlay = overlay.base;
+        const normalizedOverlays = Array.isArray(overlay.overlays)
+            ? overlay.overlays
+            : [overlay.overlays];
+        normalizedOverlays.forEach((nestedOverlay, index) => {
+            mergedOverlay = mergeValueTrees(mergedOverlay, nestedOverlay, `${path}.overlay[${index}]`);
+        });
+        return mergeValueTrees(base, mergedOverlay, path);
+    }
+    if (Array.isArray(overlay))
+        return overlay;
+    if (isKubernetesRef(overlay) || isCelExpression(overlay)) {
+        if (path === 'spec.values') {
+            throw valueTreeSerializationError(path, 'Kro CEL map merge support is required for whole-object values refs or CEL maps.');
+        }
+        return overlay;
+    }
+    if (typeof base === 'object' &&
+        base !== null &&
+        isPlainSerializableObject(base) &&
+        typeof overlay === 'object' &&
+        overlay !== null &&
+        isPlainSerializableObject(overlay)) {
+        return Object.fromEntries(Array.from(new Set([...Object.keys(base), ...Object.keys(overlay)])).flatMap((key) => {
+            const merged = mergeValueTrees(base[key], overlay[key], childPath(path, key));
+            return merged === undefined ? [] : [[key, merged]];
+        }));
+    }
+    return overlay;
+}
+function needsRuntimeMapMerge(value) {
+    if (isKubernetesRef(value) || isCelExpression(value))
+        return true;
+    if (isValuesMergeExpression(value)) {
+        const normalizedOverlays = Array.isArray(value.overlays) ? value.overlays : [value.overlays];
+        return (needsRuntimeMapMerge(value.base) ||
+            normalizedOverlays.some((overlay) => needsRuntimeMapMerge(overlay)));
+    }
+    return false;
+}
+function isKnownMergeObject(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        isPlainSerializableObject(value) &&
+        !isKubernetesRef(value) &&
+        !isCelExpression(value) &&
+        !isValuesMergeExpression(value));
+}
+function mapKeyAccess(mapExpression, key) {
+    return `(${mapExpression})[${JSON.stringify(key)}]`;
+}
+function mapHasKey(mapExpression, key) {
+    return `${JSON.stringify(key)} in (${mapExpression})`;
+}
+function celMapMergeOperand(value, context, path) {
+    if (isValuesMergeExpression(value)) {
+        return celValuesMergeExpression(value.base, value.overlays, context, path);
+    }
+    if (isKubernetesRef(value)) {
+        const celPath = getInnerCelPath(value);
+        const guard = optionalSchemaSpecGuard(celPath, context?.omitFields);
+        const operand = `json.unmarshal(json.marshal(${celPath}))`;
+        return guard ? `${guard} ? ${operand} : {}` : operand;
+    }
+    const expression = celLiteralForValueTree(value, context, path);
+    return `json.unmarshal(json.marshal(${expression}))`;
+}
+function celRuntimeMapMergeExpression(base, overlays, context, path) {
+    let expression;
+    let knownBase = base;
+    const normalizedOverlays = Array.isArray(overlays) ? overlays : [overlays];
+    normalizedOverlays.forEach((overlay, index) => {
+        if (overlay === undefined)
+            return;
+        const overlayPath = path || `spec.values.overlay[${index}]`;
+        if (expression === undefined) {
+            if (isKnownMergeObject(knownBase) && isKnownMergeObject(overlay)) {
+                knownBase = mergeValueTrees(knownBase, overlay, overlayPath);
+                return;
+            }
+            if (isKnownMergeObject(knownBase)) {
+                expression = isKnownMergeObject(overlay)
+                    ? celDeepMergeKnownOverlay(celMapMergeOperand(knownBase, context, path), overlay, context, overlayPath)
+                    : celDeepMergeRuntimeOverlay(knownBase, celMapMergeOperand(overlay, context, overlayPath), context, overlayPath);
+                return;
+            }
+            expression = isKnownMergeObject(overlay)
+                ? celDeepMergeKnownOverlay(celMapMergeOperand(knownBase, context, path), overlay, context, overlayPath)
+                : `(${celMapMergeOperand(knownBase, context, path)}).merge(${celMapMergeOperand(overlay, context, overlayPath)})`;
+            return;
+        }
+        expression = isKnownMergeObject(overlay)
+            ? celDeepMergeKnownOverlay(expression, overlay, context, overlayPath)
+            : `(${expression}).merge(${celMapMergeOperand(overlay, context, overlayPath)})`;
+    });
+    return expression ?? celLiteralForValueTree(knownBase, context, path);
+}
+function celDeepMergeRuntimeOverlay(base, overlayExpression, context, path) {
+    const entries = Object.entries(base).flatMap(([key, baseValue]) => {
+        if (baseValue === undefined)
+            return [];
+        const overlayValue = mapKeyAccess(overlayExpression, key);
+        const baseExpression = celLiteralForValueTree(baseValue, context, childPath(path, key));
+        const mergedValue = isKnownMergeObject(baseValue)
+            ? celDeepMergeRuntimeOverlay(baseValue, overlayValue, context, childPath(path, key))
+            : overlayValue;
+        return [
+            `${JSON.stringify(key)}: ${mapHasKey(overlayExpression, key)} ? ${mergedValue} : ${baseExpression}`,
+        ];
+    });
+    return `(${overlayExpression}).merge({${entries.join(', ')}})`;
+}
+function celDeepMergeKnownOverlay(baseExpression, overlay, context, path) {
+    const entries = Object.entries(overlay).flatMap(([key, overlayValue]) => {
+        if (overlayValue === undefined)
+            return [];
+        const overlayExpression = celLiteralForValueTree(overlayValue, context, childPath(path, key));
+        const baseValue = mapKeyAccess(baseExpression, key);
+        const mergedValue = isKnownMergeObject(overlayValue)
+            ? `${mapHasKey(baseExpression, key)} ? ${celDeepMergeKnownOverlay(baseValue, overlayValue, context, childPath(path, key))} : ${overlayExpression}`
+            : overlayExpression;
+        return [`${JSON.stringify(key)}: ${mergedValue}`];
+    });
+    return `(${baseExpression}).merge({${entries.join(', ')}})`;
+}
+function celValuesMergeExpression(base, overlays, context, path) {
+    const flattened = flattenValuesMergeExpression(base, overlays);
+    base = flattened.base;
+    const normalizedOverlays = flattened.overlays;
+    if (needsRuntimeMapMerge(base) ||
+        normalizedOverlays.some((overlay) => needsRuntimeMapMerge(overlay))) {
+        return celRuntimeMapMergeExpression(base, normalizedOverlays, context, path || 'spec.values');
+    }
+    let merged = base;
+    normalizedOverlays.forEach((overlay, index) => {
+        merged = mergeValueTrees(merged, overlay, path || `spec.values.overlay[${index}]`);
+    });
+    return celLiteralForValueTree(merged, context, path);
+}
+function valuesMergeNeedsRuntimeMapMerge(base, overlays) {
+    const flattened = flattenValuesMergeExpression(base, overlays);
+    return (needsRuntimeMapMerge(flattened.base) ||
+        flattened.overlays.some((overlay) => needsRuntimeMapMerge(overlay)));
+}
+function flattenValuesMergeExpression(base, overlays) {
+    let flattenedBase = base;
+    const flattenedOverlays = Array.isArray(overlays) ? [...overlays] : [overlays];
+    while (isValuesMergeExpression(flattenedBase)) {
+        const nestedOverlays = Array.isArray(flattenedBase.overlays)
+            ? flattenedBase.overlays
+            : [flattenedBase.overlays];
+        flattenedOverlays.unshift(...nestedOverlays);
+        flattenedBase = flattenedBase.base;
+    }
+    return { base: flattenedBase, overlays: flattenedOverlays };
+}
+function collectKnownMergeKeys(value, keys = new Set()) {
+    if (isValuesMergeExpression(value)) {
+        collectKnownMergeKeys(value.base, keys);
+        const normalizedOverlays = Array.isArray(value.overlays) ? value.overlays : [value.overlays];
+        normalizedOverlays.forEach((overlay) => collectKnownMergeKeys(overlay, keys));
+        return keys;
+    }
+    if (isKnownMergeObject(value)) {
+        Object.keys(value).forEach((key) => keys.add(key));
+    }
+    return keys;
+}
+function celValuesMergeTemplateObject(base, overlays, context, path) {
+    const flattened = flattenValuesMergeExpression(base, overlays);
+    base = flattened.base;
+    const normalizedOverlays = flattened.overlays;
+    const knownKeys = collectKnownMergeKeys(base);
+    normalizedOverlays.forEach((overlay) => collectKnownMergeKeys(overlay, knownKeys));
+    const orderedKeys = Array.from(knownKeys);
+    if (orderedKeys.length === 0)
+        return undefined;
+    return Object.fromEntries(orderedKeys.map((key) => {
+        const value = celValuesMergeTemplateValue(base, normalizedOverlays, key, context, path);
+        return [key, value];
+    }));
+}
+function celValuesMergeTemplateValue(base, overlays, key, context, path) {
+    let knownValue = isKnownMergeObject(base) ? base[key] : undefined;
+    for (const [index, overlay] of overlays.entries()) {
+        if (overlay === undefined)
+            continue;
+        const overlayPath = path || `spec.values.overlay[${index}]`;
+        if (isKnownMergeObject(overlay)) {
+            if (!Object.hasOwn(overlay, key))
+                continue;
+            knownValue = mergeValueTrees(knownValue, overlay[key], childPath(overlayPath, key));
+            continue;
+        }
+        return celValuesMergeRuntimeTemplateValue(knownValue, celMapMergeOperand(overlay, context, overlayPath), key, context, childPath(path, key));
+    }
+    return processResourceReferences(knownValue, context, childPath(path, key));
+}
+function celValuesMergeRuntimeTemplateValue(fallbackValue, overlayExpression, key, context, path) {
+    if (isValuesMergeExpression(fallbackValue)) {
+        const templateObject = celValuesMergeTemplateObject(fallbackValue.base, fallbackValue.overlays, context, path);
+        if (templateObject) {
+            return celValuesMergeRuntimeTemplateValue(templateObject, overlayExpression, key, context, path);
+        }
+    }
+    if (isKnownMergeObject(fallbackValue)) {
+        const childOverlay = `(${mapHasKey(overlayExpression, key)} ? ${mapKeyAccess(overlayExpression, key)} : {})`;
+        return Object.fromEntries(Object.entries(fallbackValue).flatMap(([childKey, childValue]) => {
+            if (childValue === undefined)
+                return [];
+            return [
+                [
+                    childKey,
+                    celValuesMergeRuntimeTemplateValue(childValue, childOverlay, childKey, context, childPath(path, childKey)),
+                ],
+            ];
+        }));
+    }
+    if (Array.isArray(fallbackValue)) {
+        return processResourceReferences(fallbackValue, context, path);
+    }
+    const fallbackExpression = celLiteralForValueTree(fallbackValue, context, path);
+    const expression = `${mapHasKey(overlayExpression, key)} ? ${mapKeyAccess(overlayExpression, key)} : (${fallbackExpression})`;
+    return finalizeCelForKro(expression, context?.nestedStatusCel, context);
+}
+export function processResourceReferences(obj, context, path = '') {
+    const inValueTree = valueTreePath(path);
+    if (isValuesMergeExpression(obj)) {
+        if (path === 'spec.values' && !valuesMergeNeedsRuntimeMapMerge(obj.base, obj.overlays)) {
+            const templateObject = celValuesMergeTemplateObject(obj.base, obj.overlays, context, path);
+            if (templateObject)
+                return templateObject;
+        }
+        return finalizeValueTreeCelForKro(celValuesMergeExpression(obj.base, obj.overlays, context, path), context);
+    }
     if (isKubernetesRef(obj)) {
         return generateCelExpression(obj, context);
     }
     if (isCelExpression(obj)) {
         if (obj.__isTemplate) {
-            return obj.expression.replace(/\$\{([^}]+)\}/g, (_match, innerExpr) => finalizeCelForKro(innerExpr, context?.nestedStatusCel, context));
+            return obj.expression.replace(/\$\{([^}]+)\}/g, (_match, innerExpr) => finalizeCelForKro(normalizeSchemaSpecShorthand(innerExpr), context?.nestedStatusCel, context));
         }
         // Bare CelExpression — may be a single schema.spec.X reference (possibly
         // wrapped in `string(...)`). Delegate any single schema ref to
@@ -679,6 +1083,12 @@ export function processResourceReferences(obj, context) {
         }
         return finalizeCelForKro(expr, context?.nestedStatusCel, context);
     }
+    if (inValueTree && typeof obj === 'function') {
+        throw valueTreeSerializationError(path, 'Functions are direct-mode only.');
+    }
+    if (inValueTree && typeof obj === 'symbol') {
+        throw valueTreeSerializationError(path, 'Symbols are runtime-only values.');
+    }
     // Strings containing __KUBERNETES_REF__ markers from template literals.
     // First resolve any nested-composition references — markers produced by
     // `createKubernetesRefProxy` use a virtual baseId as the resourceId,
@@ -695,15 +1105,24 @@ export function processResourceReferences(obj, context) {
         return resolved;
     }
     if (Array.isArray(obj)) {
-        return obj.map((item) => processResourceReferences(item, context));
+        return obj.flatMap((item, index) => {
+            if (inValueTree && item === undefined)
+                return [];
+            return [processResourceReferences(item, context, arrayChildPath(path, index))];
+        });
     }
     if (obj && typeof obj === 'object') {
+        if (inValueTree && !isPlainSerializableObject(obj)) {
+            throw valueTreeSerializationError(path, `${obj.constructor?.name ?? 'This value'} is not a plain serializable object.`);
+        }
         const result = {};
         for (const [key, value] of Object.entries(obj)) {
-            // Exclude hidden resourceId property and id field from the final template
-            if (key === '__resourceId' || key === 'id')
+            // Exclude hidden resourceId metadata; nested `id` fields can be valid resource config.
+            if (key === '__resourceId')
+                continue;
+            if (inValueTree && value === undefined)
                 continue;
-            result[key] = processResourceReferences(value, context);
+            result[key] = processResourceReferences(value, context, childPath(path, key));
         }
         // Preserve resource metadata (resourceId, readinessEvaluator, etc.) via WeakMap
         // Also migrates legacy non-enumerable properties from source
@@ -755,20 +1174,16 @@ export function serializeStatusMappingsToCel(statusMappings, nestedStatusCel, re
             : normalized;
     }
     /**
-     * Rewrite `schema.spec.*` references inside a resolved CEL expression so
-     * the result is valid KRO status CEL. KRO does not accept `schema.spec.*`
-     * in status CEL, so we apply two rewrites:
-     *
-     *  - `schema.spec.X.Y.orValue(Z)` → `Z` (substitute the default)
-     *  - `schema.spec.X.Y` → `X.spec.Y` iff `X` is a known resource ID
-     *    (routes the reference to the deployed resource's spec field)
+     * Rewrite resolved schema refs for KRO status CEL.
      *
-     * Unknown schema references are left intact; the KRO factory's deploy-
-     * time hydration handles them.
+     * KRO validates CR spec references as `schema.spec.*` in status mappings.
+     * The only schema-to-resource rewrite we keep is the explicit legacy shape
+     * `schema.spec.<resourceId>.<field>`, where `<resourceId>` is a real graph
+     * resource. Plain CR spec fields must remain `schema.spec.*`.
      */
     function rewriteSchemaRefsForKroStatus(expr) {
         let out = expr.replace(/__schema__\.spec\.[a-zA-Z0-9_.]+\.orValue\(([^)]+)\)/g, '$1');
-        out = out.replace(/__schema__\.spec\.([a-zA-Z0-9_.]+)/g, 'spec.$1');
+        out = out.replace(/__schema__\.spec\.([a-zA-Z0-9_.]+)/g, 'schema.spec.$1');
         out = out.replace(/schema\.spec\.[a-zA-Z0-9_.]+\.orValue\(([^)]+)\)/g, '$1');
         out = out.replace(/schema\.spec\.([a-zA-Z0-9]+)\.([a-zA-Z0-9.]+)/g, (_match, firstSegment, rest) => {
             if (resourceIds?.has(firstSegment)) {
@@ -776,7 +1191,6 @@ export function serializeStatusMappingsToCel(statusMappings, nestedStatusCel, re
             }
             return _match;
         });
-        out = out.replace(/schema\.spec\.([a-zA-Z_$][\w$]*)/g, 'spec.$1');
         return out;
     }
     /**
@@ -785,18 +1199,20 @@ export function serializeStatusMappingsToCel(statusMappings, nestedStatusCel, re
      * Centralized here so the two branches don't drift on what "produce
      * KRO status CEL from a resolved expression" means.
      */
-    function statusFieldFromExpression(expr) {
-        const resolved = normalizeLocalResourceExpr(resolveNestedCompositionRefs(normalizeLocalResourceExpr(expr), nestedStatusCel, resourceIds));
+    function statusFieldFromExpression(expr, rewriteSchemaRefs = true) {
+        const resolved = normalizeCelArrayIndexPaths(normalizeLocalResourceExpr(resolveNestedCompositionRefs(normalizeLocalResourceExpr(expr), nestedStatusCel, resourceIds)));
         if (resolved.includes('__KUBERNETES_REF_')) {
             // Marker-laden — use mixed-template form.
-            return rewriteSchemaRefsForKroStatus(convertKubernetesRefMarkersTocel(resolved));
+            const converted = convertKubernetesRefMarkersTocel(resolved);
+            return rewriteSchemaRefs ? rewriteSchemaRefsForKroStatus(converted) : converted;
         }
         if (resolved.includes('${')) {
             // Already a KRO mixed-template value. Do not wrap it again as
             // `${http://${...}}`, which is invalid CEL/YAML for status fields.
-            return rewriteSchemaRefsForKroStatus(resolved);
+            return rewriteSchemaRefs ? rewriteSchemaRefsForKroStatus(resolved) : resolved;
         }
-        return `\${${rewriteSchemaRefsForKroStatus(resolved)}}`;
+        const expression = rewriteSchemaRefs ? rewriteSchemaRefsForKroStatus(resolved) : resolved;
+        return `\${${expression}}`;
     }
     function serializeValue(value) {
         if (isKubernetesRef(value)) {
@@ -819,7 +1235,7 @@ export function serializeStatusMappingsToCel(statusMappings, nestedStatusCel, re
         }
         if (isCelExpression(value)) {
             if (value.__isTemplate) {
-                return value.expression.replace(/\$\{([^}]+)\}/g, (_match, innerExpr) => statusFieldFromExpression(innerExpr));
+                return value.expression.replace(/\$\{([^}]+)\}/g, (_match, innerExpr) => statusFieldFromExpression(normalizeSchemaSpecShorthand(innerExpr), false));
             }
             return statusFieldFromExpression(value.expression);
         }