alchemy 2.0.0-beta.35 → 2.0.0-beta.37

package/src/Plan.ts

@@ -349,8 +349,53 @@ export const make = <A>(
           });
         } else if (Output.isLiteralExpr(expr)) {
           return expr.value;
+        } else if (Output.isRefExpr(expr)) {
+          const refStack = expr.stack ?? stackName;
+          const refStage = expr.stage ?? stage;
+          const refState = yield* state
+            .get({
+              stack: refStack,
+              stage: refStage,
+              fqn: expr.resourceId,
+            })
+            .pipe(Effect.orDie);
+          if (!refState) {
+            return yield* Effect.die(
+              new Output.InvalidReferenceError({
+                message: `Reference to '${expr.resourceId}' in stack '${refStack}' and stage '${refStage}' not found. Have you deployed '${refStage}' of '${refStack}'?`,
+                stack: refStack,
+                stage: refStage,
+                resourceId: expr.resourceId,
+              }),
+            );
+          }
+          return refState.attr;
+        } else if (Output.isStackRefExpr(expr)) {
+          const refStack = expr.stack;
+          const refStage = expr.stage ?? stage;
+          const output = yield* state
+            .getOutput({
+              stack: refStack,
+              stage: refStage,
+            })
+            .pipe(Effect.orDie);
+          if (output == null) {
+            return yield* Effect.die(
+              new Output.InvalidReferenceError({
+                message: `Reference to stack '${refStack}' at stage '${refStage}' not found. Have you deployed stage '${refStage}' of '${refStack}'?`,
+                stack: refStack,
+                stage: refStage,
+                resourceId: refStack,
+              }),
+            );
+          }
+          return output;
+        } else if (Output.isNamedExpr(expr)) {
+          return yield* resolveOutput(expr.expr);
         }
-        return yield* Effect.die(new Error("Not implemented yet"));
+        return yield* Effect.die(
+          new Error("Not implemented yet" + (expr as any).kind),
+        );
       });
 
     // map of resource FQN -> its downstream dependencies (resources that depend on it)
@@ -413,16 +458,59 @@ export const make = <A>(
       }),
     );
 
-    // Map FQN -> list of downstream FQNs (resources that depend on this one)
+    // Resources that participate in a cycle when both prop and binding
+    // edges are considered. Used below to decide whether an acyclic
+    // binding edge should also become a downstream edge.
+    const combinedCycleMembers = findCycleMembers(allUpstreamDependencies);
+
+    // Map FQN -> list of downstream FQNs (resources that depend on this one).
+    //
+    // Prop edges always become downstream edges — they can't form cycles
+    // (the resource graph is a DAG by construction once props are fully
+    // resolved). Binding edges become downstream edges too, except when
+    // they participate in a cycle in the combined graph: mutual bindings
+    // (A binds to B's data, B binds to A's data) intentionally do not
+    // create downstream edges, so deletion does not deadlock waiting on
+    // each other (see the "binding-only cycles inside a construct" test
+    // in `plan.test.ts`).
+    //
+    // Including acyclic binding edges is required for cloud APIs that
+    // enforce the binding at the provider level — e.g. a Cloudflare
+    // Worker with a `service` binding to another Worker cannot delete
+    // the upstream worker until the downstream worker's binding has been
+    // removed. Without the binding edge in `downstream`, the two delete
+    // concurrently and the upstream delete fails with
+    // `ServiceBindingConflict`.
     const newDownstreamDependencies: {
       [fqn: string]: string[];
     } = Object.fromEntries(
-      resources.map((resource) => [
-        resource.FQN,
-        Object.entries(newUpstreamDependencies)
-          .filter(([_, upstream]) => upstream.includes(resource.FQN))
-          .map(([depFqn]) => depFqn),
-      ]),
+      resources.map((resource) => {
+        const upFqn = resource.FQN;
+        const downstream: string[] = [];
+        for (const [downFqn, upstreams] of Object.entries(
+          rawUpstreamDependencies,
+        )) {
+          if (downFqn === upFqn) continue;
+          if (!upstreams.includes(upFqn)) continue;
+          const isPropEdge = (newUpstreamDependencies[downFqn] ?? []).includes(
+            upFqn,
+          );
+          if (isPropEdge) {
+            downstream.push(downFqn);
+            continue;
+          }
+          // Binding-only edge — exclude when both endpoints sit inside
+          // the same SCC of the combined graph.
+          if (
+            combinedCycleMembers.has(upFqn) &&
+            combinedCycleMembers.has(downFqn)
+          ) {
+            continue;
+          }
+          downstream.push(downFqn);
+        }
+        return [upFqn, downstream];
+      }),
     );
 
     const resourceGraph = Object.fromEntries(
@@ -789,10 +877,11 @@ export const make = <A>(
       )).map((update) => [update.resource.FQN, update]),
     ) as Plan["resources"];
 
