typekro 0.3.1 → 0.5.0

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

@@ -4,11 +4,16 @@
  * 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 { ResourceReadinessChecker } from './readiness.js';
 import { createRollbackManagerWithKubeConfig } from './rollback-manager.js';
@@ -34,7 +39,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 +50,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 +68,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 +95,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,17 +127,81 @@ 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) {
+                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) {
-            throw new Error(`Failed to delete instance ${name}: ${error instanceof Error ? error.message : String(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 = 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 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;
+                }
+            }
         }
     }
     /**
@@ -223,11 +270,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,
                         });
                     }
@@ -275,7 +322,7 @@ export class DirectResourceFactoryImpl {
             }
         }
         catch (error) {
-            healthLogger.error('Error checking factory health', error);
+            healthLogger.error('Error checking factory health', ensureError(error));
             return 'failed';
         }
     }
@@ -324,8 +371,9 @@ export class DirectResourceFactoryImpl {
                                 namespace: deployedResource.namespace,
                             },
                         };
+                        // In the new API, methods return objects directly (no .body wrapper)
                         const liveResource = await k8sApi.read(resourceRef);
-                        const isReady = readinessChecker.isResourceReady(liveResource.body);
+                        const isReady = readinessChecker.isResourceReady(liveResource);
                         if (isReady) {
                             healthyCount++;
                         }
@@ -338,7 +386,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);
@@ -358,7 +406,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 },
@@ -366,7 +414,7 @@ export class DirectResourceFactoryImpl {
                     {
                         resourceId: 'factory',
                         phase: 'readiness',
-                        error: error instanceof Error ? error : new Error(String(error)),
+                        error: ensureError(error),
                         timestamp: new Date(),
                     },
                 ],
@@ -421,47 +469,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');
     }
@@ -473,20 +540,45 @@ metadata:
         const resolvedResources = this.resolveResourcesForSpec(spec);
         const instanceName = this.generateInstanceName(spec);
         const resourceArray = Object.values(resolvedResources).map((resource, index) => {
+            this.logger.debug('Processing resource for ID generation', {
+                index,
+                resourceId: resource.id,
+                resourceKind: resource.kind,
+                hasId: !!resource.id,
+                resourceKeys: Object.keys(resource),
+            });
             const baseId = `${instanceName}-resource-${index}-${resource.id || resource.kind?.toLowerCase() || 'unknown'}`;
+            const finalId = toCamelCase(baseId);
+            this.logger.debug('Generated resource ID', {
+                index,
+                originalId: resource.id,
+                resourceKind: resource.kind,
+                baseId,
+                finalId,
+            });
             const resourceWithId = {
                 ...resource,
-                id: toCamelCase(baseId),
+                id: 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,
+            // 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', {
+                originalResourceId,
+                resourceIdFromProxy,
+                effectiveOriginalId,
+                hasOriginalResourceId: !!originalResourceId,
+                hasResourceIdFromProxy: !!resourceIdFromProxy,
+            });
+            if (effectiveOriginalId) {
+                setResourceId(resourceWithId, effectiveOriginalId);
+                this.logger.debug('Preserved resourceId on resource', {
+                    originalResourceId: effectiveOriginalId,
+                    newId: finalId,
                 });
             }
             return resourceWithId;
@@ -507,9 +599,37 @@ metadata:
     }
     /**
      * Resolve resources for a specific spec
-     * This uses the existing processResourceReferences system to handle schema references
+     * This uses composition re-execution when available, or falls back to reference resolution
      */
+    reExecutedStatus = null; // Store the re-executed status
     resolveResourcesForSpec(spec) {
+        // Reset the re-executed status
+        this.reExecutedStatus = null;
+        // Check if we have composition re-execution parameters
+        if (this.factoryOptions.compositionFn && this.factoryOptions.compositionDefinition) {
+            this.logger.debug('Re-executing composition with actual spec values', {
+                hasCompositionFn: !!this.factoryOptions.compositionFn,
+                hasCompositionDefinition: !!this.factoryOptions.compositionDefinition,
+            });
+            try {
+                // Re-execute the composition with actual spec values
+                const reExecutionResult = this.reExecuteCompositionWithActualValues(spec);
+                if (reExecutionResult) {
+                    this.logger.debug('Successfully re-executed composition with actual values', {
+                        resourceCount: Object.keys(reExecutionResult.resources).length,
+                        statusFields: reExecutionResult.status ? Object.keys(reExecutionResult.status) : [],
+                    });
+                    // Store the re-executed status for later use
+                    this.reExecutedStatus = reExecutionResult.status;
+                    return reExecutionResult.resources;
+                }
+            }
+            catch (error) {
+                this.logger.error('Failed to re-execute composition, falling back to reference resolution', ensureError(error));
+            }
+        }
+        // Fall back to the original reference resolution approach
+        this.logger.debug('Using reference resolution approach (no composition re-execution available)');
         const resolvedResources = {};
         for (const [key, resource] of Object.entries(this.resources)) {
             try {
@@ -520,12 +640,187 @@ 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;
             }
         }
         return resolvedResources;
     }
+    /**
+     * Re-execute the composition function with actual spec values
+     * This provides actual values instead of proxy functions to the composition
+     */
+    reExecuteCompositionWithActualValues(spec) {
+        if (!this.factoryOptions.compositionFn || !this.factoryOptions.compositionDefinition) {
+            return null;
+        }
+        try {
+            this.logger.debug('Re-executing composition with actual spec values');
+            // 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
+                const computedStatus = this.factoryOptions.compositionFn?.(spec);
+                return {
+                    resources: reExecutionContext.resources,
+                    status: computedStatus,
+                };
+            });
+            this.logger.debug('Composition re-execution completed', {
+                capturedResourceCount: Object.keys(resources).length,
+                resourceIds: Object.keys(resources),
+                statusFields: status ? Object.keys(status) : [],
+            });
+            // 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;
+            }
+            // The status returned from re-execution should preserve CEL expressions
+            // Only spec-based values should be resolved, resource-based CEL expressions should remain
+            return {
+                resources: kubernetesResources,
+                status: status,
+            };
+        }
+        catch (error) {
+            this.logger.error('Failed to re-execute composition', ensureError(error));
+            return null;
+        }
+    }
+    /**
+     * Get the re-executed status if available
+     * This is used by the deployment strategy to use computed status instead of calling status builder with proxy functions
+     */
+    getReExecutedStatus() {
+        return this.reExecutedStatus;
+    }
+    /**
+     * 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,
+     * those values are KubernetesRef objects that need to be converted to actual values or
+     * placeholder strings for serialization.
+     *
+     * For schema references (resourceId === '__schema__'), we return a placeholder that will
+     * be resolved later when actual spec values are available.
+     *
+     * For resource references, we return a CEL expression placeholder.
+     */
+    deepResolveKubernetesRefs(value, path = 'root') {
+        // Handle KubernetesRef objects
+        if (isKubernetesRef(value)) {
+            this.logger.trace('Found KubernetesRef in value', {
+                path,
+                resourceId: value.resourceId,
+                fieldPath: value.fieldPath,
+            });
+            // For schema references, return a marker that can be resolved later
+            if (value.resourceId === '__schema__') {
+                return `__KUBERNETES_REF___schema___${value.fieldPath}__`;
+            }
+            // For resource references, return a CEL expression placeholder
+            return `__KUBERNETES_REF_${value.resourceId}_${value.fieldPath}__`;
+        }
+        // Handle CelExpression objects
+        if (isCelExpression(value)) {
+            this.logger.trace('Found CelExpression in value', {
+                path,
+                expression: value.expression,
+            });
+            return value.expression;
+        }
+        // Handle arrays
+        if (Array.isArray(value)) {
+            return value.map((item, index) => this.deepResolveKubernetesRefs(item, `${path}[${index}]`));
+        }
+        // Handle objects
+        if (value !== null && typeof value === 'object') {
+            const resolved = {};
+            for (const [key, val] of Object.entries(value)) {
+                resolved[key] = this.deepResolveKubernetesRefs(val, `${path}.${key}`);
+            }
+            return resolved;
+        }
+        // Return primitives as-is
+        return value;
+    }
+    /**
+     * Extract the underlying Kubernetes resource from an Enhanced proxy
+     *
+     * IMPORTANT: This method preserves ALL enumerable properties from the Enhanced resource,
+     * not just standard Kubernetes fields. This is critical for resources like Secret (data),
+     * ConfigMap (data, binaryData), RBAC resources (rules, roleRef, subjects), etc.
+     *
+     * It also resolves any KubernetesRef objects in the resource properties to their
+     * string representations, which is critical for HelmRelease values that may contain
+     * schema proxy references.
+     */
+    extractKubernetesResourceFromEnhanced(enhanced) {
+        // Start with required Kubernetes resource structure
+        const resource = {
+            apiVersion: enhanced.apiVersion,
+            kind: enhanced.kind,
+            metadata: this.deepResolveKubernetesRefs(enhanced.metadata),
+        };
+        // Preserve ALL other enumerable properties from the Enhanced resource
+        // This ensures resource-specific fields (data, rules, roleRef, etc.) are not lost
+        for (const [key, value] of Object.entries(enhanced)) {
+            // Skip the core fields we've already set
+            if (key === 'apiVersion' || key === 'kind' || key === 'metadata') {
+                continue;
+            }
+            // Include all other properties (spec, status, data, rules, etc.)
+            // Deep resolve any KubernetesRef objects in the value
+            if (value !== undefined && value !== null) {
+                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.
@@ -540,34 +835,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)) {
@@ -602,20 +878,68 @@ metadata:
             for (const [key, value] of Object.entries(resource)) {
                 resolved[key] = this.resolveSchemaReferencesToValues(value, spec, `${path}.${key}`);
             }
-            // 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,
+            // Debug: Check if id field is being preserved
+            const resourceRecord = resource;
+            if (path === 'root' && resourceRecord.id) {
+                this.logger.debug('Resource ID preservation check', {
+                    path,
+                    originalId: resourceRecord.id,
+                    resolvedId: resolved.id,
+                    originalKeys: Object.keys(resource),
+                    resolvedKeys: Object.keys(resolved),
                 });
             }
+            // 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 (resourceRecord.id) {
+                this.logger.trace('Preserving resource id field', { path, id: resourceRecord.id });
+                resolved.id = resourceRecord.id;
+            }
             return resolved;
         }
+        // Case 4: Handle strings that contain __KUBERNETES_REF_ markers from template literals
+        // These are generated when schema references are used in template literals like `${schema.spec.name}-suffix`
+        if (typeof resource === 'string' && resource.includes('__KUBERNETES_REF_')) {
+            this.logger.trace('Found string with KubernetesRef markers', { path, value: resource });
+            // Replace all __KUBERNETES_REF_ markers with actual values from spec
+            // Pattern: __KUBERNETES_REF_{resourceId}_{fieldPath}__
+            // For schema: __KUBERNETES_REF___schema___{fieldPath}__
+            // The fieldPath for schema refs is like "spec.baseName" or "spec.nested.field"
+            const resolvedString = resource.replace(/__KUBERNETES_REF___schema___(.+?)__/g, (_match, fieldPath) => {
+                // fieldPath is like "spec.baseName" - we need to traverse starting from the schema root
+                const pathParts = fieldPath.split('.');
+                // The first part should be 'spec' or 'status'
+                if (pathParts[0] === 'spec') {
+                    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);
+                    }
+                    return _match; // Keep original marker if path not found
+                }
+                else {
+                    // Status references or other paths - keep as-is for now
+                    this.logger.trace('Keeping non-spec schema reference marker', {
+                        fieldPath,
+                    });
+                    return _match;
+                }
+            });
+            // Also handle non-schema resource references (keep them as-is for now)
+            // Pattern: __KUBERNETES_REF_{resourceId}_{fieldPath}__ where resourceId is not __schema__
+            this.logger.trace('Resolved string with markers', {
+                path,
+                original: resource,
+                resolved: resolvedString,
+            });
+            return resolvedString;
+        }
         this.logger.trace('Returning primitive value as-is', { path, value: resource });
         // Return primitives and other types as-is.
         return resource;
@@ -628,6 +952,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
  */