alchemy 2.0.0-beta.36 → 2.0.0-beta.38

package/src/State/InMemoryState.ts

@@ -2,7 +2,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import { recordStateStoreInit } from "../Telemetry/Metrics.ts";
 import type { ResourceState } from "./ResourceState.ts";
-import { State } from "./State.ts";
+import { State, type PersistedState } from "./State.ts";
 
 type StackId = string;
 type StageId = string;
@@ -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",
@@ -50,7 +54,7 @@ export const InMemoryService = (
           (s) => s.status === "replaced",
         ),
       ),
-    set: <V extends ResourceState>({
+    set: <V extends PersistedState>({
       stack,
       stage,
       fqn,
@@ -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 as ResourceState;
+        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;
+      }),
   });

package/src/State/LocalState.ts

@@ -46,6 +46,9 @@ export const makeLocalState = () =>
       fqn: string;
     }) => path.join(stateDir, stack, stage, `${encodeFqn(fqn)}.json`);
 
+    const outputFile = ({ stack, stage }: { stack: string; stage: string }) =>
+      path.join(stateDir, stack, stage, `__stack_output__.json`);
+
     const created = new Set<string>();
 
     const ensure = (dir: string) =>
@@ -107,11 +110,32 @@ export const makeLocalState = () =>
       list: (request) =>
         fs.readDirectory(stageDir(request)).pipe(
           recover,
-          Effect.map(
-            (files) =>
-              files?.map((file) => decodeFqn(file.replace(/\.json$/, ""))) ??
-              [],
+          Effect.map((files) =>
+            (files ?? [])
+              // Filter the bookkeeping file before decoding — `decodeFqn`
+              // replaces `__` with `/`, which would turn the literal name
+              // `__stack_output__` into `/stack_output/` and slip past the
+              // filter, leaving the engine to look up a non-existent
+              // resource.
+              .filter((file) => file !== "__stack_output__.json")
+              .map((file) => decodeFqn(file.replace(/\.json$/, ""))),
+          ),
+        ),
+      getOutput: (request) =>
+        fs.readFile(outputFile(request)).pipe(
+          Effect.map((file) => JSON.parse(file.toString(), reviveState)),
+          recover,
+        ),
+      setOutput: (request) =>
+        ensure(stageDir(request)).pipe(
+          Effect.flatMap(() =>
+            fs.writeFileString(
+              outputFile(request),
+              JSON.stringify(encodeState(request.value as any), null, 2),
+            ),
           ),
+          recover,
+          Effect.map(() => request.value),
         ),
     };
     return state;

package/src/State/ResourceState.ts

@@ -27,6 +27,11 @@ export type ReplacementOldResourceState =
   | ReplacementResourceState;
 
 interface BaseResourceState {
+  /**
+   * Discriminator vs {@link ActionState}. Optional for back-compat: legacy
+   * persisted rows have no `kind` field and are implicitly resources.
+   */
+  readonly kind?: "resource";
   /** Type of the Resource (e.g. AWS.Lambda.Function) */
   resourceType: string;
   /** Namespace of the Resource */

package/src/State/State.ts

@@ -2,6 +2,21 @@ import * as Context from "effect/Context";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import type { ReplacedResourceState, ResourceState } from "./ResourceState.ts";
+import type { ActionState } from "./ActionState.ts";
+
+/**
+ * Anything persistable under an FQN. Resources are discriminated by status
+ * strings ("creating", "created", …) and Tasks by `kind: "action"`.
+ */
+export type PersistedState = ResourceState | ActionState;
+
+export const isActionState = (
+  s: PersistedState | undefined,
+): s is ActionState => !!s && (s as any).kind === "action";
+
+export const isResourceState = (
+  s: PersistedState | undefined,
+): s is ResourceState => !!s && (s as any).kind !== "task";
 
 export class StateStoreError extends Data.TaggedError("StateStoreError")<{
   message: string;
@@ -41,7 +56,7 @@ export interface StateService {
     stack: string;
     stage: string;
     fqn: string;
-  }): Effect.Effect<ResourceState | undefined, StateStoreError, never>;
+  }): Effect.Effect<PersistedState | undefined, StateStoreError, never>;
   /**
    * List top-level resources that are still in replacement cleanup.
    *
@@ -59,7 +74,7 @@ export interface StateService {
   /**
    * Set a resource by its FQN (namespace-qualified key).
    */
