@effect-agent/platform-cloudflare 0.1.0-beta.14 → 0.1.0-beta.15

package/dist/index.d.mts

@@ -195,11 +195,10 @@ declare const DurableAlarmError_base: Schema.Class<DurableAlarmError, Schema.Tag
  * 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): committed nonterminal work implies a committed alarm.
- * It is established by pre-arming — every mutating entry point and every pass arms the alarm
- * BEFORE its durable mutations — so an eviction at any failpoint leaves a persisted alarm
- * that workerd re-delivers to a fresh incarnation WITHOUT any incoming request. Spurious
- * alarms are harmless by design: a pass over an all-settled lane simply deletes the slot.
+ * 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. */
 declare class DurableAlarmError extends DurableAlarmError_base {}
@@ -220,17 +219,16 @@ declare const DurableAlarmService_base: Context.ServiceClass<DurableAlarmService
    * 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), and the deferred wake is flushed when the pass completes.
+   * 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`): `scheduleNow` calls
-   * while `body` executes coalesce into one flag, flushed as an immediate re-arm after the
-   * pass — failures of the flush are logged and swallowed (hints are droppable; the pass's
-   * own re-arm policy already bounded the next delivery).
+   * 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; only the maintenance pass does this, and only when all work settled. */
+  /** 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. */
@@ -238,57 +236,60 @@ declare class DurableAlarmService extends DurableAlarmService_base {
   static readonly layer: Layer.Layer<DurableAlarmService, never, DurableObjectContext>;
 }
 declare const MaintenancePassReport_base: Schema.Class<MaintenancePassReport, Schema.Struct<{
+  /** `caught-up` is generation-only; `actionable` ran recovery and one bounded drain. */
+  readonly phase: Schema.Literals<readonly ["caught-up", "actionable"]>;
   /** Recovery decisions executed (or deferred) BEFORE any new claim in this pass. */
   readonly recovered: Schema.Int;
   /** Settlements the drain pass finalized. */
   readonly settled: Schema.Int;
   /** Submissions still nonterminal after the pass (suspended/unknown lanes stay honest). */
   readonly nonterminal: Schema.Int;
-  /** `rearmed` while nonterminal work remains, `cleared` once everything settled. */
+  /** `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. */
 declare class MaintenancePassReport extends MaintenancePassReport_base {}
