alchemy 2.0.0-beta.61 → 2.0.0-beta.63

package/src/Platform.ts

@@ -9,13 +9,12 @@ import * as Effectable from "effect/Effectable";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Redacted from "effect/Redacted";
-import type { Scope } from "effect/Scope";
+import { Scope } from "effect/Scope";
 import type * as Stream from "effect/Stream";
 import type { HttpClient } from "effect/unstable/http/HttpClient";
 import type { HttpServerRequest } from "effect/unstable/http/HttpServerRequest";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
 import type { Dependencies } from "./Dependencies.ts";
-import type { ExecutionContext } from "./ExecutionContext.ts";
 import type { HttpEffect } from "./Http.ts";
 import type { InputProps } from "./Input.ts";
 import type { Named, Tag } from "./Named.ts";
@@ -44,6 +43,44 @@ export interface PlatformProps {
   isExternal?: boolean;
 }
 
+/**
+ * Provide the platform class's layer (`cls.make(props, impl)`) with a
+ * lifetime that matches the phase.
+ *
+ * **At runtime** (`__ALCHEMY_RUNTIME__`, folded to `true` in every bundled
+ * artifact) the layer builds against the AMBIENT scope. `Effect.provide` is
+ * implemented with `scopedWith`, so its transient region scope would tear
+ * the layer down — firing init-level finalizers and releasing
+ * `Layer.scoped` services — the moment init completes. The runtime bridges
+ * evaluate the entrypoint under the instance-lifetime build scope (closed
+ * at instance shutdown where the platform offers one — Lambda's SIGTERM
+ * window — and never on workerd), so building against it keeps instance
+ * services alive for the instance.
+ *
+ * **At plan/deploy** it stays `Effect.provide`: the transient region evicts
+ * the layer's memo entry when each `yield*` of the class completes, so
+ * every deploy in a session re-evaluates the resource and re-registers its
+ * Output sources. Building on the session scope would keep the memo alive
+ * across deploys and a second `stack.deploy` would skip source
+ * registration (`MissingSourceError`).
+ */
+const provideClassLayer =
+  <ROut, E2, RIn>(layer: Layer.Layer<ROut, E2, RIn>) =>
+  <A, E, R>(
+    self: Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E | E2, RIn | Scope | Exclude<R, ROut>> =>
+    (globalThis.__ALCHEMY_RUNTIME__
+      ? Effect.flatMap(Effect.scope, (scope) =>
+          Effect.flatMap(Layer.buildWithScope(layer, scope), (context) =>
+            Effect.provideContext(self, context),
+          ),
+        )
+      : Effect.provide(self, layer)) as Effect.Effect<
+      A,
+      E | E2,
+      RIn | Scope | Exclude<R, ROut>
+    >;
+
 export type Main<InitServices = never> = void | {
   fetch?:
     | HttpEffect<InitServices | PlatformServices | RuntimeContext | Scope>
@@ -98,14 +135,17 @@ export type MakeShape<Shape, BaseShape> = [
   ? Exclude<BaseShape, void | undefined>
   : Exclude<Shape, void | undefined> & Exclude<BaseShape, void | undefined>;
 
-// services provided to the Resource
+// Services provided to the Resource's init/props effects. Deliberately does
+// NOT include `Scope`: init runs once per instance under a build scope that
+// closes at instance shutdown at best (Lambda's SIGTERM window; never on
+// workerd), so init code that needs a scope must not typecheck. Handlers get
+// a fresh per-event `Scope` from the bridge — note the explicit `| Scope` on
+// the handler positions in `Main` / `MainRpc` above.
 export type PlatformServices =
   | NodeServices
-  | ExecutionContext
   | HttpClient
   | Provider<any>
   | ProviderCollectionLike
-  | Scope
   | Stack
   | StackServices
   | Stage;
@@ -324,7 +364,7 @@ export const Platform = <
         );
       return Object.assign(
         function (props: Props, impl: Impl) {
-          return cls.Self.pipe(Effect.provide(cls.make(props, impl)));
+          return cls.Self.pipe(provideClassLayer(cls.make(props, impl)));
         },
         // we splice in the Effect so this can be yielded to indicate a non-Effect native instance
         // e.g. here, we yield it - in this case we don't want to provide an implementation
@@ -345,12 +385,24 @@ export const Platform = <
       // e.g.
       // export default Cloudflare.Worker("id", { main: "./src/worker.ts" }, Effect.gen(function* () { .. })
       const cls = makeClass(id);
-      return cls.Self.pipe(Effect.provide(cls.make(props, impl)), effectClass);
+      return Object.assign(
+        cls.Self.pipe(provideClassLayer(cls.make(props, impl)), effectClass),
+        // Expose the logical id statically (mirrors `makeClass`) so a class
+        // reference identifies its resource without being yielded.
+        { LogicalId: id },
+      );
     }
   };
 
   const makeClass = (id: string) => {
     class Platform {
+      /**
+       * Logical id of the resource this class declares. Statically readable
+       * — e.g. `DurableObjectProps.transferredFrom` accepts a Worker class
+       * and takes its identity from here without yielding it (yielding
+       * would add a dependency edge on the referenced resource).
+       */
+      static readonly LogicalId = id;
       static readonly Self = Self(`${type}<${id}>`);
       static readonly Platform = Context.Service<Platform, Platform>(
         `Platform<${type}<${id}>>`,
@@ -367,6 +419,18 @@ export const Platform = <
               Effect.context<never>(),
             ]),
             Effect.fn(function* ([props, runtimeContext, outerServices]) {
+              // The init effect (`impl`) is evaluated inside an
+              // `Effect.provide(...)` region below, whose implementation
+              // (`scopedWith`) would otherwise shadow the ambient `Scope`
+              // with a transient one that closes the moment init returns.
+              // Pin init's ambient scope to this layer's build scope
+              // instead: under the runtime bridges that scope belongs to
+              // the instance-lifetime build, so init-level finalizers run
+              // at instance shutdown or not at all — never per event
+              // (workerd never closes it; the Lambda entry closes it in the
+              // SIGTERM window). Request-coupled cleanup belongs in
+              // handlers, where the bridge provides a per-event scope.
+              const buildScope = yield* Effect.scope;
               const instance = Object.assign(
                 yield* resource(id, props as any).pipe(
                   Effect.flatMap(
@@ -455,6 +519,18 @@ export const Platform = <
                   ).pipe(
                     Layer.provideMerge(
                       Layer.mergeAll(
+                        // Pin init's ambient `Scope` to this layer's build
+                        // scope. `Effect.provide` (`scopedWith`) would
+                        // otherwise shadow it with a transient scope that
+                        // closes the moment init returns; the build scope
+                        // lives for the instance under the runtime bridges,
+                        // so init-level finalizers run at instance shutdown
+                        // (Lambda's SIGTERM window) or never (workerd) —
+                        // request-coupled cleanup belongs in handlers, where
+                        // the bridge provides a per-event scope. It also
+                        // wins over any `Scope` captured in `outerServices`
+                        // below.
+                        Layer.succeed(Scope, buildScope),
                         Layer.succeed(Platform.Platform, runtimeContext),
                         Layer.succeed(PlatformContext, runtimeContext),
                         Layer.succeed(RuntimeContext, runtimeContext),

package/src/Provider.ts

@@ -156,6 +156,11 @@ export interface ProviderService<
    */
   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"];
@@ -166,6 +171,11 @@ export interface ProviderService<
    */
   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"];
@@ -178,6 +188,11 @@ export interface ProviderService<
   // 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?
@@ -189,6 +204,11 @@ export interface ProviderService<
   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
@@ -201,6 +221,11 @@ export interface ProviderService<
   // dev?:() => Effect.Effect<void, any, DevReq>;
   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;
@@ -230,6 +255,11 @@ export interface ProviderService<
    */
   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;
@@ -239,6 +269,11 @@ export interface ProviderService<
   }): Effect.Effect<Res["Attributes"], any, ReconcileReq>;
   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"];

package/src/Runtime.ts

@@ -6,7 +6,10 @@
  * surface tiny and dependency-light.
  */
 
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import { isRedactedMarker, sanitizeKey } from "./RuntimeContext.ts";
 import { asEffect } from "./Util/types.ts";
 
 /**
@@ -32,3 +35,92 @@ export const makeEntrypointLayer = (
   }
   return Layer.effect(tag, asEffect(entrypoint));
 };
+
+/**
+ * Unwrap the `{"_tag":"Redacted","value":...}` marker that the deploy-time
+ * `Config` interceptor (see `Platform.ts`) and `RuntimeContext.set` use to
+ * preserve `Redacted`-ness across the env-var boundary. Returns the inner
+ * source value as a string, or `undefined` when `raw` is not a marker.
+ */
+const parseRedactedMarker = (raw: string): string | undefined => {
+  if (!raw.startsWith("{")) {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (isRedactedMarker(parsed)) {
+      return typeof parsed.value === "string"
+        ? parsed.value
+        : JSON.stringify(parsed.value);
+    }
+  } catch {
+    // not JSON — plain env value, fall through
+  }
+  return undefined;
+};
+
+/**
+ * Reify an env-var string the way `RuntimeContext.get` does: unwrap the
+ * `Redacted` marker, unquote a JSON-stringified string, and pass anything
+ * else through verbatim.
+ */
+const reifyEnvString = (raw: string): string => {
+  const marker = parseRedactedMarker(raw);
+  if (marker !== undefined) {
+    return marker;
+  }
+  if (raw.startsWith('"')) {
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (typeof parsed === "string") {
+        return parsed;
+      }
+    } catch {
+      // not JSON — plain env value, fall through
+    }
+  }
+  return raw;
+};
+
+/**
+ * Wrap a runtime's env-backed `ConfigProvider` so values that were
+ * auto-bound by the deploy-time `Config` interceptor decode transparently.
+ *
+ * The engine can't know which config values are sensitive, so the
+ * interceptor binds every `Config` read during Init onto the deploy target
+ * as a secret, serialized as a `{"_tag":"Redacted","value":<source>}`
+ * marker. The interceptor's runtime branch reifies those markers for reads
+ * during Init, but effects that run later (request handlers, nested
+ * layers) resolve `Config` against the raw env-backed provider — without
+ * this wrapper, `Config.number("PORT")` inside a handler sees the marker
+ * JSON instead of the source value and fails with a schema error.
+ *
+ * Two behaviors:
+ * - Leaf values that carry the marker are unwrapped to the raw source
+ *   string before `Config` schemas decode them; everything else passes
+ *   through untouched.
+ * - On a miss, falls back to the flat `sanitizeKey`-canonicalized key
+ *   (`my.key` → `my_key`) that the interceptor bound the value under, so
+ *   config names with non-alphanumeric characters resolve at runtime too.
+ */
+export const reifyBoundConfigProvider = (
+  base: ConfigProvider.ConfigProvider,
+  env: Record<string, unknown>,
+): ConfigProvider.ConfigProvider =>
+  ConfigProvider.make((path) =>
+    base.load(path).pipe(
+      Effect.map((node) => {
+        if (node?._tag === "Value") {
+          const value = parseRedactedMarker(node.value);
+          return value === undefined ? node : ConfigProvider.makeValue(value);
+        }
+        if (node === undefined) {
+          const raw = env[sanitizeKey(path.map((p) => p.toString()).join("_"))];
+          if (typeof raw === "string") {
+            return ConfigProvider.makeValue(reifyEnvString(raw));
+          }
+        }
+        return node;
+      }),
+    ),
+  );

package/src/RuntimeContext.ts

@@ -2,6 +2,7 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
 import type { HttpEffect } from "./Http.ts";
 import type { Output } from "./Output.ts";
 
@@ -43,6 +44,84 @@ export interface BaseRuntimeContext {
 export const sanitizeKey = (key: string): string =>
   key.replaceAll(/[^a-zA-Z0-9]/g, "_");
 
+/**
+ * The wire format `RuntimeContext.set`/`get` use to carry a `Redacted` value
+ * through an environment variable. `JSON.stringify(Redacted)` emits the
+ * literal string `"<redacted>"` and loses the value, so secrets are
+ * serialized as this marker and the runtime `get` path rebuilds the wrapper.
+ */
+export interface RedactedMarker {
+  readonly _tag: "Redacted";
+  readonly value: unknown;
+}
+
+/**
+ * Detect the (already JSON-parsed) {@link RedactedMarker} shape. After
+ * `JSON.parse` the marker is a plain object — `Redacted.isRedacted` is
+ * always `false` on it — so detection is structural.
+ */
+export const isRedactedMarker = (value: unknown): value is RedactedMarker =>
+  typeof value === "object" &&
+  value !== null &&
+  (value as { _tag?: unknown })._tag === "Redacted" &&
+  "value" in value;
+
+/**
+ * Serialize a binding value for an env var: `Redacted` values are packed as
+ * a {@link RedactedMarker}, everything else is plain `JSON.stringify`.
+ */
+export const packEnvValue = (value: unknown): string =>
+  Redacted.isRedacted(value)
+    ? JSON.stringify({
+        _tag: "Redacted",
+        value: Redacted.value(value),
+      } satisfies RedactedMarker)
+    : JSON.stringify(value);
+
+/**
+ * Like {@link packEnvValue}, but a `Redacted` input keeps its `Redacted`
+ * wrapper on the *outside* of the packed string, so deploy-time code can
+ * route secrets through a dedicated channel (Cloudflare `secret_text`,
+ * Secrets Store) instead of leaking them as plain env vars. The inner
+ * payload still carries the marker for the runtime `get` accessor.
+ */
+export const packEnvValueKeepRedacted = (
+  value: unknown,
+): string | Redacted.Redacted<string> =>
+  Redacted.isRedacted(value)
+    ? Redacted.make(packEnvValue(value))
+    : packEnvValue(value);
+
+/**
+ * Parse an env-var string produced by {@link packEnvValue} back into its
+ * value: rebuild `Redacted` from the marker, return other JSON values
+ * as-is, and fall back to the raw string for non-JSON input (e.g. an env
+ * var the user set directly). `undefined` passes through.
+ *
+ * Runtime `get` accessors MUST feed this from the raw environment
+ * (`process.env[key]` / the platform env object) — never through
+ * `Config.string`: the ambient runtime `ConfigProvider` reifies bound
+ * values (unwrapping the marker before it could be detected here), and
+ * during init the ambient provider is the interceptor installed in
+ * `Platform.ts`, whose runtime branch calls back into `ctx.get(key)` —
+ * resolving through `Config` would re-enter it for the same key and
+ * recurse forever.
+ */
+export const unpackEnvValue = <T>(raw: string | undefined): T | undefined => {
+  if (raw === undefined) {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (isRedactedMarker(parsed)) {
+      return Redacted.make(parsed.value) as unknown as T;
+    }
+    return parsed as T;
+  } catch {
+    return raw as unknown as T; // assume it's just a string
+  }
+};
+
 /**
  * Context of the runtime environment.
  *

package/src/Server/Process.ts

@@ -1,4 +1,3 @@
-import * as Config from "effect/Config";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import { FileSystem } from "effect/FileSystem";
@@ -9,7 +8,11 @@ import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSp
 import type { HttpEffect } from "../Http.ts";
 import * as Http from "../Http.ts";
 import * as Output from "../Output.ts";
-import type { BaseRuntimeContext } from "../RuntimeContext.ts";
+import {
+  packEnvValue,
+  unpackEnvValue,
+  type BaseRuntimeContext,
+} from "../RuntimeContext.ts";
 
 export type ProcessServices =
   | ChildProcessSpawner
@@ -74,25 +77,15 @@ export const createHostRuntimeContext =
       set: (bindingId: string, output: Output.Output) =>
         Effect.sync(() => {
           const key = bindingId.replaceAll(/[^a-zA-Z0-9]/g, "_");
-          env[key] = output.pipe(Output.map((value) => JSON.stringify(value)));
+          // `packEnvValue` marker-packs Redacted values so they survive the
+          // Output → env round-trip.
+          env[key] = output.pipe(Output.map(packEnvValue));
           return key;
         }),
       get: <T>(key: string) =>
-        Config.string(key).pipe(
-          Effect.flatMap((value) =>
-            Effect.try({
-              try: () => JSON.parse(value) as T,
-              catch: (error) => error as Error,
-            }),
-          ),
-          Effect.catch((cause) =>
-            Effect.die(
-              new Error(`Failed to get environment variable: ${key}`, {
-                cause,
-              }),
-            ),
-          ),
-        ),
+        // Read straight from `process.env` — see `unpackEnvValue` for why
+        // this must never resolve through `Config.string`.
+        Effect.sync(() => unpackEnvValue<T>(process.env[key]) as T),
       run: (effect: Effect.Effect<void, never, any>) =>
         Effect.sync(() => {
           runners.push(effect);

package/src/Stack.ts

@@ -238,7 +238,7 @@ export const make =
                 `    providers: Cloudflare.providers(),\n` +
                 `    state: Cloudflare.state(), // <-- required\n` +
                 `  }, ...)\n` +
-                `See https://v2.alchemy.run/state-store for available state stores.`,
+                `See https://alchemy.run/state-store for available state stores.`,
             ),
           );
         }

package/src/State/HttpStateStore.ts

@@ -67,7 +67,7 @@ export const checkHttpStateStoreAuth = ({
             error.response.status >= 500),
         // Bounded: a store that 404s/500s forever is a hard failure, not
         // something to spin on until the process is killed.
-        schedule: Schedule.fixed(200).pipe(Schedule.both(Schedule.recurs(75))),
+        schedule: Schedule.max([Schedule.fixed(200), Schedule.recurs(75)]),
       }),
     );
   });
@@ -225,10 +225,10 @@ const retryTransient = <A, Err, Req>(eff: Effect.Effect<A, Err, Req>) =>
     // Exponential backoff capped at 2s, max 5 attempts. Beyond that
     // the issue isn't transient and we'd rather surface a hard
     // failure than block the deploy indefinitely.
-    schedule: Schedule.exponential(100).pipe(
-      Schedule.either(Schedule.spaced("2 seconds")),
-      Schedule.both(Schedule.recurs(5)),
-    ),
+    schedule: Schedule.max([
+      Schedule.min([Schedule.exponential(100), Schedule.spaced("2 seconds")]),
+      Schedule.recurs(5),
+    ]),
   });
 
 /**

package/src/Sync.ts

@@ -203,6 +203,7 @@ export const sync = (
       const observed = yield* provider
         .read({
           id: logicalId,
+          fqn,
           instanceId,
           olds: old.props as never,
           output: old.attr as never,
@@ -220,6 +221,7 @@ export const sync = (
         const attr = yield* provider
           .reconcile({
             id: logicalId,
+            fqn,
             instanceId,
             news: old.props as never,
             olds: undefined,
@@ -273,6 +275,7 @@ export const sync = (
       const attr = yield* provider
         .reconcile({
           id: logicalId,
+          fqn,
           instanceId,
           news: old.props as never,
           olds: old.props as never,