@xplane/core 0.16.0 → 1.0.0

package/dist/index.d.mts

@@ -1,148 +1,345 @@
 import { Construct, Construct as Construct$1 } from "constructs";
+import { AsyncLocalStorage } from "node:async_hooks";
 
-//#region src/tracking/types.d.ts
+//#region src/contract.d.ts
+/**
+ * Contract types defining the boundary between the runtime (@xplane/function)
+ * and the framework (@xplane/core).
+ *
+ * The runtime provides CompositionInput (plain data extracted from Crossplane),
+ * the framework returns CompositionResult (plain serializable data).
+ * No class instances, no WeakMaps, no shared state crosses this boundary.
+ */
+/**
+ * Plain data input provided by the runtime to the composition.
+ * All values are serializable Records — no class instances.
+ */
+interface CompositionInput {
+  /** Observed XR data (spec, status, metadata). */
+  xr: Record<string, unknown>;
+  /** Crossplane function pipeline context keys. */
+  pipelineContext: Record<string, unknown>;
+  /** Observed composed resources, keyed by resource name (e.g. "Composition/vpc"). */
+  observedComposed: Record<string, Record<string, unknown>>;
+  /** Observed existing/required resources, keyed by refKey. */
+  observedRequired: Record<string, Record<string, unknown>>;
+}
+/**
+ * Plain data output returned by the composition to the runtime.
+ * Fully serializable — no class instances, proxies, or internal state.
+ */
+interface CompositionResult {
+  /** Resources to emit to Crossplane as desired composed resources. */
+  resources: DesiredResource[];
+  /** External resources that need to be fetched via requireResource. */
+  externalResources: ExternalResourceRequest[];
+  /** Desired XR status patches (from this.xr.status assignments). */
+  xrStatus: Record<string, unknown>;
+  /** Diagnostic reports for blocked/unresolved resources. */
+  diagnostics: Diagnostic[];
+}
+/** A desired composed resource ready for emission. */
+interface DesiredResource {
+  /** The resource name (construct path without "Composition/" prefix). */
+  name: string;
+  /** The fully-resolved desired Kubernetes resource document. */
+  document: Record<string, unknown>;
+  /** Whether this resource is ready (readiness already evaluated). */
+  ready: boolean;
+}
+/** A request to fetch an external (existing) resource. */
+interface ExternalResourceRequest {
+  /** The refKey used to match the resource. */
+  refKey: string;
+  apiVersion: string;
+  kind: string;
+  /** The name to match. */
+  name: string;
+  /** Optional namespace. */
+  namespace?: string;
+}
+/** A diagnostic report for a blocked resource. */
+interface Diagnostic {
+  /** The resource name (construct path). */
+  resource: string;
+  /** Why the resource is blocked. */
+  reason: 'pending' | 'cycle' | 'not-found';
+  /** For 'pending': what paths are waiting on what. */
+  pendingPaths?: Array<{
+    path: string;
+    waitingOn: {
+      resource: string;
+      path: string;
+    };
+  }>;
+  /** For 'cycle': the cycle path. */
+  cycle?: string[];
+  /** Human-readable detail. */
+  detail?: string;
+}
 /**
- * Symbols used to access tracking metadata on proxy-wrapped values.
- * These are not enumerable and won't leak into serialized output.
+ * The shape of what a composition bundle must export.
+ * Both full bundles and thin bundles export this.
  */
-declare const TRACKING_META: unique symbol;
-declare const IS_TRACKED: unique symbol;
-/** Identifies which resource a tracked value belongs to. */
+interface CompositionModule {
+  run(input: CompositionInput): CompositionResult;
+}
+//#endregion
+//#region src/tracking/types.d.ts
+/** Identifies a resource in the dependency graph. */
 interface ResourceRef {
   readonly id: string;
 }
