alchemy 2.0.0-beta.60 → 2.0.0-beta.61

package/src/Docker/Container.ts

@@ -243,9 +243,14 @@ export const ContainerProvider = () =>
               ),
             );
           if (!info) return undefined;
+          // `olds.image` may be `undefined` when a `creating` row was
+          // persisted before upstream Outputs resolved — fall back to the
+          // live container's actual image.
           const attrs = toContainerAttributes(
             info,
-            normalizeImageRef(olds.image),
+            olds.image !== undefined
+              ? normalizeImageRef(olds.image)
+              : info.Config.Image,
           );
           if (output) return attrs;
           // Without prior state, only adopt a container that carries our
@@ -258,6 +263,10 @@ export const ContainerProvider = () =>
         }),
         diff: Effect.fn(function* ({ id, instanceId, news, olds }) {
           if (!isResolved(news)) return undefined;
+          // An Output-valued `image` doesn't survive a `creating`-state
+          // round-trip (it deserializes as `undefined`) — without comparable
+          // prior create args, let the engine apply its default update logic.
+          if (olds.image === undefined) return undefined;
           const oldArgs = yield* makeCreateArgs(id, olds, instanceId);
           const newArgs = yield* makeCreateArgs(id, news, instanceId);
           if (!Equal.equals(oldArgs, newArgs)) {

package/src/Drizzle/Schema.ts

@@ -189,15 +189,18 @@ export const SchemaProvider = () =>
           const nodeExecPath = yield* Effect.sync(() => process.execPath);
           const nodeModulesPath = path.join(process.cwd(), "node_modules");
 
+          // drizzle-kit globs the --schema/--out values; Windows backslashes
+          // are treated as glob escapes and match nothing, so pass forward
+          // slashes.
           const args = [
             bin,
             "generate",
             "--dialect",
             dialect === "postgres" ? "postgresql" : dialect,
             "--schema",
-            schemaPath,
+            schemaPath.replaceAll("\\", "/"),
             "--out",
-            out,
+            out.replaceAll("\\", "/"),
           ];
 
           const commandOptions = {
@@ -433,9 +436,13 @@ export const SchemaProvider = () =>
               ? drift.changed
               : drift.sqlStatements.length > 0;
           // Originally `output.out` was an absolute path, which is not portable.
-          // So, we trigger an update to migrate existing resources.
-          // This is safe because `regenerate` is idempotent.
-          return changed || path.isAbsolute(output.out)
+          // So, we trigger an update to migrate existing resources to the
+          // canonical (cwd-relative) form. This is safe because `regenerate`
+          // is idempotent. Compare against the canonical form rather than
+          // testing `isAbsolute`: on Windows a cross-drive `out` can never be
+          // relativized, so its canonical form IS absolute and an isAbsolute
+          // check would flag an update on every deploy.
+          return changed || output.out !== relativeOut(resolveOut(news))
             ? { action: "update" }
             : undefined;
         }),

package/src/Neon/Branch.ts

@@ -204,13 +204,20 @@ export const BranchProvider = () =>
       // planning engine resolves `news.project` to a plain object carrying that stable id (even when the project is being
       // updated in place). An unchanged project therefore resolves to the same string; a changed/replaced project resolves
       // to either a different string or an unresolved output, so `oldProjectId !== newProjectId` evaluates correctly.
+      // An Output-valued `project` doesn't survive a `creating`-state
+      // round-trip (it deserializes as `undefined`) — when the old project is
+      // unknown, fall through to the create/update recovery path rather than
+      // force a replacement.
       const oldProjectId =
-        output?.projectId ?? resolveProjectId(olds.project as BranchSource);
+        output?.projectId ??
+        (olds.project !== undefined
+          ? maybeResolveProjectId(olds.project as BranchSource)
+          : undefined);
       const newProjectId =
         "project" in news
           ? maybeResolveProjectId(news.project as BranchSource)
           : undefined;
-      if (oldProjectId !== newProjectId) {
+      if (oldProjectId !== undefined && oldProjectId !== newProjectId) {
         return { action: "replace" } as const;
       }
       if (!isResolved(news)) return undefined;
@@ -283,7 +290,12 @@ export const BranchProvider = () =>
         );
       }
       if (!olds?.project) return undefined;
-      const projectId = resolveProjectId(olds.project as BranchSource);
+      const projectId = maybeResolveProjectId(olds.project as BranchSource);
+      if (projectId === undefined) {
+        // The project reference survived as an object but its Output-valued
+        // `projectId` did not — there is nothing to look the branch up in.
+        return undefined;
+      }
       const name = yield* createBranchName(id, olds.name);
       const matches = yield* findBranchByName(projectId, name);
       const match = matches[0];

package/src/Output.ts

@@ -23,7 +23,15 @@ export const of = <R extends ResourceLike>(
   : RefExpr<R["Attributes"]> => {
   if (isRef(resource)) {
     const metadata = getRefMetadata(resource);
-    return new RefExpr(metadata.stack, metadata.stage, metadata.id) as any;
+    return new RefExpr(
+      metadata.stack,
+      metadata.stage,
+      metadata.id,
+      // Surface the target's resource type as a statically-known
+      // property so duck-typing classifiers (Worker env bindings)
+      // identify the ref exactly like a locally-declared resource.
+      metadata.type !== undefined ? { Type: metadata.type } : undefined,
+    ) as any;
   }
   return new ResourceExpr(resource) as any;
 };
@@ -377,6 +385,12 @@ export class RefExpr<A> extends BaseExpr<A, never> {
     public readonly stack: string | undefined,
     public readonly stage: string | undefined,
     public readonly resourceId: string,
+    /**
+     * Statically-known properties of the ref's target (currently its
+     * resource `Type`), served as literals by the proxy instead of
+     * `PropExpr`s — mirrors {@link ResourceExpr}'s `stables`.
+     */
+    readonly stables?: Record<string, any>,
   ) {
     super();
     return proxy(this);
@@ -502,7 +516,9 @@ function proxy(self: any): any {
           ? self
           : prop === inspect
             ? target[inspect]
-            : isResourceExpr(self) && self.stables && prop in self.stables
+            : (isResourceExpr(self) || isRefExpr(self)) &&
+                self.stables &&
+                prop in self.stables
               ? self.stables[prop as keyof typeof self.stables]
               : prop in self
                 ? typeof self[prop as keyof typeof self] === "function" &&

package/src/Planetscale/Postgres/PostgresRole.ts

@@ -199,8 +199,8 @@ export const PostgresRoleProvider = () =>
       if (newBranch !== oldBranch) {
         return { action: "replace" } as const;
       }
-      const newRoles = resolveInheritedRoles(news.inheritedRoles);
-      const oldRoles = output?.inheritedRoles ?? [];
+      const newRoles = [...resolveInheritedRoles(news.inheritedRoles)].sort();
+      const oldRoles = [...(output?.inheritedRoles ?? [])].sort();
       if (!deepEqual(newRoles, oldRoles)) {
         return { action: "replace" } as const;
       }

package/src/Provider.ts

@@ -102,6 +102,14 @@ export interface ProviderService<
    * @default 0
    */
   version?: number;
+  /**
+   * Legacy type names this provider also answers to. Copied from the
+   * resource class's `aliases` option by {@link succeed}/{@link effect} so
+   * state persisted under a pre-rename type (e.g. `"Cloudflare.Queue"`
+   * before the `"Cloudflare.Queues.Queue"` rename) still resolves to this
+   * provider via {@link tryFindProviderByType}.
+   */
+  aliases?: readonly string[];
   /**
    * Account-wide teardown (`alchemy unsafe nuke`) behaviour. Providers whose
    * resources can't meaningfully be deleted opt out here so nuke doesn't
@@ -275,8 +283,14 @@ export const effect = <
     LifecycleServices
   >
 > =>
-  // @ts-expect-error
-  Layer.effect(Provider(cls.Type), eff) as any;
+  Layer.effect(
+    // @ts-expect-error
+    Provider(cls.Type),
+    Effect.map(eff, (service) => ({
+      aliases: "Aliases" in cls ? cls.Aliases : undefined,
+      ...service,
+    })),
+  ) as any;
 
 export const succeed = <
   R extends ResourceLike,
@@ -310,7 +324,10 @@ export const succeed = <
   >
 > =>
   // @ts-expect-error
-  Layer.succeed(Provider(cls.Type), service);
+  Layer.succeed(Provider(cls.Type), {
+    aliases: "Aliases" in cls ? cls.Aliases : undefined,
+    ...service,
+  });
 
 export interface ProviderCollectionLike {
   kind: "ProviderCollection";
@@ -398,6 +415,20 @@ const isProviderCollectionService = (
   );
 };
 
+/**
+ * Structural check for a {@link ProviderService} living in the Effect
+ * context. Providers are keyed by their canonical resource type; when
+ * searching for a legacy alias, the tag key won't match, so lookup has to
+ * recognize provider services by shape.
+ */
+const isProviderService = (value: unknown): value is ProviderService =>
+  typeof value === "object" &&
+  value !== null &&
+  "reconcile" in value &&
+  typeof (value as ProviderService).reconcile === "function" &&
+  "delete" in value &&
+  typeof (value as ProviderService).delete === "function";
+
 export const findProviderByType: {
   <R extends ResourceLike>(
     resourceType: R["Type"],
@@ -448,5 +479,24 @@ export const tryFindProviderByType: {
       }
     }
   }
+
+  // State persisted before a type rename carries the legacy name, so no
+  // provider is keyed under it. Fall back to a provider that declares the
+  // name in its `aliases` — scanning both bare Provider layers and the
+  // members of every ProviderCollection.
+  for (const value of context.mapUnsafe.values()) {
+    if (isProviderCollectionService(value)) {
+      for (const provider of Object.values(value.providers)) {
+        if (provider.aliases?.includes(resourceType)) {
+          return Option.some(provider);
+        }
+      }
+    } else if (
+      isProviderService(value) &&
+      value.aliases?.includes(resourceType)
+    ) {
+      return Option.some(value);
+    }
+  }
   return Option.none();
 }) as any;

package/src/Ref.ts

@@ -20,6 +20,14 @@ export interface RefMetadata<R extends ResourceLike> {
   id: R["LogicalId"];
   stack?: string;
   stage?: string;
+  /**
+   * The resource type of the ref's target (e.g.
+   * `"Cloudflare.KV.Namespace"`). Known statically — `MyResource.ref`
+   * carries its own type — so duck-typing classifiers (Worker env
+   * bindings, capability helpers) that read `.Type` can identify a ref
+   * exactly like a locally-declared resource.
+   */
+  type?: string;
 }
 
 export const ref = <R extends ResourceLike>(
@@ -31,6 +39,7 @@ export const ref = <R extends ResourceLike>(
     stack?: string;
     stage?: string;
   } = {},
+  type?: string,
 ): Ref<R> => {
   const ref = new Proxy(
     {},
@@ -41,6 +50,7 @@ export const ref = <R extends ResourceLike>(
             stack,
             stage,
             id,
+            type,
           } satisfies RefMetadata<R>;
         }
         return (Output.of(ref) as any)[prop];

package/src/Resource.ts

@@ -45,6 +45,13 @@ export interface ResourceClassLike<R extends ResourceLike> {
   Props: R["Props"];
   Self: Self<R>;
   Provider: Provider<R>;
+  /**
+   * Legacy type names this resource was previously registered under
+   * (see {@link ResourceOptions.aliases}). Copied onto the
+   * `ProviderService` by `Provider.succeed`/`Provider.effect` so provider
+   * lookup can resolve state persisted under a pre-rename type.
+   */
+  Aliases?: readonly string[];
 }
 
 export type ResourceClass<R extends ResourceLike> = ResourceConstructor<
@@ -54,6 +61,7 @@ export type ResourceClass<R extends ResourceLike> = ResourceConstructor<
   Effect.Effect<ResourceConstructor<R>> & {
     Self: Self<R>;
     Provider: Provider<R>;
+    Aliases: readonly string[] | undefined;
     ref(
       id: string,
       options?: { stage?: string; stack?: string },
@@ -70,6 +78,7 @@ export type ResourceClassWithMethods<
   Effect.Effect<ResourceConstructor<R>> & {
     Self: Self<R>;
     Provider: Provider<R>;
+    Aliases: readonly string[] | undefined;
     ref(
       id: string,
       options?: { stage?: string; stack?: string },
@@ -133,6 +142,28 @@ export const isResource = (value: any): value is ResourceLike => {
   return typeof value === "object" && value !== null && "Type" in value;
 };
 
+/**
+ * Does `value` reference an instance of the resource type `type` —
+ * either a locally-declared resource or a `Resource.ref(...)` to one?
+ *
+ * Two constraints that ad-hoc guards get wrong for refs, which resolve
+ * to Output-expression proxies:
+ *
+ * - Read `.Type` via property access (never `in`): the proxy answers
+ *   property reads with statically-known values but deliberately does
+ *   not report key existence (so {@link isResource} keeps routing refs
+ *   through Output resolution instead of the upstream-node lookup).
+ * - Accept `typeof value === "function"`: the proxy's target is
+ *   callable (it needs an `apply` trap), so refs are not `"object"`.
+ *
+ * Either mistake silently rejects refs — in a Worker `env` that
+ * degrades the binding to a plain JSON var.
+ */
+export const isResourceOfType = (value: unknown, type: string): boolean =>
+  (typeof value === "object" || typeof value === "function") &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === type;
+
 export type Resource<
   Type extends string = any,
   Props extends object | undefined = any,
@@ -162,6 +193,23 @@ export interface ResourceOptions {
    * @default "destroy"
    */
   defaultRemovalPolicy?: RemovalPolicy["Service"];
+  /**
+   * Legacy type names this resource was previously registered under.
+   *
+   * When a resource type is renamed (e.g. `"Cloudflare.Queue"` →
+   * `"Cloudflare.Queues.Queue"`), state persisted under the old name must
+   * still resolve to this resource's provider. Listing the old names here
+   * makes provider lookup fall back from the legacy name to this type, so
+   * existing stacks keep planning, updating, and deleting cleanly across
+   * the rename. The state row migrates to the new type on its next write.
+   *
+   * ```ts
+   * export const Queue = Resource<Queue>("Cloudflare.Queues.Queue", {
+   *   aliases: ["Cloudflare.Queue"],
+   * });
+   * ```
+   */
+  aliases?: string[];
 }
 
 /**
@@ -312,11 +360,12 @@ export function Resource<R extends ResourceLike>(
       id: string,
       options?: { stage?: string; stack?: string },
     ): Effect.Effect<R> =>
-      Effect.succeed(Output.of(makeRef<R>(id, options)) as unknown as R),
+      Effect.succeed(Output.of(makeRef<R>(id, options, type)) as unknown as R),
 
     Type: type,
     Provider: ProviderTag,
     Self: self,
+    Aliases: options?.aliases,
   };
 
   const ResourceClass = Object.assign(

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/concepts/state-store for available state stores.`,
+                `See https://v2.alchemy.run/state-store for available state stores.`,
             ),
           );
         }

package/src/State/HttpStateStore.ts

@@ -59,10 +59,15 @@ export const checkHttpStateStoreAuth = ({
       Effect.retry({
         while: (error) =>
           error._tag === "HttpClientError" &&
-          !!error.response &&
-          // worker can 404 for a bit on first deploy
-          (error.response.status === 404 || error.response.status >= 500),
-        schedule: Schedule.fixed(200),
+          // transport-level failures (no response — DNS, TCP reset, TLS,
+          // "fetch failed") are as transient as the post-deploy 404s
+          (!error.response ||
+            // worker can 404 for a bit on first deploy
+            error.response.status === 404 ||
+            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))),
       }),
     );
   });
@@ -226,6 +231,43 @@ const retryTransient = <A, Err, Req>(eff: Effect.Effect<A, Err, Req>) =>
     ),
   });
 
+/**
+ * Human-readable description of a state-store client failure.
+ *
+ * Several of the errors the HTTP client can raise carry an empty
+ * `message` (e.g. the no-content `Unauthorized` the store returns on a
+ * bad bearer token), which used to surface as a blank
+ * `StateStoreError` with nothing to act on. Always produce a
+ * non-empty message: prefer the error's own message, fall back to its
+ * `_tag`/name, and append the HTTP status and any distinct `cause`
+ * message when available.
+ */
+export const describeStateStoreFailure = (e: unknown): string => {
+  if (!(e instanceof Error)) return String(e);
+  const tag = (e as { _tag?: unknown })._tag;
+  let message =
+    e.message.trim() ||
+    (typeof tag === "string" ? tag : undefined) ||
+    e.name ||
+    "Unknown error";
+  if (typeof tag === "string" && tag.startsWith("Unauthorized")) {
+    message =
+      "State store rejected the request as unauthorized. " +
+      "The stored state-store credentials may be stale — run 'alchemy login' to refresh them.";
+  }
+  const status = (e as { response?: { status?: unknown } }).response?.status;
+  if (typeof status === "number" && !message.includes(String(status))) {
+    message += ` (HTTP ${status})`;
+  }
+  if (e.cause instanceof Error) {
+    const causeMessage = e.cause.message.trim();
+    if (causeMessage && !message.includes(causeMessage)) {
+      message += ` — caused by: ${causeMessage}`;
+    }
+  }
+  return message;
+};
+
 /** Collapse any client failure into a {@link StateStoreError}. */
 const mapStateStoreError = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
   eff.pipe(
@@ -234,7 +276,7 @@ const mapStateStoreError = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
     Effect.catch((e: E) =>
       Effect.fail(
         new StateStoreError({
-          message: e instanceof Error ? e.message : String(e),
+          message: describeStateStoreFailure(e),
           cause: e instanceof Error ? e : undefined,
         }),
       ),