alchemy 2.0.0-beta.81 → 2.0.0-beta.82

package/src/Cloudflare/Queues/QueueSinkHttp.ts

@@ -0,0 +1,23 @@
+import * as Layer from "effect/Layer";
+import { QueueSinkFromWriteQueue } from "./QueueSinkBatch.ts";
+import { WriteQueueHttp } from "./WriteQueueHttp.ts";
+
+/**
+ * Implementation of the {@link QueueSink} service over the Queues bulk-push
+ * HTTP API ({@link WriteQueueHttp}), authenticated with a scoped
+ * `Queues Write` API token bound into the host.
+ * ### Providing the Layer
+ * **Example:** Drain a Stream over HTTP
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const sink = yield* Cloudflare.Queues.QueueSink(Clicks);
+ *   // ...
+ * }).pipe(Effect.provide(Cloudflare.Queues.QueueSinkHttp));
+ * ```
+ *
+ * @layer
+ * @provides Cloudflare.Queues.QueueSink
+ * @product Queues
+ * @category Storage & Databases
+ */
+export const QueueSinkHttp = QueueSinkFromWriteQueue.pipe(Layer.provide(WriteQueueHttp));

package/src/Cloudflare/Queues/QueueSinkLocal.ts

@@ -0,0 +1,32 @@
+import * as Layer from "effect/Layer";
+import { QueueSinkFromWriteQueue } from "./QueueSinkBatch.ts";
+import { WriteQueueLocal } from "./WriteQueueLocal.ts";
+
+/**
+ * Implementation of the {@link QueueSink} service that pushes over the
+ * Queues bulk-push HTTP API with the **current credentials**
+ * ({@link WriteQueueLocal}) — for draining a Stream into a queue from an
+ * Action or other deploy-time Effect, with no Worker host.
+ * ### Providing the Layer
+ * **Example:** Seed a queue from an Action
+ * ```typescript
+ * const Seed = Alchemy.Action(
+ *   "Seed",
+ *   Effect.gen(function* () {
+ *     const sink = yield* Cloudflare.Queues.QueueSink(queue);
+ *     return Effect.fn(function* () {
+ *       yield* Stream.range(1, 500).pipe(
+ *         Stream.map((id) => ({ event: "seed", id })),
+ *         Stream.run(sink),
+ *       );
+ *     });
+ *   }).pipe(Effect.provide(Cloudflare.Queues.QueueSinkLocal)),
+ * );
+ * ```
+ *
+ * @layer
+ * @provides Cloudflare.Queues.QueueSink
+ * @product Queues
+ * @category Storage & Databases
+ */
+export const QueueSinkLocal = QueueSinkFromWriteQueue.pipe(Layer.provide(WriteQueueLocal));

package/src/Cloudflare/Queues/Subscription.ts

@@ -69,6 +69,14 @@ export type SubscriptionSource =
       type: "workflows.workflow";
       /** Name of the workflow to subscribe to. */
       workflowName: string;
+    }
+  | {
+      /** Email Sending lifecycle events for one sending domain. */
+      type: "email.sending";
+      /** Zone the sending domain belongs to. */
+      zoneId: string;
+      /** The zone apex or a verified sending subdomain, e.g. `mail.example.com`. */
+      domain: string;
     };
 
 export type SubscriptionProps = {
@@ -369,6 +377,15 @@ const validateSourceAccount = (accountId: string, sourceAccountId?: string) =>
  * });
  * ```
  *
+ * **Example:** Bounces and complaints from an Email Sending domain
+ * ```typescript
+ * const subscription = yield* Cloudflare.Queues.Subscription("MailEvents", {
+ *   source: { type: "email.sending", zoneId: zone.zoneId, domain: "mail.example.com" },
+ *   events: ["message.bounced", "message.complained"],
+ *   queueId: queue.queueId,
+ * });
+ * ```
+ *
  * ### Resource and Reference Sources
  * **Example:** Account-wide KV events from a namespace
  * ```typescript
