sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Provider.ts

import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import type * as Stream from "effect/Stream";
import type { Unresolved } from "./AdoptPolicy.ts";
import type { Artifacts } from "./Artifacts.ts";
import type { Diff } from "./Diff.ts";
import type { Input } from "./Input.ts";
import type { Platform } from "./Platform.ts";
import { defaultProviderMode, type ProviderMode } from "./ProviderMode.ts";
import type { ScopedPlanStatusSession } from "./Report.ts";
import type {
  ResourceBinding,
  ResourceClass,
  ResourceClassLike,
  ResourceLike,
} from "./Resource.ts";
import type { ResourceContext } from "./ResourceContext.ts";
import type { State } from "./State/State.ts";

export interface Provider<R extends ResourceLike = ResourceLike> extends Effect.Effect<
  ProviderService<R>,
  never,
  Provider<R>
> {
  asEffect: () => Effect.Effect<ProviderService<R>, never, Provider<R>>;
  [Symbol.iterator]: () => Effect.EffectIterator<Provider<R>>;
  of: <
    ReadReq = never,
    DiffReq = never,
    PrecreateReq = never,
    ReconcileReq = never,
    DeleteReq = never,
    TailReq = never,
    LogsReq = never,
    ListReq = never,
  >(
    service: Omit<
      ProviderService<
        R,
        ReadReq,
        DiffReq,
        PrecreateReq,
        ReconcileReq,
        DeleteReq,
        TailReq,
        LogsReq,
        ListReq
      >,
      "Type"
    >,
  ) => ProviderService<
    R,
    ReadReq,
    DiffReq,
    PrecreateReq,
    ReconcileReq,
    DeleteReq,
    TailReq,
    LogsReq,
    ListReq
  >;
}

// Supplied by the engine to every lifecycle operation (the stack's `state`
// layer is merged into the context lifecycle ops run under), so they are not
// requirements of the provider layer itself.
type LifecycleServices = ResourceContext | Artifacts | State;

export const Provider = <R extends ResourceLike>(type: R["Type"]): Provider<R> =>
  Context.Service<Provider<R>, ProviderService<R>>()(type) as any;

type BindingData<Res extends ResourceLike> = [Res] extends [{ Binding: infer B }]
  ? ResourceBinding<B>[]
  : any[];

type Props<Res extends ResourceLike> = keyof Res["Props"] extends never
  ? Res["Props"] | undefined
  : Res["Props"];

export interface LogLine {
  timestamp: Date;
  message: string;
}

export interface LogsInput {
  since?: Date;
  limit?: number;
}

export interface ProviderService<
  Res extends ResourceLike = ResourceLike,
  ReadReq = never,
  DiffReq = never,
  PrecreateReq = never,
  ReconcileReq = never,
  DeleteReq = never,
  TailReq = never,
  LogsReq = never,
  ListReq = never,
