typekro 0.4.0 → 0.7.0

package/dist/core/deployment/direct-factory.js

@@ -4,12 +4,18 @@
  * This factory handles direct deployment of Kubernetes resources using TypeKro's
  * internal dependency resolution engine, without requiring the Kro controller.
  */
-import { toCamelCase } from '../../utils/helpers.js';
+import * as yaml from 'js-yaml';
+import { toCamelCase } from '../../utils/string.js';
+import { isCelExpression, isKubernetesRef } from '../../utils/type-guards.js';
+import { createCompositionContext, runWithCompositionContext } from '../composition/context.js';
+import { DEFAULT_DELETE_TIMEOUT, DEFAULT_FAST_POLL_INTERVAL, DEFAULT_MAX_RECURSION_DEPTH, } from '../config/defaults.js';
 import { DependencyResolver } from '../dependencies/index.js';
-import { isCelExpression, isKubernetesRef } from '../dependencies/type-guards.js';
-import { createKubernetesClientProvider, createKubernetesClientProviderWithKubeConfig, } from '../kubernetes/client-provider.js';
+import { ensureError, ResourceGraphFactoryError, TypeKroError, ValidationError, } from '../errors.js';
 import { getComponentLogger } from '../logging/index.js';
+import { copyResourceMetadata, getResourceId, setResourceId } from '../metadata/index.js';
+import { KubernetesClientManager } from './client-provider-manager.js';
 import { DirectDeploymentEngine } from './engine.js';
+import { synthesizeNestedCompositionStatus } from './nested-composition-status.js';
 import { ResourceReadinessChecker } from './readiness.js';
 import { createRollbackManagerWithKubeConfig } from './rollback-manager.js';
 import { generateInstanceName } from './shared-utilities.js';
