effect-inngest 0.1.2 → 0.2.0-beta.0

package/src/Function.ts

@@ -2,8 +2,13 @@
  * @since 0.1.0
  */
 import { Array as Arr, Duration, Predicate, Schema } from "effect";
+import { pipeArguments, type Pipeable } from "effect/Pipeable";
+import * as Checkpoint from "./internal/checkpoint.js";
+import type { CheckpointingOption } from "./internal/checkpoint.js";
 import { timeStr } from "./internal/helpers.js";
 
+export type { CheckpointingOption } from "./internal/checkpoint.js";
+
 /**
  * @since 0.1.0
  * @category type ids
@@ -16,7 +21,7 @@ export const TypeId: unique symbol = Symbol.for("effect-inngest/Function");
  */
 export type TypeId = typeof TypeId;
 
-type EventSchema = Schema.Schema.Any & { readonly _tag: string };
+type EventSchema = Schema.Top & { readonly identifier: string };
 
 /**
  * An event-based trigger configuration.
@@ -98,7 +103,7 @@ interface RateLimitOption {
   /**
    * The period of time to allow the function to run `limit` times.
    */
-  readonly period: Duration.DurationInput;
+  readonly period: Duration.Input;
 }
 
 interface ThrottleOption {
@@ -119,7 +124,7 @@ interface ThrottleOption {
    * The period of time for the rate limit. Run starts are evenly spaced through
    * the given period. The minimum granularity is 1 second.
    */
-  readonly period: Duration.DurationInput;
+  readonly period: Duration.Input;
 
   /**
    * The number of runs allowed to start in the given window in a single burst.
@@ -138,14 +143,14 @@ interface DebounceOption {
   /**
    * The period of time to delay after receiving the last trigger to run the function.
    */
-  readonly period: Duration.DurationInput;
+  readonly period: Duration.Input;
 
   /**
    * The maximum time that a debounce can be extended before running.
    * If events are continually received within the given period, a function
    * will always run after the given timeout period.
    */
-  readonly timeout?: Duration.DurationInput;
+  readonly timeout?: Duration.Input;
 }
 
 interface BatchEventsOption {
@@ -159,7 +164,7 @@ interface BatchEventsOption {
    * If timeout is reached, the function will be invoked with a batch
    * even if it's not filled up to `maxSize`.
    */
-  readonly timeout: Duration.DurationInput;
+  readonly timeout: Duration.Input;
 
   /**
    * An optional key to use for batching.
@@ -192,14 +197,14 @@ interface TimeoutsOption {
    * This is, essentially, the amount of time that a function sits in the
    * queue before starting.
    */
-  readonly start?: Duration.DurationInput;
+  readonly start?: Duration.Input;
 
   /**
    * Finish represents the time between a function starting and the function
    * finishing. If a function takes longer than this time to finish, the
    * function is marked as cancelled.
    */
-  readonly finish?: Duration.DurationInput;
+  readonly finish?: Duration.Input;
 }
 
 interface SingletonOption {
@@ -237,7 +242,7 @@ interface CancellationOption {
    * specified, cancellation triggers are valid for up to a year or until the
    * function ends.
    */
-  readonly timeout?: Duration.DurationInput;
+  readonly timeout?: Duration.Input;
 }
 
 type Retries = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20;
@@ -321,6 +326,20 @@ export interface FunctionOptions {
    * Batch events configuration.
    */
   readonly batchEvents?: BatchEventsOption;
+
+  /**
+   * Whether to use checkpointing for executions of this function. Overrides
+   * the client-level `checkpointing` setting.
+   *
+   * - `false` disables checkpointing for this function.
+   * - `true` enables checkpointing with safe defaults
+   *   (`bufferedSteps: 1`, `maxInterval: 0`, `maxRuntime: 10s`).
+   * - An object lets you tune `bufferedSteps`, `maxInterval`, `maxRuntime`.
+   *
+   * Defaults to inheriting from the client-level setting (which itself
+   * defaults to enabled with safe defaults).
+   */
+  readonly checkpointing?: CheckpointingOption;
 }
 
 interface RegistrationConfig {
@@ -379,6 +398,11 @@ interface FunctionRegistration {
     readonly key?: string;
   };
   readonly idempotency?: string;
+  readonly checkpoint?: {
+    readonly batch_steps: number;
+    readonly batch_interval: string;
+    readonly max_runtime: string;
+  };
 }
 
 /**
@@ -390,9 +414,9 @@ interface FunctionRegistration {
 export interface InngestFunction<
   Tag extends string,
   Triggers extends Trigger,
-  Success extends Schema.Schema.Any,
+  Success extends Schema.Top,
   Options extends FunctionOptions = FunctionOptions,
-> {
+> extends Pipeable {
   readonly [TypeId]: TypeId;
   readonly _tag: Tag;
   readonly key: string;
@@ -407,7 +431,7 @@ export interface InngestFunction<
  * @category models
  */
 export declare namespace InngestFunction {
-  export type Any = InngestFunction<string, Trigger, Schema.Schema.Any, FunctionOptions>;
+  export type Any = InngestFunction<string, Trigger, Schema.Top, FunctionOptions>;
   export type Tag<F> = F extends InngestFunction<infer T, any, any, any> ? T : never;
   export type Triggers<F> = F extends InngestFunction<any, infer T, any, any> ? T : never;
   export type Events<F> =
@@ -428,6 +452,11 @@ const isEventTrigger = (t: Trigger): t is EventTrigger => Predicate.hasProperty(
 const Proto = {
   [TypeId]: TypeId,
 
+  pipe() {
+    // eslint-disable-next-line prefer-rest-params
+    return pipeArguments(this, arguments);
+  },
+
   toRegistration(this: InngestFunction.Any, config: RegistrationConfig): FunctionRegistration {
     const triggers: Array<{
       event?: string;
@@ -437,7 +466,7 @@ const Proto = {
 
     for (const t of this.triggers) {
       if (isEventTrigger(t)) {
-        triggers.push({ event: t.event._tag, expression: t.if });
+        triggers.push({ event: t.event.identifier, expression: t.if });
       } else {
         triggers.push({ cron: t.cron });
       }
@@ -484,7 +513,7 @@ const Proto = {
 
     const concurrency =
       opts.concurrency != null
-        ? typeof opts.concurrency === "number"
+        ? Predicate.isNumber(opts.concurrency)
           ? [{ limit: opts.concurrency }]
           : Arr.ensure(opts.concurrency).map((c) => ({
               key: c.key,
@@ -505,6 +534,13 @@ const Proto = {
 
     const idempotency = opts.idempotency;
 
+    // Function-level checkpoint config only — client-level default is
+    // applied at runtime by the handler. Mirrors how other client defaults
+    // (e.g. retries) interact with registration.
+    const resolvedCheckpoint =
+      opts.checkpointing !== undefined ? Checkpoint.resolveConfig(opts.checkpointing, undefined) : undefined;
+    const checkpoint = resolvedCheckpoint ? Checkpoint.toRegistration(resolvedCheckpoint) : undefined;
+
     const fnId = `${config.appId}-${this._tag}`;
     const stepUrl = new URL(config.url);
     stepUrl.searchParams.set("fnId", fnId);
@@ -532,6 +568,7 @@ const Proto = {
       singleton,
       batchEvents,
       idempotency,
+      checkpoint,
     };
   },
 };
@@ -574,7 +611,7 @@ type NormalizeTriggers<T extends TriggerInput> = T extends ReadonlyArray<Trigger
 export function make<
   const Tag extends string,
   T extends TriggerInput,
-  S extends Schema.Schema.Any,
+  S extends Schema.Top,
   const O extends FunctionOptions = {},
 >(
   tag: Tag,

package/src/Group.ts

@@ -1,11 +1,11 @@
 /**
  * @since 0.1.0
  */
-import * as HttpApp from "@effect/platform/HttpApp";
-import * as HttpClient from "@effect/platform/HttpClient";
-import * as HttpServerRequest from "@effect/platform/HttpServerRequest";
-import * as HttpServerResponse from "@effect/platform/HttpServerResponse";
-import * as UrlParams from "@effect/platform/UrlParams";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpEffect from "effect/unstable/http/HttpEffect";
+import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
+import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+import * as UrlParams from "effect/unstable/http/UrlParams";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -150,7 +150,7 @@ const Proto = {
           const fn = functions.get(tag)!;
           contextMap.set(fn.key, { handler, context });
         }
-        return Context.unsafeMake(contextMap);
+        return Context.makeUnsafe(contextMap);
       }),
     );
   },
@@ -162,7 +162,7 @@ const Proto = {
         const context = yield* Effect.context<never>();
         const contextMap = new Map<string, unknown>();
         contextMap.set(fn.key, { handler, context });
-        return Context.unsafeMake(contextMap);
+        return Context.makeUnsafe(contextMap);
       }),
     );
   },
@@ -199,8 +199,8 @@ export const make = <Fns extends ReadonlyArray<InngestFunction.Any>>(...fns: Fns
  * )
  * ```
  */
-export const toHttpApp = (group: InngestGroup.Any): HttpApp.Default<never, InngestClient | HttpClient.HttpClient> =>
-  Effect.gen(function* () {
+export const toHttpApp = Effect.fn("InngestGroup.toHttpApp")(
+  function* (group: InngestGroup.Any) {
     const request = yield* HttpServerRequest.HttpServerRequest;
     const method = request.method;
     const requestUrl = Option.match(HttpServerRequest.toURL(request), {
@@ -225,17 +225,30 @@ export const toHttpApp = (group: InngestGroup.Any): HttpApp.Default<never, Innge
     }
 
     if (method === "POST") {
-      const url = Option.getOrThrow(HttpServerRequest.toURL(request));
-
-      const ExecuteParams = Schema.Struct({
-        fnId: Schema.String,
-        stepId: Schema.optional(Schema.String),
+      const url = yield* Option.match(HttpServerRequest.toURL(request), {
+        onNone: () =>
+          Effect.fail(
+            HttpServerResponse.jsonUnsafe(
+              { error: "Unable to parse request URL" },
+              { status: 400, headers: { [Protocol.Headers.NoRetry]: "true" } },
+            ),
+          ),
+        onSome: (u) => Effect.succeed(u),
       });
 
-      const params = yield* UrlParams.schemaStruct(ExecuteParams)(UrlParams.fromInput(url.searchParams)).pipe(
-        Effect.catchAll(() =>
+      const ExecuteParamsSchema = UrlParams.schemaRecord.pipe(
+        Schema.decodeTo(
+          Schema.Struct({
+            fnId: Schema.String,
+            stepId: Schema.optional(Schema.String),
+          }),
+        ),
+      );
+
+      const params = yield* Schema.decodeUnknownEffect(ExecuteParamsSchema)(UrlParams.fromInput(url.searchParams)).pipe(
+        Effect.catch(() =>
           Effect.fail(
-            HttpServerResponse.unsafeJson(
+            HttpServerResponse.jsonUnsafe(
               { error: "Missing or invalid fnId query parameter" },
               { status: 400, headers: { [Protocol.Headers.NoRetry]: "true" } },
             ),
@@ -245,9 +258,9 @@ export const toHttpApp = (group: InngestGroup.Any): HttpApp.Default<never, Innge
 
       const body = yield* InternalHandler.verifyAndParseRequestBody(request).pipe(
         Effect.provide(SignatureLive),
-        Effect.catchAll((error) =>
+        Effect.catch((error) =>
           Effect.fail(
-            HttpServerResponse.unsafeJson(
+            HttpServerResponse.jsonUnsafe(
               { error: error.message },
               {
                 status: error._tag === "SignatureError" ? 401 : 400,
@@ -267,13 +280,13 @@ export const toHttpApp = (group: InngestGroup.Any): HttpApp.Default<never, Innge
     }
 
     return yield* HttpServerResponse.json({ error: `Method ${method} not allowed` }, { status: 405 });
-  }).pipe(
-    Effect.catchAllCause((cause) =>
-      HttpServerResponse.json({ error: "Internal server error", cause: String(cause) }, { status: 500 }).pipe(
-        Effect.orDie,
-      ),
+  },
+  Effect.catchCause((cause) =>
+    HttpServerResponse.json({ error: "Internal server error", cause: String(cause) }, { status: 500 }).pipe(
+      Effect.orDie,
     ),
-  );
+  ),
+);
 
 /**
  * Create a standalone web handler from an InngestGroup.
@@ -307,4 +320,4 @@ export const toWebHandler = <R, E>(
 ): {
   readonly handler: (request: Request, context?: Context.Context<never>) => Promise<Response>;
   readonly dispose: () => Promise<void>;
-} => HttpApp.toWebHandlerLayer(toHttpApp(group), Layer.mergeAll(options.layer, Layer.scope));
+} => HttpEffect.toWebHandlerLayer(toHttpApp(group), options.layer);

package/src/HttpApi.ts

@@ -1,12 +1,12 @@
 /**
  * @since 0.1.0
  */
-import * as HttpApi from "@effect/platform/HttpApi";
-import * as HttpApiBuilder from "@effect/platform/HttpApiBuilder";
-import * as HttpApiEndpoint from "@effect/platform/HttpApiEndpoint";
-import * as HttpApiGroup from "@effect/platform/HttpApiGroup";
-import * as HttpClient from "@effect/platform/HttpClient";
-import * as HttpServerRequest from "@effect/platform/HttpServerRequest";
+import * as HttpApi from "effect/unstable/httpapi/HttpApi";
+import * as HttpApiBuilder from "effect/unstable/httpapi/HttpApiBuilder";
+import * as HttpApiEndpoint from "effect/unstable/httpapi/HttpApiEndpoint";
+import * as HttpApiGroup from "effect/unstable/httpapi/HttpApiGroup";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
@@ -22,25 +22,34 @@ const ExecuteParams = Schema.Struct({
   stepId: Schema.optional(Schema.String),
 });
 
-class FunctionNotFoundError extends Schema.TaggedError<FunctionNotFoundError>()("FunctionNotFoundError", {
+class FunctionNotFoundError extends Schema.TaggedErrorClass<FunctionNotFoundError>()("FunctionNotFoundError", {
   message: Schema.String,
 }) {}
 
-const IntrospectEndpoint = HttpApiEndpoint.get("introspect", "/").addSuccess(Protocol.IntrospectionResponse);
-const RegisterEndpoint = HttpApiEndpoint.put("register", "/").addSuccess(Protocol.RegisterResponse);
-const ExecuteEndpoint = HttpApiEndpoint.post("execute", "/").setUrlParams(ExecuteParams).addSuccess(Schema.Unknown);
+const CommonErrors = [FunctionNotFoundError, InternalHandler.InvalidRequestError, InternalHandler.SignatureError];
+
+const IntrospectEndpoint = HttpApiEndpoint.get("introspect", "/", {
+  success: Protocol.IntrospectionResponse,
+  error: CommonErrors,
+});
+const RegisterEndpoint = HttpApiEndpoint.put("register", "/", {
+  success: Protocol.RegisterResponse,
+  error: CommonErrors,
+});
+const ExecuteEndpoint = HttpApiEndpoint.post("execute", "/", {
+  query: ExecuteParams,
+  success: Schema.Unknown,
+  error: CommonErrors,
+});
 
 /**
  * @since 0.1.0
  * @category api
  */
-export const InngestApiGroup = HttpApiGroup.make("inngest")
+export class InngestApiGroup extends HttpApiGroup.make("inngest")
   .add(IntrospectEndpoint)
   .add(RegisterEndpoint)
-  .add(ExecuteEndpoint)
-  .addError(FunctionNotFoundError, { status: 404 })
-  .addError(InternalHandler.InvalidRequestError, { status: 400 })
-  .addError(InternalHandler.SignatureError, { status: 401 });
+  .add(ExecuteEndpoint) {}
 
 type InngestApiGroupType = typeof InngestApiGroup;
 
@@ -48,8 +57,8 @@ type InngestApiGroupType = typeof InngestApiGroup;
  * @since 0.1.0
  * @category layers
  */
-export const layerGroup = <ApiId extends string, Groups extends HttpApiGroup.HttpApiGroup.Any, ApiError, ApiR>(
-  api: HttpApi.HttpApi<ApiId, Groups, ApiError, ApiR>,
+export const layerGroup = <ApiId extends string, Groups extends HttpApiGroup.Any>(
+  api: HttpApi.HttpApi<ApiId, Groups>,
   group: InngestGroup.Any,
 ): Layer.Layer<HttpApiGroup.ApiGroup<ApiId, "inngest">, never, InngestClient | HttpClient.HttpClient> => {
   const toUrl = (req: HttpServerRequest.HttpServerRequest) =>
@@ -59,24 +68,26 @@ export const layerGroup = <ApiId extends string, Groups extends HttpApiGroup.Htt
     });
 
   return HttpApiBuilder.group(
-    api as unknown as HttpApi.HttpApi<ApiId, InngestApiGroupType, ApiError, ApiR>,
+    api as unknown as HttpApi.HttpApi<ApiId, InngestApiGroupType>,
     "inngest",
-    (handlers) =>
-      handlers
+    Effect.fn(function* (handlers) {
+      return handlers
         .handle("introspect", ({ request }) =>
           InternalHandler.handleIntrospection(group, toUrl(request)).pipe(Effect.map((r) => r.body)),
         )
         .handle("register", ({ request }) =>
           InternalHandler.handleRegistration(group, toUrl(request)).pipe(Effect.map((r) => r.body)),
         )
-        .handleRaw("execute", ({ urlParams, request }) =>
+        .handleRaw("execute", ({ query, request }) =>
           InternalHandler.verifyAndParseRequestBody(request).pipe(
-            Effect.provide(SignatureLive),
-            Effect.flatMap((payload) =>
-              InternalHandler.handleExecution(group, urlParams.fnId, urlParams.stepId, payload),
-            ),
+            Effect.flatMap((payload) => InternalHandler.handleExecution(group, query.fnId, query.stepId, payload)),
             Effect.map((r) => r.body),
           ),
-        ),
-  ) as Layer.Layer<HttpApiGroup.ApiGroup<ApiId, "inngest">, never, InngestClient | HttpClient.HttpClient>;
+        );
+    }),
+  ).pipe(Layer.provide(SignatureLive)) as unknown as Layer.Layer<
+    HttpApiGroup.ApiGroup<ApiId, "inngest">,
+    never,
+    InngestClient | HttpClient.HttpClient
+  >;
 };

package/src/internal/checkpoint.ts

@@ -0,0 +1,218 @@
+/**
+ * Checkpoint configuration + per-execution state for spec §10 async
+ * checkpointing.
+ *
+ * Sync checkpointing (§10.3.2 / §10.4.2) is intentionally out of scope —
+ * it requires a durable endpoint primitive the SDK does not yet expose.
+ *
+ * @internal
+ */
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { timeStr } from "./helpers.js";
+import type * as Protocol from "./protocol.js";
+
+/**
+ * Tagged error returned by `InngestClient.checkpointAsync` when the API call
+ * fails (network error or non-2xx after retries). The driver and step tools
+ * treat this as a graceful-fallback signal — buffered steps are restored to
+ * the buffer so they get included in the final 206 response.
+ */
+export class CheckpointApiError extends Schema.TaggedErrorClass<CheckpointApiError>()("CheckpointApiError", {
+  message: Schema.String,
+  status: Schema.optionalKey(Schema.Number),
+}) {}
+
+/**
+ * User-facing checkpointing option, accepted on `ClientConfig.checkpointing`
+ * and `FunctionOptions.checkpointing`.
+ *
+ * - `false` disables checkpointing entirely (no API calls; classic 206-per-step).
+ * - `true` enables checkpointing with the safe defaults
+ *   (`bufferedSteps: 1`, `maxInterval: 0`, `maxRuntime: 10 seconds`).
+ * - An object lets you tune `bufferedSteps`, `maxInterval`, `maxRuntime`.
+ */
+export type CheckpointingOption =
+  | boolean
+  | {
+      readonly bufferedSteps?: number;
+      readonly maxInterval?: Duration.Input;
+      readonly maxRuntime?: Duration.Input;
+    };
+
+/**
+ * Resolved internal config — defaults applied, durations normalized.
+ */
+export interface CheckpointConfig {
+  readonly bufferedSteps: number;
+  readonly maxInterval: Duration.Duration;
+  readonly maxRuntime: Duration.Duration;
+}
+
+const DEFAULTS: CheckpointConfig = {
+  bufferedSteps: 1,
+  maxInterval: Duration.millis(0),
+  maxRuntime: Duration.seconds(10),
+};
+
+const normalize = (option: Exclude<CheckpointingOption, boolean>): CheckpointConfig => ({
+  bufferedSteps: option.bufferedSteps ?? DEFAULTS.bufferedSteps,
+  maxInterval: option.maxInterval !== undefined ? Duration.fromInputUnsafe(option.maxInterval) : DEFAULTS.maxInterval,
+  maxRuntime: option.maxRuntime !== undefined ? Duration.fromInputUnsafe(option.maxRuntime) : DEFAULTS.maxRuntime,
+});
+
+/**
+ * Resolve final config from function-level + client-level settings.
+ *
+ * Precedence: function-level explicit > client-level explicit > built-in
+ * defaults (default-ON, matching the TS reference SDK).
+ *
+ * Returns `undefined` if either level explicitly disables checkpointing.
+ */
+export const resolveConfig = (
+  fnLevel: CheckpointingOption | undefined,
+  clientLevel: CheckpointingOption | undefined,
+): CheckpointConfig | undefined => {
+  if (fnLevel === false) return undefined;
+  // Per the `CheckpointingOption` docstring, `true` means "enable with safe
+  // defaults" — it never inherits a client-level object. Explicit object at
+  // the fn level overrides everything; otherwise fall through to client.
+  if (fnLevel === true) return DEFAULTS;
+  if (fnLevel !== undefined) return normalize(fnLevel);
+  // fnLevel === undefined — use client-level
+  if (clientLevel === false) return undefined;
+  if (clientLevel === true) return DEFAULTS;
+  if (clientLevel !== undefined) return normalize(clientLevel);
+  // Default-ON: undefined at both levels
+  return DEFAULTS;
+};
+
+/**
+ * Registration payload fragment per spec §10.1.1.
+ */
+export interface RegistrationFragment {
+  readonly batch_steps: number;
+  readonly batch_interval: string;
+  readonly max_runtime: string;
+}
+
+export const toRegistration = (cfg: CheckpointConfig): RegistrationFragment => ({
+  batch_steps: cfg.bufferedSteps,
+  batch_interval: timeStr(cfg.maxInterval),
+  max_runtime: timeStr(cfg.maxRuntime),
+});
+
+/**
+ * Per-execution state for checkpoint mode. NOT a `Context.Service` — each
+ * `execute` call constructs its own and passes it directly to step tools and
+ * the driver.
+ *
+ * Internal `Ref`s are closure-private; only effectful ops are exposed. All
+ * ops are safe to sequence from a single fiber; the buffer/interval/runtime
+ * primitives are not designed for concurrent fibers (none are spawned today).
+ */
+export interface CheckpointState {
+  readonly config: CheckpointConfig;
+  readonly runId: string;
+  readonly fnId: string;
+  readonly qiId: string;
+  /** Append a sync opcode; flush if `bufferedSteps` or `maxInterval` reached. */
+  readonly bufferStep: (op: typeof Protocol.GeneratorOpcode.Type) => Effect.Effect<void>;
+  /**
+   * Best-effort flush. On API error the buffered steps are re-prepended so
+   * `drain` can include them in the terminal 206 (no step loss per §10.4.3).
+   */
+  readonly flush: Effect.Effect<void>;
+  /** Atomic snapshot + clear, for terminal response assembly. */
+  readonly drain: Effect.Effect<ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>>;
+  /** Signal that the handler's `maxRuntime` deadline fired (spec §10.4.1 #7). */
+  readonly markRuntimeExceeded: Effect.Effect<void>;
+  /** Query whether the `maxRuntime` deadline fired. */
+  readonly isRuntimeExceeded: Effect.Effect<boolean>;
+}
+
+/**
+ * Construct a `CheckpointState`. Caller supplies a pre-bound `checkpointAsync`
+ * callback (typically `(steps) => client.checkpointAsync({runId, fnId, qiId, steps})`),
+ * so this module has no dependency on `InngestClient`.
+ */
+export const make = (args: {
+  readonly config: CheckpointConfig;
+  readonly runId: string;
+  readonly fnId: string;
+  readonly qiId: string;
+  readonly checkpointAsync: (
+    steps: ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>,
+  ) => Effect.Effect<void, CheckpointApiError>;
+}): Effect.Effect<CheckpointState> =>
+  Effect.sync(() => {
+    const buffer = Ref.makeUnsafe<ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>>([]);
+    const intervalStartedAt = Ref.makeUnsafe<Option.Option<number>>(Option.none());
+    const runtimeExceeded = Ref.makeUnsafe(false);
+
+    const maxIntervalMs = Duration.toMillis(args.config.maxInterval);
+
+    // Extract-then-restore is NOT atomic across multiple fibers; a concurrent
+    // `bufferStep` between the `Ref.modify` snapshot and the error-path
+    // `Ref.update` restore would reorder opcodes. Request-scoped execution
+    // today only runs a single fiber, so this is safe. If parallel fibers
+    // are ever added here, guard `flushInner` with a `Semaphore(1)`.
+    const flushInner: Effect.Effect<void> = Effect.gen(function* () {
+      const steps = yield* Ref.modify(buffer, (current) => [
+        current,
+        [] as ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>,
+      ]);
+      if (steps.length === 0) return;
+      const result = yield* Effect.result(args.checkpointAsync(steps));
+      if (Result.isFailure(result)) {
+        // Restore at the head so subsequent `drain` includes them in the 206.
+        yield* Ref.update(buffer, (current) => [...steps, ...current]);
+        return;
+      }
+      yield* Ref.set(intervalStartedAt, Option.none());
+    });
+
+    const bufferStep = (op: typeof Protocol.GeneratorOpcode.Type): Effect.Effect<void> =>
+      Effect.gen(function* () {
+        const len = yield* Ref.modify(buffer, (current) => {
+          const next = [...current, op];
+          return [next.length, next] as const;
+        });
+        const now = yield* Clock.currentTimeMillis;
+        const start = yield* Ref.get(intervalStartedAt);
+
+        if (len >= args.config.bufferedSteps) {
+          yield* flushInner;
+          return;
+        }
+        if (Option.isSome(start) && maxIntervalMs > 0 && now - start.value >= maxIntervalMs) {
+          yield* flushInner;
+          return;
+        }
+        if (Option.isNone(start) && maxIntervalMs > 0) {
+          yield* Ref.set(intervalStartedAt, Option.some(now));
+        }
+      });
+
+    const drain: Effect.Effect<ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>> = Ref.modify(buffer, (current) => [
+      current,
+      [] as ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>,
+    ]);
+
+    return {
+      config: args.config,
+      runId: args.runId,
+      fnId: args.fnId,
+      qiId: args.qiId,
+      bufferStep,
+      flush: flushInner,
+      drain,
+      markRuntimeExceeded: Ref.set(runtimeExceeded, true),
+      isRuntimeExceeded: Ref.get(runtimeExceeded),
+    };
+  });