effect-cf 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {

package/src/AiGateway.ts

@@ -1,4 +1,4 @@
-import { Context, Data, Effect, type Layer } from "effect";
+import { Context, Data, Effect, type Layer, Schema as S } from "effect";
 import type { AiGateway as CloudflareAiGateway } from "@cloudflare/workers-types";
 
 import * as Binding from "./Binding";
@@ -37,6 +37,46 @@ export type AiGatewayProvider = NonNullable<Parameters<AiGatewayBinding["getUrl"
 export type AiGatewayUniversalRequest = Exclude<AiGatewayRunData, ReadonlyArray<unknown>>;
 export type AiGatewayHeaders = NonNullable<AiGatewayUniversalRequest["headers"]>;
 export type AiGatewayRunOptions = Parameters<CloudflareAiGateway["run"]>[1];
+type AiGatewayBindingCandidate = Parameters<typeof isWorkersAiBinding>[0];
+
+const AiGatewayMetadata = S.Record(S.String, S.Union([S.String, S.Number, S.Boolean, S.Null]));
+const AiGatewayHttpMetadata = S.Union([AiGatewayMetadata, S.fromJsonString(AiGatewayMetadata)]);
+const AiGatewayLogResponse = S.Struct({
+  success: S.Literal(true),
+  result: S.Struct({
+    id: S.String,
+    provider: S.String,
+    model: S.String,
+    model_type: S.optional(S.String),
+    path: S.String,
+    duration: S.Number,
+    request_type: S.optional(S.String),
+    request_content_type: S.optional(S.String),
+    status_code: S.Number,
+    response_content_type: S.optional(S.String),
+    success: S.Boolean,
+    cached: S.Boolean,
+    tokens_in: S.optional(S.Number),
+    tokens_out: S.optional(S.Number),
+    metadata: S.optional(AiGatewayHttpMetadata),
+    step: S.optional(S.Number),
+    cost: S.optional(S.Number),
+    custom_cost: S.optional(S.Boolean),
+    request_size: S.Number,
+    request_head: S.optional(S.String),
+    request_head_complete: S.Boolean,
+    response_size: S.Number,
+    response_head: S.optional(S.String),
+    response_head_complete: S.Boolean,
+    created_at: S.DateFromString,
+  }),
+});
+const AiGatewayPatchLogResponse = S.Struct({
+  success: S.Literal(true),
+  result: S.Unknown,
+});
+const decodeAiGatewayLogResponse = S.decodeUnknownPromise(AiGatewayLogResponse);
+const decodeAiGatewayPatchLogResponse = S.decodeUnknownPromise(AiGatewayPatchLogResponse);
 
 export interface AiGatewayFetchOptions {
   readonly provider?: AiGatewayProvider;
@@ -131,7 +171,13 @@ const providerUrl = (baseUrl: string, path = "") => {
 const gatewayUrl = (definition: { readonly accountId: string; readonly gatewayId: string }) =>
   `https://gateway.ai.cloudflare.com/v1/${definition.accountId}/${definition.gatewayId}/`;
 
-export const isAiGatewayBinding = (value: unknown): value is WorkersAiBinding =>
+const ensureSuccessfulResponse = (response: Response): void => {
+  if (!response.ok) {
+    throw new Error(`AI Gateway HTTP request failed with status ${response.status}`);
+  }
+};
+
+export const isAiGatewayBinding = (value: AiGatewayBindingCandidate): value is WorkersAiBinding =>
   isWorkersAiBinding(value);
 
 export const makeClient = (definition: AiGatewayDefinition, gateway: AiGatewayBinding) =>
@@ -144,6 +190,7 @@ export const makeClient = (definition: AiGatewayDefinition, gateway: AiGatewayBi
       ) =>
         tryAiGatewayPromise(definition.binding, "run", () =>
           gateway.run(
+            // SAFETY: spreading the readonly batch produces the mutable array accepted by the binding.
             (Array.isArray(data) ? [...data] : data) as
               | AiGatewayUniversalRequest
               | Array<AiGatewayUniversalRequest>,
@@ -225,6 +272,7 @@ export const makeHttpClient = (
       Array.isArray(options.extraHeaders) ||
       options.extraHeaders instanceof Headers
     ) {
+      // SAFETY: the preceding branches retain only HeadersInit-compatible header containers.
       return options?.extraHeaders as HeadersInit | undefined;
     }
 
@@ -266,14 +314,17 @@ export const makeHttpClient = (
       ),
     ),
     patchLog: Effect.fn("AiGateway.patchLog")((logId: string, data: AiGatewayPatchLog) =>
-      tryAiGatewayPromise(binding, "patchLog", (signal) =>
-        request(providerUrl(gatewayUrl(definition), `logs/${logId}`).href, {
+      tryAiGatewayPromise(binding, "patchLog", async (signal) => {
+        const response = await request(providerUrl(gatewayUrl(definition), `logs/${logId}`).href, {
           method: "PATCH",
           body: JSON.stringify(data),
           headers: { "content-type": "application/json" },
           signal,
-        }).then(() => undefined),
-      ),
+        });
+
+        ensureSuccessfulResponse(response);
+        await decodeAiGatewayPatchLogResponse(await response.json());
+      }),
     ),
     getLog: Effect.fn("AiGateway.getLog")((logId: string) =>
       tryAiGatewayPromise(binding, "getLog", async (signal) => {
@@ -281,7 +332,10 @@ export const makeHttpClient = (
           signal,
         });
 
-        return (await response.json()) as AiGatewayLog;
+        ensureSuccessfulResponse(response);
+        const payload = await decodeAiGatewayLogResponse(await response.json());
+
+        return payload.result;
       }),
     ),
     rawUnsafe: Effect.fail(
@@ -315,6 +369,7 @@ export const Tag =
 
     const makeLayer = (definition: LayerOptions) => layer(tag, definition);
 
+    // SAFETY: these are exactly the members required by TagClass, attached to the matching service tag.
     return Object.assign(tag, {
       id,
       layer: makeLayer,

package/src/AnalyticsEngine.ts

@@ -10,6 +10,7 @@ import {
   Effect,
   Layer,
   Option,
+  Predicate,
   Result,
   Schema as S,
 } from "effect";
@@ -321,7 +322,7 @@ const byteLength = (value: AnalyticsEngineFieldValue) => {
     return 0;
   }
 
-  return typeof value === "string" ? textEncoder.encode(value).byteLength : value.byteLength;
+  return Predicate.isString(value) ? textEncoder.encode(value).byteLength : value.byteLength;
 };
 
 const lengthViolation = (
@@ -420,11 +421,15 @@ const schemaViolation = (
 
 const toAnalyticsEngineDataPoint = (
   dataPoint: S.Schema.Type<typeof AnalyticsEngineDataPointSchema>,
-): AnalyticsEngineDataPoint => ({
-  ...(dataPoint.indexes === undefined ? {} : { indexes: [...dataPoint.indexes] }),
-  ...(dataPoint.doubles === undefined ? {} : { doubles: [...dataPoint.doubles] }),
-  ...(dataPoint.blobs === undefined ? {} : { blobs: [...dataPoint.blobs] }),
-});
+): AnalyticsEngineDataPoint => {
+  const result: AnalyticsEngineDataPoint = {};
+
+  if (dataPoint.indexes !== undefined) result.indexes = [...dataPoint.indexes];
+  if (dataPoint.doubles !== undefined) result.doubles = [...dataPoint.doubles];
+  if (dataPoint.blobs !== undefined) result.blobs = [...dataPoint.blobs];
+
+  return result;
+};
 
 const validateDataPoint = (
   binding: string,
@@ -678,13 +683,10 @@ const makeQueryClientWith = (
 export const makeQueryClient = (definition: AnalyticsEngineQueryDefinition) =>
   Effect.map(HttpClient.HttpClient, (httpClient) => makeQueryClientWith(definition, httpClient));
 
-export const isAnalyticsEngineDataset = (value: unknown): value is AnalyticsEngineBinding => {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-
-  return typeof Reflect.get(value, "writeDataPoint") === "function";
-};
+export const isAnalyticsEngineDataset = <Candidate>(
+  value: Candidate,
+): value is Candidate & AnalyticsEngineBinding =>
+  Predicate.hasProperty(value, "writeDataPoint") && Predicate.isFunction(value.writeDataPoint);
 
 export const makeClient =
   (definition: AnalyticsEngineDefinition, defaults?: AnalyticsEngineWritePolicy) =>
@@ -793,6 +795,7 @@ export const Tag =
 
     const makeLayer = (definition: LayerOptions) => layer(tag, definition);
 
+    // SAFETY: these are exactly the members required by TagClass, attached to the matching service tag.
     return Object.assign(tag, {
       id,
       layer: makeLayer,
@@ -811,6 +814,7 @@ export const QueryTag =
     const makeLayerFetchConfig = (config?: Config.Config<AnalyticsEngineQueryDefinition>) =>
       layerFetchConfig(tag, config);
 
+    // SAFETY: these are exactly the members required by QueryTagClass, attached to the matching service tag.
     return Object.assign(tag, {
       id,
       layer: makeLayer,

package/src/Artifacts.ts

@@ -6,7 +6,7 @@ import type {
   ArtifactsTokenInfo as CloudflareArtifactsTokenInfo,
   ArtifactsTokenListResult as CloudflareArtifactsTokenListResult,
 } from "@cloudflare/workers-types";
-import { Context, Data, Effect, type Layer } from "effect";
+import { Context, Data, Effect, type Layer, Predicate, Schema } from "effect";
 
 import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
@@ -31,6 +31,7 @@ export type ArtifactsOperation =
   | "getToken"
   | "revokeToken"
   | "fork"
+  | "info"
   | "log"
   | "readCommit"
   | "readTree"
@@ -136,34 +137,37 @@ export type ArtifactsTokenInfo = CloudflareArtifactsTokenInfo;
 /** Repository token list result. */
 export type ArtifactsTokenListResult = CloudflareArtifactsTokenListResult;
 
-/**
- * Commit history returned by `log()`.
- *
- * Cloudflare currently documents this generated type by name but does not
- * publish its fields in the binding reference or Workers type declarations.
- */
-export interface ArtifactsLogResult {
-  readonly [field: string]: unknown;
+/** Identity recorded for a Git commit author or committer. */
+export interface ArtifactsCommitIdentity {
+  readonly name: string;
+  readonly email: string;
 }
 
-/**
- * Parsed Git commit returned by `readCommit()`.
- *
- * Cloudflare currently documents this generated type by name but does not
- * publish its fields in the binding reference or Workers type declarations.
- */
+/** Parsed Git commit returned by `readCommit()` and `log()`. */
 export interface ArtifactsCommit {
-  readonly [field: string]: unknown;
+  readonly hash: string;
+  readonly treeHash: string;
+  readonly message: string;
+  readonly author: ArtifactsCommitIdentity;
+  readonly committer: ArtifactsCommitIdentity;
+  readonly parents: ReadonlyArray<string>;
+  /** Unix timestamp in seconds. */
+  readonly authoredAt: number;
+  /** Unix timestamp in seconds. */
+  readonly committedAt: number;
 }
 
+/** Bare commit array returned by `log()`. */
+export type ArtifactsLogResult = ReadonlyArray<ArtifactsCommit>;
+
 /**
  * Parsed Git tree returned by `readTree()`.
  *
  * Cloudflare currently documents this generated type by name but does not
  * publish its fields in the binding reference or Workers type declarations.
  */
-export interface ArtifactsTree {
-  readonly [field: string]: unknown;
+export interface ArtifactsTree<Field = unknown> {
+  readonly [field: string]: Field;
 }
 
 /** Options for `Artifacts.create()`. */
@@ -228,7 +232,15 @@ export interface ArtifactsLogOptions {
 }
 
 /** Runtime repository handle, including methods absent from current shipped Workers types. */
-export interface ArtifactsRepoBinding extends ArtifactsRepoInfo {
+export interface ArtifactsRepoBinding extends Partial<ArtifactsRepoInfo> {
+  /**
+   * Read repository metadata.
+   *
+   * Remote bindings expose method-only RPC handles and provide metadata only
+   * through this method. It is optional solely for compatibility with older
+   * local handles that expose metadata as data properties.
+   */
+  readonly info?: () => Promise<ArtifactsRepoInfo>;
   /**
    * Create a Git token for the repository.
    *
@@ -262,8 +274,15 @@ export interface ArtifactsBinding {
   readonly delete: (name: RepoName) => Promise<boolean>;
 }
 
-/** Effect wrapper around a repository handle returned by `Artifacts.get()`. */
+/**
+ * Effect wrapper around a repository handle returned by `Artifacts.get()`.
+ *
+ * The inherited metadata is the snapshot read while resolving the client.
+ * Use `info()` to refresh it from the repository handle.
+ */
 export interface ArtifactsRepoClient extends ArtifactsRepoInfo {
+  /** Read and validate the repository's current metadata. */
+  readonly info: () => Effect.Effect<ArtifactsRepoInfo, ArtifactsOperationError>;
   /**
    * Create a Git token for the repository.
    *
@@ -319,6 +338,11 @@ export type LayerOptions = {
   readonly binding: string;
 };
 
+interface MutableArtifactsErrorDetails {
+  code?: ArtifactsOperationError["code"];
+  numericCode?: number;
+}
+
 export interface TagClass<Self, Id extends string> extends Context.ServiceClass<
   Self,
   Id,
@@ -337,17 +361,18 @@ export interface TagClass<Self, Id extends string> extends Context.ServiceClass<
 const artifactsErrorDetails = (
   cause: unknown,
 ): Pick<ArtifactsOperationError, "code" | "numericCode"> => {
-  if (typeof cause !== "object" || cause === null) {
+  if (!Predicate.isObject(cause)) {
     return {};
   }
 
-  const code = Reflect.get(cause, "code");
-  const numericCode = Reflect.get(cause, "numericCode");
+  const code = Predicate.hasProperty(cause, "code") ? cause.code : undefined;
+  const numericCode = Predicate.hasProperty(cause, "numericCode") ? cause.numericCode : undefined;
+  const details: MutableArtifactsErrorDetails = {};
 
-  return {
-    ...(typeof code === "string" ? { code } : {}),
-    ...(typeof numericCode === "number" ? { numericCode } : {}),
-  };
+  if (Predicate.isString(code)) details.code = code;
+  if (Predicate.isNumber(numericCode)) details.numericCode = numericCode;
+
+  return details;
 };
 
 const artifactsError = (binding: string, operation: ArtifactsOperation, cause: unknown) =>
@@ -372,13 +397,53 @@ const spanOptions = (binding: string, operation: ArtifactsOperation) => ({
   attributes: { binding, operation },
 });
 
-const hasFunction = (value: object, key: string): boolean =>
-  typeof Reflect.get(value, key) === "function";
+const hasFunction = <Candidate, Key extends string>(
+  value: Candidate,
+  key: Key,
+): value is Candidate & Record<Key, (...args: ReadonlyArray<any>) => any> =>
+  Predicate.hasProperty(value, key) && Predicate.isFunction(value[key]);
+
+const ArtifactsRepoInfoSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  description: Schema.NullOr(Schema.String),
+  defaultBranch: Schema.String,
+  createdAt: Schema.String,
+  updatedAt: Schema.String,
+  lastPushAt: Schema.NullOr(Schema.String),
+  source: Schema.NullOr(Schema.String),
+  readOnly: Schema.Boolean,
+  remote: Schema.String,
+});
+
+const decodeRepoInfo = (
+  binding: string,
+  value: ArtifactsRepoInfo | ArtifactsRepoBinding,
+): Effect.Effect<ArtifactsRepoInfo, ArtifactsOperationError> =>
+  Schema.decodeUnknownEffect(ArtifactsRepoInfoSchema)(value).pipe(
+    Effect.mapError((cause) => artifactsError(binding, "info", cause)),
+  );
+
+const readRepoInfo = (
+  binding: string,
+  repo: ArtifactsRepoBinding,
+): Effect.Effect<ArtifactsRepoInfo, ArtifactsOperationError> => {
+  if (hasFunction(repo, "info")) {
+    return tryArtifactsPromise(binding, "info", () => repo.info()).pipe(
+      Effect.flatMap((info) => decodeRepoInfo(binding, info)),
+      Effect.withSpan("Artifacts.info", spanOptions(binding, "info")),
+    );
+  }
+
+  return decodeRepoInfo(binding, repo).pipe(
+    Effect.withSpan("Artifacts.info", spanOptions(binding, "info")),
+  );
+};
 
 /** Tests whether a value exposes the complete documented Artifacts repo handle API. */
-export const isArtifactsRepoBinding = (value: unknown): value is ArtifactsRepoBinding =>
-  typeof value === "object" &&
-  value !== null &&
+export const isArtifactsRepoBinding = <Candidate>(
+  value: Candidate,
+): value is Candidate & ArtifactsRepoBinding =>
   hasFunction(value, "createToken") &&
   hasFunction(value, "listTokens") &&
   hasFunction(value, "revokeToken") &&
@@ -388,26 +453,22 @@ export const isArtifactsRepoBinding = (value: unknown): value is ArtifactsRepoBi
   hasFunction(value, "readTree");
 
 /** Tests whether a value exposes the complete documented Artifacts namespace API. */
-export const isArtifactsBinding = (value: unknown): value is ArtifactsBinding =>
-  typeof value === "object" &&
-  value !== null &&
+export const isArtifactsBinding = <Candidate>(
+  value: Candidate,
+): value is Candidate & ArtifactsBinding =>
   hasFunction(value, "create") &&
   hasFunction(value, "get") &&
   hasFunction(value, "import") &&
   hasFunction(value, "list") &&
   hasFunction(value, "delete");
 
-const wrapRepo = (binding: string, repo: ArtifactsRepoBinding): ArtifactsRepoClient => ({
-  id: repo.id,
-  name: repo.name,
-  description: repo.description,
-  defaultBranch: repo.defaultBranch,
-  createdAt: repo.createdAt,
-  updatedAt: repo.updatedAt,
-  lastPushAt: repo.lastPushAt,
-  source: repo.source,
-  readOnly: repo.readOnly,
-  remote: repo.remote,
+const wrapRepo = (
+  binding: string,
+  repo: ArtifactsRepoBinding,
+  info: ArtifactsRepoInfo,
+): ArtifactsRepoClient => ({
+  ...info,
+  info: () => readRepoInfo(binding, repo),
   createToken: Effect.fn(
     "Artifacts.createToken",
     spanOptions(binding, "createToken"),
@@ -463,7 +524,9 @@ export const makeClient =
       tryArtifactsPromise(definition.binding, "get", () => artifacts.get(name)).pipe(
         Effect.flatMap((repo) =>
           isArtifactsRepoBinding(repo)
-            ? Effect.succeed(wrapRepo(definition.binding, repo))
+            ? readRepoInfo(definition.binding, repo).pipe(
+                Effect.map((info) => wrapRepo(definition.binding, repo, info)),
+              )
             : Effect.fail(
                 artifactsError(
                   definition.binding,
@@ -512,6 +575,7 @@ export const Tag =
 
     const makeLayer = (definition: LayerOptions) => layer(tag, definition);
 
+    // SAFETY: these are exactly the members required by TagClass, attached to the matching service tag.
     return Object.assign(tag, {
       id,
       layer: makeLayer,

package/src/Binding.ts

@@ -1,4 +1,4 @@
-import { Context, Data, Effect, Layer } from "effect";
+import { Context, Data, Effect, Layer, Predicate } from "effect";
 
 import { WorkerEnvironment, type WorkerEnv } from "./Environment";
 
@@ -28,22 +28,25 @@ export interface ValidationOptions {
 
 const defaultExpected = "Cloudflare binding resource";
 
-const isPropertyTarget = (value: unknown): value is object =>
-  (typeof value === "object" || typeof value === "function") && value !== null;
+type BindingCandidate = Parameters<typeof Predicate.isUnknown>[0];
+type PropertyTarget = { readonly constructor?: Function };
 
-const getObjectName = (value: object | Function): string => {
+const isPropertyTarget = (value: BindingCandidate): value is PropertyTarget =>
+  Predicate.isObjectOrArray(value) || Predicate.isFunction(value);
+
+const getObjectName = (value: PropertyTarget): string => {
   const tag = (() => {
     try {
       return Object.prototype.toString.call(value).slice("[object ".length, -1);
     } catch {
-      return typeof value;
+      return Predicate.isFunction(value) ? "function" : "object";
     }
   })();
   const constructorName = (() => {
     try {
       return "constructor" in value &&
-        typeof value.constructor === "function" &&
-        typeof value.constructor.name === "string"
+        Predicate.isFunction(value.constructor) &&
+        Predicate.isString(value.constructor.name)
         ? value.constructor.name
         : undefined;
     } catch {
@@ -62,7 +65,7 @@ const getObjectName = (value: object | Function): string => {
   return tag;
 };
 
-const propertyNames = (value: object | Function): ReadonlyArray<string> => {
+const propertyNames = (value: PropertyTarget): ReadonlyArray<string> => {
   const names = new Set<string>();
 
   for (const target of [value, Object.getPrototypeOf(value)] as const) {
@@ -82,21 +85,27 @@ const propertyNames = (value: object | Function): ReadonlyArray<string> => {
   return [...names].filter((name) => name !== "constructor").sort();
 };
 
-const isMethod = (value: object | Function, name: string): boolean => {
+const isMethod = (value: PropertyTarget, name: string): boolean => {
   try {
-    return typeof Reflect.get(value, name) === "function";
+    return Predicate.hasProperty(value, name) && Predicate.isFunction(value[name]);
   } catch {
     return false;
   }
 };
 
-const describeActual = (value: unknown): string => {
+const describeActual = (value: BindingCandidate): string => {
   if (value === null) {
     return "null";
   }
 
-  if (typeof value !== "object" && typeof value !== "function") {
-    return typeof value;
+  if (!isPropertyTarget(value)) {
+    if (Predicate.isString(value)) return "string";
+    if (Predicate.isNumber(value)) return "number";
+    if (Predicate.isBoolean(value)) return "boolean";
+    if (Predicate.isBigInt(value)) return "bigint";
+    if (Predicate.isSymbol(value)) return "symbol";
+
+    return "undefined";
   }
 
   const names = propertyNames(value);
@@ -117,7 +126,7 @@ const describeActual = (value: unknown): string => {
 const getBinding = <Resource>(
   env: WorkerEnv,
   binding: string,
-  isResource: (value: unknown) => value is Resource,
+  isResource: (value: BindingCandidate) => value is Resource,
   options?: ValidationOptions,
 ): Effect.Effect<Resource, BindingNotFoundError | BindingValidationError> =>
   Effect.gen(function* () {
@@ -134,7 +143,7 @@ const getBinding = <Resource>(
       );
     }
 
-    const resource = Reflect.get(env, binding);
+    const resource = Predicate.hasProperty(env, binding) ? env[binding] : undefined;
 
     if (resource === undefined) {
       return yield* Effect.fail(
@@ -191,7 +200,7 @@ export interface BindingService<Self, Id extends string, Service> extends Contex
 const makeBindingLayer = <Self, Resource, Service>(
   tag: Context.Service<Self, Service>,
   binding: string,
-  isResource: (value: unknown) => value is Resource,
+  isResource: (value: BindingCandidate) => value is Resource,
   wrap: ((resource: Resource) => Service) | undefined,
   options: ValidationOptions | undefined,
 ): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment> =>
@@ -201,28 +210,29 @@ const makeBindingLayer = <Self, Resource, Service>(
       const env = yield* WorkerEnvironment;
       const resource = yield* getBinding(env, binding, isResource, options);
 
-      return wrap === undefined ? (resource as unknown as Service) : wrap(resource);
+      // SAFETY: the overload without wrap fixes Service to Resource; the other branch invokes wrap.
+      return wrap === undefined ? (resource as Resource & Service) : wrap(resource);
     }),
   );
 
 export function layer<Self, Resource>(
   tag: Context.Service<Self, Resource>,
   binding: string,
-  isResource: (value: unknown) => value is Resource,
+  isResource: (value: BindingCandidate) => value is Resource,
   wrap?: undefined,
   options?: ValidationOptions,
 ): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
 export function layer<Self, Resource, Service>(
   tag: Context.Service<Self, Service>,
   binding: string,
-  isResource: (value: unknown) => value is Resource,
+  isResource: (value: BindingCandidate) => value is Resource,
   wrap: (resource: Resource) => Service,
   options?: ValidationOptions,
 ): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
 export function layer<Self, Resource, Service = Resource>(
   tag: Context.Service<Self, Service>,
   binding: string,
-  isResource: (value: unknown) => value is Resource,
+  isResource: (value: BindingCandidate) => value is Resource,
   wrap?: (resource: Resource) => Service,
   options?: ValidationOptions,
 ): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment> {
@@ -233,27 +243,28 @@ export const Service = <Self>() => {
   function makeService<Id extends string, Resource>(
     id: Id,
     binding: string,
-    isResource: (value: unknown) => value is Resource,
+    isResource: (value: BindingCandidate) => value is Resource,
     wrap?: undefined,
     options?: ValidationOptions,
   ): BindingService<Self, Id, Resource>;
   function makeService<Id extends string, Resource, Service>(
     id: Id,
     binding: string,
-    isResource: (value: unknown) => value is Resource,
+    isResource: (value: BindingCandidate) => value is Resource,
     wrap: (resource: Resource) => Service,
     options?: ValidationOptions,
   ): BindingService<Self, Id, Service>;
   function makeService<Id extends string, Resource, Service = Resource>(
     id: Id,
     binding: string,
-    isResource: (value: unknown) => value is Resource,
+    isResource: (value: BindingCandidate) => value is Resource,
     wrap?: (resource: Resource) => Service,
     options?: ValidationOptions,
   ): BindingService<Self, Id, Service> {
     const tag = Context.Service<Self, Service>()(`effect-cf/Binding/${id}` as const);
     const serviceLayer = makeBindingLayer(tag, binding, isResource, wrap, options);
 
+    // SAFETY: the assigned metadata and layer exactly implement BindingService for this tag.
     return Object.assign(tag, {
       [TypeId]: TypeId,
       id,