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

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { Cause, Clock, Context, Duration, Effect, Exit, Fiber, Layer, Option, PubSub, Random, Ref, Schema, Stream } from "effect";
+import { Cause, Clock, Context, Duration, Effect, Exit, Fiber, Layer, Option, PubSub, Random, Ref, Schema, Semaphore, Stream } from "effect";
 import { AbortCommand, AbortIntent, AdmissionConflict, AgentBindingResolver, AppendConflict, ApprovalConflict, ApprovalDecisionCommand, ApprovalDecisionIntent, CanonicalRecordEnvelope, CanonicalSequence, ConversationNotMaterialized, ConversationRead, ConversationStore, ConversationStoreError, DEFAULT_OWNERSHIP_LEASE_DURATION, DefinitionDigests, DeploymentId, DigestError, DurableAgentRuntime, DurableRuntimeConfig, DurableRuntimeFailpoint, DurableRuntimeFailpointError, FenceRejected, IdempotencyKey, IntegrityReport, JoinedToHost, LedgerError, ObligationReport, ObligationThresholds, OperationAuthorizationRequest, OperationAuthorizer, OperationDenied, OwnershipLost, PersistedJson, Principal, ProducerId, Receipt, RecoveryExplanation, RecoveryReport, RetryCommand, RetryRefused, RunJournalError, Settlement, SettlementConflict, SubmissionLedger, SubmissionLookupByKey, ToolReconciler, UnknownResolutionCommand, UnknownResolutionConflict, UnknownResolutionIntent, WakeScheduler } from "@effect-agent/session";
 import { ConversationPortTransport, DEFAULT_MAX_STORED_VALUE_BYTES, conversationStoreLayer, handleEncodedPortRequest, portTransportFailure, routedConversationStoreLayer, routedSubmissionLedgerLayer, storageConfigLayer, storageFailpointLayer, submissionLedgerLayer } from "@effect-agent/storage-cloudflare";
 import { AgentId, AgentInputError, ConversationId, SubmissionId } from "@effect-agent/core";