> {
  /**
   * The version of the provider.
   *
   * @default 0
   */
  version?: number;
  /**
   * Legacy type names this provider also answers to. Copied from the
   * resource class's `aliases` option by {@link succeed}/{@link effect} so
   * state persisted under a pre-rename type (e.g. `"Cloudflare.Queue"`
   * before the `"Cloudflare.Queues.Queue"` rename) still resolves to this
   * provider via {@link tryFindProviderByType}.
   */
  aliases?: readonly string[];
  /**
   * The {@link ProviderMode} this service operates in.
   *
   * Set by `ProviderLayer.dual` registrations: the delegating service
   * registered in context carries the run's default mode, and each built
   * variant carries its concrete mode. Mode-agnostic providers (plain
   * {@link succeed}/{@link effect} registrations) leave it `undefined` —
   * their resources never persist a mode and never replace on a mode
   * switch.
   */
  mode?: ProviderMode;
  /**
   * Lazily-built mode variants, present only for `ProviderLayer.dual`
   * registrations. Each effect builds (once, memoized, into the stack's
   * layer scope) the provider service for that mode — including any
   * mode-specific dependency layers — and returns it. The engine resolves
   * a concrete variant via {@link findProviderByType} with a mode so that
   * e.g. a local-mode state row is always deleted by the local provider,
   * even during a live deploy (and vice versa).
   */
  modes?: { readonly [M in ProviderMode]: Effect.Effect<ProviderService<Res>> };
  /**
   * Data-plane override context for this provider's **local** mode: a layer
   * of cloud environment services (endpoint, credentials, region,
   * environment) that points data-plane API calls at the local emulator —
   * the same override the local lifecycle variant runs under (e.g. AWS's
   * `flociServices()`).
   *
   * Set by `ProviderLayer.dual` registrations that pass `dataPlane`.
   * Consumed by `Binding.Service`'s client wrapper (via
   * {@link resolveLocalDataPlane}) so deploy-time binding invocations —
   * inside an `Action` body or a plan-time `execute` — target whatever
   * data plane the bound resource actually lives on: a local-mode resource
   * routes to the emulator while an `Alchemy.remote()` resource keeps
   * hitting the real cloud. Pass a module-memoized layer reference.
   */
  localDataPlane?: () => Layer.Layer<any, any, never>;
  /**
   * Data-plane override context for this provider's **live** mode: the
   * cloud environment captured at provider registration (credentials,
   * region, endpoint). In an `alchemy dev` run the ambient environment IS
   * the emulator, so an unwrapped live client would hit floci. Stamp this
   * so `Alchemy.remote()` binding calls are provided the live chain
   * closest, the inverse of {@link localDataPlane}.
   */
  liveDataPlane?: () => Layer.Layer<any, any, never>;
  /**
   * Account-wide teardown (`alchemy unsafe nuke`) behaviour. Providers whose
   * resources can't meaningfully be deleted opt out here so nuke doesn't
   * report an endless "deleted but still there" loop. `read`/import are
   * unaffected.
   */
  nuke?: {
    /**
     * The resource is an account/zone **singleton setting** — always-present
     * configuration (e.g. Bot Management, Email Routing, a zone's SSL
     * settings) whose `delete` only *resets* it to defaults rather than
     * removing a discrete resource. Skipped by nuke, since `list` always
     * re-enumerates it and "deleting" it just resets config the operator
     * never created.
     */
    singleton?: boolean;
    /**
     * The resource is skipped by nuke for any other reason — typically because
     * it can never actually be deleted (no delete API, like RealtimeKit Apps;
     * or a registration that is never released, like Registrar Domains). Unlike
     * {@link singleton}, these are ordinary multi-instance resources.
     */
    skip?: boolean;
    /**
     * Provider IDs (picomatch globs, e.g. `"AWS.IAM.Role"` or `"AWS.EC2.*"`)
     * whose resources this type's **cloud-side teardown** consumes — they
     * must still exist while this type is deleting. `alchemy unsafe nuke`
     * topologically orders deletion so every resource of this type is fully
     * gone before any matching type starts deleting; if this type's deletes
     * fail, the matching types are held back rather than deleted out from
     * under an in-flight teardown.
     *
     * Example: SageMaker HyperPod deletes node ENIs by assuming the
     * instance group's execution role — deleting the role (or the VPC)
     * mid-teardown wedges the cluster in `Deleting` permanently, so
     * `AWS.SageMaker.Cluster` declares `dependsOn: ["AWS.IAM.Role", ...]`.
     *
     * The constraint only takes effect when resources of this type are
     * actually present in the nuke target set; declaration cycles collapse
     * into a single concurrent wave (with a logged warning) instead of
     * failing.
     */
    dependsOn?: readonly string[];
  };
  /**
   * Enumerates every existing resource of this type in the ambient scope
   * (account / region / zone resolved from the environment services), and
   * returns the full {@link ProviderService} `Attributes` shape for each —
   * the same shape {@link read} produces, so each item is directly usable
   * with {@link delete} without a follow-up read.
   *
   * This powers account-wide operations such as `alchemy nuke`, which lists
   * everything and then deletes it. It takes no input and must paginate
   * exhaustively so the returned array is complete.
   *
   * Resources with no native enumeration API (account/zone singletons,
   * existence-only resources, sub-resources keyed entirely by a parent)
   * should return an empty array rather than throwing.
   */
  list(): Effect.Effect<Res["Attributes"][], any, ListReq>;
  /**
   * Returns a stream of log lines for a deployed resource.
   * Used by `alchemy logs --tail` to stream real-time logs.
   */
  tail?(input: {
    id: string;
    /**
     * Fully-qualified name (namespace path + logical id, see `./FQN.ts`) —
     * globally unique, so providers can stamp ownership metadata on cloud objects.
     */
    fqn: string;
    instanceId: string;
    props: Props<Res>;
    output: Res["Attributes"];
  }): Stream.Stream<LogLine, any, TailReq>;
  /**
   * Queries historical logs for a deployed resource.
   * Used by `alchemy logs` to fetch past log entries.
   */
  logs?(input: {
    id: string;
    /**
     * Fully-qualified name (namespace path + logical id, see `./FQN.ts`) —
     * globally unique, so providers can stamp ownership metadata on cloud objects.
     */
    fqn: string;
    instanceId: string;
    props: Props<Res>;
    output: Res["Attributes"];
    options: LogsInput;
  }): Effect.Effect<LogLine[], any, LogsReq>;
  // watch();
  // replace(): Effect.Effect<void, never, never>;
  // different interface that is persistent, watching, reloads
  // run?() {}
  // branch?() {}
  read?(input: {
    id: string;
    /**
     * Fully-qualified name (namespace path + logical id, see `./FQN.ts`) —
     * globally unique, so providers can stamp ownership metadata on cloud objects.
     */
    fqn: string;
    instanceId: string;
    olds: Props<Res>;
    // what is the ARN?
    output: Res["Attributes"] | undefined; // current state -> synced state
    /**
     * When the engine checks the identity a replacement will claim, the
     * attributes of the generation it replaces. A provider that can't tell
     * our resource from a foreign one by ownership metadata alone (e.g. an
     * explicitly named resource without tags) reports a resource that is
     * this previous generation as owned, not `Unowned`.
     */
    previous?: Res["Attributes"];
  }): Effect.Effect<Res["Attributes"] | undefined, any, ReadReq>;
  /**
   * Properties that are always stable across any update.
   */
  stables?: Extract<keyof Res["Attributes"], string>[];
  diff?(input: {
    id: string;
    /**
     * Fully-qualified name (namespace path + logical id, see `./FQN.ts`) —
     * globally unique, so providers can stamp ownership metadata on cloud objects.
     */
    fqn: string;
    instanceId: string;
    olds: Props<Res>;
    // Note: we do not resolve (Res["Props"]) here because diff runs during plan
    // -> we need a way for the diff handlers to work with Outputs
    news: Input<Props<Res>>;
    oldBindings: BindingData<Res>;
    newBindings: Input<BindingData<Res>>;
    output: Res["Attributes"] | undefined;
  }): Effect.Effect<Diff | void, any, DiffReq>;
  // dev?:() => Effect.Effect<void, any, DevReq>;
  /**
   * Reports what exists at the physical resource {@link precreate} would
   * claim, without writing. A dependency cycle precreates on raw, possibly unresolved
   * props, before `read` can run, so the engine asks `observe` first and
   * refuses a foreign resource before `precreate` touches it, unless adoption
   * is allowed (`--adopt` / `adopt(true)`).
   *
   * It receives the same raw props as `precreate` and must derive the same
   * identity. Report what exists there the way {@link read} does: `undefined`
   * when nothing does, its attributes when it belongs to this
   * stack/stage/logical-id, and `Unowned(attrs)` otherwise. Return
   * `Unresolved` when the identity depends on props that have not resolved
   * yet: the engine then checks the resolved identity before `reconcile`.
   *
   * The attributes may be partial. During a replacement, `previous` holds
   * the attributes of the generation being replaced: report a resource that
   * is that generation as owned. The engine compares no attributes itself.
   *
   * Without {@link read}, the engine also calls `observe` with resolved props
   * to check an identity before `reconcile` claims it.
   *
   * Opt-in: implement it whenever `precreate` can write to a resource that
   * already exists. Without it, such a cycle precreates unchecked.
   */
  observe?(input: {
    id: string;
    /**
     * Fully-qualified name (namespace path + logical id, see `./FQN.ts`) —
     * globally unique, so providers can stamp ownership metadata on cloud objects.
     */
    fqn: string;
    news: Props<Res>;
    instanceId: string;
    /** During a replacement, the attributes of the generation being replaced. */
    previous?: Res["Attributes"];
  }): Effect.Effect<Partial<Res["Attributes"]> | Unresolved | undefined, any, PrecreateReq>;
  precreate?(input: {
    id: string;
    /**
     * Fully-qualified name (namespace path + logical id, see `./FQN.ts`) —
     * globally unique, so providers can stamp ownership metadata on cloud objects.
     */
    fqn: string;
    news: Props<Res>;
    instanceId: string;
    session: ScopedPlanStatusSession;
    bindings: BindingData<Res>;
  }): Effect.Effect<Res["Attributes"], any, PrecreateReq>;
  /**
   * Reconciles the desired state of a Resource with the live cloud state.
   *
   * This unified lifecycle method replaces the previous `create` and `update`
   * pair. The engine dispatches `reconcile` for both intents — initial
   * provisioning and subsequent updates — and providers must defensively
   * handle every combination of inputs:
   *
   * - `output === undefined` and `olds === undefined` — first reconciliation
   *   for this logical resource. Treat as a create. Must remain idempotent
   *   because state persistence can fail after a successful API call.
   * - `output !== undefined` and `olds === undefined` — engine adopted an
   *   existing cloud resource (via {@link read}). The provider has never
   *   written this resource through Alchemy before, so cannot rely on prior
   *   props as a baseline.
   * - `output !== undefined` and `olds !== undefined` — standard update
   *   path with a known prior state.
   *
   * Ownership has already been verified upstream — by the time `reconcile`
   * runs, the engine has confirmed (via `read` returning a non-`Unowned`
   * value, or by writing the resource itself) that mutation is safe.
   */
  reconcile(input: {
    id: string;
    /**
     * Fully-qualified name (namespace path + logical id, see `./FQN.ts`) —
     * globally unique, so providers can stamp ownership metadata on cloud objects.
     */
    fqn: string;
    instanceId: string;
    news: Props<Res>;
    olds: Props<Res> | undefined;
    output: Res["Attributes"] | undefined;
    session: ScopedPlanStatusSession;
    bindings: BindingData<Res>;
  }): Effect.Effect<Res["Attributes"], any, ReconcileReq>;
  /** Idempotent; fail with {@link DeleteInProgress} when the cloud cannot finish the delete yet. */
  delete(input: {
    id: string;
    /**
     * Fully-qualified name (namespace path + logical id, see `./FQN.ts`) —
     * globally unique, so providers can stamp ownership metadata on cloud objects.
     */
    fqn: string;
    instanceId: string;
    olds: Props<Res>;
    output: Res["Attributes"];
    session: ScopedPlanStatusSession;
    bindings: BindingData<Res>;
    /**
     * Set by account-wide teardown (`alchemy unsafe nuke`) to signal the
     * operator explicitly requested destructive deletion. Nuke enumerates
     * resources straight from the cloud, so `olds` carries Attributes rather
     * than the originally-deployed Props — destructive prerequisites that a
     * normal destroy gates behind a prop (e.g. emptying a non-empty S3
     * bucket behind `forceDestroy`) may be performed when this is set.
     * Normal engine destroys never set it.
     */
    force?: boolean;
  }): Effect.Effect<void, any, DeleteReq>;
}

