@effect-agent/platform-cloudflare 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/Alarm.d.mts

@@ -0,0 +1,188 @@
+import { DurableObjectContext } from "./CloudflareBindings.mjs";
+import { o as CloudflareDurableRuntimeConfig } from "./CloudflareConfig-f3CqTel1.mjs";
+import { Cause, Context, Deferred, Effect, Layer, Option, Schema } 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. */
+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. */
+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. */
+declare class MaintenancePassReport extends MaintenancePassReport_base {}
+/** Fault boundaries around every maintenance-owned durable mutation. */
+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:finish:before" | "maintenance:finish:after";
+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. */
+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.
+ * `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.
+ */
+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)(...) })`. */
+declare class ThreadPublication extends ThreadPublication_base {
+  static readonly layer: Layer.Layer<ThreadPublication, never, never>;
+}
+/**
+ * Host-assembled message recovery, supplied by ThreadObject.layer even when the application
+ * rebuilds ThreadMaintenance. These obligations outlive source Runs and never defer a ready
+ * source Attempt while a destination is processing an accepted message.
+ */
+declare const ThreadMessageDelivery: Context.Reference<{
+  readonly drain: Effect.Effect<void, DurableAlarmError>;
+  /** Drain inserts and due retries during source work, finishing the bounded wave on completion. */
+  readonly drainUntil?: (finished: Deferred.Deferred<void>) => Effect.Effect<void, DurableAlarmError>;
+  readonly pendingDeadline: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+}>;
+/**
+ * Application obligations sharing this Object's alarm. The deadline read is local and
+ * read-only. Drain beside the native Attempt and always finish one initial bounded wave,
+ * even when `finished` was already signalled. Then stop starting new waves on that signal
+ * and finish the bounded current wave before returning. Native maintenance joins that work
+ * before acknowledging a generation. Mutations use the same ThreadMutationGate; hooks never
+ * write the raw alarm slot. Pending host work does not defer a ready model Attempt.
+ */
+declare const ThreadHostMaintenance: Context.Reference<{
+  readonly pendingDeadline: Effect.Effect<Option.Option<number>, DurableAlarmError>;
+  readonly drainUntil: (finished: Deferred.Deferred<void>) => Effect.Effect<void, DurableAlarmError>;
+}>;
+/** @internal A committed source operation must not become a failed operation because delivery failed. */
+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>,
+  /** Indexed host work has its own durable deadline and does not invalidate ledger recovery. */
+  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.
+ */
+declare class ThreadMutationGate extends ThreadMutationGate_base {
+  static readonly layer: Layer.Layer<ThreadMutationGate, never, CloudflareDurableRuntimeConfig | DurableObjectContext | SqlClient | ThreadMaintenanceFailpoint>;
+}
+type MaintenancePassFailure = DurableWorkerFailure | DurableBindingFailure | DurableAlarmError | ThreadProjectionError;
+declare const ThreadMaintenance_base: Context.ServiceClass<ThreadMaintenance, "@effect-agent/platform-cloudflare/ThreadMaintenance", {
+  /** One idempotent maintenance pass; failures propagate so workerd retries the alarm. */
+  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. 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 ThreadMaintenance extends ThreadMaintenance_base {
+  static readonly layer: Layer.Layer<ThreadMaintenance, never, ThreadMutationGate | ThreadPublication | ThreadProjectionMaintenance | DurableAgentRuntime | SubmissionLedger | DurableAlarmService | ThreadMaintenanceFailpoint | CloudflareDurableRuntimeConfig | DurableObjectContext | SqlClient>;
+}
+//#endregion
+export { DurableAlarmError, DurableAlarmService, MaintenancePassFailure, MaintenancePassReport, ThreadHostMaintenance, ThreadMaintenance, ThreadMaintenanceFailpoint, ThreadMaintenanceFailpointHandler, ThreadMaintenanceFailpointLocation, ThreadMessageDelivery, ThreadMutationGate, ThreadPublication, ThreadPublicationService, publishCommitted, Alarm_d_exports as t };
+//# sourceMappingURL=Alarm.d.mts.map

package/dist/Alarm.mjs

@@ -0,0 +1,451 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { DurableObjectContext } from "./CloudflareBindings.mjs";
+import { CloudflareDurableRuntimeConfig } from "./CloudflareConfig.mjs";
+import { r as safeCauseMessage } from "./boundary-BguazVkh.mjs";
+import { Cause, Clock, Context, DateTime, Deferred, Effect, Exit, Fiber, Layer, Option, Random, Ref, Schema, Semaphore, Stream } from "effect";
+import "effect-agent/agent-registration";
+import { DurableAgentRuntime } from "effect-agent/durable-agent-runtime";
+import { ThreadId } from "effect-agent/identifiers";
+import { SubmissionLedger } from "effect-agent/submission-ledger";
+import { ThreadProjectionMaintenance, drainDue } from "effect-agent/thread-projection-maintenance";
+import { SqlClient } from "effect/unstable/sql/SqlClient";
+//#region src/Alarm.ts
+var Alarm_exports = /* @__PURE__ */ __exportAll({
+	DurableAlarmError: () => DurableAlarmError,
+	DurableAlarmService: () => DurableAlarmService,
+	MaintenancePassReport: () => MaintenancePassReport,
+	ThreadHostMaintenance: () => ThreadHostMaintenance,
+	ThreadMaintenance: () => ThreadMaintenance,
+	ThreadMaintenanceFailpoint: () => ThreadMaintenanceFailpoint,
+	ThreadMessageDelivery: () => ThreadMessageDelivery,
+	ThreadMutationGate: () => ThreadMutationGate,
+	ThreadPublication: () => ThreadPublication,
+	publishCommitted: () => publishCommitted
+});
+/**
+* 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. */
+var DurableAlarmError = class extends Schema.TaggedError()("DurableAlarmError", {
+	operation: Schema.String,
+	message: Schema.String,
+	cause: Schema.optionalKey(Schema.Defect())
+}) {};
+const alarmFailure = (operation) => (cause) => DurableAlarmError.make({
+	operation,
+	message: safeCauseMessage(cause, "The Cloudflare alarm API failed without a diagnostic"),
+	cause
+});
+const makeStorageOperation = Effect.map(SqlClient, (sql) => (operation, execute) => Effect.flatMap(Effect.serviceOption(sql.transactionService), (current) => {
+	const body = Effect.uninterruptible(Effect.tryPromise({
+		try: execute,
+		catch: alarmFailure(operation)
+	}));
+	return current._tag === "Some" ? body : Effect.scoped(Effect.andThen(sql.reserve.pipe(Effect.mapError(alarmFailure(operation))), body));
+}));
+/** `ctx.storage` alarm slot as an Effect service; storage is truth, never a memory field. */
+var DurableAlarmService = class DurableAlarmService extends Context.Service()("@effect-agent/platform-cloudflare/DurableAlarmService") {
+	static layer = Layer.effect(DurableAlarmService)(Effect.gen(function* () {
+		const { ctx } = yield* DurableObjectContext;
+		/**
+		* In-memory pass bookkeeping — a pure CACHE, never state: a fresh incarnation has no
+		* running pass, and a deferred wake lost to eviction was only ever a promptness hint
+		* on top of the already-committed pre-armed alarm.
+		*/
+		const runningPasses = yield* Ref.make(0);
+		const storageOperation = yield* makeStorageOperation;
+		const scheduled = storageOperation("get alarm", () => ctx.storage.getAlarm()).pipe(Effect.map((deadline) => deadline === null ? Option.none() : Option.some(deadline)));
+		const scheduleAt = (epochMillis) => storageOperation("set alarm", () => ctx.storage.setAlarm(epochMillis));
+		const ensureScheduledBy = (epochMillis) => storageOperation("ensure alarm", () => ctx.storage.transaction(async (transaction) => {
+			const existing = await transaction.getAlarm();
+			if (existing === null || existing > epochMillis) await transaction.setAlarm(epochMillis);
+		}));
+		const armNow = Clock.currentTimeMillis.pipe(Effect.flatMap((now) => ensureScheduledBy(now)));
+		const scheduleNow = Ref.get(runningPasses).pipe(Effect.flatMap((passes) => passes > 0 ? Effect.void : armNow));
+		const withWakesDeferred = (body) => Ref.update(runningPasses, (passes) => passes + 1).pipe(Effect.andThen(body), Effect.ensuring(Ref.update(runningPasses, (passes) => passes - 1)));
+		const cancel = storageOperation("delete alarm", () => ctx.storage.deleteAlarm());
+		return DurableAlarmService.of({
+			scheduled,
+			scheduleAt,
+			ensureScheduledBy,
+			scheduleNow,
+			withWakesDeferred,
+			cancel
+		});
+	}));
+};
+/** What one maintenance pass did — auditable evidence mirroring `NodeDurableHost`'s report. */
+var MaintenancePassReport = class extends Schema.Class("@effect-agent/platform-cloudflare/MaintenancePassReport")({
+	/** `caught-up` ran no runtime work (publication may be pending); `actionable` ran recovery. */
+	phase: Schema.Literals(["caught-up", "actionable"]),
+	/** Recovery decisions executed (or deferred) BEFORE any new claim in this pass. */
+	recovered: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+	/** Whether the head Attempt settled. Joined input may settle with that head. */
+	settled: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+	/** Submissions still nonterminal after the pass (suspended/unknown lanes stay honest). */
+	nonterminal: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+	/** `rearmed` for dirty/autonomous work, `cleared` for stable waits or settlement. */
+	alarm: Schema.Literals(["rearmed", "cleared"])
+}) {};
+/** Test-only fault authority; production uses the inert layer. */
+var ThreadMaintenanceFailpoint = class extends Context.Service()("@effect-agent/platform-cloudflare/ThreadMaintenanceFailpoint") {
+	static layer = Layer.succeed(this)({ hit: () => Effect.void });
+};
+/** Opt in with `ThreadObject.layer(registrations, { publication: Layer.effect(ThreadPublication)(...) })`. */
+var ThreadPublication = class extends Context.Service()("@effect-agent/platform-cloudflare/ThreadPublication") {
+	static layer = Layer.succeed(this)({
+		invalidate: Effect.void,
+		prepareGeneration: () => Effect.void,
+		drain: Effect.void,
+		pendingDeadline: Effect.succeed(Option.none())
+	});
+};
+/**
+* Host-assembled message recovery, supplied by ThreadObject.layer even when the application
+* rebuilds ThreadMaintenance. These obligations outlive source Runs and never defer a ready
+* source Attempt while a destination is processing an accepted message.
+*/
+const ThreadMessageDelivery = Context.Reference("@effect-agent/platform-cloudflare/ThreadMessageDelivery", { defaultValue: () => ({
+	drain: Effect.void,
+	pendingDeadline: Effect.succeed(Option.none())
+}) });
+/**
+* Application obligations sharing this Object's alarm. The deadline read is local and
+* read-only. Drain beside the native Attempt and always finish one initial bounded wave,
+* even when `finished` was already signalled. Then stop starting new waves on that signal
+* and finish the bounded current wave before returning. Native maintenance joins that work
+* before acknowledging a generation. Mutations use the same ThreadMutationGate; hooks never
+* write the raw alarm slot. Pending host work does not defer a ready model Attempt.
+*/
+const ThreadHostMaintenance = Context.Reference("@effect-agent/platform-cloudflare/ThreadHostMaintenance", { defaultValue: () => ({
+	pendingDeadline: Effect.succeed(Option.none()),
+	drainUntil: () => Effect.void
+}) });
+const earliestDeadline = (left, right) => Option.isSome(left) ? Option.isSome(right) ? Option.some(Math.min(left.value, right.value)) : left : right;
+/** @internal A committed source operation must not become a failed operation because delivery failed. */
+const publishCommitted = Effect.gen(function* () {
+	const publication = yield* ThreadPublication;
+	yield* publication.invalidate.pipe(Effect.andThen(publication.drain));
+}).pipe(Effect.catchCause((cause) => Cause.hasInterrupts(cause) ? Effect.interrupt : Effect.logError("Thread publication deferred after source commit", cause)));
+const MaintenanceGeneration = Schema.BigIntFromString.check(Schema.isGreaterThanOrEqualToBigInt(0n));
+/** Versioned, platform-private maintenance state stored through Durable Object KV. */
+var ThreadMaintenanceState = class extends Schema.Class("@effect-agent/platform-cloudflare/ThreadMaintenanceState")({
+	schemaVersion: Schema.Literal(1),
+	dirty: MaintenanceGeneration,
+	processed: MaintenanceGeneration,
+	nonterminal: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+	/** One physical-owner cursor; old single-lane records need no conversion. */
+	lastServedThreadId: Schema.optionalKey(ThreadId)
+}) {};
+const MAINTENANCE_STATE_KEY = "effect-agent:thread-maintenance:v1";
+const decodeMaintenanceState = Schema.decodeUnknownSync(ThreadMaintenanceState);
+const encodeMaintenanceState = Schema.encodeSync(ThreadMaintenanceState);
+const initialMaintenanceState = () => ThreadMaintenanceState.make({
+	schemaVersion: 1,
+	dirty: 1n,
+	processed: 0n,
+	nonterminal: 0
+});
+const readMaintenanceState = async (transaction) => {
+	const encoded = await transaction.get(MAINTENANCE_STATE_KEY);
+	return encoded === void 0 ? {
+		state: initialMaintenanceState(),
+		initialized: false
+	} : {
+		state: decodeMaintenanceState(encoded),
+		initialized: true
+	};
+};
+const ensureTransactionAlarmBy = async (transaction, deadline) => {
+	const scheduled = await transaction.getAlarm();
+	if (scheduled === null || scheduled > deadline) await transaction.setAlarm(deadline);
+};
+const stableExternalWait = (snapshot, reports) => {
+	const decision = reports.get(snapshot.submissionId)?.decision._tag;
+	if (decision === "SettleAborted") return false;
+	switch (snapshot.state) {
+		case "suspended":
+		case "joined": return true;
+		case "unknown": return decision === "AwaitUnknownResolution" || decision === "MarkUnknown";
+		case "admitted": return reports.get(snapshot.submissionId)?.decision._tag === "AwaitParentEstablishment";
+		case "input-applied":
+		case "joining":
+		case "ready":
+		case "running":
+		case "settled":
+		case "terminalizing": return false;
+	}
+};
+/**
+* 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.
+*/
+var ThreadMutationGate = class ThreadMutationGate extends Context.Service()("@effect-agent/platform-cloudflare/internal/ThreadMutationGate") {
+	static layer = Layer.effect(this)(Effect.gen(function* () {
+		const { ctx } = yield* DurableObjectContext;
+		const config = yield* CloudflareDurableRuntimeConfig;
+		const failpoint = yield* ThreadMaintenanceFailpoint;
+		const activeMutations = yield* Ref.make(0);
+		const generationGate = yield* Semaphore.make(1);
+		const minimumAlarmDelay = Math.max(1, Math.ceil(config.alarmBackoffBase / 2));
+		const runTransaction = yield* makeStorageOperation;
+		const beginMutation = Effect.fn("ThreadMaintenance.beginMutation")(function* (invalidatesRecovery) {
+			yield* failpoint.hit("maintenance:dirty:before");
+			const now = yield* Clock.currentTimeMillis;
+			yield* runTransaction("advance maintenance generation", () => ctx.storage.transaction(async (transaction) => {
+				const { state, initialized } = await readMaintenanceState(transaction);
+				const next = ThreadMaintenanceState.make({
+					...state,
+					dirty: state.dirty + (invalidatesRecovery ? 1n : 0n)
+				});
+				if (invalidatesRecovery || !initialized) await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
+				await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
+			}));
+			yield* failpoint.hit("maintenance:dirty:after");
+			yield* Ref.update(activeMutations, (active) => active + 1);
+		});
+		const endMutation = generationGate.withPermit(Ref.update(activeMutations, (active) => Math.max(0, active - 1)));
+		const withMutation = (body, options) => Effect.acquireUseRelease(generationGate.withPermit(beginMutation(options?.invalidatesRecovery ?? true)), () => failpoint.hit("maintenance:mutation:armed").pipe(Effect.andThen(body), Effect.tap(() => failpoint.hit("maintenance:mutation:finished"))), () => endMutation);
+		return ThreadMutationGate.of({
+			withMutation,
+			withSnapshot: (body) => generationGate.withPermit(Effect.flatMap(Ref.get(activeMutations), body))
+		});
+	}));
+};
+/**
+* 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. 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.
+*/
+var ThreadMaintenance = class ThreadMaintenance extends Context.Service()("@effect-agent/platform-cloudflare/ThreadMaintenance") {
+	static layer = Layer.effect(ThreadMaintenance)(Effect.gen(function* () {
+		const runtime = yield* DurableAgentRuntime;
+		const ledger = yield* SubmissionLedger;
+		const alarm = yield* DurableAlarmService;
+		const config = yield* CloudflareDurableRuntimeConfig;
+		const { ctx } = yield* DurableObjectContext;
+		const failpoint = yield* ThreadMaintenanceFailpoint;
+		/**
+		* Consecutive no-progress passes — an in-memory CACHE, not state: a fresh incarnation
+		* restarts at zero and merely re-arms sooner than a long-lived one would have.
+		*/
+		const stalls = yield* Ref.make(0);
+		const mutations = yield* ThreadMutationGate;
+		const publication = yield* ThreadPublication;
+		const projection = yield* ThreadProjectionMaintenance;
+		const messages = yield* ThreadMessageDelivery;
+		const host = yield* ThreadHostMaintenance;
+		const projectionDeadline = projection.pendingDeadline.pipe(Effect.catchCauseIf((cause) => !Cause.hasInterrupts(cause), (cause) => Effect.logError("Thread projection deadline unavailable", cause).pipe(Effect.as(Option.some(0)))));
+		const pendingDeadline = Effect.gen(function* () {
+			return earliestDeadline(earliestDeadline(yield* publication.pendingDeadline, yield* messages.pendingDeadline), earliestDeadline(yield* projectionDeadline, yield* host.pendingDeadline));
+		});
+		const maintenancePassGate = yield* Semaphore.make(1);
+		const minimumAlarmDelay = Math.max(1, Math.ceil(config.alarmBackoffBase / 2));
+		const runTransaction = yield* makeStorageOperation;
+		const ensureAlarm = Effect.fn("ThreadMaintenance.ensureAlarm")(function* () {
+			yield* failpoint.hit("maintenance:ensure:before");
+			const now = yield* Clock.currentTimeMillis;
+			yield* runTransaction("ensure maintenance alarm", () => ctx.storage.transaction(async (transaction) => {
+				const { state, initialized } = await readMaintenanceState(transaction);
+				if (!initialized) await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(state));
+				if (state.dirty > state.processed) await ensureTransactionAlarmBy(transaction, now + config.wakeScanInterval);
+			}));
+			const deadline = yield* pendingDeadline;
+			if (Option.isSome(deadline)) yield* runTransaction("ensure publication alarm", () => ctx.storage.transaction((transaction) => ensureTransactionAlarmBy(transaction, Math.max(now + minimumAlarmDelay, deadline.value))));
+			yield* failpoint.hit("maintenance:ensure:after");
+		});
+		const beginPass = Effect.fn("ThreadMaintenance.beginPass")(function* () {
+			yield* failpoint.hit("maintenance:begin:before");
+			const now = yield* Clock.currentTimeMillis;
+			const result = yield* runTransaction("begin maintenance pass", () => ctx.storage.transaction(async (transaction) => {
+				const { state, initialized } = await readMaintenanceState(transaction);
+				if (!initialized) await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(state));
+				if (state.processed >= state.dirty) {
+					await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
+					return {
+						_tag: "CaughtUp",
+						nonterminal: state.nonterminal
+					};
+				}
+				await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
+				return {
+					_tag: "Actionable",
+					generation: state.dirty,
+					nonterminal: state.nonterminal
+				};
+			}));
+			yield* failpoint.hit("maintenance:begin:after");
+			return result;
+		});
+		const rearmDelay = Effect.fn("ThreadMaintenance.rearmDelay")(function* (progressed) {
+			const priorStalls = yield* Ref.getAndUpdate(stalls, (count) => progressed ? 0 : count + 1);
+			if (progressed) return config.alarmBackoffBase;
+			const exponent = Math.min(priorStalls, 30);
+			const backoff = Math.min(config.alarmBackoffCap, config.alarmBackoffBase * 2 ** exponent);
+			const jitter = yield* Random.next;
+			const jittered = Math.ceil(backoff / 2 + backoff / 2 * jitter);
+			return Math.min(jittered, config.wakeScanInterval);
+		});
+		const pass = Effect.fn("ThreadMaintenance.pass")(function* (yieldAfter) {
+			const annotate = (report) => Effect.annotateCurrentSpan({
+				phase: report.phase,
+				recovered: report.recovered,
+				settled: report.settled,
+				nonterminal: report.nonterminal,
+				alarm: report.alarm
+			}).pipe(Effect.as(report));
+			const started = yield* mutations.withSnapshot((activeAtStart) => Effect.gen(function* () {
+				const generation = yield* beginPass();
+				if (generation._tag === "Actionable" && activeAtStart === 0) yield* publication.prepareGeneration(generation.generation);
+				return {
+					...generation,
+					activeAtStart
+				};
+			}));
+			const deliveryFinished = yield* Deferred.make();
+			const delivery = yield* Effect.forkChild(messages.drainUntil?.(deliveryFinished) ?? messages.drain);
+			const hostWork = yield* Effect.forkChild(host.drainUntil(deliveryFinished));
+			const finishDelivery = Deferred.succeed(deliveryFinished, void 0).pipe(Effect.andThen(Fiber.awaitAll([delivery, hostWork])), Effect.flatMap((outcomes) => Effect.forEach(outcomes, (outcome) => outcome, { discard: true })));
+			const projected = yield* Effect.exit(drainDue.pipe(Effect.provideService(ThreadProjectionMaintenance, projection)));
+			if (Exit.isFailure(projected) && Cause.hasInterrupts(projected.cause)) return yield* Effect.failCause(projected.cause);
+			const deadline = yield* publication.pendingDeadline;
+			if (started._tag === "Actionable" || Option.isSome(deadline) && deadline.value <= (yield* Clock.currentTimeMillis)) yield* publication.drain;
+			const pending = yield* publication.pendingDeadline;
+			if (started._tag === "CaughtUp" || Option.isSome(pending)) {
+				yield* finishDelivery;
+				if (Exit.isFailure(projected)) return yield* Effect.failCause(projected.cause);
+				yield* failpoint.hit("maintenance:finish:before");
+				const disposition = yield* mutations.withSnapshot((active) => Effect.gen(function* () {
+					const latest = yield* pendingDeadline;
+					const now = yield* Clock.currentTimeMillis;
+					return yield* runTransaction("finish publication pass", () => ctx.storage.transaction(async (transaction) => {
+						const { state } = await readMaintenanceState(transaction);
+						const nativeDeadline = active > 0 || state.dirty > state.processed ? now + config.wakeScanInterval : Infinity;
+						const next = Option.isSome(latest) ? Math.min(nativeDeadline, latest.value) : nativeDeadline;
+						if (Number.isFinite(next)) {
+							await transaction.setAlarm(Math.max(now + minimumAlarmDelay, next));
+							return "rearmed";
+						}
+						await transaction.deleteAlarm();
+						return "cleared";
+					}));
+				}));
+				yield* failpoint.hit("maintenance:finish:after");
+				return yield* annotate(MaintenancePassReport.make({
+					phase: "caught-up",
+					recovered: 0,
+					settled: 0,
+					nonterminal: started.nonterminal,
+					alarm: disposition
+				}));
+			}
+			const recovered = yield* runtime.runRecovery;
+			const reports = new Map(recovered.map((report) => [report.submissionId, report]));
+			const current = yield* Stream.runCollect(ledger.scanNonterminal);
+			const heads = /* @__PURE__ */ new Map();
+			for (const row of current) if (!heads.has(row.threadId)) heads.set(row.threadId, row);
+			const eligible = [...heads.values()].filter((head) => !stableExternalWait(head, reports)).map((head) => head.threadId).sort();
+			let selected = eligible[0];
+			if (heads.size > 1 && selected !== void 0) {
+				yield* failpoint.hit("maintenance:select:before");
+				selected = yield* runTransaction("select maintenance lane", () => ctx.storage.transaction(async (transaction) => {
+					const { state } = await readMaintenanceState(transaction);
+					const next = eligible.find((threadId) => state.lastServedThreadId === void 0 || threadId > state.lastServedThreadId) ?? eligible[0];
+					if (next !== void 0) await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(ThreadMaintenanceState.make({
+						...state,
+						lastServedThreadId: next
+					})));
+					return next;
+				}));
+				yield* failpoint.hit("maintenance:select:after");
+			}
+			const settlement = selected === void 0 ? Option.none() : yield* runtime.processThreadHead(selected, { yieldAfter });
+			yield* finishDelivery;
+			if (Exit.isFailure(projected)) return yield* Effect.failCause(projected.cause);
+			const remaining = yield* Stream.runCollect(ledger.scanNonterminal);
+			const waitingHeads = /* @__PURE__ */ new Map();
+			const autonomous = remaining.some((snapshot) => {
+				const headWaiting = waitingHeads.get(snapshot.threadId);
+				if (headWaiting === void 0) waitingHeads.set(snapshot.threadId, stableExternalWait(snapshot, reports));
+				if (headWaiting === true && snapshot.state === "ready" && reports.get(snapshot.submissionId)?.decision._tag === "ApplyInput") return false;
+				return !stableExternalWait(snapshot, reports);
+			});
+			const progressed = Option.isSome(settlement) || recovered.some((report) => report.disposition === "repaired");
+			const delay = autonomous ? yield* rearmDelay(progressed) : 0;
+			const now = yield* Clock.currentTimeMillis;
+			yield* failpoint.hit("maintenance:finish:before");
+			const alarmDisposition = yield* mutations.withSnapshot((active) => Effect.gen(function* () {
+				const publicationDeadline = yield* pendingDeadline;
+				return yield* runTransaction("finish maintenance pass", () => ctx.storage.transaction(async (transaction) => {
+					const { state } = await readMaintenanceState(transaction);
+					const processed = autonomous || started.activeAtStart > 0 || active > 0 ? state.processed : state.processed > started.generation ? state.processed : started.generation;
+					const next = ThreadMaintenanceState.make({
+						...state,
+						processed,
+						nonterminal: remaining.length
+					});
+					await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
+					if (autonomous) {
+						await transaction.setAlarm(Option.isSome(publicationDeadline) ? Math.max(now + minimumAlarmDelay, Math.min(now + delay, publicationDeadline.value)) : now + delay);
+						return "rearmed";
+					}
+					if (started.activeAtStart > 0 || active > 0 || next.dirty > next.processed) {
+						await ensureTransactionAlarmBy(transaction, Option.isSome(publicationDeadline) ? Math.max(now + minimumAlarmDelay, Math.min(now + config.wakeScanInterval, publicationDeadline.value)) : now + config.wakeScanInterval);
+						return "rearmed";
+					}
+					if (Option.isSome(publicationDeadline)) {
+						await transaction.setAlarm(Math.max(now + minimumAlarmDelay, publicationDeadline.value));
+						return "rearmed";
+					}
+					await transaction.deleteAlarm();
+					return "cleared";
+				}));
+			}));
+			yield* failpoint.hit("maintenance:finish:after");
+			if (alarmDisposition === "cleared") yield* Ref.set(stalls, 0);
+			return yield* annotate(MaintenancePassReport.make({
+				phase: "actionable",
+				recovered: recovered.length,
+				settled: Option.isSome(settlement) ? 1 : 0,
+				nonterminal: remaining.length,
+				alarm: alarmDisposition
+			}));
+		});
+		return ThreadMaintenance.of({
+			pass: Effect.gen(function* () {
+				const yieldAfter = DateTime.makeUnsafe((yield* Clock.currentTimeMillis) + 6e5);
+				return yield* alarm.withWakesDeferred(maintenancePassGate.withPermit(pass(yieldAfter)));
+			}).pipe(Effect.timeoutOrElse({
+				duration: "14 minutes",
+				orElse: () => DurableAlarmError.make({
+					operation: "maintenance pass deadline",
+					message: "The maintenance event exceeded its 14 minute deadline; durable recovery remains pending"
+				})
+			})),
+			ensureAlarm: mutations.withSnapshot(() => ensureAlarm()),
+			withMutation: (body) => mutations.withMutation(body.pipe(Effect.tap(() => publishCommitted.pipe(Effect.provideService(ThreadPublication, publication)))))
+		});
+	}));
+};
+//#endregion
+export { DurableAlarmError, DurableAlarmService, MaintenancePassReport, ThreadHostMaintenance, ThreadMaintenance, ThreadMaintenanceFailpoint, ThreadMessageDelivery, ThreadMutationGate, ThreadPublication, publishCommitted, Alarm_exports as t };
+
+//# sourceMappingURL=Alarm.mjs.map