typekro 0.8.0 → 0.9.0

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

@@ -8,18 +8,23 @@ 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 { buildNestedCompositionAliasTargets } from '../composition/nested-status-cel.js';
+import { KUBERNETES_REF_SCHEMA_MARKER_SOURCE } from '../constants/brands.js';
 import { DEFAULT_DELETE_TIMEOUT, DEFAULT_FAST_POLL_INTERVAL, DEFAULT_MAX_RECURSION_DEPTH, } from '../config/defaults.js';
 import { DependencyResolver } from '../dependencies/index.js';
+import { BUILT_IN_GVKS } from './deployment-state-discovery.js';
 import { ensureError, ResourceGraphFactoryError, TypeKroError, ValidationError, } from '../errors.js';
 import { getComponentLogger } from '../logging/index.js';
-import { copyResourceMetadata, getResourceId, setResourceId } from '../metadata/index.js';
+import { copyResourceMetadata, getMetadataField, getResourceId, setResourceId } from '../metadata/index.js';
+import { logHandleSnapshot } from './handle-tracing.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';
+import { generateInstanceName, getSingletonInstanceName, validateSpec } from './shared-utilities.js';
+import { assertNoDeployedSingletonSpecDrift, assertNoDiscoveredSingletonSpecDrift, singletonSpecFingerprintAnnotationValue, } from './singleton-owner-drift.js';
 import { AlchemyDeploymentStrategy, DirectDeploymentStrategy } from './strategies/index.js';
+import { getSingletonResourceId } from '../singleton/singleton.js';
 /**
  * DirectResourceFactory implementation
  *
@@ -34,14 +39,19 @@ export class DirectResourceFactoryImpl {
     resources;
     closures;
     schemaDefinition;
+    // biome-ignore lint/suspicious/noExplicitAny: status builders accept composition-specific resource maps that cannot be expressed more tightly here.
     statusBuilder;
     deploymentEngine;
     alchemyScope;
     factoryOptions;
+    singletonDefinitions;
+    singletonOwnerStatuses = new Map();
     deployedInstances = new Map();
     logger = getComponentLogger('direct-factory');
     clientManager;
-    constructor(name, resources, schemaDefinition, statusBuilder, options = {}) {
+    constructor(name, resources, schemaDefinition, 
+    // biome-ignore lint/suspicious/noExplicitAny: constructor must preserve the generic status-builder resource map contract.
+    statusBuilder, options = {}) {
         this.name = name;
         this.namespace = options.namespace || 'default';
         this.alchemyScope = options.alchemyScope;
@@ -51,6 +61,7 @@ export class DirectResourceFactoryImpl {
         this.schemaDefinition = schemaDefinition;
         this.statusBuilder = statusBuilder;
         this.factoryOptions = options;
+        this.singletonDefinitions = options.singletonDefinitions ?? [];
         this.clientManager = new KubernetesClientManager(options);
     }
     /**
@@ -59,6 +70,29 @@ export class DirectResourceFactoryImpl {
     getClientProvider() {
         return this.clientManager.getClientProvider();
     }
+    getDebugState() {
+        return {
+            mode: this.mode,
+            namespace: this.namespace,
+            deployedInstances: this.deployedInstances.size,
+            hasDeploymentEngine: !!this.deploymentEngine,
+            clientManager: this.clientManager.getDebugState(),
+            deploymentEngine: this.deploymentEngine?.getDebugState(),
+        };
+    }
+    async dispose() {
+        logHandleSnapshot(this.logger, 'direct-factory.dispose.before', {
+            factoryState: this.getDebugState(),
+        });
+        if (this.deploymentEngine) {
+            await this.deploymentEngine.dispose();
+            this.deploymentEngine = undefined;
+        }
+        this.clientManager.dispose();
+        logHandleSnapshot(this.logger, 'direct-factory.dispose.after', {
+            factoryState: this.getDebugState(),
+        });
+    }
     /**
      * Get or create the deployment engine using the centralized client provider
      */
