alchemy 2.0.0-beta.65 → 2.0.0-beta.67

package/src/Provider.ts

@@ -10,6 +10,7 @@ import type { Diff } from "./Diff.ts";
 import type { Input } from "./Input.ts";
 import type { InstanceId } from "./InstanceId.ts";
 import type { Platform } from "./Platform.ts";
+import type { ProviderMode } from "./ProviderMode.ts";
 import type {
   ResourceBinding,
   ResourceClass,
@@ -111,6 +112,27 @@ export interface ProviderService<
    * 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>> };
   /**
    * Account-wide teardown (`alchemy unsafe nuke`) behaviour. Providers whose
    * resources can't meaningfully be deleted opt out here so nuke doesn't
@@ -313,6 +335,64 @@ export interface ProviderService<
   }): 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,
@@ -327,7 +407,7 @@ export const effect = <
 >(
   cls: ResourceClassLike<R> | Platform<R, any, any, any, any>,
   eff: Effect.Effect<
-    ProviderService<
+    ProviderServiceInput<
       R,
       ReadReq,
       DiffReq,
@@ -354,7 +434,7 @@ export const effect = <
     Provider(cls.Type),
     Effect.map(eff, (service) => ({
       aliases: "Aliases" in cls ? cls.Aliases : undefined,
-      ...service,
+      ...withDefaultList(service),
     })),
   ) as any;
 
@@ -370,7 +450,7 @@ export const succeed = <
   ListReq = never,
 >(
   cls: ResourceClass<R> | Platform<R, any, any, any, any>,
-  service: ProviderService<
+  service: ProviderServiceInput<
     R,
     ReadReq,
     DiffReq,
@@ -392,7 +472,7 @@ export const succeed = <
   // @ts-expect-error
   Layer.succeed(Provider(cls.Type), {
     aliases: "Aliases" in cls ? cls.Aliases : undefined,
-    ...service,
+    ...withDefaultList(service),
   });
 
 export interface ProviderCollectionLike {
@@ -495,12 +575,33 @@ const isProviderService = (value: unknown): value is ProviderService =>
   "delete" in value &&
   typeof (value as ProviderService).delete === "function";
 
+/**
+ * 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. R2 buckets) 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);
+
 export const findProviderByType: {
   <R extends ResourceLike>(
     resourceType: R["Type"],
+    mode?: ProviderMode,
   ): Effect.Effect<ProviderService<R>>;
-} = ((type: string) =>
-  tryFindProviderByType(type).pipe(
+} = ((type: string, mode?: ProviderMode) =>
+  tryFindProviderByType(type, mode).pipe(
     Effect.flatMap(
       Option.match({
         onNone: () => Effect.die(`Provider not found for ${type}`),
@@ -518,9 +619,10 @@ export const findProviderByType: {
 export const findProvider: {
   <R extends ResourceLike>(
     resource: ResourceClassLike<R> | Platform<R, any, any, any, any>,
+    mode?: ProviderMode,
   ): Effect.Effect<ProviderService<R>>;
-} = (resource: { Type?: string; key?: string }) =>
-  findProviderByType((resource.Type ?? resource.key) as string) as any;
+} = (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
@@ -561,44 +663,58 @@ export const missingProviderError = (
 export const tryFindProviderByType: {
   <R extends ResourceLike>(
     resourceType: R["Type"],
+    mode?: ProviderMode,
   ): 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;
-  }
+} = Effect.fn(function* <R extends ResourceLike>(
+  resourceType: R["Type"],
+  mode?: ProviderMode,
+) {
+  // When a mode is requested, resolve the found service to that mode's
+  // variant (building it lazily if needed) before returning.
+  const found = yield* Effect.gen(function* () {
+    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);
+    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);
+    // 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);
       }
-    } else if (
-      isProviderService(value) &&
-      value.aliases?.includes(resourceType)
-    ) {
-      return Option.some(value);
     }
+    return Option.none();
+  });
+  if (Option.isNone(found)) {
+    return found;
   }
-  return Option.none();
+  return Option.some(
+    yield* providerForMode(found.value as ProviderService<R>, mode),
+  );
 }) as any;

package/src/ProviderMode.ts

@@ -0,0 +1,123 @@
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { AlchemyContext } from "./AlchemyContext.ts";
+
+/**
+ * The mode a resource's provider operates in.
+ *
+ * - `"live"`  — the provider converges real cloud state.
+ * - `"local"` — the provider emulates the resource on the developer's
+ *   machine (`alchemy dev`), typically as a long-running process managed
+ *   by the dev sidecar.
+ *
+ * The mode a resource was last reconciled with is persisted on its state
+ * row (`providerMode`). Switching a resource between modes is planned as a
+ * **replacement**: the new instance is created with the new mode's provider
+ * and the old instance is deleted with the provider of the mode that
+ * created it.
+ */
+export type ProviderMode = "live" | "local";
+
+/**
+ * ProviderModePolicy opts resources OUT of local emulation: when `true`,
+ * resources registered while it is in context resolve the **live**
+ * provider even during `alchemy dev`.
+ *
+ * Apply it with the {@link remote} combinator. During `alchemy deploy`
+ * everything is live anyway, so the policy only has an effect in dev.
+ *
+ * Tri-state `Context.Reference`: `undefined` (the default — no explicit
+ * decoration, inherit/run default), `true` (`remote()`), `false`
+ * (`remote(false)` — explicitly follow the run default again). The unset vs
+ * explicit distinction is load-bearing for conflict detection at
+ * registration (see `Resource.ts`).
+ */
+export const ProviderModePolicy = Context.Reference<boolean | undefined>(
+  "ProviderModePolicy",
+  { defaultValue: () => undefined },
+);
+
+/**
+ * The same resource (identified by FQN) was registered (`yield*`ed) from two
+ * places whose ambient {@link ProviderModePolicy} disagree — e.g. once inside
+ * `remote()` and once without it. Context-based decoration cannot decide which
+ * one wins, so the engine fails loudly instead of silently picking one.
+ *
+ * Fix: register the resource once and close over the returned value, or make
+ * both registration sites agree.
+ */
+export class ConflictingProviderModeError extends Data.TaggedError(
+  "ConflictingProviderModeError",
+)<{
+  message: string;
+  fqn: string;
+  /** The mode captured at the first registration site (undefined = default). */
+  existingMode: ProviderMode | undefined;
+  /** The explicit mode at the conflicting registration site. */
+  conflictingMode: ProviderMode | undefined;
+}> {}
+
+/**
+ * Run the wrapped resources **remotely (against the real cloud) even during
+ * `alchemy dev`** — the opt-out from local emulation. During `alchemy deploy`
+ * this is a no-op (everything is remote).
+ *
+ * Captured at registration time like `adopt()` / `retain()`, so it can be
+ * applied to a single resource or a whole scope:
+ *
+ * ```ts
+ * // This queue talks to real Cloudflare even in dev
+ * const queue = yield* Queue("Jobs", {}).pipe(Alchemy.remote());
+ *
+ * // Everything in this scope runs live in dev
+ * yield* Effect.gen(function* () {
+ *   const queue = yield* Queue("Jobs", {});
+ *   const consumer = yield* Consumer("JobsConsumer", { queue });
+ * }).pipe(Alchemy.remote());
+ * ```
+ *
+ * `remote(false)` (or an `Effect<boolean>` resolving to false) removes the
+ * pin — the resource follows the run default again.
+ *
+ * Providers with a single implementation are mode-agnostic and already run
+ * live in dev; `remote()` on them is a no-op.
+ */
+export const remote: {
+  (
+    enabled?: boolean,
+  ): <A, E, R = never>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, R>;
+  <R1 = never>(
+    enabled: Effect.Effect<boolean, never, R1>,
+  ): <A, E, R2 = never>(
+    effect: Effect.Effect<A, E, R2>,
+  ) => Effect.Effect<A, E, R1 | R2>;
+} = ((enabled: boolean | Effect.Effect<boolean, never, any> = true) =>
+  (eff: Effect.Effect<any, any, any>) =>
+    eff.pipe(
+      typeof enabled === "boolean"
+        ? Effect.provideService(ProviderModePolicy, enabled)
+        : Effect.provideServiceEffect(ProviderModePolicy, enabled),
+    )) as any;
+
+/**
+ * Resolve the run-level default provider mode:
+ *
+ * 1. An ambient {@link ProviderModePolicy} of `true` (e.g. `remote()` wrapped
+ *    around a whole program) forces `"live"`.
+ * 2. Otherwise `AlchemyContext.dev` decides: `dev: true` → `"local"`.
+ * 3. Without an AlchemyContext (bare engine tests), default to `"live"`.
+ */
+export const defaultProviderMode: Effect.Effect<ProviderMode> = Effect.gen(
+  function* () {
+    if (yield* ProviderModePolicy) return "live" as const;
+    const ctx = yield* Effect.serviceOption(AlchemyContext);
+    return Option.match(ctx, {
+      onNone: () => "live" as const,
+      onSome: (c) => (c.dev ? ("local" as const) : ("live" as const)),
+    });
+  },
+);

