@xplane/core 0.15.2 → 1.0.0

package/dist/index.mjs

@@ -1,540 +1,547 @@
 import { Construct, Construct as Construct$1 } from "constructs";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/core/context.ts
+/**
+* AsyncLocalStorage instance that carries the CompositionContext.
+* The handler sets it before constructing the user's Composition,
+* and the Composition constructor reads from it.
+*/
+const compositionStorage = new AsyncLocalStorage();
+/**
+* Get the current composition context from AsyncLocalStorage.
+* Throws if called outside of a composition construction scope.
+*/
+function getCompositionContext() {
+	const ctx = compositionStorage.getStore();
+	if (ctx) return ctx;
+	throw new Error("No composition context found. Ensure the Composition is constructed within compositionStorage.run().");
+}
+//#endregion
+//#region src/core/composition.ts
+/**
+* Base class for user-authored Crossplane compositions.
+*
+* Users extend this class and define resources in the constructor:
+*
+* ```ts
+* class MyComposition extends Composition<MySpec, MyStatus> {
+*   constructor() {
+*     super();
+*     const vpc = new Vpc(this, 'vpc', { spec: { ... } });
+*     this.xr.status.vpcId = vpc.status.atProvider.vpcId;
+*   }
+* }
+* ```
+*
+* `this.xr` is a "desired-first, fallback-to-observed" proxy over the XR.
+* `this.pipelineContext` provides typed read-only access to Crossplane function context.
+*/
+var Composition = class extends Construct$1 {
+	/**
+	* The XR proxy — reads from desired first (status writes), falls through to observed.
+	* Writing to `this.xr.status.*` sets the composite status output.
+	*/
+	xr;
+	/** The dependency graph tracking resource relationships. */
+	graph;
+	/** The edge collector accumulating dependency edges. */
+	collector;
+	constructor() {
+		super(void 0, "Composition");
+		const ctx = getCompositionContext();
+		this.graph = ctx.graph;
+		this.collector = ctx.collector;
+		this.node.setContext("xplane:graph", ctx.graph);
+		this.node.setContext("xplane:collector", ctx.collector);
+		const xrMeta = ctx.xr.metadata;
+		if (xrMeta) this.node.setContext("xplane:xr-meta", xrMeta);
+		this.xr = createXrProxy(ctx);
+	}
+	/**
+	* Read-only accessor for Crossplane function pipeline context.
+	* Keys are the context keys set by Crossplane or prior functions in the pipeline.
+	*/
+	get pipelineContext() {
+		const ctx = getCompositionContext();
+		return {
+			get(key) {
+				return ctx.pipelineContext.get(key);
+			},
+			has(key) {
+				return ctx.pipelineContext.has(key);
+			},
+			keys() {
+				return ctx.pipelineContext.keys();
+			}
+		};
+	}
+};
+/**
+* Creates the "desired-first, fallback-to-observed" proxy for the XR.
+*
+* - Reading `xr.spec.*` reads from observed XR spec (creates ReadProxy for tracking)
+* - Writing `xr.status.*` writes to a desired-status store (emitted as composite status)
+* - Other reads fall through to observed
+*/
+function createXrProxy(ctx) {
+	const xrObserved = ctx.xr;
+	const xrDesiredStatus = {};
+	ctx.graph.addResource({ id: "__xr__" });
+	const statusProxy = new Proxy(xrDesiredStatus, {
+		get(_target, prop) {
+			if (typeof prop === "symbol") return void 0;
+			const key = String(prop);
+			if (key in xrDesiredStatus) return xrDesiredStatus[key];
+			const observedStatus = xrObserved.status;
+			if (observedStatus && key in observedStatus) return observedStatus[key];
+		},
+		set(_target, prop, value) {
+			if (typeof prop === "symbol") return false;
+			xrDesiredStatus[String(prop)] = value;
+			return true;
+		},
+		has(_target, prop) {
+			if (typeof prop === "symbol") return false;
+			const key = String(prop);
+			if (key in xrDesiredStatus) return true;
+			const observedStatus = xrObserved.status;
+			return observedStatus ? key in observedStatus : false;
+		}
+	});
+	return new Proxy({}, {
+		get(_target, prop) {
+			if (typeof prop === "symbol") return void 0;
+			const key = String(prop);
+			if (key === "status") return statusProxy;
+			if (key in xrObserved) return xrObserved[key];
+		},
+		set(_target, prop, value) {
+			if (typeof prop === "symbol") return false;
+			const key = String(prop);
+			if (key === "status") {
+				Object.assign(xrDesiredStatus, value);
+				return true;
+			}
+			xrObserved[key] = value;
+			return true;
+		},
+		has(_target, prop) {
+			if (typeof prop === "symbol") return false;
+			return String(prop) in xrObserved || String(prop) === "status";
+		}
+	});
+}
+/**
+* Extract the desired XR status from a Composition instance.
+* Used by the emit pipeline phase to produce composite status output.
+*/
+function getXrDesiredStatus(composition) {
+	const statusProxy = composition.xr.status;
+	const result = {};
+	if (statusProxy && typeof statusProxy === "object") for (const key of Object.keys(statusProxy)) {
+		const value = statusProxy[key];
+		if (value != null) result[key] = value;
+	}
+	return result;
+}
+//#endregion
 //#region src/tracking/dependency-graph.ts
 /**
-* Directed acyclic graph of resource dependencies.
-* Supports topological sorting to determine resource creation order
-* and cycle detection to surface configuration errors.
+* Tracks dependency relationships between resources as a directed acyclic graph.
+* Edges are added as resources reference each other's observed state.
 */
 var DependencyGraph = class {
-	/** adjacency list: resource id → set of resource ids it depends on */
-	_deps = /* @__PURE__ */ new Map();
-	/** all registered resource refs by id */
+	_adjacency = /* @__PURE__ */ new Map();
 	_resources = /* @__PURE__ */ new Map();
-	/** raw edges for introspection */
 	_edges = [];
-	/** Register a resource node in the graph. */
 	addResource(ref) {
 		this._resources.set(ref.id, ref);
-		if (!this._deps.has(ref.id)) this._deps.set(ref.id, /* @__PURE__ */ new Set());
+		if (!this._adjacency.has(ref.id)) this._adjacency.set(ref.id, /* @__PURE__ */ new Set());
+	}
+	addEdge(edge) {
+		this.addResource(edge.from);
+		this.addResource(edge.to);
+		this._adjacency.get(edge.to.id).add(edge.from.id);
+		this._edges.push(edge);
 	}
-	/** Add dependency edges from the collector. */
 	addEdges(edges) {
-		for (const edge of edges) {
-			this.addResource(edge.from);
-			this.addResource(edge.to);
-			const deps = this._deps.get(edge.to.id);
-			if (deps) deps.add(edge.from.id);
-			this._edges.push(edge);
-		}
+		for (const edge of edges) this.addEdge(edge);
 	}
-	/** Add an explicit dependency: `dependent` depends on `dependency`. */
 	addExplicitDependency(dependent, dependency) {
 		this.addResource(dependent);
 		this.addResource(dependency);
-		const deps = this._deps.get(dependent.id);
-		if (deps) deps.add(dependency.id);
+		this._adjacency.get(dependent.id).add(dependency.id);
 	}
-	/** Get all resource IDs that `resourceId` directly depends on. */
+	/** Get the set of resource IDs that `resourceId` depends on. */
 	getDependencies(resourceId) {
-		return this._deps.get(resourceId) ?? /* @__PURE__ */ new Set();
+		return this._adjacency.get(resourceId) ?? /* @__PURE__ */ new Set();
 	}
-	/** Get all registered resource IDs. */
 	get resourceIds() {
 		return [...this._resources.keys()];
 	}
-	/** Get all raw edges. */
 	get edges() {
 		return this._edges;
 	}
 	/**
-	* Returns resource IDs in topological order (dependencies first).
-	* Throws if the graph contains cycles.
+	* Returns a topological ordering of resources.
+	* If a cycle is detected, returns { order: null, cycle: string[] }.
 	*/
 	topologicalSort() {
 		const visited = /* @__PURE__ */ new Set();
 		const visiting = /* @__PURE__ */ new Set();
 		const sorted = [];
 		const visit = (id) => {
-			if (visited.has(id)) return;
-			if (visiting.has(id)) {
-				const cycle = [...visiting, id].join(" → ");
-				throw new Error(`Dependency cycle detected: ${cycle}`);
-			}
+			if (visited.has(id)) return null;
+			if (visiting.has(id)) return [...visiting, id];
 			visiting.add(id);
-			const deps = this._deps.get(id);
-			if (deps) for (const depId of deps) visit(depId);
+			const deps = this._adjacency.get(id);
+			if (deps) for (const depId of deps) {
+				const cycle = visit(depId);
+				if (cycle) return cycle;
+			}
 			visiting.delete(id);
 			visited.add(id);
 			sorted.push(id);
+			return null;
 		};
-		for (const id of this._resources.keys()) visit(id);
-		return sorted;
+		for (const id of this._resources.keys()) {
+			const cycle = visit(id);
+			if (cycle) {
+				const start = cycle[cycle.length - 1];
+				const startIdx = cycle.indexOf(start);
+				return {
+					order: null,
+					cycle: cycle.slice(startIdx)
+				};
+			}
+		}
+		return { order: sorted };
 	}
 };
 //#endregion