/**
 * The provider shape accepted by {@link effect} / {@link succeed}: identical
 * to {@link ProviderService} except `list` is **optional**. Providers with no
 * native enumeration API (local/dev providers, account singletons,
 * sub-resources keyed entirely by a parent) simply omit it and get a safe
 * `() => Effect.succeed([])` default.
 *
 * Making `list` optional at the constructor (rather than on
 * {@link ProviderService} itself) keeps the engine's contract intact — every
 * registered provider still has a callable `list` — while removing the
 * type-inference trap where a missing required member silently defaults all
 * `*Req` type params to `never` and produces baffling `R is not assignable
 * to never` cascades at every other property.
 */
export type ProviderServiceInput<
  Res extends ResourceLike = ResourceLike,
  ReadReq = never,
  DiffReq = never,
  PrecreateReq = never,
  ReconcileReq = never,
  DeleteReq = never,
  TailReq = never,
  LogsReq = never,
  ListReq = never,
> = Omit<
  ProviderService<
    Res,
    ReadReq,
    DiffReq,
    PrecreateReq,
    ReconcileReq,
    DeleteReq,
    TailReq,
    LogsReq,
    ListReq
  >,
  "list"
> &
  Partial<
    Pick<
      ProviderService<
        Res,
        ReadReq,
        DiffReq,
        PrecreateReq,
        ReconcileReq,
        DeleteReq,
        TailReq,
        LogsReq,
        ListReq
      >,
      "list"
    >
  >;