-  set<V extends ResourceState>(request: {
+  set<V extends PersistedState>(request: {
     stack: string;
     stage: string;
     fqn: string;
@@ -87,4 +102,25 @@ export interface StateService {
     stack: string;
     stage: string;
   }): Effect.Effect<readonly string[], StateStoreError, never>;
+  /**
+   * Read the persisted stack output for `(stack, stage)`. Returns
+   * `undefined` when the stack has not been deployed (or has been
+   * destroyed) at this stage.
+   *
+   * Stack outputs are written by `apply` once the deploy succeeds and
+   * read by cross-stack references (`yield* OtherStack` /
+   * `OtherStack.stage.<name>` / `Output.stackRef(...)`).
+   */
+  getOutput(request: {
+    stack: string;
+    stage: string;
+  }): Effect.Effect<unknown, StateStoreError, never>;
+  /**
+   * Persist the resolved stack output for `(stack, stage)`.
+   */
+  setOutput(request: {
+    stack: string;
+    stage: string;
+    value: unknown;
+  }): Effect.Effect<unknown, StateStoreError, never>;
 }

package/src/State/index.ts

@@ -4,5 +4,6 @@ export * from "./InMemoryState.ts";
 export * from "./LocalState.ts";
 export * from "./ResourceState.ts";
 export * from "./State.ts";
+export * from "./ActionState.ts";
 export * from "./StateEncoding.ts";
 export * from "./Sync.ts";

package/src/Test/Bun.ts

@@ -1,12 +1,17 @@
 import bun from "bun:test";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
 import type { HookOptions } from "node:test";
 
 import type { AlchemyContext } from "../AlchemyContext.ts";
 import type { CompiledStack } from "../Stack.ts";
 import type { Stage } from "../Stage.ts";
+import { installLocalhostDns } from "../Util/LocalhostDns.ts";
 import * as Core from "./Core.ts";
 
+installLocalhostDns();
+
 export type MakeOptions<ROut = any> = Core.MakeOptions<ROut>;
 export type ScratchStack = Core.ScratchStack;
 export type TestEffect<A, R = never> = Core.TestEffect<A, R>;
@@ -106,7 +111,15 @@ const DEFAULT_HOOK_TIMEOUT: HookOptions = { timeout: 120_000 };
  * ```
  */
 export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
-  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options);
+  // Single scope shared across `beforeAll`, every `test`, and `afterAll`.
+  // Scoped resources in dev mode (the Cloudflare sidecar process and its
+  // workerd children) must outlive a single `Effect.runPromise` boundary,
+  // otherwise the proxy is killed the moment `beforeAll(deploy(Stack))`
+  // resolves and every later `HttpClient.get(workerUrl)` hits a dead port.
+  // The scope is closed by `destroy(...)` (or never — the next test run
+  // reclaims any leaked sidecar via the lock file).
+  const sharedScope = Scope.makeUnsafe("sequential");
+  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options, sharedScope);
 
   const test = ((name, eff, opts) => {
     bun.test(name, () => runEff(eff), opts);
@@ -130,10 +143,11 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
   ) => {
     const scratch = Core.scratchStack(options, name);
-    return Core.run(Core.withProviders(fn(scratch), options, scratch.name), {
-      ...options,
-      state: scratch.state,
-    });
+    return Core.run(
+      Core.withProviders(fn(scratch), options, scratch.name),
+      { ...options, state: scratch.state },
+      sharedScope,
+    );
   };
 
   const provider = ((name, fn, opts) => {
@@ -175,13 +189,35 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     bun.afterEach(() => runEff(eff), hookOptions);
   };
 
+  // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`
+  // for each worker. We close the shared scope only AFTER destroy completes.
+  // `Scope.close` on an already-closed scope is a no-op, so it's safe for both
+  // the destroy wrapper AND the fallback cleanup hook below to call it.
+  const closeScope = Effect.suspend(() =>
+    Scope.close(sharedScope, Exit.void),
+  ).pipe(Effect.ignore);
+
+  // Fallback cleanup: if the user never calls `destroy(Stack)` (e.g.
+  // `NO_DESTROY=1`), nothing else closes the shared scope and the sidecar
+  // child process leaks past the test process. Register an `afterAll` that
+  // closes it. We defer registration to a microtask so it runs AFTER any
+  // user-registered `afterAll` (including `destroy(Stack)`); bun runs
+  // afterAll hooks in registration order.
+  queueMicrotask(() => {
+    bun.afterAll(() => Effect.runPromise(closeScope), DEFAULT_HOOK_TIMEOUT);
+  });
+
   return {
     test,
     beforeAll,
     beforeEach,
     afterAll,
     afterEach,
-    deploy: (stack, callOpts) => Core.deploy(options, stack, callOpts),
-    destroy: (stack, callOpts) => Core.destroy(options, stack, callOpts),
+    deploy: (stack, callOpts) =>
+      Core.deploy(options, stack, { ...callOpts, scope: sharedScope }),
+    destroy: (stack, callOpts) =>
+      Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
+        Effect.ensuring(closeScope),
+      ),
   };
 };

