typekro 0.3.1 → 0.5.0

package/dist/core/serialization/core.js

@@ -4,22 +4,20 @@
  * This module provides the main serialization functions to convert
  * TypeScript resource definitions to Kro ResourceGraphDefinition YAML manifests.
  */
-import { DependencyResolver } from '../dependencies/index.js';
 import { createDirectResourceFactory } from '../deployment/direct-factory.js';
 import { createKroResourceFactory } from '../deployment/kro-factory.js';
-import { optimizeStatusMappings } from '../evaluation/cel-optimizer.js';
-import { analyzeStatusBuilderForToResourceGraph } from '../expressions/status-builder-analyzer.js';
-import { analyzeImperativeComposition } from '../expressions/imperative-analyzer.js';
+import { ensureError, ValidationError } from '../errors.js';
+import { analyzeCompositionBody, applyAnalysisToResources, } from '../expressions/composition/composition-analyzer.js';
+import { StatusBuilderAnalyzer } from '../expressions/factory/status-builder-analyzer.js';
 import { getComponentLogger } from '../logging/index.js';
-import { createSchemaProxy, externalRef } from '../references/index.js';
+import { setResourceId } from '../metadata/index.js';
+import { createExternalRefWithoutRegistration, createSchemaProxy } from '../references/index.js';
+import { getKindInfo, getSemanticCandidateKinds } from '../resources/factory-registry.js';
 import { validateResourceGraphDefinition } from '../validation/cel-validator.js';
+import { optimizeStatusMappings } from './cel-optimizer.js';
 import { generateKroSchemaFromArktype } from './schema.js';
+import { runStatusAnalysisPipeline } from './status-analysis-pipeline.js';
 import { serializeResourceGraphToYaml } from './yaml.js';
-import { StatusBuilderAnalyzer } from '../expressions/status-builder-analyzer.js';
-import { containsKubernetesRefs } from '../../utils/type-guards.js';
-import { isCelExpression } from '../../utils/type-guards.js';
-import { CelToJavaScriptMigrationHelper } from '../expressions/migration-helpers.js';
-import { CelConversionEngine } from '../expressions/cel-conversion-engine.js';
 /**
  * Separate Enhanced<> resources from deployment closures in the builder result
  */
@@ -43,303 +41,361 @@ function separateResourcesAndClosures(builderResult) {
     return { resources, closures };
 }
 /**
- * Detect and preserve existing CEL expressions for backward compatibility
+ * Create a minimal stub resource object for factory calls that were detected
+ * by AST analysis but didn't execute at runtime.
  *
- * This function recursively checks status mappings for existing CEL expressions
- * and preserves them without conversion, ensuring backward compatibility.
+ * This happens when a factory call is inside an if-branch that wasn't taken
+ * because the schema proxy's `Symbol.toPrimitive` value didn't match the comparison.
+ * The stub contains just enough info for YAML serialization to produce a valid
+ * resource entry with includeWhen/forEach directives.
  */