@@ -670,6 +687,8 @@ type WireSource = {
   modelName?: string | null;
   workerName?: string | null;
   workflowName?: string | null;
+  zoneId?: string | null;
+  domain?: string | null;
 };
 
 const toSource = (wire: unknown): SubscriptionSource => {
@@ -687,6 +706,12 @@ const toSource = (wire: unknown): SubscriptionSource => {
         type: "workflows.workflow",
         workflowName: source.workflowName ?? "",
       };
+    case "email.sending":
+      return {
+        type: "email.sending",
+        zoneId: source.zoneId ?? "",
+        domain: source.domain ?? "",
+      };
     case "images":
     case "kv":
     case "r2":
@@ -709,6 +734,10 @@ const sameSource = (a: SubscriptionSource, b: SubscriptionSource): boolean => {
       return a.workerName === (b as { workerName?: string }).workerName;
     case "workflows.workflow":
       return a.workflowName === (b as { workflowName?: string }).workflowName;
+    case "email.sending": {
+      const other = b as { zoneId?: string; domain?: string };
+      return a.zoneId === other.zoneId && a.domain === other.domain;
+    }
     default:
       return true;
   }

package/src/Cloudflare/Queues/index.ts

@@ -2,6 +2,10 @@ export * from "./Queue.ts";
 export * from "./Consumer.ts";
 export * from "./EventSource.ts";
 export * from "./QueueTypes.ts";
+export * from "./QueueSink.ts";
+export * from "./QueueSinkBinding.ts";
+export * from "./QueueSinkHttp.ts";
+export * from "./QueueSinkLocal.ts";
 export * from "./WriteQueue.ts";
 export * from "./WriteQueueBinding.ts";
 export * from "./WriteQueueHttp.ts";

package/src/Cloudflare/R2/Bucket.ts

@@ -134,6 +134,50 @@ export type BucketCorsRule = {
   maxAgeSeconds?: number;
 };
 
+export type BucketLockCondition =
+  | {
+      /**
+       * Lock matching objects permanently. They can never be deleted or
+       * overwritten, so the bucket can never be emptied or deleted.
+       */
+      type: "Indefinite";
+    }
+  | {
+      type: "Age";
+      /**
+       * Seconds after upload during which matching objects stay locked.
+       */
+      maxAgeSeconds: number;
+    }
+  | {
+      type: "Date";
+      /**
+       * Absolute date (ISO 8601) until which matching objects stay locked.
+       */
+      date: string;
+    };
+
+export type BucketLockRule = {
+  /**
+   * Unique identifier for the rule within the bucket.
+   */
+  id: string;
+  /**
+   * Whether the rule is in effect.
+   */
+  enabled: boolean;
+  /**
+   * Object key prefix the rule applies to. Use `""` (or omit) to lock every
+   * object in the bucket.
+   * @default ""
+   */
+  prefix?: string;
+  /**
+   * How long matching objects stay locked.
+   */
+  condition: BucketLockCondition;
+};
+
 export type BucketProps = {
   /**
    * Name of the bucket. If omitted, a unique name will be generated.
@@ -184,6 +228,19 @@ export type BucketProps = {
    * configuration.
    */
   cors?: BucketCorsRule[];
+  /**
+   * Object lock rules applied to the bucket. While a rule's condition
+   * holds, R2 refuses to delete or overwrite any object whose key matches
+   * the rule's prefix, whoever signs the request (S3 API credentials
+   * included). An `Indefinite` rule never lapses: matching objects are
+   * permanent and the bucket can never be emptied, so `forceDestroy`
+   * cannot delete it.
+   *
+   * A bucket that never declared `locks` keeps whatever rules it has: they
+   * are left unmanaged. Pass an empty array, or drop `locks` after
+   * declaring it, to remove every rule.
+   */
+  locks?: BucketLockRule[];
   /**
    * Allow alchemy to delete every object in the bucket when the bucket
    * itself is deleted.
@@ -215,6 +272,11 @@ export type Bucket = Resource<
     domains: Bucket.CustomDomain[];
     lifecycleRules: Bucket.LifecycleRule[];
     cors: Bucket.CorsRule[];
+    /**
+     * Lock rules on the bucket. `undefined` while `locks` is unmanaged
+     * (omitted from the props).
+     */
+    locks: Bucket.LockRule[] | undefined;
     /**
      * Hostname of the bucket's Cloudflare-managed `r2.dev` domain.
      * Set only while `publicAccess` is enabled; `undefined` when
@@ -446,6 +508,45 @@ export type Bucket = Resource<
  * });
  * ```
  *
+ * ### Bucket Locks
+ *
+ * Lock rules make objects write-once: while a rule's condition holds, R2
+ * refuses to delete or overwrite any object under the rule's prefix,
+ * whoever signs the request. `Indefinite` locks never lapse, so a bucket
+ * with indefinitely locked objects can never be emptied or deleted. A
+ * bucket that never declares `locks` keeps its rules unmanaged; pass an
+ * empty array (or drop `locks` after declaring it) to remove them. See the
+ * [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/bucket-locks/)
+ * for details.
+ *
+ * **Example:** Write-once landing zone
+ * ```typescript
+ * const lake = yield* Cloudflare.R2.Bucket("Lake", {
+ *   locks: [
+ *     {
+ *       id: "raw-write-once",
+ *       enabled: true,
+ *       prefix: "raw/",
+ *       condition: { type: "Indefinite" },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * **Example:** Retain logs for 90 days
+ * ```typescript
+ * const audit = yield* Cloudflare.R2.Bucket("Audit", {
+ *   locks: [
+ *     {
+ *       id: "retain-logs",
+ *       enabled: true,
+ *       prefix: "logs/",
+ *       condition: { type: "Age", maxAgeSeconds: 60 * 60 * 24 * 90 },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
  * ### Deleting a Bucket
  *
  * R2 refuses to delete a bucket that still has objects in it, and alchemy
@@ -505,6 +606,12 @@ export declare namespace Bucket {
     exposeHeaders: string[] | undefined;
     maxAgeSeconds: number | undefined;
   };
+  export type LockRule = {
+    id: string;
+    enabled: boolean;
+    prefix: string;
+    condition: BucketLockCondition;
+  };
   export type CustomDomain = {
     domain: string;
     zoneId: string | undefined;
@@ -938,6 +1045,58 @@ export const ProviderLive = () =>
           return desiredRules;
         });
 
+      // PUT replaces the bucket's whole rule set, so `[]` clears it.
+      const reconcileLockRules = (
+        bucketName: string,
+        jurisdiction: Bucket.Jurisdiction,
+        desired: BucketLockRule[],
+      ) =>
+        Effect.gen(function* () {
+          const { accountId } = yield* yield* CloudflareEnvironment;
+          const observed = yield* r2
+            .getBucketLock({
+              accountId,
+              bucketName,
+              jurisdiction,
+            })
+            .pipe(
+              Effect.map((response) => sortLockRules((response.rules ?? []).map(toLockRule))),
+              Effect.retry({
+                while: (e) => e._tag === "NoSuchBucket",
+                schedule: r2BucketEndpointConsistencySchedule,
+              }),
+            );
+
+          // R2 returns rules sorted by id, not in the order they were PUT,
+          // so compare (and report) both sides in id order.
+          const desiredRules = sortLockRules(
+            desired.map((rule): Bucket.LockRule => ({
+              ...rule,
+              prefix: rule.prefix ?? "",
+            })),
+          );
+
+          if (deepEqual(observed, desiredRules)) {
+            return desiredRules;
+          }
+
+          yield* r2
+            .putBucketLock({
+              accountId,
+              bucketName,
+              jurisdiction,
+              rules: desiredRules,
+            })
+            .pipe(
+              Effect.retry({
+                while: (e) => e._tag === "NoSuchBucket",
+                schedule: r2BucketEndpointConsistencySchedule,
+              }),
+            );
+
+          return desiredRules;
+        });
+
       return {
         stables: ["bucketName", "accountId"],
         list: () =>
@@ -1016,6 +1175,7 @@ export const ProviderLive = () =>
                     domains,
                     lifecycleRules,
                     cors,
+                    locks: undefined,
                     publicDomain,
                   };
                 }).pipe(
@@ -1038,6 +1198,7 @@ export const ProviderLive = () =>
                       domains: [] as Bucket.CustomDomain[],
                       lifecycleRules: [] as Bucket.LifecycleRule[],
                       cors: [] as Bucket.CorsRule[],
+                      locks: undefined,
                       publicDomain: undefined,
                     }),
                   ),
@@ -1082,11 +1243,14 @@ export const ProviderLive = () =>
           if (!deepEqual(olds.cors, news.cors)) {
             return { action: "update" } as const;
           }
+          if (!deepEqual(olds.locks, news.locks)) {
+            return { action: "update" } as const;
+          }
           if ((olds.publicAccess ?? false) !== (news.publicAccess ?? false)) {
             return { action: "update" } as const;
           }
         }),
-        reconcile: Effect.fn(function* ({ id, news = {}, output }) {
+        reconcile: Effect.fn(function* ({ id, news = {}, olds, output }) {
           const { accountId } = yield* yield* CloudflareEnvironment;
           // Prefer the deployed name: regenerating would target a different
           // bucket if the generator's output for this id ever drifts.
@@ -1193,6 +1357,14 @@ export const ProviderLive = () =>
             news.cors ?? [],
           );
 
+          // Locks are managed only once the props name them: clearing rules
+          // a stack never declared would drop protection someone else set.
+          // Removing `locks` after declaring it still clears them.
+          const locks =
+            news.locks !== undefined || olds?.locks !== undefined
+              ? yield* reconcileLockRules(attrs.bucketName, attrs.jurisdiction, news.locks ?? [])
+              : undefined;
+
           const publicDomain = yield* reconcileManagedDomain(
             attrs.bucketName,
             attrs.jurisdiction,
@@ -1204,6 +1376,7 @@ export const ProviderLive = () =>
             domains,
             lifecycleRules,
             cors,
+            locks,
             publicDomain,
           };
         }),
@@ -1287,6 +1460,7 @@ export const ProviderLive = () =>
                 domains: output?.domains ?? [],
                 lifecycleRules: output?.lifecycleRules ?? [],
                 cors: output?.cors ?? [],
+                locks: output?.locks,
                 publicDomain: output?.publicDomain,
               })),
               Effect.catchTag("NoSuchBucket", () => Effect.succeed(undefined)),
@@ -1304,9 +1478,9 @@ export const ProviderLive = () =>
  * opaque id — the name IS the identity — so the `dev:` marker rides on the
  * name (a `:` can never appear in a real R2 bucket name).
  *
- * Custom domains, lifecycle rules, CORS, and the managed r2.dev domain
- * are deploy-side concerns with no local behavior; the local attributes
- * report them empty.
+ * Custom domains, lifecycle rules, CORS, lock rules, and the managed r2.dev
+ * domain are deploy-side concerns with no local behavior; the local
+ * attributes report them empty.
  */
 export const ProviderLocal = () =>
   Provider.succeed(Bucket, {
@@ -1335,6 +1509,7 @@ export const ProviderLocal = () =>
         domains: [],
         lifecycleRules: [],
         cors: [],
+        locks: undefined,
         publicDomain: undefined,
       };
     }),
@@ -1463,6 +1638,28 @@ const toLifecyclePutPayload = (
   storageClassTransitions: rule.storageClassTransitions,
 });
 
