@effect-agent/platform-cloudflare 0.1.0-beta.111 → 0.1.0-beta.113

package/dist/Alarm.d.mts

@@ -2,13 +2,15 @@ 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 { 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, ThreadMaintenance, ThreadMaintenanceFailpoint, ThreadMaintenanceFailpointHandler, ThreadMaintenanceFailpointLocation, ThreadMessageDelivery, ThreadMutationGate, ThreadPublication, ThreadPublicationService, publishCommitted };
+  export { DurableAlarmError, DurableAlarmService, MaintenancePassFailure, MaintenancePassReport, ThreadHostMaintenance, ThreadMaintenance, ThreadMaintenanceActivity, ThreadMaintenanceFailpoint, ThreadMaintenanceFailpointHandler, ThreadMaintenanceFailpointLocation, ThreadMessageDelivery, ThreadMutationGate, ThreadPublication, ThreadPublicationService, ThreadRecoveryFault, publishCommitted };
 }
 declare const DurableAlarmError_base: Schema.Class<DurableAlarmError, Schema.TaggedStruct<"DurableAlarmError", {
   readonly operation: Schema.String;
@@ -64,7 +66,7 @@ export declare class DurableAlarmService extends DurableAlarmService_base {
 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. */
+  /** 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;
@@ -76,7 +78,7 @@ declare const MaintenancePassReport_base: Schema.Class<MaintenancePassReport, Sc
 /** 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:checkpoint:before" | "maintenance:checkpoint:after" | "maintenance:finish:before" | "maintenance:finish:after";
+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;
@@ -112,25 +114,49 @@ declare const ThreadPublication_base: Context.ServiceClass<ThreadPublication, "@
 export declare class ThreadPublication extends ThreadPublication_base {
   static readonly layer: Layer.Layer<ThreadPublication, never, never>;
 }
+declare const ThreadMaintenanceActivity_base: Context.ServiceClass<ThreadMaintenanceActivity, "@effect-agent/platform-cloudflare/ThreadMaintenanceActivity", {
+  /**
+   * Account for one finite selection/dispatch, through joined completion or interruption.
+   * Register before reading/claiming work. After dispatch closes the body is not started.
+   * Host waves retain their declared allowance from this call; message Claims keep the driver's
+   * own deadline. Waiting for notifications belongs outside this bracket.
+   */
+  readonly run: <R>(wave: Effect.Effect<void, DurableAlarmError, R>) => Effect.Effect<void, DurableAlarmError, R>;
+  /** Acknowledge all initial subscriptions/scans. Composite hosts use `all` below. */
+  readonly ready: Effect.Effect<void>;
+  /**
+   * Acquire an independent scoped subscription before the initial scan and `ready`.
+   * The returned wait observes coalesced native scan hints, including those published before
+   * its first execution. Each hint requests a current local due-work check.
+   */
+  readonly subscribeChanges: Effect.Effect<Effect.Effect<void>, never, Scope.Scope>;
+}>;
+/** Event-local accounting shared by the existing maintenance pumps and native scheduler. */
+export declare class ThreadMaintenanceActivity extends ThreadMaintenanceActivity_base {
+  /** Join child pumps; acknowledge the parent only after every child is ready or has exited. */
+  static readonly all: <A, E, R>(lanes: readonly Effect.Effect<A, E, R>[]) => Effect.Effect<readonly A[], E, R | ThreadMaintenanceActivity>;
+}
 /**
  * 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: (dispatchClosed: Effect.Effect<void>, dispatchUntil: DateTime.Utc) => Effect.Effect<void, DurableAlarmError, Scope.Scope>;
+  readonly drainUntil: (dispatchClosed: Effect.Effect<void>, dispatchUntil: DateTime.Utc) => Effect.Effect<void, DurableAlarmError, Scope.Scope | ThreadMaintenanceActivity>;
   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 until dispatchClosed. This closes only admission
- * of NEW external waves; native work can continue while admitted waves finish. Keep local
- * admission/hub subscriptions in the event Scope until maintenance tears it down.
+ * a caught-up pass, then respond to wakes and ThreadMaintenanceActivity.subscribeChanges until
+ * dispatchClosed. Yield the event's ThreadMaintenanceActivity to bracket each finite lane with
+ * run and acknowledge initial setup with ready.
+ * Passive subscriptions do not count as active work. Closure stops both new waves and native
+ * Attempts; local admission/control subscriptions belong to the event Scope until teardown.
  * 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 dispatchClosed,
+ * arrivals cannot renew an admitted wave's allowance. Maintenance bounds each registered wave,
  * interrupts and joins event Scope, then reads local deadlines under the mutation gate.
  *
  * Setup and pendingDeadline are bounded local operations. Persist claims/envelopes before
@@ -141,11 +167,28 @@ export declare const ThreadMessageDelivery: Context.Reference<{
  */
 export declare const ThreadHostMaintenance: Context.Reference<{
   readonly dispatchTimeoutMillis: number;
-  readonly drainUntil: (dispatchClosed: Effect.Effect<void>, dispatchUntil: DateTime.Utc) => Effect.Effect<void, DurableAlarmError, Scope.Scope>;
+  readonly drainUntil: (dispatchClosed: Effect.Effect<void>, dispatchUntil: DateTime.Utc) => Effect.Effect<void, DurableAlarmError, Scope.Scope | ThreadMaintenanceActivity>;
   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 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>,
   /**
@@ -175,6 +218,13 @@ declare const ThreadMaintenance_base: Context.ServiceClass<ThreadMaintenance, "@
    * 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.
+   * 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.
@@ -191,17 +241,17 @@ declare const ThreadMaintenance_base: Context.ServiceClass<ThreadMaintenance, "@
  *    recovery, ledger scans or canonical-history reads.
  * 2. Reconcile before each head Attempt, then checkpoint only the observed generation. A racing
  *    producer keeps its newer generation dirty. Native retries retain their durable backoff.
- * 3. After the initial native opportunity, stop admitting new external waves and let the
- *    active waves finish. While they remain in flight, native wakes and bounded scans can
- *    advance more heads. All Attempts share the event's original ten-minute yield deadline.
- * 4. Native message delivery retains its driver-owned Claim deadline. Host/backfill joins are
+ * 3. 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, before retiring listeners.
+ * 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 | SubmissionLedger | WakeScheduler | DurableAlarmService | ThreadMaintenanceFailpoint | CloudflareDurableRuntimeConfig | DurableObjectContext | SqlClient>;
+  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 };