@@ -180,11 +180,10 @@ const CLOUDFLARE_RUNTIME_DEFAULTS = {
 * 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. */
 var DurableAlarmError = class extends Schema.TaggedError()("DurableAlarmError", {
@@ -207,7 +206,6 @@ var DurableAlarmService = class DurableAlarmService extends Context.Service()("@
 		* on top of the already-committed pre-armed alarm.
 		*/
 		const runningPasses = yield* Ref.make(0);
-		const wakeDeferred = yield* Ref.make(false);
 		const scheduled = Effect.tryPromise({
 			try: () => ctx.storage.getAlarm(),
 			catch: alarmFailure("get alarm")
@@ -218,14 +216,8 @@ var DurableAlarmService = class DurableAlarmService extends Context.Service()("@
 		});
 		const ensureScheduledBy = (epochMillis) => scheduled.pipe(Effect.flatMap((existing) => Option.isSome(existing) && existing.value <= epochMillis ? Effect.void : scheduleAt(epochMillis)));
 		const armNow = Clock.currentTimeMillis.pipe(Effect.flatMap((now) => ensureScheduledBy(now)));
-		const scheduleNow = Ref.get(runningPasses).pipe(Effect.flatMap((passes) => passes > 0 ? Ref.set(wakeDeferred, true) : armNow));
-		/**
-		* Flush after the LAST concurrent pass: the re-arm lands at the very end of the alarm
-		* handler, where a superseding cancellation only re-delivers to the already-idempotent
-		* pass. Runs inside `Effect.ensuring`, so flush failures are logged, never raised.
-		*/
-		const flushDeferredWake = Ref.get(runningPasses).pipe(Effect.flatMap((passes) => passes > 0 ? Effect.void : Ref.getAndSet(wakeDeferred, false).pipe(Effect.flatMap((wanted) => wanted ? armNow : Effect.void))), Effect.catch((error) => Effect.logWarning("DurableAlarmService: deferred wake flush failed", error)));
-		const withWakesDeferred = (body) => Ref.update(runningPasses, (passes) => passes + 1).pipe(Effect.andThen(body), Effect.ensuring(Ref.update(runningPasses, (passes) => passes - 1).pipe(Effect.andThen(flushDeferredWake))));
+		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 = Effect.tryPromise({
 			try: () => ctx.storage.deleteAlarm(),
 			catch: alarmFailure("delete alarm")
@@ -242,35 +234,78 @@ var DurableAlarmService = class DurableAlarmService extends Context.Service()("@
 };
 /** What one maintenance pass did — auditable evidence mirroring `NodeDurableHost`'s report. */
 var MaintenancePassReport = class extends Schema.Class("@effect-agent/platform-cloudflare/MaintenancePassReport")({
+	/** `caught-up` is generation-only; `actionable` ran recovery and one bounded drain. */
+	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)),
 	/** Settlements the drain pass finalized. */
 	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` while nonterminal work remains, `cleared` once everything settled. */
+	/** `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 ConversationMaintenanceFailpoint = class extends Context.Service()("@effect-agent/platform-cloudflare/ConversationMaintenanceFailpoint") {
+	static layer = Layer.succeed(this)({ hit: () => Effect.void });
+};
+const MaintenanceGeneration = Schema.BigIntFromString.check(Schema.isGreaterThanOrEqualToBigInt(0n));
+/** Versioned, platform-private maintenance state stored through Durable Object KV. */
+var ConversationMaintenanceState = class extends Schema.Class("@effect-agent/platform-cloudflare/ConversationMaintenanceState")({
+	schemaVersion: Schema.Literal(1),
+	dirty: MaintenanceGeneration,
+	processed: MaintenanceGeneration,
+	nonterminal: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+}) {};
+const MAINTENANCE_STATE_KEY = "effect-agent:conversation-maintenance:v1";
+const decodeMaintenanceState = Schema.decodeUnknownSync(ConversationMaintenanceState);
+const encodeMaintenanceState = Schema.encodeSync(ConversationMaintenanceState);
+const initialMaintenanceState = () => ConversationMaintenanceState.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) => {
+	switch (snapshot.state) {
+		case "suspended":
+		case "unknown":
+		case "joined": return true;
+		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;
+	}
+};
 /**
-* The idempotent maintenance pass and the alarm-invariant helpers (plan §1.4, D-P6-1/2).
-*
-* `pass` = pre-arm → `runRecovery` → `processConversationResolved` → re-arm-or-clear:
+* Incremental, quiescent maintenance over a durable dirty/processed generation (issue #93).
 *
-* 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.
+* `pass` = generation snapshot/pre-arm → recovery → bounded drain → generation acknowledgement:
 *
-* 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.
 */
 var ConversationMaintenance = class ConversationMaintenance extends Context.Service()("@effect-agent/platform-cloudflare/ConversationMaintenance") {
 	static layer = Layer.effect(ConversationMaintenance)(Effect.gen(function* () {
@@ -280,13 +315,76 @@ var ConversationMaintenance = class ConversationMaintenance extends Context.Serv
 		const alarm = yield* DurableAlarmService;
 		const config = yield* CloudflareDurableRuntimeConfig;
 		const identity = yield* ConversationObjectIdentity;
+		const { ctx } = yield* DurableObjectContext;
+		const failpoint = yield* ConversationMaintenanceFailpoint;
 		/**
 		* 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 preArm = Clock.currentTimeMillis.pipe(Effect.flatMap((now) => alarm.ensureScheduledBy(now + config.wakeScanInterval)));
-		const countNonterminal = Stream.runCollect(ledger.scanNonterminal).pipe(Effect.map((snapshots) => snapshots.length));
+		/**
+		* Incarnation-local mutation count guarded with the generation transactions below. It is
+		* deliberately not durable: after eviction every begun mutation has stopped, while its
+		* pre-armed dirty generation remains durable for recovery. The short gate never spans the
+		* caller's mutation or cross-Object I/O.
+		*/
+		const activeMutations = yield* Ref.make(0);
+		const generationGate = yield* Semaphore.make(1);
+		const maintenancePassGate = yield* Semaphore.make(1);
+		const minimumAlarmDelay = Math.max(1, Math.ceil(config.alarmBackoffBase / 2));
+		const runTransaction = (operation, transaction) => Effect.tryPromise({
+			try: transaction,
+			catch: alarmFailure(operation)
+		});
+		const beginMutation = Effect.fn("ConversationMaintenance.beginMutation")(function* () {
+			yield* failpoint.hit("maintenance:dirty:before");
+			const now = yield* Clock.currentTimeMillis;
+			yield* runTransaction("advance maintenance generation", () => ctx.storage.transaction(async (transaction) => {
+				const { state } = await readMaintenanceState(transaction);
+				const next = ConversationMaintenanceState.make({
+					...state,
+					dirty: state.dirty + 1n
+				});
+				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) => Effect.acquireUseRelease(generationGate.withPermit(beginMutation()), () => failpoint.hit("maintenance:mutation:armed").pipe(Effect.andThen(body), Effect.tap(() => failpoint.hit("maintenance:mutation:finished"))), () => endMutation);
+		const ensureAlarm = Effect.fn("ConversationMaintenance.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);
+			}));
+			yield* failpoint.hit("maintenance:ensure:after");
+		});
+		const beginPass = Effect.fn("ConversationMaintenance.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 transaction.deleteAlarm();
+					return {
+						_tag: "CaughtUp",
+						nonterminal: state.nonterminal
+					};
+				}
+				await ensureTransactionAlarmBy(transaction, now + minimumAlarmDelay);
+				return {
+					_tag: "Actionable",
+					generation: state.dirty
+				};
+			}));
+			yield* failpoint.hit("maintenance:begin:after");
+			return result;
+		});
 		const rearmDelay = Effect.fn("ConversationMaintenance.rearmDelay")(function* (progressed) {
 			const priorStalls = yield* Ref.getAndUpdate(stalls, (count) => progressed ? 0 : count + 1);
 			if (progressed) return config.alarmBackoffBase;
@@ -297,49 +395,73 @@ var ConversationMaintenance = class ConversationMaintenance extends Context.Serv
 			return Math.min(jittered, config.wakeScanInterval);
 		});
 		const pass = Effect.fn("ConversationMaintenance.pass")(function* () {
-			yield* preArm;
+			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* generationGate.withPermit(Effect.gen(function* () {
+				const activeAtStart = yield* Ref.get(activeMutations);
+				return {
+					...yield* beginPass(),
+					activeAtStart
+				};
+			}));
+			if (started._tag === "CaughtUp") return yield* annotate(MaintenancePassReport.make({
+				phase: "caught-up",
+				recovered: 0,
+				settled: 0,
+				nonterminal: started.nonterminal,
+				alarm: "cleared"
+			}));
 			const recovered = yield* runtime.runRecovery;
 			const settlements = yield* runtime.processConversationResolved(identity.conversationId).pipe(Effect.provideService(AgentBindingResolver, resolver));
-			const nonterminal = yield* countNonterminal;
-			if (nonterminal === 0) {
-				yield* alarm.cancel;
-				yield* Ref.set(stalls, 0);
-				const appeared = yield* countNonterminal;
-				if (appeared > 0) {
-					yield* preArm;
-					return MaintenancePassReport.make({
-						recovered: recovered.length,
-						settled: settlements.length,
-						nonterminal: appeared,
-						alarm: "rearmed"
-					});
-				}
-				return MaintenancePassReport.make({
-					recovered: recovered.length,
-					settled: settlements.length,
-					nonterminal,
-					alarm: "cleared"
-				});
-			}
+			const remaining = yield* Stream.runCollect(ledger.scanNonterminal);
+			const reports = new Map(recovered.map((report) => [report.submissionId, report]));
+			const autonomous = remaining.some((snapshot) => !stableExternalWait(snapshot, reports));
 			const progressed = settlements.length > 0 || recovered.some((report) => report.disposition === "repaired");
-			const delay = yield* rearmDelay(progressed);
+			const delay = autonomous ? yield* rearmDelay(progressed) : 0;
 			const now = yield* Clock.currentTimeMillis;
-			yield* alarm.ensureScheduledBy(now + delay);
-			return MaintenancePassReport.make({
+			yield* failpoint.hit("maintenance:finish:before");
+			const alarmDisposition = yield* generationGate.withPermit(Effect.gen(function* () {
+				const active = yield* Ref.get(activeMutations);
+				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 = ConversationMaintenanceState.make({
+						...state,
+						processed,
+						nonterminal: remaining.length
+					});
+					await transaction.put(MAINTENANCE_STATE_KEY, encodeMaintenanceState(next));
+					if (autonomous) {
+						await transaction.setAlarm(now + delay);
+						return "rearmed";
+					}
+					if (started.activeAtStart > 0 || active > 0 || next.dirty > next.processed) {
+						await ensureTransactionAlarmBy(transaction, now + config.wakeScanInterval);
+						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: settlements.length,
-				nonterminal,
-				alarm: "rearmed"
-			});
-		});
-		const ensureAlarm = Effect.fn("ConversationMaintenance.ensureAlarm")(function* () {
-			if ((yield* countNonterminal) === 0) return;
-			yield* preArm;
+				nonterminal: remaining.length,
+				alarm: alarmDisposition
+			}));
 		});
 		return ConversationMaintenance.of({
-			pass: alarm.withWakesDeferred(pass()),
+			pass: alarm.withWakesDeferred(maintenancePassGate.withPermit(pass())),
 			ensureAlarm: ensureAlarm(),
-			preArm
+			withMutation
 		});
 	}));
 };
@@ -519,6 +641,7 @@ var CloudflareDurableRuntime = class {
 				abortPollInterval: Duration.millis(config.abortPollInterval)
 			}));
 			const runtimeFailpointLayer = options.runtimeFailpoint === void 0 ? DurableRuntimeFailpoint.layer : Layer.succeed(DurableRuntimeFailpoint)({ hit: options.runtimeFailpoint(ctx) });
