@effect-agent/platform-cloudflare 0.1.0-beta.13 → 0.1.0-beta.130

package/dist/Alarm.d.mts

@@ -0,0 +1,244 @@
+import { DurableObjectContext } from "./CloudflareBindings.mjs";
+import { s as CloudflareDurableRuntimeConfig } from "./CloudflareConfig-DKXGo8L3.mjs";
+import { Cause, Context, Effect, Layer, Option, Schema, Scope } from "effect";
+import { DurableBindingFailure } from "effect-agent/agent-registration";
+import { DurableAgentRuntime, DurableRuntimeConfig, DurableWorkerFailure, RecoveryFailure } from "effect-agent/durable-agent-runtime";
+import { ThreadId } from "effect-agent/identifiers";
+import { OperationDenied } from "effect-agent/operation-authorizer";
+import { SubmissionLedger } from "effect-agent/submission-ledger";
+import { ThreadProjectionError, ThreadProjectionMaintenance } from "effect-agent/thread-projection-maintenance";
+import { WakeScheduler } from "effect-agent/wake-scheduler";
+import { SqlClient } from "effect/unstable/sql/SqlClient";
+declare namespace Alarm_d_exports {
+  export { DurableAlarmError, DurableAlarmService, MaintenancePassFailure, MaintenancePassReport, ThreadHostMaintenance, ThreadHostMaintenanceLane, ThreadMaintenance, ThreadMaintenanceFailpoint, ThreadMaintenanceFailpointHandler, ThreadMaintenanceFailpointLocation, ThreadMessageDelivery, ThreadMutationGate, ThreadPublication, ThreadPublicationService, ThreadRecoveryFault, 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 and Thread faults observed during this event. */
+  readonly recovered: Schema.Int;
+  /** Head Attempts settled during the event. Joined input may settle with each 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:recovery-status:before" | "maintenance:recovery-status:after" | "maintenance:retry:before" | "maintenance:retry:after" | "maintenance:checkpoint:before" | "maintenance:checkpoint: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. Preparation is a bounded local selection; the
+ * driver bounds each actual Claim and persists its timeout/retry before `run` returns.
+ * The alarm must not add a timer starting at selection: Claim setup and retry commits belong
+ * to the driver. The prepared allowance decides only whether a wave fits this event.
+ */
+export declare const ThreadMessageDelivery: Context.Reference<{
+  readonly prepare: Effect.Effect<{
+    readonly timeoutMillis: number;
+    readonly run: Effect.Effect<void, DurableAlarmError>;
+  }, DurableAlarmError>;
+  readonly pendingDeadline: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+}>;
+/**
+ * One independently schedulable application obligation. `run` selects and joins one finite
+ * wave, including its retry/receipt commits. The alarm gives every lane an initial opportunity,
+ * then checks its local pending deadline on completion, native progress, wakes and bounded scans.
+ * No subscriptions, readiness acknowledgements, deadline sleeps or dispatch loops are needed.
+ *
+ * Declare a whole-wave allowance (1..300000ms), including selection, local commits and cleanup. A wave
+ * starts only if that allowance fits the event and later arrivals cannot renew it. A failed
+ * lane is not retried within the event. The alarm joins admitted work and closes its Scope
+ * before reading durable deadlines under the shared ThreadMutationGate.
+ *
+ * `pendingDeadline` is bounded local control state, never a retained-history scan. Persist
+ * envelopes/claims before dispatch; cancellation is local, not remote rollback. Network waits
+ * and finalizers must be interruptible; short atomic commits may be uninterruptible. Mutations
+ * use the shared gate and producers notify the existing WakeScheduler after commit. Hooks never
+ * write the raw alarm slot. Required native publication gates belong to ThreadPublication.
+ */
+export interface ThreadHostMaintenanceLane {
+  readonly dispatchTimeoutMillis: number;
+  readonly run: Effect.Effect<void, DurableAlarmError, Scope.Scope>;
+  readonly pendingDeadline: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+}
+/** Independent lanes share the existing alarm; compose hosts by concatenating their lanes. */
+export declare const ThreadHostMaintenance: Context.Reference<{
+  readonly lanes: ReadonlyArray<ThreadHostMaintenanceLane>;
+}>;
+/** @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 ThreadRecoveryFault_base: Schema.Class<ThreadRecoveryFault, Schema.Struct<{
+  readonly schemaVersion: Schema.Literal<1>;
+  readonly threadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">;
+  readonly firstFailedAt: Schema.Finite;
+  readonly lastFailedAt: Schema.Finite;
+  /** Earliest automatic recovery retry; new admissions do not erase this deadline. */
+  readonly retryAt: Schema.Finite;
+  /** Saturates at 2^31 - 1; one observation per Thread per recovery sweep. */
+  readonly attempts: Schema.Int;
+  readonly failure: typeof RecoveryFailure;
+}>, {}>;
+/**
+ * A durable observation of blocked recovery, independent of the execution journal. This is
+ * neither a Settlement nor proof that external effects did not happen. A successful recovery
+ * sweep clears it; repair must preserve canonical history and the original admission identity.
+ */
+export declare class ThreadRecoveryFault extends ThreadRecoveryFault_base {}
+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>;
+  /**
+   * Authorize `explain`, then read one bounded local record without reading execution history.
+   * None means no recorded fault, not proof of health or settlement. The host authenticates
+   * callers and verifies local Thread membership before exposing this service across RPC.
+   * Created, updated and cleared faults notify WakeScheduler after their durable commit.
+   * Provide OperationAuthorizer when constructing this Layer, as for DurableAgentRuntime.
+   */
+  readonly recoveryStatus: (threadId: ThreadId) => Effect.Effect<Option.Option<ThreadRecoveryFault>, DurableAlarmError | OperationDenied>;
+  /**
+   * 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).
+ *
+ * One physical event owns native scheduling, auxiliary delivery and final alarm rearming.
+ *
+ * 1. Prearm before any work. A caught-up native step uses the O(1) generation record without
+ *    recovery, ledger scans or canonical-history reads.
+ * 2. Reconcile before each head Attempt, then checkpoint only the observed generation. A racing
+ *    producer keeps its generation dirty and immediately eligible. Quiescent native retries
+ *    retain their durable backoff.
+ * 3. Admit at most two independent Thread Attempts, one active head per Thread.
+ *    Keep native and delivery admission open together while finite waves remain active, so
+ *    fresh replies and abort controls can progress during unrelated cleanup. Close atomically
+ *    at quiescence, or at the original ten-minute yield deadline, then join admitted waves.
+ * 4. Native message delivery retains its driver-owned Claim deadline. Host/backfill waves are
+ *    bounded independently; incoming native work never restarts or cancels their attempts.
+ *    Auxiliary failures are reported after the current native opportunity.
+ * 5. Close every event resource before the final gated deadline snapshot and alarm decision.
+ *    The whole event retains one fourteen-minute cooperative timeout.
+ */
+export declare class ThreadMaintenance extends ThreadMaintenance_base {
+  static readonly layer: Layer.Layer<ThreadMaintenance, never, ThreadMutationGate | ThreadPublication | ThreadProjectionMaintenance | DurableAgentRuntime | DurableRuntimeConfig | SubmissionLedger | WakeScheduler | DurableAlarmService | ThreadMaintenanceFailpoint | CloudflareDurableRuntimeConfig | DurableObjectContext | SqlClient>;
+}
+//#endregion
+export { Alarm_d_exports as t };
+//# sourceMappingURL=Alarm.d.mts.map