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

package/src/Cloudflare/D1/QueryDatabaseLocal.ts

@@ -0,0 +1,66 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { Credentials } from "../Credentials.ts";
+import type { Database } from "./Database.ts";
+import { QueryDatabase } from "./QueryDatabase.ts";
+import {
+  type D1Auth,
+  makeHttpQueryDatabaseClient,
+} from "./QueryDatabaseHttpClient.ts";
+
+/**
+ * Local implementation of the {@link QueryDatabase} binding — queries D1 over
+ * the Cloudflare HTTP API using the **current credentials** instead of a native
+ * Worker binding (`QueryDatabaseBinding`) or a scoped API token.
+ *
+ * Provide it on an {@link Action} (or any deploy-time Effect) so you can talk to
+ * a D1 database with the same `prepare`/`exec`/`batch` client you'd use inside a
+ * Worker:
+ *
+ * @example Seeding a database from an Action
+ * ```typescript
+ * const Seed = Alchemy.Action(
+ *   "Seed",
+ *   Effect.gen(function* () {
+ *     const db = yield* Cloudflare.D1.QueryDatabase(database);
+ *     return Effect.fn(function* () {
+ *       yield* db.exec("CREATE TABLE IF NOT EXISTS users (id TEXT, name TEXT)");
+ *       yield* db
+ *         .prepare("INSERT INTO users (id, name) VALUES (?, ?)")
+ *         .bind("1", "Ada")
+ *         .run();
+ *     });
+ *   }).pipe(Effect.provide(Cloudflare.D1.QueryDatabaseLocal)),
+ * );
+ * ```
+ *
+ * The database id is resolved at apply time through the ambient
+ * {@link RuntimeContext} (in an Action, that's the resolve context the engine
+ * provides around the body), so `QueryDatabase(database)` works even though the
+ * database is created in the same deploy.
+ */
+export const QueryDatabaseLocal = Layer.effect(
+  QueryDatabase,
+  Effect.gen(function* () {
+    // Account + credentials are ambient during stack-eval (the stack's
+    // providers layer). Capture the full context so the HTTP query ops run
+    // with the current credentials — no `host.bind`, no minted token.
+    const { accountId } = yield* yield* CloudflareEnvironment;
+    const context = yield* Effect.context<
+      Credentials | HttpClient.HttpClient
+    >();
+    const auth: D1Auth = {
+      authorize: (eff) => eff.pipe(Effect.provideContext(context)),
+      accountId,
+    };
+
+    return Effect.fn(function* (database: Database) {
+      // Deferred accessor — resolves the databaseId against the tracker at
+      // apply time. No `host.bind`: the local variant registers no binding.
+      const databaseId = yield* database.databaseId;
+      return makeHttpQueryDatabaseClient(auth, databaseId);
+    });
+  }),
+);

package/src/Cloudflare/D1/index.ts

@@ -1,3 +1,4 @@
 export * from "./Database.ts";
 export * from "./QueryDatabase.ts";
 export * from "./QueryDatabaseBinding.ts";
+export * from "./QueryDatabaseLocal.ts";

package/src/Cloudflare/DNS/DnsHttp.ts

@@ -1,9 +1,13 @@
 import * as Effect from "effect/Effect";
 import type * as Redacted from "effect/Redacted";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
 import * as Output from "../../Output.ts";
 import { Self } from "../../Self.ts";
 import { AccountApiToken } from "../ApiToken/AccountApiToken.ts";
 import type { PermissionGroupRef } from "../ApiToken/Common.ts";
+import type { Credentials } from "../Credentials.ts";
+import { authorizeWith } from "../HttpClientUtils.ts";
 import type { Zone } from "../Zone/Zone.ts";
 
 /**
@@ -21,7 +25,7 @@ import type { Zone } from "../Zone/Zone.ts";
  */
 export const makeHttpDnsBinding = <Client>(options: {
   permissionGroups: PermissionGroupRef[];
-  makeClient: (token: Token, zoneId: Effect.Effect<string>) => Client;
+  makeClient: (auth: DnsAuth, zoneId: Effect.Effect<string>) => Client;
 }) =>
   Effect.gen(function* () {
     const Token = yield* AccountApiToken;
@@ -52,10 +56,28 @@ export const makeHttpDnsBinding = <Client>(options: {
         value: yield* token.value,
       } satisfies Token;
       const zoneId = yield* zone.zoneId;
-      return options.makeClient(bound, zoneId);
+      return options.makeClient(makeDnsAuth(bound), zoneId);
     });
   });
 