@@ -34,7 +40,7 @@ export class DirectResourceFactoryImpl {
     factoryOptions;
     deployedInstances = new Map();
     logger = getComponentLogger('direct-factory');
-    clientProvider;
+    clientManager;
     constructor(name, resources, schemaDefinition, statusBuilder, options = {}) {
         this.name = name;
         this.namespace = options.namespace || 'default';
@@ -45,36 +51,13 @@ export class DirectResourceFactoryImpl {
         this.schemaDefinition = schemaDefinition;
         this.statusBuilder = statusBuilder;
         this.factoryOptions = options;
-        // Don't initialize client provider in constructor - do it lazily when needed
-        // This allows tests to create factories without requiring a kubeconfig
+        this.clientManager = new KubernetesClientManager(options);
     }
     /**
      * Get or create the Kubernetes client provider (lazy initialization)
      */
     getClientProvider() {
-        if (!this.clientProvider) {
-            this.clientProvider = this.createClientProvider(this.factoryOptions);
-        }
-        return this.clientProvider;
-    }
-    /**
-     * Create and configure the Kubernetes client provider
-     */
-    createClientProvider(options) {
-        // If a pre-configured kubeConfig is provided, use it directly
-        if (options.kubeConfig) {
-            this.logger.debug('Using pre-configured KubeConfig from factory options');
-            return createKubernetesClientProviderWithKubeConfig(options.kubeConfig);
-        }
-        // Create client provider with configuration from factory options
-        const clientConfig = {
-            ...(options.skipTLSVerify !== undefined && { skipTLSVerify: options.skipTLSVerify }),
-            // Add other configuration options as needed
-        };
-        this.logger.debug('Creating new KubernetesClientProvider with configuration', {
-            skipTLSVerify: clientConfig.skipTLSVerify,
-        });
-        return createKubernetesClientProvider(clientConfig);
+        return this.clientManager.getClientProvider();
     }
     /**
      * Get or create the deployment engine using the centralized client provider
@@ -86,7 +69,8 @@ export class DirectResourceFactoryImpl {
             const clientProvider = this.getClientProvider();
             const kubeConfig = clientProvider.getKubeConfig();
             // Create the deployment engine with the provider's KubeConfig
-            this.deploymentEngine = new DirectDeploymentEngine(kubeConfig, undefined, undefined, 'direct');
+            // Pass HTTP timeout configuration if provided in factory options
+            this.deploymentEngine = new DirectDeploymentEngine(kubeConfig, undefined, undefined, 'direct', this.factoryOptions.httpTimeouts);
             this.logger.debug('DirectDeploymentEngine created successfully', {
                 currentContext: kubeConfig.getCurrentContext(),
                 server: kubeConfig.getCurrentCluster()?.server,
@@ -112,7 +96,7 @@ export class DirectResourceFactoryImpl {
         if (instance.metadata?.annotations?.['typekro.io/deployment-status'] === 'failed') {
             const errorMessage = instance.metadata?.annotations?.['typekro.io/deployment-error'] ||
                 'Deployment failed - check logs for details';
-            throw new Error(errorMessage);
+            throw new ResourceGraphFactoryError(errorMessage, this.name, 'deployment');
         }
         // Track the deployed instance
         const instanceName = this.generateInstanceName(spec);
@@ -144,25 +128,117 @@ export class DirectResourceFactoryImpl {
     async deleteInstance(name) {
         const instance = this.deployedInstances.get(name);
         if (!instance) {
-            throw new Error(`Instance not found: ${name}`);
+            throw new TypeKroError(`Instance not found: ${name}`, 'INSTANCE_NOT_FOUND', {
+                instanceName: name,
+                factoryName: this.name,
+            });
         }
         try {
-            // Use the deployment engine to delete the resources
+            // Use the deployment engine to delete resources using actual deployment ID
             const engine = this.getDeploymentEngine();
-            await engine.rollback(`${this.name}-${name}`);
+            const deploymentId = instance.metadata?.annotations?.['typekro.io/deployment-id'];
+            if (!deploymentId) {
+                throw new TypeKroError(`Instance ${name} does not have a deployment ID annotation. Cannot perform cleanup.`, 'MISSING_DEPLOYMENT_ID', { instanceName: name, factoryName: this.name });
+            }
+            const rollbackResult = await engine.rollback(deploymentId);
+            // Wait for any namespaces to be fully deleted before returning.
+            // Namespace deletion is asynchronous (enters "Terminating" phase) and can
+            // cause race conditions if the caller immediately re-creates resources.
+            const deletedNamespaces = rollbackResult.rolledBackResources
+                .filter((r) => r.startsWith('Namespace/'))
+                .map((r) => r.split('/')[1]);
+            if (deletedNamespaces.length > 0) {
+                // Delete PVCs in namespaces before waiting — StatefulSet PVCs have
+                // finalizers that block namespace termination until volumes are released.
+                const kubeConfig = this.getClientProvider().getKubeConfig();
+                try {
+                    const { CoreV1Api } = await import('@kubernetes/client-node');
+                    const coreApi = kubeConfig.makeApiClient(CoreV1Api);
+                    for (const ns of deletedNamespaces) {
+                        try {
+                            const pvcs = await coreApi.listNamespacedPersistentVolumeClaim({ namespace: ns });
+                            if (pvcs.items.length > 0) {
+                                this.logger.info('Deleting PVCs to unblock namespace termination', {
+                                    namespace: ns, count: pvcs.items.length,
+                                });
+                            }
+                            for (const pvc of pvcs.items) {
+                                const pvcName = pvc.metadata?.name;
+                                if (!pvcName)
+                                    continue;
+                                await coreApi.deleteNamespacedPersistentVolumeClaim({
+                                    name: pvcName,
+                                    namespace: ns,
+                                }).catch((err) => {
+                                    this.logger.info('PVC delete failed', {
+                                        pvc: pvcName, namespace: ns, error: String(err),
+                                    });
+                                });
+                            }
+                        }
+                        catch {
+                            // Namespace may already be gone
+                        }
+                    }
+                }
+                catch {
+                    // PVC cleanup is best-effort
+                }
+                const k8sApi = engine.getKubernetesApi();
+                const deleteTimeout = this.factoryOptions.timeout ?? DEFAULT_DELETE_TIMEOUT;
+                await this.waitForNamespaceDeletion(k8sApi, deletedNamespaces, deleteTimeout);
+            }
             // Remove from tracking
             this.deployedInstances.delete(name);
         }
         catch (error) {
             // If the deployment isn't found in the state, it may have already been cleaned up
             // or the deployment ID format changed. Log and remove from tracking anyway.
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = ensureError(error).message;
             if (errorMessage.includes('not found') || errorMessage.includes('Cannot rollback')) {
                 this.deployedInstances.delete(name);
                 // Don't throw - the instance is already gone
                 return;
             }
-            throw new Error(`Failed to delete instance ${name}: ${errorMessage}`);
+            throw new ResourceGraphFactoryError(`Failed to delete instance ${name}: ${errorMessage}`, this.name, 'cleanup');
+        }
+    }
+    /**
+     * Poll until the given namespaces no longer exist (HTTP 404).
+     * Namespaces enter a "Terminating" phase on deletion and may take time
+     * to fully disappear, especially when finalizers or remaining resources
+     * are involved.
+     */
+    async waitForNamespaceDeletion(k8sApi, namespaces, timeout) {
+        const pollInterval = DEFAULT_FAST_POLL_INTERVAL;
+        for (const ns of namespaces) {
+            // Each namespace gets its own timeout budget
+            const nsStartTime = Date.now();
+            while (Date.now() - nsStartTime < timeout) {
+                try {
+                    await k8sApi.read({
+                        apiVersion: 'v1',
+                        kind: 'Namespace',
+                        metadata: { name: ns },
+                    });
+                    // Namespace still exists (likely "Terminating"), keep polling
+                    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+                }
+                catch (error) {
+                    // 404 means the namespace is fully gone
+                    const k8sErr = error;
+                    if (k8sErr.statusCode === 404 || k8sErr.body?.code === 404) {
+                        this.logger.debug('Namespace fully deleted', { namespace: ns });
+                        break;
+                    }
+                    // Unexpected error — log and stop waiting for this namespace
+                    this.logger.warn('Error polling namespace deletion', {
+                        namespace: ns,
+                        error: ensureError(error).message,
+                    });
+                    break;
+                }
+            }
         }
     }
     /**
@@ -231,11 +307,11 @@ export class DirectResourceFactoryImpl {
                         const healthError = {
                             resourceId: deployedResource.id,
                             phase: 'readiness',
-                            error: error instanceof Error ? error : new Error(String(error)),
+                            error: ensureError(error),
                             timestamp: new Date(),
                         };
                         healthErrors.push(healthError);
-                        healthLogger.error('Failed to check resource health', error, {
+                        healthLogger.error('Failed to check resource health', ensureError(error), {
                             resourceId: deployedResource.id,
                         });
                     }
@@ -283,7 +359,7 @@ export class DirectResourceFactoryImpl {
             }
         }
         catch (error) {
-            healthLogger.error('Error checking factory health', error);
+            healthLogger.error('Error checking factory health', ensureError(error));
             return 'failed';
         }
     }
@@ -347,7 +423,7 @@ export class DirectResourceFactoryImpl {
                         const healthError = {
                             resourceId: deployedResource.id,
                             phase: 'readiness',
-                            error: error instanceof Error ? error : new Error(String(error)),
+                            error: ensureError(error),
                             timestamp: new Date(),
                         };
                         healthErrors.push(healthError);
@@ -367,7 +443,7 @@ export class DirectResourceFactoryImpl {
             };
         }
         catch (error) {
-            healthLogger.error('Error getting health details', error);
+            healthLogger.error('Error getting health details', ensureError(error));
             return {
                 health: 'failed',
                 resourceCounts: { healthy: 0, degraded: 0, failed: 0, total: 0 },
@@ -375,7 +451,7 @@ export class DirectResourceFactoryImpl {
                     {
                         resourceId: 'factory',
                         phase: 'readiness',
-                        error: error instanceof Error ? error : new Error(String(error)),
+                        error: ensureError(error),
                         timestamp: new Date(),
                     },
                 ],
@@ -430,47 +506,66 @@ export class DirectResourceFactoryImpl {
         return this.getDeploymentEngine().deploy(resourceGraph, deploymentOptions);
     }
     /**
-     * Generate YAML for instance deployment
+     * Generate YAML for instance deployment.
+     *
+     * In direct mode this produces plain Kubernetes manifests with all schema
+     * references resolved from the provided spec.  If any KubernetesRef or
+     * CelExpression objects remain after resolution (cross-resource references,
+     * explicit Cel.expr/Cel.template calls, $-prefixed optional access) a
+     * ValidationError is thrown — those constructs require the Kro controller
+     * or runtime deployment via deploy().
      */
     toYaml(spec) {
         // Resolve references with the actual spec values
         const resolvedResources = this.resolveResourcesForSpec(spec);
-        // Generate individual Kubernetes resource YAML manifests (not RGD)
+        // Validate that all values are fully resolved — no KubernetesRef or
+        // CelExpression objects should remain in direct-mode YAML output.
+        const unresolvedRefs = findUnresolvedReferences(resolvedResources);
+        if (unresolvedRefs.length > 0) {
+            const details = unresolvedRefs.map((r) => `  - ${r.path}: ${r.description}`).join('\n');
+            throw new ValidationError(`Cannot generate direct-mode YAML: ${unresolvedRefs.length} unresolved reference(s) found.\n` +
+                `Direct mode toYaml() produces plain Kubernetes manifests where all values must be resolved.\n\n` +
+                `Unresolved references:\n${details}\n\n` +
+                `To fix this, either:\n` +
+                `  1. Use factory('kro') to generate Kro-managed YAML with CEL expressions\n` +
+                `  2. Use deploy() which resolves all references at runtime against the live cluster\n` +
+                `  3. Remove Cel.expr() / Cel.template() / cross-resource references from your resource builder`, 'DirectResourceFactory', this.name, undefined, [
+                'Use factory("kro") for resource graphs with CEL expressions or cross-resource references',
+                'Use deploy() for runtime resolution against the live cluster',
+                'Remove explicit Cel.expr() / Cel.template() calls if direct-mode YAML is needed',
+            ]);
+        }
+        // Generate individual Kubernetes resource YAML manifests (not RGD).
+        // Uses js-yaml for safe serialization — avoids YAML injection via string interpolation.
         const yamlParts = Object.values(resolvedResources).map((resource) => {
             // Remove TypeKro-specific fields and generate clean Kubernetes YAML
             const cleanResource = { ...resource };
             delete cleanResource.id; // Remove TypeKro id field
-            // Simple YAML serialization for Kubernetes resources
-            let yamlContent = `apiVersion: ${cleanResource.apiVersion}
-kind: ${cleanResource.kind}
-metadata:
-  name: ${cleanResource.metadata?.name}
-  namespace: ${this.namespace}`;
-            // Add labels if present
-            if (cleanResource.metadata?.labels) {
-                yamlContent += `\n  labels:\n${Object.entries(cleanResource.metadata.labels)
-                    .map(([k, v]) => `    ${k}: ${v}`)
-                    .join('\n')}`;
-            }
+            // Build a clean manifest object for yaml.dump
+            const manifest = {
+                apiVersion: cleanResource.apiVersion,
+                kind: cleanResource.kind,
+                metadata: {
+                    name: cleanResource.metadata?.name,
+                    namespace: this.namespace,
+                    ...(cleanResource.metadata?.labels
+                        ? { labels: cleanResource.metadata.labels }
+                        : undefined),
+                },
+            };
             // Handle different resource types
             const resourceWithSpec = cleanResource;
             if (resourceWithSpec.spec) {
-                yamlContent += `\nspec:\n${Object.entries(resourceWithSpec.spec)
-                    .map(([key, value]) => `  ${key}: ${typeof value === 'object'
-                    ? JSON.stringify(value, null, 2)
-                        .split('\n')
-                        .map((line, i) => (i === 0 ? line : `  ${line}`))
-                        .join('\n')
-                    : value}`)
-                    .join('\n')}`;
+                manifest.spec = resourceWithSpec.spec;
             }
             const resourceWithData = cleanResource;
             if (resourceWithData.data) {
-                yamlContent += `\ndata:\n${Object.entries(resourceWithData.data)
-                    .map(([key, value]) => `  ${key}: ${typeof value === 'string' ? JSON.stringify(value) : value}`)
-                    .join('\n')}`;
+                manifest.data = resourceWithData.data;
             }
-            return yamlContent;
+            // JSON round-trip strips non-serializable values (functions, symbols, proxies)
+            // that may remain in resolved resources before safe YAML serialization.
+            const safeManifest = JSON.parse(JSON.stringify(manifest));
+            return yaml.dump(safeManifest, { lineWidth: -1, noRefs: true, sortKeys: false }).trimEnd();
         });
         return yamlParts.join('\n---\n');
     }
@@ -502,15 +597,14 @@ metadata:
                 ...resource,
                 id: finalId,
             };
-            // Preserve the __resourceId property if it exists (it's non-enumerable)
-            // This is the original resource ID (e.g., 'webappConfig') that's used for cross-resource references
-            // Note: For Enhanced proxy resources, __resourceId is on the target object and accessible via Reflect.get
-            const originalResourceId = resource.__resourceId;
-            // Also check if the resource has an 'id' property that was set by the factory
-            // The proxy returns resourceId when accessing 'id' property
+            // Preserve resource metadata from the original resource to the spread copy
+            // The WeakMap-based copyResourceMetadata replaces manual Object.defineProperty calls
+            copyResourceMetadata(resource, resourceWithId);
+            // Also check proxy 'id' as fallback for the original resource key
+            const originalResourceId = getResourceId(resource);
             const resourceIdFromProxy = resource.id;
             const effectiveOriginalId = originalResourceId || resourceIdFromProxy;
-            this.logger.debug('Checking __resourceId preservation', {
+            this.logger.debug('Checking resourceId preservation', {
                 originalResourceId,
                 resourceIdFromProxy,
                 effectiveOriginalId,
@@ -518,27 +612,12 @@ metadata:
                 hasResourceIdFromProxy: !!resourceIdFromProxy,
             });
             if (effectiveOriginalId) {
-                Object.defineProperty(resourceWithId, '__resourceId', {
-                    value: effectiveOriginalId,
-                    enumerable: false,
-                    configurable: true,
-                });
-                this.logger.debug('Preserved __resourceId on resource', {
+                setResourceId(resourceWithId, effectiveOriginalId);
+                this.logger.debug('Preserved resourceId on resource', {
                     originalResourceId: effectiveOriginalId,
                     newId: finalId,
                 });
             }
-            // Preserve the readinessEvaluator function if it exists (it's non-enumerable)
-            const originalResource = resource;
-            if (originalResource.readinessEvaluator &&
-                typeof originalResource.readinessEvaluator === 'function') {
-                Object.defineProperty(resourceWithId, 'readinessEvaluator', {
-                    value: originalResource.readinessEvaluator,
-                    enumerable: false,
-                    configurable: true,
-                    writable: false,
-                });
-            }
             return resourceWithId;
         });
         // Convert to DeployableK8sResource format expected by dependency resolver
@@ -583,7 +662,7 @@ metadata:
                 }
             }
             catch (error) {
-                this.logger.warn('Failed to re-execute composition, falling back to reference resolution', error);
+                this.logger.error('Failed to re-execute composition, falling back to reference resolution', ensureError(error));
             }
         }
         // Fall back to the original reference resolution approach