+/** Fault boundaries around every maintenance-owned durable mutation. */
+type ConversationMaintenanceFailpointLocation = "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:finish:before" | "maintenance:finish:after";
+type ConversationMaintenanceFailpointHandler = (location: ConversationMaintenanceFailpointLocation) => Effect.Effect<void>;
+declare const ConversationMaintenanceFailpoint_base: Context.ServiceClass<ConversationMaintenanceFailpoint, "@effect-agent/platform-cloudflare/ConversationMaintenanceFailpoint", {
+  readonly hit: ConversationMaintenanceFailpointHandler;
+}>;
+/** Test-only fault authority; production uses the inert layer. */
+declare class ConversationMaintenanceFailpoint extends ConversationMaintenanceFailpoint_base {
+  static readonly layer: Layer.Layer<ConversationMaintenanceFailpoint, never, never>;
+}
 type MaintenancePassFailure = DurableWorkerFailure | DurableBindingFailure | DurableAlarmError;
 declare const ConversationMaintenance_base: Context.ServiceClass<ConversationMaintenance, "@effect-agent/platform-cloudflare/ConversationMaintenance", {
   /** One idempotent maintenance pass; failures propagate so workerd retries the alarm. */
   readonly pass: Effect.Effect<MaintenancePassReport, MaintenancePassFailure>;
   /**
-   * Defensive half of the alarm invariant, run by the constructor gate: if any local
-   * Submission is nonterminal and no alarm is scheduled, arm one within the scan interval.
-   * Local-only (one ledger scan + the alarm slot) — never a recovery pass, never transport.
+   * 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>;
   /**
-   * The pre-arm every mutating entry point runs BEFORE its first durable mutation: with
-   * the alarm committed first, a committed admission (or any other committed nonterminal
-   * transition) can never be observed without the alarm that will finish it.
+   * 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 preArm: Effect.Effect<void, DurableAlarmError>;
+  readonly withMutation: <A, E, R>(body: Effect.Effect<A, E, R>) => Effect.Effect<A, E | DurableAlarmError, R>;
 }>;
 /**
- * The idempotent maintenance pass and the alarm-invariant helpers (plan §1.4, D-P6-1/2).
+ * Incremental, quiescent maintenance over a durable dirty/processed generation (issue #93).
  *
- * `pass` = pre-arm → `runRecovery` → `processConversationResolved` → re-arm-or-clear:
+ * `pass` = generation snapshot/pre-arm → recovery → bounded drain → generation acknowledgement:
  *
- * 1. **Pre-arm**: the alarm is re-armed at `now + wakeScanInterval` BEFORE any work, so an
- *    eviction (or thrown failure → workerd alarm retry) at any point of the pass leaves a
- *    committed alarm and the fresh incarnation converges without an incoming request.
- * 2. **Reconcile before new work** (exit gate): every pass classifies and repairs every
- *    nonterminal Submission before the drain claims anything; the pure classifier and the
- *    repair executors are idempotent, so at-least-once alarm delivery re-runs them safely.
- * 3. **Drain**: one bounded `processConversationResolved` pass over this Object's lane — the
- *    D-P6-1 shape; no infinite `runResolvedWorker` loop ever pins the Object.
- * 4. **Re-arm policy**: nonterminal work re-arms at `now + min(backoff-with-jitter,
- *    wakeScanInterval)` — the scan interval bounds every wait (lease expiry of a dead
- *    incarnation included, since claims retry each pass) and the backoff (reset on progress,
- *    grown otherwise) keeps stuck lanes from busy-spinning; all settled clears the slot.
- *
- * Every step is a durability-protocol step that already tolerates re-execution, which is
- * what makes double-fired alarms harmless (the alarm.test.ts gate).
+ * 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 still strictly precedes a new claim, and one bounded drain advances the lane.
+ * 3. The final transaction acknowledges only the generation observed at pass start. A racing
+ *    mutation therefore remains `dirty > processed` and retains its atomically-established alarm.
+ * 4. Stable external waits acknowledge and clear. Autonomous retry, indeterminate, and lease
+ *    recovery states leave their generation dirty and retain bounded backoff rearming.
  */
 declare class ConversationMaintenance extends ConversationMaintenance_base {
-  static readonly layer: Layer.Layer<ConversationMaintenance, never, DurableAgentRuntime | AgentBindingResolver | SubmissionLedger | DurableAlarmService | CloudflareDurableRuntimeConfig | ConversationObjectIdentity>;
+  static readonly layer: Layer.Layer<ConversationMaintenance, never, DurableAgentRuntime | AgentBindingResolver | SubmissionLedger | DurableAlarmService | ConversationMaintenanceFailpoint | CloudflareDurableRuntimeConfig | ConversationObjectIdentity | DurableObjectContext>;
 }
 //#endregion
 //#region src/wake-scheduler.d.ts
@@ -367,6 +368,8 @@ interface CloudflareDurableRuntimeOptions {
   readonly storageFailpoint?: ((ctx: DurableObjectState) => DoStorageFailpointHandler) | undefined;
   /** Coordinator fault injection (`submit:*` / `terminalize:*` locations); default none. */
   readonly runtimeFailpoint?: ((ctx: DurableObjectState) => DurableRuntimeFailpointHandler) | undefined;
+  /** Conversation-maintenance generation/alarm fault injection; default none. */
+  readonly maintenanceFailpoint?: ((ctx: DurableObjectState) => ConversationMaintenanceFailpointHandler) | undefined;
   /**
    * Reconciliation policy consulted for open ordinary Tool Calls before an Unknown Outcome
    * is recorded (durability §10, DUR-009). Defaults to the fail-closed
@@ -821,18 +824,44 @@ declare const encodeHostResponse: (input: AbortRecorded | ApprovalRecorded | Hos
 } | {
   readonly _tag: "HostFailed";
   readonly failure: {
-    readonly _tag: "LedgerError";
-    readonly operation: string;
+    readonly _tag: "HostProtocolError";
+    readonly message: string;
+  } | {
+    readonly _tag: "AgentInputError";
     readonly message: string;
-    readonly cause?: Schema.Json | undefined;
   } | {
     readonly _tag: "DigestError";
     readonly message: string;
     readonly cause?: Schema.Json | undefined;
+  } | {
+    readonly _tag: "AdmissionConflict";
+    readonly conversationId: string;
+    readonly principal: string;
+    readonly idempotencyKey: string;
+    readonly existingInputDigest: string;
+    readonly attemptedInputDigest: string;
   } | {
     readonly _tag: "SettlementConflict";
     readonly submissionId: string;
     readonly existingOutcome: "aborted" | "completed" | "failed";
+  } | {
+    readonly _tag: "ApprovalConflict";
+    readonly submissionId: string;
+    readonly toolCallId: string;
+    readonly existingDecision: "approved" | "denied";
+  } | {
+    readonly _tag: "UnknownResolutionConflict";
+    readonly submissionId: string;
+    readonly toolCallId: string;
+  } | {
+    readonly _tag: "JoinedToHost";
+    readonly submissionId: string;
+    readonly hostSubmissionId: string;
+  } | {
+    readonly _tag: "LedgerError";
+    readonly operation: string;
+    readonly message: string;
+    readonly cause?: Schema.Json | undefined;
   } | {
     readonly _tag: "ConversationStoreError";
     readonly operation: string;
@@ -856,42 +885,16 @@ declare const encodeHostResponse: (input: AbortRecorded | ApprovalRecorded | Hos
   } | {
     readonly _tag: "DurableRuntimeFailpointError";
     readonly location: "abort:after-intent" | "approval:after-request-append" | "approval:after-suspend" | "claim:after-claim" | "compaction:after-canonical-append" | "input:after-canonical-append" | "join:after-canonical-append" | "join:after-claim" | "resolve:after-intent" | "step:after-step-append" | "subagent:after-admit" | "subagent:after-child-abort-intent" | "subagent:after-child-ready" | "subagent:after-join-append" | "subagent:after-release" | "subagent:after-release-pending" | "subagent:after-request-append" | "subagent:after-reserve" | "subagent:after-sibling-settle" | "subagent:after-start-append" | "subagent:after-suspend" | "submit:after-admit" | "submit:after-materialize" | "terminalize:after-canonical-append" | "terminalize:after-reserve" | "tools:after-prepared-append" | "turn:after-canonical-append" | "turn:after-response-append" | "turn:after-results-append";
-  } | {
-    readonly _tag: "DurableAlarmError";
-    readonly operation: string;
-    readonly message: string;
-    readonly cause?: Schema.Json | undefined;
-  } | {
-    readonly _tag: "HostProtocolError";
-    readonly message: string;
-  } | {
-    readonly _tag: "AgentInputError";
-    readonly message: string;
-  } | {
-    readonly _tag: "AdmissionConflict";
-    readonly conversationId: string;
-    readonly principal: string;
-    readonly idempotencyKey: string;
-    readonly existingInputDigest: string;
-    readonly attemptedInputDigest: string;
-  } | {
-    readonly _tag: "ApprovalConflict";
-    readonly submissionId: string;
-    readonly toolCallId: string;
-    readonly existingDecision: "approved" | "denied";
-  } | {
-    readonly _tag: "UnknownResolutionConflict";
-    readonly submissionId: string;
-    readonly toolCallId: string;
-  } | {
-    readonly _tag: "JoinedToHost";
-    readonly submissionId: string;
-    readonly hostSubmissionId: string;
   } | {
     readonly _tag: "AdmissionLimitExceeded";
     readonly limit: "database-bytes" | "input-bytes" | "queue-depth";
     readonly actual: number;
     readonly maximum: number;
+  } | {
+    readonly _tag: "DurableAlarmError";
+    readonly operation: string;
+    readonly message: string;
+    readonly cause?: Schema.Json | undefined;
   };
 }, Schema.SchemaError, never>;
 declare const decodeHostResponse: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Effect.Effect<AbortRecorded | ApprovalRecorded | HostFailed | ObservedPage | SettlementReached | SubmitSucceeded | UnknownResolutionRecorded, Schema.SchemaError, never>;
@@ -1408,38 +1411,21 @@ declare const encodeAdminResponse: (input: AdminFailed | ExplainedRecovery | Obl
 } | {
   readonly _tag: "AdminFailed";
   readonly failure: {
-    readonly _tag: "OperationDenied";
-    readonly operation: "explain" | "observe" | "resolveApproval" | "resolveUnknown" | "retry" | "scanObligations" | "verify" | "wake";
-    readonly reason: string;
-    readonly conversationId?: string | undefined;
-    readonly submissionId?: string | undefined;
-  } | {
-    readonly _tag: "RetryRefused";
-    readonly submissionId: string;
-    readonly refusal: "await-approval-decision" | "await-unknown-resolution" | "settled";
-    readonly decisionTag: string;
-    readonly message: string;
-  } | {
-    readonly _tag: "LedgerError";
-    readonly operation: string;
+    readonly _tag: "HostProtocolError";
     readonly message: string;
-    readonly cause?: Schema.Json | undefined;
-  } | {
-    readonly _tag: "RunJournalError";
-    readonly message: string;
-    readonly cause?: Schema.Json | undefined;
   } | {
     readonly _tag: "DigestError";
     readonly message: string;
     readonly cause?: Schema.Json | undefined;
-  } | {
-    readonly _tag: "OwnershipLost";
-    readonly submissionId: string;
-    readonly actualEpoch: number;
   } | {
     readonly _tag: "SettlementConflict";
     readonly submissionId: string;
     readonly existingOutcome: "aborted" | "completed" | "failed";
+  } | {
+    readonly _tag: "LedgerError";
+    readonly operation: string;
+    readonly message: string;
+    readonly cause?: Schema.Json | undefined;
   } | {
     readonly _tag: "ConversationStoreError";
     readonly operation: string;
@@ -1469,8 +1455,25 @@ declare const encodeAdminResponse: (input: AdminFailed | ExplainedRecovery | Obl
     readonly message: string;
     readonly cause?: Schema.Json | undefined;
   } | {
-    readonly _tag: "HostProtocolError";
+    readonly _tag: "OperationDenied";
+    readonly operation: "explain" | "observe" | "resolveApproval" | "resolveUnknown" | "retry" | "scanObligations" | "verify" | "wake";
+    readonly reason: string;
+    readonly conversationId?: string | undefined;
+    readonly submissionId?: string | undefined;
+  } | {
+    readonly _tag: "RetryRefused";
+    readonly submissionId: string;
+    readonly refusal: "await-approval-decision" | "await-unknown-resolution" | "settled";
+    readonly decisionTag: string;
+    readonly message: string;
+  } | {
+    readonly _tag: "RunJournalError";
     readonly message: string;
+    readonly cause?: Schema.Json | undefined;
+  } | {
+    readonly _tag: "OwnershipLost";
+    readonly submissionId: string;
+    readonly actualEpoch: number;
   };
 }, Schema.SchemaError, never>;
 declare const decodeAdminResponse: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Effect.Effect<AdminFailed | ExplainedRecovery | ObligationsScanned | RetryExecuted | VerifiedIntegrity, Schema.SchemaError, never>;
@@ -1546,5 +1549,5 @@ interface DynamicWorkerCodeExecutorOptions {
 /** Layer building the Dynamic Worker `CodeExecutor` from resolved bindings. */
 declare const dynamicWorkerCodeExecutorLayer: (options: DynamicWorkerCodeExecutorOptions) => Layer.Layer<CodeExecutor>;
 //#endregion
-export { AbortRecorded, AdminExplainRequest, AdminFailed, AdminFailure, AdminResponse, AdminVerifyRequest, AdmissionLimitExceeded, ApprovalRecorded, CLOUDFLARE_DATABASE_CAP_BYTES, CLOUDFLARE_RUNTIME_DEFAULTS, ClientAbortFailure, ClientApprovalFailure, ClientAwaitFailure, ClientObserveFailure, ClientSubmitFailure, ClientUnknownFailure, CloudflareAdmissionLimitsValue, CloudflareBindingError, CloudflareBindingSource, CloudflareBindingSourceContext, CloudflareConversationClient, CloudflareDurableRuntime, CloudflareDurableRuntimeConfig, CloudflareDurableRuntimeConfigValue, CloudflareDurableRuntimeInitializationError, CloudflareDurableRuntimeOptions, CloudflareDurableRuntimeServices, CloudflarePlatformConfigError, CodeModeHostEntrypoint, CodeModeHostStub, ConversationClientError, ConversationMaintenance, ConversationObjectClass, ConversationObjectIdentity, ConversationObjectInstance, ConversationObjectNamespace, ConversationObjectOptions, ConversationObjectPorts, ConversationObjectRpc, DEFAULT_MAX_DATABASE_BYTES, DurableAlarmError, DurableAlarmService, DurableObjectContext, DynamicWorkerCodeExecutorOptions, ExplainedRecovery, HostFailed, HostFailure, HostProtocolError, HostResponse, MaintenancePassFailure, MaintenancePassReport, ObligationsScanned, ObservePageRequest, ObservedPage, RetryExecuted, SettlementReached, SubmitRequest, SubmitSucceeded, UnknownResolutionRecorded, VerifiedIntegrity, boundHostDiagnostic, cloudflareWakeSchedulerLayer, conversationNamespaceFromEnv, conversationNamespaceLayer, conversationPortTransportLayer, decodeAbortCommand, decodeAdminExplainRequest, decodeAdminResponse, decodeAdminVerifyRequest, decodeApprovalDecisionCommand, decodeHostResponse, decodeObligationThresholds, decodeObservePageRequest, decodeReceipt, decodeRetryCommand, decodeSubmitRequest, decodeUnknownResolutionCommand, dynamicWorkerCodeExecutorLayer, dynamicWorkerImplementation, encodeAbortCommand, encodeAdminResponse, encodeApprovalDecisionCommand, encodeHostResponse, encodeObservePageRequest, encodeReceipt, encodeSubmitRequest, encodeUnknownResolutionCommand, makeConversationObjectClass };
+export { AbortRecorded, AdminExplainRequest, AdminFailed, AdminFailure, AdminResponse, AdminVerifyRequest, AdmissionLimitExceeded, ApprovalRecorded, CLOUDFLARE_DATABASE_CAP_BYTES, CLOUDFLARE_RUNTIME_DEFAULTS, ClientAbortFailure, ClientApprovalFailure, ClientAwaitFailure, ClientObserveFailure, ClientSubmitFailure, ClientUnknownFailure, CloudflareAdmissionLimitsValue, CloudflareBindingError, CloudflareBindingSource, CloudflareBindingSourceContext, CloudflareConversationClient, CloudflareDurableRuntime, CloudflareDurableRuntimeConfig, CloudflareDurableRuntimeConfigValue, CloudflareDurableRuntimeInitializationError, CloudflareDurableRuntimeOptions, CloudflareDurableRuntimeServices, CloudflarePlatformConfigError, CodeModeHostEntrypoint, CodeModeHostStub, ConversationClientError, ConversationMaintenance, ConversationMaintenanceFailpoint, ConversationMaintenanceFailpointHandler, ConversationMaintenanceFailpointLocation, ConversationObjectClass, ConversationObjectIdentity, ConversationObjectInstance, ConversationObjectNamespace, ConversationObjectOptions, ConversationObjectPorts, ConversationObjectRpc, DEFAULT_MAX_DATABASE_BYTES, DurableAlarmError, DurableAlarmService, DurableObjectContext, DynamicWorkerCodeExecutorOptions, ExplainedRecovery, HostFailed, HostFailure, HostProtocolError, HostResponse, MaintenancePassFailure, MaintenancePassReport, ObligationsScanned, ObservePageRequest, ObservedPage, RetryExecuted, SettlementReached, SubmitRequest, SubmitSucceeded, UnknownResolutionRecorded, VerifiedIntegrity, boundHostDiagnostic, cloudflareWakeSchedulerLayer, conversationNamespaceFromEnv, conversationNamespaceLayer, conversationPortTransportLayer, decodeAbortCommand, decodeAdminExplainRequest, decodeAdminResponse, decodeAdminVerifyRequest, decodeApprovalDecisionCommand, decodeHostResponse, decodeObligationThresholds, decodeObservePageRequest, decodeReceipt, decodeRetryCommand, decodeSubmitRequest, decodeUnknownResolutionCommand, dynamicWorkerCodeExecutorLayer, dynamicWorkerImplementation, encodeAbortCommand, encodeAdminResponse, encodeApprovalDecisionCommand, encodeHostResponse, encodeObservePageRequest, encodeReceipt, encodeSubmitRequest, encodeUnknownResolutionCommand, makeConversationObjectClass };
 //# sourceMappingURL=index.d.mts.map