const withDefaultList = <S extends { list?: unknown }>(service: S): S =>
  service.list ? service : { ...service, list: () => Effect.succeed([]) };

export const effect = <
  R extends ResourceLike,
  Req = never,
  ReadReq = never,
  DiffReq = never,
  PrecreateReq = never,
  ReconcileReq = never,
  DeleteReq = never,
  TailReq = never,
  LogsReq = never,
  ListReq = never,
>(
  cls: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
  eff: Effect.Effect<
    ProviderServiceInput<
      R,
      ReadReq,
      DiffReq,
      PrecreateReq,
      ReconcileReq,
      DeleteReq,
      TailReq,
      LogsReq,
      ListReq
    >,
    never,
    Req
  >,
): Layer.Layer<
  Provider<R>,
  never,
  Exclude<
    Req | ReadReq | DiffReq | PrecreateReq | ReconcileReq | DeleteReq | ListReq,
    LifecycleServices
  >
> =>
  Layer.effect(
    // @ts-expect-error
    Provider(cls.Type),
    Effect.map(eff, (service) => ({
      aliases: "Aliases" in cls ? cls.Aliases : undefined,
      ...withDefaultList(service),
    })),
  ) as any;

export const succeed = <
  R extends ResourceLike,
  ReadReq = never,
  DiffReq = never,
  PrecreateReq = never,
  ReconcileReq = never,
  DeleteReq = never,
  TailReq = never,
  LogsReq = never,
  ListReq = never,