+			const maintenanceFailpointLayer = options.maintenanceFailpoint === void 0 ? ConversationMaintenanceFailpoint.layer : Layer.succeed(ConversationMaintenanceFailpoint)({ hit: options.maintenanceFailpoint(ctx) });
 			const reconcilerLayer = options.toolReconciler ?? ToolReconciler.uncertain;
 			const bindingResolverLayer = Layer.effect(AgentBindingResolver)(Effect.map(resolveBindings(options.bindings, {
 				ctx,
@@ -526,7 +649,7 @@ var CloudflareDurableRuntime = class {
 				conversationId,
 				producerId
 			}), (bindings) => AgentBindingResolver.fromBindings(bindings)));
-			const base = Layer.mergeAll(identityLayer, cloudflareConfigLayer, DurableAlarmService.layer);
+			const base = Layer.mergeAll(identityLayer, cloudflareConfigLayer, DurableAlarmService.layer, maintenanceFailpointLayer);
 			const runtimeStack = DurableAgentRuntime.layer.pipe(Layer.provideMerge(routedPorts), Layer.provideMerge(cloudflareWakeSchedulerLayer), Layer.provideMerge(runtimeConfigLayer), Layer.provideMerge(bindingResolverLayer), Layer.provide(Layer.mergeAll(runtimeFailpointLayer, reconcilerLayer, BrowserCrypto.layer)), Layer.provideMerge(base));
 			return Layer.mergeAll(runtimeStack, ConversationMaintenance.layer.pipe(Layer.provide(runtimeStack)), portsEndpointLayer);
 		}));
