alchemy 2.0.0-beta.84 → 2.0.0-beta.85

package/src/Stack.ts

@@ -1,23 +1,21 @@
 import type { ConfigError } from "effect/Config";
-import { ConfigProvider } from "effect/ConfigProvider";
 import * as Context from "effect/Context";
-import type { Crypto } from "effect/Crypto";
+import type { Digest } from "effect/crypto/Digest";
+import type { SecureRandom } from "effect/crypto/SecureRandom";
 import * as Effect from "effect/Effect";
 import { FileSystem } from "effect/FileSystem";
-import * as FetchHttpClient from "effect/http/FetchHttpClient";
 import type { HttpClient } from "effect/http/HttpClient";
 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 { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
-import * as Scope from "effect/Scope";
+import type * as Scope from "effect/Scope";
 import type { ActionLike } from "./Action.ts";
-import { AlchemyContext, AlchemyContextLive } from "./AlchemyContext.ts";
-import { type ArtifactStore, provideFreshArtifactStore } from "./Artifacts.ts";
-import { AuthProviders } from "./Auth/AuthProvider.ts";
-import { CredentialsStore, CredentialsStoreLive } from "./Auth/Credentials.ts";
-import { ProfileStore, ProfileStoreLive } from "./Auth/Profile.ts";
+import type { AlchemyContext } from "./AlchemyContext.ts";
+import type { ArtifactStore } from "./Artifacts.ts";
+import type { CredentialsStore } from "./Auth/Credentials.ts";
+import type { ProfileStore } from "./Auth/Profile.ts";
+import { AuthProvidersLive, type AuthProviders } from "./Auth/Registry.ts";
 import type { Input, InputProps } from "./Input.ts";
 // Type-only: with verbatimModuleSyntax a value import would survive emit and
 // drag the terminal helpers (node:tty, Sigil's ansi helpers) into every unbundled
@@ -30,17 +28,17 @@ import type { SecretsEntry, SecretsOption } from "./Secrets/Provider.ts";
 import { StackContext } from "./StackContext.ts";
 import { Stage } from "./Stage.ts";
 import type { State } from "./State/State.ts";
-import { loadConfigProvider, stackConfigLayer } from "./Util/ConfigProvider.ts";
+import { stackConfigLayer } from "./Util/ConfigProvider.ts";
 import { effectClass, taggedFunction } from "./Util/effect.ts";
-import { fileLogger } from "./Util/FileLogger.ts";
-import { PlatformServices } from "./Util/PlatformServices.ts";
+import type { PlatformServices } from "./Util/PlatformServices.ts";
 
 export type StackServices =
   | Stack
   | Stage
   | Scope.Scope
   | FileSystem
-  | Crypto
+  | Digest
+  | SecureRandom
   | Path
   | AlchemyContext
   | HttpClient
@@ -138,6 +136,14 @@ export type ConfiguredStackMeta<Req = never> = {
   readonly stackName: string;
 } & StackProps<Req>;
 
+/**
+ * What `Alchemy.Stack(...)` returns, and what an `alchemy.run.ts`
+ * default-exports: the stack program, not yet run, with its providers,
+ * state store, and secrets attached.
+ */
+export type ConfiguredStack<Output, Req> = Effect.Effect<CompiledStack<Output>, ConfigError> &
+  ConfiguredStackMeta<Req>;
+
 export const Stack: Context.ServiceClass<Stack, "Stack", Omit<StackSpec, "output">> & {
   make<A, Req>(
     stack: {
@@ -158,16 +164,16 @@ export const Stack: Context.ServiceClass<Stack, "Stack", Omit<StackSpec, "output
       };
     };
   };
-  <Self, Shape>(): {
+  <Self, Shape, Stages extends string = string>(): {
     (stackName: string): Effect.Effect<Self> & {
       new (_: never): Output.ToOutput<Shape>;
       readonly stackName: string;
       make: <A, Req>(
         options: StackProps<NoInfer<Req>>,
         effect: Effect.Effect<A, ConfigError, Req>,
-      ) => Effect.Effect<CompiledStack<A>, ConfigError> & ConfiguredStackMeta<NoInfer<Req>>;
+      ) => ConfiguredStack<A, NoInfer<Req>>;
       stage: {
-        [stage: string]: Effect.Effect<Self>;
+        readonly [S in Stages]: Effect.Effect<Self>;
       };
     };
   };
@@ -175,7 +181,7 @@ export const Stack: Context.ServiceClass<Stack, "Stack", Omit<StackSpec, "output
     stackName: string,
     options: StackProps<NoInfer<Req>>,
     eff: Effect.Effect<A, ConfigError, Req>,
-  ): Effect.Effect<CompiledStack<A>, ConfigError> & ConfiguredStackMeta<NoInfer<Req>>;
+  ): ConfiguredStack<A, NoInfer<Req>>;
 } = Object.assign(
   taggedFunction(
     StackContext,
@@ -256,67 +262,96 @@ export const StackName = Stack.use((stack) => Effect.succeed(stack.name));
 
 export interface MakeStackProps<ROut = never> {
   name: string;
-  providers: Layer.Layer<ROut, never, StackServices>;
-  state: Layer.Layer<State, never, StackServices>;
+  /** Required; {@link make} dies with setup guidance when it is missing. */
+  providers?: Layer.Layer<ROut, never, StackServices>;
+  /** Required; {@link make} dies with setup guidance when it is missing. */
+  state?: Layer.Layer<State, never, StackServices>;
   /** Opt in to secret providers. When omitted, existing configuration is preserved. */
   secrets?: StackSecrets;
   /** @internal */
   stack?: StackSpec;
 }
 
-export const make =
-  <ROut = never>(options: MakeStackProps<ROut>) =>
-  <A, Err = never, Req extends ROut | StackServices = never>(effect: Effect.Effect<A, Err, Req>) =>
-    Effect.scope.pipe(
-      Effect.flatMap((scope) => {
-        if (options.state == null) {
-          return Effect.die(
-            new Error(
-              `Stack "${options.name}" is missing a state store. ` +
-                `Add a \`state\` layer to the stack options, e.g.:\n` +
-                `  Alchemy.Stack("${options.name}", {\n` +
-                `    providers: Cloudflare.providers(),\n` +
-                `    state: Cloudflare.state(), // <-- required\n` +
-                `  }, ...)\n` +
-                `See https://alchemy.run/state-store for available state stores.`,
-            ),
-          );
-        }
-        if (options.providers == null) {
-          return Effect.die(
-            new Error(
-              `Stack "${options.name}" is missing a providers layer. ` +
-                `Add a \`providers\` layer to the stack options, e.g.:\n` +
-                `  Alchemy.Stack("${options.name}", {\n` +
-                `    providers: Cloudflare.providers(), // <-- required\n` +
-                `    state: Cloudflare.state(),\n` +
-                `  }, ...)`,
-            ),
-          );
-        }
-        return options.providers.pipe(
-          Layer.provideMerge(options.state),
-          Layer.provideMerge(stackConfigLayer(options.secrets)),
-          Layer.provideMerge(
-            Layer.effect(
-              Stack,
-              Stage.pipe(
-                Effect.map(
-                  (stage) =>
-                    options.stack ?? {
-                      name: options.name,
-                      stage,
-                      resources: {},
-                      bindings: {},
-                      actions: {},
-                    },
-                ),
+/**
+ * The scope a stack's state store is built into when it must close sooner
+ * than the rest of the stack. A store holds its stack's lease until its scope
+ * closes, so `evalStack` (`EvalStack.ts`) gives it one per call even when the caller
+ * keeps providers alive in a longer scope.
+ */
+export class StateScope extends Context.Service<StateScope, Scope.Scope>()(
+  "alchemy/Stack/StateScope",
+) {}
+
+/**
+ * Build a stack's providers, state store, secrets config and `Stack` spec,
+ * without running its program. Destroy needs nothing more: it plans from state
+ * alone, and every row records the provider mode that deletes it.
+ */
+export const build = <ROut = never>(options: MakeStackProps<ROut>) =>
+  Effect.all([Effect.scope, Effect.serviceOption(StateScope)]).pipe(
+    Effect.flatMap(([scope, stateScope]) => {
+      if (options.state == null) {
+        return Effect.die(
+          new Error(
+            `Stack "${options.name}" is missing a state store. ` +
+              `Add a \`state\` layer to the stack options, e.g.:\n` +
+              `  Alchemy.Stack("${options.name}", {\n` +
+              `    providers: Cloudflare.providers(),\n` +
+              `    state: Cloudflare.state(), // <-- required\n` +
+              `  }, ...)\n` +
+              `See https://alchemy.run/state-store for available state stores.`,
+          ),
+        );
+      }
+      if (options.providers == null) {
+        return Effect.die(
+          new Error(
+            `Stack "${options.name}" is missing a providers layer. ` +
+              `Add a \`providers\` layer to the stack options, e.g.:\n` +
+              `  Alchemy.Stack("${options.name}", {\n` +
+              `    providers: Cloudflare.providers(), // <-- required\n` +
+              `    state: Cloudflare.state(),\n` +
+              `  }, ...)`,
+          ),
+        );
+      }
+      const state = options.state;
+      return options.providers.pipe(
+        Layer.provideMerge(
+          Option.match(stateScope, {
+            onNone: () => state,
+            onSome: (stateScope) => Layer.effectContext(Layer.buildWithScope(state, stateScope)),
+          }),
+        ),
+        Layer.provideMerge(stackConfigLayer(options.secrets)),
+        Layer.provideMerge(
+          Layer.effect(
+            Stack,
+            Stage.pipe(
+              Effect.map(
+                (stage) =>
+                  options.stack ?? {
+                    name: options.name,
+                    stage,
+                    resources: {},
+                    bindings: {},
+                    actions: {},
+                  },
               ),
             ),
           ),
-          Layer.buildWithScope(scope),
-        );
-      }),
+        ),
+        Layer.provideMerge(AuthProvidersLive),
+        Layer.buildWithScope(scope),
+      );
+    }),
+  );
+
+/** Build a stack's services with {@link build}, then run its program under them. */
+export const make =
+  <ROut = never>(options: MakeStackProps<ROut>) =>
+  <A, Err = never, Req extends ROut | StackServices = never>(effect: Effect.Effect<A, Err, Req>) =>
+    build(options).pipe(
       Effect.flatMap((context) =>
         Effect.all([effect, Stack, Effect.context<ROut | StackServices>()]).pipe(
           Effect.map(([output, stack, services]): CompiledStack<A, ROut | StackServices> => ({
@@ -329,71 +364,14 @@ export const make =
       ),
     );
 
+/** What `Alchemy.Stack(...)` attaches to the stack it returns: everything but its program. */
+export interface StackDefinition<ROut = never> {
+  readonly stackName: string;
+  readonly providers?: Layer.Layer<ROut, never, StackServices>;
+  readonly state?: Layer.Layer<State, never, StackServices>;
+  readonly secrets?: StackSecrets;
+}
+
 export const CurrentStack = Effect.serviceOption(Stack)
 
   .pipe(Effect.map(Option.getOrUndefined));
-
-const platform = Layer.mergeAll(
-  PlatformServices,
-  FetchHttpClient.layer,
-  Logger.layer([fileLogger("out")], { mergeWithExisting: true }),
-  Layer.provide(ProfileStoreLive, PlatformServices),
-  Layer.provide(CredentialsStoreLive, PlatformServices),
-);
-// override alchemy state store, CLI/reporting, state, and Config
-const alchemy = (overrides?: { dev?: boolean }) =>
-  Layer.mergeAll(
-    // optional
-    overrides?.dev
-      ? Layer.provide(
-          Layer.effect(
-            AlchemyContext,
-            AlchemyContext.useSync((ctx) => ({ ...ctx, dev: overrides.dev! })),
-          ),
-          AlchemyContextLive,
-        )
-      : AlchemyContextLive,
-  );
-
-export const evalStack = <A, B, StackErr, Err, Req>(
-  effect: StackEffect<CompiledStack<A>, StackErr, Stage | AlchemyContext>,
-  fn: (stack: CompiledStack<A>) => Effect.Effect<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;
-  },
-) => {
-  const body = Effect.gen(function* () {
-    const stack = yield* effect;
-    const configProvider = yield* loadConfigProvider(Option.none());
-    return yield* fn(stack).pipe(
-      provideFreshArtifactStore,
-      Effect.provide(
-        Layer.succeedContext(stack.services).pipe(
-          Layer.provideMerge(Layer.succeed(ConfigProvider, configProvider)),
-        ),
-      ),
-    );
-  }).pipe(
-    Effect.provide(
-      Layer.effect(
-        AuthProviders,
-        Effect.serviceOption(AuthProviders).pipe(Effect.map(Option.getOrElse(() => ({})))),
-      ).pipe(
-        Layer.provideMerge(Layer.succeed(Stage, options.stage)),
-        Layer.provideMerge(Layer.provideMerge(alchemy({ dev: options.dev }), platform)),
-      ),
-    ),
-  );
-
-  return options.scope === undefined ? Effect.scoped(body) : Scope.provide(body, options.scope);
-};

package/src/State/BucketState.ts

@@ -40,6 +40,9 @@ const OUTPUT_FILE = "__stack_output__.json";
  * the lock outlives the objects it was guarding; the store deletes it on
  * close.
  */
+/** The lease token `alchemy state migrate` leaves on a stage it moved to DynamoDB. */
+const MIGRATED_TOKEN = "migrated:dynamodb";
+
 const LEASE_FILE = "__lease__.json";
 
 /** How long a lease stays valid without a refresh. */
@@ -106,6 +109,12 @@ export interface BucketStateOptions {
   readonly objects: Effect.Effect<BucketObjects, StateStoreError>;
 }
 
+/**
+ * Tokens of the leases this process holds, so a conflict with one of them
+ * can say the holder is an earlier, still-open build in the same process.
+ */
+const heldInProcess = new Set<string>();
+
 interface LeaseRecord {
   readonly token: string;
   readonly expiresAt: number;
@@ -182,7 +191,7 @@ export const makeBucketState = (options: BucketStateOptions) =>
       use((o) => o.read(key)).pipe(
         Effect.flatMap((object) =>
           object === undefined
-            ? Effect.succeed(undefined)
+            ? Effect.undefined
             : Effect.try({
                 try: () => JSON.parse(object.text, reviveState) as T,
                 catch: (cause) =>
@@ -208,9 +217,14 @@ export const makeBucketState = (options: BucketStateOptions) =>
         ),
       );
 
-    const heldError = (stack: string, stage: string) =>
+    const heldError = (stack: string, stage: string, holder: string | undefined) =>
+      // The message always starts "another deploy holds": callers match on it
+      // (the AWS migration tells a held stage from a failed one by it).
       new StateStoreError({
-        message: `another deploy holds the ${options.label} state lock '${stack}/${stage}'`,
+        message:
+          holder !== undefined && heldInProcess.has(holder)
+            ? `another deploy holds the ${options.label} state lock '${stack}/${stage}': this process holds it, from an earlier operation on this stage that is still open. Run each operation in its own Effect.scoped so its build closes first.`
+            : `another deploy holds the ${options.label} state lock '${stack}/${stage}'`,
       });
 
     const lostError = (stack: string, stage: string) =>
@@ -240,16 +254,22 @@ export const makeBucketState = (options: BucketStateOptions) =>
         if (version === undefined) {
           const existing = yield* readLease(key);
           const stillHeld = existing === undefined || existing.record.expiresAt > now;
+          if (existing?.record.token === MIGRATED_TOKEN) {
+            return yield* new StateStoreError({
+              message: `${heldError(stack, stage, undefined).message}: the stage moved to a DynamoDB state store. Deploy it with a version of alchemy that has AWS.state() on DynamoDB, or run 'alchemy state migrate --rollback' with that version to move it back.`,
+            });
+          }
           if (stillHeld) {
-            return yield* Effect.fail(heldError(stack, stage));
+            return yield* heldError(stack, stage, existing?.record.token);
           }
           const replaced = yield* putLease(key, fresh, { ifVersion: existing.version });
           if (replaced === undefined) {
-            return yield* Effect.fail(heldError(stack, stage));
+            return yield* heldError(stack, stage, undefined);
           }
           version = replaced;
         }
 
+        heldInProcess.add(token);
         const cursor = { version, lost: false };
         const gate = Semaphore.makeUnsafe(1);
 
@@ -286,16 +306,29 @@ export const makeBucketState = (options: BucketStateOptions) =>
           1,
         )(
           Effect.gen(function* () {
-            if (cursor.lost) return yield* Effect.fail(lostError(stack, stage));
+            if (cursor.lost) return yield* lostError(stack, stage);
             const existing = yield* readLease(key);
-            const observedAt = yield* Clock.currentTimeMillis;
-            const leaseLost =
-              existing === undefined ||
-              existing.record.token !== token ||
-              existing.record.expiresAt <= observedAt;
-            if (leaseLost) {
+            if (existing === undefined || existing.record.token !== token) {
               cursor.lost = true;
-              return yield* Effect.fail(lostError(stack, stage));
+              return yield* lostError(stack, stage);
+            }
+            const observedAt = yield* Clock.currentTimeMillis;
+            if (existing.record.expiresAt <= observedAt) {
+              // The lease lapsed without anyone taking it: a refresh queued
+              // behind a large deploy's writes missed its window. Take it
+              // back at the version we read, so a deploy that took it in
+              // the meantime wins and this one stops.
+              const reclaimed = yield* putLease(
+                key,
+                { token, expiresAt: observedAt + LEASE_TTL_MS },
+                { ifVersion: existing.version },
+              );
+              if (reclaimed === undefined) {
+                cursor.lost = true;
+                return yield* lostError(stack, stage);
+              }
+              cursor.version = reclaimed;
+              return;
             }
             cursor.version = existing.version;
           }),
@@ -311,6 +344,7 @@ export const makeBucketState = (options: BucketStateOptions) =>
           )(
             Effect.gen(function* () {
               cursor.lost = true;
+              heldInProcess.delete(token);
               // Read the version we actually hold. A refresh that landed
               // after the cursor was last stored would make a release
               // against the old version a no-op, and the lease would stay.
@@ -393,14 +427,12 @@ export const makeBucketState = (options: BucketStateOptions) =>
         verifyHeldLeases.pipe(Effect.andThen(listChildren(`${prefix}${stack}/`))),
       get: (request) => guarded(request, readJson<PersistedState>(resourceKey(request))),
       getReplacedResources: Effect.fn(function* (request) {
-        return (yield* Effect.all(
-          (yield* state.list(request)).map((fqn) =>
-            state.get({
-              stack: request.stack,
-              stage: request.stage,
-              fqn,
-            }),
-          ),
+        return (yield* Effect.forEach(yield* state.list(request), (fqn) =>
+          state.get({
+            stack: request.stack,
+            stage: request.stage,
+            fqn,
+          }),
         )).filter((r) => r?.status === "replaced");
       }),
       set: (request) =>

package/src/State/LocalState.ts

@@ -110,7 +110,7 @@ export const makeLocalState = () =>
 
     const ensure = (dir: string) =>
       created.has(dir)
-        ? Effect.succeed(void 0)
+        ? Effect.void
         : fs
             .makeDirectory(dir, { recursive: true })
             .pipe(Effect.tap(() => Effect.sync(() => created.add(dir))));
@@ -134,14 +134,12 @@ export const makeLocalState = () =>
           recover,
         ),
       getReplacedResources: Effect.fn(function* (request) {
-        return (yield* Effect.all(
-          (yield* state.list(request)).map((fqn) =>
-            state.get({
-              stack: request.stack,
-              stage: request.stage,
-              fqn,
-            }),
-          ),
+        return (yield* Effect.forEach(yield* state.list(request), (fqn) =>
+          state.get({
+            stack: request.stack,
+            stage: request.stage,
+            fqn,
+          }),
         )).filter((r) => r?.status === "replaced");
       }),
       set: (request) =>

package/src/State/Provisioning.ts

@@ -28,10 +28,17 @@ export interface StoreRef {
   readonly name?: string;
   /** e.g. `Cloudflare State Store 'alchemy-state-store'`. */
   readonly label: string;
+  /**
+   * Only the stack's config describes this store, e.g. a custom Worker or
+   * bucket name or a pinned account, so `--backend` can't address it.
+   */
+  readonly configured?: boolean;
 }
 
 const required = (store: StoreRef, action: "bootstrap" | "upgrade", problem: string) => {
-  const command = `alchemy state bootstrap --backend ${store.backend}${store.name ? ` --name ${store.name}` : ""}`;
+  const command = store.configured
+    ? "alchemy state bootstrap"
+    : `alchemy state bootstrap --backend ${store.backend}${store.name ? ` --name ${store.name}` : ""}`;
   return new StateStoreError({
     message: `${store.label} ${problem}. Run '${command} --profile <your-ci-profile>' first, or pass --yes.`,
     requires: { action, command },

package/src/State/ResourceState.ts

@@ -57,6 +57,8 @@ interface BaseResourceState {
   removalPolicy?: RemovalPolicy["Service"];
   /** Attr-less lookup could recover the predecessor migrated away from this FQN. */
   adoptionBlocked?: "migrated-fqn";
+  /** Unresolved props were stripped from this attr-less checkpoint; they cannot identify it. */
+  propsIncomplete?: true;
   /**
    * The {@link ProviderMode} this resource was last reconciled with.
    *

package/src/State/State.ts

@@ -131,4 +131,34 @@ export interface StateService {
     stage: string;
     value: unknown;
   }): Effect.Effect<unknown, StateStoreError, never>;
+  /**
+   * Move stages into this store from the one it replaces, or back with
+   * `rollback`, for stores that replace another. Idempotent: run it again
+   * to finish what a failure or a blocked stage left.
+   */
+  migrate?(
+    request: StateMigrationRequest,
+  ): Effect.Effect<ReadonlyArray<StateMigration>, StateStoreError, never>;
+}
+
+/** Which stages {@link StateService.migrate} moves. */
+export interface StateMigrationRequest {
+  /** Only this stack's stages. */
+  readonly stack?: string;
+  /** Only stages of this name. */
+  readonly stage?: string;
+  /** Move stages back to the store this one replaces. */
+  readonly rollback?: boolean;
+}
+
+/** What {@link StateService.migrate} did with one stage. */
+export interface StateMigration {
+  readonly stack: string;
+  readonly stage: string;
+  /** e.g. `migrated`, `already-migrated`, `rolled-back`, `blocked` or `failed`. */
+  readonly status: string;
+  /** Records moved. */
+  readonly records?: number;
+  /** Why a stage was not moved. */
+  readonly reason?: string;
 }

package/src/State/StateEncoding.ts

@@ -1,6 +1,7 @@
 import * as Duration from "effect/Duration";
 import * as Redacted from "effect/Redacted";
 import { isResource } from "../Resource.ts";
+import { base64ToBytes, bytesToBase64 } from "../Util/base64.ts";
 
 /**
  * JSON marker used to tag a `Redacted<T>` value when writing state.
@@ -27,6 +28,14 @@ export const DURATION_MARKER = "__duration__";
  */
 export const DATE_MARKER = "__date__";
 
+/**
+ * JSON marker used to tag a byte array (`Uint8Array`) when writing state.
+ * The reviver rebuilds a real `Uint8Array`, so a byte-valued prop (a WAF
+ * byte-match string, a zip) read back out of persisted state is the same
+ * value the program declares — instead of an index-keyed object.
+ */
+export const BYTES_MARKER = "__bytes__";
+
 const decodeDate = (encoded: unknown): Date | undefined => {
   if (typeof encoded !== "string") return undefined;
   const date = new Date(encoded);
@@ -103,6 +112,9 @@ export const encodeState = (value: unknown): unknown => {
   if (value instanceof Date) {
     return { [DATE_MARKER]: value.toJSON() };
   }
+  if (value instanceof Uint8Array) {
+    return { [BYTES_MARKER]: bytesToBase64(value) };
+  }
   if (isResource(value)) {
     return {
       id: value.LogicalId,
@@ -144,6 +156,13 @@ export const reviveState = (_key: string, value: unknown): unknown => {
       const decoded = decodeDate(obj[DATE_MARKER]);
       if (decoded !== undefined) return decoded;
     }
+    if (
+      BYTES_MARKER in obj &&
+      Object.keys(obj).length === 1 &&
+      typeof obj[BYTES_MARKER] === "string"
+    ) {
+      return base64ToBytes(obj[BYTES_MARKER]);
+    }
   }
   return value;
 };
@@ -171,6 +190,9 @@ export const reviveStateRecursive = (value: unknown): unknown => {
     const decoded = decodeDate(obj[DATE_MARKER]);
     if (decoded !== undefined) return decoded;
   }
+  if (keys.length === 1 && keys[0] === BYTES_MARKER && typeof obj[BYTES_MARKER] === "string") {
+    return base64ToBytes(obj[BYTES_MARKER]);
+  }
   const result: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(obj)) {
     result[k] = reviveStateRecursive(v);

package/src/State/index.ts

@@ -1,7 +1,7 @@
 // PostgresState is intentionally NOT re-exported here: this barrel is pulled
 // into worker bundles via the core engine, and PostgresState loads
-// "@effect/sql-pg" (and through it "pg", which is Node-only). Deep-import it
-// instead: `@alchemy.run/sql/PostgresState`.
+// "@effect/sql-pg", which opens sockets through Node's `net`/`tls`.
+// Deep-import it instead: `@alchemy.run/sql/PostgresState`.
 export * from "./Export.ts";
 export * from "./HttpStateApi.ts";
 export * from "./HttpStateStore.ts";