typekro 0.4.0 → 0.5.0

package/dist/core/composition/context.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Composition Context Infrastructure
+ *
+ * This module owns the AsyncLocalStorage singletons that track the active
+ * composition and status-builder contexts. It was extracted from
+ * `src/factories/shared.ts` to fix an architectural inversion where
+ * `src/core/` depended on `src/factories/` for foundational infrastructure.
+ *
+ * **Singleton guarantee:** The AsyncLocalStorage instances are module-scoped
+ * constants. Every consumer (core and factories alike) must import from this
+ * single canonical location to avoid accidental duplication.
+ */
+import type { DeploymentClosure } from '../types/deployment.js';
+import type { Enhanced } from '../types.js';
+/**
+ * Context for imperative composition pattern.
+ * Tracks resources and deployment closures created during composition function execution.
+ */
+export interface CompositionContext {
+    /** Map of resource ID to Enhanced resource */
+    resources: Record<string, Enhanced<any, any>>;
+    /** Map of closure ID to deployment closure */
+    closures: Record<string, DeploymentClosure>;
+    /** Counter for generating unique resource IDs */
+    resourceCounter: number;
+    /** Counter for generating unique closure IDs */
+    closureCounter: number;
+    /** Counter for composition instances */
+    compositionInstanceCounter: number;
+    /** Map of variable names to resource IDs for CEL expression generation */
+    variableMappings: Record<string, string>;
+    /** Add a resource to the context */
+    addResource(id: string, resource: Enhanced<any, any>): void;
+    /** Add a deployment closure to the context */
+    addClosure(id: string, closure: DeploymentClosure): void;
+    /** Add a variable to resource ID mapping */
+    addVariableMapping(variableName: string, resourceId: string): void;
+    /** Generate a unique resource ID */
+    generateResourceId(kind: string, name?: string): string;
+    /** Generate a unique closure ID */
+    generateClosureId(name?: string): string;
+}
+/**
+ * Options for composition context creation.
+ */
+export interface CompositionContextOptions {
+    /**
+     * When true, duplicate resource IDs get a numeric suffix instead of overwriting.
+     * Used during direct-mode re-execution where forEach loops create multiple
+     * resources with the same id (e.g., 'regionDep' → 'regionDep', 'regionDep-1', 'regionDep-2').
+     */
+    deduplicateIds?: boolean;
+}
+/**
+ * Check if the current execution is within a status builder context.
+ */
+export declare function isInStatusBuilderContext(): boolean;
+/**
+ * Run a function within a status builder context where Enhanced resource
+ * proxies return KubernetesRef objects for all property access.
+ */
+export declare function runInStatusBuilderContext<T>(fn: () => T): T;
+/**
+ * Get the current composition context if one is active.
+ * @returns The active composition context or undefined if not in composition
+ */
+export declare function getCurrentCompositionContext(): CompositionContext | undefined;
+/**
+ * Run a function with a composition context.
+ * @param context The composition context to use
+ * @param fn The function to run with the context
+ * @returns The result of the function
+ */
+export declare function runWithCompositionContext<T>(context: CompositionContext, fn: () => T): T;
+/**
+ * Generic deployment closure registration wrapper.
+ * Automatically registers any deployment closure with the active composition context.
+ *
+ * @param closureFactory Function that creates the deployment closure
+ * @param name Optional name for the closure (used for ID generation)
+ * @returns The deployment closure, registered with context if active
+ */
+export declare function registerDeploymentClosure<T extends DeploymentClosure>(closureFactory: () => T, name?: string): T;
+/**
+ * Create a new composition context with default implementations.
+ * @param name Optional name for the composition (used in ID generation)
+ * @param contextOptions Options controlling context behavior
+ * @returns A new composition context
+ */
+export declare function createCompositionContext(name?: string, contextOptions?: CompositionContextOptions): CompositionContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/core/composition/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/core/composition/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAM5C;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC5C,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,0BAA0B,EAAE,MAAM,CAAC;IACnC,0EAA0E;IAC1E,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,oCAAoC;IACpC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC5D,8CAA8C;IAC9C,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACzD,4CAA4C;IAC5C,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnE,oCAAoC;IACpC,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxD,mCAAmC;IACnC,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AA4BD;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE3D;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,kBAAkB,GAAG,SAAS,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,OAAO,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAExF;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,iBAAiB,EACnE,cAAc,EAAE,MAAM,CAAC,EACvB,IAAI,CAAC,EAAE,MAAM,GACZ,CAAC,CAYH;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,CAAC,EAAE,MAAM,EACb,cAAc,CAAC,EAAE,yBAAyB,GACzC,kBAAkB,CAkCpB"}