+/**
+ * Injectable auth for the DNS HTTP client builders. Both the scoped-token
+ * (`*Http`) and current-credentials (`*Local`) variants supply an `authorize`
+ * that provides `Credentials` + `HttpClient` to a raw SDK op, so the client
+ * builders are agnostic to how creds are obtained. DNS record ops are
+ * zone-scoped (the `zoneId` is passed alongside), so no `accountId` is needed.
+ */
+export interface DnsAuth {
+  authorize: <A, E>(
+    eff: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+  ) => Effect.Effect<A, E, RuntimeContext>;
+}
+
+/** Build a scoped-token {@link DnsAuth} from a bound {@link Token}. */
+export const makeDnsAuth = (token: Token): DnsAuth => ({
+  authorize: authorizeWith(token),
+});
+
 /**
  * Runtime accessor for a DNS binding's token, obtained by binding the
  * {@link AccountApiToken}'s `value` output in the Worker's Init phase. Reads the

package/src/Cloudflare/DNS/DnsLocal.ts

@@ -0,0 +1,41 @@
+import * as Effect from "effect/Effect";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { Credentials } from "../Credentials.ts";
+import type { Zone } from "../Zone/Zone.ts";
+import type { DnsAuth } from "./DnsHttp.ts";
+
+/**
+ * Shared scaffolding for the `*Local` DNS services.
+ *
+ * Instead of minting a scoped {@link AccountApiToken} (the `*Http` path), it
+ * captures the ambient current-credentials context available during stack-eval
+ * and builds a {@link DnsAuth} that provides those credentials directly to the
+ * DNS HTTP ops. It then delegates to the same client builders the `*Http`
+ * variant uses. DNS is a zone-management capability with no native Worker
+ * binding, so there is no `*Binding` counterpart.
+ *
+ * NOT exported from `index.ts` — this is internal scaffolding shared by the
+ * three access-level Local layers.
+ */
+export const makeLocalDnsBinding = <Client>(options: {
+  makeClient: (auth: DnsAuth, zoneId: Effect.Effect<string>) => Client;
+}) =>
+  Effect.gen(function* () {
+    // Credentials are ambient during stack-eval (the stack's providers layer).
+    // Capture the full context so DNS HTTP ops can run with the current
+    // credentials — no `host.bind`, no minted token. DNS record ops are
+    // zone-scoped, so no accountId is needed.
+    const context = yield* Effect.context<
+      Credentials | HttpClient.HttpClient
+    >();
+
+    return Effect.fn(function* (zone: Zone) {
+      // Deferred accessor — resolves the zoneId against the tracker at apply
+      // time (in an Action, that's the engine's resolve context).
+      const zoneId = yield* zone.zoneId;
+      const auth: DnsAuth = {
+        authorize: (eff) => eff.pipe(Effect.provideContext(context)),
+      };
+      return options.makeClient(auth, zoneId);
+    });
+  });

package/src/Cloudflare/DNS/ReadDnsHttp.ts

@@ -1,8 +1,7 @@
 import * as dns from "@distilled.cloud/cloudflare/dns";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import { authorizeWith } from "../HttpClientUtils.ts";
-import { makeHttpDnsBinding, type Token } from "./DnsHttp.ts";
+import { type DnsAuth, makeHttpDnsBinding } from "./DnsHttp.ts";
 import { ReadDns, type ReadDnsClient } from "./ReadDns.ts";
 
 /** Runtime layer for {@link ReadDns}. */
@@ -16,12 +15,12 @@ export const ReadDnsHttp = Layer.effect(
   ),
 );
 
