@effect-agent/platform-cloudflare 0.1.0-beta.10 → 0.1.0-beta.101

package/dist/Alarm.d.mts

@@ -0,0 +1,207 @@
+import { DurableObjectContext } from "./CloudflareBindings.mjs";
+import { s as CloudflareDurableRuntimeConfig } from "./CloudflareConfig-DKXGo8L3.mjs";
+import { Cause, Context, DateTime, Effect, Layer, Option, Schema, Scope } from "effect";
+import { DurableBindingFailure } from "effect-agent/agent-registration";
+import { DurableAgentRuntime, DurableWorkerFailure } from "effect-agent/durable-agent-runtime";
+import { SubmissionLedger } from "effect-agent/submission-ledger";
+import { ThreadProjectionError, ThreadProjectionMaintenance } from "effect-agent/thread-projection-maintenance";
+import { SqlClient } from "effect/unstable/sql/SqlClient";
+declare namespace Alarm_d_exports {
+  export { DurableAlarmError, DurableAlarmService, MaintenancePassFailure, MaintenancePassReport, ThreadHostMaintenance, ThreadMaintenance, ThreadMaintenanceFailpoint, ThreadMaintenanceFailpointHandler, ThreadMaintenanceFailpointLocation, ThreadMessageDelivery, ThreadMutationGate, ThreadPublication, ThreadPublicationService, publishCommitted };
+}
+declare const DurableAlarmError_base: Schema.Class<DurableAlarmError, Schema.TaggedStruct<"DurableAlarmError", {
+  readonly operation: Schema.String;
+  readonly message: Schema.String;
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, Cause.YieldableError>;
+/**
+ * The single multiplexed Durable Object alarm (decision D-P6-2). A Durable Object has ONE
+ * alarm slot; every cadence the Node host ran on fibers (wake scan, lease expiry, settlement
+ * and abort re-checks, retry backoff) multiplexes into one idempotent maintenance pass, and
+ * the slot always holds the EARLIEST deadline any caller asked for.
+ *
+ * The alarm invariant (plan §1.4): every committed actionable mutation carries a newer durable
+ * maintenance generation and a committed alarm. Stable externally-driven waits may be
+ * nonterminal without retaining an alarm; their resolving mutation advances the generation and
+ * restores the alarm atomically.
+ */
+/** The Durable Object alarm API failed; surfaces on host entry points as a typed refusal. */
+export declare class DurableAlarmError extends DurableAlarmError_base {}
+declare const DurableAlarmService_base: Context.ServiceClass<DurableAlarmService, "@effect-agent/platform-cloudflare/DurableAlarmService", {
+  /** The scheduled deadline in epoch milliseconds, if any. */
+  readonly scheduled: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+  /** Replace the slot with this deadline. */
+  readonly scheduleAt: (epochMillis: number) => Effect.Effect<void, DurableAlarmError>;
+  /** Keep the EARLIER of the existing deadline and this one (the multiplexing rule). */
+  readonly ensureScheduledBy: (epochMillis: number) => Effect.Effect<void, DurableAlarmError>;
+  /**
+   * Arm an immediate alarm (the durable, coalescing local wake) — DEFERRED while a
+   * maintenance pass is executing. Workerd cancels an in-flight alarm handler when a new
+   * EARLIER deadline is written during its execution (`requestScheduledAlarm`), and the
+   * maintenance pass runs INSIDE the alarm handler: an immediate wake landing mid-pass
+   * (a routed port mutation, a sibling's `wake()`, the coordinator's own local notify)
+   * would kill the running Attempt — manufacturing an ownership loss no real eviction
+   * caused, and routing open uncertain-class Tool Calls into spurious Unknown Outcomes.
+   * Deferral is contract-safe: wakes are droppable hints, every mutating entry point
+   * pre-arms BEFORE its first durable mutation (the alarm invariant never rests on this
+   * call). The pass's durable generation check observes any racing mutation, so the
+   * in-memory hint does not need to be flushed after a stable wait is acknowledged.
+   */
+  readonly scheduleNow: Effect.Effect<void, DurableAlarmError>;
+  /**
+   * Run one maintenance pass with wake deferral (see `scheduleNow`). Calls made while `body`
+   * executes are droppable promptness hints; correctness rests on the durable generation.
+   */
+  readonly withWakesDeferred: <A, E, R>(body: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+  /** Clear the slot; correctness-sensitive clears live in maintenance generation transactions. */
+  readonly cancel: Effect.Effect<void, DurableAlarmError>;
+}>;
+/** `ctx.storage` alarm slot as an Effect service; storage is truth, never a memory field. */
+export declare class DurableAlarmService extends DurableAlarmService_base {
+  static readonly layer: Layer.Layer<DurableAlarmService, never, DurableObjectContext | SqlClient>;
+}
+declare const MaintenancePassReport_base: Schema.Class<MaintenancePassReport, Schema.Struct<{
+  /** `caught-up` ran no runtime work (publication may be pending); `actionable` ran recovery. */
+  readonly phase: Schema.Literals<readonly ["caught-up", "actionable"]>;
+  /** Recovery decisions executed (or deferred) BEFORE any new claim in this pass. */
+  readonly recovered: Schema.Int;
+  /** Whether the head Attempt settled. Joined input may settle with that head. */
+  readonly settled: Schema.Int;
+  /** Submissions still nonterminal after the pass (suspended/unknown lanes stay honest). */
+  readonly nonterminal: Schema.Int;
+  /** `rearmed` for dirty/autonomous work, `cleared` for stable waits or settlement. */
+  readonly alarm: Schema.Literals<readonly ["rearmed", "cleared"]>;
+}>, {}>;
+/** What one maintenance pass did — auditable evidence mirroring `NodeDurableHost`'s report. */
+export declare class MaintenancePassReport extends MaintenancePassReport_base {}
+/** Fault boundaries around every maintenance-owned durable mutation. */
+export type ThreadMaintenanceFailpointLocation = "maintenance:dirty:before" | "maintenance:dirty:after" | "maintenance:mutation:armed" | "maintenance:mutation:finished" | "maintenance:ensure:before" | "maintenance:ensure:after" | "maintenance:begin:before" | "maintenance:begin:after" | "maintenance:select:before" | "maintenance:select:after" | "maintenance:binding-retry:before" | "maintenance:binding-retry:after" | "maintenance:retry:before" | "maintenance:retry:after" | "maintenance:finish:before" | "maintenance:finish:after";
+export type ThreadMaintenanceFailpointHandler = (location: ThreadMaintenanceFailpointLocation) => Effect.Effect<void>;
+declare const ThreadMaintenanceFailpoint_base: Context.ServiceClass<ThreadMaintenanceFailpoint, "@effect-agent/platform-cloudflare/ThreadMaintenanceFailpoint", {
+  readonly hit: ThreadMaintenanceFailpointHandler;
+}>;
+/** Test-only fault authority; production uses the inert layer. */
+export declare class ThreadMaintenanceFailpoint extends ThreadMaintenanceFailpoint_base {
+  static readonly layer: Layer.Layer<ThreadMaintenanceFailpoint, never, never>;
+}
+/**
+ * Durable host publication of canonical records and ledger approval/abort/resolution intents.
+ * The host owns schema-versioned cursors, destination idempotency and acknowledgement. Delivery
+ * is at least once. Hooks must not write the alarm slot or mutate the supplied raw source ports.
+ *
+ * `invalidate`, `prepareGeneration` and `pendingDeadline` must be bounded local operations.
+ * `prepareGeneration` durably invalidates a scan only when its generation changes; repeated
+ * calls must preserve partial scan progress. It runs with no source mutation in flight.
+ * Use this gate only for publication required before dependent native execution. Independent
+ * UI relays and outboxes belong to ThreadHostMaintenance.
+ * `drain` performs bounded delivery and persists retries before returning. A pending deadline
+ * defers runtime recovery/Attempts, allowing committed host publications to drain first.
+ * Unexpected hook failures leave the prearmed generation for retry. Hooks acquire per-call
+ * resources with Effect.scoped; Layer construction owns incarnation resources (eviction need
+ * not run finalizers). Do not hold a local hook behind network I/O or call back into producers.
+ */
+export interface ThreadPublicationService {
+  readonly invalidate: Effect.Effect<void, DurableAlarmError>;
+  readonly prepareGeneration: (generation: bigint) => Effect.Effect<void, DurableAlarmError>;
+  readonly drain: Effect.Effect<void, DurableAlarmError>;
+  readonly pendingDeadline: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+}
+declare const ThreadPublication_base: Context.ServiceClass<ThreadPublication, "@effect-agent/platform-cloudflare/ThreadPublication", ThreadPublicationService>;
+/** Opt in with `ThreadObject.layer(registrations, { publication: Layer.effect(ThreadPublication)(...) })`. */
+export declare class ThreadPublication extends ThreadPublication_base {
+  static readonly layer: Layer.Layer<ThreadPublication, never, never>;
+}
+/**
+ * Host-assembled native message recovery. The driver bounds each actual Claim and persists its
+ * timeout/retry before this pump returns. Do not add a second timer starting at batch selection:
+ * local Claim setup may take time, and expiration still owes the driver's local retry commit.
+ */
+export declare const ThreadMessageDelivery: Context.Reference<{
+  readonly drainUntil: (sourceFinished: Effect.Effect<void>, dispatchUntil: DateTime.Utc) => Effect.Effect<void, DurableAlarmError, Scope.Scope>;
+  readonly pendingDeadline: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+}>;
+/**
+ * Application obligations sharing this Object's alarm. Admit one initial external wave even on
+ * a caught-up pass, then respond to wakes while native work runs. sourceFinished closes only
+ * admission of NEW external waves. Keep local admission/hub subscriptions in the supplied event
+ * Scope until maintenance tears it down; do not scope them to sourceFinished or to this Effect.
+ * No deadline sleeps or automatic retry loops. Return after already-admitted waves finish.
+ *
+ * Declare a finite whole-wave allowance (1..300000ms): maximum for parallel lanes, sum for
+ * sequential operations. Admit a wave only if its allowance fits before dispatchUntil. Later
+ * arrivals cannot renew the retirement window. Maintenance bounds the join after sourceFinished,
+ * interrupts and joins event Scope, then reads local deadlines under the mutation gate.
+ *
+ * Setup and pendingDeadline are bounded local operations. Persist claims/envelopes before
+ * dispatch; interrupted waits leave exact retries/receipts recoverable. Cancellation is local,
+ * not remote rollback. Retry accounting is unchanged. Network waits/finalizers must be
+ * interruptible; short local atomic commits may be uninterruptible. Hooks never write the raw
+ * alarm slot. Required native publication gates belong to ThreadPublication.
+ */
+export declare const ThreadHostMaintenance: Context.Reference<{
+  readonly dispatchTimeoutMillis: number;
+  readonly drainUntil: (sourceFinished: Effect.Effect<void>, dispatchUntil: DateTime.Utc) => Effect.Effect<void, DurableAlarmError, Scope.Scope>;
+  readonly pendingDeadline: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+}>;
+/** @internal A committed source operation must not become a failed operation because delivery failed. */
+export declare const publishCommitted: Effect.Effect<void, never, ThreadPublication>;
+declare const ThreadMutationGate_base: Context.ServiceClass<ThreadMutationGate, "@effect-agent/platform-cloudflare/internal/ThreadMutationGate", {
+  readonly withMutation: <A, E, R>(body: Effect.Effect<A, E, R>,
+  /**
+   * Native admission, approval, abort and unknown resolution keep the default true.
+   * Projection/relay/reply receipt-only bookkeeping must use false: its local durable
+   * pendingDeadline owns scheduling without creating native recovery debt.
+   */
+  options?: {
+    readonly invalidatesRecovery: boolean;
+  }) => Effect.Effect<A, E | DurableAlarmError, R>;
+  readonly withSnapshot: <A, E, R>(body: (active: number) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}>;
+/**
+ * Shared prearm/acknowledgement boundary for ingress and runtime-owned producers.
+ * `ThreadObject.layer` provides this same instance in its Services. Rebuilt runtime/maintenance
+ * Layers must reuse that instance; a second gate cannot observe the native producers' activity.
+ */
+export declare class ThreadMutationGate extends ThreadMutationGate_base {
+  static readonly layer: Layer.Layer<ThreadMutationGate, never, CloudflareDurableRuntimeConfig | DurableObjectContext | SqlClient | ThreadMaintenanceFailpoint>;
+}
+export type MaintenancePassFailure = DurableWorkerFailure | DurableBindingFailure | DurableAlarmError | ThreadProjectionError;
+declare const ThreadMaintenance_base: Context.ServiceClass<ThreadMaintenance, "@effect-agent/platform-cloudflare/ThreadMaintenance", {
+  /** One idempotent pass; failures propagate after durably scheduling bounded recovery. */
+  readonly pass: Effect.Effect<MaintenancePassReport, MaintenancePassFailure>;
+  /**
+   * Constructor gate: initialize/inspect only the O(1) maintenance record and ensure a dirty
+   * generation has an alarm. It never scans the ledger or canonical history.
+   */
+  readonly ensureAlarm: Effect.Effect<void, MaintenancePassFailure>;
+  /**
+   * Serialize the pre-arm boundary with pass acknowledgement, advance the durable dirty
+   * generation and arm the alarm in one transaction BEFORE running the caller's mutation.
+   * A pass cannot acknowledge while that mutation remains in flight.
+   */
+  readonly withMutation: <A, E, R>(body: Effect.Effect<A, E, R>) => Effect.Effect<A, E | DurableAlarmError, R>;
+}>;
+/**
+ * Incremental, quiescent maintenance over a durable dirty/processed generation (issue #93).
+ *
+ * `pass` = generation snapshot/pre-arm → recovery → one head Attempt → generation acknowledgement:
+ *
+ * 1. One storage transaction reads dirty/processed and re-arms before work. A caught-up forced
+ *    alarm takes an O(1) path without recovery, ledger scans, or canonical-history reads.
+ * 2. Recovery strictly precedes a new claim. One head Attempt advances the lane and requests
+ *    a safe yield after ten minutes. The whole event has a fourteen-minute cooperative timeout.
+ * 3. Auxiliary dispatch and listeners belong to the event Scope. After native completion,
+ *    stop new external waves, join native delivery through its driver-owned Claim deadline,
+ *    and bound host/backfill work by explicit allowances before closing and joining Scope.
+ *    Ordinary auxiliary setup failures are reported after the one native opportunity.
+ * 4. The final transaction acknowledges only the generation observed at pass start. A racing
+ *    mutation therefore remains `dirty > processed` and retains its atomically-established alarm.
+ * 5. Stable external waits acknowledge and clear. Autonomous retry, indeterminate, and lease
+ *    recovery states leave their generation dirty and retain bounded backoff rearming.
+ */
+export declare class ThreadMaintenance extends ThreadMaintenance_base {
+  static readonly layer: Layer.Layer<ThreadMaintenance, never, ThreadMutationGate | ThreadPublication | ThreadProjectionMaintenance | DurableAgentRuntime | SubmissionLedger | DurableAlarmService | ThreadMaintenanceFailpoint | CloudflareDurableRuntimeConfig | DurableObjectContext | SqlClient>;
+}
+//#endregion
+export { Alarm_d_exports as t };
+//# sourceMappingURL=Alarm.d.mts.map