>(
  cls: ResourceClass<R> | Platform<R, any, any, any, any, any>,
  service: ProviderServiceInput<
    R,
    ReadReq,
    DiffReq,
    PrecreateReq,
    ReconcileReq,
    DeleteReq,
    TailReq,
    LogsReq,
    ListReq
  >,
): Layer.Layer<
  Provider<R>,
  never,
  Exclude<ReadReq | DiffReq | PrecreateReq | ReconcileReq | DeleteReq | ListReq, LifecycleServices>
> =>
  // @ts-expect-error
  Layer.succeed(Provider(cls.Type), {
    aliases: "Aliases" in cls ? cls.Aliases : undefined,
    ...withDefaultList(service),
  });

export interface ProviderCollectionLike {
  kind: "ProviderCollection";
}

export interface ProviderCollectionShape<Identifier extends string>
  extends
    Context.ServiceClass.Shape<Identifier, ProviderCollectionService>,
    ProviderCollectionLike {}

export interface ProviderCollection<Self, Identifier extends string>
  extends Context.Service<Self, ProviderCollectionService>, ProviderCollectionLike {
  readonly key: Identifier;
  new (_: never): ProviderCollectionShape<Identifier>;
}

export const ProviderCollection =
  <Self>() =>
  <const ProviderId extends string>(id: ProviderId) =>
    Context.Service<Self, ProviderCollectionService>()(id) as ProviderCollection<Self, ProviderId>;