+//#region src/tracking/read-proxy.ts
+/**
+* WeakMap storing metadata for ReadProxy instances.
+* This avoids polluting proxy objects with symbols.
+*/
+const proxyMeta = /* @__PURE__ */ new WeakMap();
+/** Sentinel symbol to identify ReadProxy instances. */
+const READ_PROXY_TAG = Symbol.for("xplane.readProxy");
+/**
+* Check if a value is a ReadProxy.
+*/
+function isReadProxy(value) {
+	return typeof value === "object" && value !== null && value[READ_PROXY_TAG] === true;
+}
+/**
+* Get the metadata for a ReadProxy value.
+*/
+function getReadProxyMeta(value) {
+	if (!isReadProxy(value)) return void 0;
+	return proxyMeta.get(value);
+}
+/**
+* Creates a ReadProxy that wraps observed data.
+*
+* - Property access navigates into the data, building up the path.
+* - Missing paths return `undefined` (no placeholder proxies).
+* - The proxy carries owner + path metadata so that when it's assigned
+*   to a WriteProxy, the dependency edge can be recorded.
+*/
+function createReadProxy(target, owner, basePath) {
+	const proxy = new Proxy(target, {
+		get(obj, prop, receiver) {
+			if (prop === READ_PROXY_TAG) return true;
+			if (typeof prop === "symbol") return Reflect.get(obj, prop, receiver);
+			if (prop === "toJSON") return () => obj;
+			const childPath = basePath ? `${basePath}.${String(prop)}` : String(prop);
+			const value = Reflect.get(obj, prop, receiver);
+			if (value === void 0 || value === null) return createLeafReadProxy(owner, childPath);
+			if (typeof value === "object") return createReadProxy(value, owner, childPath);
+			return createPrimitiveReadProxy(value, owner, childPath);
+		},
+		has(obj, prop) {
+			if (prop === READ_PROXY_TAG) return true;
+			return Reflect.has(obj, prop);
+		}
+	});
+	proxyMeta.set(proxy, {
+		owner,
+		path: basePath
+	});
+	return proxy;
+}
+/**
+* A "leaf" ReadProxy for paths that don't exist in observed data yet.
+* Carries metadata for edge creation. Resolves to `undefined` when
+* coerced to a primitive.
+*/
+function createLeafReadProxy(owner, path) {
+	const proxy = new Proxy(Object.create(null), {
+		get(_obj, prop) {
+			if (prop === READ_PROXY_TAG) return true;
+			if (prop === Symbol.toPrimitive) return () => `__pending__${owner.id}__${path}`;
+			if (typeof prop === "symbol") return void 0;
+			if (prop === "toJSON") return () => void 0;
+			if (prop === "toString") return () => `__pending__${owner.id}__${path}`;
+			if (prop === "valueOf") return () => proxy;
+			return createLeafReadProxy(owner, `${path}.${String(prop)}`);
+		},
+		has(_obj, prop) {
+			if (prop === READ_PROXY_TAG) return true;
+			return false;
+		}
+	});
+	proxyMeta.set(proxy, {
+		owner,
+		path
+	});
+	return proxy;
+}
+/**
+* Wraps a concrete primitive value so it carries ReadProxy metadata.
+* This allows the WriteProxy to detect it during assignment and
+* record the dependency edge, while the value itself resolves correctly.
+*/
+function createPrimitiveReadProxy(value, owner, path) {
+	const proxy = new Proxy(Object.create(null), {
+		get(_obj, prop) {
+			if (prop === READ_PROXY_TAG) return true;
+			if (prop === Symbol.toPrimitive) return () => value;
+			if (prop === "valueOf") return () => value;
+			if (prop === "toString") return () => String(value);
+			if (prop === "toJSON") return () => value;
+			if (typeof prop === "symbol") return void 0;
+			return createLeafReadProxy(owner, `${path}.${String(prop)}`);
+		},
+		has(_obj, prop) {
+			if (prop === READ_PROXY_TAG) return true;
+			return false;
+		}
+	});
+	proxyMeta.set(proxy, {
+		owner,
+		path
+	});
+	return proxy;
+}
+//#endregion
 //#region src/tracking/types.ts
 /**
-* Symbols used to access tracking metadata on proxy-wrapped values.
-* These are not enumerable and won't leak into serialized output.
+* A Pending marker stored in a desired document when a ReadProxy value
+* is assigned. Carries full source info so the resolve phase knows
+* where to look for the concrete value.
 */
-const TRACKING_META = Symbol.for("xplane.tracking.meta");
-const IS_TRACKED = Symbol.for("xplane.tracking.isTracked");
+const PENDING_TAG = Symbol.for("xplane.pending");
+var Pending = class {
+	source;
+	path;
+	static TAG = PENDING_TAG;
+	[PENDING_TAG] = true;
+	constructor(source, path) {
+		this.source = source;
+		this.path = path;
+	}
+	static is(value) {
+		return typeof value === "object" && value !== null && value[PENDING_TAG] === true;
+	}
+};
 //#endregion
-//#region src/tracking/proxy.ts
+//#region src/tracking/write-proxy.ts
 /**
-* Registry that collects dependency edges discovered during proxy access.
-* Shared across all tracked values within a single composition run.
+* Collector that accumulates dependency edges discovered during
+* WriteProxy assignments.
 */