-/** Build the read-only client over a bound token and zone id. */
+/** Build the read-only client over an injectable auth and zone id. */
 export const dnsReadClient = (
-  token: Token,
+  auth: DnsAuth,
   zoneId: Effect.Effect<string>,
 ): ReadDnsClient => {
-  const authorize = authorizeWith(token);
+  const authorize = auth.authorize;
   return {
     getDnsRecord: Effect.fn("Cloudflare.DNS.getDnsRecord")(
       function* (dnsRecordId) {

package/src/Cloudflare/DNS/ReadDnsLocal.ts

@@ -0,0 +1,38 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeLocalDnsBinding } from "./DnsLocal.ts";
+import { ReadDns } from "./ReadDns.ts";
+import { dnsReadClient } from "./ReadDnsHttp.ts";
+
+/**
+ * Local implementation of the {@link ReadDns} binding — reads Cloudflare DNS
+ * records over the HTTP API using the **current credentials** instead of a
+ * scoped API token ({@link ReadDnsHttp}). DNS is a zone-management capability
+ * with no native Worker binding.
+ *
+ * Provide it on an {@link Action} (or any deploy-time Effect) so you can read a
+ * zone's DNS records with the same `getDnsRecord`/`listDnsRecords` client you'd
+ * use inside a Worker:
+ *
+ * @example Reading records from an Action
+ * ```typescript
+ * const Check = Alchemy.Action(
+ *   "Check",
+ *   Effect.gen(function* () {
+ *     const dns = yield* Cloudflare.DNS.ReadDns(zone);
+ *     return Effect.fn(function* () {
+ *       return yield* dns.listDnsRecords({ type: "TXT" });
+ *     });
+ *   }).pipe(Effect.provide(Cloudflare.DNS.ReadDnsLocal)),
+ * );
+ * ```
+ *
+ * The zone id is resolved at apply time through the ambient
+ * {@link RuntimeContext} (in an Action, that's the resolve context the engine
+ * provides around the body), so `ReadDns(zone)` works even though the zone may
+ * be created/adopted in the same deploy.
+ */
+export const ReadDnsLocal = Layer.effect(
+  ReadDns,
+  Effect.suspend(() => makeLocalDnsBinding({ makeClient: dnsReadClient })),
+);

package/src/Cloudflare/DNS/ReadWriteDnsHttp.ts

@@ -1,6 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import { makeHttpDnsBinding, type Token } from "./DnsHttp.ts";
+import { type DnsAuth, makeHttpDnsBinding } from "./DnsHttp.ts";
 import { dnsReadClient } from "./ReadDnsHttp.ts";
 import { ReadWriteDns, type ReadWriteDnsClient } from "./ReadWriteDns.ts";
 import { dnsWriteClient } from "./WriteDnsHttp.ts";
@@ -16,11 +16,11 @@ export const ReadWriteDnsHttp = Layer.effect(
   ),
 );
 
-/** Build the combined read + write client over a bound token and zone id. */
+/** Build the combined read + write client over an injectable auth and zone id. */
 export const dnsReadWriteClient = (
-  token: Token,
+  auth: DnsAuth,
   zoneId: Effect.Effect<string>,
 ): ReadWriteDnsClient => ({
-  ...dnsReadClient(token, zoneId),
-  ...dnsWriteClient(token, zoneId),
+  ...dnsReadClient(auth, zoneId),
+  ...dnsWriteClient(auth, zoneId),
 });

package/src/Cloudflare/DNS/ReadWriteDnsLocal.ts

@@ -0,0 +1,46 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeLocalDnsBinding } from "./DnsLocal.ts";
+import { ReadWriteDns } from "./ReadWriteDns.ts";
+import { dnsReadWriteClient } from "./ReadWriteDnsHttp.ts";
+
+/**
+ * Local implementation of the {@link ReadWriteDns} binding — performs the full
+ * Cloudflare DNS record CRUD surface over the HTTP API using the **current
+ * credentials** instead of a scoped API token ({@link ReadWriteDnsHttp}). DNS
+ * is a zone-management capability with no native Worker binding.
+ *
+ * Provide it on an {@link Action} (or any deploy-time Effect) so you can manage
+ * a zone's DNS records with the same read + write client you'd use inside a
+ * Worker:
+ *
+ * @example Seeding and reading records from an Action
+ * ```typescript
+ * const Seed = Alchemy.Action(
+ *   "Seed",
+ *   Effect.gen(function* () {
+ *     const dns = yield* Cloudflare.DNS.ReadWriteDns(zone);
+ *     return Effect.fn(function* () {
+ *       const created = yield* dns.createDnsRecord({
+ *         type: "TXT",
+ *         name: "_seed.example.com",
+ *         content: '"hello"',
+ *         ttl: 60,
+ *       });
+ *       const record = yield* dns.getDnsRecord(created.id);
+ *       yield* dns.deleteDnsRecord(created.id);
+ *       return record;
+ *     });
+ *   }).pipe(Effect.provide(Cloudflare.DNS.ReadWriteDnsLocal)),
+ * );
+ * ```
+ *
+ * The zone id is resolved at apply time through the ambient
+ * {@link RuntimeContext} (in an Action, that's the resolve context the engine
+ * provides around the body), so `ReadWriteDns(zone)` works even though the zone
+ * may be created/adopted in the same deploy.
+ */
+export const ReadWriteDnsLocal = Layer.effect(
+  ReadWriteDns,
+  Effect.suspend(() => makeLocalDnsBinding({ makeClient: dnsReadWriteClient })),
+);

package/src/Cloudflare/DNS/WriteDnsHttp.ts

@@ -1,8 +1,7 @@
 import * as dns from "@distilled.cloud/cloudflare/dns";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import { authorizeWith } from "../HttpClientUtils.ts";
-import { makeHttpDnsBinding, type Token } from "./DnsHttp.ts";
+import { type DnsAuth, makeHttpDnsBinding } from "./DnsHttp.ts";
 import { WriteDns, type WriteDnsClient } from "./WriteDns.ts";
 
 /** Runtime layer for {@link WriteDns}. */
@@ -16,12 +15,12 @@ export const WriteDnsHttp = Layer.effect(
   ),
 );
 