export interface ProviderCollectionService {
  kind: "ProviderCollection";
  get<Resource extends ResourceLike>(service: string): ProviderService<Resource> | undefined;
  /**
   * Every provider in this collection keyed by its resource type
   * (e.g. `"Cloudflare.Worker"`). Used by account-wide operations such
   * as `alchemy unsafe nuke` to enumerate and filter providers — the
   * collection's closure-captured map would otherwise be unreachable.
   */
  readonly providers: Record<string, ProviderService>;
}

export const collection = <
  R extends ResourceClassLike<any> | Platform<any, any, any, any, any, any>,
>(
  resources: R[],
): Effect.Effect<
  ProviderCollectionService,
  never,
  R extends ResourceClass<infer R> | Platform<infer R, any, any, any, any, any>
    ? Provider<R>
    : never
> =>
  Effect.gen(function* () {
    const context = yield* Effect.context();

    const providers = Object.fromEntries(
      yield* Effect.forEach(
        resources,
        (resource) =>
          "Provider" in resource
            ? resource.Provider.pipe(Effect.map((provider) => [resource.Type, provider] as const))
            : Effect.succeed([
                (resource as { key: string }).key,
                context.mapUnsafe.get((resource as { key: string }).key),
              ] as const),
        { concurrency: "unbounded" },
      ),
    );

    return {
      kind: "ProviderCollection" as const,
      get: (service: string) => providers[service],
      providers,
    };
  }) as any;

export const isProviderCollectionService = (value: unknown): value is ProviderCollectionService =>
  Predicate.isObject(value) &&
  Predicate.hasProperty(value, "kind") &&
  value.kind === "ProviderCollection";

/**
 * Structural check for a {@link ProviderService} living in the Effect
 * context. Providers are keyed by their canonical resource type; when
 * searching for a legacy alias, the tag key won't match, so lookup has to
 * recognize provider services by shape.
 */
export const isProviderService = (value: unknown): value is ProviderService =>
  Predicate.isObject(value) &&
  Predicate.hasProperty(value, "reconcile") &&
  Predicate.isFunction(value.reconcile) &&
  Predicate.hasProperty(value, "delete") &&
  Predicate.isFunction(value.delete);

/**
 * Resolve the concrete service for `mode` from a provider found in context.
 *
 * - `mode === undefined` → the service as registered (for dual
 *   registrations that is the delegating service for the run's default
 *   mode).
 * - `mode` given and the provider carries {@link ProviderService.modes} →
 *   the (lazily built, memoized) variant for that mode.
 * - `mode` given but the provider is mode-agnostic → the service itself:
 *   a single implementation satisfies every mode (hybrid), which is what
 *   lets live-only resources (e.g. DNS records) participate in dev runs.
 */
export const providerForMode = <R extends ResourceLike>(
  service: ProviderService<R>,
  mode: ProviderMode | undefined,
): Effect.Effect<ProviderService<R>> =>
  mode !== undefined && service.modes !== undefined ? service.modes[mode] : Effect.succeed(service);