package/dist/core/composition/context.js

@@ -0,0 +1,125 @@
+/**
+ * Composition Context Infrastructure
+ *
+ * This module owns the AsyncLocalStorage singletons that track the active
+ * composition and status-builder contexts. It was extracted from
+ * `src/factories/shared.ts` to fix an architectural inversion where
+ * `src/core/` depended on `src/factories/` for foundational infrastructure.
+ *
+ * **Singleton guarantee:** The AsyncLocalStorage instances are module-scoped
+ * constants. Every consumer (core and factories alike) must import from this
+ * single canonical location to avoid accidental duplication.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+// =============================================================================
+// ASYNC-LOCAL-STORAGE SINGLETONS
+// =============================================================================
+/**
+ * AsyncLocalStorage for composition context.
+ * Enables context-aware resource registration across async boundaries.
+ */
+const COMPOSITION_CONTEXT = new AsyncLocalStorage();
+/**
+ * AsyncLocalStorage for status builder context.
+ *
+ * When active, property access on Enhanced resource proxies always returns
+ * KubernetesRef objects (instead of eager values), enabling JavaScript-to-CEL
+ * conversion in status builder functions.
+ *
+ * Replaces the previous `(globalThis as any).__TYPEKRO_STATUS_BUILDER_CONTEXT__`
+ * mutable global flag with a properly scoped, async-safe context.
+ */
+const STATUS_BUILDER_CONTEXT = new AsyncLocalStorage();
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+/**
+ * Check if the current execution is within a status builder context.
+ */
+export function isInStatusBuilderContext() {
+    return STATUS_BUILDER_CONTEXT.getStore() === true;
+}
+/**
+ * Run a function within a status builder context where Enhanced resource
+ * proxies return KubernetesRef objects for all property access.
+ */
+export function runInStatusBuilderContext(fn) {
+    return STATUS_BUILDER_CONTEXT.run(true, fn);
+}
+/**
+ * Get the current composition context if one is active.
+ * @returns The active composition context or undefined if not in composition
+ */
+export function getCurrentCompositionContext() {
+    return COMPOSITION_CONTEXT.getStore();
+}
+/**
+ * Run a function with a composition context.
+ * @param context The composition context to use
+ * @param fn The function to run with the context
+ * @returns The result of the function
+ */
+export function runWithCompositionContext(context, fn) {
+    return COMPOSITION_CONTEXT.run(context, fn);
+}
+/**
+ * Generic deployment closure registration wrapper.
+ * Automatically registers any deployment closure with the active composition context.
+ *
+ * @param closureFactory Function that creates the deployment closure
+ * @param name Optional name for the closure (used for ID generation)
+ * @returns The deployment closure, registered with context if active
+ */
+export function registerDeploymentClosure(closureFactory, name) {
+    const context = getCurrentCompositionContext();
+    if (context) {
+        const closure = closureFactory();
+        const closureId = context.generateClosureId(name);
+        context.addClosure(closureId, closure);
+        return closure;
+    }
+    // Outside composition context - return closure as-is
+    return closureFactory();
+}
+/**
+ * Create a new composition context with default implementations.
+ * @param name Optional name for the composition (used in ID generation)
+ * @param contextOptions Options controlling context behavior
+ * @returns A new composition context
+ */
+export function createCompositionContext(name, contextOptions) {
+    const idCounts = {};
+    return {
+        resources: {},
+        closures: {},
+        resourceCounter: 0,
+        closureCounter: 0,
+        compositionInstanceCounter: 0,
+        variableMappings: {},
+        addResource(id, resource) {
+            if (contextOptions?.deduplicateIds && id in this.resources) {
+                // Append numeric suffix to make the key unique
+                idCounts[id] = (idCounts[id] ?? 0) + 1;
+                const count = idCounts[id];
+                this.resources[`${id}-${count}`] = resource;
+            }
+            else {
+                this.resources[id] = resource;
+            }
+        },
+        addClosure(id, closure) {
+            this.closures[id] = closure;
+        },
+        addVariableMapping(variableName, resourceId) {
+            this.variableMappings[variableName] = resourceId;
+        },
+        generateResourceId(kind, resourceName) {
+            return resourceName || `${kind.toLowerCase()}-${++this.resourceCounter}`;
+        },
+        generateClosureId(closureName) {
+            const prefix = name ? `${name}-` : '';
+            return closureName ? `${prefix}${closureName}` : `${prefix}closure-${++this.closureCounter}`;
+        },
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/core/composition/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/core/composition/context.ts"],"names":[],"mappings":"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"}

package/dist/core/composition/imperative.d.ts

@@ -8,10 +8,6 @@
  */
 import type { CallableComposition } from '../types/deployment.js';
 import type { KroCompatibleType, MagicAssignableShape, ResourceGraphDefinition, SerializationOptions } from '../types/serialization.js';
-/**
- * Enable debug mode for composition execution
- * This will log detailed information about resource registration, status building, and performance
- */
 export declare function enableCompositionDebugging(): void;
 /**
  * Disable debug mode for composition execution
@@ -27,13 +23,43 @@ export declare function getCompositionDebugLogs(): string[];
  */
 export declare function clearCompositionDebugLogs(): void;
 /**
- * Create an imperative composition that automatically captures resources
- * and returns status objects using MagicAssignableShape
+ * Create an imperative Kubernetes composition using natural TypeScript.
+ *
+ * Unlike {@link toResourceGraph} which uses separate resource/status builders,
+ * `kubernetesComposition` lets you write a single function that creates resources
+ * inline. Resources are automatically captured via the magic proxy system.
+ * The returned callable composition can be deployed directly or nested inside
+ * other compositions.
  *
- * @param definition - The resource graph definition with schemas
- * @param compositionFn - Synchronous function that takes spec and returns MagicAssignableShape<TStatus>
+ * @typeParam TSpec - The arktype schema for the custom resource's spec
+ * @typeParam TStatus - The arktype schema for the custom resource's status
+ *
+ * @param definition - The RGD metadata: name, apiVersion, kind, spec/status schemas
+ * @param compositionFn - Imperative function receiving the spec, creates resources
+ *   inline, and returns a status shape. Resources created with factory functions
+ *   (e.g., `Deployment()`, `Service()`) are automatically registered.
  * @param options - Optional serialization options
- * @returns TypedResourceGraph directly (not a factory)
+ * @returns A `CallableComposition` that can be deployed or nested inside other compositions
+ *
+ * @example
+ * ```typescript
+ * const webapp = kubernetesComposition(
+ *   {
+ *     name: 'webapp',
+ *     apiVersion: 'apps.example.com/v1alpha1',
+ *     kind: 'WebApp',
+ *     spec: type({ name: 'string', replicas: 'number' }),
+ *     status: type({ ready: 'boolean' }),
+ *   },
+ *   (spec) => {
+ *     const deploy = Deployment({ name: spec.name, replicas: spec.replicas });
+ *     const svc = Service({ name: spec.name });
+ *     return {
+ *       ready: Cel.expr<boolean>(deploy.status.readyReplicas, ' > 0'),
+ *     };
+ *   },
+ * );
+ * ```
  */
-export declare function kubernetesComposition<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType>(definition: ResourceGraphDefinition<TSpec, TStatus>, compositionFn: (spec: TSpec) => TStatus | MagicAssignableShape<TStatus>, options?: SerializationOptions): CallableComposition<TSpec, TStatus>;
+export declare function kubernetesComposition<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType>(definition: ResourceGraphDefinition<TSpec, TStatus>, compositionFn: (spec: TSpec) => MagicAssignableShape<TStatus>, options?: SerializationOptions): CallableComposition<TSpec, TStatus>;
 //# sourceMappingURL=imperative.d.ts.map

package/dist/core/composition/imperative.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imperative.d.ts","sourceRoot":"","sources":["../../../src/core/composition/imperative.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,OAAO,KAAK,EAAsB,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EAEvB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AAGnC;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAElD;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAskBD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,SAAS,iBAAiB,EAC/B,OAAO,SAAS,iBAAiB,EAEjC,UAAU,EAAE,uBAAuB,CAAC,KAAK,EAAE,OAAO,CAAC,EACnD,aAAa,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,oBAAoB,CAAC,OAAO,CAAC,EACvE,OAAO,CAAC,EAAE,oBAAoB,GAC7B,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAyOrC"}
+{"version":3,"file":"imperative.d.ts","sourceRoot":"","sources":["../../../src/core/composition/imperative.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,KAAK,EACV,mBAAmB,EAIpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EAEvB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AAgBnC,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAElD;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AA8iBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,SAAS,iBAAiB,EAC/B,OAAO,SAAS,iBAAiB,EAEjC,UAAU,EAAE,uBAAuB,CAAC,KAAK,EAAE,OAAO,CAAC,EACnD,aAAa,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,oBAAoB,CAAC,OAAO,CAAC,EAC7D,OAAO,CAAC,EAAE,oBAAoB,GAC7B,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAyOrC"}

package/dist/core/composition/imperative.js

@@ -6,14 +6,17 @@
  * automatically generating the same robust, type-safe ResourceGraphDefinitions
  * as the existing toResourceGraph API.
  */
-import { createCompositionContext, getCurrentCompositionContext, runWithCompositionContext, } from '../../factories/shared.js';
-import { CompositionDebugger, CompositionExecutionError } from '../errors.js';
+import { CompositionDebugger } from '../composition-debugger.js';
 import { CALLABLE_COMPOSITION_BRAND, KUBERNETES_REF_BRAND, NESTED_COMPOSITION_BRAND, } from '../constants/brands.js';
+import { CompositionExecutionError, ensureError } from '../errors.js';
+import { getComponentLogger } from '../logging/index.js';
 import { toResourceGraph } from '../serialization/core.js';
+import { createCompositionContext, getCurrentCompositionContext, runInStatusBuilderContext, runWithCompositionContext, } from './context.js';
 /**
  * Enable debug mode for composition execution
  * This will log detailed information about resource registration, status building, and performance
  */
+const logger = getComponentLogger('imperative-composition');
 export function enableCompositionDebugging() {
     CompositionDebugger.enableDebugMode();
 }
@@ -147,6 +150,59 @@ function executeNestedCompositionWithSpec(definition, compositionFn, options, pa
     };
     return nestedCompositionResource;
 }
+/**
+ * KubernetesRef metadata property names used by the proxy allowlist strategy.
+ * When `useAllowlist` is true, only these properties are returned from the
+ * proxy target — all other string accesses create nested proxies.
+ */
+const KUBERNETES_REF_PROXY_PROPS = new Set([
+    KUBERNETES_REF_BRAND,
+    'resourceId',
+    'fieldPath',
+    '__nestedComposition',
+]);
+/**
+ * Create a recursive proxy that returns `KubernetesRef` objects for
+ * arbitrarily deep property access.
+ *
+ * Two property-resolution strategies are supported:
+ * - `useAllowlist: false` (default) — uses `prop in target` to decide
+ *   whether to return the target value or create a nested proxy.
+ * - `useAllowlist: true` — only the four KubernetesRef metadata properties
+ *   (`KUBERNETES_REF_BRAND`, `resourceId`, `fieldPath`, `__nestedComposition`)
+ *   are returned from the target; everything else creates a nested proxy.
+ *
+ * @param resourceId  - The resource identifier embedded in every ref
+ * @param basePath    - The initial field path (e.g. `'status'` or `''`)
+ * @param useAllowlist - When true, use an explicit allowlist instead of `prop in target`
+ */
+function createKubernetesRefProxy(resourceId, basePath, useAllowlist = false) {
+    const baseObj = {
+        [KUBERNETES_REF_BRAND]: true,
+        resourceId,
+        fieldPath: basePath,
+        __nestedComposition: true,
+    };
+    return new Proxy(baseObj, {
+        get(target, prop) {
+            // Determine whether to return the target property directly
+            const isKnownProp = useAllowlist
+                ? typeof prop === 'string' || typeof prop === 'symbol'
+                    ? KUBERNETES_REF_PROXY_PROPS.has(prop)
+                    : false
+                : prop in target;
+            if (isKnownProp) {
+                return target[prop];
+            }
+            // For any other string property, create a nested proxy
+            if (typeof prop === 'string') {
+                const fullPath = basePath ? `${basePath}.${prop}` : prop;
+                return createKubernetesRefProxy(resourceId, fullPath, useAllowlist);
+            }
+            return undefined;
+        },
+    });
+}
 /**
  * Create a status proxy for cross-composition references
  * @param compositionName - Name of the composition
@@ -154,90 +210,20 @@ function executeNestedCompositionWithSpec(definition, compositionFn, options, pa
  * @param nestedResult - The result of executing the nested composition
  * @param forCompositionProperty - If true, create KubernetesRef proxy for composition.status; if false, create for call result
  */
-function createStatusProxy(compositionName, parentContext, nestedResult, forCompositionProperty = false) {
-    // For CallableComposition.status property, always return KubernetesRef-based proxy
-    // This enables cross-composition references like: const ready = otherComposition.status.ready
-    if (forCompositionProperty) {
-        const resourceId = compositionName;
-        function createRecursiveProxy(basePath) {
-            const baseObj = {
-                [KUBERNETES_REF_BRAND]: true,
-                resourceId,
-                fieldPath: basePath,
-                __nestedComposition: true,
-            };
-            return new Proxy(baseObj, {
-                get(target, prop) {
-                    if (prop in target) {
-                        return target[prop];
-                    }
-                    if (typeof prop === 'string') {
-                        const fullPath = basePath ? `${basePath}.${prop}` : prop;
-                        return createRecursiveProxy(fullPath);
-                    }
-                    return undefined;
-                },
-            });
-        }
-        return createRecursiveProxy('status');
-    }
-    // For nested composition call results within a parent context,
-    // create a recursive proxy that returns KubernetesRef objects
-    // This enables deep property access like nested.status.metadata.name
-    if (parentContext) {
-        const resourceId = compositionName;
-        function createRecursiveProxy(basePath) {
-            const baseObj = {
-                [KUBERNETES_REF_BRAND]: true,
-                resourceId,
-                fieldPath: basePath,
-                __nestedComposition: true,
-            };
-            return new Proxy(baseObj, {
-                get(target, prop) {
-                    if (prop in target) {
-                        return target[prop];
-                    }
-                    if (typeof prop === 'string') {
-                        const fullPath = basePath ? `${basePath}.${prop}` : prop;
-                        return createRecursiveProxy(fullPath);
-                    }
-                    return undefined;
-                },
-            });
-        }
-        return createRecursiveProxy('status');
-    }
-    // For top-level composition calls (no parent context),
-    // create a proxy that returns KubernetesRef objects
-    const resourceId = `${compositionName}-status`;
-    function createRecursiveProxy(basePath) {
-        const baseObj = {
-            [KUBERNETES_REF_BRAND]: true,
-            resourceId,
-            fieldPath: basePath,
-            __nestedComposition: true,
-        };
-        return new Proxy(baseObj, {
-            get(target, prop) {
-                // Only return the actual KubernetesRef metadata properties
-                // Don't intercept other property accesses - let them create nested proxies
-                if (prop === KUBERNETES_REF_BRAND ||
-                    prop === 'resourceId' ||
-                    prop === 'fieldPath' ||
-                    prop === '__nestedComposition') {
-                    return target[prop];
-                }
-                // For any other string property, create a nested proxy to support deep access like status.metadata.name
-                if (typeof prop === 'string') {
-                    const fullPath = basePath ? `${basePath}.${prop}` : prop;
-                    return createRecursiveProxy(fullPath);
-                }
-                return undefined;
-            },
-        });
+function createStatusProxy(compositionName, parentContext, _nestedResult, forCompositionProperty = false) {
+    // For CallableComposition.status property or nested composition results
+    // within a parent context, create a KubernetesRef proxy using the
+    // composition name as resource ID and 'status' as the base path.
+    // Cast is intentional: the proxy creates KubernetesRef shapes at runtime,
+    // but exposes TStatus to the compiler for type-safe property access.
+    if (forCompositionProperty || parentContext) {
+        return createKubernetesRefProxy(compositionName, 'status');
     }
-    return createRecursiveProxy('');
+    // For top-level composition calls (no parent context), use the strict
+    // allowlist strategy so only KubernetesRef metadata properties are
+    // returned directly from the target, and start from an empty base path.
+    return createKubernetesRefProxy(`${compositionName}-status`, '', 
+    /* useAllowlist */ true);
 }
 /**
  * Global composition counter for unique identifier generation
@@ -303,23 +289,15 @@ function executeCompositionCore(definition, compositionFn, options, context, com
                     CompositionDebugger.logResourceRegistration(id, resourceKind, 'factory-function');
                 };
                 const resourceBuildStart = Date.now();
-                // Execute the composition function in a special context that preserves KubernetesRef objects
-                // This allows JavaScript expressions to be converted to CEL during serialization
-                globalThis.__TYPEKRO_STATUS_BUILDER_CONTEXT__ = true;
-                try {
-                    // Use the actual spec directly when provided, otherwise use schema spec
-                    const specToUse = actualSpec || schema.spec;
-                    capturedStatus = compositionFn(specToUse);
-                    // Store the original composition function for later analysis
-                    // This allows the serialization system to analyze the original JavaScript expressions
-                    capturedStatus.__originalCompositionFn = compositionFn;
-                    capturedStatus.__originalSchema = schema.spec;
-                    // Debug logging removed for cleaner output
-                }
-                finally {
-                    // Always clean up the global flag
-                    delete globalThis.__TYPEKRO_STATUS_BUILDER_CONTEXT__;
-                }
+                // Execute the composition function in a status builder context where
+                // Enhanced resource proxies return KubernetesRef objects, enabling
+                // JavaScript-to-CEL conversion during serialization.
+                const specToUse = actualSpec || schema.spec;
+                capturedStatus = runInStatusBuilderContext(() => compositionFn(specToUse));
+                // Store the original composition function for later analysis
+                // This allows the serialization system to analyze the original JavaScript expressions
+                Reflect.set(capturedStatus, '__originalCompositionFn', compositionFn);
+                Reflect.set(capturedStatus, '__originalSchema', schema.spec);
                 const resourceBuildEnd = Date.now();
                 CompositionDebugger.logPerformanceMetrics('Resource Building', resourceBuildStart, resourceBuildEnd, {
                     resourceCount: Object.keys(context.resources).length,
@@ -332,14 +310,16 @@ function executeCompositionCore(definition, compositionFn, options, context, com
                 for (const [id, resource] of Object.entries(context.resources)) {
                     combined[id] = resource;
                 }
-                // Add deployment closures (cast them as Enhanced resources for compatibility)
+                // Type cast: closures and Enhanced resources share the same map for sequential
+                // processing. Closures are functions but are stored under Enhanced<> type here;
+                // code that reads this map uses duck-typing to distinguish them at runtime.
                 for (const [id, closure] of Object.entries(context.closures)) {
                     combined[id] = closure;
                 }
                 return combined;
             }
             catch (error) {
-                throw CompositionExecutionError.withResourceContext(`Failed to execute composition function: ${error instanceof Error ? error.message : String(error)}`, compositionName, 'resource-creation', 'composition-function', 'composition', 'kubernetesComposition', error instanceof Error ? error : undefined);
+                throw CompositionExecutionError.withResourceContext(`Failed to execute composition function: ${ensureError(error).message}`, compositionName, 'resource-creation', 'composition-function', 'composition', 'kubernetesComposition', ensureError(error));
             }
         }, 
         // Status builder - return the captured status
@@ -353,7 +333,7 @@ function executeCompositionCore(definition, compositionFn, options, context, com
                 // Return the status captured during resource building
                 // This avoids double execution and ensures resources are available
                 if (!capturedStatus) {
-                    throw new Error('Status was not captured during resource building phase');
+                    throw new CompositionExecutionError('Status was not captured during resource building phase', compositionName, 'status-building');
                 }
                 return capturedStatus;
             }
@@ -361,7 +341,7 @@ function executeCompositionCore(definition, compositionFn, options, context, com
                 if (error instanceof CompositionExecutionError) {
                     throw error;
                 }
-                throw CompositionExecutionError.forStatusBuilding(compositionName, 'status-object', 'MagicAssignableShape<TStatus>', capturedStatus, error instanceof Error ? error : undefined);
+                throw CompositionExecutionError.forStatusBuilding(compositionName, 'status-object', 'MagicAssignableShape<TStatus>', capturedStatus, ensureError(error));
             }
         }, options);
         // For executed compositions (when called with a spec), replace the schema status with the executed status values
@@ -417,29 +397,61 @@ function executeCompositionCore(definition, compositionFn, options, context, com
         }
         catch (error) {
             // If we can't add properties to the result object, log a warning but continue
-            console.warn('Could not store composition function for re-execution:', error);
+            logger.warn('Could not store composition function for re-execution', {
+                error: String(error),
+            });
         }
         return result;
     }
     catch (error) {
         const endTime = Date.now();
         CompositionDebugger.logPerformanceMetrics('Failed Composition', startTime, endTime, {
-            error: error instanceof Error ? error.message : String(error),
+            error: ensureError(error).message,
         });
         if (error instanceof CompositionExecutionError) {
             throw error;
         }
-        throw new CompositionExecutionError(`Composition execution failed: ${error instanceof Error ? error.message : String(error)}`, compositionName, 'context-setup', undefined, error instanceof Error ? error : undefined);
+        throw new CompositionExecutionError(`Composition execution failed: ${ensureError(error).message}`, compositionName, 'context-setup', undefined, ensureError(error));
     }
 }
 /**
- * Create an imperative composition that automatically captures resources
- * and returns status objects using MagicAssignableShape
+ * Create an imperative Kubernetes composition using natural TypeScript.
+ *
+ * Unlike {@link toResourceGraph} which uses separate resource/status builders,
+ * `kubernetesComposition` lets you write a single function that creates resources
+ * inline. Resources are automatically captured via the magic proxy system.
+ * The returned callable composition can be deployed directly or nested inside
+ * other compositions.
  *
- * @param definition - The resource graph definition with schemas
- * @param compositionFn - Synchronous function that takes spec and returns MagicAssignableShape<TStatus>
+ * @typeParam TSpec - The arktype schema for the custom resource's spec
+ * @typeParam TStatus - The arktype schema for the custom resource's status
+ *
+ * @param definition - The RGD metadata: name, apiVersion, kind, spec/status schemas
+ * @param compositionFn - Imperative function receiving the spec, creates resources
+ *   inline, and returns a status shape. Resources created with factory functions
+ *   (e.g., `Deployment()`, `Service()`) are automatically registered.
  * @param options - Optional serialization options
- * @returns TypedResourceGraph directly (not a factory)
+ * @returns A `CallableComposition` that can be deployed or nested inside other compositions
+ *
+ * @example
+ * ```typescript
+ * const webapp = kubernetesComposition(
+ *   {
+ *     name: 'webapp',
+ *     apiVersion: 'apps.example.com/v1alpha1',
+ *     kind: 'WebApp',
+ *     spec: type({ name: 'string', replicas: 'number' }),
+ *     status: type({ ready: 'boolean' }),
+ *   },
+ *   (spec) => {
+ *     const deploy = Deployment({ name: spec.name, replicas: spec.replicas });
+ *     const svc = Service({ name: spec.name });
+ *     return {
+ *       ready: Cel.expr<boolean>(deploy.status.readyReplicas, ' > 0'),
+ *     };
+ *   },
+ * );
+ * ```
  */
 export function kubernetesComposition(definition, compositionFn, options) {
     const compositionName = definition.name || 'unnamed-composition';
@@ -526,7 +538,7 @@ export function kubernetesComposition(definition, compositionFn, options) {
             __compositionId: callCompositionName,
             __resources: callResult.resources,
         };
-    }); // Type assertion to avoid complex typing
+    }); // Double cast needed: function shape doesn't overlap with CallableComposition
     // Create a set to track explicitly deleted properties
     const deletedProperties = new Set();
     // Wrap the callable composition in a Proxy to preserve magic proxy behavior from result