-/** Build the write client over a bound token and zone id. */
+/** Build the write client over an injectable auth and zone id. */
 export const dnsWriteClient = (
-  token: Token,
+  auth: DnsAuth,
   zoneId: Effect.Effect<string>,
 ): WriteDnsClient => {
-  const authorize = authorizeWith(token);
+  const authorize = auth.authorize;
   return {
     createDnsRecord: Effect.fn("Cloudflare.DNS.createDnsRecord")(
       function* (request) {

package/src/Cloudflare/DNS/WriteDnsLocal.ts

@@ -0,0 +1,44 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeLocalDnsBinding } from "./DnsLocal.ts";
+import { WriteDns } from "./WriteDns.ts";
+import { dnsWriteClient } from "./WriteDnsHttp.ts";
+
+/**
+ * Local implementation of the {@link WriteDns} binding — creates, updates, and
+ * deletes Cloudflare DNS records over the HTTP API using the **current
+ * credentials** instead of a scoped API token ({@link WriteDnsHttp}). DNS is a
+ * zone-management capability with no native Worker binding.
+ *
+ * Provide it on an {@link Action} (or any deploy-time Effect) so you can mutate
+ * a zone's DNS records with the same
+ * `createDnsRecord`/`updateDnsRecord`/`deleteDnsRecord`/`batchDnsRecords`
+ * client you'd use inside a Worker:
+ *
+ * @example Creating a record from an Action
+ * ```typescript
+ * const Seed = Alchemy.Action(
+ *   "Seed",
+ *   Effect.gen(function* () {
+ *     const dns = yield* Cloudflare.DNS.WriteDns(zone);
+ *     return Effect.fn(function* () {
+ *       return yield* dns.createDnsRecord({
+ *         type: "TXT",
+ *         name: "_seed.example.com",
+ *         content: '"hello"',
+ *         ttl: 60,
+ *       });
+ *     });
+ *   }).pipe(Effect.provide(Cloudflare.DNS.WriteDnsLocal)),
+ * );
+ * ```
+ *
+ * The zone id is resolved at apply time through the ambient
+ * {@link RuntimeContext} (in an Action, that's the resolve context the engine
+ * provides around the body), so `WriteDns(zone)` works even though the zone may
+ * be created/adopted in the same deploy.
+ */
+export const WriteDnsLocal = Layer.effect(
+  WriteDns,
+  Effect.suspend(() => makeLocalDnsBinding({ makeClient: dnsWriteClient })),
+);

package/src/Cloudflare/DNS/index.ts

@@ -4,12 +4,15 @@ export * from "./Dnssec.ts";
 export * from "./Firewall.ts";
 export * from "./ReadDns.ts";
 export * from "./ReadDnsHttp.ts";
+export * from "./ReadDnsLocal.ts";
 export * from "./ReadWriteDns.ts";
 export * from "./ReadWriteDnsHttp.ts";
+export * from "./ReadWriteDnsLocal.ts";
 export * from "./Record.ts";
 export * from "./View.ts";
 export * from "./WriteDns.ts";
 export * from "./WriteDnsHttp.ts";
+export * from "./WriteDnsLocal.ts";
 export * from "./ZoneSettings.ts";
 export * from "./ZoneTransferAcl.ts";
 export * from "./ZoneTransferIncoming.ts";

package/src/Cloudflare/Diagnostics/EndpointHealthcheck.ts

@@ -260,9 +260,10 @@ const observeExisting = (accountId: string, id: string) =>
     Effect.map((hc): ObservedHealthcheck => ({ ...hc, accountId })),
     Effect.retry({
       while: (e) => e._tag === "EndpointHealthcheckNotFound",
-      schedule: Schedule.exponential("500 millis").pipe(
-        Schedule.both(Schedule.recurs(6)),
-      ),
+      schedule: Schedule.max([
+        Schedule.exponential("500 millis"),
+        Schedule.recurs(6),
+      ]),
     }),
     Effect.catchTag("EndpointHealthcheckNotFound", () =>
       Effect.succeed(undefined),

package/src/Cloudflare/Flagship/ReadFlagsHttpClient.ts

@@ -0,0 +1,183 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as flagship from "@distilled.cloud/cloudflare/flagship";
+import * as Effect from "effect/Effect";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import type { Credentials } from "../Credentials.ts";
+import {
+  type EvaluationContext,
+  type EvaluationDetails,
+  FlagshipError,
+  type ReadFlagsClient,
+} from "./ReadFlags.ts";
+
+// Shared HTTP scaffolding for the Flagship `ReadFlags` binding. NOT
+// re-exported from `index.ts` — only the contract and the impl layers are
+// public. A future token-scoped `ReadFlagsHttp` layer reuses this builder with
+// an auth minted from an `AccountApiToken`; `ReadFlagsLocal` builds the auth
+// from the ambient current-credentials context.
+
+/**
+ * Injectable auth shared by the Local (current-credentials) impl and a future
+ * Http (scoped-token) impl. `authorize` discharges the
+ * `Credentials | HttpClient` requirement of a distilled op; `accountId` is the
+ * Cloudflare account the ops run against.
+ */
+export interface FlagshipAuth {
+  authorize: <A, E>(
+    eff: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+  ) => Effect.Effect<A, E>;
+  accountId: string;
+}
+
+/**
+ * The HTTP evaluate endpoint only supports a single `targetingKey` query
+ * param, not the full flat evaluation context the Worker binding accepts.
+ */
+const targetingKeyOf = (
+  context: EvaluationContext | undefined,
+): string | undefined => {
+  const value = context?.["targetingKey"];
+  return value === undefined ? undefined : String(value);
+};
+
+/**
+ * Build a {@link ReadFlagsClient} over the Flagship HTTP evaluate endpoint
+ * (`GET .../flagship/apps/{appId}/evaluate`).
+ *
+ * `appId` is an Effect so the resolution stays deferred to each call — inside
+ * an Action it resolves through the apply-time RuntimeContext. Mirrors the
+ * Worker binding's fall-back-to-default semantics: evaluation never fails the
+ * effect — an HTTP error or a value whose type does not match the requested
+ * method resolves to `defaultValue` instead. The `raw` runtime binding has no
+ * HTTP equivalent and dies if used.
+ */
+export const makeHttpFlagshipClient = (
+  auth: FlagshipAuth,
+  appId: Effect.Effect<string>,
+): ReadFlagsClient => {
+  const evaluate = (flagKey: string, context?: EvaluationContext) =>
+    appId.pipe(
+      Effect.flatMap((id) =>
+        auth.authorize(
+          flagship.getAppEvaluate({
+            accountId: auth.accountId,
+            appId: id,
+            flagKey,
+            targetingKey: targetingKeyOf(context),
+          }),
+        ),
+      ),
+    );
+
+  const details = <T>(
+    flagKey: string,
+    defaultValue: T,
+    match: (value: unknown) => value is T,
+    context?: EvaluationContext,
+  ): Effect.Effect<EvaluationDetails<T>, FlagshipError, RuntimeContext> =>
+    evaluate(flagKey, context).pipe(
+      Effect.map(
+        (r): EvaluationDetails<T> =>
+          match(r.value)
+            ? { flagKey, value: r.value, variant: r.variant, reason: r.reason }
+            : {
+                flagKey,
+                value: defaultValue,
+                variant: r.variant,
+                reason: r.reason,
+                errorCode: "TYPE_MISMATCH",
+              },
+      ),
+      Effect.catch((error) =>
+        Effect.succeed<EvaluationDetails<T>>({
+          flagKey,
+          value: defaultValue,
+          reason: "ERROR",
+          errorCode: error._tag,
+        }),
+      ),
+    );
+
+  const value = <T>(
+    flagKey: string,
+    defaultValue: T,
+    match: (value: unknown) => value is T,
+    context?: EvaluationContext,
+  ): Effect.Effect<T, FlagshipError, RuntimeContext> =>
+    evaluate(flagKey, context).pipe(
+      Effect.map((r) => (match(r.value) ? r.value : defaultValue)),
+      Effect.catch(() => Effect.succeed(defaultValue)),
+    );
+
+  const isBoolean = (v: unknown): v is boolean => typeof v === "boolean";
+  const isString = (v: unknown): v is string => typeof v === "string";
+  const isNumber = (v: unknown): v is number => typeof v === "number";
+  const isObjectLike = (v: unknown): boolean =>
+    v !== null && typeof v === "object";
+
+  return {
+    // The raw runtime binding is a workerd object with no HTTP surface.
+    raw: Effect.die(
+      new FlagshipError({
+        message:
+          "the raw Flagship runtime binding is unavailable over HTTP; use ReadFlagsBinding inside a Worker",
+        cause: undefined,
+      }),
+    ) as Effect.Effect<cf.Flagship, never, RuntimeContext>,
+    get: (flagKey, defaultValue, context) =>
+      evaluate(flagKey, context).pipe(
+        Effect.map((r) => r.value ?? defaultValue),
+        Effect.catch(() => Effect.succeed(defaultValue)),
+      ),
+    getBooleanValue: (flagKey, defaultValue, context) =>
+      value(flagKey, defaultValue, isBoolean, context),
+    getStringValue: (flagKey, defaultValue, context) =>
+      value(flagKey, defaultValue, isString, context),
+    getNumberValue: (flagKey, defaultValue, context) =>
+      value(flagKey, defaultValue, isNumber, context),
+    getObjectValue: (flagKey, defaultValue, context) =>
+      evaluate(flagKey, context).pipe(
+        Effect.map((r) =>
+          isObjectLike(r.value)
+            ? (r.value as typeof defaultValue)
+            : defaultValue,
+        ),
+        Effect.catch(() => Effect.succeed(defaultValue)),
+      ),
+    getBooleanDetails: (flagKey, defaultValue, context) =>
+      details(flagKey, defaultValue, isBoolean, context),
+    getStringDetails: (flagKey, defaultValue, context) =>
+      details(flagKey, defaultValue, isString, context),
+    getNumberDetails: (flagKey, defaultValue, context) =>
+      details(flagKey, defaultValue, isNumber, context),
+    getObjectDetails: (flagKey, defaultValue, context) =>
+      evaluate(flagKey, context).pipe(
+        Effect.map(
+          (r): EvaluationDetails<typeof defaultValue> =>
+            isObjectLike(r.value)
+              ? {
+                  flagKey,
+                  value: r.value as typeof defaultValue,
+                  variant: r.variant,
+                  reason: r.reason,
+                }
+              : {
+                  flagKey,
+                  value: defaultValue,
+                  variant: r.variant,
+                  reason: r.reason,
+                  errorCode: "TYPE_MISMATCH",
+                },
+        ),
+        Effect.catch((error) =>
+          Effect.succeed<EvaluationDetails<typeof defaultValue>>({
+            flagKey,
+            value: defaultValue,
+            reason: "ERROR",
+            errorCode: error._tag,
+          }),
+        ),
+      ),
+  } satisfies ReadFlagsClient;
+};

package/src/Cloudflare/Flagship/ReadFlagsLocal.ts

@@ -0,0 +1,69 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { Credentials } from "../Credentials.ts";
+import type { App } from "./App.ts";
+import { ReadFlags } from "./ReadFlags.ts";
+import {
+  type FlagshipAuth,
+  makeHttpFlagshipClient,
+} from "./ReadFlagsHttpClient.ts";
+
+/**
+ * Local implementation of the {@link ReadFlags} binding — evaluates Flagship
+ * feature flags over the Cloudflare HTTP API (`GET .../flagship/apps/{appId}/evaluate`)
+ * using the **current credentials** instead of a native Worker binding
+ * ({@link ReadFlagsBinding}).
+ *
+ * Provide it on an {@link Action} (or any deploy-time Effect) so you can read
+ * flag values with the same `getBooleanValue`/`getStringValue`/… client you'd
+ * use inside a Worker:
+ *
+ * @example Reading a flag from an Action
+ * ```typescript
+ * const CheckFlag = Alchemy.Action(
+ *   "CheckFlag",
+ *   Effect.gen(function* () {
+ *     const flags = yield* Cloudflare.Flagship.ReadFlags(app);
+ *     return Effect.fn(function* () {
+ *       return yield* flags.getBooleanValue("new-checkout", false);
+ *     });
+ *   }).pipe(Effect.provide(Cloudflare.Flagship.ReadFlagsLocal)),
+ * );
+ * ```
+ *
+ * The app id is resolved at apply time through the ambient {@link RuntimeContext}
+ * (in an Action, that's the resolve context the engine provides around the
+ * body), so `ReadFlags(app)` works even though the app is created in the same
+ * deploy.
+ *
+ * Limitations vs. the Worker binding: the HTTP evaluate endpoint only accepts a
+ * single `targetingKey` (read from `context.targetingKey`), so attribute-based
+ * targeting rules that key off other context fields cannot be exercised locally.
+ * The `raw` runtime binding has no HTTP equivalent and dies if used — see
+ * {@link makeHttpFlagshipClient}.
+ */
+export const ReadFlagsLocal = Layer.effect(
+  ReadFlags,
+  Effect.gen(function* () {
+    // Account + credentials are ambient during stack-eval (the stack's
+    // providers layer). Capture the full context so the evaluate op can run
+    // with the current credentials — no `host.bind`, no minted token.
+    const { accountId } = yield* yield* CloudflareEnvironment;
+    const context = yield* Effect.context<
+      Credentials | HttpClient.HttpClient
+    >();
+    const auth: FlagshipAuth = {
+      authorize: (eff) => eff.pipe(Effect.provideContext(context)),
+      accountId,
+    };
+
+    return Effect.fn(function* (app: App) {
+      // Deferred accessor — resolves the appId against the tracker at apply
+      // time (in an Action, that's the engine's resolve context).
+      const appId = yield* app.appId;
+      return makeHttpFlagshipClient(auth, appId);
+    });
+  }),
+);

package/src/Cloudflare/Flagship/index.ts

@@ -8,3 +8,4 @@ export {
   type EvaluationDetails,
 } from "./ReadFlags.ts";
 export { ReadFlagsBinding } from "./ReadFlagsBinding.ts";
+export { ReadFlagsLocal } from "./ReadFlagsLocal.ts";