typekro 0.7.0 → 0.9.0

package/dist/core/serialization/yaml.js

@@ -1,15 +1,17 @@
 /**
  * YAML generation functionality for Kro ResourceGraphDefinitions
  *
- * Supports Kro v0.8.x features: forEach, includeWhen, readyWhen, externalRef,
+ * Supports Kro 0.9.1+ ResourceGraphDefinition serialization, including
+ * forEach, includeWhen, readyWhen, externalRef, mixed-template CEL, omit(),
  * schema group, and allowBreakingChanges annotation.
  */
 import * as yaml from 'js-yaml';
+import { getMetadataField } from '../metadata/resource-metadata.js';
 import { escapeRegExp } from '../../utils/helpers.js';
 import { extractResourceReferences, isCelExpression, isKubernetesRef, } from '../../utils/type-guards.js';
 import { getForEach, getIncludeWhen, getReadyWhen, getResourceId, getTemplateOverrides, } from '../metadata/index.js';
 import { generateDeterministicResourceId } from '../resources/id.js';
-import { getInnerCelPath, processResourceReferences } from './cel-references.js';
+import { finalizeCelForKro, getInnerCelPath, normalizeRefMarkersToCelPaths, processResourceReferences } from './cel-references.js';
 import { generateKroSchema } from './schema.js';
 /**
  * Read a non-enumerable property from an Enhanced resource.
@@ -63,24 +65,31 @@ function readTemplateOverrides(resource) {
  * Convert a single includeWhen value to a CEL expression string.
  *
  * Accepted input types:
- *  - KubernetesRef proxy  → `${schema.spec.field}`
- *  - CelExpression object → `${expression}`
+ *  - KubernetesRef proxy  → `${schema.spec.field}` — the field's value is
+ *    used as the boolean condition. This is the semantics of the explicit
+ *    `.withIncludeWhen(spec.boolField)` API: the caller is being deliberate
+ *    about the field they want as the test. Callers who need a presence
+ *    check on an optional field should use `Cel.has(ref)` explicitly, or
+ *    write `if (spec.optional)` in the composition body (which the AST
+ *    analyzer rewrites to `has(...)` automatically based on the schema).
+ *  - CelExpression object → `${expression}` — use Cel.has / Cel.not /
+ *    Cel.expr to build explicit conditions.
  *  - string (already CEL) → pass-through
  *  - string with __KUBERNETES_REF__ markers → convert markers to CEL
  */