-    // Compute SCC membership once. Apply uses it to decide whether an
-    // update node must publish its prior attr early to break a cycle, or
-    // can simply wait for upstreams like a DAG node (the common case).
-    const cycleMembers = findCycleMembers(allUpstreamDependencies);
+    // SCC membership of the combined upstream graph. Apply uses it to
+    // decide whether an update node must publish its prior attr early to
+    // break a cycle, or can simply wait for upstreams like a DAG node
+    // (the common case). Computed once, above, for the downstream graph.
+    const cycleMembers = combinedCycleMembers;
 
     // Detect unsatisfiable dependency cycles among create/replace nodes.
     // Update/noop nodes signal their Deferred before waitForDeps when in a

package/src/Platform.ts

@@ -242,8 +242,18 @@ export const Platform = <
               }),
             )
         ).pipe(
-          Effect.tap(
-            (resource) => hooks.onCreate?.(resource as R, props) ?? Effect.void,
+          Effect.tap((resource) =>
+            hooks.onCreate
+              ? Effect.flatMap(
+                  // `props` may itself be an Effect (e.g. when wrapped by
+                  // `Cloudflare.Vite` via `Effect.map`); resolve it before
+                  // handing it to the hook so `onCreate` always sees the
+                  // plain props object — the second call site (in
+                  // `cls.make`) already does this.
+                  Effect.isEffect(props) ? props : Effect.succeed(props ?? {}),
+                  (resolved) => hooks.onCreate!(resource as R, resolved),
+                )
+              : Effect.void,
           ),
         );
       return Object.assign(
@@ -324,8 +334,13 @@ export const Platform = <
               yield* impl.pipe(
                 Effect.flatMap((impl) =>
                   impl?.fetch
-                    ? (runtimeContext.serve?.(impl.fetch) ??
-                      Effect.die("No serve handler"))
+                    ? // Hand the full impl to `serve` so the runtime can
+                      // expose any non-handler methods on the impl shape
+                      // (e.g. RPC methods on a Cloudflare Worker) alongside
+                      // the standard `fetch` handler.
+                      (runtimeContext.serve?.(impl.fetch, {
+                        shape: impl as Record<string, unknown>,
+                      }) ?? Effect.die("No serve handler"))
                     : Effect.void,
                 ),
                 Effect.provide(

package/src/Ref.ts

@@ -22,11 +22,16 @@ export interface RefMetadata<R extends ResourceLike> {
   stage?: string;
 }
 
-export const ref = <R extends ResourceLike>({
-  stack,
-  id,
-  stage,
-}: RefMetadata<R>): Ref<R> => {
+export const ref = <R extends ResourceLike>(
+  id: string,
+  {
+    stack,
+    stage,
+  }: {
+    stack?: string;
+    stage?: string;
+  } = {},
+): Ref<R> => {
   const ref = new Proxy(
     {},
     {

package/src/Resource.ts

@@ -7,6 +7,7 @@ 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 { ref as makeRef } from "./Ref.ts";
 import { RemovalPolicy } from "./RemovalPolicy.ts";
 import { Self } from "./Self.ts";
 import { Stack } from "./Stack.ts";
@@ -47,6 +48,10 @@ export type ResourceClassWithMethods<
   Effect.Effect<ResourceConstructor<R>> & {
     Self: Self<R>;
     Provider: Provider<R>;
+    ref(
+      id: string,
+      options?: { stage?: string; stack?: string },
+    ): Effect.Effect<R>;
   } & Methods;
 
 export type ResourceClass<R extends ResourceLike> = ResourceConstructor<
@@ -56,6 +61,10 @@ export type ResourceClass<R extends ResourceLike> = ResourceConstructor<
   Effect.Effect<ResourceConstructor<R>> & {
     Self: Self<R>;
     Provider: Provider<R>;
+    ref(
+      id: string,
+      options?: { stage?: string; stack?: string },
+    ): Effect.Effect<R>;
   };
 
 export type LogicalId = string;
@@ -286,6 +295,19 @@ export function Resource<R extends ResourceLike>(
         constructor(id, props),
       );
     },
+    /**
+     * Build a typed reference to a deployed instance of this resource
+     * — in the current stack/stage by default, or in another via
+     * `options`. Resolves to the same shape as `yield*
+     * MyResource("id", props)` so downstream code can read attributes
+     * (`ref.someAttr`) exactly the way it would for a locally-declared
+     * resource.
+     */
+    ref: (
+      id: string,
+      options?: { stage?: string; stack?: string },
+    ): Effect.Effect<R> =>
+      Effect.succeed(Output.of(makeRef<R>(id, options)) as unknown as R),
     Type: type,
     Provider: ProviderTag,
     Self: self,

package/src/RuntimeContext.ts

@@ -14,6 +14,7 @@ export interface BaseRuntimeContext {
   exports?: Effect.Effect<Record<string, any>>;
   serve?<Req = never>(
     handler: HttpEffect<Req>,
+    options?: { shape?: Record<string, unknown> },
   ): Effect.Effect<void, never, Req>;
 }
 

package/src/Secret.ts

@@ -0,0 +1,87 @@
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Output from "./Output.ts";
+
+/**
+ * The shapes a {@link secret} can be derived from.
+ *
+ * - `string` — wrapped in `Redacted.make` and bound as a literal.
+ * - `Redacted<string>` — bound as-is.
+ * - `Effect<string | Redacted<string>>` — resolved at deploy time.
+ * - `Config<string | Redacted<string>>` — resolved against the active
+ *   `ConfigProvider` at deploy time.
+ */
+export type SecretInput<R = never> =
+  | string
+  | Redacted.Redacted<string>
+  | Effect.Effect<string | Redacted.Redacted<string>, any, R>
+  | Config.Config<string | Redacted.Redacted<string>>;
+
+/**
+ * Bind a secret value into the active {@link RuntimeContext} (e.g. a
+ * Cloudflare Worker's `env`) under the given `name` so the resource
+ * provider deploys it as a secret (e.g. `secret_text` for Cloudflare).
+ *
+ * The result is an `Output<Redacted<string>>` — `yield*`-ing it returns
+ * an `Accessor<Redacted<string>>` that resolves the value at runtime.
+ *
+ * @example One-arg shortcut — reads `Config.redacted("API_KEY")`
+ * ```ts
+ * const apiKey = yield* Alchemy.Secret("API_KEY");
+ * ```
+ *
+ * @example From a literal
+ * ```ts
+ * const apiKey = yield* Alchemy.Secret("API_KEY", "sk-123");
+ * ```
+ *
+ * @example From an Effect
+ * ```ts
+ * const apiKey = yield* Alchemy.Secret(
+ *   "API_KEY",
+ *   Effect.succeed(Redacted.make("sk-123")),
+ * );
+ * ```
+ *
+ * @example From a Config
+ * ```ts
+ * const apiKey = yield* Alchemy.Secret("API_KEY", Config.redacted("API_KEY"));
+ * ```
+ */
+export function Secret(
+  name: string,
+): Output.Output<Redacted.Redacted<string>, never>;
+export function Secret<R = never>(
+  name: string,
+  value: SecretInput<R>,
+): Output.Output<Redacted.Redacted<string>, R>;
+export function Secret<R = never>(
+  name: string,
+  value?: SecretInput<R>,
+): Output.Output<Redacted.Redacted<string>, R> {
+  const source = value ?? Config.redacted(name);
+  const base = toOutput<string | Redacted.Redacted<string>, R>(source);
+  return Output.named(
+    base.pipe(
+      Output.map((v) => (Redacted.isRedacted(v) ? v : Redacted.make(v))),
+    ) as Output.Output<Redacted.Redacted<string>, R>,
+    name,
+  );
+}
+
+/** @internal */
+export const toOutput = <T, R = never>(
+  source: T | Effect.Effect<T, any, R> | Config.Config<T> | Output.Output<T, R>,
+): Output.Output<T, R> => {
+  if (Output.isOutput(source)) {
+    return source;
+  }
+  if (Config.isConfig(source)) {
+    return Output.asOutput(source.asEffect() as any) as Output.Output<T, R>;
+  }
+  if (Effect.isEffect(source)) {
+    return Output.asOutput(source as any) as Output.Output<T, R>;
+  }
+  return Output.asOutput(source as T) as Output.Output<T, R>;
+};

package/src/Serverless/Function.ts

@@ -3,7 +3,16 @@ import type { HttpEffect } from "../Http.ts";
 import type { BaseRuntimeContext } from "../RuntimeContext.ts";
 
 export interface FunctionContext extends BaseRuntimeContext {
-  serve<Req = never>(handler: HttpEffect<Req>): Effect.Effect<void, never, Req>;
+  /**
+   * Register an HTTP handler. The optional `shape` payload is the user's
+   * full default-export shape — Cloudflare Workers use it to expose
+   * non-handler methods (e.g. `greet`) as RPC methods on the deployed
+   * `WorkerEntrypoint`. Other platforms (Lambda, etc.) ignore it.
+   */
+  serve<Req = never>(
+    handler: HttpEffect<Req>,
+    options?: { shape?: Record<string, unknown> },
+  ): Effect.Effect<void, never, Req>;
   listen<A, Req = never>(
     handler: FunctionListener<A, Req>,
   ): Effect.Effect<void, never, Req>;

package/src/Stack.ts

@@ -6,7 +6,7 @@ import * as Layer from "effect/Layer";
 import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import { Path } from "effect/Path";
-import type { Scope } from "effect/Scope";
+import * as Scope from "effect/Scope";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 import type { HttpClient } from "effect/unstable/http/HttpClient";
 import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
@@ -18,19 +18,18 @@ import { Profile, ProfileLive } from "./Auth/Profile.ts";
 import { Cli } from "./Cli/Cli.ts";
 import type { Input, InputProps } from "./Input.ts";
 import * as Output from "./Output.ts";
-import { ref } from "./Ref.ts";
 import type { ResourceBinding, ResourceLike } from "./Resource.ts";
 import { Stage } from "./Stage.ts";
 import type { State } from "./State/State.ts";
 import { loadConfigProvider } from "./Util/ConfigProvider.ts";
-import { taggedFunction } from "./Util/effect.ts";
+import { effectClass, taggedFunction } from "./Util/effect.ts";
 import { fileLogger } from "./Util/FileLogger.ts";
 import { PlatformServices } from "./Util/PlatformServices.ts";
 
 export type StackServices =
   | Stack
   | Stage
-  | Scope
+  | Scope.Scope
   | FileSystem
   | Path
   | AlchemyContext
@@ -46,7 +45,7 @@ export type StackEffect<A, Err = never, Req = never> = Effect.Effect<
   Err,
   | PlatformServices
   | HttpClient
-  | Scope
+  | Scope.Scope
   | AuthProviders
   | AlchemyContext
   | Cli
@@ -98,6 +97,7 @@ export const Stack: Context.ServiceClass<
     (stackName: string): Effect.Effect<Self> & {
       new (_: never): Output.ToOutput<Shape>;
       make: <A, Req>(
+        options: StackProps<NoInfer<Req>>,
         effect: Effect.Effect<A, never, Req>,
       ) => Effect.Effect<CompiledStack<A>>;
       stage: {
@@ -114,36 +114,46 @@ export const Stack: Context.ServiceClass<
   taggedFunction(
     Context.Service<Stack, Omit<StackSpec, "output">>()("Stack"),
     <A, Req>(
-      stackName: string,
-      options: {
-        providers: Layer.Layer<NoInfer<Req>, never, StackServices>;
-        state: Layer.Layer<State, never, StackServices>;
-      },
-      eff: Effect.Effect<A, never, Req>,
-    ) =>
-      eff.pipe(
+      stackName?: string,
+      options?: StackProps<NoInfer<Req>>,
+      eff?: Effect.Effect<A, never, Req>,
+    ) => {
+      if (!stackName) {
+        return (stackName: string) =>
+          Object.assign(
+            // by default, reference the stack at the "current" stage of the importer
+            Output.stackRef<A>(stackName).pipe(effectClass),
+            {
+              stage: createStageProxy(stackName),
+              make: <Req = never>(
+                options: StackProps<NoInfer<Req>>,
+                eff: Effect.Effect<A, never, Req>,
+              ) => Stack(stackName, options, eff),
+            },
+          );
+      }
+      return eff!.pipe(
         make({
           name: stackName,
-          ...options,
+          ...options!,
         }),
         (eff) =>
           Object.assign(eff, {
-            stage: new Proxy(
-              {},
-              {
-                get: (_, stage: string) =>
-                  ref({
-                    stack: stackName,
-                    stage,
-                    id: stackName,
-                  }),
-              },
-            ),
+            stage: createStageProxy(stackName),
           }),
-      ),
+      );
+    },
   ),
 ) as any;
 
+const createStageProxy = (stackName: string) =>
+  new Proxy(
+    {},
+    {
+      get: (_, stage: string) => Output.stackRef(stackName, { stage }),
+    },
+  );
+
 export interface StackSpec<Output = any> {
   name: string;
   stage: string;
@@ -283,9 +293,18 @@ export const evalStack = <A, B, Err, Req>(
   options: {
     stage: string;
     dev?: boolean;
+    /**
+     * Optional caller-supplied scope. When provided, scoped resources
+     * (e.g. the dev sidecar process) live until the caller closes this
+     * scope instead of being torn down when `evalStack` resolves. Used
+     * by the test harness so the sidecar survives across `beforeAll`,
+     * tests, and `afterAll`. When omitted, behaves as before with a
+     * private scope closed on completion.
+     */
+    scope?: Scope.Scope;
   },
-) =>
-  Effect.gen(function* () {
+) => {
+  const body = Effect.gen(function* () {
     const stack = yield* effect;
     const configProvider = yield* loadConfigProvider(Option.none());
 
@@ -305,5 +324,9 @@ export const evalStack = <A, B, Err, Req>(
     ),
     Effect.provide(Layer.succeed(Stage, options.stage)),
     Effect.provide(Layer.provideMerge(alchemy({ dev: options.dev }), platform)),
-    Effect.scoped,
   );
+
+  return options.scope === undefined
+    ? Effect.scoped(body)
+    : Scope.provide(body, options.scope);
+};

package/src/State/HttpStateApi.ts

@@ -155,6 +155,25 @@ export const GetReplacedResources = HttpApiEndpoint.get(
   },
 );
 
+export const GetStackOutput = HttpApiEndpoint.get(
+  "getStackOutput",
+  "/state/stacks/:stack/stages/:stage/output",
+  {
+    params: StackStage,
+    success: Schema.UndefinedOr(ResourceStateSchema),
+  },
+);
+
+export const SetStackOutput = HttpApiEndpoint.put(
+  "setStackOutput",
+  "/state/stacks/:stack/stages/:stage/output",
+  {
+    params: StackStage,
+    payload: ResourceStateSchema,
+    success: ResourceStateSchema,
+  },
+);
+
 /** Response shape for the unauthenticated `/version` probe. */
 export const VersionResponse = Schema.Struct({
   version: Schema.Number,
@@ -179,6 +198,8 @@ export class StateGroup extends HttpApiGroup.make("state")
   .add(DeleteState)
   .add(GetReplacedResources)
   .add(DeleteStack)
+  .add(GetStackOutput)
+  .add(SetStackOutput)
   .middleware(StateAuth) {}
 
 export class VersionGroup extends HttpApiGroup.make("version").add(

package/src/State/HttpStateStore.ts

@@ -129,6 +129,27 @@ export const makeHttpStateStore = ({
             query: request.stage === undefined ? {} : { stage: request.stage },
           })
           .pipe(Effect.asVoid, mapStateStoreError),
+      getOutput: (request) =>
+        state
+          .getStackOutput({
+            params: { stack: request.stack, stage: request.stage },
+          })
+          .pipe(
+            Effect.map((s) =>
+              s == null ? undefined : reviveStateRecursive(s),
+            ),
+            mapStateStoreError,
+          ),
+      setOutput: (request) =>
+        state
+          .setStackOutput({
+            params: { stack: request.stack, stage: request.stage },
+            payload: encodeState(request.value as any),
+          })
+          .pipe(
+            Effect.map(() => request.value),
+            mapStateStoreError,
+          ),
     };
     return service;
   });

package/src/State/InMemoryState.ts

@@ -13,14 +13,18 @@ export const inMemoryState = (
     StackId,
     Record<StageId, Record<Fqn, ResourceState>>
   > = {},
+  initialOutputs: Record<StackId, Record<StageId, unknown>> = {},
 ) =>
   Layer.effect(
     State,
-    Effect.succeed(InMemoryService(initialState)).pipe(recordStateStoreInit),
+    Effect.succeed(InMemoryService(initialState, initialOutputs)).pipe(
+      recordStateStoreInit,
+    ),
   );
 
 export const InMemoryService = (
   state: Record<StackId, Record<StageId, Record<Fqn, ResourceState>>> = {},
+  outputs: Record<StackId, Record<StageId, unknown>> = {},
 ) =>
   State.of({
     id: "inmemory",
@@ -60,12 +64,13 @@ export const InMemoryService = (
       stage: string;
       fqn: string;
       value: V;
-    }) => {
-      const stackState = (state[stack] ??= {});
-      const stageState = (stackState[stage] ??= {});
-      stageState[fqn] = value;
-      return Effect.succeed(value);
-    },
+    }) =>
+      Effect.sync(() => {
+        const stackState = (state[stack] ??= {});
+        const stageState = (stackState[stage] ??= {});
+        stageState[fqn] = value;
+        return value;
+      }),
     delete: ({
       stack,
       stage,
@@ -74,7 +79,7 @@ export const InMemoryService = (
       stack: string;
       stage: string;
       fqn: string;
-    }) => Effect.succeed(delete state[stack]?.[stage]?.[fqn]),
+    }) => Effect.sync(() => delete state[stack]?.[stage]?.[fqn]),
     deleteStack: ({ stack, stage }: { stack: string; stage?: string }) =>
       Effect.sync(() => {
         if (stage === undefined) {
@@ -87,4 +92,20 @@ export const InMemoryService = (
       Effect.succeed(
         Array.from(Object.keys(state[stack]?.[stage] ?? {}) ?? []),
       ),
+    getOutput: ({ stack, stage }: { stack: string; stage: string }) =>
+      Effect.succeed(outputs[stack]?.[stage]),
+    setOutput: ({
+      stack,
+      stage,
+      value,
+    }: {
+      stack: string;
+      stage: string;
+      value: unknown;
+    }) =>
+      Effect.sync(() => {
+        const stackOutputs = (outputs[stack] ??= {});
+        stackOutputs[stage] = value;
+        return value;
+      }),
   });