@@ -598,7 +677,7 @@ metadata:
             }
             catch (error) {
                 // If resolution fails, use the original resource
-                this.logger.warn('Failed to resolve references for resource', error);
+                this.logger.error('Failed to resolve references for resource', ensureError(error));
                 resolvedResources[key] = resource;
             }
         }
@@ -614,10 +693,13 @@ metadata:
         }
         try {
             this.logger.debug('Re-executing composition with actual spec values');
-            // Import the composition context utilities
-            const { createCompositionContext, runWithCompositionContext, } = require('../../factories/shared.js');
-            // Create a new composition context for re-execution
-            const reExecutionContext = createCompositionContext('re-execution');
+            // Composition context utilities are now statically imported from core
+            // Create a new composition context for re-execution.
+            // Enable ID deduplication so forEach loops that create multiple resources
+            // with the same id (e.g., 'regionDep') get unique keys ('regionDep', 'regionDep-1', etc.)
+            const reExecutionContext = createCompositionContext('re-execution', {
+                deduplicateIds: true,
+            });
             // Execute the composition function within the new context and capture both resources and status
             const { resources, status } = runWithCompositionContext(reExecutionContext, () => {
                 // Execute the composition function with actual spec values
@@ -632,9 +714,16 @@ metadata:
                 resourceIds: Object.keys(resources),
                 statusFields: status ? Object.keys(status) : [],
             });
-            // Convert Enhanced resources back to KubernetesResource format
+            // Convert Enhanced resources back to KubernetesResource format.
+            // Filter out externalRef resources — they already exist in the cluster
+            // and should NOT be deployed in direct mode.
             const kubernetesResources = {};
             for (const [id, enhanced] of Object.entries(resources)) {
+                // Skip external references — they're not managed by us
+                if (Reflect.get(enhanced, '__externalRef') === true) {
+                    this.logger.debug('Skipping externalRef resource in direct mode', { id });
+                    continue;
+                }
                 // Extract the underlying Kubernetes resource from the Enhanced proxy
                 const kubernetesResource = this.extractKubernetesResourceFromEnhanced(enhanced);
                 kubernetesResources[id] = kubernetesResource;
@@ -647,7 +736,7 @@ metadata:
             };
         }
         catch (error) {
-            this.logger.error('Failed to re-execute composition', error);
+            this.logger.error('Failed to re-execute composition', ensureError(error));
             return null;
         }
     }