@@ -81,17 +115,22 @@ export class DirectResourceFactoryImpl {
     /**
      * Deploy a new instance with the given spec
      */
-    async deploy(spec) {
+    async deploy(spec, opts) {
         this.logger.debug('DirectResourceFactory deploy called', {
             factoryName: this.name,
             hasStatusBuilder: !!this.statusBuilder,
         });
+        validateSpec(spec, this.schemaDefinition, {
+            kind: this.schemaDefinition.kind,
+            name: this.name,
+        });
         // Use the consolidated deployment strategy
         const strategy = this.getDeploymentStrategy();
         this.logger.debug('Got deployment strategy', {
             strategyType: strategy.constructor.name,
         });
-        const instance = await strategy.deploy(spec);
+        await this.ensureSingletonOwners(spec);
+        const instance = await strategy.deploy(spec, opts);
         // Check if deployment failed and throw for user-facing error handling
         if (instance.metadata?.annotations?.['typekro.io/deployment-status'] === 'failed') {
             const errorMessage = instance.metadata?.annotations?.['typekro.io/deployment-error'] ||
@@ -99,7 +138,7 @@ export class DirectResourceFactoryImpl {
             throw new ResourceGraphFactoryError(errorMessage, this.name, 'deployment');
         }
         // Track the deployed instance
-        const instanceName = this.generateInstanceName(spec);
+        const instanceName = opts?.instanceNameOverride ?? this.generateInstanceName(spec);
         this.deployedInstances.set(instanceName, instance);
         return instance;
     }
@@ -118,35 +157,58 @@ export class DirectResourceFactoryImpl {
     }
     /**
      * Get all deployed instances
+     *
+     * Direct mode currently reports same-process instances only. Cross-process
+     * discovery is implemented for `deleteInstance(name)`, but reconstructing
+     * fully typed Enhanced instances from live tagged resources is intentionally
+     * not attempted here.
      */
     async getInstances() {
         return Array.from(this.deployedInstances.values());
     }
     /**
-     * Delete a specific instance by name
+     * Delete a specific instance by name.
+     *
+     * Lookup order:
+     *   1. In-memory `deployedInstances` Map (same-process path) — uses
+     *      the deployment-id annotation on the Enhanced instance proxy.
+     *   2. Cluster-side label discovery (cross-process path) — queries
+     *      for all resources labeled `typekro.io/factory-name=<factory>,
+     *      typekro.io/instance-name=<instance>`, reconstructs the
+     *      dependency graph from per-resource `typekro.io/depends-on`
+     *      annotations, and performs reverse-topological deletion.
+     *
+     * Both paths feed into the same graph-based reverse-topological
+     * delete via `engine.rollbackRecord`.
+     *
+     * **Scope filtering**: By default, unscoped (instance-private)
+     * resources are deleted and scoped resources are preserved. Pass
+     * `opts.scopes` to include broader-scope resources additively:
+     *
+     * ```ts
+     * await factory.deleteInstance('my-app');                                         // unscoped only (safe default)
+     * await factory.deleteInstance('my-app', { scopes: ['cluster'] });               // unscoped + cluster
+     * await factory.deleteInstance('my-app', { scopes: ['cluster'],
+     *   includeUnscopedResources: false });                                           // cluster-only (leave app running)
+     * ```
      */
-    async deleteInstance(name) {
-        const instance = this.deployedInstances.get(name);
-        if (!instance) {
-            throw new TypeKroError(`Instance not found: ${name}`, 'INSTANCE_NOT_FOUND', {
-                instanceName: name,
-                factoryName: this.name,
-            });
-        }
+    async deleteInstance(name, opts) {
+        const engine = this.getDeploymentEngine();
         try {
-            // Use the deployment engine to delete resources using actual deployment ID
-            const engine = this.getDeploymentEngine();
-            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 this.rollbackInstanceResources(name, opts);
+            if (rollbackResult.status !== 'success' || rollbackResult.errors.length > 0) {
+                const errorSummary = rollbackResult.errors
+                    .map((error) => `${error.resourceId}: ${ensureError(error.error).message}`)
+                    .join('; ');
+                throw new Error(`Cleanup incomplete for instance ${name}: rollback ${rollbackResult.status}${errorSummary ? ` (${errorSummary})` : ''}`);
             }
-            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]);
+                .map((r) => r.split('/')[1])
+                .filter((namespace) => namespace !== undefined);
             if (deletedNamespaces.length > 0) {
                 // Delete PVCs in namespaces before waiting — StatefulSet PVCs have
                 // finalizers that block namespace termination until volumes are released.
@@ -192,17 +254,81 @@ export class DirectResourceFactoryImpl {
             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.
+            // INSTANCE_NOT_FOUND bubbles up — the caller asked us to delete
+            // an instance that has neither in-memory state nor a persisted
+            // record. That's a legitimate error (wrong name, already cleaned
+            // up) and the caller needs to see it.
+            if (error instanceof TypeKroError && error.code === 'INSTANCE_NOT_FOUND') {
+                throw error;
+            }
+            // Soft-swallow "Cannot rollback" errors from the engine —
+            // they indicate the engine's in-memory deployment state has
+            // already been cleaned up (e.g., by a previous rollback call).
+            // The instance is effectively gone, so we remove from tracking.
             const errorMessage = ensureError(error).message;
-            if (errorMessage.includes('not found') || errorMessage.includes('Cannot rollback')) {
+            if (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');
         }
     }
+    buildKnownGvks() {
+        const crdHints = new Map();
+        for (const r of Object.values(this.resources)) {
+            if (!r.apiVersion || !r.kind)
+                continue;
+            const key = `${r.apiVersion}/${r.kind}`;
+            if (crdHints.has(key))
+                continue;
+            const scope = getMetadataField(r, 'scope');
+            crdHints.set(key, { apiVersion: r.apiVersion, kind: r.kind, namespaced: scope !== 'cluster' });
+        }
+        return [
+            ...BUILT_IN_GVKS,
+            ...crdHints.values(),
+        ];
+    }
+    async rollbackInstanceResources(name, opts) {
+        const engine = this.getDeploymentEngine();
+        const instance = this.deployedInstances.get(name);
+        if (instance) {
+            const deploymentId = instance.metadata?.annotations?.['typekro.io/deployment-id'];
+            if (deploymentId) {
+                try {
+                    return await engine.rollback(deploymentId, {
+                        ...(opts?.scopes && { scopes: opts.scopes }),
+                        ...(opts?.includeUnscopedResources === false && { includeUnscopedResources: false }),
+                    });
+                }
+                catch (error) {
+                    const isNotFound = error instanceof ResourceGraphFactoryError &&
+                        error.operation === 'cleanup';
+                    if (!isNotFound) {
+                        throw error;
+                    }
+                }
+            }
+        }
+        const record = await engine.loadDeploymentByInstance({
+            factoryName: this.name,
+            instanceName: name,
+            knownGvks: this.buildKnownGvks(),
+        });
+        if (!record) {
+            throw new TypeKroError(`Instance not found: ${name} (no in-memory state and no tagged resources on the cluster). The instance may have been cleaned up already, or was deployed with a typekro version that did not tag resources.`, 'INSTANCE_NOT_FOUND', { instanceName: name, factoryName: this.name });
+        }
+        this.logger.info('Cross-process cleanup: discovered deployment from cluster labels', {
+            instanceName: name,
+            factoryName: this.name,
+            deploymentId: record.deploymentId,
+            resourceCount: record.resources.length,
+        });
+        return engine.rollbackRecord(record, {
+            ...(opts?.scopes && { scopes: opts.scopes }),
+            ...(opts?.includeUnscopedResources === false && { includeUnscopedResources: false }),
+        });
+    }
     /**
      * Poll until the given namespaces no longer exist (HTTP 404).
      * Namespaces enter a "Terminating" phase on deletion and may take time
@@ -214,6 +340,7 @@ export class DirectResourceFactoryImpl {
         for (const ns of namespaces) {
             // Each namespace gets its own timeout budget
             const nsStartTime = Date.now();
+            let deleted = false;
             while (Date.now() - nsStartTime < timeout) {
                 try {
                     await k8sApi.read({
@@ -229,20 +356,28 @@ export class DirectResourceFactoryImpl {
                     const k8sErr = error;
                     if (k8sErr.statusCode === 404 || k8sErr.body?.code === 404) {
                         this.logger.debug('Namespace fully deleted', { namespace: ns });
+                        deleted = true;
                         break;
                     }
-                    // Unexpected error — log and stop waiting for this namespace
+                    // Unexpected error — fail loudly so callers do not assume cleanup completed.
                     this.logger.warn('Error polling namespace deletion', {
                         namespace: ns,
                         error: ensureError(error).message,
                     });
-                    break;
+                    throw error;
                 }
             }
+            if (!deleted) {
+                throw new ResourceGraphFactoryError(`Timed out waiting for namespace ${ns} to be deleted after ${timeout}ms`, this.name, 'cleanup');
+            }
         }
     }
     /**
      * Get factory status with real health checking using readiness evaluators
+     *
+     * Direct mode status is based on same-process instances returned by
+     * `getInstances()`. Use `deleteInstance(name)` for cross-process cleanup;
+     * status reconstruction from tagged live resources is not currently exposed.
      */
     async getStatus() {
         const instances = await this.getInstances();
@@ -460,27 +595,60 @@ export class DirectResourceFactoryImpl {
     }
     /**
      * Rollback all deployments made by this factory
+     *
+     * This rolls back same-process deployments tracked by this factory instance.
+     * For cross-process cleanup, call `deleteInstance(name)` with the known
+     * instance name so TypeKro can discover tagged resources from the cluster.
      */
     async rollback() {
         this.logger.debug('Starting rollback for all deployed instances');
-        // Get kubeConfig from the centralized provider (lazy initialization)
-        const clientProvider = this.getClientProvider();
-        const kubeConfig = clientProvider.getKubeConfig();
-        // Create rollback manager with the provider's KubeConfig
-        const rollbackManager = createRollbackManagerWithKubeConfig(kubeConfig);
-        // Get all deployed instances as Enhanced resources
-        const resourcesToRollback = Array.from(this.deployedInstances.values());
+        const startedAt = Date.now();
+        const instanceNames = Array.from(this.deployedInstances.keys());
         this.logger.debug('Rolling back resources', {
-            resourceCount: resourcesToRollback.length,
-            instanceNames: Array.from(this.deployedInstances.keys()),
-        });
-        // Perform rollback using consolidated logic
-        const result = await rollbackManager.rollbackResources(resourcesToRollback, {
-            timeout: this.factoryOptions.timeout || undefined,
-            emitEvent: this.factoryOptions.progressCallback || undefined,
+            instanceCount: instanceNames.length,
+            instanceNames,
         });
-        // Clear all tracked instances after rollback
-        this.deployedInstances.clear();
+        const rolledBackResources = [];
+        const errors = [];
+        let status = 'success';
+        for (const instanceName of instanceNames) {
+            try {
+                const result = await this.rollbackInstanceResources(instanceName);
+                rolledBackResources.push(...result.rolledBackResources);
+                errors.push(...result.errors);
+                if (result.status === 'failed') {
+                    status = 'failed';
+                }
+                else if (result.status === 'partial' && status === 'success') {
+                    status = 'partial';
+                }
+                if (result.status === 'success' && result.errors.length === 0) {
+                    this.deployedInstances.delete(instanceName);
+                }
+            }
+            catch (error) {
+                status = 'failed';
+                errors.push({
+                    resourceId: instanceName,
+                    phase: 'rollback',
+                    error: ensureError(error),
+                    timestamp: new Date(),
+                });
+            }
+        }
+        if (errors.length > 0 && status === 'success') {
+            status = rolledBackResources.length > 0 ? 'partial' : 'failed';
+        }
+        const result = {
+            deploymentId: `factory-rollback-${Date.now()}`,
+            rolledBackResources,
+            duration: Date.now() - startedAt,
+            status,
+            errors,
+        };
+        if (result.status === 'success') {
+            this.deployedInstances.clear();
+        }
         this.logger.info('Rollback completed', {
             status: result.status,
             resourceCount: result.rolledBackResources.length,
@@ -572,10 +740,10 @@ export class DirectResourceFactoryImpl {
     /**
      * Create a resource graph for a specific instance
      */
-    createResourceGraphForInstance(spec) {
+    createResourceGraphForInstance(spec, instanceNameOverride) {
         const dependencyResolver = new DependencyResolver();
         const resolvedResources = this.resolveResourcesForSpec(spec);
-        const instanceName = this.generateInstanceName(spec);
+        const instanceName = instanceNameOverride ?? this.generateInstanceName(spec);
         const resourceArray = Object.values(resolvedResources).map((resource, index) => {
             this.logger.debug('Processing resource for ID generation', {
                 index,
@@ -662,7 +830,8 @@ export class DirectResourceFactoryImpl {
                 }
             }
             catch (error) {
-                this.logger.error('Failed to re-execute composition, falling back to reference resolution', ensureError(error));
+                this.logger.error('Failed to re-execute composition with actual spec values', ensureError(error));
+                throw error;
             }
         }
         // Fall back to the original reference resolution approach
@@ -699,6 +868,7 @@ export class DirectResourceFactoryImpl {
             // with the same id (e.g., 'regionDep') get unique keys ('regionDep', 'regionDep-1', etc.)
             const reExecutionContext = createCompositionContext('re-execution', {
                 deduplicateIds: true,
+                isReExecution: true,
             });
             // Execute the composition function within the new context and capture both resources and status
             const { resources, status } = runWithCompositionContext(reExecutionContext, () => {
@@ -737,7 +907,7 @@ export class DirectResourceFactoryImpl {
         }
         catch (error) {
             this.logger.error('Failed to re-execute composition', ensureError(error));
-            return null;
+            throw error;
         }
     }
     /**
@@ -747,6 +917,22 @@ export class DirectResourceFactoryImpl {
     getReExecutedStatus() {
         return this.reExecutedStatus;
     }
+    reExecuteSingletonStatus(singletonDefinition, liveStatusMap) {
+        const compositionFn = singletonDefinition.composition._compositionFn;
+        if (!compositionFn) {
+            return undefined;
+        }
+        const singletonContext = createCompositionContext('singleton-re-execution', {
+            deduplicateIds: true,
+            isReExecution: true,
+        });
+        singletonContext.liveStatusMap = liveStatusMap;
+        const status = runWithCompositionContext(singletonContext, () => compositionFn(singletonDefinition.spec));
+        if (status && typeof status === 'object' && !Array.isArray(status)) {
+            return status;
+        }
+        return undefined;
+    }
     /**
      * Re-execute the composition with live status data from deployed resources.
      *
@@ -773,6 +959,7 @@ export class DirectResourceFactoryImpl {
             // synthesize status entries from child resources' live data.
             const probeContext = createCompositionContext('re-execution-probe', {
                 deduplicateIds: true,
+                isReExecution: true,
             });
             probeContext.liveStatusMap = liveStatusMap;
             runWithCompositionContext(probeContext, () => {
@@ -787,10 +974,41 @@ export class DirectResourceFactoryImpl {
             // 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);
+            const enrichedMap = synthesizeNestedCompositionStatus(probeContext.resources, liveStatusMap, this.logger, probeContext.nestedCompositionIds, probeContext.nestedStatusSnapshots);
+            // Framework invariant: direct-mode re-execution must preserve the same
+            // cross-composition semantics as KRO-mode serialization. If a user writes
+            // `const stack = nestedComp(...); return { ready: stack.status.ready && ... }`,
+            // TypeKro must resolve that alias in the framework rather than pushing
+            // CEL-specific workarounds into composition code.
+            const aliasTargets = buildNestedCompositionAliasTargets(this.factoryOptions.compositionFn.toString(), probeContext.nestedCompositionIds);
+            for (const [aliasName, baseId] of Object.entries(aliasTargets)) {
+                const synthesizedStatus = enrichedMap.get(baseId);
+                if (synthesizedStatus && !enrichedMap.has(aliasName)) {
+                    enrichedMap.set(aliasName, synthesizedStatus);
+                }
+            }
+            const singletonDefinitions = new Map();
+            for (const definition of this.singletonDefinitions) {
+                singletonDefinitions.set(definition.key, definition);
+            }
+            for (const definition of probeContext.singletonDefinitions?.values() ?? []) {
+                singletonDefinitions.set(definition.key, definition);
+            }
+            for (const definition of singletonDefinitions.values()) {
+                const singletonResourceId = getSingletonResourceId(definition.key);
+                if (enrichedMap.has(singletonResourceId)) {
+                    continue;
+                }
+                const singletonStatus = this.singletonOwnerStatuses.get(singletonResourceId) ??
+                    this.reExecuteSingletonStatus(definition, liveStatusMap);
+                if (singletonStatus) {
+                    enrichedMap.set(singletonResourceId, singletonStatus);
+                }
+            }
             // Phase 2: Real execution with enriched live status map
             const reExecutionContext = createCompositionContext('re-execution', {
                 deduplicateIds: true,
+                isReExecution: true,
             });
             reExecutionContext.liveStatusMap = enrichedMap;
             const { status } = runWithCompositionContext(reExecutionContext, () => {
@@ -920,6 +1138,19 @@ export class DirectResourceFactoryImpl {
         }
         return { found: true, value: currentValue };
     }
+    resolveSpecPathValue(spec, specPath, logPath) {
+        const pathParts = specPath.split('.').filter(Boolean);
+        return this.traverseSpec(spec, pathParts, logPath);
+    }
+    stringifyCelFallbackValue(value) {
+        if (value === null)
+            return 'null';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return String(value);
+        return JSON.stringify(value);
+    }
     /**
      * 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.
@@ -949,15 +1180,24 @@ export class DirectResourceFactoryImpl {
             this.logger.trace('Found CEL Expression', { path, expression: resource.expression });
             // The .expression property holds a string like "schema.spec.name-db-config"
             let expressionString = resource.expression;
+            const exactSchemaRef = expressionString.match(/^schema\.spec\.([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)$/);
+            const exactSpecPath = exactSchemaRef?.[1];
+            if (exactSpecPath !== undefined) {
+                const resolved = this.resolveSpecPathValue(spec, exactSpecPath, path);
+                if (resolved.found) {
+                    return resolved.value;
+                }
+            }
             // Use regex to find all `schema.spec.fieldName` placeholders in the string
             // and replace them with the corresponding values from the spec object.
             // The 'g' flag ensures all occurrences are replaced.
-            expressionString = expressionString.replace(/schema\.spec\.(\w+)/g, (_match, fieldName) => {
-                const value = spec[fieldName];
-                this.logger.trace('Replacing CEL placeholder', { fieldName, value });
+            expressionString = expressionString.replace(/schema\.spec\.([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/g, (_match, specPath) => {
+                const resolved = this.resolveSpecPathValue(spec, specPath, path);
+                const value = resolved.found ? resolved.value : undefined;
+                this.logger.trace('Replacing CEL placeholder', { specPath, value });
                 // If the value exists in the spec, convert it to a string for concatenation.
                 // Otherwise, keep the original placeholder (though this shouldn't happen in valid cases).
-                return value !== undefined ? String(value) : _match;
+                return value !== undefined ? this.stringifyCelFallbackValue(value) : _match;
             });
             this.logger.trace('Resolved CEL expression to value', {
                 path,
@@ -1007,7 +1247,7 @@ export class DirectResourceFactoryImpl {
             // 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) => {
+            const resolvedString = resource.replace(new RegExp(KUBERNETES_REF_SCHEMA_MARKER_SOURCE, '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'
@@ -1050,6 +1290,259 @@ export class DirectResourceFactoryImpl {
         // Use the imported shared utility
         return generateInstanceName(spec);
     }
+    async ensureTargetNamespace(namespace = this.namespace) {
+        try {
+            const { createBunCompatibleKubernetesObjectApi } = await import('../kubernetes/bun-api-client.js');
+            const k8sApi = createBunCompatibleKubernetesObjectApi(this.getClientProvider().getKubeConfig());
+            const waitForNamespaceDeletion = async () => {
+                const start = Date.now();
+                while (Date.now() - start < 120000) {
+                    try {
+                        const existing = (await k8sApi.read({
+                            apiVersion: 'v1',
+                            kind: 'Namespace',
+                            metadata: { name: namespace },
+                        }));
+                        if (!existing.metadata?.deletionTimestamp) {
+                            return;
+                        }
+                    }
+                    catch (pollError) {
+                        const err = pollError;
+                        const code = err.statusCode ?? err.body?.code;
+                        if (code === 404) {
+                            return;
+                        }
+                        throw pollError;
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                }
+                throw new Error(`Namespace ${namespace} is still terminating after 120000ms`);
+            };
+            try {
+                const existing = (await k8sApi.read({
+                    apiVersion: 'v1',
+                    kind: 'Namespace',
+                    metadata: { name: namespace },
+                }));
+                if (existing.metadata?.deletionTimestamp) {
+                    await waitForNamespaceDeletion();
+                }
+                else {
+                    return;
+                }
+            }
+            catch (readError) {
+                const k8sErr = readError;
+                const code = k8sErr.statusCode ?? k8sErr.body?.code;
+                if (code !== 404) {
+                    throw readError;
+                }
+            }
+            try {
+                await k8sApi.create({
+                    apiVersion: 'v1',
+                    kind: 'Namespace',
+                    metadata: {
+                        name: namespace,
+                        labels: {
+                            'app.kubernetes.io/managed-by': 'typekro',
+                        },
+                    },
+                });
+            }
+            catch (createError) {
+                const k8sErr = createError;
+                const code = k8sErr.statusCode ?? k8sErr.body?.code;
+                const isNamespaceTerminating = k8sErr.body?.reason === 'Forbidden' &&
+                    k8sErr.message?.includes('NamespaceTerminating') === true;
+                if (isNamespaceTerminating) {
+                    await waitForNamespaceDeletion();
+                    await k8sApi.create({
+                        apiVersion: 'v1',
+                        kind: 'Namespace',
+                        metadata: {
+                            name: namespace,
+                            labels: {
+                                'app.kubernetes.io/managed-by': 'typekro',
+                            },
+                        },
+                    });
+                }
+                else if (code !== 409) {
+                    throw createError;
+                }
+            }
+        }
+        catch (error) {
+            throw new ResourceGraphFactoryError(`Failed to ensure target namespace "${namespace}" exists: ${ensureError(error).message}`, this.name, 'deployment', ensureError(error));
+        }
+    }
+    async ensureSingletonOwners(spec) {
+        const discoveredSingletons = new Map();
+        if (this.factoryOptions.compositionFn) {
+            const singletonContext = createCompositionContext('singleton-owner-discovery');
+            runWithCompositionContext(singletonContext, () => {
+                this.factoryOptions.compositionFn?.(spec);
+            });
+            for (const [key, definition] of singletonContext.singletonDefinitions ?? []) {
+                discoveredSingletons.set(key, definition);
+            }
+        }
+        for (const definition of this.singletonDefinitions) {
+            if (!discoveredSingletons.has(definition.key)) {
+                discoveredSingletons.set(definition.key, definition);
+            }
+        }
+        if (discoveredSingletons.size === 0)
+            return;
+        for (const definition of discoveredSingletons.values()) {
+            await this.ensureTargetNamespace(definition.registryNamespace);
+            const singletonInstanceName = getSingletonInstanceName(definition.id);
+            const singletonFactory = definition.composition.factory('direct', {
+                namespace: definition.registryNamespace,
+                waitForReady: true,
+                ...(this.factoryOptions.timeout !== undefined ? { timeout: this.factoryOptions.timeout } : {}),
+                ...(this.factoryOptions.kubeConfig !== undefined ? { kubeConfig: this.factoryOptions.kubeConfig } : {}),
+                ...(this.factoryOptions.skipTLSVerify !== undefined ? { skipTLSVerify: this.factoryOptions.skipTLSVerify } : {}),
+            });
+            try {
+                const existingInstances = await singletonFactory.getInstances();
+                assertNoDeployedSingletonSpecDrift(definition, singletonInstanceName, existingInstances);
+                if ('createResourceGraphForInstance' in singletonFactory && existingInstances.length === 0) {
+                    const discovered = await this.getDeploymentEngine().loadDeploymentByInstance({
+                        factoryName: singletonFactory.name,
+                        instanceName: singletonInstanceName,
+                    });
+                    const discoveredResources = discovered?.resources ?? [];
+                    const driftCheck = assertNoDiscoveredSingletonSpecDrift(definition, singletonInstanceName, discoveredResources);
+                    if (driftCheck.hasLegacyUnfingerprintedResources) {
+                        const expectedGraph = singletonFactory.createResourceGraphForInstance(definition.spec, singletonInstanceName);
+                        const discoveredIds = new Set(discoveredResources.map((resource) => resource.id));
+                        const hasAllExpectedResources = expectedGraph.resources.every((resource) => discoveredIds.has(resource.id));
+                        const hasHelmReleaseResources = expectedGraph.resources.some((resource) => resource.manifest.kind === 'HelmRelease');
+                        const legacyStatus = this.reExecuteSingletonStatusFromDiscoveredResources(definition, discoveredResources);
+                        if (legacyStatus) {
+                            this.singletonOwnerStatuses.set(getSingletonResourceId(definition.key), legacyStatus);
+                        }
+                        if (hasAllExpectedResources && !hasHelmReleaseResources) {
+                            this.logger.warn('Skipping direct singleton owner reconciliation for legacy resources without a spec fingerprint', {
+                                singletonId: definition.id,
+                                singletonKey: definition.key,
+                                singletonInstanceName,
+                                registryNamespace: definition.registryNamespace,
+                            });
+                            continue;
+                        }
+                        this.logger.warn('Reconciling direct singleton owner because legacy resources may need repair', {
+                            singletonId: definition.id,
+                            singletonKey: definition.key,
+                            singletonInstanceName,
+                            registryNamespace: definition.registryNamespace,
+                            discoveredResourceCount: discoveredResources.length,
+                            expectedResourceCount: expectedGraph.resources.length,
+                            hasAllExpectedResources,
+                            hasHelmReleaseResources,
+                        });
+                    }
+                }
+                const singletonDeployOptions = {
+                    instanceNameOverride: singletonInstanceName,
+                    singletonSpecFingerprint: singletonSpecFingerprintAnnotationValue(definition.specFingerprint),
+                };
+                const deployedSingleton = await singletonFactory.deploy(definition.spec, singletonDeployOptions);
+                const singletonStatus = deployedSingleton.status;
+                if (singletonStatus && typeof singletonStatus === 'object' && !Array.isArray(singletonStatus)) {
+                    this.singletonOwnerStatuses.set(getSingletonResourceId(definition.key), singletonStatus);
+                }
+            }
+            finally {
+                await singletonFactory.dispose?.();
+            }
+        }
+    }
+    reExecuteSingletonStatusFromDiscoveredResources(definition, resources) {
+        if (resources.length === 0)
+            return null;
+        const liveStatusMap = new Map();
+        const localIdsByLiveIdentity = this.getSingletonLocalIdsByLiveIdentity(definition);
+        const singletonInstanceName = getSingletonInstanceName(definition.id);
+        for (const resource of resources) {
+            const manifest = resource.manifest;
+            const status = manifest && typeof manifest === 'object' && 'status' in manifest
+                ? manifest.status
+                : undefined;
+            const statusRecord = status && typeof status === 'object' && !Array.isArray(status)
+                ? status
+                : {};
+            for (const id of this.getSingletonStatusAliases(resource.id, manifest, singletonInstanceName, localIdsByLiveIdentity)) {
+                liveStatusMap.set(id, statusRecord);
+            }
+        }
+        return this.reExecuteSingletonStatus(definition, liveStatusMap) ?? null;
+    }
+    getSingletonLocalIdsByLiveIdentity(definition) {
+        const compositionFn = definition.composition._compositionFn;
+        const idsByIdentity = new Map();
+        if (!compositionFn)
+            return idsByIdentity;
+        const probeContext = createCompositionContext('singleton-status-discovery-probe', {
+            deduplicateIds: true,
+            isReExecution: true,
+        });
+        runWithCompositionContext(probeContext, () => compositionFn(definition.spec));
+        for (const [id, resource] of Object.entries(probeContext.resources)) {
+            const identity = this.getLiveIdentityKey(resource.kind, resource.metadata?.name, resource.metadata?.namespace);
+            if (identity)
+                idsByIdentity.set(identity, id);
+            const namespaceAgnosticIdentity = this.getLiveIdentityKey(resource.kind, resource.metadata?.name);
+            if (namespaceAgnosticIdentity)
+                idsByIdentity.set(namespaceAgnosticIdentity, id);
+        }
+        return idsByIdentity;
+    }
+    getSingletonStatusAliases(discoveredId, manifest, singletonInstanceName, localIdsByLiveIdentity) {
+        const aliases = new Set([discoveredId]);
+        const annotationId = manifest && typeof manifest === 'object'
+            ? manifest.metadata?.annotations?.['typekro.io/resource-id']
+            : undefined;
+        if (annotationId)
+            aliases.add(annotationId);
+        const derivedId = this.deriveLocalIdFromDirectGraphId(discoveredId, singletonInstanceName, localIdsByLiveIdentity.values());
+        if (derivedId)
+            aliases.add(derivedId);
+        if (manifest && typeof manifest === 'object') {
+            const resource = manifest;
+            const identity = this.getLiveIdentityKey(resource.kind, resource.metadata?.name, resource.metadata?.namespace);
+            const namespaceAgnosticIdentity = this.getLiveIdentityKey(resource.kind, resource.metadata?.name);
+            const localId = (identity ? localIdsByLiveIdentity.get(identity) : undefined) ??
+                (namespaceAgnosticIdentity ? localIdsByLiveIdentity.get(namespaceAgnosticIdentity) : undefined);
+            if (localId)
+                aliases.add(localId);
+        }
+        return [...aliases];
+    }
+    deriveLocalIdFromDirectGraphId(id, singletonInstanceName, candidateLocalIds = []) {
+        const prefix = `${toCamelCase(singletonInstanceName)}Resource`;
+        const match = id.match(new RegExp(`^${prefix}\\d+(.+)$`));
+        if (!match?.[1])
+            return undefined;
+        const suffix = match[1].charAt(0).toLowerCase() + match[1].slice(1);
+        const normalizedSuffix = suffix.toLowerCase();
+        for (const candidate of candidateLocalIds) {
+            if (candidate === suffix ||
+                candidate.toLowerCase() === normalizedSuffix ||
+                toCamelCase(candidate).toLowerCase() === normalizedSuffix) {
+                return candidate;
+            }
+        }
+        return suffix;
+    }
+    getLiveIdentityKey(kind, name, namespace) {
+        if (!kind || !name)
+            return undefined;
+        return `${kind}/${namespace ?? ''}/${name}`;
+    }
 }
 /**
  * Recursively walk a resolved resource tree and collect any remaining
@@ -1107,7 +1600,9 @@ function findUnresolvedReferences(resources) {
 /**
  * Create a DirectResourceFactory instance
  */
-export function createDirectResourceFactory(name, resources, schemaDefinition, statusBuilder, options = {}) {
+export function createDirectResourceFactory(name, resources, schemaDefinition, 
+// biome-ignore lint/suspicious/noExplicitAny: factory creation must accept status builders with composition-specific resource maps.
+statusBuilder, options = {}) {
     return new DirectResourceFactoryImpl(name, resources, schemaDefinition, statusBuilder, options);
 }
 //# sourceMappingURL=direct-factory.js.map