-function convertIncludeWhenValueToCel(value) {
+function convertIncludeWhenValueToCel(value, context) {
     if (typeof value === 'string') {
         if (value.includes('__KUBERNETES_REF_')) {
-            return convertRefMarkersInString(value);
+            return `\${${convertRefMarkersInString(value, context)}}`;
         }
         return value;
     }
     if (isKubernetesRef(value)) {
-        const celPath = getInnerCelPath(value);
+        const celPath = normalizeRefMarkersToCelPaths(getInnerCelPath(value), context);
         return `\${${celPath}}`;
     }
     if (isCelExpression(value)) {
-        return `\${${value.expression}}`;
+        return `\${${normalizeRefMarkersToCelPaths(value.expression, context)}}`;
     }
     // Fallback — coerce to string
     if (value !== undefined && value !== null) {
@@ -96,13 +105,13 @@ function convertIncludeWhenValueToCel(value) {
  *  - An array of the above
  *  - undefined (no condition)
  */
-function resolveIncludeWhen(raw) {
+function resolveIncludeWhen(raw, context) {
     if (raw === undefined || raw === null)
         return undefined;
     const items = Array.isArray(raw) ? raw : [raw];
     const celStrings = [];
     for (const item of items) {
-        const cel = convertIncludeWhenValueToCel(item);
+        const cel = convertIncludeWhenValueToCel(item, context);
         if (cel)
             celStrings.push(cel);
     }
@@ -111,6 +120,109 @@ function resolveIncludeWhen(raw) {
 // ---------------------------------------------------------------------------
 // readyWhen → CEL conversion
 // ---------------------------------------------------------------------------
+const READY_WHEN_CALLBACK_METHODS = new Set(['exists', 'all', 'filter', 'map', 'some', 'every']);
+function findMatchingParen(source, openIndex) {
+    let depth = 0;
+    let quote;
+    let escaped = false;
+    for (let i = openIndex; i < source.length; i++) {
+        const char = source[i];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === '\\') {
+                escaped = true;
+            }
+            else if (char === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (char === '(') {
+            depth++;
+        }
+        else if (char === ')') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function normalizeArrowBody(body) {
+    const trimmed = body.trim();
+    if (!trimmed.startsWith('{'))
+        return trimmed;
+    return trimmed
+        .replace(/^\{\s*(?:return\s+)?/, '')
+        .replace(/;?\s*\}\s*$/, '')
+        .trim();
+}
+function convertReadyWhenCallbackMethods(expression) {
+    let result = '';
+    let index = 0;
+    while (index < expression.length) {
+        const dotIndex = expression.indexOf('.', index);
+        if (dotIndex === -1) {
+            result += expression.slice(index);
+            break;
+        }
+        result += expression.slice(index, dotIndex);
+        let cursor = dotIndex + 1;
+        while (/\s/.test(expression[cursor] ?? ''))
+            cursor++;
+        const methodMatch = /^[a-zA-Z_$][a-zA-Z0-9_$]*/.exec(expression.slice(cursor));
+        if (!methodMatch || !READY_WHEN_CALLBACK_METHODS.has(methodMatch[0])) {
+            result += expression[dotIndex];
+            index = dotIndex + 1;
+            continue;
+        }
+        const method = methodMatch[0];
+        cursor += method.length;
+        while (/\s/.test(expression[cursor] ?? ''))
+            cursor++;
+        if (expression[cursor] !== '(') {
+            result += expression[dotIndex];
+            index = dotIndex + 1;
+            continue;
+        }
+        const closeIndex = findMatchingParen(expression, cursor);
+        if (closeIndex === -1) {
+            result += expression[dotIndex];
+            index = dotIndex + 1;
+            continue;
+        }
+        const callbackSource = expression.slice(cursor + 1, closeIndex).trim();
+        const arrowIndex = callbackSource.indexOf('=>');
+        if (arrowIndex === -1) {
+            result += expression.slice(dotIndex, closeIndex + 1);
+            index = closeIndex + 1;
+            continue;
+        }
+        let param = callbackSource.slice(0, arrowIndex).trim();
+        param = param.replace(/^\(\s*/, '').replace(/\s*\)$/, '').trim();
+        const colonIndex = param.indexOf(':');
+        if (colonIndex !== -1)
+            param = param.slice(0, colonIndex).trim();
+        if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param)) {
+            result += expression.slice(dotIndex, closeIndex + 1);
+            index = closeIndex + 1;
+            continue;
+        }
+        let body = normalizeArrowBody(callbackSource.slice(arrowIndex + 2));
+        body = body.replace(/===/g, '==').replace(/!==/g, '!=');
+        body = convertReadyWhenCallbackMethods(body);
+        const celMethod = method === 'some' ? 'exists' : method === 'every' ? 'all' : method;
+        result += `.${celMethod}(${param}, ${body})`;
+        index = closeIndex + 1;
+    }
+    return result;
+}
 /**
  * Convert a readyWhen callback function to a CEL expression string by parsing its source.
  *
@@ -163,17 +275,10 @@ function convertReadyWhenCallbackToCel(fn, resourceId) {
     // JS → CEL operator conversions (must happen before inner callback processing)
     celExpr = celExpr.replace(/===/g, '==');
     celExpr = celExpr.replace(/!==/g, '!=');
-    // Convert JS arrow function callbacks inside .exists(), .filter(), .all(), .map()
-    // Pattern: .exists((c) => c.type === 'Ready' && c.status === 'True')
-    // → .exists(c, c.type == "Ready" && c.status == "True")
-    celExpr = celExpr.replace(/\.\s*(exists|all|filter|map)\s*\(\s*\(?([a-zA-Z_$][a-zA-Z0-9_$]*)\)?\s*(?::\s*\w+)?\s*=>\s*([\s\S]+?)\)/g, (_match, method, innerParam, innerBody) => {
-        let cleanBody = innerBody.trim();
-        // Fix operators in inner body too
-        cleanBody = cleanBody.replace(/===/g, '==').replace(/!==/g, '!=');
-        // Convert single quotes to double quotes for string literals
-        cleanBody = cleanBody.replace(/'([^']+)'/g, '"$1"');
-        return `.${method}(${innerParam}, ${cleanBody})`;
-    });
+    // Convert JS arrow function callbacks inside CEL macros and natural JS array
+    // helpers. Use a balanced scanner instead of a regex so nested parentheses in
+    // predicate bodies don't truncate the callback body.
+    celExpr = convertReadyWhenCallbackMethods(celExpr);
     // Convert remaining single-quoted strings to double-quoted for CEL
     celExpr = celExpr.replace(/'([^']+)'/g, '"$1"');
     return celExpr;
@@ -187,7 +292,7 @@ function convertReadyWhenCallbackToCel(fn, resourceId) {
  *  - CelExpression object → `${expression}`
  *  - string (already CEL) → pass-through
  */
-function convertReadyWhenValueToCel(value, resourceId, hasForEach) {
+function convertReadyWhenValueToCel(value, resourceId, hasForEach, context) {
     // Callback function — parse source to extract CEL expression
     if (typeof value === 'function') {
         const baseId = hasForEach ? 'each' : resourceId;
@@ -195,15 +300,16 @@ function convertReadyWhenValueToCel(value, resourceId, hasForEach) {
         return `\${${celExpr}}`;
     }
     if (isKubernetesRef(value)) {
-        const celPath = getInnerCelPath(value);
+        const celPath = normalizeRefMarkersToCelPaths(getInnerCelPath(value), context);
         return `\${${celPath}}`;
     }
     if (isCelExpression(value)) {
-        return `\${${value.expression}}`;
+        return `\${${normalizeRefMarkersToCelPaths(value.expression, context)}}`;
     }
     if (typeof value === 'string') {
         if (value.includes('__KUBERNETES_REF_')) {
-            return `\${${convertRefMarkersInString(value)}}`;
+            const converted = convertRefMarkersInString(value, context);
+            return converted.includes('${') ? converted : `\${${converted}}`;
         }
         return value;
     }
@@ -215,13 +321,13 @@ function convertReadyWhenValueToCel(value, resourceId, hasForEach) {
 /**
  * Resolve the readyWhen property from an Enhanced resource to an array of CEL strings.
  */
-function resolveReadyWhen(raw, resourceId, hasForEach) {
+function resolveReadyWhen(raw, resourceId, hasForEach, context) {
     if (raw === undefined || raw === null)
         return undefined;
     const items = Array.isArray(raw) ? raw : [raw];
     const celStrings = [];
     for (const item of items) {
-        const cel = convertReadyWhenValueToCel(item, resourceId, hasForEach);
+        const cel = convertReadyWhenValueToCel(item, resourceId, hasForEach, context);
         if (cel)
             celStrings.push(cel);
     }
@@ -236,16 +342,8 @@ function resolveReadyWhen(raw, resourceId, hasForEach) {
  * Input:  "__KUBERNETES_REF_web_status.readyReplicas__ > 0"
  * Output: "web.status.readyReplicas > 0"
  */
-function convertRefMarkersInString(str) {
-    // Pattern: __KUBERNETES_REF_{resourceId}_{fieldPath}__
-    // For schema: __KUBERNETES_REF___schema___{fieldPath}__
-    const refPattern = /__KUBERNETES_REF_(__schema__|[^_]+)_([a-zA-Z0-9.$]+)__/g;
-    return str.replace(refPattern, (_match, resourceId, fieldPath) => {
-        if (resourceId === '__schema__') {
-            return `schema.${fieldPath}`;
-        }
-        return `${resourceId}.${fieldPath}`;
-    });
+function convertRefMarkersInString(str, context) {
+    return normalizeRefMarkersToCelPaths(str, context);
 }
 // ---------------------------------------------------------------------------
 // forEach $item sentinel substitution
@@ -295,6 +393,130 @@ function substituteForEachSentinels(template, basePath, varName) {
     // Primitives (number, boolean, null, undefined) pass through unchanged
     return template;
 }
+/**
+ * Strip orphaned `$item` sentinel references from a template.
+ *
+ * After forEach substitution, any remaining `$item` paths are from non-forEach
+ * contexts — typically when `...spec.array` is spread into a literal array.
+ * These are not valid CEL identifiers and must be collapsed to the parent
+ * array reference.
+ *
+ * Handles both wrapped CEL (`${path.$item.field}`) and raw paths.
+ * Strips `.$item` and any trailing field access, keeping just the parent path.
+ */
+function stripOrphanedItemSentinels(template) {
+    if (typeof template === 'string') {
+        const normalized = normalizeOptionalArrayConditional(template);
+        if (normalized !== undefined)
+            return normalized;
+        if (!template.includes('$item'))
+            return template;
+        // Match any path segment ending with .$item optionally followed by .field
+        const stripped = template.replace(/(\w[\w.]*)\.\$item(?:\.[a-zA-Z0-9_.]+)?/g, '$1');
+        return (normalizeOptionalArrayConditional(stripped) ?? stripped);
+    }
+    if (Array.isArray(template)) {
+        const collapsed = collapseOrphanedArraySpreads(template);
+        if (collapsed !== undefined)
+            return collapsed;
+        return template.map((item) => stripOrphanedItemSentinels(item));
+    }
+    if (template !== null && typeof template === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(template)) {
+            result[key] = stripOrphanedItemSentinels(value);
+        }
+        return result;
+    }
+    return template;
+}
+function normalizeOptionalArrayConditional(value) {
+    const match = value.match(/^\$\{has\(([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\) \? (\[.*), \1\] : (\[.*\])\}$/);
+    if (!match?.[1] || !match[2] || !match[3])
+        return undefined;
+    const [, basePath, truthyPrefix, fallbackList] = match;
+    if (`${truthyPrefix}]` !== fallbackList)
+        return undefined;
+    return `\${${fallbackList} + (has(${basePath}) ? ${basePath} : [])}`;
+}
+function findOrphanedItemBase(value) {
+    const serialized = JSON.stringify(value);
+    return serialized?.match(/([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.\$item/)?.[1];
+}
+function isDirectOrphanedItemElement(value, basePath) {
+    if (typeof value === 'string') {
+        return value.includes('${') && value.includes(`${basePath}.$item`);
+    }
+    if (Array.isArray(value))
+        return value.every((item) => isDirectOrphanedItemElement(item, basePath));
+    if (value && typeof value === 'object') {
+        const entries = Object.values(value);
+        return entries.length > 0 && entries.every((entry) => isDirectOrphanedItemElement(entry, basePath));
+    }
+    return false;
+}
+function collapseOrphanedArraySpreads(items) {
+    const parts = [];
+    let literals = [];
+    let sawSpread = false;
+    const flushLiterals = () => {
+        if (literals.length === 0)
+            return;
+        parts.push(celValueForTemplate(literals));
+        literals = [];
+    };
+    for (const item of items) {
+        const basePath = findOrphanedItemBase(item);
+        if (!basePath || !isDirectOrphanedItemElement(item, basePath)) {
+            literals.push(stripOrphanedItemSentinels(item));
+            continue;
+        }
+        sawSpread = true;
+        flushLiterals();
+        const serialized = JSON.stringify(item) ?? '';
+        parts.push(serialized.includes(`has(${basePath})`) ? `(has(${basePath}) ? ${basePath} : [])` : basePath);
+    }
+    if (!sawSpread)
+        return undefined;
+    flushLiterals();
+    return parts.length > 0 ? `\${${parts.join(' + ')}}` : undefined;
+}
+function celValueForTemplate(value) {
+    if (typeof value === 'string')
+        return celStringForTemplate(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return `[${value.map(celValueForTemplate).join(', ')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).map(([key, entryValue]) => `${JSON.stringify(key)}: ${celValueForTemplate(entryValue)}`);
+        return `{${entries.join(', ')}}`;
+    }
+    return 'null';
+}
+function celStringForTemplate(value) {
+    const fullCel = value.match(/^\$\{(.+)\}$/);
+    if (fullCel?.[1])
+        return fullCel[1];
+    if (!value.includes('${'))
+        return JSON.stringify(value);
+    const parts = [];
+    let cursor = 0;
+    const pattern = /\$\{([^}]+)\}/g;
+    for (const match of value.matchAll(pattern)) {
+        const index = match.index ?? 0;
+        if (index > cursor)
+            parts.push(JSON.stringify(value.slice(cursor, index)));
+        if (match[1])
+            parts.push(`string(${match[1]})`);
+        cursor = index + match[0].length;
+    }
+    if (cursor < value.length)
+        parts.push(JSON.stringify(value.slice(cursor)));
+    return parts.length > 0 ? parts.join(' + ') : '""';
+}
 // ---------------------------------------------------------------------------
 // Template override application
 // ---------------------------------------------------------------------------
@@ -309,32 +531,89 @@ function substituteForEachSentinels(template, basePath, varName) {
  * @param template - The processed template object (after processResourceReferences)
  * @param overrides - Array of {propertyPath, celExpression} overrides
  */
-function applyTemplateOverrides(template, overrides) {
+function applyTemplateOverrides(template, overrides, context) {
     for (const { propertyPath, celExpression } of overrides) {
         const parts = propertyPath.split('.');
         let target = template;
-        // Walk to the parent of the target property
+        // Walk to the parent of the target property. Object-branch ternaries can
+        // produce paths that only exist in the non-selected branch, so materialize
+        // missing containers instead of silently dropping those overrides.
         for (let i = 0; i < parts.length - 1; i++) {
             const part = parts[i];
             if (!part)
                 continue;
-            const next = target[part];
-            if (next && typeof next === 'object' && !Array.isArray(next)) {
+            if (!target)
+                break;
+            const next = Array.isArray(target) && /^\d+$/.test(part)
+                ? target[Number(part)]
+                : target[part];
+            if (next && typeof next === 'object') {
                 target = next;
             }
             else {
-                // Path doesn't exist in the template — skip this override
-                target = undefined;
-                break;
+                if (!celExpression.includes('omit()')) {
+                    target = undefined;
+                    break;
+                }
+                const nextPart = parts[i + 1];
+                const container = nextPart && /^\d+$/.test(nextPart) ? [] : {};
+                if (Array.isArray(target) && /^\d+$/.test(part)) {
+                    target[Number(part)] = container;
+                }
+                else {
+                    target[part] = container;
+                }
+                target = container;
             }
         }
         if (!target)
             continue;
         const lastKey = parts[parts.length - 1];
-        if (lastKey && lastKey in target) {
-            target[lastKey] = celExpression;
+        if (lastKey) {
+            const finalized = finalizeCelForKro(celExpression, context.nestedStatusCel, context);
+            if (Array.isArray(target) && /^\d+$/.test(lastKey)) {
+                target[Number(lastKey)] = finalized;
+            }
+            else {
+                target[lastKey] = finalized;
+            }
+        }
+    }
+}
+function toIdSuffix(resourceId) {
+    return resourceId.charAt(0).toUpperCase() + resourceId.slice(1);
+}
+function commonPrefixLength(left, right) {
+    const max = Math.min(left.length, right.length);
+    let index = 0;
+    while (index < max && left[index] === right[index]) {
+        index += 1;
+    }
+    return index;
+}
+function deriveResourceIdAliases(resourceId) {
+    const aliases = [];
+    for (const match of resourceId.matchAll(/\d+/g)) {
+        const suffix = resourceId.slice((match.index ?? 0) + match[0].length);
+        if (suffix && /^[A-Z]/.test(suffix)) {
+            aliases.push(suffix.charAt(0).toLowerCase() + suffix.slice(1));
         }
     }
+    return aliases;
+}
+function resolveDependsOnResourceId(dependencyId, currentResourceId, knownResourceIds) {
+    if (!knownResourceIds || knownResourceIds.has(dependencyId)) {
+        return dependencyId;
+    }
+    const suffix = toIdSuffix(dependencyId);
+    const candidates = Array.from(knownResourceIds).filter((resourceId) => resourceId.endsWith(suffix));
+    if (candidates.length === 0) {
+        return dependencyId;
+    }
+    if (candidates.length === 1) {
+        return candidates[0] ?? dependencyId;
+    }
+    return candidates.sort((left, right) => commonPrefixLength(right, currentResourceId) - commonPrefixLength(left, currentResourceId))[0] ?? dependencyId;
 }
 // ---------------------------------------------------------------------------
 // Resource entry builder
@@ -350,6 +629,10 @@ function applyTemplateOverrides(template, overrides) {
 function buildResourceEntry(id, resource, context) {
     const isExternalRef = readNonEnumerable(resource, '__externalRef');
     if (isExternalRef) {
+        const forEach = readForEachDimensions(resource);
+        if (forEach && forEach.length > 0) {
+            throw new Error(`Resource '${id}' cannot use both externalRef and forEach`);
+        }
         // externalRef resources: emit externalRef metadata, NOT template.
         // Use Object.getOwnPropertyDescriptor to bypass the Enhanced proxy's get trap
         // and read the actual underlying values. Going through the proxy would cause
@@ -362,20 +645,24 @@ function buildResourceEntry(id, resource, context) {
         // Process marker strings in metadata values to convert them to CEL expressions.
         // externalRef metadata.name may contain __KUBERNETES_REF__ markers from template
         // literals (e.g., `${spec.name}-db-${dbOwner}`).
-        const rawName = typeof rawMeta?.name === 'string' ? rawMeta.name : '';
-        const rawNamespace = typeof rawMeta?.namespace === 'string' ? rawMeta.namespace : undefined;
+        const rawName = rawMeta && 'name' in rawMeta ? rawMeta.name : '';
+        const rawNamespace = rawMeta && 'namespace' in rawMeta ? rawMeta.namespace : undefined;
+        const processedName = processResourceReferences(rawName, context);
+        const processedNamespace = processResourceReferences(rawNamespace, context);
         const extRef = {
             apiVersion: String(apiVersionDesc?.value ?? ''),
             kind: String(kindDesc?.value ?? ''),
             metadata: {
-                name: String(processResourceReferences(rawName)),
-                ...(rawNamespace && { namespace: String(processResourceReferences(rawNamespace)) }),
+                name: String(processedName ?? ''),
+                ...(rawNamespace !== undefined && processedNamespace !== undefined && {
+                    namespace: String(processedNamespace),
+                }),
             },
         };
         const entry = { id, externalRef: extRef };
         // externalRef can still have includeWhen (but NOT forEach — mutually exclusive)
         const rawIncludeWhen = readIncludeWhen(resource);
-        const includeWhen = resolveIncludeWhen(rawIncludeWhen);
+        const includeWhen = resolveIncludeWhen(rawIncludeWhen, context);
         if (includeWhen) {
             entry.includeWhen = includeWhen;
         }
@@ -412,24 +699,59 @@ function buildResourceEntry(id, resource, context) {
             }
         }
     }
+    // Orphaned $item sentinels — strip remaining $item references from non-forEach
+    // resources. When a schema array proxy is spread (`...spec.envFrom`) into a
+    // literal array, the proxy iterator yields $item-marked refs that never get
+    // matched by a forEach dimension. Collapse `path.$item.field` → `path` so
+    // the CEL expression references the whole array (valid CEL), rather than
+    // leaving `$item` which is not a valid CEL identifier.
+    if (entry.template && !hasForEach) {
+        entry.template = stripOrphanedItemSentinels(entry.template);
+    }
     // Template overrides — ternary expressions in factory args that evaluated to
     // literals at runtime but should be CEL conditionals in the output.
     const templateOverrides = readTemplateOverrides(resource);
     if (templateOverrides && templateOverrides.length > 0 && entry.template) {
-        applyTemplateOverrides(entry.template, templateOverrides);
+        applyTemplateOverrides(entry.template, templateOverrides, context);
     }
     // includeWhen — conditional resource creation (convert raw values to CEL)
     const rawIncludeWhen = readIncludeWhen(resource);
-    const includeWhen = resolveIncludeWhen(rawIncludeWhen);
+    const includeWhen = resolveIncludeWhen(rawIncludeWhen, context);
     if (includeWhen) {
         entry.includeWhen = includeWhen;
     }
     // readyWhen — resource readiness conditions (convert callbacks/refs to CEL)
     const rawReadyWhen = readReadyWhen(resource);
-    const readyWhen = resolveReadyWhen(rawReadyWhen, id, hasForEach);
+    const readyWhen = resolveReadyWhen(rawReadyWhen, id, hasForEach, context);
     if (readyWhen) {
         entry.readyWhen = readyWhen;
     }
+    // dependsOn — explicit dependency ordering via template annotation injection.
+    //
+    // KRO builds its dependency graph ONLY from template expression references.
+    // readyWhen only supports self-references (e.g., self.status.readyReplicas)
+    // — it CANNOT reference other resources. To establish a dependency edge
+    // between resources, we inject an annotation into the dependent resource's
+    // template that references the dependency's metadata.name. KRO scans ALL
+    // template fields for expressions and creates DAG edges from them.
+    //
+    // Once KRO sees the edge, it automatically waits for the dependency to be
+    // ready (all its own readyWhen conditions satisfied) before creating the
+    // dependent resource. No cross-resource readyWhen is needed.
+    const dependsOnDeps = getMetadataField(resource, 'dependsOn');
+    if (dependsOnDeps && dependsOnDeps.length > 0) {
+        const template = entry.template;
+        if (template) {
+            const metadata = (template.metadata ?? {});
+            const annotations = (metadata.annotations ?? {});
+            for (const dep of dependsOnDeps) {
+                const resolvedDependencyId = resolveDependsOnResourceId(dep.resourceId, id, context.resourceIds);
+                annotations[`typekro.dev/depends-on-${resolvedDependencyId}`] = `\${${resolvedDependencyId}.metadata.name}`;
+            }
+            metadata.annotations = annotations;
+            template.metadata = metadata;
+        }
+    }
     return entry;
 }
 // ---------------------------------------------------------------------------
@@ -438,7 +760,7 @@ function buildResourceEntry(id, resource, context) {
 /**
  * Serializes resources to Kro YAML (ResourceGraphDefinition).
  *
- * Supports Kro v0.8.x features:
+ * Supports Kro 0.9.1+ features:
  * - externalRef: Resources marked with __externalRef emit `externalRef` instead of `template`
  * - includeWhen: Non-enumerable includeWhen arrays are emitted per resource
  * - readyWhen: Non-enumerable readyWhen arrays are emitted per resource
@@ -447,21 +769,45 @@ function buildResourceEntry(id, resource, context) {
  * - allowBreakingChanges: Emits annotation on RGD metadata
  */
 export function serializeResourceGraphToYaml(name, resources, options, customSchema) {
+    // Extract optional-field omit list from schema metadata (if present).
+    // These fields get `has() ? ... : omit()` wrapping applied inline during
+    // ref-to-CEL conversion — no post-hoc YAML-string rewriting needed.
+    const schemaWithMeta = customSchema;
+    const omitFieldsList = schemaWithMeta?.__omitFields;
+    const omitFields = omitFieldsList && omitFieldsList.length > 0
+        ? new Set(omitFieldsList)
+        : undefined;
     // Create serialization context
+    const nestedStatusCel = schemaWithMeta?.__nestedStatusCel;
     const context = {
         celPrefix: 'resources', // Default Kro prefix, but now configurable
         ...(options?.namespace && { namespace: options.namespace }),
         resourceIdStrategy: 'deterministic',
+        ...(omitFields && { omitFields }),
+        ...(nestedStatusCel && { nestedStatusCel }),
     };
     // 1. Use embedded resource IDs and build dependency graph
     const resourceMap = new Map();
     const dependencies = [];
+    const resourceAliases = new Map();
     // 2. Process each resource and extract references
     for (const [resourceName, resource] of Object.entries(resources)) {
         // Use the embedded resource ID if available, otherwise generate deterministic one
         const resourceId = getResourceId(resource) ||
             generateDeterministicResourceId(resource.kind || 'Resource', resource.metadata?.name || resourceName, resource.metadata?.namespace || options?.namespace);
         resourceMap.set(resourceName, { id: resourceId, resource });
+        resourceAliases.set(resourceName, resourceId);
+        for (const alias of deriveResourceIdAliases(resourceId)) {
+            if (!resourceAliases.has(alias)) {
+                resourceAliases.set(alias, resourceId);
+            }
+        }
+        const aliases = getMetadataField(resource, 'resourceAliases');
+        if (aliases) {
+            for (const alias of aliases) {
+                resourceAliases.set(alias, resourceId);
+            }
+        }
         // Extract all ResourceReference objects from the resource
         const refs = extractResourceReferences(resource);
         for (const ref of refs) {
@@ -473,10 +819,12 @@ export function serializeResourceGraphToYaml(name, resources, options, customSch
             });
         }
     }
+    const knownResourceIds = new Set(Array.from(resourceMap.values(), ({ id }) => id));
+    context.resourceIds = knownResourceIds;
+    context.resourceAliases = resourceAliases;
     // 3. Build metadata with optional annotations
     const metadata = {
         name,
-        namespace: options?.namespace || 'default',
     };
     if (options?.allowBreakingChanges) {
         metadata.annotations = {