-var DependencyCollector = class {
+var EdgeCollector = class {
 	_edges = [];
-	addEdge(edge) {
+	add(edge) {
 		if (!this._edges.some((e) => e.from.id === edge.from.id && e.fromPath === edge.fromPath && e.to.id === edge.to.id && e.toPath === edge.toPath)) this._edges.push(edge);
 	}
 	get edges() {
 		return this._edges;
 	}
-	clear() {
-		this._edges.length = 0;
-	}
 };
 /**
-* Returns true if `value` is a tracked proxy created by `createTrackedProxy`.
-*/
-function isTracked(value) {
-	return typeof value === "object" && value !== null && value[IS_TRACKED] === true;
-}
-/**
-* Retrieves the tracking metadata from a tracked proxy.
-* Returns undefined if the value is not tracked.
-*/
-function getTrackingMeta(value) {
-	if (isTracked(value)) return value[TRACKING_META];
-}
-/**
-* Creates a proxy around `target` that:
-* 1. Returns nested proxies for property access (building up dot-paths).
-* 2. On set: if the assigned value is itself a tracked proxy from a *different*
-*    resource, records a DependencyEdge in the collector.
-* 3. Stores concrete values normally so the underlying object is populated.
+* Creates a WriteProxy that wraps a desired document.
 *
-* For "observed" proxies, property reads on missing keys return a nested
-* tracked proxy (representing an "unknown" value) rather than undefined.
-* This lets `vpc.status.atProvider.vpcId` work even before the VPC exists.
-*/
-function createTrackedProxy(target, opts) {
-	const meta = {
-		owner: opts.owner,
-		path: opts.path,
-		observed: opts.observed
-	};
+* - Writes store values in the target.
+* - When a ReadProxy value is assigned, it records a dependency edge
+*   and stores a Pending marker if the value is not yet concrete.
+* - Reads return the stored value (desired-first).
+*/
+function createWriteProxy(target, opts) {
+	const { owner, collector, basePath = "" } = opts;
 	return new Proxy(target, {
 		get(obj, prop, receiver) {
-			if (prop === TRACKING_META) return meta;
-			if (prop === IS_TRACKED) return true;
-			if (prop === Symbol.toPrimitive) {
-				if (opts.observed && Object.keys(obj).length === 0) return () => {
-					throw new Error(`Cannot coerce XR path '${opts.path}' to a primitive — the field does not exist in the composite resource`);
-				};
-				return Reflect.get(obj, prop, receiver);
-			}
 			if (typeof prop === "symbol") return Reflect.get(obj, prop, receiver);
 			if (prop === "toJSON") return () => obj;
-			const existing = Reflect.get(obj, prop, receiver);
-			if (isTracked(existing)) return existing;
-			if (typeof existing === "object" && existing !== null) {
-				const wrapped = createTrackedProxy(existing, {
-					owner: opts.owner,
-					path: opts.path ? `${opts.path}.${prop}` : String(prop),
-					observed: opts.observed,
-					collector: opts.collector,
-					strict: opts.strict
-				});
-				Reflect.set(obj, prop, wrapped);
-				return wrapped;
-			}
-			if (existing !== void 0 || prop in obj) return existing;
-			if (opts.observed) {
-				if (opts.strict) return;
-				return createTrackedProxy({}, {
-					owner: opts.owner,
-					path: opts.path ? `${opts.path}.${prop}` : String(prop),
-					observed: true,
-					collector: opts.collector
-				});
-			}
-			const wrapped = createTrackedProxy({}, {
-				owner: opts.owner,
-				path: opts.path ? `${opts.path}.${prop}` : String(prop),
-				observed: false,
-				collector: opts.collector
+			const value = Reflect.get(obj, prop, receiver);
+			if (typeof value === "object" && value !== null && !Pending.is(value)) return createWriteProxy(value, {
+				owner,
+				collector,
+				basePath: basePath ? `${basePath}.${String(prop)}` : String(prop)
 			});
-			Reflect.set(obj, prop, wrapped);
-			return wrapped;
+			return value;
 		},
 		set(obj, prop, value) {
 			if (typeof prop === "symbol") return Reflect.set(obj, prop, value);
-			const targetPath = opts.path ? `${opts.path}.${prop}` : String(prop);
-			if (isTracked(value)) {
-				const sourceMeta = getTrackingMeta(value);
-				if (sourceMeta && sourceMeta.owner.id === "__xr__") {
-					const concrete = resolveTrackedValue(value);
-					return Reflect.set(obj, prop, concrete === UNRESOLVED ? void 0 : concrete);
+			const targetPath = basePath ? `${basePath}.${String(prop)}` : String(prop);
+			if (isReadProxy(value)) {
+				const meta = getReadProxyMeta(value);
+				if (meta && meta.owner.id !== owner.id) {
+					collector.add({
+						from: meta.owner,
+						fromPath: meta.path,
+						to: owner,
+						toPath: targetPath
+					});
+					const primitive = tryExtractPrimitive$2(value);
+					if (primitive !== void 0) return Reflect.set(obj, prop, primitive);
+					return Reflect.set(obj, prop, new Pending(meta.owner, meta.path));
+				}
+				const primitive = tryExtractPrimitive$2(value);
+				if (primitive !== void 0) return Reflect.set(obj, prop, primitive);
+				if (meta) {
+					collector.add({
+						from: meta.owner,
+						fromPath: meta.path,
+						to: owner,
+						toPath: targetPath
+					});
+					return Reflect.set(obj, prop, new Pending(meta.owner, meta.path));
 				}
-				if (sourceMeta && sourceMeta.owner.id !== opts.owner.id) opts.collector.addEdge({
-					from: sourceMeta.owner,
-					fromPath: sourceMeta.path,
-					to: opts.owner,
-					toPath: targetPath
-				});
-				const concrete = resolveTrackedValue(value);
-				return Reflect.set(obj, prop, concrete);
 			}
-			if (typeof value === "object" && value !== null && !isTracked(value)) {
-				const wrapped = createTrackedProxy(value, {
-					owner: opts.owner,
-					path: targetPath,
-					observed: opts.observed,
-					collector: opts.collector
-				});
-				return Reflect.set(obj, prop, wrapped);
+			if (typeof value === "object" && value !== null && !Pending.is(value)) {
+				const processed = deepProcessValue(value, owner, targetPath, collector);
+				return Reflect.set(obj, prop, processed);
 			}
 			return Reflect.set(obj, prop, value);
 		},
-		ownKeys(obj) {
-			return Reflect.ownKeys(obj).filter((k) => typeof k === "string");
-		},
-		getOwnPropertyDescriptor(obj, prop) {
-			const desc = Reflect.getOwnPropertyDescriptor(obj, prop);
-			if (desc) return {
-				...desc,
-				configurable: true,
-				enumerable: true
-			};
-			if (opts.observed && typeof prop === "string") return {
-				configurable: true,
-				enumerable: true,
-				writable: true,
-				value: void 0
-			};
-		},
-		has(obj, prop) {
-			if (prop === IS_TRACKED || prop === TRACKING_META) return true;
-			return Reflect.has(obj, prop);
+		deleteProperty(obj, prop) {
+			return Reflect.deleteProperty(obj, prop);
 		}
 	});
 }
 /**
-* Sentinel value used when a tracked reference cannot be resolved yet
-* (the source resource hasn't been observed).
+* Try to extract a primitive value from a ReadProxy via Symbol.toPrimitive.
+* Returns `undefined` if the proxy represents a non-existent (leaf) value.
 */
-const UNRESOLVED = Symbol.for("xplane.unresolved");
-/**
-* Attempts to extract a concrete (non-proxy) value from a tracked value.
-* Returns UNRESOLVED if the tracked value points to an empty observed path.
-*/
-function resolveTrackedValue(tracked) {
-	if (!isTracked(tracked)) return tracked;
-	const obj = unwrapProxy(tracked);
-	const keys = Object.keys(obj);
-	const meta = getTrackingMeta(tracked);
-	if (keys.length === 0 && meta?.observed) return UNRESOLVED;
-	return obj;
-}
-/**
-* Strips the proxy layer and returns the raw underlying object.
-*/
-function unwrapProxy(tracked) {
-	const result = {};
-	for (const key of Object.keys(tracked)) result[key] = tracked[key];
-	return result;
+function tryExtractPrimitive$2(proxy) {
+	const toPrim = proxy[Symbol.toPrimitive];
+	if (typeof toPrim === "function") {
+		const result = toPrim();
+		if (result !== void 0 && result !== null && typeof result !== "object") {
+			if (typeof result === "string" && result.startsWith("__pending__")) return void 0;
+			return result;
+		}
+	}
 }
-//#endregion
-//#region src/core/construct.ts
-/**
-* Context keys used to propagate tracking infrastructure through the construct tree.
-* Set by Composition (root), read by Resource and other constructs.
-* @internal
-*/
-const CONTEXT_COLLECTOR = "xplane:collector";
-const CONTEXT_GRAPH = "xplane:graph";
-/** Raw XR name and namespace stored at composition root for use by uniqueName. */
-const CONTEXT_XR_META = "xplane:xr-meta";
-/** Registry of existing resource references on the composition root. */
-const CONTEXT_EXISTING = "xplane:existing";
-//#endregion
-//#region src/core/composition.ts
 /**
-* A Composition is the root Construct for a Crossplane composition function.
-* Like CDK's `App` or cdk8s's `Chart`, it is the root of the construct tree.
-* Resources and constructs are created in the constructor.
-*
-* Usage:
-* ```ts
-* class MyComposition extends Composition {
-*   constructor() {
-*     super();
-*     const vpc = new aws.ec2.VPC(this, 'vpc', { ... });
-*     const subnet = new aws.ec2.Subnet(this, 'subnet', {
-*       spec: { forProvider: { vpcId: vpc.status.atProvider.vpcId } }
-*     });
-*   }
-* }
-* ```
+* Deep-process a plain object/array being assigned to a WriteProxy.
+* Replaces any nested ReadProxy values with Pending markers or concrete values.
 */
-var Composition = class Composition extends Construct$1 {
-	/**
-	* Pending XR data, set by the framework before instantiation.
-	* @internal
-	*/
-	static _pendingXR;
-	/**
-	* Pending environment data, set by the framework before instantiation.
-	* Populated from the Crossplane context key `apiextensions.crossplane.io/environment`.
-	* @internal
-	*/
-	static _pendingEnvironment;
-	/** The composite resource (XR) — proxy-wrapped for tracking. */
-	xr;
-	/** Environment data from function-environment-configs or other pipeline steps. */
-	environment;
-	/** Raw name from the XR metadata (not proxy-tracked). */
-	xrName;
-	/** Raw namespace from the XR metadata (not proxy-tracked). */
-	xrNamespace;
-	/** Dependency collector shared across all resources. */
-	collector;
-	/** Dependency graph built during compose(). */
-	graph;
-	/** Registry of existing (read-only) resource references keyed by refKey. */
-	_existingResources = /* @__PURE__ */ new Map();
-	/** Registered status output function. @internal */
-	_statusFn;
-	constructor() {
-		super(void 0, "");
-		this.collector = new DependencyCollector();
-		this.graph = new DependencyGraph();
-		this.node.setContext(CONTEXT_COLLECTOR, this.collector);
-		this.node.setContext(CONTEXT_GRAPH, this.graph);
-		this.node.setContext(CONTEXT_EXISTING, this._existingResources);
-		const xrData = Composition._pendingXR ?? {};
-		Composition._pendingXR = void 0;
-		const envData = Composition._pendingEnvironment ?? {};
-		Composition._pendingEnvironment = void 0;
-		const xrMeta = xrData.metadata ?? {};
-		this.xrName = typeof xrMeta.name === "string" ? xrMeta.name : void 0;
-		this.xrNamespace = typeof xrMeta.namespace === "string" ? xrMeta.namespace : void 0;
-		this.node.setContext(CONTEXT_XR_META, {
-			name: this.xrName,
-			namespace: this.xrNamespace
+function deepProcessValue(value, owner, basePath, collector) {
+	if (value === null || value === void 0) return value;
+	if (typeof value !== "object") return value;
+	if (isReadProxy(value)) {
+		const meta = getReadProxyMeta(value);
+		collector.add({
+			from: meta.owner,
+			fromPath: meta.path,
+			to: owner,
+			toPath: basePath
 		});
-		this.xr = createTrackedProxy(xrData, {
-			owner: { id: "__xr__" },
-			path: "",
-			observed: true,
-			collector: this.collector,
-			strict: true
-		});
-		this.environment = envData;
-	}
-	/**
-	* Register a function that computes the desired XR status output.
-	*
-	* The function is called by the framework **after** observed state has been
-	* fed into all resources, so `resource.observed` contains real data.
-	*
-	* @example
-	* ```ts
-	* this.setStatusOutput(() => ({
-	*   config: {
-	*     projectHostedZoneId: hostedZone.observed?.status?.atProvider?.id,
-	*   },
-	* }));
-	* ```
-	*/
-	setStatusOutput(fn) {
-		this._statusFn = fn;
-	}
-	/**
-	* Compute and return the desired status output.
-	* Returns an empty object if no status function was registered.
-	* @internal
-	*/
-	computeStatusOutput() {
-		return this._statusFn?.() ?? {};
-	}
-	/**
-	* Walk up the construct tree and return the root Composition.
-	* Throws if the scope is not within a Composition.
-	*/
-	static of(scope) {
-		let current = scope;
-		while (current !== void 0) {
-			if (current instanceof Composition) return current;
-			current = current.node.scope;
-		}
-		throw new Error("No Composition found in the scope chain. Ensure constructs are created within a Composition.");
+		const primitive = tryExtractPrimitive$2(value);
+		if (primitive !== void 0) return primitive;
+		return new Pending(meta.owner, meta.path);
 	}
-	/** Get all composed (non-existing) resources keyed by construct path. */
-	get resources() {
-		const map = /* @__PURE__ */ new Map();
-		for (const construct of this.node.findAll()) if (isResource(construct) && !construct.isExisting) map.set(construct.node.path, construct);
-		return map;
-	}
-	/** Get all existing (read-only) resource references keyed by refKey. */
-	get existingResources() {
-		return this._existingResources;
-	}
-};
-/**
-* Type guard for Resource — avoids circular import by checking for
-* characteristic properties rather than instanceof.
-*/
-function isResource(construct) {
-	return construct !== null && typeof construct === "object" && "apiVersion" in construct && "kind" in construct && "resourceRef" in construct && "isExisting" in construct;
+	if (Array.isArray(value)) return value.map((item, i) => deepProcessValue(item, owner, `${basePath}[${i}]`, collector));
+	const result = {};
+	for (const [key, val] of Object.entries(value)) result[key] = deepProcessValue(val, owner, `${basePath}.${key}`, collector);
+	return result;
 }
 //#endregion
 //#region src/core/resource.ts
+const internals = /* @__PURE__ */ new WeakMap();
 /**
-* A Construct that represents a single Crossplane managed/composed resource.
+* A Kubernetes resource within a Composition.
+*
+* The Resource instance acts as a "desired-first, fallback-to-observed" proxy:
+* - Reading a path that exists in the desired document returns the desired value.
+* - Reading a path that does NOT exist in desired falls through to a tracked
+*   ReadProxy over observed state (creates dependency edges).
+* - Writing always goes to the desired document.
 *
-* The `spec` and `status` properties are proxy-wrapped for automatic
-* dependency tracking. Assigning a value from another resource's status
-* to this resource's spec automatically records a dependency edge.
+* The only reserved properties are `node` (from Construct) and `resource`
+* (framework config namespace).
 */
 var Resource = class Resource extends Construct$1 {
-	apiVersion;
-	kind;
-	resourceRef;
-	/** Proxy-wrapped desired spec — writes are tracked. */
-	spec;
-	/** Proxy-wrapped observed status — reads create dependency tracking. */
-	status;
-	/** Proxy-wrapped desired metadata. */
-	metadata;
-	/**
-	* Observed-mode tracked proxy over the entire resource document.
-	* Use this to access arbitrary top-level fields on existing resources
-	* (e.g., `secret.root.data.myKey` for a Secret, `configMap.root.data.key` for a ConfigMap).
-	*/
-	root;
-	/** Whether auto-ready is enabled for this resource. */
-	autoReady;
-	/** Whether this is a read-only reference to an existing cluster resource. */
-	isExisting;
-	/** If this is an existing resource, holds the reference metadata for the handler. */
-	existingRef;
-	/** Extra top-level fields (e.g. data/stringData for Secret). Not proxy-tracked. */
-	_extra;
-	/** Observed state populated by the bridge before construction. */
-	_observed;
-	/** Backing object for the status proxy — populated by setObserved(). */
-	_statusTarget;
-	/** Backing object for the spec proxy (existing resources only) — populated by setObservedFull(). */
-	_specTarget;
-	/** Backing object for the root proxy — populated by setObservedFull(). */
-	_rootTarget;
-	/** Backing object for the metadata proxy — populated by setObserved(). */
-	_metaTarget;
-	/** Keys the user explicitly declared in constructor metadata props. */
-	_desiredMetaKeys;
-	/** Explicit dependency refs. */
-	_explicitDeps = [];
-	/** @internal */
-	_graph;
-	constructor(scope, id, props, options) {
+	resource;
+	constructor(scope, id, props) {
 		super(scope, id);
-		this.apiVersion = props.apiVersion;
-		this.kind = props.kind;
-		this.autoReady = options?.autoReady ?? true;
-		this.isExisting = false;
-		this.existingRef = void 0;
-		const collector = this.node.tryGetContext(CONTEXT_COLLECTOR);
-		const graph = this.node.tryGetContext(CONTEXT_GRAPH);
-		if (!collector || !graph) throw new Error("Resource must be created within a Composition tree");
-		this.resourceRef = { id: this.node.path };
-		graph.addResource(this.resourceRef);
-		const KNOWN_KEYS = new Set([
-			"apiVersion",
-			"kind",
-			"metadata",
-			"spec"
-		]);
-		this._extra = {};
-		for (const [k, v] of Object.entries(props)) if (!KNOWN_KEYS.has(k)) this._extra[k] = v;
-		const specTarget = deepCloneWithTracked(props.spec ?? {});
-		resolveTrackedRefs(specTarget, this.resourceRef, "spec", collector);
-		this.spec = createTrackedProxy(specTarget, {
-			owner: this.resourceRef,
-			path: "spec",
-			observed: false,
-			collector
-		});
-		this._metaTarget = props.metadata ?? {};
-		this._desiredMetaKeys = new Set(Object.keys(this._metaTarget));
-		this.metadata = createTrackedProxy(this._metaTarget, {
-			owner: this.resourceRef,
-			path: "metadata",
-			observed: true,
-			collector
-		});
-		this._statusTarget = {};
-		this.status = createTrackedProxy(this._statusTarget, {
-			owner: this.resourceRef,
-			path: "status",
-			observed: true,
-			collector
-		});
-		this._rootTarget = {};
-		this.root = createTrackedProxy(this._rootTarget, {
-			owner: this.resourceRef,
-			path: "",
-			observed: true,
+		const graph = scope.node.tryGetContext("xplane:graph");
+		const collector = scope.node.tryGetContext("xplane:collector");
+		if (!graph || !collector) throw new Error("Resource must be created within a Composition tree.");
+		const ref = { id: this.node.path };
+		graph.addResource(ref);
+		const readyChecks = [];
+		const config = {
+			autoReady: true,
+			addReadyCheck(fn, priority = 50) {
+				readyChecks.push({
+					fn,
+					priority
+				});
+			}
+		};
+		this.resource = config;
+		const internal = {
+			ref,
+			desired: processDesiredProps(props, ref, collector),
+			observed: {},
+			external: false,
+			config,
+			readyChecks,
+			graph,
 			collector
-		});
-		this._specTarget = void 0;
-		this._graph = graph;
-	}
-	/** Fully qualified path in the construct tree. */
-	get path() {
-		return this.node.path;
-	}
-	/** Add an explicit dependency on another resource. */
-	addDependency(other) {
-		this._explicitDeps.push(other.resourceRef);
-		this._graph.addExplicitDependency(this.resourceRef, other.resourceRef);
-	}
-	/** Get explicit dependency refs. */
-	get explicitDependencies() {
-		return this._explicitDeps;
-	}
-	/** Set observed state (called by the bridge before compose). */
-	setObserved(observed) {
-		this._observed = observed;
-		for (const key of Object.keys(this._metaTarget)) this._desiredMetaKeys.add(key);
-		if (observed.metadata && typeof observed.metadata === "object") Object.assign(this._metaTarget, observed.metadata);
-		if (observed.status && typeof observed.status === "object") Object.assign(this._statusTarget, observed.status);
-	}
-	/** Get observed state. */
-	get observed() {
-		return this._observed;
+		};
+		internals.set(this, internal);
+		return createResourceProxy(this, internal);
 	}
 	/**
-	* Compute a unique name for a resource based on its construct node path,
-	* similar to `cdk.Names.uniqueResourceName`.
-	*
-	* The name is structured as:
-	*   `[namespace-]claimName-PathSegments[-extra]-hash8`
+	* Look up an existing cluster resource by name.
+	* Returns a Resource that only has observed state (no desired output).
 	*
-	* - XR namespace (if present) and XR name are always prepended.
-	* - Path segments (construct tree, root skipped) are appended next.
-	* - An optional `extra` string is appended after the path.
-	* - An 8-char hash of the full untruncated string is always appended for uniqueness.
-	* - Whitespace in each segment is stripped (CDK convention).
-	* - Disallowed characters are replaced by the separator; consecutive separators are collapsed.
-	* - The result is truncated to `maxLength` while keeping the hash suffix.
-	*
-	* @param scope    - The construct whose node path is used.
-	* @param options  - Optional tuning.
+	* The `name` parameter accepts either a plain string or a PrimitiveReadProxy
+	* (returned when reading a tracked property like `ns.metadata.labels['x']`).
+	* Proxies are coerced to their underlying string via `Symbol.toPrimitive`.
+	*/
+	static fromExistingByName(scope, apiVersion, kind, name, namespace) {
+		const resolvedName = coerceToString(name);
+		const refKey = computeRefKey(apiVersion, kind, resolvedName, namespace);
+		const instance = new Resource(scope, `__existing__${refKey.replace(/\//g, "_")}`, {
+			apiVersion,
+			kind
+		});
+		const internal = internals.get(instance);
+		internal.external = true;
+		internal.externalRef = {
+			apiVersion,
+			kind,
+			name: resolvedName ?? name,
+			namespace,
+			refKey
+		};
+		const ctx = compositionStorage.getStore();
+		if (ctx) {
+			const observed = ctx.requiredResources.get(refKey);
+			if (observed) Object.assign(internal.observed, observed);
+		}
+		return instance;
+	}
+	/**
+	* Generate a deterministic unique name based on the XR identity and construct path.
+	* Useful for resource fields that need unique names (e.g., AWS resource names).
 	*/
 	static uniqueName(scope, options = {}) {
 		const maxLength = options.maxLength ?? 63;
@@ -543,12 +550,10 @@ var Resource = class Resource extends Construct$1 {
 		const escapedSep = separator.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 		const collapseRe = new RegExp(`${escapedSep}+`, "g");
 		const clean = (s) => s.replace(/\s+/g, "").replace(allowedPattern, separator).replace(collapseRe, separator).replace(new RegExp(`^${escapedSep}|${escapedSep}$`, "g"), "");
-		const xrMeta = scope.node.tryGetContext(CONTEXT_XR_META);
-		const xrName = xrMeta?.name;
-		const xrNamespace = xrMeta?.namespace;
+		const xrMeta = scope.node.tryGetContext("xplane:xr-meta");
 		const parts = [];
-		if (xrNamespace) parts.push(clean(xrNamespace));
-		if (xrName) parts.push(clean(xrName));
+		if (xrMeta?.namespace) parts.push(clean(xrMeta.namespace));
+		if (xrMeta?.name) parts.push(clean(xrMeta.name));
 		for (const s of scope.node.scopes.slice(1)) {
 			const c = clean(s.node.id);
 			if (c) parts.push(c);
@@ -563,91 +568,48 @@ var Resource = class Resource extends Construct$1 {
 		if (withHash.length <= maxLength) return withHash;
 		return `${full.slice(0, maxLength - hash.length - separator.length)}${separator}${hash}`;
 	}
-	/**
-	* Serialize to a plain Kubernetes resource object for the desired state.
-	* Strips proxy wrappers, UNRESOLVED sentinels, and server-managed metadata
-	* fields (uid, resourceVersion, etc.) that must not appear in desired state.
-	*/
-	toDesired() {
-		const fullMeta = JSON.parse(JSON.stringify(this.metadata));
-		const desiredMeta = {};
-		for (const key of this._desiredMetaKeys) if (key in fullMeta) desiredMeta[key] = fullMeta[key];
-		const cleanMeta = stripUnresolved(desiredMeta);
-		const desired = {
-			...this._extra,
-			apiVersion: this.apiVersion,
-			kind: this.kind,
-			metadata: cleanMeta,
-			spec: stripUnresolved(JSON.parse(JSON.stringify(this.spec)))
-		};
-		if (desired.spec && typeof desired.spec === "object" && Object.keys(desired.spec).length === 0) delete desired.spec;
-		return desired;
-	}
-	/**
-	* Populate the full observed state for an existing resource.
-	* Feeds data into `root`, `status`, `spec`, and `metadata` backing targets
-	* so that proxy reads resolve to real values.
-	*/
-	setObservedFull(resource) {
-		this._observed = resource;
-		for (const [key, value] of Object.entries(resource)) if (value !== null && value !== void 0) this._rootTarget[key] = value;
-		if (resource.status && typeof resource.status === "object") Object.assign(this._statusTarget, resource.status);
-		if (this._specTarget && resource.spec && typeof resource.spec === "object") Object.assign(this._specTarget, resource.spec);
-		if (resource.metadata && typeof resource.metadata === "object") Object.assign(this._metaTarget, resource.metadata);
-	}
-	/**
-	* Create a read-only reference to an existing cluster resource.
-	* The resource will be fetched by Crossplane via the Required Resources mechanism.
-	* Its `status`, `spec`, and `root` proxies can be read to create dependency edges.
-	*
-	* @param scope - Parent construct (typically `this` inside a Composition constructor)
-	* @param apiVersion - API version of the resource (e.g. "example.io/v1")
-	* @param kind - Kind of the resource (e.g. "Project")
-	* @param name - Name of the resource (can be a literal string or a tracked proxy value)
-	* @param namespace - Optional namespace of the resource
-	*/
-	static fromExistingByName(scope, apiVersion, kind, name, namespace) {
-		const refKey = computeRefKey(apiVersion, kind, typeof name === "string" ? name : void 0, namespace);
-		const resource = new Resource(scope, `__existing__${refKey.replace(/\//g, "_")}`, {
-			apiVersion,
-			kind,
-			spec: {}
-		});
-		resource.isExisting = true;
-		resource.existingRef = {
-			apiVersion,
-			kind,
-			name,
-			namespace,
-			refKey
-		};
-		const collector = resource.node.tryGetContext(CONTEXT_COLLECTOR);
-		const specTarget = {};
-		resource._specTarget = specTarget;
-		resource.spec = createTrackedProxy(specTarget, {
-			owner: resource.resourceRef,
-			path: "spec",
-			observed: true,
-			collector
-		});
-		const existingMap = resource.node.tryGetContext(CONTEXT_EXISTING);
-		if (existingMap) existingMap.set(refKey, resource);
-		return resource;
-	}
 };
+function getResourceInternals(resource) {
+	const internal = internals.get(resource);
+	if (!internal) throw new Error("Resource internals not found");
+	return internal;
+}
+function getResourceRef(resource) {
+	return getResourceInternals(resource).ref;
+}
+function getDesiredDocument(resource) {
+	return getResourceInternals(resource).desired;
+}
+function getObservedDocument(resource) {
+	return getResourceInternals(resource).observed;
+}
+function hydrateObserved(resource, data) {
+	const internal = getResourceInternals(resource);
+	Object.assign(internal.observed, data);
+}
+function isExternal(resource) {
+	return getResourceInternals(resource).external;
+}
+function getExternalRef(resource) {
+	return getResourceInternals(resource).externalRef;
+}
+function getReadyChecks(resource) {
+	return getResourceInternals(resource).readyChecks;
+}
 /**
-* Compute a deterministic reference key for an existing resource.
-* Format: "apiVersion/kind/[namespace/]name" or "apiVersion/kind/__unresolved__" if name is not yet known.
+* Coerce a value to a string, handling PrimitiveReadProxy objects that wrap
+* primitive values behind a `Symbol.toPrimitive` method.
+* Returns `undefined` if the value cannot be resolved to a string.
 */
+function coerceToString(value) {
+	if (typeof value === "string") return value;
+	if (value != null && typeof value[Symbol.toPrimitive] === "function") return String(value);
+}
 function computeRefKey(apiVersion, kind, name, namespace) {
 	const namePart = name ?? "__unresolved__";
 	if (namespace) return `${apiVersion}/${kind}/${namespace}/${namePart}`;
 	return `${apiVersion}/${kind}/${namePart}`;
 }
-/**
-* Produce an 8-character hex hash of a string using a simple djb2-style
-* algorithm — no crypto dependency required.
-*/
 function shortHash(s) {
 	let h = 5381;
 	for (let i = 0; i < s.length; i++) {
@@ -656,165 +618,651 @@ function shortHash(s) {
 	}
 	return h.toString(16).padStart(8, "0");
 }
-/** Recursively remove UNRESOLVED sentinel values from an object. */
-function stripUnresolved(obj) {
-	if (obj === null || obj === void 0) return obj;
-	if (typeof obj === "symbol" && obj === UNRESOLVED) return void 0;
-	if (Array.isArray(obj)) return obj.map(stripUnresolved);
-	if (typeof obj === "object") {
-		const result = {};
-		for (const [key, value] of Object.entries(obj)) {
-			const cleaned = stripUnresolved(value);
-			if (cleaned !== void 0) result[key] = cleaned;
-		}
-		return result;
-	}
-	return obj;
-}
 /**
-* Deep-clone an object while preserving tracked proxy references.
-* Plain objects and arrays are cloned; tracked proxies and primitives are kept as-is.
+* Process the desired props — deep-scan for ReadProxy values and replace them
+* with Pending markers (recording edges in the collector).
 */
-function deepCloneWithTracked(obj) {
-	if (obj === null || obj === void 0) return obj;
-	if (isTracked(obj)) return obj;
-	if (typeof obj !== "object") return obj;
-	if (Array.isArray(obj)) return obj.map(deepCloneWithTracked);
-	const clone = {};
-	for (const [key, value] of Object.entries(obj)) clone[key] = deepCloneWithTracked(value);
-	return clone;
+function processDesiredProps(props, owner, collector) {
+	const result = {};
+	for (const [key, value] of Object.entries(props)) result[key] = processValue(value, owner, key, collector);
+	return result;
+}
+function processValue(value, owner, path, collector) {
+	if (value === null || value === void 0) return value;
+	if (typeof value !== "object") return value;
+	if (isReadProxy(value)) {
+		const meta = getReadProxyMeta(value);
+		collector.add({
+			from: meta.owner,
+			fromPath: meta.path,
+			to: owner,
+			toPath: path
+		});
+		const prim = tryExtractPrimitive$1(value);
+		if (prim !== void 0) return prim;
+		return new Pending(meta.owner, meta.path);
+	}
+	if (Array.isArray(value)) return value.map((item, i) => processValue(item, owner, `${path}[${i}]`, collector));
+	const result = {};
+	for (const [key, val] of Object.entries(value)) result[key] = processValue(val, owner, `${path}.${key}`, collector);
+	return result;
+}
+function tryExtractPrimitive$1(proxy) {
+	const toPrim = proxy[Symbol.toPrimitive];
+	if (typeof toPrim === "function") {
+		const result = toPrim();
+		if (result !== void 0 && result !== null && typeof result !== "object") {
+			if (typeof result === "string" && result.startsWith("__pending__")) return void 0;
+			return result;
+		}
+	}
 }
 /**
-* Recursively scan an object for tracked proxy values from other resources.
-* For each one found, record a dependency edge and replace the value with
-* the UNRESOLVED sentinel. This handles values passed via object literals
-* in constructor props, which bypass the proxy's set trap.
+* Creates the "desired-first, fallback-to-observed" proxy around a Resource.
 */
-function resolveTrackedRefs(obj, owner, basePath, collector) {
-	for (const [key, value] of Object.entries(obj)) {
-		const path = basePath ? `${basePath}.${key}` : key;
-		if (isTracked(value)) {
-			const sourceMeta = getTrackingMeta(value);
-			if (sourceMeta && sourceMeta.owner.id !== owner.id) {
-				collector.addEdge({
-					from: sourceMeta.owner,
-					fromPath: sourceMeta.path,
-					to: owner,
-					toPath: path
+function createResourceProxy(resource, internal) {
+	const { ref, desired, collector } = internal;
+	const proxy = new Proxy(resource, {
+		get(target, prop, receiver) {
+			if (prop === "node") return Reflect.get(target, prop, receiver);
+			if (prop === "resource") return Reflect.get(target, prop, receiver);
+			if (typeof prop === "symbol") return Reflect.get(target, prop, receiver);
+			if (prop === "constructor") return Reflect.get(target, prop, receiver);
+			if (prop in desired) {
+				const value = desired[String(prop)];
+				if (typeof value === "object" && value !== null && !Pending.is(value)) return createWriteProxy(value, {
+					owner: ref,
+					collector,
+					basePath: String(prop)
 				});
-				obj[key] = UNRESOLVED;
+				return value;
 			}
-			continue;
+			const observed = internal.observed;
+			if (String(prop) in observed) {
+				const value = observed[String(prop)];
+				if (typeof value === "object" && value !== null) return createReadProxy(value, ref, String(prop));
+				return createPrimitiveReadProxyFromResource(value, ref, String(prop));
+			}
+			return createReadProxy({}, ref, String(prop));
+		},
+		set(target, prop, value) {
+			if (typeof prop === "symbol") return Reflect.set(target, prop, value);
+			if (prop === "resource") return Reflect.set(target, prop, value);
+			const path = String(prop);
+			desired[path] = processValue(value, ref, path, collector);
+			return true;
+		},
+		has(target, prop) {
+			if (typeof prop === "symbol") return Reflect.has(target, prop);
+			if (prop === "node" || prop === "resource") return true;
+			return prop in desired || prop in internal.observed;
 		}
-		if (Array.isArray(value)) {
-			for (let i = 0; i < value.length; i++) {
-				const item = value[i];
-				if (isTracked(item)) {
-					const sourceMeta = getTrackingMeta(item);
-					if (sourceMeta && sourceMeta.owner.id !== owner.id) {
-						collector.addEdge({
-							from: sourceMeta.owner,
-							fromPath: sourceMeta.path,
-							to: owner,
-							toPath: `${path}[${i}]`
-						});
-						value[i] = UNRESOLVED;
-					}
-				} else if (typeof item === "object" && item !== null) resolveTrackedRefs(item, owner, `${path}[${i}]`, collector);
+	});
+	internals.set(proxy, internal);
+	return proxy;
+}
+/**
+* Wrap a primitive observed value so it carries ReadProxy metadata
+* for dependency tracking when assigned elsewhere.
+*/
+function createPrimitiveReadProxyFromResource(value, owner, path) {
+	if (value === null || value === void 0) return value;
+	return createPrimitiveReadProxy(value, owner, path);
+}
+//#endregion
+//#region src/logging/context.ts
+const noopLogger = {
+	debug() {},
+	info() {},
+	warn() {}
+};
+const loggerStorage = new AsyncLocalStorage();
+/**
+* Get the current logger from async context.
+* Returns a no-op logger if none has been set (silent by default).
+*/
+function getLogger() {
+	return loggerStorage.getStore() ?? noopLogger;
+}
+/**
+* Run a function with a logger available in async context.
+* All code within `fn` (and any nested async calls) can access
+* the logger via `getLogger()`.
+*/
+function withLogger(logger, fn) {
+	return loggerStorage.run(logger, fn);
+}
+//#endregion
+//#region src/pipeline/diagnose.ts
+/**
+* DIAGNOSE phase: produce structured diagnostics for blocked resources.
+*
+* For each resource classified as 'blocked':
+* - Find all Pending markers in the desired document
+* - Report what they're waiting on (source resource + path)
+*
+* For circular dependencies (detected in sequence phase):
+* - Produce a 'cycle' diagnostic with the full cycle path
+*/
+function diagnose(state) {
+	const diagnostics = [];
+	const sortResult = state.graph.topologicalSort();
+	if (sortResult.order === null && sortResult.cycle) {
+		const firstCycleMember = sortResult.cycle[0];
+		if (firstCycleMember) diagnostics.push({
+			resource: firstCycleMember,
+			reason: "cycle",
+			cycle: sortResult.cycle
+		});
+	}
+	for (const resource of state.resources) {
+		if (!isExternal(resource)) continue;
+		const ref = getExternalRef(resource);
+		if (!ref) continue;
+		const observed = getObservedDocument(resource);
+		if (Object.keys(observed).length > 0) continue;
+		const nameDisplay = typeof ref.name === "string" ? ref.name : ref.name == null ? "(unresolved)" : "(unresolved)";
+		const nsDisplay = ref.namespace ? ` in namespace '${ref.namespace}'` : "";
+		diagnostics.push({
+			resource: getResourceRef(resource).id,
+			reason: "not-found",
+			detail: `External resource ${ref.apiVersion}/${ref.kind} '${nameDisplay}'${nsDisplay} was required but not found by Crossplane`
+		});
+	}
+	const pendingDiagnostics = [];
+	for (const resource of state.resources) {
+		if (isExternal(resource)) continue;
+		const ref = getResourceRef(resource);
+		if (state.classification.get(ref.id) !== "blocked") continue;
+		if (sortResult.order === null && sortResult.cycle?.includes(ref.id)) continue;
+		const pendingPaths = findPendingPaths(getDesiredDocument(resource), "");
+		if (pendingPaths.length > 0) pendingDiagnostics.push({
+			resource: ref.id,
+			reason: "pending",
+			pendingPaths
+		});
+	}
+	const notFoundIds = new Set(diagnostics.filter((d) => d.reason === "not-found").map((d) => d.resource));
+	const blockedIds = new Set(pendingDiagnostics.map((d) => d.resource));
+	for (const diag of pendingDiagnostics) if (diag.pendingPaths?.some((p) => {
+		const dep = p.waitingOn.resource;
+		return !blockedIds.has(dep) && !notFoundIds.has(dep);
+	})) diagnostics.push(diag);
+	return {
+		...state,
+		diagnostics
+	};
+}
+/**
+* Recursively find all Pending markers in a document and report their source.
+*/
+function findPendingPaths(obj, basePath) {
+	const results = [];
+	if (obj === null || obj === void 0) return results;
+	if (Pending.is(obj)) {
+		results.push({
+			path: basePath,
+			waitingOn: {
+				resource: obj.source.id,
+				path: obj.path
 			}
-			continue;
+		});
+		return results;
+	}
+	if (typeof obj !== "object") return results;
+	if (Array.isArray(obj)) {
+		for (let i = 0; i < obj.length; i++) {
+			const childPath = basePath ? `${basePath}[${i}]` : `[${i}]`;
+			results.push(...findPendingPaths(obj[i], childPath));
 		}
-		if (typeof value === "object" && value !== null) resolveTrackedRefs(value, owner, path, collector);
+		return results;
+	}
+	for (const [key, value] of Object.entries(obj)) {
+		const childPath = basePath ? `${basePath}.${key}` : key;
+		results.push(...findPendingPaths(value, childPath));
 	}
+	return results;
 }
 //#endregion
-//#region src/ready/auto-ready.ts
+//#region src/pipeline/emit.ts
 /**
-* Determines if a Crossplane managed resource is ready based on its
-* observed status conditions.
+* EMIT phase: serialize each resource classified as 'emit' into a plain
+* Kubernetes resource document ready for Crossplane.
 *
-* - If the resource has a `Ready: True` condition → ready.
-* - If the resource has a `Ready: False` condition → not ready.
-* - If the resource exists but has no `Ready` condition at all (e.g. Namespace,
-*   ProviderConfig) → considered ready (the resource exists and is functional).
-* - If not yet observed → not ready.
-*/
-function isResourceReady(observed) {
-	if (!observed) return false;
-	const conditions = observed.status?.conditions;
-	if (!Array.isArray(conditions) || conditions.length === 0) return true;
-	const readyCondition = conditions.find((c) => c.type === "Ready");
-	if (!readyCondition) return true;
-	return readyCondition.status === "True";
+* Also extracts the XR desired status from this.xr.status assignments.
+*/
+function emit(state) {
+	const emitted = [];
+	for (const resource of state.resources) {
+		if (isExternal(resource)) continue;
+		const ref = getResourceRef(resource);
+		if (state.classification.get(ref.id) !== "emit") continue;
+		const internal = getResourceInternals(resource);
+		const desired = getDesiredDocument(resource);
+		const name = ref.id.startsWith("Composition/") ? ref.id.slice(12) : ref.id;
+		emitted.push({
+			name,
+			document: deepClean(desired),
+			autoReady: internal.config.autoReady,
+			readyChecks: getReadyChecks(resource)
+		});
+	}
+	const resourceById = new Map(state.resources.map((r) => [getResourceRef(r).id, r]));
+	const xrStatusPatches = resolveXrStatus(getXrDesiredStatus(state.composition), resourceById);
+	return {
+		...state,
+		emitted,
+		xrStatusPatches
+	};
 }
 /**
-* Gets the Ready condition from a resource, if present.
+* Deep-clone an object, stripping any remaining framework internals.
+* This produces a clean JSON-serializable Kubernetes document.
 */
-function getReadyCondition(observed) {
-	if (!observed?.status) return void 0;
-	const conditions = observed.status.conditions;
-	if (!Array.isArray(conditions)) return void 0;
-	return conditions.find((c) => c.type === "Ready");
+function deepClean(obj) {
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) result[key] = cleanValue(value);
+	return result;
+}
+function cleanValue(value) {
+	if (value === null || value === void 0) return value;
+	if (typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(cleanValue);
+	const result = {};
+	for (const [key, val] of Object.entries(value)) result[key] = cleanValue(val);
+	return result;
+}
+/**
+* Resolve ReadProxy values in XR status using observed resource data.
+* This is needed because XR status is written at construction time (before hydration),
+* so read proxy references need to be resolved post-hydration.
+*/
+function resolveXrStatus(status, resourceById) {
+	const result = {};
+	for (const [key, value] of Object.entries(status)) {
+		const resolved = resolveStatusValue(value, resourceById);
+		if (resolved !== void 0) result[key] = resolved;
+	}
+	return result;
+}
+function resolveStatusValue(value, resourceById) {
+	if (value === null || value === void 0) return void 0;
+	if (isReadProxy(value)) {
+		const meta = getReadProxyMeta(value);
+		if (!meta) return void 0;
+		const prim = tryExtractPrimitive(value);
+		if (prim !== void 0) return prim;
+		const resource = resourceById.get(meta.owner.id);
+		if (!resource) return void 0;
+		return getNestedValue$1(getObservedDocument(resource), meta.path);
+	}
+	if (Array.isArray(value)) return value.map((v) => resolveStatusValue(v, resourceById)).filter((v) => v != null);
+	if (typeof value === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) {
+			const resolved = resolveStatusValue(v, resourceById);
+			if (resolved !== void 0) out[k] = resolved;
+		}
+		return Object.keys(out).length > 0 ? out : void 0;
+	}
+	return value;
+}
+function tryExtractPrimitive(proxy) {
+	const toPrim = proxy[Symbol.toPrimitive];
+	if (typeof toPrim === "function") {
+		const result = toPrim();
+		if (result !== void 0 && result !== null && typeof result !== "object") {
+			if (typeof result === "string" && result.startsWith("__pending__")) return void 0;
+			return result;
+		}
+	}
+}
+function getNestedValue$1(obj, path) {
+	const parts = path.split(".");
+	let current = obj;
+	for (const part of parts) {
+		if (current === null || current === void 0 || typeof current !== "object") return void 0;
+		current = current[part];
+	}
+	return current;
+}
+//#endregion
+//#region src/pipeline/hydrate.ts
+/**
+* HYDRATE phase: feed observed state from Crossplane into each resource.
+*
+* - Composed resources are matched by their construct path (resource name).
+* - External resources are matched by their refKey.
+*/
+function hydrate(state) {
+	for (const resource of state.resources) if (isExternal(resource)) {
+		const ref = getExternalRef(resource);
+		if (ref) {
+			const observed = state.observedRequired.get(ref.refKey);
+			if (observed) hydrateObserved(resource, observed);
+		}
+	} else {
+		const name = resource.node.path;
+		const observed = state.observedComposed.get(name);
+		if (observed) hydrateObserved(resource, observed);
+	}
+	return state;
 }
 //#endregion
-//#region src/sequencing/resolver.ts
+//#region src/pipeline/resolve.ts
 /**
-* Resolves resource dependencies and determines which resources can be
-* emitted in the current pass.
+* RESOLVE phase: walk dependency edges and replace Pending markers
+* with concrete values from observed state where available.
 *
-* Algorithm:
-* 1. Topologically sort resources using the dependency graph.
-* 2. For each resource (in order), check if upstream dependencies have
-*    resolved values in observed state.
-* 3. If all deps resolved → emit. If any dep unresolved → block.
-*/
-function resolveSequencing(resources, graph, observedResources) {
-	const order = graph.topologicalSort();
-	const emit = [];
-	const blocked = [];
-	for (const resourceId of order) {
-		const resource = findResourceByRef(resources, resourceId);
-		if (!resource) continue;
-		const deps = graph.getDependencies(resourceId);
-		let allDepsReady = true;
-		for (const depId of deps) {
-			const depResource = findResourceByRef(resources, depId);
-			if (!depResource) {
-				if (!observedResources.get(depId)) allDepsReady = false;
-				continue;
+* For each resource's desired document, recursively find Pending values.
+* Look up the source resource's observed state at the source path.
+* If concrete → replace. If not available → leave Pending in place.
+*/
+function resolve(state) {
+	const resourceById = new Map(state.resources.map((r) => [getResourceRef(r).id, r]));
+	for (const resource of state.resources) resolvePending(getDesiredDocument(resource), resourceById);
+	return state;
+}
+/**
+* Recursively walk an object and resolve any Pending markers.
+*/
+function resolvePending(obj, resourceById) {
+	for (const [key, value] of Object.entries(obj)) if (Pending.is(value)) {
+		const sourceResource = resourceById.get(value.source.id);
+		if (sourceResource) {
+			const resolved = getNestedValue(getObservedDocument(sourceResource), value.path);
+			if (resolved !== void 0) obj[key] = resolved;
+		}
+	} else if (Array.isArray(value)) resolveArray(value, resourceById);
+	else if (value !== null && typeof value === "object") resolvePending(value, resourceById);
+}
+function resolveArray(arr, resourceById) {
+	for (let i = 0; i < arr.length; i++) {
+		const value = arr[i];
+		if (Pending.is(value)) {
+			const sourceResource = resourceById.get(value.source.id);
+			if (sourceResource) {
+				const resolved = getNestedValue(getObservedDocument(sourceResource), value.path);
+				if (resolved !== void 0) arr[i] = resolved;
 			}
-			if (!observedResources.get(depResource.path)) allDepsReady = false;
+		} else if (Array.isArray(value)) resolveArray(value, resourceById);
+		else if (value !== null && typeof value === "object") resolvePending(value, resourceById);
+	}
+}
+/**
+* Get a nested value from an object by dot-separated path.
+*/
+function getNestedValue(obj, path) {
+	const segments = path.split(".");
+	let current = obj;
+	for (const segment of segments) {
+		if (current === null || current === void 0) return void 0;
+		if (typeof current !== "object") return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+//#endregion
+//#region src/pipeline/sequence.ts
+/**
+* SEQUENCE phase: topological sort and classification.
+*
+* - Runs topological sort on the dependency graph.
+* - Classifies each resource as 'emit', 'blocked', or 'external'.
+* - A resource is 'blocked' if it still has Pending markers in its desired document.
+* - External resources are classified as 'external' (never emitted).
+* - Circular dependencies are detected via the graph's topological sort.
+*/
+function sequence(state) {
+	const classification = /* @__PURE__ */ new Map();
+	const sortResult = state.graph.topologicalSort();
+	for (const resource of state.resources) {
+		const ref = getResourceRef(resource);
+		if (isExternal(resource)) {
+			classification.set(ref.id, "external");
+			continue;
 		}
-		if (allDepsReady && hasUnresolvedFields(resource)) allDepsReady = false;
-		if (allDepsReady) emit.push(resource);
-		else blocked.push(resource);
+		if (containsPending(getDesiredDocument(resource))) classification.set(ref.id, "blocked");
+		else classification.set(ref.id, "emit");
+	}
+	if (sortResult.order === null && sortResult.cycle) {
+		for (const id of sortResult.cycle) if (classification.get(id) !== "external") classification.set(id, "blocked");
 	}
 	return {
-		emit,
-		blocked,
-		order
+		...state,
+		classification
 	};
 }
 /**
-* Check if a resource's desired state contains any UNRESOLVED sentinels.
-* Uses the raw spec/metadata before stripping, so UNRESOLVED symbols are visible.
+* Recursively check if an object contains any Pending markers.
 */
-function hasUnresolvedFields(resource) {
-	return containsUnresolved(resource.spec) || containsUnresolved(resource.metadata);
-}
-/** Recursively check if an object contains UNRESOLVED sentinels. */
-function containsUnresolved(obj) {
-	if (obj === UNRESOLVED) return true;
+function containsPending(obj) {
 	if (obj === null || obj === void 0) return false;
-	if (Array.isArray(obj)) return obj.some(containsUnresolved);
-	if (typeof obj === "object") return Object.values(obj).some(containsUnresolved);
+	if (Pending.is(obj)) return true;
+	if (typeof obj !== "object") return false;
+	if (Array.isArray(obj)) return obj.some(containsPending);
+	for (const value of Object.values(obj)) if (containsPending(value)) return true;
+	return false;
+}
+//#endregion
+//#region src/pipeline/index.ts
+/**
+* Run the full rendering pipeline.
+*
+* Phases: hydrate → resolve → sequence → diagnose → emit
+*/
+function runPipeline(input) {
+	const resources = collectResources(input.composition);
+	let state = {
+		composition: input.composition,
+		resources,
+		graph: input.composition.graph,
+		observedComposed: input.observedComposed,
+		observedRequired: input.observedRequired,
+		classification: /* @__PURE__ */ new Map(),
+		diagnostics: [],
+		emitted: [],
+		xrStatusPatches: {}
+	};
+	state = hydrate(state);
+	state = resolve(state);
+	state = sequence(state);
+	state = diagnose(state);
+	state = emit(state);
+	return state;
+}
+/**
+* Collect all Resource instances from the composition's construct tree.
+*/
+function collectResources(composition) {
+	const resources = [];
+	collectFromNode(composition, resources);
+	return resources;
+}
+function collectFromNode(construct, resources) {
+	for (const child of construct.node.children) {
+		if (isResourceInstance(child)) resources.push(child);
+		collectFromNode(child, resources);
+	}
+}
+function isResourceInstance(obj) {
+	if (obj === null || typeof obj !== "object") return false;
+	const r = obj;
+	if (!("resource" in r) || r.resource === null || typeof r.resource !== "object") return false;
+	return "autoReady" in r.resource;
+}
+//#endregion
+//#region src/readiness/defaults.ts
+/**
+* Checks if the resource has a `Ready` condition with status `True`.
+*/
+function conditionReady(observed) {
+	const conditions = observed.status?.conditions;
+	if (!conditions || !Array.isArray(conditions)) return void 0;
+	const ready = conditions.find((c) => c.type === "Ready");
+	if (!ready) return void 0;
+	return ready.status === "True";
+}
+/**
+* Checks if the resource has `status.ready === true`.
+*/
+function statusReady(observed) {
+	const status = observed.status;
+	if (status === void 0) return void 0;
+	if (!("ready" in status)) return void 0;
+	return status.ready === true;
+}
+/**
+* Fallback: resource exists in observed state → ready.
+* Always returns `true` (only called when observed is defined).
+*/
+function exists(_observed) {
+	return true;
+}
+/**
+* Built-in default readiness checks, appended at low priority.
+*/
+const DEFAULT_CHECKS = [
+	{
+		fn: conditionReady,
+		priority: 100,
+		name: "conditionReady"
+	},
+	{
+		fn: statusReady,
+		priority: 200,
+		name: "statusReady"
+	},
+	{
+		fn: exists,
+		priority: 1e3,
+		name: "exists"
+	}
+];
+//#endregion
+//#region src/readiness/evaluate.ts
+/**
+* Evaluate readiness for a resource by running checks grouped by priority.
+*
+* - If `observed` is undefined, the resource doesn't exist yet → not ready.
+* - Checks are grouped by priority (ascending). Within a group, all checks
+*   are AND-ed: if any returns `false`, the resource is not ready. If at least
+*   one returns `true` and none return `false`, the resource is ready.
+*   If all return `undefined`, cascade to the next priority group.
+* - Final fallback (no group had a definitive answer): not ready.
+*/
+function evaluateReadiness(checks, observed) {
+	const log = getLogger();
+	if (!observed) {
+		log.debug("readiness: resource not observed, not ready");
+		return false;
+	}
+	const groups = /* @__PURE__ */ new Map();
+	for (const check of checks) {
+		const group = groups.get(check.priority);
+		if (group) group.push(check);
+		else groups.set(check.priority, [check]);
+	}
+	const priorities = [...groups.keys()].sort((a, b) => a - b);
+	for (const priority of priorities) {
+		const group = groups.get(priority);
+		let hasTrue = false;
+		let hasFalse = false;
+		const results = [];
+		for (const check of group) {
+			const result = check.fn(observed);
+			results.push({
+				name: check.name ?? "anonymous",
+				result
+			});
+			if (result === false) {
+				hasFalse = true;
+				break;
+			}
+			if (result === true) hasTrue = true;
+		}
+		log.debug("readiness: evaluated group", {
+			priority,
+			results
+		});
+		if (hasFalse) {
+			log.debug("readiness: group returned false, not ready", { priority });
+			return false;
+		}
+		if (hasTrue) {
+			log.debug("readiness: group returned true, ready", { priority });
+			return true;
+		}
+	}
+	log.debug("readiness: no group had definitive answer, not ready");
 	return false;
 }
-/** Find a resource by its ref ID (which is the path). */
-function findResourceByRef(resources, refId) {
-	return resources.get(refId);
+//#endregion
+//#region src/run.ts
+/**
+* Run a composition class with the given input and return a plain-data result.
+*
+* This is the single entry point that bridges the composition author's class
+* with the runtime. It handles:
+* 1. Setting up internal context (DependencyGraph, EdgeCollector, ALS)
+* 2. Instantiating the Composition class
+* 3. Running the full pipeline (hydrate → resolve → sequence → diagnose → emit)
+* 4. Evaluating readiness per resource
+* 5. Returning a fully serializable CompositionResult
+*
+* The runtime never needs to access framework internals — everything it needs
+* is in the returned plain-data structure.
+*/
+function runComposition(CompositionClass, input) {
+	const observedComposed = new Map(Object.entries(input.observedComposed));
+	const observedRequired = new Map(Object.entries(input.observedRequired));
+	const graph = new DependencyGraph();
+	const collector = new EdgeCollector();
+	const pipelineContext = new Map(Object.entries(input.pipelineContext));
+	const ctx = {
+		xr: input.xr,
+		pipelineContext,
+		requiredResources: observedRequired,
+		graph,
+		collector
+	};
+	const state = runPipeline({
+		composition: compositionStorage.run(ctx, () => new CompositionClass()),
+		observedComposed,
+		observedRequired
+	});
+	const resources = state.emitted.map((emitted) => {
+		const allChecks = [...emitted.readyChecks, ...DEFAULT_CHECKS];
+		const observed = observedComposed.get(`Composition/${emitted.name}`);
+		const ready = emitted.autoReady ? evaluateReadiness(allChecks, observed) : true;
+		return {
+			name: emitted.name,
+			document: emitted.document,
+			ready
+		};
+	});
+	const externalResources = [];
+	for (const resource of state.resources) {
+		if (!isExternal(resource)) continue;
+		const ref = getExternalRef(resource);
+		if (!ref || typeof ref.name !== "string") continue;
+		if (ref.name.startsWith("__pending__")) continue;
+		externalResources.push({
+			refKey: ref.refKey,
+			apiVersion: ref.apiVersion,
+			kind: ref.kind,
+			name: ref.name,
+			...ref.namespace ? { namespace: ref.namespace } : {}
+		});
+	}
+	return {
+		resources,
+		externalResources,
+		xrStatus: state.xrStatusPatches,
+		diagnostics: state.diagnostics
+	};
 }
 //#endregion
-export { Composition, Construct, DependencyCollector, DependencyGraph, IS_TRACKED, Resource, TRACKING_META, UNRESOLVED, computeRefKey, createTrackedProxy, getReadyCondition, getTrackingMeta, isResourceReady, isTracked, resolveSequencing };
+export { Composition, Construct, DEFAULT_CHECKS, DependencyGraph, EdgeCollector, Pending, Resource, compositionStorage, createPrimitiveReadProxy, createReadProxy, createWriteProxy, diagnose, emit, evaluateReadiness, getCompositionContext, getDesiredDocument, getExternalRef, getLogger, getObservedDocument, getReadProxyMeta, getReadyChecks, getResourceInternals, getResourceRef, getXrDesiredStatus, hydrate, hydrateObserved, isExternal, isReadProxy, resolve, runComposition, runPipeline, sequence, withLogger };
 
 //# sourceMappingURL=index.mjs.map