package/src/Resource.ts

@@ -9,6 +9,11 @@ import type { Input, InputProps } from "./Input.ts";
 import { CurrentNamespace, type NamespaceNode } from "./Namespace.ts";
 import * as Output from "./Output.ts";
 import { Provider } from "./Provider.ts";
+import {
+  ConflictingProviderModeError,
+  ProviderModePolicy,
+  type ProviderMode,
+} from "./ProviderMode.ts";
 import { ref as makeRef } from "./Ref.ts";
 import { RemovalPolicy } from "./RemovalPolicy.ts";
 import { Self } from "./Self.ts";
@@ -130,6 +135,13 @@ export interface ResourceLike<
    * resource-scoped override — the planner falls back to the stack/CLI default.
    */
   Adopt: boolean | undefined;
+  /**
+   * Per-resource provider mode captured from the ambient
+   * {@link ProviderModePolicy} at registration time. `"live"` when the
+   * resource was pinned via `.pipe(remote())` (opting out of local emulation
+   * during dev); `undefined` means the run default (`AlchemyContext.dev`).
+   */
+  Mode: ProviderMode | undefined;
   /** @internal phantom */
   Attributes: Attributes;
   /** @internal phantom */
@@ -265,8 +277,41 @@ export function Resource<R extends ResourceLike>(
       const namespace = yield* CurrentNamespace;
       const fqn = toFqn(namespace, id);
 
+      // `remote()` opts resources out of local emulation during dev. The
+      // captured Mode is either "live" (pinned) or undefined (run default).
+      // The Reference default is `undefined` — "no explicit decoration" —
+      // which is distinct from an explicit `remote(false)`.
+      const ambientPolicy = yield* ProviderModePolicy;
+      const ambientMode: ProviderMode | undefined = ambientPolicy
+        ? "live"
+        : undefined;
+
       const existing = stack.resources[fqn];
       if (existing) {
+        // A resource may be `yield*`ed from several places (idempotent
+        // registration). If a later site carries an *explicit* ambient
+        // ProviderModePolicy that disagrees with what the resource was
+        // registered with, the decorations are conflicting — fail loudly
+        // instead of silently picking one. A later site with NO ambient
+        // policy simply inherits the registered resource (the common
+        // "reference it from elsewhere" pattern).
+        if (ambientPolicy !== undefined && existing.Mode !== ambientMode) {
+          return yield* Effect.die(
+            new ConflictingProviderModeError({
+              message:
+                `Resource '${fqn}' was registered with provider mode ` +
+                `'${existing.Mode ?? "default"}' but is now being registered ` +
+                `with conflicting mode '${ambientMode ?? "default"}'. A ` +
+                "resource must resolve to a single provider mode: register " +
+                "it once and close over the returned value, or make both " +
+                "registration sites agree (e.g. wrap both in the same " +
+                "`remote()` scope).",
+              fqn,
+              existingMode: existing.Mode,
+              conflictingMode: ambientMode,
+            }),
+          );
+        }
         // // TODO(sam): check if props are different and die
         return existing;
       }
@@ -341,6 +386,7 @@ export function Resource<R extends ResourceLike>(
         Adopt: yield* Effect.serviceOption(AdoptPolicy).pipe(
           Effect.map(Option.getOrUndefined),
         ),
+        Mode: ambientMode,
         bind,
         toString(this: typeof target) {
           return `Resource<${this.Type}>(${this.LogicalId})`;

package/src/RuntimeContext.ts

@@ -28,6 +28,13 @@ export interface BaseRuntimeContext {
   shape?: () => Record<string, unknown>;
   /** additional services to provide to the plan  */
   planServices?: Layer.Layer<any>;
+  /**
+   * Telemetry exporter Layer registered during init via
+   * `Telemetry.layer(...)` / `Telemetry.layerOtlp(...)` (see Telemetry.ts).
+   * The runtime bridges build it into every event's request scope,
+   * overriding the env-driven default.
+   */
+  telemetry?: Layer.Layer<never, any, any>;
 }
 
 /**

package/src/Server/Process.ts

@@ -102,3 +102,36 @@ export const createHostRuntimeContext =
       })),
     } satisfies HostRuntimeContext;
   };
+
+/**
+ * Host runtime context for container platforms (`AWS.ECS.Task`,
+ * `AWS.ECS.Service`, `Docker.Service`): extends the shared process host
+ * context so an impl shape's `run` effect is registered as a one-shot runner
+ * (the container exits when it completes) and the HTTP server only boots when
+ * the impl actually declares a `fetch` handler.
+ */
+export const createContainerRuntimeContext =
+  (type: string) =>
+  (id: string): HostRuntimeContext => {
+    const base = createHostRuntimeContext(type)(id);
+    // Capture the host serve BEFORE Object.assign overwrites `base.serve`
+    // with the wrapper below — calling `base.serve` inside the wrapper would
+    // resolve to the wrapper itself (property lookup happens at call time)
+    // and recurse without bound the moment an impl declares `fetch`.
+    const serveBase = base.serve;
+    const serve: HostRuntimeContext["serve"] = (handler, options) =>
+      Effect.gen(function* () {
+        const shape = options?.shape;
+        const run = shape?.run;
+        if (Effect.isEffect(run)) {
+          yield* base.run(run as Effect.Effect<void, never, any>);
+        }
+        // Boot the HTTP server only for an impl that declared `fetch` — a
+        // pure one-shot `{ run }` program must exit when `run` completes
+        // rather than parking behind the 404 fallback server forever.
+        if (shape === undefined || shape.fetch !== undefined) {
+          yield* serveBase(handler, options);
+        }
+      }) as Effect.Effect<void, never, never>;
+    return Object.assign(base, { serve });
+  };

package/src/State/InMemoryState.ts

@@ -87,8 +87,10 @@ export const InMemoryService = (
         Effect.sync(() => {
           if (stage === undefined) {
             delete state[stack];
+            delete outputs[stack];
           } else {
             delete state[stack]?.[stage];
+            delete outputs[stack]?.[stage];
           }
         }),
       list: ({ stack, stage }: { stack: string; stage: string }) =>

package/src/State/ResourceState.ts

@@ -1,4 +1,5 @@
 import type { NamespaceNode } from "../Namespace.ts";
+import type { ProviderMode } from "../ProviderMode.ts";
 import type { RemovalPolicy } from "../RemovalPolicy.ts";
 import type { ResourceBinding } from "../Resource.ts";
 
@@ -56,6 +57,21 @@ interface BaseResourceState {
   attr?: Attr;
   /** The removal policy of the resource */
   removalPolicy?: RemovalPolicy["Service"];
+  /**
+   * The {@link ProviderMode} this resource was last reconciled with.
+   *
+   * Stamped by Apply on every commit for resources whose provider
+   * distinguishes modes (`ProviderLayer.dual`). Plan treats a mismatch
+   * between the persisted mode and the resolved desired mode as a
+   * **replacement**, and deletion always uses the provider variant of the
+   * mode that created the row.
+   *
+   * `undefined` means either a mode-agnostic provider (single
+   * implementation serves both dev and deploy) or a legacy row written
+   * before modes were persisted — both are treated as "whatever the
+   * current run's mode is" (no replacement churn).
+   */
+  providerMode?: ProviderMode;
 }
 
 export interface CreatingResourceState extends BaseResourceState {
@@ -74,6 +90,8 @@ export interface CreatedResourceState extends BaseResourceState {
 
 export interface UpdatingReourceState extends BaseResourceState {
   status: "updating";
+  /** Persisted until the first post-adoption reconcile succeeds. */
+  adopting?: true;
   /** The new resource properties that are being (or have been) applied. */
   props: Props;
   old: {

package/src/Sync.ts

@@ -185,7 +185,12 @@ export const sync = (
         );
       }
 
-      const provider = yield* findProviderByType(resourceType);
+      // Observe with the provider variant of the mode that created the row —
+      // a local dev worker's state must be read by the local provider.
+      const provider = yield* findProviderByType(
+        resourceType,
+        old.providerMode,
+      );
       if (!provider.read) {
         return yield* skip(
           `provider '${resourceType}' does not implement read`,
@@ -436,7 +441,12 @@ export const plan = (stack: {
         fqn,
       });
       if (!persisted || isActionState(persisted)) continue;
-      const provider = yield* findProviderByType(persisted.resourceType);
+      // Repair the row with the provider mode that created it (sync never
+      // switches modes — a local ⇄ live switch is a plan-time replacement).
+      const provider = yield* findProviderByType(
+        persisted.resourceType,
+        persisted.providerMode,
+      );
       const action =
         r.action === "drifted"
           ? ("update" as const)
@@ -448,6 +458,7 @@ export const plan = (stack: {
         props: persisted.props,
         state: persisted,
         provider,
+        mode: persisted.providerMode,
         // Synthetic ResourceLike reconstructed from persisted state, the
         // same way Plan.make builds its deletion nodes.
         resource: {
@@ -461,6 +472,7 @@ export const plan = (stack: {
           Provider: Provider(persisted.resourceType),
           RemovalPolicy: persisted.removalPolicy,
           Adopt: undefined,
+          Mode: persisted.providerMode,
           RuntimeContext: undefined!,
           Providers: undefined,
         } as ResourceLike,