+type LockRuleResponse = NonNullable<r2.GetBucketLockResponse["rules"]>[number];
+
+const sortLockRules = (rules: Bucket.LockRule[]): Bucket.LockRule[] =>
+  [...rules].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+// The condition decodes as an unchecked union; copy only the known fields so
+// the drift comparison against the desired rules is exact.
+const toLockRule = (rule: LockRuleResponse): Bucket.LockRule => {
+  const condition = rule.condition;
+  return {
+    id: rule.id,
+    enabled: rule.enabled,
+    prefix: rule.prefix ?? "",
+    condition:
+      condition.type === "Age"
+        ? { type: "Age", maxAgeSeconds: condition.maxAgeSeconds }
+        : condition.type === "Date"
+          ? { type: "Date", date: condition.date }
+          : { type: "Indefinite" },
+  };
+};
+
 // Cloudflare keys a custom domain to a single bucket at the zone level. After a
 // domain is deleted, re-attaching the same hostname can transiently 409 with
 // "Domain already in use" (typed as `CustomDomainInUse`) until the prior

package/src/Cloudflare/R2/DataCatalog.ts

@@ -9,6 +9,7 @@ import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Providers } from "../Providers.ts";
+import type { Bucket } from "./Bucket.ts";
 
 const TypeId = "Cloudflare.R2.DataCatalog" as const;
 type TypeId = typeof TypeId;