-function detectAndPreserveCelExpressions(statusMappings, preservedExpressions = {}, path = '') {
-    let hasExistingCel = false;
-    const preservedMappings = { ...preservedExpressions };
-    if (!statusMappings || typeof statusMappings !== 'object') {
-        return { hasExistingCel, preservedMappings };
-    }
-    for (const [key, value] of Object.entries(statusMappings)) {
-        const currentPath = path ? `${path}.${key}` : key;
-        if (isCelExpression(value)) {
-            // Found existing CEL expression - preserve it
-            hasExistingCel = true;
-            preservedMappings[currentPath] = value;
-        }
-        else if (value && typeof value === 'object' && !Array.isArray(value)) {
-            // Recursively check nested objects
-            const nestedResult = detectAndPreserveCelExpressions(value, preservedMappings, currentPath);
-            hasExistingCel = hasExistingCel || nestedResult.hasExistingCel;
-            Object.assign(preservedMappings, nestedResult.preservedMappings);
-        }
-    }
-    return { hasExistingCel, preservedMappings };
+function createStubResource(factoryName, resourceId) {
+    const kindInfo = getKindInfo(factoryName);
+    if (!kindInfo)
+        return null;
+    const stub = {
+        apiVersion: kindInfo.apiVersion,
+        kind: kindInfo.kind,
+        metadata: { name: resourceId, labels: {} },
+    };
+    // Store resource ID in WeakMap metadata
+    setResourceId(stub, resourceId);
+    return stub;
 }
+// =============================================================================
+// Re-exported helpers (canonical source: status-analysis-helpers.ts)
+// =============================================================================
+import { analyzeStatusMappingTypes, analyzeValueType, detectAndPreserveCelExpressions, isLikelyStaticObject, mergePreservedCelExpressions, } from './status-analysis-helpers.js';
+// =============================================================================
+// Internal helpers exported for testing
+// =============================================================================
+/** @internal Exported for testing only */
+export { separateResourcesAndClosures, createStubResource, detectAndPreserveCelExpressions, mergePreservedCelExpressions, analyzeStatusMappingTypes, analyzeValueType, isLikelyStaticObject, validateResourceGraphName, findResourceByKey, analyzeAndConvertStatusMappings, processCompositionBodyAnalysis, reanalyzeStatusForDirectFactory, wrapWithResourceGraphProxy, };
+// =============================================================================
+// Extracted helper: Resource graph name validation
+// =============================================================================
 /**
- * Check if a value contains any CelExpression objects
+ * Validate a resource graph name and return the Kubernetes-compatible form.
+ *
+ * @throws {ValidationError} if the name is empty, whitespace-only, not DNS-compliant,
+ *   or exceeds the 253-character Kubernetes limit.
+ * @returns The validated, lowercase-hyphenated Kubernetes name.
+ *
+ * @internal Exported for testing only
  */
-function containsCelExpressions(value) {
-    if (isCelExpression(value)) {
-        return true;
+function validateResourceGraphName(name) {
+    if (!name || typeof name !== 'string') {
+        throw new ValidationError(`Invalid resource graph name: ${JSON.stringify(name)}. Resource graph name must be a non-empty string.`, 'ResourceGraphDefinition', String(name), 'name', ['Provide a non-empty string for the resource graph name']);
     }
-    if (Array.isArray(value)) {
-        return value.some(item => containsCelExpressions(item));
+    const trimmedName = name.trim();
+    if (trimmedName.length === 0) {
+        throw new ValidationError(`Invalid resource graph name: Resource graph name cannot be empty or whitespace-only.`, 'ResourceGraphDefinition', name, 'name', ['Provide a non-whitespace resource graph name']);
     }
-    if (value && typeof value === 'object') {
-        return Object.values(value).some(val => containsCelExpressions(val));
+    const kubernetesName = trimmedName.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    if (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(kubernetesName)) {
+        throw new ValidationError(`Invalid resource graph name: "${name}" converts to "${kubernetesName}" which is not a valid Kubernetes resource name. Names must consist of lowercase alphanumeric characters or '-', and must start and end with an alphanumeric character.`, 'ResourceGraphDefinition', name, 'name', [
+            'Use lowercase alphanumeric characters and hyphens only',
+            'Must start and end with an alphanumeric character',
+        ]);
     }
-    return false;
+    if (kubernetesName.length > 253) {
+        throw new ValidationError(`Invalid resource graph name: "${name}" converts to "${kubernetesName}" which exceeds the 253 character limit for Kubernetes resource names.`, 'ResourceGraphDefinition', name, 'name', ['Shorten the resource graph name to stay under 253 characters']);
+    }
+    return kubernetesName;
 }
+// =============================================================================
+// Extracted helper: Resource key lookup (cross-composition access)
+// =============================================================================
 /**
- * Merge preserved CEL expressions with analyzed mappings
+ * Find a resource by key name in a resources map.
  *
- * This ensures that existing CEL expressions take precedence over
- * newly analyzed JavaScript expressions for backward compatibility.
+ * Implements multiple matching strategies for cross-composition magic proxy
+ * access (e.g. `composition.database`):
+ * 1. Direct match by generated resource ID (exact)
+ * 2. Smart pattern matching — name parts + kind-based (fuzzy, logged)
+ * 3. Case-insensitive match on resource ID (fuzzy, logged)
+ * 4. Partial matching — key parts contained in resource ID (fuzzy, logged)
+ *
+ * Strategies 2-4 emit a debug-level warning so users can diagnose unexpected
+ * cross-composition references. Strategy 1 is the only silent/exact match.
+ *
+ * @internal Exported for testing only
  */
-function mergePreservedCelExpressions(analyzedMappings, preservedMappings) {
-    const mergedMappings = { ...analyzedMappings };
-    // Preserved CEL expressions take precedence
-    for (const [path, celExpression] of Object.entries(preservedMappings)) {
-        // Handle nested paths by setting the value at the correct location
-        const pathParts = path.split('.');
-        let current = mergedMappings;
-        for (let i = 0; i < pathParts.length - 1; i++) {
-            const part = pathParts[i];
-            if (!part)
-                continue;
-            if (!current[part] || typeof current[part] !== 'object') {
-                current[part] = {};
+function findResourceByKey(key, resourcesWithKeys, logger) {
+    if (typeof key !== 'string')
+        return undefined;
+    // Strategy 1: Direct match by generated resource ID (exact — no warning)
+    if (resourcesWithKeys[key]) {
+        return resourcesWithKeys[key];
+    }
+    // Strategy 2: Smart pattern matching for common cases
+    const keyLower = key.toLowerCase();
+    const keyParts = key.split(/[-_]/).map((p) => p.toLowerCase());
+    for (const [resourceId, resource] of Object.entries(resourcesWithKeys)) {
+        const kind = resource.kind.toLowerCase();
+        let name = '';
+        if (resource.metadata.name && typeof resource.metadata.name === 'string') {
+            name = resource.metadata.name.toLowerCase();
+        }
+        else if (resource.metadata.name && typeof resource.metadata.name === 'object') {
+            continue;
+        }
+        const resourceIdLower = resourceId.toLowerCase();
+        const nameParts = name.split(/[-_]/).map((p) => p.toLowerCase());
+        const hasCommonParts = keyParts.some((keyPart) => nameParts.some((namePart) => keyPart.includes(namePart) || namePart.includes(keyPart)));
+        if (hasCommonParts) {
+            if (keyParts.includes(kind) ||
+                (keyParts.includes('deployment') && kind === 'deployment') ||
+                (keyParts.includes('service') && kind === 'service')) {
+                logger?.debug('findResourceByKey: fuzzy match (strategy 2: pattern+kind)', {
+                    requestedKey: key,
+                    matchedResourceId: resourceId,
+                    matchedKind: resource.kind,
+                });
+                return resource;
             }
-            current = current[part];
         }
-        const finalKey = pathParts[pathParts.length - 1];
-        if (finalKey) {
-            current[finalKey] = celExpression;
+        if (keyParts.includes(kind)) {
+            const nameInResourceId = nameParts.some((part) => resourceIdLower.includes(part));
+            if (nameInResourceId) {
+                logger?.debug('findResourceByKey: fuzzy match (strategy 2: kind+name)', {
+                    requestedKey: key,
+                    matchedResourceId: resourceId,
+                    matchedKind: resource.kind,
+                });
+                return resource;
+            }
+        }
+        // Semantic alias matching — delegated to the central FactoryRegistry.
+        // Custom factories can register their own aliases via registerFactory().
+        for (const part of keyParts) {
+            const candidateKinds = getSemanticCandidateKinds(part);
+            if (candidateKinds?.includes(kind)) {
+                logger?.debug('findResourceByKey: fuzzy match (strategy 2: semantic pattern)', {
+                    requestedKey: key,
+                    matchedResourceId: resourceId,
+                    matchedKind: resource.kind,
+                    semanticPattern: part,
+                });
+                return resource;
+            }
         }
     }
-    return mergedMappings;
+    // Strategy 3: Case-insensitive match on generated resource ID
+    for (const [resourceKey, resource] of Object.entries(resourcesWithKeys)) {
+        if (resourceKey.toLowerCase() === keyLower) {
+            logger?.debug('findResourceByKey: fuzzy match (strategy 3: case-insensitive)', {
+                requestedKey: key,
+                matchedResourceId: resourceKey,
+                matchedKind: resource.kind,
+            });
+            return resource;
+        }
+    }
+    // Strategy 4: Partial matching - find resources that contain key parts in their ID
+    for (const [resourceKey, resource] of Object.entries(resourcesWithKeys)) {
+        const resourceKeyLower = resourceKey.toLowerCase();
+        if (keyParts.some((part) => part.length > 2 && resourceKeyLower.includes(part))) {
+            logger?.debug('findResourceByKey: fuzzy match (strategy 4: partial key)', {
+                requestedKey: key,
+                matchedResourceId: resourceKey,
+                matchedKind: resource.kind,
+            });
+            return resource;
+        }
+    }
+    return undefined;
 }
 /**
- * Comprehensive analysis of status mappings to categorize different types of expressions
+ * Analyze a status builder function and convert JavaScript expressions to CEL.
  *
- * This function provides detailed analysis of status mappings to determine:
- * - Which fields contain KubernetesRef objects (need conversion)
- * - Which fields are existing CEL expressions (preserve as-is)
- * - Which fields are static values (no conversion needed)
- * - Which fields are complex expressions that might need analysis
+ * This encapsulates the full pipeline:
+ * 1. Execute the status builder in a context that returns KubernetesRef objects
+ * 2. If imperative, try status builder analysis or fall back to imperative analysis
+ * 3. If declarative, analyze directly
+ * 4. Detect and preserve existing CEL expressions
+ * 5. Convert KubernetesRef objects to CEL via CelConversionEngine
+ * 6. Log migration opportunities
+ *
+ * @internal Exported for testing only
  */
-function analyzeStatusMappingTypes(statusMappings, path = '') {
-    const kubernetesRefFields = [];
-    const celExpressionFields = [];
-    const staticValueFields = [];
-    const complexExpressionFields = [];
-    const analysisDetails = {};
-    if (!statusMappings || typeof statusMappings !== 'object') {
-        return {
-            kubernetesRefFields,
-            celExpressionFields,
-            staticValueFields,
-            complexExpressionFields,
-            analysisDetails
-        };
-    }
-    for (const [key, value] of Object.entries(statusMappings)) {
-        const currentPath = path ? `${path}.${key}` : key;
-        // Analyze the value type and requirements
-        const analysis = analyzeValueType(value);
-        analysisDetails[currentPath] = analysis;
-        switch (analysis.type) {
-            case 'kubernetesRef':
-                kubernetesRefFields.push(currentPath);
-                break;
-            case 'celExpression':
-                celExpressionFields.push(currentPath);
-                break;
-            case 'staticValue':
-                staticValueFields.push(currentPath);
-                break;
-            case 'complexExpression':
-                complexExpressionFields.push(currentPath);
-                break;
-        }
-        // Recursively analyze nested objects
-        if (value && typeof value === 'object' && !Array.isArray(value) && !isCelExpression(value) && !containsKubernetesRefs(value)) {
-            const nestedAnalysis = analyzeStatusMappingTypes(value, currentPath);
-            kubernetesRefFields.push(...nestedAnalysis.kubernetesRefFields);
-            celExpressionFields.push(...nestedAnalysis.celExpressionFields);
-            staticValueFields.push(...nestedAnalysis.staticValueFields);
-            complexExpressionFields.push(...nestedAnalysis.complexExpressionFields);
-            Object.assign(analysisDetails, nestedAnalysis.analysisDetails);
-        }
-    }
-    return {
-        kubernetesRefFields,
-        celExpressionFields,
-        staticValueFields,
-        complexExpressionFields,
-        analysisDetails
-    };
+function analyzeAndConvertStatusMappings(definition, statusBuilder, schema, resourcesWithKeys, serializationLogger) {
+    // Delegate to the decomposed pipeline (Phase 2.9).
+    // The pipeline produces the same result shape as the original function.
+    return runStatusAnalysisPipeline(definition, statusBuilder, schema, resourcesWithKeys, serializationLogger);
 }
 /**
- * Analyze a single value to determine its type and conversion requirements
+ * Analyze the composition function body for control flow patterns
+ * (if-statements -> includeWhen, for-of loops -> forEach, ternary -> template overrides,
+ * collection aggregates -> status overrides).
+ *
+ * This MUST run before validation because:
+ * 1. Stub resources need to exist before resource ID validation
+ * 2. Status overrides (e.g. .map().join()) need to replace raw marker strings
+ *    before CEL expression validation
+ *
+ * @internal Exported for testing only
  */
-function analyzeValueType(value) {
-    // Check for existing CEL expressions first (highest priority)
-    if (isCelExpression(value)) {
-        return {
-            type: 'celExpression',
-            value,
-            requiresConversion: false,
-            confidence: 1.0
-        };
-    }
-    // Check for KubernetesRef objects (need conversion)
-    if (containsKubernetesRefs(value)) {
-        return {
-            type: 'kubernetesRef',
-            value,
-            requiresConversion: true,
-            confidence: 1.0
-        };
-    }
-    // Check for primitive static values
-    if (value === null ||
-        value === undefined ||
-        typeof value === 'string' ||
-        typeof value === 'number' ||
-        typeof value === 'boolean') {
-        return {
-            type: 'staticValue',
-            value,
-            requiresConversion: false,
-            confidence: 1.0
-        };
-    }
-    // Check for arrays of static values
-    if (Array.isArray(value)) {
-        const hasKubernetesRefs = value.some(item => containsKubernetesRefs(item));
-        const hasCelExpressions = value.some(item => isCelExpression(item));
-        if (hasKubernetesRefs) {
-            return {
-                type: 'kubernetesRef',
-                value,
-                requiresConversion: true,
-                confidence: 0.9
-            };
-        }
-        else if (hasCelExpressions) {
-            return {
-                type: 'celExpression',
-                value,
-                requiresConversion: false,
-                confidence: 0.9
-            };
-        }
-        else {
-            return {
-                type: 'staticValue',
-                value,
-                requiresConversion: false,
-                confidence: 0.8
-            };
-        }
-    }
-    // Check for plain objects (might be complex expressions or static data)
-    if (value && typeof value === 'object') {
-        const hasKubernetesRefs = containsKubernetesRefs(value);
-        const hasCelExpressions = Object.values(value).some(v => isCelExpression(v));
-        if (hasKubernetesRefs) {
-            return {
-                type: 'kubernetesRef',
-                value,
-                requiresConversion: true,
-                confidence: 0.8
-            };
-        }
-        else if (hasCelExpressions) {
-            return {
-                type: 'celExpression',
-                value,
-                requiresConversion: false,
-                confidence: 0.8
-            };
-        }
-        else {
-            // Could be static data or complex expression - analyze further
-            const isLikelyStatic = isLikelyStaticObject(value);
-            if (isLikelyStatic) {
-                return {
-                    type: 'staticValue',
-                    value,
-                    requiresConversion: false,
-                    confidence: 0.7
-                };
+function processCompositionBodyAnalysis(statusMappings, resourcesWithKeys, analyzedStatusMappings, serializationLogger) {
+    let compositionAnalysis = null;
+    const analysisState = { appliedToResources: false };
+    const originalCompositionFnForAnalysis = statusMappings
+        ?.__originalCompositionFn;
+    if (originalCompositionFnForAnalysis) {
+        try {
+            const resourceIds = new Set(Object.keys(resourcesWithKeys));
+            compositionAnalysis = analyzeCompositionBody(originalCompositionFnForAnalysis, resourceIds);
+            // Create stub resources for factory calls that weren't registered at runtime
+            for (const unregistered of compositionAnalysis.unregisteredFactories) {
+                if (!resourceIds.has(unregistered.resourceId)) {
+                    const stub = createStubResource(unregistered.factoryName, unregistered.resourceId);
+                    if (stub) {
+                        resourcesWithKeys[unregistered.resourceId] = stub;
+                        resourceIds.add(unregistered.resourceId);
+                        serializationLogger.debug('Created stub resource for unregistered factory', {
+                            resourceId: unregistered.resourceId,
+                            factoryName: unregistered.factoryName,
+                        });
+                    }
+                }
             }
-            else {
-                return {
-                    type: 'complexExpression',
-                    value,
-                    requiresConversion: false, // Conservative - don't convert unless we're sure
-                    confidence: 0.5
-                };
+            // Apply status overrides before validation
+            if (compositionAnalysis.statusOverrides.length > 0) {
+                for (const override of compositionAnalysis.statusOverrides) {
+                    analyzedStatusMappings[override.propertyPath] = override.celExpression;
+                    serializationLogger.debug('Applied status override before validation', {
+                        propertyPath: override.propertyPath,
+                        celExpression: override.celExpression,
+                    });
+                }
             }
         }
+        catch (analysisError) {
+            serializationLogger.debug('Composition body analysis failed (non-fatal), proceeding without control flow detection', { error: ensureError(analysisError).message });
+        }
     }
-    // Unknown type - treat as complex expression
-    return {
-        type: 'complexExpression',
-        value,
-        requiresConversion: false,
-        confidence: 0.3
-    };
+    return { compositionAnalysis, analysisState };
 }
+// =============================================================================
+// Extracted helper: Direct factory status re-analysis
+// =============================================================================
 /**
- * Determine if an object is likely to be static data rather than an expression
+ * Re-analyze status mappings specifically for the direct factory pattern.
+ *
+ * When the factory mode is `'direct'`, the status mappings may need different
+ * treatment than the Kro pattern (which is the default analysis target).
+ *
+ * @internal Exported for testing only
  */
-function isLikelyStaticObject(obj) {
-    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
-        return false;
+function reanalyzeStatusForDirectFactory(analysisResults, analyzedStatusMappings, resourcesWithKeys, schema, serializationLogger) {
+    if (!analysisResults.hasKubernetesRefs) {
+        return analyzedStatusMappings;
     }
-    // Check if all values are primitive types
-    const values = Object.values(obj);
-    const allPrimitive = values.every(value => value === null ||
-        value === undefined ||
-        typeof value === 'string' ||
-        typeof value === 'number' ||
-        typeof value === 'boolean');
-    if (allPrimitive) {
-        return true;
+    try {
+        serializationLogger.debug('Re-analyzing status mappings for direct factory pattern');
+        const directStatusAnalyzer = new StatusBuilderAnalyzer(undefined, {
+            factoryType: 'direct',
+            performOptionalityAnalysis: true,
+            includeSourceMapping: true,
+        });
+        const directAnalysisResult = directStatusAnalyzer.analyzeReturnObjectWithMagicProxy(analysisResults.statusMappings, resourcesWithKeys, schema);
+        if (directAnalysisResult.errors.length === 0) {
+            const { preservedMappings: directPreservedMappings } = detectAndPreserveCelExpressions(analysisResults.statusMappings);
+            const result = mergePreservedCelExpressions(directAnalysisResult.statusMappings, directPreservedMappings);
+            serializationLogger.debug('Successfully re-analyzed status mappings for direct factory');
+            return result;
+        }
+    }
+    catch (error) {
+        serializationLogger.error('Failed to re-analyze status mappings for direct factory, using default analysis', ensureError(error));
     }
-    // Check for common static object patterns
-    const keys = Object.keys(obj);
-    const hasCommonStaticKeys = keys.some(key => ['name', 'id', 'type', 'kind', 'version', 'label', 'tag'].includes(key.toLowerCase()));
-    return hasCommonStaticKeys && values.length <= 10; // Reasonable size for static config
+    return analyzedStatusMappings;
 }
+// =============================================================================
+// Extracted helper: Cross-composition magic proxy
+// =============================================================================
 /**
- * Create a ResourceGraph from resources for deployment
+ * Wrap a base resource graph object with a Proxy that enables cross-composition
+ * resource access (e.g. `composition.database`).
+ *
+ * The Proxy intercepts property access for unknown keys and delegates to
+ * `findResourceByKey` to locate matching resources, then creates an external
+ * ref for them.
+ *
+ * @internal Exported for testing only
  */
-function _createResourceGraph(name, resources) {
-    const dependencyResolver = new DependencyResolver();
-    const resourceArray = Object.values(resources).map((resource) => ({
-        ...resource,
-        id: resource.id || resource.metadata?.name || 'unknown',
-    }));
-    // Type assertion needed because we're converting KubernetesResource to DeployableK8sResource
-    // This is safe because the deployment engine handles the conversion internally
-    const deployableResources = resourceArray;
-    const dependencyGraph = dependencyResolver.buildDependencyGraph(deployableResources);
-    // Convert to ResourceGraphResource format
-    const resourceGraphResources = deployableResources.map((resource) => ({
-        id: resource.id,
-        manifest: resource,
-    }));
-    return {
-        name,
-        resources: resourceGraphResources,
-        dependencyGraph,
-    };
+function wrapWithResourceGraphProxy(baseResourceGraph, resourcesWithKeys, logger) {
+    return new Proxy(baseResourceGraph, {
+        get(target, prop, receiver) {
+            if (prop in target) {
+                return Reflect.get(target, prop, receiver);
+            }
+            const matchingResource = findResourceByKey(prop, resourcesWithKeys, logger);
+            if (matchingResource?.metadata.name) {
+                return createExternalRefWithoutRegistration(matchingResource.apiVersion, matchingResource.kind, matchingResource.metadata.name, matchingResource.metadata.namespace);
+            }
+            return undefined;
+        },
+        ownKeys(target) {
+            return Reflect.ownKeys(target);
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            if (prop in target) {
+                return Reflect.getOwnPropertyDescriptor(target, prop);
+            }
+            const matchingResource = findResourceByKey(prop, resourcesWithKeys, logger);
+            if (matchingResource) {
+                return {
+                    configurable: true,
+                    enumerable: false,
+                    value: undefined,
+                };
+            }
+            return undefined;
+        },
+    });
 }
 // =============================================================================
 // NEW FACTORY PATTERN API
 // =============================================================================
 /**
- * Create a new typed resource graph with factory pattern support
- * This is the new API with definition-first parameter and separate builder functions
+ * Create a typed ResourceGraphDefinition (RGD) from a declarative definition,
+ * a resource builder, and a status builder.
+ *
+ * This is the primary API for defining Kubernetes compositions in TypeKro.
+ * The returned object contains the serialized YAML for the RGD and can be
+ * deployed via `deploy()` in both Direct and Kro modes.
+ *
+ * @typeParam TSpec - The arktype schema for the custom resource's spec
+ * @typeParam TStatus - The arktype schema for the custom resource's status
+ * @typeParam TResources - The shape of resources returned by the resource builder
+ *
+ * @param definition - The RGD metadata: name, apiVersion, kind, spec schema, status schema
+ * @param resourceBuilder - Function receiving a schema proxy, returns Kubernetes resources
+ * @param statusBuilder - Function receiving schema proxy + resources, returns status shape
+ * @param options - Optional serialization options (e.g., custom CEL prefix)
+ * @returns A `TypedResourceGraph` containing the serialized RGD and deploy/toYaml methods
+ *
+ * @example
+ * ```typescript
+ * const webapp = toResourceGraph(
+ *   {
+ *     name: 'webapp',
+ *     apiVersion: 'apps.example.com/v1alpha1',
+ *     kind: 'WebApp',
+ *     spec: type({ name: 'string', replicas: 'number' }),
+ *     status: type({ ready: 'boolean', url: 'string' }),
+ *   },
+ *   (schema) => ({
+ *     deploy: Deployment({ name: schema.spec.name, replicas: schema.spec.replicas }),
+ *     svc: Service({ name: schema.spec.name }),
+ *   }),
+ *   (schema, resources) => ({
+ *     ready: Cel.expr<boolean>(resources.deploy.status.readyReplicas, ' > 0'),
+ *     url: Cel.template('https://%s', schema.spec.name),
+ *   }),
+ * );
+ * ```
  */
 export function toResourceGraph(definition, 
 // The resourceBuilder is now defined as returning that specific shape
@@ -350,31 +406,24 @@ statusBuilder, options) {
     return createTypedResourceGraph(definition, resourceBuilder, statusBuilder, options);
 }
 /**
- * Create a typed resource graph implementation
+ * Create a typed resource graph implementation.
+ *
+ * Orchestrates the full pipeline:
+ * 1. Validate definition name
+ * 2. Execute resource builder to get Enhanced<> resources and closures
+ * 3. Analyze status builder and convert JS expressions to CEL
+ * 4. Analyze composition body for control flow (includeWhen/forEach)
+ * 5. Validate and optimize CEL expressions
+ * 6. Build the TypedResourceGraph result object
+ * 7. Wrap with cross-composition magic proxy
  */
 function createTypedResourceGraph(definition, resourceBuilder, statusBuilder, options) {
     const serializationLogger = getComponentLogger('resource-graph-serialization').child({
         name: definition.name,
     });
-    // Validate resource graph name early
-    if (!definition.name || typeof definition.name !== 'string') {
-        throw new Error(`Invalid resource graph name: ${JSON.stringify(definition.name)}. Resource graph name must be a non-empty string.`);
-    }
-    const trimmedName = definition.name.trim();
-    if (trimmedName.length === 0) {
-        throw new Error(`Invalid resource graph name: Resource graph name cannot be empty or whitespace-only.`);
-    }
-    // Validate that the name will convert to a valid Kubernetes resource name
-    const kubernetesName = trimmedName.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-    if (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(kubernetesName)) {
-        throw new Error(`Invalid resource graph name: "${definition.name}" converts to "${kubernetesName}" which is not a valid Kubernetes resource name. Names must consist of lowercase alphanumeric characters or '-', and must start and end with an alphanumeric character.`);
-    }
-    if (kubernetesName.length > 253) {
-        throw new Error(`Invalid resource graph name: "${definition.name}" converts to "${kubernetesName}" which exceeds the 253 character limit for Kubernetes resource names.`);
-    }
-    // Apply default apiVersion if not specified
-    // Note: This should be just the version part (e.g., 'v1alpha1'), not the full API version
-    // The full API version (kro.run/v1alpha1) is constructed when creating instances
+    // 1. Validate name
+    validateResourceGraphName(definition.name);
+    // 2. Build schema definition and execute resource builder
     const schemaDefinition = {
         apiVersion: definition.apiVersion || 'v1alpha1',
         kind: definition.kind,
@@ -383,268 +432,17 @@ function createTypedResourceGraph(definition, resourceBuilder, statusBuilder, op
     };
     const schema = createSchemaProxy();
     const builderResult = resourceBuilder(schema);
-    // Separate Enhanced<> resources from deployment closures
     const { resources: resourcesWithKeys, closures } = separateResourcesAndClosures(builderResult);
-    // NEW: Analyze status builder for JavaScript expressions with KubernetesRef detection
-    let statusMappings;
-    let analyzedStatusMappings = {};
-    let mappingAnalysis;
-    let imperativeAnalysisSucceeded = false;
-    try {
-        // Execute the status builder to get the return object
-        globalThis.__TYPEKRO_STATUS_BUILDER_CONTEXT__ = true;
-        try {
-            statusMappings = statusBuilder(schema, resourcesWithKeys);
-        }
-        finally {
-            delete globalThis.__TYPEKRO_STATUS_BUILDER_CONTEXT__;
-        }
-        // Check if this is from an imperative composition with original expressions
-        const originalCompositionFn = statusMappings.__originalCompositionFn;
-        // Debug logging removed for cleaner output
-        if (originalCompositionFn) {
-            serializationLogger.debug('Detected imperative composition, checking for existing KubernetesRef objects');
-            // First, check if the status object already contains KubernetesRef objects or CelExpression objects
-            // If so, we can use those directly instead of parsing the JavaScript source code
-            let hasKubernetesRefs = containsKubernetesRefs(statusMappings);
-            let hasCelExpressions = containsCelExpressions(statusMappings);
-            serializationLogger.debug('Imperative composition analysis', {
-                hasKubernetesRefs,
-                hasCelExpressions,
-                statusMappings: JSON.stringify(statusMappings, null, 2)
-            });
-            if (hasKubernetesRefs || hasCelExpressions) {
-                serializationLogger.debug('Status object already contains KubernetesRef objects or CelExpression objects, using direct analysis');
-                // Use the status builder analyzer to process the existing KubernetesRef objects
-                try {
-                    const statusBuilderAnalysis = analyzeStatusBuilderForToResourceGraph(statusBuilder, resourcesWithKeys, schema, 'kro');
-                    if (statusBuilderAnalysis.requiresConversion) {
-                        analyzedStatusMappings = statusBuilderAnalysis.statusMappings;
-                        imperativeAnalysisSucceeded = true;
-                        serializationLogger.debug('Using status builder analysis for imperative composition', {
-                            fieldCount: Object.keys(analyzedStatusMappings).length
-                        });
-                    }
-                    else {
-                        analyzedStatusMappings = statusMappings;
-                        serializationLogger.debug('No conversion required, using original status mappings');
-                    }
-                }
-                catch (statusAnalysisError) {
-                    serializationLogger.debug('Status builder analysis failed, falling back to imperative analysis', {
-                        error: statusAnalysisError.message
-                    });
-                    // Fall back to imperative analysis
-                    hasKubernetesRefs = false;
-                    hasCelExpressions = false;
-                }
-            }
-            if (!hasKubernetesRefs && !hasCelExpressions) {
-                serializationLogger.debug('No KubernetesRef objects or CelExpression objects found, analyzing original composition function');
-                // For imperative compositions, we need to analyze the original composition function
-                // to detect JavaScript expressions that should be converted to CEL
-                try {
-                    const imperativeAnalysis = analyzeImperativeComposition(originalCompositionFn, resourcesWithKeys, { factoryType: 'kro' });
-                    serializationLogger.debug('Imperative analysis result', {
-                        statusFieldCount: Object.keys(imperativeAnalysis.statusMappings).length,
-                        hasJavaScriptExpressions: imperativeAnalysis.hasJavaScriptExpressions,
-                        errorCount: imperativeAnalysis.errors.length
-                    });
-                    serializationLogger.debug('Imperative composition analysis complete', {
-                        statusFieldCount: Object.keys(imperativeAnalysis.statusMappings).length,
-                        hasJavaScriptExpressions: imperativeAnalysis.hasJavaScriptExpressions
-                    });
-                    if (imperativeAnalysis.hasJavaScriptExpressions) {
-                        analyzedStatusMappings = imperativeAnalysis.statusMappings;
-                        imperativeAnalysisSucceeded = true;
-                        serializationLogger.debug('Using analyzed imperative composition mappings with CEL expressions', {
-                            fieldCount: Object.keys(analyzedStatusMappings).length
-                        });
-                    }
-                    else {
-                        analyzedStatusMappings = statusMappings;
-                        serializationLogger.debug('No JavaScript expressions found, using original status mappings');
-                    }
-                }
-                catch (imperativeAnalysisError) {
-                    serializationLogger.debug('Imperative composition analysis failed, using executed status mappings', {
-                        error: imperativeAnalysisError.message
-                    });
-                    analyzedStatusMappings = statusMappings;
-                }
-            }
-        }
-        else {
-            // Regular status builder - try to analyze it directly
-            try {
-                const statusBuilderAnalysis = analyzeStatusBuilderForToResourceGraph(statusBuilder, resourcesWithKeys, schema, 'kro');
-                serializationLogger.debug('Status builder analysis complete', {
-                    statusFieldCount: Object.keys(statusBuilderAnalysis.statusMappings).length,
-                    dependencyCount: statusBuilderAnalysis.dependencies.length,
-                    hasJavaScriptExpressions: statusBuilderAnalysis.dependencies.length > 0
-                });
-                if (statusBuilderAnalysis.dependencies.length > 0) {
-                    analyzedStatusMappings = statusBuilderAnalysis.statusMappings;
-                    serializationLogger.debug('Using analyzed status mappings with CEL expressions', {
-                        fieldCount: Object.keys(analyzedStatusMappings).length
-                    });
-                }
-                else {
-                    analyzedStatusMappings = statusMappings;
-                }
-            }
-            catch (analysisError) {
-                serializationLogger.debug('Status builder analysis failed, using executed status mappings', {
-                    error: analysisError.message
-                });
-                analyzedStatusMappings = statusMappings;
-            }
-        }
-        // COMPREHENSIVE ANALYSIS: Analyze the final status mappings
-        mappingAnalysis = analyzeStatusMappingTypes(analyzedStatusMappings);
-        serializationLogger.debug('Final mapping analysis result', {
-            kubernetesRefFields: mappingAnalysis.kubernetesRefFields.length,
-            celExpressionFields: mappingAnalysis.celExpressionFields.length,
-            staticValueFields: mappingAnalysis.staticValueFields.length,
-            complexExpressionFields: mappingAnalysis.complexExpressionFields.length
-        });
-        serializationLogger.debug('Status mapping analysis complete', {
-            kubernetesRefFields: mappingAnalysis.kubernetesRefFields.length,
-            celExpressionFields: mappingAnalysis.celExpressionFields.length,
-            staticValueFields: mappingAnalysis.staticValueFields.length,
-            complexExpressionFields: mappingAnalysis.complexExpressionFields.length
-        });
-        // BACKWARD COMPATIBILITY: Detect and preserve existing CEL expressions
-        const { hasExistingCel, preservedMappings } = detectAndPreserveCelExpressions(statusMappings);
-        if (hasExistingCel) {
-            serializationLogger.debug('Found existing CEL expressions, preserving for backward compatibility', {
-                preservedCount: Object.keys(preservedMappings).length
-            });
-            // MIGRATION HELPER: Provide migration suggestions for existing CEL expressions
-            try {
-                const migrationHelper = new CelToJavaScriptMigrationHelper();
-                const migrationAnalysis = migrationHelper.analyzeMigrationOpportunities(statusMappings);
-                if (migrationAnalysis.migrationFeasibility.migratableExpressions > 0) {
-                    serializationLogger.info('Migration opportunities detected for CEL expressions', {
-                        totalExpressions: migrationAnalysis.migrationFeasibility.totalExpressions,
-                        migratableExpressions: migrationAnalysis.migrationFeasibility.migratableExpressions,
-                        overallConfidence: Math.round(migrationAnalysis.migrationFeasibility.overallConfidence * 100)
-                    });
-                    // Log migration suggestions for high-confidence migrations
-                    const highConfidenceSuggestions = migrationAnalysis.suggestions.filter(s => s.confidence >= 0.8 && s.isSafe);
-                    if (highConfidenceSuggestions.length > 0) {
-                        serializationLogger.info('High-confidence migration suggestions available', {
-                            suggestions: highConfidenceSuggestions.map(s => ({
-                                original: s.originalCel,
-                                suggested: s.suggestedJavaScript,
-                                confidence: Math.round(s.confidence * 100)
-                            }))
-                        });
-                    }
-                }
-            }
-            catch (migrationError) {
-                serializationLogger.warn('Failed to analyze migration opportunities', migrationError);
-            }
-        }
-        // The issue is that JavaScript expressions are evaluated before we can analyze them
-        // We need to re-execute the status builder with a special proxy that intercepts expressions
-        // and converts them to CEL expressions before evaluation
-        // For now, let's use a simpler approach: detect KubernetesRef objects in the raw status mappings
-        // and convert them directly to CEL expressions
-        const celConversionEngine = new CelConversionEngine();
-        // Convert the status mappings to CEL expressions for Kro factories
-        const convertedStatusMappings = {};
-        let hasConversions = false;
-        for (const [fieldName, fieldValue] of Object.entries(statusMappings)) {
-            // Check if this field contains KubernetesRef objects
-            if (containsKubernetesRefs(fieldValue)) {
-                // Convert to CEL expression
-                const conversionResult = celConversionEngine.convertValue(fieldValue, { factoryType: 'kro', factoryName: definition.name, analysisEnabled: true }, { factoryType: 'kro', preserveStatic: false });
-                if (conversionResult.wasConverted) {
-                    convertedStatusMappings[fieldName] = conversionResult.converted;
-                    hasConversions = true;
-                    serializationLogger.debug('Converted field to CEL expression', {
-                        fieldName,
-                        strategy: conversionResult.strategy,
-                        referencesConverted: conversionResult.metrics.referencesConverted
-                    });
-                }
-                else {
-                    convertedStatusMappings[fieldName] = fieldValue;
-                }
-            }
-            else {
-                // Keep static values as-is
-                convertedStatusMappings[fieldName] = fieldValue;
-            }
-        }
-        if (hasConversions) {
-            // Only overwrite if imperative analysis hasn't already provided CEL expressions
-            if (!imperativeAnalysisSucceeded) {
-                // Merge converted CEL expressions with preserved ones (preserved take precedence)
-                analyzedStatusMappings = mergePreservedCelExpressions(convertedStatusMappings, preservedMappings);
-            }
-            serializationLogger.debug('Successfully converted JavaScript expressions to CEL', {
-                convertedFields: Object.keys(convertedStatusMappings).filter(key => convertedStatusMappings[key] !== statusMappings[key]).length,
-                preservedFields: Object.keys(preservedMappings).length,
-                staticFields: mappingAnalysis.staticValueFields.length
-            });
-        }
-        else {
-            // No KubernetesRef objects found, but may have existing CEL expressions or static values
-            if (hasExistingCel) {
-                // Only overwrite if imperative analysis hasn't already provided CEL expressions
-                if (!imperativeAnalysisSucceeded) {
-                    // Merge original mappings with preserved CEL expressions
-                    analyzedStatusMappings = mergePreservedCelExpressions(statusMappings, preservedMappings);
-                }
-                serializationLogger.debug('Preserved existing CEL expressions without conversion', {
-                    preservedFields: Object.keys(preservedMappings).length,
-                    staticFields: mappingAnalysis.staticValueFields.length,
-                    complexFields: mappingAnalysis.complexExpressionFields.length
-                });
-            }
-            else {
-                // No KubernetesRef objects or CEL expressions, use status mappings as-is
-                if (!imperativeAnalysisSucceeded) {
-                    analyzedStatusMappings = statusMappings;
-                }
-                serializationLogger.debug('Status builder contains only static values and complex expressions', {
-                    staticFields: mappingAnalysis.staticValueFields.length,
-                    complexFields: mappingAnalysis.complexExpressionFields.length,
-                    totalFields: Object.keys(mappingAnalysis.analysisDetails).length
-                });
-            }
-        }
-    }
-    catch (error) {
-        serializationLogger.error('Failed to analyze status builder', error);
-        // Fallback to executing status builder normally
-        globalThis.__TYPEKRO_STATUS_BUILDER_CONTEXT__ = true;
-        try {
-            statusMappings = statusBuilder(schema, resourcesWithKeys);
-        }
-        finally {
-            delete globalThis.__TYPEKRO_STATUS_BUILDER_CONTEXT__;
-        }
-        analyzedStatusMappings = statusMappings;
-        // Create empty analysis for fallback
-        mappingAnalysis = {
-            kubernetesRefFields: [],
-            celExpressionFields: [],
-            staticValueFields: [],
-            complexExpressionFields: [],
-            analysisDetails: {}
-        };
-    }
-    // Validate resource IDs and CEL expressions
+    // 3. Analyze status builder and convert JS expressions to CEL
+    const { statusMappings, analyzedStatusMappings, mappingAnalysis } = analyzeAndConvertStatusMappings(definition, statusBuilder, schema, resourcesWithKeys, serializationLogger);
+    // 4. Analyze composition body for control flow patterns (must run before validation)
+    const { compositionAnalysis, analysisState } = processCompositionBodyAnalysis(statusMappings, resourcesWithKeys, analyzedStatusMappings, serializationLogger);
+    // 5. Validate resource IDs and CEL expressions
     const validation = validateResourceGraphDefinition(resourcesWithKeys, analyzedStatusMappings);
     if (!validation.isValid) {
         const errorMessages = validation.errors.map((err) => `${err.field}: ${err.error}`).join('\n');
-        throw new Error(`ResourceGraphDefinition validation failed:\n${errorMessages}`);
+        throw new ValidationError(`ResourceGraphDefinition validation failed:\n${errorMessages}`, 'ResourceGraphDefinition', definition.name, undefined, ['Fix the validation errors listed above']);
     }
-    // Log warnings if any
     if (validation.warnings.length > 0) {
         serializationLogger.warn('ResourceGraphDefinition validation warnings', {
             warnings: validation.warnings.map((w) => ({
@@ -657,183 +455,86 @@ function createTypedResourceGraph(definition, resourceBuilder, statusBuilder, op
     // Evaluate and optimize CEL expressions
     const evaluationContext = { resources: resourcesWithKeys, schema };
     const { mappings: optimizedStatusMappings, optimizations } = optimizeStatusMappings(analyzedStatusMappings, evaluationContext);
-    // Log optimizations if any
     if (optimizations.length > 0) {
         serializationLogger.info('CEL expression optimizations applied', { optimizations });
     }
-    // schemaDefinition is already created above with default apiVersion handling
-    /**
-     * Find a resource by key name in the resources map
-     * This enables cross-composition magic proxy access like composition.database
-     */
-    function findResourceByKey(key) {
-        if (typeof key !== 'string')
-            return undefined;
-        // Strategy 1: Direct match by generated resource ID
-        if (resourcesWithKeys[key]) {
-            return resourcesWithKeys[key];
-        }
-        // Strategy 2: Smart pattern matching for common cases
-        const keyLower = key.toLowerCase();
-        const keyParts = key.split(/[-_]/).map((p) => p.toLowerCase()); // Split on hyphens and underscores
-        for (const [resourceId, resource] of Object.entries(resourcesWithKeys)) {
-            const kind = resource.kind.toLowerCase();
-            const name = resource.metadata.name?.toLowerCase() || '';
-            const resourceIdLower = resourceId.toLowerCase();
-            // Pattern 1: Key parts match resource name parts
-            // e.g., 'my-deployment' matches 'test-deployment' if 'deployment' appears in both
-            const nameParts = name.split(/[-_]/).map((p) => p.toLowerCase());
-            const hasCommonParts = keyParts.some((keyPart) => nameParts.some((namePart) => keyPart.includes(namePart) || namePart.includes(keyPart)));
-            if (hasCommonParts) {
-                // Also check if the kinds match logically
-                if (keyParts.includes(kind) ||
-                    (keyParts.includes('deployment') && kind === 'deployment') ||
-                    (keyParts.includes('service') && kind === 'service')) {
-                    return resource;
-                }
-            }
-            // Pattern 2: Key contains kind and resource ID contains resource name parts
-            if (keyParts.includes(kind)) {
-                const nameInResourceId = nameParts.some((part) => resourceIdLower.includes(part));
-                if (nameInResourceId) {
-                    return resource;
-                }
-            }
-            // Pattern 3: Common semantic patterns
-            const semanticPatterns = {
-                database: ['deployment', 'statefulset'],
-                db: ['deployment', 'statefulset'],
-                cache: ['deployment', 'statefulset'],
-                redis: ['deployment', 'statefulset'],
-                service: ['service'],
-                svc: ['service'],
-                ingress: ['ingress'],
-                configmap: ['configmap'],
-                secret: ['secret'],
-            };
-            for (const [pattern, kinds] of Object.entries(semanticPatterns)) {
-                if (keyParts.includes(pattern) && kinds.includes(kind)) {
-                    return resource;
-                }
-            }
-        }
-        // Strategy 3: Case-insensitive match on generated resource ID
-        for (const [resourceKey, resource] of Object.entries(resourcesWithKeys)) {
-            if (resourceKey.toLowerCase() === keyLower) {
-                return resource;
-            }
-        }
-        // Strategy 4: Partial matching - find resources that contain key parts in their ID
-        for (const [resourceKey, resource] of Object.entries(resourcesWithKeys)) {
-            const resourceKeyLower = resourceKey.toLowerCase();
-            if (keyParts.some((part) => part.length > 2 && resourceKeyLower.includes(part))) {
-                return resource;
-            }
-        }
-        return undefined;
-    }
-    // Create the base TypedResourceGraph object
+    // 6. Build the composition re-execution function for direct factory
+    const declarativeCompositionFn = (spec) => {
+        const actualSchema = { spec, status: {} };
+        const resources = resourceBuilder(actualSchema);
+        return statusBuilder(actualSchema, resources);
+    };
+    // 7. Assemble the TypedResourceGraph result object
+    const uniqueResourcesSet = new Set(Object.values(resourcesWithKeys));
     const baseResourceGraph = {
         name: definition.name,
-        resources: Object.values(resourcesWithKeys),
+        resources: Array.from(uniqueResourcesSet),
         schema,
-        // Store closures for access during factory creation
         closures,
-        // Store analysis results for factory-specific processing
+        _compositionFn: declarativeCompositionFn,
+        _definition: definition,
         _analysisResults: {
             mappingAnalysis,
             hasKubernetesRefs: mappingAnalysis.kubernetesRefFields.length > 0,
             statusMappings,
-            analyzedStatusMappings
+            analyzedStatusMappings,
         },
         factory(mode, factoryOptions) {
             if (mode === 'direct') {
-                // For direct factory, we need to re-analyze status mappings with direct factory context
-                let directStatusMappings = analyzedStatusMappings;
-                if (this._analysisResults.hasKubernetesRefs) {
-                    try {
-                        serializationLogger.debug('Re-analyzing status mappings for direct factory pattern');
-                        const directStatusAnalyzer = new StatusBuilderAnalyzer(undefined, {
-                            factoryType: 'direct',
-                            performOptionalityAnalysis: true,
-                            includeSourceMapping: true
-                        });
-                        const directAnalysisResult = directStatusAnalyzer.analyzeReturnObjectWithMagicProxy(this._analysisResults.statusMappings, resourcesWithKeys, schema);
-                        if (directAnalysisResult.errors.length === 0) {
-                            // Merge with preserved CEL expressions
-                            const { preservedMappings: directPreservedMappings } = detectAndPreserveCelExpressions(this._analysisResults.statusMappings);
-                            directStatusMappings = mergePreservedCelExpressions(directAnalysisResult.statusMappings, directPreservedMappings);
-                            serializationLogger.debug('Successfully re-analyzed status mappings for direct factory');
-                        }
-                    }
-                    catch (error) {
-                        serializationLogger.warn('Failed to re-analyze status mappings for direct factory, using default analysis', error);
-                    }
-                }
-                const directFactory = createDirectResourceFactory(definition.name, resourcesWithKeys, schemaDefinition, statusBuilder, {
+                const directStatusMappings = reanalyzeStatusForDirectFactory(this._analysisResults, analyzedStatusMappings, resourcesWithKeys, schema, serializationLogger);
+                return createDirectResourceFactory(definition.name, resourcesWithKeys, schemaDefinition, statusBuilder, {
                     ...factoryOptions,
                     closures,
-                    // Pass the factory-specific status mappings
-                    statusMappings: directStatusMappings
+                    statusMappings: directStatusMappings,
+                    compositionFn: declarativeCompositionFn,
+                    compositionDefinition: definition,
                 });
-                return directFactory;
             }
             else if (mode === 'kro') {
-                // For Kro factory, use the already analyzed status mappings (which default to Kro pattern)
-                const kroFactory = createKroResourceFactory(definition.name, resourcesWithKeys, schemaDefinition, analyzedStatusMappings, {
+                return createKroResourceFactory(definition.name, resourcesWithKeys, schemaDefinition, analyzedStatusMappings, {
                     ...factoryOptions,
                     closures,
-                    // Indicate this is for Kro factory pattern
-                    factoryType: 'kro'
+                    factoryType: 'kro',
                 });
-                return kroFactory;
             }
             else {
-                throw new Error(`Unsupported factory mode: ${mode}`);
+                throw new ValidationError(`Unsupported factory mode: ${mode}`, 'ResourceGraphDefinition', definition.name, 'mode', ['Use "kro" or "direct" as the factory mode']);
             }
         },
         toYaml() {
-            // Generate ResourceGraphDefinition YAML with user-defined status mappings
-            const kroSchema = generateKroSchemaFromArktype(definition.name, schemaDefinition, resourcesWithKeys, optimizedStatusMappings);
-            return serializeResourceGraphToYaml(definition.name, resourcesWithKeys, options, kroSchema);
-        },
-    };
-    // Wrap with cross-composition magic proxy for resource access
-    return new Proxy(baseResourceGraph, {
-        get(target, prop, receiver) {
-            // Handle existing properties normally
-            if (prop in target) {
-                return Reflect.get(target, prop, receiver);
-            }
-            // For unknown properties, check if it's a resource key and create external ref
-            const matchingResource = findResourceByKey(prop);
-            if (matchingResource?.metadata.name) {
-                return externalRef(matchingResource.apiVersion, matchingResource.kind, matchingResource.metadata.name, matchingResource.metadata.namespace);
+            // Apply composition body analysis results (guard: only once)
+            if (compositionAnalysis && !analysisState.appliedToResources) {
+                analysisState.appliedToResources = true;
+                if (compositionAnalysis.resources.size > 0 ||
+                    compositionAnalysis.templateOverrides.size > 0) {
+                    applyAnalysisToResources(resourcesWithKeys, compositionAnalysis);
+                    serializationLogger.debug('Applied composition body analysis', {
+                        analyzedResources: compositionAnalysis.resources.size,
+                        templateOverrides: compositionAnalysis.templateOverrides.size,
+                        errors: compositionAnalysis.errors.length,
+                    });
+                }
             }
-            // Return undefined for non-existent properties (standard JavaScript behavior)
-            return undefined;
-        },
-        // Ensure proper enumeration of properties
-        ownKeys(target) {
-            return Reflect.ownKeys(target);
-        },
-        // Ensure proper property descriptor handling
-        getOwnPropertyDescriptor(target, prop) {
-            // For existing properties, return normal descriptor
-            if (prop in target) {
-                return Reflect.getOwnPropertyDescriptor(target, prop);
+            const kroSchema = generateKroSchemaFromArktype(definition.name, schemaDefinition, resourcesWithKeys, optimizedStatusMappings);
+            if (definition.group) {
+                kroSchema.group = definition.group;
             }
-            // For resource properties, indicate they exist but are not enumerable
-            const matchingResource = findResourceByKey(prop);
-            if (matchingResource) {
-                return {
-                    configurable: true,
-                    enumerable: false, // Don't enumerate resource properties in for..in loops
-                    value: undefined, // Value will be computed by get trap
-                };
+            // Inject status overrides into schema status section.
+            // Convert "..." to '...' in CEL string literals for YAML compatibility.
+            const statusOverrides = compositionAnalysis?.statusOverrides ?? [];
+            if (statusOverrides.length > 0) {
+                if (!kroSchema.status) {
+                    kroSchema.status = {};
+                }
+                for (const override of statusOverrides) {
+                    const yamlSafe = override.celExpression.replace(/"([^"\\]*)"/g, "'$1'");
+                    kroSchema.status[override.propertyPath] = yamlSafe;
+                }
             }
-            return undefined;
+            return serializeResourceGraphToYaml(definition.name, resourcesWithKeys, options, kroSchema);
         },
-    });
+    };
+    // 8. Wrap with cross-composition magic proxy
+    return wrapWithResourceGraphProxy(baseResourceGraph, resourcesWithKeys, serializationLogger);
 }
 //# sourceMappingURL=core.js.map