/**
 * Why a resource's deploy-time binding clients target the data plane they
 * do — see {@link describeDataPlane}.
 *
 * - `local` — the resource runs on its provider's local emulator; `layer`
 *   is the override to provide closest around every client call.
 * - `live` — the resource targets the real cloud: either pinned there
 *   (`Alchemy.remote()`) or the run is a plain deploy. `layer` is the
 *   registration-captured live environment, provided closest around every
 *   client call so a `remote()` resource still hits the real cloud when the
 *   ambient environment is the emulator.
 * - `undeclared` — the resource resolves to local mode, but its provider
 *   is a dual registration without a {@link ProviderService.localDataPlane}
 *   (a process-hosted local variant with no API to route to, or a missing
 *   `dataPlane` on a hand-written `ProviderLayer.dual`). Clients fall back
 *   to the real cloud — reported by name so the two are never confused.
 * - `agnostic` — the provider is mode-agnostic (plain registration); its
 *   resources live on the real cloud even in dev.
 * - `unregistered` — no provider in context (bare runtime, unit tests).
 */
export type DataPlaneResolution =
  | { readonly kind: "local"; readonly layer: Layer.Layer<any, any, never> }
  | {
      readonly kind: "live";
      readonly layer?: Layer.Layer<any, any, never> | undefined;
    }
  | { readonly kind: "undeclared"; readonly providerType: string }
  | { readonly kind: "agnostic" }
  | { readonly kind: "unregistered" };

/**
 * Resolve where a resource's deploy-time binding clients should be routed:
 * its registration-captured {@link ResourceLike.Mode} (`Alchemy.remote()`
 * → `"live"`) or the run default (`alchemy dev` → `"local"`) — the same
 * resolution `Plan.make` applies to lifecycle operations — combined with
 * whether the provider registered a local data plane at all.
 */
export const describeDataPlane = (resource: {
  readonly Type: string;
  readonly Mode?: ProviderMode | undefined;
}): Effect.Effect<DataPlaneResolution> =>
  Effect.gen(function* () {
    const found = yield* tryFindProviderRegistrationByType(resource.Type);
    if (Option.isNone(found)) return { kind: "unregistered" as const };
    const provider = found.value;
    if (provider.modes === undefined) return { kind: "agnostic" as const };
    const mode = resource.Mode ?? (yield* defaultProviderMode);
    if (mode !== "local") {
      const layer = provider.liveDataPlane?.();
      return layer !== undefined ? { kind: "live" as const, layer } : { kind: "live" as const };
    }
    if (provider.localDataPlane === undefined) {
      return { kind: "undeclared" as const, providerType: resource.Type };
    }
    return { kind: "local" as const, layer: provider.localDataPlane() };
  });

/**
 * The data-plane override layer for a resource, or `undefined` when its
 * clients target the real cloud for any reason (see
 * {@link describeDataPlane} for which).
 */
export const resolveLocalDataPlane = (resource: {
  readonly Type: string;
  readonly Mode?: ProviderMode | undefined;
}): Effect.Effect<Layer.Layer<any, any, never> | undefined> =>
  describeDataPlane(resource).pipe(
    Effect.map((plane) => (plane.kind === "local" ? plane.layer : undefined)),
  );

export const findProviderByType: {
  <R extends ResourceLike>(
    resourceType: R["Type"],
    mode?: ProviderMode,
  ): Effect.Effect<ProviderService<R>>;
} = ((type: string, mode?: ProviderMode) =>
  tryFindProviderByType(type, mode).pipe(
    Effect.flatMap(
      Option.match({
        onNone: () => Effect.die(`Provider not found for ${type}`),
        onSome: (provider) => Effect.succeed(provider),
      }),
    ),
  )) as any;