package/src/Test/Core.ts

@@ -2,6 +2,7 @@ import { ConfigProvider } from "effect/ConfigProvider";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Scope from "effect/Scope";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 
 import { AdoptPolicy } from "../AdoptPolicy.ts";
@@ -66,9 +67,7 @@ export const resolveDev = (options: { dev?: boolean }): boolean => {
 const overrideAlchemyContext = (overrides: { dev: boolean }) =>
   Layer.effect(
     AlchemyContext,
-    AlchemyContext.asEffect().pipe(
-      Effect.map((ctx) => ({ ...ctx, ...overrides })),
-    ),
+    AlchemyContext.pipe(Effect.map((ctx) => ({ ...ctx, ...overrides }))),
   );
 
 export type TestEffect<A, Req = never> = StackEffect<A, any, Req>;
@@ -90,14 +89,22 @@ const alchemyLayer = Layer.mergeAll(LoggingCli, AlchemyContextLive);
  * registry that the user's `providers` layer populates, the platform layers,
  * and the configured state store. Adapters wrap this into runner-specific
  * thunks (`bun.test` -> `runPromise`, `it.live` -> as-is).
+ *
+ * When `scope` is provided, scoped resources (like the Cloudflare dev
+ * sidecar) survive past this effect and are tied to the lifetime of the
+ * provided scope instead. The runner is responsible for closing it.
+ *
+ * When `scope` is omitted, the effect runs with `Effect.scoped` and any
+ * scoped resources are torn down as soon as it resolves.
  */
 export const toEffect = <A>(
   effect: TestEffect<A>,
   options: MakeOptions,
-): Effect.Effect<A, any, never> =>
-  Effect.gen(function* () {
-    const base = yield* loadConfigProvider(Option.none());
-    const configProvider = withProfileOverride(base, options.profile);
+  scope?: Scope.Scope,
+): Effect.Effect<A, any, never> => {
+  const base = Effect.gen(function* () {
+    const cfg = yield* loadConfigProvider(Option.none());
+    const configProvider = withProfileOverride(cfg, options.profile);
     return yield* effect.pipe(
       provideFreshArtifactStore,
       Effect.provide(Layer.succeed(ConfigProvider, configProvider)),
@@ -112,14 +119,19 @@ export const toEffect = <A>(
     Effect.provide(options.state ?? State.localState()),
     Effect.provideService(AuthProviders, {}),
     Effect.provide(Layer.provideMerge(alchemyLayer, platformLayer)),
-    Effect.scoped,
+  );
+
+  return (
+    scope === undefined ? Effect.scoped(base) : Scope.provide(base, scope)
   ) as Effect.Effect<A, any, never>;
+};
 
 /** Promise wrapper around {@link toEffect} for `bun.test`-style runners. */
 export const run = <A>(
   effect: TestEffect<A>,
   options: MakeOptions,
-): Promise<A> => Effect.runPromise(toEffect(effect, options));
+  scope?: Scope.Scope,
+): Promise<A> => Effect.runPromise(toEffect(effect, options, scope));
 
 /**
  * Wrap an effect so it runs with `options.providers` + a placeholder Stack +
@@ -139,6 +151,7 @@ export const withProviders = <A, E, R, ROut>(
         stage: options.stage ?? "test",
         resources: {},
         bindings: {},
+        actions: {},
       }),
     ),
     Effect.provide(Layer.succeed(Stage, options.stage ?? "test")),
@@ -148,27 +161,34 @@ export const withProviders = <A, E, R, ROut>(
  * Curried `deploy` for the test factory: bakes in the configured stage and
  * adds the telemetry layer the CLI uses, so `beforeAll(deploy(Stack))` works
  * the same way as `alchemy deploy`.
+ *
+ * `scope`, when supplied, is forwarded down so the dev sidecar (and other
+ * scoped resources) lives until the caller closes it instead of dying as
+ * soon as `deploy` resolves. The test harness uses this to keep workerd
+ * alive across `beforeAll` → tests → `afterAll`.
  */
 export const deploy = <A>(
   options: MakeOptions,
   stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
-  callOptions?: { stage?: string },
+  callOptions?: { stage?: string; scope?: Scope.Scope },
 ) =>
   _deploy({
     stack: stack as Effect.Effect<CompiledStack<A>, never, any>,
     stage: callOptions?.stage ?? options.stage ?? "test",
     dev: resolveDev(options),
+    scope: callOptions?.scope,
   }).pipe(Effect.provide(TelemetryLive));
 
 export const destroy = (
   options: MakeOptions,
   stack: TestEffect<CompiledStack, Stage | AlchemyContext>,
-  callOptions?: { stage?: string },
+  callOptions?: { stage?: string; scope?: Scope.Scope },
 ) =>
   _destroy({
     stack: stack as Effect.Effect<CompiledStack, never, any>,
     stage: callOptions?.stage ?? options.stage ?? "test",
     dev: resolveDev(options),
+    scope: callOptions?.scope,
   }).pipe(Effect.provide(TelemetryLive));
 
 /**
@@ -241,6 +261,7 @@ export const scratchStack = <ROut>(
         stage,
         resources: {},
         bindings: {},
+        actions: {},
         output: {},
       }).pipe(
         Effect.flatMap(apply),
@@ -253,6 +274,7 @@ export const scratchStack = <ROut>(
             stage,
             resources: {},
             bindings: {},
+            actions: {},
           }),
         ),
         Effect.provide(Layer.succeed(Stage, stage)),

package/src/Test/Vitest.ts

@@ -1,5 +1,7 @@
 import { it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
 import {
   afterAll as vitestAfterAll,
   afterEach as vitestAfterEach,
@@ -98,8 +100,13 @@ const DEFAULT_TIMEOUT = 120_000;
  * Effect-aware tests stay first-class.
  */
 export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
-  const wrap = <A>(eff: TestEffect<A>) => Core.toEffect(eff, options);
-  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options);
+  // See `Test/Bun.ts` for the rationale: the dev sidecar must outlive a
+  // single `runPromise` boundary, so all hooks share one scope that's only
+  // closed after `destroy(...)` runs.
+  const sharedScope = Scope.makeUnsafe("sequential");
+  const wrap = <A>(eff: TestEffect<A>) =>
+    Core.toEffect(eff, options, sharedScope);
+  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options, sharedScope);
 
   const test = ((name, eff, opts) => {
     it.live(name, () => wrap(eff), timeoutOf(opts));
@@ -130,6 +137,7 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     return Core.toEffect(
       Core.withProviders(fn(scratch), options, scratch.name),
       { ...options, state: scratch.state },
+      sharedScope,
     );
   };
 
@@ -182,13 +190,34 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     vitestAfterEach(() => runEff(eff), timeoutOf(hookOptions));
   };
 
+  // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`.
+  // `Scope.close` on an already-closed scope is a no-op, so the destroy
+  // wrapper AND the fallback cleanup hook below can both call it safely.
+  const closeScope = Effect.suspend(() =>
+    Scope.close(sharedScope, Exit.void),
+  ).pipe(Effect.ignore);
+
+  // Fallback cleanup: if the user never calls `destroy(Stack)` (e.g.
+  // `NO_DESTROY=1`), nothing else closes the shared scope and the sidecar
+  // child process leaks past the test process. Register an `afterAll` that
+  // closes it. We defer registration to a microtask so it runs AFTER any
+  // user-registered `afterAll` (including `destroy(Stack)`); vitest runs
+  // afterAll hooks in registration order.
+  queueMicrotask(() => {
+    vitestAfterAll(() => Effect.runPromise(closeScope), DEFAULT_TIMEOUT);
+  });
+
   return {
     test,
     beforeAll,
     beforeEach,
     afterAll,
     afterEach,
-    deploy: (stack, callOpts) => Core.deploy(options, stack, callOpts),
-    destroy: (stack, callOpts) => Core.destroy(options, stack, callOpts),
+    deploy: (stack, callOpts) =>
+      Core.deploy(options, stack, { ...callOpts, scope: sharedScope }),
+    destroy: (stack, callOpts) =>
+      Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
+        Effect.ensuring(closeScope),
+      ),
   };
 };