-/** A single dependency edge between two resource fields. */
+/** A dependency edge between two resources at specific field paths. */
 interface DependencyEdge {
-  /** Resource whose field is being read (the dependency). */
+  /** Resource being read from (observed state). */
   readonly from: ResourceRef;
-  /** Dot-separated path on the source resource. */
+  /** Path in the source resource's observed data. */
   readonly fromPath: string;
-  /** Resource whose field is being set (the dependent). */
+  /** Resource being written to (desired state). */
   readonly to: ResourceRef;
-  /** Dot-separated path on the target resource. */
+  /** Path in the target resource's desired data. */
   readonly toPath: string;
 }
-/** Metadata attached to every tracked proxy. */
-interface TrackingMeta {
-  /** The resource this value belongs to. */
-  readonly owner: ResourceRef;
-  /** The dot-separated path from root of the resource object. */
+/**
+ * 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.
+ */
+declare const PENDING_TAG: unique symbol;
+declare class Pending {
+  /** The resource that owns the observed data. */
+  readonly source: ResourceRef;
+  /** The path within that resource's observed data. */
   readonly path: string;
-  /** Whether this value originates from observed state (read-only). */
-  readonly observed: boolean;
+  static readonly TAG: symbol;
+  readonly [PENDING_TAG] = true;
+  constructor(/** The resource that owns the observed data. */
+
+  source: ResourceRef, /** The path within that resource's observed data. */
+
+  path: string);
+  static is(value: unknown): value is Pending;
 }
-/** Reference to an existing cluster resource requested via Crossplane's required resources mechanism. */
-interface ExistingResourceRef {
-  /** API version of the resource (e.g. "example.io/v1"). */
-  readonly apiVersion: string;
-  /** Kind of the resource (e.g. "Project"). */
-  readonly kind: string;
-  /** Name of the resource. May be a raw string or a tracked proxy value (resolved later). */
-  readonly name: unknown;
-  /** Optional namespace of the resource. */
-  readonly namespace?: string;
-  /** Deterministic key for this reference (apiVersion/kind/[namespace/]name). */
-  readonly refKey: string;
+/** Metadata associated with a ReadProxy instance. */
+interface ReadProxyMeta {
+  readonly owner: ResourceRef;
+  readonly path: string;
 }
 //#endregion
 //#region src/tracking/dependency-graph.d.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.
  */
 declare class DependencyGraph {
-  /** adjacency list: resource id → set of resource ids it depends on */
-  private readonly _deps;
-  /** all registered resource refs by id */
+  private readonly _adjacency;
   private readonly _resources;
-  /** raw edges for introspection */
   private readonly _edges;
-  /** Register a resource node in the graph. */
   addResource(ref: ResourceRef): void;
-  /** Add dependency edges from the collector. */
+  addEdge(edge: DependencyEdge): void;
   addEdges(edges: ReadonlyArray<DependencyEdge>): void;
-  /** Add an explicit dependency: `dependent` depends on `dependency`. */
   addExplicitDependency(dependent: ResourceRef, dependency: ResourceRef): void;
-  /** Get all resource IDs that `resourceId` directly depends on. */
+  /** Get the set of resource IDs that `resourceId` depends on. */
   getDependencies(resourceId: string): ReadonlySet<string>;
-  /** Get all registered resource IDs. */
   get resourceIds(): ReadonlyArray<string>;
-  /** Get all raw edges. */
   get edges(): ReadonlyArray<DependencyEdge>;
   /**
-   * 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(): string[];
+  topologicalSort(): {
+    order: string[];
+  } | {
+    order: null;
+    cycle: string[];
+  };
 }
 //#endregion
-//#region src/tracking/proxy.d.ts
+//#region src/tracking/read-proxy.d.ts
 /**
- * Registry that collects dependency edges discovered during proxy access.
- * Shared across all tracked values within a single composition run.
+ * Check if a value is a ReadProxy.
+ */
+declare function isReadProxy(value: unknown): value is object;
+/**
+ * Get the metadata for a ReadProxy value.
+ */
+declare function getReadProxyMeta(value: unknown): ReadProxyMeta | undefined;
+/**
+ * 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.
  */
-declare class DependencyCollector {
+declare function createReadProxy<T extends object>(target: T, owner: ResourceRef, basePath: string): T;
+/**
+ * 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.
+ */
+declare function createPrimitiveReadProxy(value: string | number | boolean, owner: ResourceRef, path: string): object;
+//#endregion
+//#region src/tracking/write-proxy.d.ts
+/**
+ * Collector that accumulates dependency edges discovered during
+ * WriteProxy assignments.
+ */
+declare class EdgeCollector {
   private readonly _edges;
-  addEdge(edge: DependencyEdge): void;
+  add(edge: DependencyEdge): void;
   get edges(): ReadonlyArray<DependencyEdge>;
-  clear(): void;
 }
-/** Options for creating a tracked proxy. */
-interface TrackedProxyOptions {
-  /** Which resource this value belongs to. */
+interface WriteProxyOptions {
+  /** The resource that owns this desired document. */
   owner: ResourceRef;
-  /** Dot-path from the resource root (e.g. "spec.forProvider.region"). */
-  path: string;
-  /** Whether this originates from observed state. */
-  observed: boolean;
-  /** Shared collector for discovered dependencies. */
-  collector: DependencyCollector;
+  /** The collector to record edges into. */
+  collector: EdgeCollector;
+  /** Base path prefix (e.g., "spec" when wrapping the spec subtree). */
+  basePath?: string;
+}
+/**
+ * Creates a WriteProxy that wraps a desired document.
+ *
+ * - 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).
+ */
+declare function createWriteProxy<T extends object>(target: T, opts: WriteProxyOptions): T;
+//#endregion
+//#region src/core/composition.d.ts
+/** The shape of the XR proxy exposed via `this.xr`. */
+interface XrProxy<TSpec = Record<string, unknown>, TStatus = Record<string, unknown>> {
+  spec: TSpec;
+  status: TStatus;
+  metadata: {
+    name: string;
+    namespace?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+/**
+ * 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.
+ */
+declare class Composition<TSpec = Record<string, unknown>, TStatus = Record<string, unknown>, TContext extends object = Record<string, unknown>> 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.
+   */
+  readonly xr: XrProxy<TSpec, TStatus>;
+  /** The dependency graph tracking resource relationships. */
+  readonly graph: DependencyGraph;
+  /** The edge collector accumulating dependency edges. */
+  readonly collector: EdgeCollector;
+  constructor();
   /**
-   * When true, missing keys on observed proxies return `undefined` instead of
-   * placeholder proxies. This allows optional chaining (`?.`) to short-circuit
-   * correctly. Used for XR proxies whose data is fully available at composition time.
+   * Read-only accessor for Crossplane function pipeline context.
+   * Keys are the context keys set by Crossplane or prior functions in the pipeline.
    */
-  strict?: boolean;
+  get pipelineContext(): PipelineContextAccessor<TContext>;
+}
+/** Typed read-only interface for pipeline context. */
+interface PipelineContextAccessor<TContext extends object = Record<string, unknown>> {
+  get<K extends keyof TContext>(key: K): TContext[K] | undefined;
+  has(key: keyof TContext): boolean;
+  keys(): IterableIterator<keyof TContext>;
 }
 /**
- * Returns true if `value` is a tracked proxy created by `createTrackedProxy`.
+ * Extract the desired XR status from a Composition instance.
+ * Used by the emit pipeline phase to produce composite status output.
  */
-declare function isTracked(value: unknown): value is object & {
-  [TRACKING_META]: TrackingMeta;
-};
+declare function getXrDesiredStatus(composition: Composition): Record<string, unknown>;
+//#endregion
+//#region src/core/context.d.ts
 /**
- * Retrieves the tracking metadata from a tracked proxy.
- * Returns undefined if the value is not tracked.
+ * Runtime context passed into a Composition during construction
+ * via AsyncLocalStorage. Holds everything the Composition needs
+ * without relying on static state or globalThis.
  */
-declare function getTrackingMeta(value: unknown): TrackingMeta | undefined;
+interface CompositionContext {
+  /** Observed XR data. */
+  xr: Record<string, unknown>;
+  /** Full Crossplane function pipeline context (all keys). */
+  pipelineContext: ReadonlyMap<string, unknown>;
+  /** Pre-populated data for existing resources (from prior iterations). */
+  requiredResources: ReadonlyMap<string, Record<string, unknown>>;
+  /** The dependency graph for this composition run. */
+  graph: DependencyGraph;
+  /** The edge collector for this composition run. */
+  collector: EdgeCollector;
+}
+/**
+ * AsyncLocalStorage instance that carries the CompositionContext.
+ * The handler sets it before constructing the user's Composition,
+ * and the Composition constructor reads from it.
+ */
+declare const compositionStorage: AsyncLocalStorage<CompositionContext>;
+/**
+ * Get the current composition context from AsyncLocalStorage.
+ * Throws if called outside of a composition construction scope.
+ */
+declare function getCompositionContext(): CompositionContext;
+//#endregion
+//#region src/readiness/types.d.ts
 /**
- * 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.
+ * A readiness check function that evaluates whether a resource is ready
+ * based on its observed state.
  *
- * 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.
+ * @returns `true` if ready, `false` if not ready, `undefined` if unable to determine
  */
-declare function createTrackedProxy<T extends object>(target: T, opts: TrackedProxyOptions): T;
+type ReadyCheckFn = (observed: Record<string, unknown>) => boolean | undefined;
 /**
- * Sentinel value used when a tracked reference cannot be resolved yet
- * (the source resource hasn't been observed).
+ * A readiness check with an associated priority.
+ * Lower priority numbers are evaluated first.
+ * Checks at the same priority level are AND-ed together.
  */
-declare const UNRESOLVED: unique symbol;
+interface ReadyCheck {
+  fn: ReadyCheckFn;
+  priority: number;
+  name?: string;
+}
 //#endregion
-//#region src/core/resource.d.ts
+//#region src/readiness/defaults.d.ts
+/**
+ * Built-in default readiness checks, appended at low priority.
+ */
+declare const DEFAULT_CHECKS: ReadyCheck[];
+//#endregion
+//#region src/readiness/evaluate.d.ts
 /**
- * Recursive type that allows arbitrary deep property access without undefined.
- * Uses a known-key mapped type to bypass noUncheckedIndexedAccess.
- * Used as the default for untyped Resource spec/status so that
- * `resource.spec.forProvider.vpcId` compiles without casts.
+ * 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.
  */
-type AnyFields = Record<string, any>;
-/** Minimal Kubernetes resource shape. */
+declare function evaluateReadiness(checks: ReadyCheck[], observed: Record<string, unknown> | undefined): boolean;
+//#endregion
+//#region src/core/resource.d.ts
+/** Minimal shape for a Kubernetes resource — only apiVersion + kind required. */
 interface KubernetesResource {
   apiVersion: string;
   kind: string;
@@ -153,278 +350,257 @@ interface KubernetesResource {
     annotations?: Record<string, string>;
     [key: string]: unknown;
   };
-  spec?: Record<string, unknown>;
-  status?: Record<string, unknown>;
   [key: string]: unknown;
 }
-/** Props for constructing a Resource. */
+/** Props passed to the Resource constructor — becomes the desired document. */
 interface ResourceProps {
   apiVersion: string;
   kind: string;
-  metadata?: {
+  [key: string]: unknown;
+}
+/** Framework configuration accessible via `resource.resource`. */
+interface ResourceConfig {
+  autoReady: boolean;
+  addReadyCheck(fn: ReadyCheckFn, priority?: number): void;
+}
+/** Internal metadata stored per Resource (not exposed on the proxy). */
+interface ResourceInternals {
+  /** Unique reference for the dependency graph. */
+  ref: ResourceRef;
+  /** The desired document (what the user wrote). */
+  desired: Record<string, unknown>;
+  /** The observed document (populated by the hydrate phase). */
+  observed: Record<string, unknown>;
+  /** Whether this is an external (existing) resource. */
+  external: boolean;
+  /** For external resources: the lookup key. */
+  externalRef?: ExternalResourceRef;
+  /** Framework config. */
+  config: ResourceConfig;
+  /** Custom readiness checks registered by the composition author. */
+  readyChecks: ReadyCheck[];
+  /** The dependency graph. */
+  graph: DependencyGraph;
+  /** The edge collector. */
+  collector: EdgeCollector;
+}
+interface ExternalResourceRef {
+  apiVersion: string;
+  kind: string;
+  name: unknown;
+  namespace?: string;
+  refKey: string;
+}
+/**
+ * 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 only reserved properties are `node` (from Construct) and `resource`
+ * (framework config namespace).
+ */
+declare class Resource extends Construct$1 {
+  readonly resource: ResourceConfig;
+  metadata: {
     name?: string;
     namespace?: string;
     labels?: Record<string, string>;
     annotations?: Record<string, string>;
     [key: string]: unknown;
   };
-  spec?: Record<string, unknown>;
-  /** Top-level extra fields for resources that don't use spec (e.g. Secret's data/stringData/type). */
-  [key: string]: unknown;
-}
-/** Configuration options for a resource. */
-interface ResourceOptions {
-  /** Whether auto-ready detection is enabled for this resource. Default: true. */
-  autoReady?: boolean;
-}
-/**
- * A Construct that represents a single Crossplane managed/composed resource.
- *
- * 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.
- */
-declare class Resource<TSpec extends object = AnyFields, TStatus extends object = AnyFields> extends Construct$1 {
-  readonly apiVersion: string;
-  readonly kind: string;
-  readonly resourceRef: ResourceRef;
-  /** Proxy-wrapped desired spec — writes are tracked. */
-  readonly spec: TSpec;
-  /** Proxy-wrapped observed status — reads create dependency tracking. */
-  readonly status: TStatus;
-  /** Proxy-wrapped desired metadata. */
-  readonly metadata: NonNullable<KubernetesResource['metadata']>;
+  constructor(scope: Construct$1, id: string, props: ResourceProps);
   /**
-   * 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).
+   * Look up an existing cluster resource by name.
+   * Returns a Resource that only has observed state (no desired output).
+   *
+   * 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`.
    */
-  readonly root: AnyFields;
-  /** Whether auto-ready is enabled for this resource. */
-  autoReady: boolean;
-  /** Whether this is a read-only reference to an existing cluster resource. */
-  readonly isExisting: boolean;
-  /** If this is an existing resource, holds the reference metadata for the handler. */
-  readonly existingRef: ExistingResourceRef | undefined;
-  /** Extra top-level fields (e.g. data/stringData for Secret). Not proxy-tracked. */
-  private readonly _extra;
-  /** Observed state populated by the bridge before construction. */
-  private _observed;
-  /** Backing object for the status proxy — populated by setObserved(). */
-  private readonly _statusTarget;
-  /** Backing object for the spec proxy (existing resources only) — populated by setObservedFull(). */
-  private readonly _specTarget;
-  /** Backing object for the root proxy — populated by setObservedFull(). */
-  private readonly _rootTarget;
-  /** Backing object for the metadata proxy — populated by setObserved(). */
-  private readonly _metaTarget;
-  /** Keys the user explicitly declared in constructor metadata props. */
-  private readonly _desiredMetaKeys;
-  /** Explicit dependency refs. */
-  private readonly _explicitDeps;
-  /** @internal */
-  private readonly _graph;
-  constructor(scope: Construct$1, id: string, props: ResourceProps, options?: ResourceOptions);
-  /** Fully qualified path in the construct tree. */
-  get path(): string;
-  /** Add an explicit dependency on another resource. */
-  addDependency(other: Resource): void;
-  /** Get explicit dependency refs. */
-  get explicitDependencies(): ReadonlyArray<ResourceRef>;
-  /** Set observed state (called by the bridge before compose). */
-  setObserved(observed: KubernetesResource): void;
-  /** Get observed state. */
-  get observed(): KubernetesResource | undefined;
+  static fromExistingByName(scope: Construct$1, apiVersion: string, kind: string, name: unknown, namespace?: string): Resource;
   /**
-   * 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`
-   *
-   * - 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.
+   * 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: Construct$1, options?: {
-    /** Maximum length of the resulting name. Default: 63. */maxLength?: number; /** Separator inserted between path segments (also replaces disallowed chars). Default: "-". */
-    separator?: string; /** Regex of characters to keep. Anything else is replaced by the separator. Default: /[^a-zA-Z0-9]/g */
-    allowedPattern?: RegExp; /** Extra string appended after the path segments and before the hash. */
+    maxLength?: number;
+    separator?: string;
+    allowedPattern?: RegExp;
     extra?: string;
   }): string;
-  /**
-   * 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(): KubernetesResource;
-  /**
-   * 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: KubernetesResource): void;
-  /**
-   * 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: Construct$1, apiVersion: string, kind: string, name: unknown, namespace?: string): Resource;
 }
+declare function getResourceInternals(resource: Resource): ResourceInternals;
+declare function getResourceRef(resource: Resource): ResourceRef;
+declare function getDesiredDocument(resource: Resource): Record<string, unknown>;
+declare function getObservedDocument(resource: Resource): Record<string, unknown>;
+declare function hydrateObserved(resource: Resource, data: Record<string, unknown>): void;
+declare function isExternal(resource: Resource): boolean;
+declare function getExternalRef(resource: Resource): ExternalResourceRef | undefined;
+declare function getReadyChecks(resource: Resource): ReadyCheck[];
+//#endregion
+//#region src/logging/types.d.ts
 /**
- * Compute a deterministic reference key for an existing resource.
- * Format: "apiVersion/kind/[namespace/]name" or "apiVersion/kind/__unresolved__" if name is not yet known.
+ * Minimal logger interface for the @xplane/core library.
+ * Compatible with pino, the Crossplane function-sdk Logger, and console.
  */
-declare function computeRefKey(apiVersion: string, kind: string, name: string | undefined, namespace?: string): string;
+interface XplaneLogger {
+  debug(msg: string, data?: Record<string, unknown>): void;
+  info(msg: string, data?: Record<string, unknown>): void;
+  warn(msg: string, data?: Record<string, unknown>): void;
+}
 //#endregion
-//#region src/core/composition.d.ts
+//#region src/logging/context.d.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 } }
- *     });
- *   }
- * }
- * ```
+ * Get the current logger from async context.
+ * Returns a no-op logger if none has been set (silent by default).
  */
-declare class Composition extends Construct$1 {
-  /**
-   * Pending XR data, set by the framework before instantiation.
-   * @internal
-   */
-  static _pendingXR: Record<string, unknown> | undefined;
-  /**
-   * Pending environment data, set by the framework before instantiation.
-   * Populated from the Crossplane context key `apiextensions.crossplane.io/environment`.
-   * @internal
-   */
-  static _pendingEnvironment: Record<string, unknown> | undefined;
-  /** The composite resource (XR) — proxy-wrapped for tracking. */
-  readonly xr: AnyFields;
-  /** Environment data from function-environment-configs or other pipeline steps. */
-  readonly environment: AnyFields;
-  /** Raw name from the XR metadata (not proxy-tracked). */
-  readonly xrName: string | undefined;
-  /** Raw namespace from the XR metadata (not proxy-tracked). */
-  readonly xrNamespace: string | undefined;
-  /** Dependency collector shared across all resources. */
-  readonly collector: DependencyCollector;
-  /** Dependency graph built during compose(). */
-  readonly graph: DependencyGraph;
-  /** Registry of existing (read-only) resource references keyed by refKey. */
-  private readonly _existingResources;
-  /** Registered status output function. @internal */
-  private _statusFn?;
-  constructor();
-  /**
-   * 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: () => Record<string, unknown>): void;
-  /**
-   * Compute and return the desired status output.
-   * Returns an empty object if no status function was registered.
-   * @internal
-   */
-  computeStatusOutput(): Record<string, unknown>;
-  /**
-   * Walk up the construct tree and return the root Composition.
-   * Throws if the scope is not within a Composition.
-   */
-  static of(scope: Construct$1): Composition;
-  /** Get all composed (non-existing) resources keyed by construct path. */
-  get resources(): ReadonlyMap<string, Resource>;
-  /** Get all existing (read-only) resource references keyed by refKey. */
-  get existingResources(): ReadonlyMap<string, Resource>;
-}
+declare function getLogger(): XplaneLogger;
+/**
+ * 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()`.
+ */
+declare function withLogger<T>(logger: XplaneLogger, fn: () => T): T;
 //#endregion
-//#region src/ready/auto-ready.d.ts
-/** Condition from a Kubernetes resource's status.conditions array. */
-interface StatusCondition {
-  type: string;
-  status: string;
-  reason?: string;
-  message?: string;
+//#region src/pipeline/types.d.ts
+interface PipelineState {
+  /** The fully-constructed Composition instance. */
+  composition: Composition;
+  /** All resources in the composition tree (including external). */
+  resources: Resource[];
+  /** The dependency graph. */
+  graph: DependencyGraph;
+  /** Observed composed resources from Crossplane (keyed by resource name). */
+  observedComposed: ReadonlyMap<string, Record<string, unknown>>;
+  /** Observed existing/required resources from Crossplane (keyed by refKey). */
+  observedRequired: ReadonlyMap<string, Record<string, unknown>>;
+  /** Classification of resources after sequencing. */
+  classification: Map<string, ResourceClassification>;
+  /** Diagnostics produced by the diagnose phase. */
+  diagnostics: DiagnosticReport[];
+  /** Emitted desired resources (final output). */
+  emitted: EmittedResource[];
+  /** Desired XR status patches (from this.xr.status assignments). */
+  xrStatusPatches: Record<string, unknown>;
+}
+type ResourceClassification = 'emit' | 'blocked' | 'external';
+interface DiagnosticReport {
+  resource: string;
+  reason: 'pending' | 'cycle' | 'not-found';
+  pendingPaths?: Array<{
+    path: string;
+    waitingOn: {
+      resource: string;
+      path: string;
+    };
+  }>;
+  cycle?: string[];
+  detail?: string;
+}
+interface EmittedResource {
+  /** The construct path (used as resource name in Crossplane). */
+  name: string;
+  /** The desired Kubernetes resource document. */
+  document: Record<string, unknown>;
+  /** Whether autoReady was enabled for this resource. */
+  autoReady: boolean;
+  /** Custom readiness checks registered by the composition author. */
+  readyChecks: ReadyCheck[];
 }
+//#endregion
+//#region src/pipeline/diagnose.d.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
+ */
+declare function diagnose(state: PipelineState): PipelineState;
+//#endregion
+//#region src/pipeline/emit.d.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.
+ * Also extracts the XR desired status from this.xr.status assignments.
  */
-declare function isResourceReady(observed: KubernetesResource | undefined): boolean;
+declare function emit(state: PipelineState): PipelineState;
+//#endregion
+//#region src/pipeline/hydrate.d.ts
 /**
- * Gets the Ready condition from a resource, if present.
+ * 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.
  */
-declare function getReadyCondition(observed: KubernetesResource | undefined): StatusCondition | undefined;
+declare function hydrate(state: PipelineState): PipelineState;
 //#endregion
-//#region src/sequencing/resolver.d.ts
-/** Result of dependency resolution for a single resource. */
-interface ResolutionResult {
-  /** The resource. */
-  resource: Resource;
-  /** Whether all dependencies are satisfied and the resource can be emitted. */
-  ready: boolean;
-  /** Paths that are still unresolved (waiting on upstream). */
-  unresolvedPaths: string[];
-}
-/** Result of resolving all resources in a composition. */
-interface SequencingResult {
-  /** Resources in dependency order that are ready to emit. */
-  emit: Resource[];
-  /** Resources blocked on unresolved dependencies. */
-  blocked: Resource[];
-  /** Topologically sorted resource IDs. */
-  order: string[];
+//#region src/pipeline/resolve.d.ts
+/**
+ * RESOLVE phase: walk dependency edges and replace Pending markers
+ * with concrete values from observed state where available.
+ *
+ * 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.
+ */
+declare function resolve(state: PipelineState): PipelineState;
+//#endregion
+//#region src/pipeline/sequence.d.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.
+ */
+declare function sequence(state: PipelineState): PipelineState;
+//#endregion
+//#region src/pipeline/index.d.ts
+/**
+ * Input to the pipeline — provided by the handler or simulator.
+ */
+interface PipelineInput {
+  /** The constructed Composition instance. */
+  composition: Composition;
+  /** Observed composed resources from Crossplane (keyed by resource name). */
+  observedComposed: ReadonlyMap<string, Record<string, unknown>>;
+  /** Observed existing/required resources (keyed by refKey). */
+  observedRequired: ReadonlyMap<string, Record<string, unknown>>;
 }
 /**
- * Resolves resource dependencies and determines which resources can be
- * emitted in the current pass.
+ * Run the full rendering pipeline.
+ *
+ * Phases: hydrate → resolve → sequence → diagnose → emit
+ */
+declare function runPipeline(input: PipelineInput): PipelineState;
+//#endregion
+//#region src/run.d.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
  *
- * 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.
+ * The runtime never needs to access framework internals — everything it needs
+ * is in the returned plain-data structure.
  */
-declare function resolveSequencing(resources: ReadonlyMap<string, Resource>, graph: DependencyGraph, observedResources: ReadonlyMap<string, KubernetesResource>): SequencingResult;
+declare function runComposition<TSpec, TStatus, TContext extends object>(CompositionClass: new () => Composition<TSpec, TStatus, TContext>, input: CompositionInput): CompositionResult;
 //#endregion
-export { type AnyFields, Composition, Construct, DependencyCollector, type DependencyEdge, DependencyGraph, type ExistingResourceRef, IS_TRACKED, type KubernetesResource, type ResolutionResult, Resource, type ResourceOptions, type ResourceProps, type ResourceRef, type SequencingResult, TRACKING_META, type TrackingMeta, UNRESOLVED, computeRefKey, createTrackedProxy, getReadyCondition, getTrackingMeta, isResourceReady, isTracked, resolveSequencing };
+export { Composition, type CompositionContext, type CompositionInput, type CompositionModule, type CompositionResult, Construct, DEFAULT_CHECKS, type DependencyEdge, DependencyGraph, type DesiredResource, type Diagnostic, type DiagnosticReport, EdgeCollector, type EmittedResource, type ExternalResourceRef, type ExternalResourceRequest, type KubernetesResource, Pending, type PipelineContextAccessor, type PipelineInput, type PipelineState, type ReadProxyMeta, type ReadyCheck, type ReadyCheckFn, Resource, type ResourceClassification, type ResourceConfig, type ResourceProps, type ResourceRef, type XplaneLogger, type XrProxy, 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.d.mts.map