@@ -862,13 +985,12 @@ const submitEndpoint = (encoded) => decodeSubmitRequest(encoded).pipe(Effect.map
 	const maintenance = yield* ConversationMaintenance;
 	const runtime = yield* DurableAgentRuntime;
 	yield* gateAdmissionLimits(request);
-	yield* maintenance.preArm;
-	const receipt = yield* runtime.submit(passthroughSubmitAgent(request.agentId), request.inputPayload, {
+	const receipt = yield* maintenance.withMutation(runtime.submit(passthroughSubmitAgent(request.agentId), request.inputPayload, {
 		conversationId: identity.conversationId,
 		principal: request.principal,
 		idempotencyKey: request.idempotencyKey,
 		definitions: request.definitions
-	});
+	}));
 	return SubmitSucceeded.make({ receipt });
 })), respond, Effect.flatMap(encodeResponse));
 const awaitSettlementEndpoint = (encoded) => decodeReceipt(encoded).pipe(Effect.mapError(protocolFailure("The receipt could not be decoded")), Effect.flatMap((receipt) => Effect.gen(function* () {
@@ -892,8 +1014,7 @@ const observePageEndpoint = (encoded) => decodeObservePageRequest(encoded).pipe(
 const abortEndpoint = (encoded) => decodeAbortCommand(encoded).pipe(Effect.mapError(protocolFailure("The abort command could not be decoded")), Effect.flatMap((command) => Effect.gen(function* () {
 	const maintenance = yield* ConversationMaintenance;
 	const runtime = yield* DurableAgentRuntime;
-	yield* maintenance.preArm;
-	const intent = yield* runtime.abort(command);
+	const intent = yield* maintenance.withMutation(runtime.abort(command));
 	return AbortRecorded.make({ intent });
 })), respond, Effect.flatMap(encodeResponse));
 /**
@@ -907,15 +1028,13 @@ const deniedToProtocolFailure = (denied) => Effect.fail(HostProtocolError.make({
 const resolveApprovalEndpoint = (encoded) => decodeApprovalDecisionCommand(encoded).pipe(Effect.mapError(protocolFailure("The approval command could not be decoded")), Effect.flatMap((command) => Effect.gen(function* () {
 	const maintenance = yield* ConversationMaintenance;
 	const runtime = yield* DurableAgentRuntime;
-	yield* maintenance.preArm;
-	const intent = yield* runtime.resolveApproval(command).pipe(Effect.catchTag("OperationDenied", deniedToProtocolFailure));
+	const intent = yield* maintenance.withMutation(runtime.resolveApproval(command).pipe(Effect.catchTag("OperationDenied", deniedToProtocolFailure)));
 	return ApprovalRecorded.make({ intent });
 })), respond, Effect.flatMap(encodeResponse));
 const resolveUnknownEndpoint = (encoded) => decodeUnknownResolutionCommand(encoded).pipe(Effect.mapError(protocolFailure("The resolution command could not be decoded")), Effect.flatMap((command) => Effect.gen(function* () {
 	const maintenance = yield* ConversationMaintenance;
 	const runtime = yield* DurableAgentRuntime;
-	yield* maintenance.preArm;
-	const intent = yield* runtime.resolveUnknown(command).pipe(Effect.catchTag("OperationDenied", deniedToProtocolFailure));
+	const intent = yield* maintenance.withMutation(runtime.resolveUnknown(command).pipe(Effect.catchTag("OperationDenied", deniedToProtocolFailure)));
 	return UnknownResolutionRecorded.make({ intent });
 })), respond, Effect.flatMap(encodeResponse));
 /** Explain one Submission (`submissionId` present) or every nonterminal lane member. */
@@ -983,8 +1102,7 @@ const verifyEndpoint = (encoded) => decodeAdminVerifyRequest(encoded).pipe(Effec
 const retryEndpoint = (encoded) => decodeRetryCommand(encoded).pipe(Effect.mapError(protocolFailure("The retry command could not be decoded")), Effect.flatMap((command) => Effect.gen(function* () {
 	const maintenance = yield* ConversationMaintenance;
 	const runtime = yield* DurableAgentRuntime;
-	yield* maintenance.preArm;
-	const report = yield* runtime.retry(command);
+	const report = yield* maintenance.withMutation(runtime.retry(command));
 	return RetryExecuted.make({ report });
 })), respondAdmin, Effect.flatMap(encodeAdminResponseTotal));
 const obligationsEndpoint = (encoded) => decodeObligationThresholds(encoded).pipe(Effect.mapError(protocolFailure("The obligation thresholds could not be decoded")), Effect.flatMap((thresholds) => Effect.gen(function* () {
@@ -992,20 +1110,20 @@ const obligationsEndpoint = (encoded) => decodeObligationThresholds(encoded).pip
 	return ObligationsScanned.make({ report });
 })), respondAdmin, Effect.flatMap(encodeAdminResponseTotal));
 /**
-* Owner-side `portCall`: pre-arm before a mutating envelope (a routed admission committed by
-* THIS Object must already carry the alarm that will finish it), execute on the LOCAL facets
-* (never the routed decorators), then arm an immediate alarm so the mutated lane is
-* processed promptly. Protocol anomalies answer `PortFailed(PortProtocolError)`.
+* Owner-side `portCall`: wrap a mutating envelope in the same pre-armed generation protocol as
+* public RPC (a routed mutation committed by THIS Object must already carry the alarm that will
+* finish it), execute on the LOCAL facets (never the routed decorators), then arm an immediate
+* alarm so the mutated lane is processed promptly. Protocol anomalies answer
+* `PortFailed(PortProtocolError)`.
 */
 const portCallEndpoint = (encoded) => Effect.gen(function* () {
 	const ports = yield* ConversationObjectPorts;
 	const maintenance = yield* ConversationMaintenance;
 	const alarm = yield* DurableAlarmService;
 	const mutating = isMutatingPortRequest(encoded);
-	if (mutating) {
-		if ((yield* maintenance.preArm.pipe(Effect.exit))._tag === "Failure") return encodedPortProtocolFailure("The owner Object could not arm its maintenance alarm before the mutation.");
-	}
-	const response = yield* ports.handle(encoded);
+	const handled = yield* (mutating ? maintenance.withMutation(ports.handle(encoded)) : ports.handle(encoded)).pipe(Effect.exit);
+	if (handled._tag === "Failure") return encodedPortProtocolFailure("The owner Object could not arm its maintenance alarm before the mutation.");
+	const response = handled.value;
 	if (mutating) yield* alarm.scheduleNow.pipe(Effect.catch((error) => Effect.logWarning("ConversationObject.portCall: immediate re-arm failed", error)));
 	return response;
 });
@@ -1711,6 +1829,6 @@ const classifyWorkerFailure = (cause, maxWallTime) => {
 /** Layer building the Dynamic Worker `CodeExecutor` from resolved bindings. */
 const dynamicWorkerCodeExecutorLayer = (options) => Layer.succeed(CodeExecutor)(CodeExecutor.of({ execute: makeExecute(options) }));
 //#endregion
-export { AbortRecorded, AdminExplainRequest, AdminFailed, AdminFailure, AdminResponse, AdminVerifyRequest, AdmissionLimitExceeded, ApprovalRecorded, CLOUDFLARE_DATABASE_CAP_BYTES, CLOUDFLARE_RUNTIME_DEFAULTS, CloudflareAdmissionLimitsValue, CloudflareBindingError, CloudflareConversationClient, CloudflareDurableRuntime, CloudflareDurableRuntimeConfig, CloudflareDurableRuntimeConfigValue, CloudflarePlatformConfigError, CodeModeHostEntrypoint, ConversationClientError, ConversationMaintenance, ConversationObjectIdentity, ConversationObjectNamespace, ConversationObjectPorts, DEFAULT_MAX_DATABASE_BYTES, DurableAlarmError, DurableAlarmService, DurableObjectContext, ExplainedRecovery, HostFailed, HostFailure, HostProtocolError, HostResponse, 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, CloudflareAdmissionLimitsValue, CloudflareBindingError, CloudflareConversationClient, CloudflareDurableRuntime, CloudflareDurableRuntimeConfig, CloudflareDurableRuntimeConfigValue, CloudflarePlatformConfigError, CodeModeHostEntrypoint, ConversationClientError, ConversationMaintenance, ConversationMaintenanceFailpoint, ConversationObjectIdentity, ConversationObjectNamespace, ConversationObjectPorts, DEFAULT_MAX_DATABASE_BYTES, DurableAlarmError, DurableAlarmService, DurableObjectContext, ExplainedRecovery, HostFailed, HostFailure, HostProtocolError, HostResponse, 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.mjs.map