@@ -658,6 +747,68 @@ metadata:
     getReExecutedStatus() {
         return this.reExecutedStatus;
     }
+    /**
+     * Re-execute the composition with live status data from deployed resources.
+     *
+     * After deployment completes, we have live status for each resource.
+     * This method re-runs the composition function with that live data injected
+     * into the proxy system, so status comparisons like
+     * `database.status.readyInstances >= 1` evaluate correctly.
+     *
+     * @param spec - The original spec
+     * @param liveStatusMap - Map of resource ID to live status object
+     * @returns Re-executed status with live data, or null on failure
+     */
+    reExecuteWithLiveStatus(spec, liveStatusMap) {
+        if (!this.factoryOptions.compositionFn)
+            return null;
+        try {
+            this.logger.debug('Re-executing composition with live status data', {
+                liveResourceCount: liveStatusMap.size,
+                resourceIds: [...liveStatusMap.keys()],
+            });
+            // Phase 1: Probe execution to discover nested composition IDs.
+            // Nested compositions generate IDs like "inngest-bootstrap1" via the
+            // composition instance counter. We need to discover these IDs so we can
+            // synthesize status entries from child resources' live data.
+            const probeContext = createCompositionContext('re-execution-probe', {
+                deduplicateIds: true,
+            });
+            probeContext.liveStatusMap = liveStatusMap;
+            runWithCompositionContext(probeContext, () => {
+                this.factoryOptions.compositionFn?.(spec);
+            });
+            // Synthesize status for nested compositions from deployment readiness.
+            //
+            // Every deployed resource has a readiness status from its factory-provided
+            // evaluator (the deployment engine confirmed each one via waitForReady).
+            // Nested compositions are "ready" when ALL their children are ready.
+            //
+            // This uses synthesizeNestedCompositionStatus which is shared between
+            // direct and KRO deployment strategies — it only depends on the probe
+            // context's resource keys and the liveStatusMap's deployed resource keys.
+            const enrichedMap = synthesizeNestedCompositionStatus(probeContext.resources, liveStatusMap, this.logger, probeContext.nestedCompositionIds);
+            // Phase 2: Real execution with enriched live status map
+            const reExecutionContext = createCompositionContext('re-execution', {
+                deduplicateIds: true,
+            });
+            reExecutionContext.liveStatusMap = enrichedMap;
+            const { status } = runWithCompositionContext(reExecutionContext, () => {
+                const computedStatus = this.factoryOptions.compositionFn?.(spec);
+                return { status: computedStatus };
+            });
+            this.logger.debug('Live status re-execution completed', {
+                statusFields: status ? Object.keys(status) : [],
+            });
+            return status;
+        }
+        catch (error) {
+            this.logger.warn('Failed to re-execute composition with live status', {
+                error: ensureError(error).message,
+            });
+            return null;
+        }
+    }
     /**
      * Deep resolve any KubernetesRef objects in a value to their string representation
      * This is needed because when composition functions build objects with schema proxy values,
@@ -735,15 +886,40 @@ metadata:
             // Include all other properties (spec, status, data, rules, etc.)
             // Deep resolve any KubernetesRef objects in the value
             if (value !== undefined && value !== null) {
-                resource[key] = this.deepResolveKubernetesRefs(value);
+                Reflect.set(resource, key, this.deepResolveKubernetesRefs(value));
             }
         }
         // Preserve the non-enumerable id field if it exists (needed for resource mapping in CEL resolution)
         if (enhanced.id) {
             resource.id = enhanced.id;
         }
+        // Preserve the non-enumerable readinessEvaluator if it exists.
+        // Preserve resource metadata (resourceId, readinessEvaluator, etc.) from Enhanced proxy
+        copyResourceMetadata(enhanced, resource);
         return resource;
     }
+    /**
+     * Traverse a spec object using dot-separated path parts, returning the resolved value.
+     * Shared by both KubernetesRef resolution (Case 1) and template marker resolution (Case 4).
+     */
+    traverseSpec(spec, pathParts, logPath) {
+        let currentValue = spec;
+        this.logger.trace('Traversing spec with path parts', { pathParts });
+        for (const part of pathParts) {
+            if (currentValue && typeof currentValue === 'object' && part in currentValue) {
+                currentValue = currentValue[part];
+            }
+            else {
+                this.logger.warn('Path part not found in spec', {
+                    path: logPath,
+                    part,
+                    availableKeys: currentValue && typeof currentValue === 'object' ? Object.keys(currentValue) : [],
+                });
+                return { found: false };
+            }
+        }
+        return { found: true, value: currentValue };
+    }
     /**
      * Resolve schema references and CEL expressions to actual values for direct deployment.
      * This is the final, corrected version that handles both direct proxies and Cel.expr wrappers.
@@ -758,34 +934,15 @@ metadata:
         if (isKubernetesRef(resource) && resource.resourceId === '__schema__') {
             this.logger.trace('Found schema KubernetesRef', { path, fieldPath: resource.fieldPath });
             const pathParts = resource.fieldPath.split('.');
-            let currentValue = spec;
-            // Skip the first part ('spec') and traverse the spec object
-            this.logger.trace('Traversing spec with path parts', { pathParts: pathParts.slice(1) });
-            for (const part of pathParts.slice(1)) {
-                if (currentValue && typeof currentValue === 'object' && part in currentValue) {
-                    const oldValue = currentValue;
-                    currentValue = currentValue[part];
-                    this.logger.trace('Successfully traversed spec part', {
-                        part,
-                        oldValue: JSON.stringify(oldValue),
-                        newValue: JSON.stringify(currentValue),
-                    });
-                }
-                else {
-                    this.logger.warn('Path part not found in spec, returning original reference', {
-                        path,
-                        part,
-                        spec: JSON.stringify(spec),
-                    });
-                    return resource;
-                    // Path not found, return original
-                }
+            const resolved = this.traverseSpec(spec, pathParts.slice(1), path);
+            if (resolved.found) {
+                this.logger.trace('Resolved schema KubernetesRef to value', {
+                    path,
+                    resolvedValue: resolved.value,
+                });
+                return resolved.value;
             }
-            this.logger.trace('Resolved schema KubernetesRef to value', {
-                path,
-                resolvedValue: currentValue,
-            });
-            return currentValue;
+            return resource;
         }
         // Case 2: Handle CelExpression objects (e.g., Cel.expr(schema.spec.name, '-db'))
         if (isCelExpression(resource)) {
@@ -821,31 +978,24 @@ metadata:
                 resolved[key] = this.resolveSchemaReferencesToValues(value, spec, `${path}.${key}`);
             }
             // Debug: Check if id field is being preserved
-            if (path === 'root' && resource.id) {
+            const resourceRecord = resource;
+            if (path === 'root' && resourceRecord.id) {
                 this.logger.debug('Resource ID preservation check', {
                     path,
-                    originalId: resource.id,
+                    originalId: resourceRecord.id,
                     resolvedId: resolved.id,
                     originalKeys: Object.keys(resource),
                     resolvedKeys: Object.keys(resolved),
                 });
             }
-            // FIX: Explicitly check for and preserve the non-enumerable readinessEvaluator property.
-            const evaluator = resource
-                .readinessEvaluator;
-            if (typeof evaluator === 'function') {
-                this.logger.trace('Preserving readiness evaluator for resource', { path });
-                Object.defineProperty(resolved, 'readinessEvaluator', {
-                    value: evaluator,
-                    enumerable: false,
-                    configurable: false,
-                    writable: false,
-                });
+            // Preserve resource metadata (resourceId, readinessEvaluator, etc.) via WeakMap
+            if (typeof resource === 'object' && resource !== null) {
+                copyResourceMetadata(resource, resolved);
             }
             // FIX: Preserve the id field if it exists (needed for resource mapping in CEL resolution)
-            if (resource.id) {
-                this.logger.trace('Preserving resource id field', { path, id: resource.id });
-                resolved.id = resource.id;
+            if (resourceRecord.id) {
+                this.logger.trace('Preserving resource id field', { path, id: resourceRecord.id });
+                resolved.id = resourceRecord.id;
             }
             return resolved;
         }
@@ -862,27 +1012,15 @@ metadata:
                 const pathParts = fieldPath.split('.');
                 // The first part should be 'spec' or 'status'
                 if (pathParts[0] === 'spec') {
-                    // Traverse the spec object using the remaining path parts
-                    let currentValue = spec;
-                    for (const part of pathParts.slice(1)) {
-                        if (currentValue && typeof currentValue === 'object' && part in currentValue) {
-                            currentValue = currentValue[part];
-                        }
-                        else {
-                            this.logger.warn('Schema path not found in spec', {
-                                path,
-                                fieldPath,
-                                part,
-                                availableKeys: currentValue ? Object.keys(currentValue) : [],
-                            });
-                            return _match; // Keep original marker if path not found
-                        }
+                    const resolved = this.traverseSpec(spec, pathParts.slice(1), path);
+                    if (resolved.found) {
+                        this.logger.trace('Resolved schema marker to value', {
+                            fieldPath,
+                            resolvedValue: resolved.value,
+                        });
+                        return String(resolved.value);
                     }
-                    this.logger.trace('Resolved schema marker to value', {
-                        fieldPath,
-                        resolvedValue: currentValue,
-                    });
-                    return String(currentValue);
+                    return _match; // Keep original marker if path not found
                 }
                 else {
                     // Status references or other paths - keep as-is for now
@@ -913,6 +1051,59 @@ metadata:
         return generateInstanceName(spec);
     }
 }
+/**
+ * Recursively walk a resolved resource tree and collect any remaining
+ * KubernetesRef or CelExpression objects.  These cannot be serialized
+ * in direct-mode YAML and indicate the user should use Kro mode or deploy().
+ */
+function findUnresolvedReferences(resources) {
+    const refs = [];
+    const visited = new WeakSet();
+    function walk(value, path, depth) {
+        if (value == null || typeof value !== 'object') {
+            // Check for __KUBERNETES_REF_ marker strings left in resolved primitives
+            if (typeof value === 'string' && value.includes('__KUBERNETES_REF_')) {
+                refs.push({ path, description: `Unresolved reference marker: ${value}` });
+            }
+            return;
+        }
+        if (depth >= DEFAULT_MAX_RECURSION_DEPTH)
+            return;
+        if (visited.has(value))
+            return;
+        visited.add(value);
+        if (isKubernetesRef(value)) {
+            const ref = value;
+            refs.push({
+                path,
+                description: `KubernetesRef(${ref.resourceId ?? '?'}.${ref.fieldPath ?? '?'})`,
+            });
+            return;
+        }
+        if (isCelExpression(value)) {
+            const expr = value;
+            refs.push({
+                path,
+                description: `CelExpression(${expr.expression ?? '?'})`,
+            });
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                walk(value[i], `${path}[${i}]`, depth + 1);
+            }
+            return;
+        }
+        for (const [key, child] of Object.entries(value)) {
+            walk(child, path ? `${path}.${key}` : key, depth + 1);
+        }
+    }
+    for (const [resourceKey, resource] of Object.entries(resources)) {
+        const label = `${resource.kind ?? 'Resource'}/${resource.metadata?.name ?? resourceKey}`;
+        walk(resource, label, 0);
+    }
+    return refs;
+}
 /**
  * Create a DirectResourceFactory instance
  */