package/src/Util/LocalhostDns.ts

@@ -1,22 +1,27 @@
 /**
- * Process-level DNS shim that makes `*.localhost` resolve to 127.0.0.1.
+ * Process-level DNS shim that makes `*.localhost` resolve to 127.0.0.1
+ * for any HTTP client that goes through undici (Node's global `fetch`,
+ * undici-based clients, etc.).
  *
  * Background: macOS's `getaddrinfo` does not honor RFC 6761 for arbitrary
- * `*.localhost` names; only the bare `localhost` is mapped to loopback.
- * workerd and browsers handle it themselves, but Node's undici-based fetch
- * (and Bun's libcurl-based fetch on some platforms) fails with `ENOTFOUND`
- * when calling URLs returned by the local Cloudflare worker proxy
- * (e.g. `http://my-worker.localhost:1337`).
+ * `*.localhost` names — only the bare `localhost` is mapped to loopback.
+ * The Cloudflare local proxy returns URLs like
+ * `http://my-worker.localhost:1337` and dispatches by the URL hostname,
+ * so we cannot rewrite the URL client-side to `127.0.0.1` (and `Host` is
+ * a forbidden fetch header). The fix is to make the host resolvable at
+ * the network layer.
  *
- * The proxy in `@distilled.cloud/cloudflare-runtime` dispatches by the
- * URL hostname, so we cannot rewrite the URL client-side to `127.0.0.1`
- * (and `Host` is a forbidden fetch header). The fix is to make the host
- * resolvable at the network layer.
+ * On Bun, `globalThis.fetch` is the native (Zig) implementation and does
+ * not consult undici's global dispatcher; Bun resolves `*.localhost`
+ * itself on Darwin/Linux, so this shim is effectively a no-op there for
+ * the global `fetch` and only matters if user code reaches for `undici`
+ * directly.
  *
  * Calling `installLocalhostDns()` is idempotent.
  */
 