@@ -58,14 +59,7 @@ export type SnapshotExpiration = {
   minSnapshotsToKeep?: number;
 };
 
-export type DataCatalogProps = {
-  /**
-   * Name of the R2 bucket to enable the Iceberg data catalog on. The bucket
-   * must already exist — pass `bucket.bucketName` from a `Cloudflare.R2.Bucket`
-   * resource to order catalog-after-bucket. Changing the bucket replaces the
-   * catalog (the old bucket's catalog is disabled; table data is untouched).
-   */
-  bucketName: string;
+export type DataCatalogProps = DataCatalogBucket & {
   /**
    * Compaction maintenance configuration. Only the fields you specify are
    * enforced; omitted fields keep Cloudflare's defaults.
@@ -85,6 +79,46 @@ export type DataCatalogProps = {
   token?: Redacted.Redacted<string>;
 };
 
+/**
+ * The bucket a catalog is enabled on. `bucketName` is the deprecated spelling
+ * of `bucket`; both name the same bucket and switching between them is not a
+ * change.
+ */
+export type DataCatalogBucket =
+  | {
+      /**
+       * The R2 bucket to enable the Iceberg catalog on: a
+       * `Cloudflare.R2.Bucket` resource (orders the catalog after the bucket)
+       * or a bucket name. Changing the bucket replaces the catalog (the old
+       * bucket's catalog is disabled; table data is untouched).
+       */
+      bucket: string | Bucket;
+      bucketName?: never;
+    }
+  | {
+      /**
+       * Name of the R2 bucket to enable the catalog on.
+       * @deprecated Use `bucket`, which also accepts the bucket resource.
+       */
+      bucketName: string;
+      bucket?: never;
+    };
+
+/**
+ * The bucket name behind a catalog's props: `bucket` as a name or a resolved
+ * `Cloudflare.R2.Bucket`, or the deprecated `bucketName`.
+ */
+export const catalogBucketName = (props: unknown): string | undefined => {
+  if (props === null || typeof props !== "object") return undefined;
+  const { bucket, bucketName } = props as { bucket?: unknown; bucketName?: unknown };
+  if (typeof bucket === "string") return bucket;
+  if (bucket !== null && typeof bucket === "object") {
+    const name = (bucket as { bucketName?: unknown }).bucketName;
+    if (typeof name === "string") return name;
+  }
+  return typeof bucketName === "string" ? bucketName : undefined;
+};
+
 export type DataCatalogAttributes = {
   /**
    * Unique identifier of the catalog (stable across disable/enable cycles).
@@ -153,13 +187,20 @@ export type DataCatalog = Resource<
  * Iceberg tables stored in R2. The catalog is a singleton per bucket: this
  * resource enables it, keeps its maintenance configuration in sync, and
  * disables it on destroy (table data in the bucket is never deleted).
+ *
+ * Also exported as `Cloudflare.Basin.Catalog` — the catalog of Cloudflare's
+ * Basin product (Pipelines + Catalog + SQL). The warehouse is named
+ * `<accountId>_<bucket>` and served at
+ * `https://catalog.cloudflarestorage.com/<accountId>/<bucket>`. Pass the
+ * catalog resource to a catalog `Cloudflare.Basin.Sink` (`catalog: Catalog`)
+ * so the sink is created after it.
  * ### Enabling a catalog
  * **Example:** Enable the catalog on an R2 bucket
  * ```typescript
  * const bucket = yield* Cloudflare.R2.Bucket("LakehouseBucket");
  *
- * const catalog = yield* Cloudflare.R2.R2DataCatalog("Lakehouse", {
- *   bucketName: bucket.bucketName,
+ * const catalog = yield* Cloudflare.Basin.Catalog("Lakehouse", {
+ *   bucket,
  * });
  *
  * // Point any Iceberg REST client at the warehouse:
@@ -170,8 +211,8 @@ export type DataCatalog = Resource<
  * ### Maintenance
  * **Example:** Configure compaction and snapshot expiration
  * ```typescript
- * const catalog = yield* Cloudflare.R2.R2DataCatalog("Lakehouse", {
- *   bucketName: bucket.bucketName,
+ * const catalog = yield* Cloudflare.Basin.Catalog("Lakehouse", {
+ *   bucket,
  *   compaction: { state: "enabled", targetSizeMb: "256" },
  *   snapshotExpiration: {
  *     state: "enabled",
@@ -184,8 +225,8 @@ export type DataCatalog = Resource<
  * **Example:** Register a maintenance credential
  * ```typescript
  * // Maintenance jobs need an API token with R2 read/write on the bucket.
- * const catalog = yield* Cloudflare.R2.R2DataCatalog("Lakehouse", {
- *   bucketName: bucket.bucketName,
+ * const catalog = yield* Cloudflare.Basin.Catalog("Lakehouse", {
+ *   bucket,
  *   compaction: { state: "enabled" },
  *   token: maintenanceToken, // Redacted<string>
  * });
@@ -200,7 +241,7 @@ export type DataCatalog = Resource<
 export const DataCatalog = Resource<DataCatalog>(TypeId);
 
 /**
- * Returns true if the given value is an R2DataCatalog resource.
+ * Returns true if the given value is a DataCatalog (Basin Catalog) resource.
  */
 export const isDataCatalog = (value: unknown): value is DataCatalog =>
   Predicate.hasProperty(value, "Type") && value.Type === TypeId;
@@ -217,13 +258,9 @@ export const DataCatalogProvider = () =>
       // The catalog is keyed to its bucket — moving buckets is a replacement
       // (disable on the old bucket, enable on the new one). bucketName is an
       // Input<string>; compare only once both sides are concrete strings.
-      const oldBucket =
-        output?.bucketName ?? (typeof olds?.bucketName === "string" ? olds.bucketName : undefined);
-      if (
-        oldBucket !== undefined &&
-        typeof news.bucketName === "string" &&
-        oldBucket !== news.bucketName
-      ) {
+      const oldBucket = output?.bucketName ?? catalogBucketName(olds);
+      const newBucket = catalogBucketName(news);
+      if (oldBucket !== undefined && newBucket !== undefined && oldBucket !== newBucket) {
         return { action: "replace" } as const;
       }
       return undefined;
@@ -231,8 +268,7 @@ export const DataCatalogProvider = () =>
     read: Effect.fn(function* ({ output, olds }) {
       const { accountId } = yield* yield* CloudflareEnvironment;
       const acct = output?.accountId ?? accountId;
-      const bucketName =
-        output?.bucketName ?? (typeof olds?.bucketName === "string" ? olds.bucketName : undefined);
+      const bucketName = output?.bucketName ?? catalogBucketName(olds);
       if (bucketName === undefined) return undefined;
 
       const observed = yield* getCatalog(acct, bucketName);
@@ -261,8 +297,9 @@ export const DataCatalogProvider = () =>
     reconcile: Effect.fn(function* ({ news, olds, output }) {
       const { accountId } = yield* yield* CloudflareEnvironment;
       const acct = output?.accountId ?? accountId;
-      // Inputs have been resolved to concrete strings by Plan.
-      const bucketName = news.bucketName as string;
+      // Inputs have been resolved by Plan: `bucket` is a name or the
+      // bucket's attributes.
+      const bucketName = catalogBucketName(news) as string;
 
       // Observe — `output` is only a cache; a disabled or never-enabled
       // catalog observes as missing/inactive and falls through to ensure.

package/src/Cloudflare/R2/LocalR2Gateway.ts

@@ -51,6 +51,7 @@ export const makeProxyBucketHelpers = (
   ambient: Context.Context<never>,
 ): ReturnType<typeof makeHelpers> => {
   const use = <T>(fn: (raw: runtime.R2Bucket) => Promise<T>): Effect.Effect<T, R2Error> =>
+    // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- remaining requirements are satisfied by the captured ambient context
     Effect.scoped(
       Effect.gen(function* () {
         const proxy = yield* open({

package/src/Cloudflare/R2/S3Credentials.ts

@@ -14,8 +14,9 @@ export type S3CredentialsAccess = "read" | "write" | "read-write";
 export interface S3CredentialsOptions {
   /**
    * Object operations the credentials may perform. Deployed, this selects
-   * the permission groups of the scoped API token they are derived from
-   * (`Workers R2 Storage Read` and/or `Workers R2 Storage Write`).
+   * the permission groups of the bucket-scoped API token they are derived
+   * from (`Workers R2 Storage Bucket Item Read` and/or
+   * `Workers R2 Storage Bucket Item Write`).
    */
   access: S3CredentialsAccess;
 }
@@ -62,9 +63,10 @@ export interface S3Credentials extends Effect.Effect<
  * credentials and R2's S3 endpoint. `S3Credentials` provides both, resolved
  * per mode:
  *
- * - **Deployed** — Alchemy mints a scoped account API token for the Worker
- *   and derives S3 credentials from it (access key id = token id, secret =
- *   SHA-256 of the token value). The endpoint is
+ * - **Deployed** — Alchemy mints an account API token for the Worker whose
+ *   policy is scoped to this bucket only, and derives S3 credentials from it
+ *   (access key id = token id, secret = SHA-256 of the token value). The
+ *   endpoint is
  *   `https://{accountId}.r2.cloudflarestorage.com` (`.eu.`/`.fedramp.` for
  *   jurisdictional buckets). The value is injected as a secret.
  * - **`alchemy dev`** — a locally-emulated bucket is served on the Worker's
@@ -175,6 +177,7 @@ export const makeS3Credentials = (
       // Deploy-time only; its requirements (CloudflareEnvironment, the
       // token provider) are ambient wherever a Worker is evaluated, so they
       // are erased like `Binding.Host`'s.
+      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- deploy-time only; requirements are ambient where the Worker is evaluated
       yield* bindS3Credentials(host, bindingName, bucket, access) as Effect.Effect<void>;
     }
     // Captured at init; read at exec phase, where it is populated.