/**
 * Resolve the concrete provider for the requested or current run mode.
 * Typed provider lookup by resource class (or {@link Platform}) value. Infers
 * `R` from the class so `provider.list()` / `provider.read(...)` return the
 * resource's `Attributes` shape — prefer this over {@link findProviderByType},
 * which only takes the type string.
 */
export const findProvider: {
  <R extends ResourceLike>(
    resource: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
    mode?: ProviderMode,
  ): Effect.Effect<ProviderService<R>>;
} = (resource: { Type?: string; key?: string }, mode?: ProviderMode) =>
  findProviderByType((resource.Type ?? resource.key) as string, mode) as any;

/**
 * A persisted state row references a resource type with no registered
 * provider — the type was removed from the program (or renamed without an
 * alias) while its state row still exists ("zombie" row).
 *
 * This is FATAL at plan time: the program and state fundamentally disagree,
 * and without the provider the row's physical resource cannot be deleted
 * anyway, so proceeding would only strand it silently. The plan dies with
 * this error; nothing is deployed or destroyed until the provider is
 * re-registered (or aliased), or the state row is cleared manually.
 */
export class MissingProviderError extends Data.TaggedError("MissingProviderError")<{
  message: string;
  resourceType: string;
  fqn: string;
}> {}

/** Build the fatal plan-time error for a zombie state row. */
export const missingProviderError = (resourceType: string, fqn: string): MissingProviderError =>
  new MissingProviderError({
    message:
      `No provider is registered for resource type '${resourceType}' ` +
      `(state row '${fqn}'). The type was removed from the program or ` +
      "renamed without an alias. Re-register the provider (or add the " +
      "old name to the resource's `aliases`) so this row can be " +
      "destroyed, or clear the state row manually if the physical " +
      "resource is already gone.",
    resourceType,
    fqn,
  });

/** A started delete the cloud cannot finish yet: a replacement's old generation is retried next apply, any other delete fails. */
export class DeleteInProgress extends Data.TaggedError("DeleteInProgress")<{
  message: string;
}> {}

/** Resolve a concrete provider, using the current run's mode when omitted. */
export const tryFindProviderByType = <R extends ResourceLike>(
  resourceType: R["Type"],
  mode?: ProviderMode,
): Effect.Effect<Option.Option<ProviderService<R>>> =>
  Effect.gen(function* () {
    const found = yield* tryFindProviderRegistrationByType<R>(resourceType);
    if (Option.isNone(found)) return found;
    return Option.some(yield* providerForMode(found.value, mode ?? (yield* defaultProviderMode)));
  });

/** Inspect registration metadata without constructing either provider variant. */
export const tryFindProviderRegistrationByType: {
  <R extends ResourceLike>(
    resourceType: R["Type"],
  ): Effect.Effect<Option.Option<ProviderService<R>>>;
} = Effect.fn(function* <R extends ResourceLike>(resourceType: R["Type"]) {
  const Tag = Provider<R>(resourceType) as unknown as Context.Service<Provider<R>, any>;
  const direct = yield* Effect.serviceOption(Tag);
  if (Option.isSome(direct)) {
    return direct;
  }

  const context = yield* Effect.context<never>();
  for (const value of context.mapUnsafe.values()) {
    if (isProviderCollectionService(value)) {
      const provider = value.get(resourceType);
      if (provider) {
        return Option.some(provider);
      }
    }
  }

  // State persisted before a type rename carries the legacy name, so no
  // provider is keyed under it. Fall back to a provider that declares the
  // name in its `aliases` — scanning both bare Provider layers and the
  // members of every ProviderCollection.
  for (const value of context.mapUnsafe.values()) {
    if (isProviderCollectionService(value)) {
      for (const provider of Object.values(value.providers)) {
        if (provider.aliases?.includes(resourceType)) {
          return Option.some(provider);
        }
      }
    } else if (isProviderService(value) && value.aliases?.includes(resourceType)) {
      return Option.some(value);
    }
  }
  return Option.none();
}) as any;