-import { createRequire } from "node:module";
+import * as dns from "node:dns";
+import * as undici from "undici";
 
 let installed = false;
 
@@ -28,31 +33,20 @@ const isLocalhost = (hostname: string): boolean =>
 export const installLocalhostDns = (): void => {
   if (installed) return;
   installed = true;
-  // Bun resolves `*.localhost` natively via its libcurl-based fetch on
-  // Darwin and Linux, so the shim is a no-op there. If a future Bun
-  // release changes this, install via Bun's undici-compatible global
-  // dispatcher here.
-  if (typeof (globalThis as { Bun?: unknown }).Bun !== "undefined") return;
-  try {
-    const require = createRequire(import.meta.url);
-    const undici: typeof import("undici") = require("undici");
-    const dns: typeof import("node:dns") = require("node:dns");
-    undici.setGlobalDispatcher(
-      new undici.Agent({
-        connect: {
-          lookup: (hostname, options, cb: any) => {
-            if (isLocalhost(hostname)) {
-              if (options && (options as { all?: boolean }).all) {
-                return cb(null, [{ address: "127.0.0.1", family: 4 }]);
-              }
-              return cb(null, "127.0.0.1", 4);
+
+  undici.setGlobalDispatcher(
+    new undici.Agent({
+      connect: {
+        lookup: (hostname, options, cb) => {
+          if (isLocalhost(hostname)) {
+            if (options && (options as { all?: boolean }).all) {
+              return cb(null, [{ address: "127.0.0.1", family: 4 }]);
             }
-            return dns.lookup(hostname, options, cb);
-          },
+            return cb(null, "127.0.0.1", 4);
+          }
+          return dns.lookup(hostname, options, cb);
         },
-      }),
-    );
-  } catch {
-    // undici not available; nothing to do.
-  }
+      },
+    }),
+  );
 };

package/src/Util/effect.ts

@@ -27,10 +27,10 @@ export const effectClass: {
             return impl;
           }
           static [Symbol.iterator]() {
-            return new SingleShotGen(this);
+            return new SingleShotGen(this.asEffect());
           }
           static pipe(...fns: any) {
-            return pipeArguments(this.asEffect(), fns);
+            return pipeArguments(this, fns);
           }
         },
         impl,
@@ -44,9 +44,9 @@ export const taggedFunction = <
   fn: Fn,
 ): Tag & Fn => {
   const overrides = {
-    asEffect: () => tag.asEffect(),
+    asEffect: () => tag,
     [Symbol.iterator]: () => tag[Symbol.iterator](),
-    pipe: (...fns: any[]) => pipeArguments(tag.asEffect(), fns as any),
+    pipe: (...fns: any[]) => pipeArguments(tag, fns as any),
     toString: () => `${tag.toString()}.${fn.name}`,
   };
 
@@ -64,6 +64,31 @@ export const taggedFunction = <
   }) as Tag & Fn;
 };
 
+export const isYieldableEffect = (
+  value: unknown,
+): value is Effect.Effect<unknown, unknown, unknown> =>
+  Effect.isEffect(value) &&
+  typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] ===
+    "function";
+
+export type YieldableEffectLike<A = unknown, E = unknown, R = unknown> =
+  | Effect.Effect<A, E, R>
+  | {
+      asEffect: () => Effect.Effect<A, E, R>;
+      [Symbol.iterator]: () => Iterator<unknown>;
+    };
+
+export const isEffectClassLike = (
+  value: unknown,
+): value is YieldableEffectLike =>
+  typeof value === "function" &&
+  typeof (value as { asEffect?: unknown }).asEffect === "function";
+
+export const isYieldableEffectLike = (
+  value: unknown,
+): value is YieldableEffectLike =>
+  isYieldableEffect(value) || isEffectClassLike(value);
+
 export type UnwrapEffect<T> =
   T extends Effect.Effect<infer A, any, any> ? A : T;
 

package/src/Util/hash.ts

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+import * as Effect from "effect/Effect";
+
+/**
+ * Stable hash of a resolved Task input. Wrapped in `Effect.sync` so the
+ * call participates in the Effect runtime (tracing/interruption) per the
+ * Effect-platform conventions.
+ */
+export const hashInput = (input: unknown): Effect.Effect<string> =>
+  Effect.sync(() =>
+    createHash("sha256")
+      .update(JSON.stringify(input ?? null))
+      .digest("hex"),
+  );