@akterjs/effect 0.0.0-stage → 0.1.1

package/dist/host/sqlite/sqlite-reason.pure.mjs

@@ -0,0 +1,13 @@
+import { Option, Schema } from "effect";
+// src/host/sqlite/sqlite-reason.pure.ts
+const NativeSqliteError = Schema.Struct({
+	errcode: Schema.Int,
+	message: Schema.String
+});
+const decodeNative = Schema.decodeUnknownOption(NativeSqliteError);
+const sqliteReason = (cause) => Option.map(decodeNative(cause), ({ errcode, message }) => ({
+	code: errcode,
+	message
+}));
+const reasonText = ({ code, message }) => `${message} (SQLite error ${code})`;
+export { reasonText, sqliteReason };

package/dist/host/timer/actor-timers.sql.d.mts

@@ -0,0 +1,32 @@
+import { TimerChanges, TimerId } from "../../contract/command/timer.schema.mjs";
+import { Effect, Option } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+interface TimerWrite {
+  readonly at: number;
+  readonly principal: string;
+  readonly sql: SqlClient.SqlClient;
+  readonly timers: TimerChanges;
+}
+interface TimerLookup {
+  readonly id: TimerId;
+  readonly sql: SqlClient.SqlClient;
+}
+interface DueLookup {
+  readonly now: number;
+  readonly sql: SqlClient.SqlClient;
+}
+interface ClaimedTimer {
+  readonly command: string;
+  readonly payload: string;
+  readonly principal: string;
+}
+type Sql<Value> = Effect.Effect<Value, SqlError.SqlError>;
+declare const saveTimers: ({ at, principal, sql, timers }: TimerWrite) => Sql<void>;
+declare const dueTimers: ({ now, sql }: DueLookup) => Sql<readonly TimerId[]>;
+declare const claimTimer: ({ id, sql }: TimerLookup) => Sql<Option.Option<ClaimedTimer>>;
+interface Deferral extends TimerLookup {
+  readonly at: number;
+}
+declare const deferTimer: ({ at, id, sql }: Deferral) => Sql<void>;
+declare const earliestDue: (sql: SqlClient.SqlClient) => Sql<Option.Option<number>>;
+export { claimTimer, deferTimer, dueTimers, earliestDue, saveTimers };

package/dist/host/timer/actor-timers.sql.mjs

@@ -0,0 +1,8 @@
+import { Array, Duration, Effect, Option } from "effect";
+// src/host/timer/actor-timers.sql.ts
+const saveTimers = ({ at, principal, sql, timers }) => Effect.andThen(Effect.forEach(timers.cancelled, (id) => sql`DELETE FROM akter_timers WHERE id = ${id}`, { discard: true }), Effect.forEach(timers.scheduled, (timer) => sql`INSERT INTO akter_timers (id, due_at, command, payload, principal) VALUES (${timer.id}, ${at + Duration.toMillis(timer.after)}, ${timer.command}, ${timer.payload}, ${principal})`, { discard: true }));
+const dueTimers = ({ now, sql }) => Effect.map(sql`SELECT id FROM akter_timers WHERE due_at <= ${now} ORDER BY due_at, id`, Array.map((row) => row.id));
+const claimTimer = ({ id, sql }) => Effect.map(sql`DELETE FROM akter_timers WHERE id = ${id} RETURNING command, payload, principal`, Array.head);
+const deferTimer = ({ at, id, sql }) => Effect.asVoid(sql`UPDATE akter_timers SET due_at = ${at} WHERE id = ${id}`);
+const earliestDue = (sql) => Effect.map(sql`SELECT due_at AS due FROM akter_timers ORDER BY due_at LIMIT 1`, (rows) => Option.map(Array.head(rows), (row) => row.due));
+export { claimTimer, deferTimer, dueTimers, earliestDue, saveTimers };

package/dist/host/timer/timer-runner.service.d.mts

@@ -0,0 +1,26 @@
+import { TimerId } from "../../contract/command/timer.schema.mjs";
+import { OpenedActor } from "../actor/actor-database.service.mjs";
+import { CommandRunner } from "../command/command-runner.service.mjs";
+import { CeilingGuard } from "../upkeep/execution-authority.pure.mjs";
+import { Context, Duration, Effect, Layer, Option } from "effect";
+import { SqlError } from "effect/sql";
+interface Firing {
+  readonly key: string;
+  /** Runs each timer's command against the store's storage ceiling, when it has one. */
+  readonly measured?: CeilingGuard;
+  readonly opened: OpenedActor;
+}
+declare const TimerRunner_base: Context.ServiceClass<TimerRunner, "@akterjs/effect/host/timer/timer-runner.service/TimerRunner", {
+  readonly fireDue: (firing: Firing) => Effect.Effect<readonly TimerId[], SqlError.SqlError>;
+  readonly nextDue: (opened: OpenedActor) => Effect.Effect<Option.Option<number>, SqlError.SqlError>;
+}> & {
+  readonly make: Effect.Effect<{
+    readonly fireDue: (firing: Firing) => Effect.Effect<readonly TimerId[], SqlError.SqlError>;
+    readonly nextDue: (opened: OpenedActor) => Effect.Effect<Option.Option<number>, SqlError.SqlError>;
+  }, never, CommandRunner>;
+};
+export declare class TimerRunner extends TimerRunner_base {
+  static readonly layer: Layer.Layer<TimerRunner, never, never>;
+  static readonly refusedRetry: Context.Reference<Duration.Duration>;
+}
+export {};

package/dist/host/timer/timer-runner.service.mjs

@@ -0,0 +1,68 @@
+import { claimTimer, deferTimer, dueTimers, earliestDue } from "./actor-timers.sql.mjs";
+import { CommandRunner } from "../command/command-runner.service.mjs";
+import { timerCommandId } from "../command/command-id-reuse.pure.mjs";
+import { Array, Clock, Context, Duration, Effect, Layer, Option, identity } from "effect";
+import { SqlError } from "effect/sql";
+// src/host/timer/timer-runner.service.ts
+const refusedRetrySeconds = 30;
+/**
+* How long a timer whose command the storage ceiling refused waits to fire again. A refusal lasts at least until the
+* store's size is read again, so retrying sooner would mostly be refused again.
+*/
+const RefusedTimerRetry = Context.Reference("@akterjs/effect/host/timer/timer-runner.service/RefusedTimerRetry", { defaultValue: () => Duration.seconds(refusedRetrySeconds) });
+const refusedTimer = ({ id, opened, retry }) => (refused) => Effect.gen(function* deferRefused() {
+	const now = yield* Clock.currentTimeMillis;
+	yield* deferTimer({
+		at: now + Duration.toMillis(retry),
+		id,
+		sql: opened.sql
+	});
+	yield* Effect.logWarning(`timer ${id} would grow its store past its storage ceiling and fires again later`, refused);
+	return Option.none();
+});
+var TimerRunner = class extends Context.Service()("@akterjs/effect/host/timer/timer-runner.service/TimerRunner", { make: Effect.gen(function* makeTimerRunner() {
+	const runner = yield* CommandRunner;
+	const retry = yield* RefusedTimerRetry;
+	const fireOne = ({ id, key, measured = identity, opened }) => opened.sql.withTransaction(Effect.gen(function* claimAndRun() {
+		const claimed = yield* claimTimer({
+			id,
+			sql: opened.sql
+		});
+		if (Option.isNone(claimed)) return Option.none();
+		yield* measured(runner.runOwn({
+			opened,
+			request: {
+				...claimed.value,
+				commandId: timerCommandId(id),
+				key,
+				member: claimed.value.command
+			}
+		}).pipe(Effect.catchIf((failure) => !SqlError.isSqlError(failure), (failure) => Effect.logWarning(`timer ${id} ended with a failure the journal does not keep`, failure))));
+		return Option.some(id);
+	})).pipe(Effect.catchTag("StorageLimitError", refusedTimer({
+		id,
+		opened,
+		retry
+	})));
+	return {
+		fireDue: Effect.fn("TimerRunner.fireDue")(function* fireDue(firing) {
+			const now = yield* Clock.currentTimeMillis;
+			const due = yield* dueTimers({
+				now,
+				sql: firing.opened.sql
+			});
+			const fired = yield* Effect.forEach(due, (id) => fireOne({
+				...firing,
+				id
+			}));
+			return Array.getSomes(fired);
+		}),
+		nextDue: Effect.fn("TimerRunner.nextDue")(function* nextDue(opened) {
+			return yield* earliestDue(opened.sql);
+		})
+	};
+}) }) {
+	static layer = Layer.effect(this, this.make).pipe(Layer.provide(CommandRunner.layer));
+	static refusedRetry = RefusedTimerRetry;
+};
+export { TimerRunner };

package/dist/host/upkeep/actor-due.sql.d.mts

@@ -0,0 +1,26 @@
+import { Parked } from "../job/job-runs.pure.mjs";
+import "../job/job-engine.adapter.mjs";
+import { Effect, Option } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+/** When an actor next has work: its soonest timer (or a job result's next round of retries), and whether a message waits for delivery and a job to run. */
+interface DueWork {
+  readonly jobs: boolean;
+  readonly messages: boolean;
+  readonly timer: Option.Option<number>;
+}
+/**
+ * One statement for what the upkeep reads after each commit, instead of one each for the soonest timer, the outbox
+ * and the open jobs: each is a message to the native worker on Akter Cloud. An open job is counted as `openJobs`
+ * counts it, so an 'open' entry an older engine left behind beside its result doesn't count. A job whose result spent
+ * a round of retries doesn't count either: its next round's time counts as a timer instead, so the actor goes idle
+ * until then and the upkeep, or Akter Cloud's shard, wakes it for that round.
+ *
+ * A job `parked` on a signal or a clock doesn't count until one of the entries it waits on is stored: a signal comes
+ * with a command, which opens the actor, and a clock's time (its `clock/<name>` entry, until its
+ * `deferred/DurableClock/<name>` result) counts as a timer, so the actor can go idle while its jobs wait.
+ */
+declare const dueWork: ({ parked, sql }: {
+  readonly parked: readonly Parked[];
+  readonly sql: SqlClient.SqlClient;
+}) => Effect.Effect<DueWork, SqlError.SqlError>;
+export { type DueWork, dueWork };

package/dist/host/upkeep/actor-due.sql.mjs

@@ -0,0 +1,43 @@
+import { Array, Effect, Option, Schema } from "effect";
+// src/host/upkeep/actor-due.sql.ts
+const none = 0;
+const Ids = Schema.fromJsonString(Schema.Array(Schema.String));
+const Waits = Schema.fromJsonString(Schema.Array(Schema.Struct({
+	entry: Schema.String,
+	id: Schema.String
+})));
+const dueRows = (sql, { parked, waits }) => sql`SELECT (SELECT min(due) FROM (SELECT (SELECT due_at FROM akter_timers ORDER BY due_at LIMIT 1) AS due UNION ALL SELECT min(json_extract(stalled.value, '$.next')) FROM akter_workflow open INDEXED BY akter_workflow_open JOIN akter_workflow stalled ON stalled.execution_id = open.execution_id AND stalled.entry = 'undelivered' WHERE open.entry = 'open' AND json_extract(stalled.value, '$.retrying') = 0 UNION ALL SELECT min(CAST(clock.value AS INTEGER)) FROM akter_workflow open INDEXED BY akter_workflow_open JOIN akter_workflow clock ON clock.execution_id = open.execution_id AND clock.entry > 'clock/' AND clock.entry < 'clock0' WHERE open.entry = 'open' AND NOT EXISTS (SELECT 1 FROM akter_workflow result WHERE result.execution_id = open.execution_id AND result.entry = 'result') AND NOT EXISTS (SELECT 1 FROM akter_workflow fired WHERE fired.execution_id = open.execution_id AND fired.entry = 'deferred/DurableClock/' || substr(clock.entry, 7)))) AS timer, EXISTS (SELECT 1 FROM akter_outbox) AS messages, EXISTS (SELECT 1 FROM akter_workflow open INDEXED BY akter_workflow_open JOIN akter_workflow started ON started.execution_id = open.execution_id AND started.entry = 'job' JOIN akter_workflow payload ON payload.execution_id = open.execution_id AND payload.entry = 'payload' WHERE open.entry = 'open' AND NOT EXISTS (SELECT 1 FROM akter_workflow result WHERE result.execution_id = open.execution_id AND result.entry = 'result') AND NOT EXISTS (SELECT 1 FROM akter_workflow stalled WHERE stalled.execution_id = open.execution_id AND stalled.entry = 'undelivered' AND json_extract(stalled.value, '$.retrying') = 0) AND (open.execution_id NOT IN (SELECT value FROM json_each(${parked})) OR EXISTS (SELECT 1 FROM json_each(${waits}) wait JOIN akter_workflow stored ON stored.execution_id = open.execution_id AND stored.entry = json_extract(wait.value, '$.entry') WHERE json_extract(wait.value, '$.id') = open.execution_id))) AS jobs`;
+/** The parked jobs' ids and the entries they wait on, as the JSON lists the statement reads with `json_each`. */
+const listsOf = (parked) => {
+	const ids = Array.map(parked, (job) => job.id);
+	const waits = Array.flatMap(parked, ({ id, waits: entries }) => Array.map(entries, (entry) => ({
+		entry,
+		id
+	})));
+	return Effect.orDie(Effect.all({
+		parked: Schema.encodeEffect(Ids)(ids),
+		waits: Schema.encodeEffect(Waits)(waits)
+	}));
+};
+/**
+* One statement for what the upkeep reads after each commit, instead of one each for the soonest timer, the outbox
+* and the open jobs: each is a message to the native worker on Akter Cloud. An open job is counted as `openJobs`
+* counts it, so an 'open' entry an older engine left behind beside its result doesn't count. A job whose result spent
+* a round of retries doesn't count either: its next round's time counts as a timer instead, so the actor goes idle
+* until then and the upkeep, or Akter Cloud's shard, wakes it for that round.
+*
+* A job `parked` on a signal or a clock doesn't count until one of the entries it waits on is stored: a signal comes
+* with a command, which opens the actor, and a clock's time (its `clock/<name>` entry, until its
+* `deferred/DurableClock/<name>` result) counts as a timer, so the actor can go idle while its jobs wait.
+*/
+const dueWork = ({ parked, sql }) => Effect.gen(function* readDue() {
+	const lists = yield* listsOf(parked);
+	const rows = yield* dueRows(sql, lists);
+	const row = Array.head(rows);
+	return {
+		jobs: Option.exists(row, (found) => found.jobs !== none),
+		messages: Option.exists(row, (found) => found.messages !== none),
+		timer: Option.flatMap(row, (found) => Option.fromNullOr(found.timer))
+	};
+});
+export { dueWork };

package/dist/host/upkeep/actor-upkeep.service.d.mts

@@ -0,0 +1,55 @@
+import { OpenedActor } from "../actor/actor-database.service.mjs";
+import { JobStore } from "../job/job-runs.pure.mjs";
+import { Delivery, DeliveryBatch, OutboxRunner } from "../outbox/outbox-runner.service.mjs";
+import { TimerRunner } from "../timer/timer-runner.service.mjs";
+import { JobEngine } from "../job/job-engine.adapter.mjs";
+import { JobResults } from "../job/job-results.service.mjs";
+import { CeilingGuard } from "./execution-authority.pure.mjs";
+import { Context, Duration, Effect, Layer, Option, Scope } from "effect";
+import { SqlError } from "effect/sql";
+interface Upkeep<Failure> {
+  readonly exclusive: <Success, Error, Needs>(effect: Effect.Effect<Success, Error, Needs>) => Effect.Effect<Success, Error, Needs>;
+  readonly key: string;
+  readonly lock: <Success, Error, Needs>(effect: Effect.Effect<Success, Error, Needs>) => Effect.Effect<Success, Error, Needs>;
+  /** Runs app code that upkeep starts against the store's storage ceiling, when it has one. */
+  readonly measured?: CeilingGuard;
+  readonly opened: OpenedActor;
+  readonly read: Upkeep<Failure>["exclusive"];
+  readonly send: DeliveryBatch<Failure>;
+}
+interface Kept<Failure> {
+  /**
+   * When the oldest job activity executing now in this session started, if one is. A host keeps such an actor open:
+   * closing it would interrupt the activity, which then runs again on the next session.
+   */
+  readonly busySince: Effect.Effect<Option.Option<number>>;
+  readonly committed: Effect.Effect<void>;
+  readonly drain: Effect.Effect<boolean, Failure | SqlError.SqlError>;
+  readonly jobs: JobStore;
+  readonly kick: Effect.Effect<void>;
+  /**
+   * When the actor next has work: now while a message waits or a job has something to run, else its soonest timer,
+   * clock wait or job result round. A job parked on a signal or a clock leaves it idle, so a host may close it.
+   */
+  readonly nextDue: Effect.Effect<Option.Option<number>, SqlError.SqlError>;
+}
+type Start = <Failure>(upkeep: Upkeep<Failure>) => Effect.Effect<Kept<Failure>, never, Scope.Scope>;
+declare const ActorUpkeep_base: Context.ServiceClass<ActorUpkeep, "@akterjs/effect/host/upkeep/actor-upkeep.service/ActorUpkeep", {
+  readonly keep: <Success, Failure>(effect: Effect.Effect<Success, Failure>, what: string) => Effect.Effect<void>;
+  readonly locateJobs: JobEngine["Service"]["bind"];
+  readonly retainedJobs: JobEngine["Service"]["retained"];
+  readonly start: Start;
+}> & {
+  readonly make: Effect.Effect<{
+    readonly keep: <Success, Failure>(effect: Effect.Effect<Success, Failure>, what: string) => Effect.Effect<void>;
+    readonly locateJobs: JobEngine["Service"]["bind"];
+    readonly retainedJobs: JobEngine["Service"]["retained"];
+    readonly start: Start;
+  }, never, JobEngine | JobResults | OutboxRunner | TimerRunner>;
+};
+export declare class ActorUpkeep extends ActorUpkeep_base {
+  static readonly refusedTimerRetry: Context.Reference<Duration.Duration>;
+  static readonly sequentialDeliveries: <Failure, Needs>(send: (delivery: Delivery) => Effect.Effect<unknown, Failure, Needs>) => ((deliveries: readonly Delivery[]) => Effect.Effect<readonly import("effect/Result").Result<void, Failure>[], never, Needs>);
+  static readonly layer: Layer.Layer<ActorUpkeep, never, never>;
+}
+export type { Kept, Upkeep };

package/dist/host/upkeep/actor-upkeep.service.mjs

@@ -0,0 +1,218 @@
+import { pendingThrough } from "../outbox/actor-outbox.sql.mjs";
+import { OutboxRunner } from "../outbox/outbox-runner.service.mjs";
+import { TimerRunner } from "../timer/timer-runner.service.mjs";
+import { JobEngine } from "../job/job-engine.adapter.mjs";
+import { JobResults } from "../job/job-results.service.mjs";
+import { dueWork } from "./actor-due.sql.mjs";
+import { ExecutionAuthority, UpkeepGate } from "./execution-authority.pure.mjs";
+import { Array, Clock, Context, Deferred, Duration, Effect, Latch, Layer, Option, Queue, Ref, Schedule, Semaphore } from "effect";
+// src/host/upkeep/actor-upkeep.service.ts
+const pendingSignal = 1;
+const oneDelivery = 1;
+const noWait = 0;
+const backoff = Schedule.min([Schedule.exponential("100 millis"), Schedule.spaced("30 seconds")]);
+const retryLimit = 10;
+const retried = (effect, what) => effect.pipe(Effect.tapError((failure) => Effect.logWarning(`${what} failed and will be retried`, failure)), Effect.retry({
+	schedule: backoff,
+	times: retryLimit
+}), Effect.matchEffect({
+	onFailure: (failure) => Effect.logError(`${what} failed ${retryLimit} retries and waits for the next command or restart`, failure),
+	onSuccess: () => Effect.void
+}));
+const delivering = (outbox, { key, opened }, { deliveries, delivering: lock, gate }) => {
+	const deliverAll = retried(lock.withPermits(oneDelivery)(outbox.deliver).pipe(Effect.tap((delivered) => {
+		if (Array.isReadonlyArrayNonEmpty(delivered)) return Queue.offer(deliveries, true);
+		return Effect.void;
+	})), `${opened.actor.name}/${key} delivery`);
+	const held = Effect.andThen(gate.await, deliverAll);
+	return Effect.forever(Effect.andThen(Queue.take(deliveries), held));
+};
+const firing = ({ timers }, upkeep, signals) => {
+	const { exclusive, key, opened } = upkeep;
+	const untilDue = (due) => Effect.flatMap(Clock.currentTimeMillis, (now) => {
+		const sleep = Effect.sleep(Duration.millis(Math.max(due - now, noWait)));
+		return Effect.raceFirst(sleep, Queue.take(signals.wakes));
+	});
+	const fireWhenDue = Effect.gen(function* fireWhenDue() {
+		const next = yield* Ref.get(signals.soonest);
+		yield* Option.match(next, {
+			onNone: () => Queue.take(signals.wakes),
+			onSome: untilDue
+		});
+		const [now, current] = yield* Effect.all([Clock.currentTimeMillis, Ref.get(signals.soonest)]);
+		if (!Option.exists(current, (due) => due <= now)) return;
+		yield* signals.gate.await;
+		yield* exclusive(timers.fireDue(upkeep));
+		yield* Queue.offer(signals.deliveries, true);
+		yield* Queue.offer(signals.starts, true);
+		yield* Effect.flatMap(timers.nextDue(opened), (due) => Ref.set(signals.soonest, due));
+	});
+	return Effect.forever(retried(fireWhenDue, `${opened.actor.name}/${key} timers`));
+};
+/** If a stalled run can't even be recorded, it is retried from memory after the first round's gap. */
+const unrecordedRetry = "5 minutes";
+const jobStore = ({ results }, { exclusive, key, lock, measured, opened }, { authority, kick, scope }) => {
+	const guard = (effect) => authority(exclusive(effect));
+	const later = Effect.andThen(Effect.sleep(unrecordedRetry), kick);
+	const unrecorded = (cause) => Effect.andThen(Effect.logError("a stalled job could not be recorded, so it is retried from memory", cause), Effect.forkIn(later, scope));
+	return {
+		authority,
+		exclusive: (effect) => authority(lock(effect)),
+		finish: (finished) => Effect.andThen(results.settle({
+			...finished,
+			key,
+			measured,
+			opened
+		}, guard), kick),
+		id: opened.filename,
+		stalled: (stalled) => Effect.matchCauseEffect(results.stall({
+			...stalled,
+			key,
+			opened
+		}, guard), {
+			onFailure: unrecorded,
+			onSuccess: () => kick
+		}),
+		withSql: (use) => use(opened.sql)
+	};
+};
+const starting = ({ jobs }, store, { gate, starts }) => {
+	const held = Effect.andThen(gate.await, jobs.start(store));
+	return Effect.forever(Effect.andThen(Queue.take(starts), held));
+};
+const drainOnce = ({ jobs, timers }, upkeep, { gate, lock, outbox, store }) => Effect.gen(function* drainPass() {
+	if (!Latch.isOpen(gate)) return false;
+	const fired = yield* upkeep.exclusive(timers.fireDue(upkeep));
+	const ran = yield* jobs.drain(store);
+	const delivered = yield* lock.withPermits(oneDelivery)(Effect.tap(outbox.deliver, () => outbox.flush));
+	return ran || fired.length + delivered.length > noWait;
+});
+const offered = (signals) => Effect.forEach(signals, (signal) => Queue.offer(signal, true), { discard: true });
+/** Reads what is due, counting the session's parked jobs as waiting (`dueWork`). */
+const dueOf = (opened, parked) => Effect.flatMap(parked, (jobs) => dueWork({
+	parked: jobs,
+	sql: opened.sql
+}));
+/**
+* After a write, reads what is due in one statement: the timer loop gets the soonest timer, so it reads none itself on
+* a wake, and the job runner wakes only while a job has something to run. Delivery always wakes; it reads nothing
+* unless a message was committed past what it delivered. If the read fails, the timer loop is told a timer may be due
+* now, so it fires and reads the next one with its own retries.
+*/
+const kicked = (due, signals) => Effect.matchEffect(due, {
+	onFailure: () => Effect.andThen(Effect.flatMap(Clock.currentTimeMillis, (now) => Ref.set(signals.soonest, Option.some(now))), offered([
+		signals.deliveries,
+		signals.starts,
+		signals.wakes
+	])),
+	onSuccess: ({ jobs, timer }) => Effect.andThen(Ref.set(signals.soonest, timer), offered([
+		signals.deliveries,
+		signals.wakes,
+		...Array.filter([signals.starts], () => jobs)
+	]))
+});
+const dueSoonest = Effect.fnUntraced(function* nextDue(due) {
+	const now = yield* Clock.currentTimeMillis;
+	const { jobs, messages, timer } = yield* due;
+	if (!jobs && !messages) return timer;
+	return Option.some(Math.min(now, Option.getOrElse(timer, () => now)));
+});
+const committedOutbox = Effect.fnUntraced(function* committedOutbox({ outbox }, upkeep, signals) {
+	const initial = yield* Effect.orDie(upkeep.exclusive(pendingThrough(upkeep.opened.sql)));
+	const through = yield* Ref.make(initial);
+	const session = yield* outbox.open({
+		...upkeep,
+		committed: Ref.get(through)
+	});
+	return {
+		committed: Effect.orDie(Effect.flatMap(pendingThrough(upkeep.opened.sql), (seq) => Ref.set(through, seq))).pipe(Effect.andThen(Queue.offer(signals.deliveries, true)), Effect.asVoid),
+		session
+	};
+});
+const attachedJobs = (runners, upkeep, guards) => Effect.tap(Effect.map(Effect.scope, (scope) => jobStore(runners, upkeep, {
+	...guards,
+	scope
+})), (jobs) => Effect.addFinalizer(() => runners.jobs.detach(jobs)));
+/**
+* The session's job store and its kick: the kick reads the store's parked jobs with what is due, and the store kicks
+* after each result it stores, so the kick waits for the store it reads.
+*/
+const kickedJobs = Effect.fnUntraced(function* kickedJobs(runners, upkeep, { authority, signals }) {
+	const store = yield* Deferred.make();
+	const due = dueOf(upkeep.opened, Effect.flatMap(Deferred.await(store), runners.jobs.parked));
+	const kick = kicked(due, signals);
+	const jobs = yield* attachedJobs(runners, upkeep, {
+		authority,
+		kick
+	});
+	yield* Deferred.succeed(store, jobs);
+	return {
+		due,
+		jobs,
+		kick
+	};
+});
+const startWith = (runners) => Effect.fnUntraced(function* start(upkeep) {
+	const authority = yield* ExecutionAuthority;
+	const bound = {
+		...upkeep,
+		send: (deliveries) => authority(upkeep.send(deliveries))
+	};
+	const signals = {
+		deliveries: yield* Queue.sliding(pendingSignal),
+		delivering: yield* Semaphore.make(oneDelivery),
+		gate: yield* UpkeepGate,
+		soonest: yield* Ref.make(Option.none()),
+		starts: yield* Queue.sliding(pendingSignal),
+		wakes: yield* Queue.sliding(pendingSignal)
+	};
+	const { due, jobs, kick } = yield* kickedJobs(runners, bound, {
+		authority,
+		signals
+	});
+	const outbox = yield* committedOutbox(runners, bound, signals);
+	const work = [
+		authority(delivering(outbox.session, bound, signals)),
+		authority(firing(runners, bound, signals)),
+		authority(starting(runners, jobs, signals))
+	];
+	yield* Effect.forEach(work, (effect) => Effect.forkScoped(effect), { discard: true });
+	yield* kick;
+	return {
+		busySince: runners.jobs.busySince(jobs),
+		committed: authority(outbox.committed),
+		drain: authority(drainOnce(runners, bound, {
+			gate: signals.gate,
+			lock: signals.delivering,
+			outbox: outbox.session,
+			store: jobs
+		})),
+		jobs,
+		kick: authority(kick),
+		nextDue: dueSoonest(due)
+	};
+});
+var ActorUpkeep = class extends Context.Service()("@akterjs/effect/host/upkeep/actor-upkeep.service/ActorUpkeep", { make: Effect.gen(function* makeActorUpkeep() {
+	const runners = {
+		jobs: yield* JobEngine,
+		outbox: yield* OutboxRunner,
+		results: yield* JobResults,
+		timers: yield* TimerRunner
+	};
+	return {
+		keep: retried,
+		locateJobs: runners.jobs.bind,
+		retainedJobs: runners.jobs.retained,
+		start: startWith(runners)
+	};
+}) }) {
+	static refusedTimerRetry = TimerRunner.refusedRetry;
+	static sequentialDeliveries = OutboxRunner.sequentialDeliveries;
+	static layer = Layer.effect(this, this.make).pipe(Layer.provide([
+		JobEngine.layerShared,
+		JobResults.layer,
+		OutboxRunner.layer,
+		TimerRunner.layer
+	]));
+};
+export { ActorUpkeep };

package/dist/host/upkeep/execution-authority.pure.d.mts

@@ -0,0 +1,19 @@
+import { StorageLimitError } from "../../contract/client/storage-limit.errors.mjs";
+import { Context, Effect, Latch } from "effect";
+import { SqlError } from "effect/sql";
+type ExecutionGuard = <Value, Failure, Needs>(effect: Effect.Effect<Value, Failure, Needs>) => Effect.Effect<Value, Failure, Needs>;
+/**
+ * Runs one write of app code that upkeep starts, such as a timer's command, against the store's storage ceiling: past
+ * it the write stays only if the actor's database didn't grow, and one that grew is rolled back and refused with the
+ * ceiling's StorageLimitError. Measuring is SQL of its own, which can fail. Akter Cloud supplies it; the local engine
+ * has no ceiling.
+ */
+type CeilingGuard = <Value, Failure, Needs>(effect: Effect.Effect<Value, Failure, Needs>) => Effect.Effect<Value, Failure | SqlError.SqlError | StorageLimitError, Needs>;
+declare const ExecutionAuthority: Context.Reference<ExecutionGuard>;
+/**
+ * Whether an actor's upkeep may act: fire its due timers, deliver its outbox and run its jobs. A quiet environment,
+ * such as a branch that was not promoted yet, closes it. Its work is held, not dropped: it waits at the gate and runs
+ * once the gate opens. Open by default, so an engine that never closes it acts as before.
+ */
+declare const UpkeepGate: Context.Reference<Latch.Latch>;
+export { type CeilingGuard, ExecutionAuthority, type ExecutionGuard, UpkeepGate };

package/dist/host/upkeep/execution-authority.pure.mjs

@@ -0,0 +1,10 @@
+import { Context, Latch, identity } from "effect";
+// src/host/upkeep/execution-authority.pure.ts
+const ExecutionAuthority = Context.Reference("@akterjs/effect/host/upkeep/execution-authority.pure/ExecutionAuthority", { defaultValue: () => identity });
+/**
+* Whether an actor's upkeep may act: fire its due timers, deliver its outbox and run its jobs. A quiet environment,
+* such as a branch that was not promoted yet, closes it. Its work is held, not dropped: it waits at the gate and runs
+* once the gate opens. Open by default, so an engine that never closes it acts as before.
+*/
+const UpkeepGate = Context.Reference("@akterjs/effect/host/upkeep/execution-authority.pure/UpkeepGate", { defaultValue: () => Latch.makeUnsafe(true) });
+export { ExecutionAuthority, UpkeepGate };

package/dist/runtime/akter-local.layer.d.mts

@@ -0,0 +1,28 @@
+import { localEngine } from "./local-engine.layer.mjs";
+import { offlineEnvironments } from "./local-environments.layer.mjs";
+import { LocalMigration, StoreMigration } from "../serve/store/store-migrations.service.mjs";
+import { jobs } from "./local-job-runtime.layer.mjs";
+import { localClient } from "../serve/rpc/in-process-client.layer.mjs";
+import { Duration, Layer } from "effect";
+import { WorkflowEngine } from "effect/workflow";
+interface LocalServing {
+  /** The data directory, `.akter` for `akter dev`. */
+  readonly directory: string;
+  /**
+   * Serve this environment of the data directory, such as a branch to call before promoting it, instead of the one
+   * promoted to serve. It stays quiet until it is promoted.
+   */
+  readonly environment?: string | undefined;
+}
+type LocalServices = Layer.Success<ReturnType<typeof localEngine>> | WorkflowEngine.WorkflowEngine;
+/**
+ * The local engine on a data directory. It serves the directory's serving environment, the directory itself until a
+ * branch is promoted, and switches when a promote makes another serve; `LocalEnvironments` snapshots, branches and
+ * promotes them.
+ */
+declare const local: (target: string | LocalServing) => Layer.Layer<LocalServices>;
+/** A data directory's environments and snapshots without an engine, as the CLI reads and changes them. */
+declare const environments: (directory: string) => Layer.Layer<Layer.Success<ReturnType<typeof offlineEnvironments>>>;
+declare const historyRetention: (retention: Duration.Input) => Layer.Layer<never>;
+declare const migrate: (migration: LocalMigration) => StoreMigration;
+export { environments, historyRetention, jobs, local, localClient, migrate };

package/dist/runtime/akter-local.layer.mjs

@@ -0,0 +1,24 @@
+import { localEngine } from "./local-engine.layer.mjs";
+import { ActorHost } from "../serve/engine/actor-host.service.mjs";
+import { offlineEnvironments } from "./local-environments.layer.mjs";
+import { withJobs } from "../serve/engine/job-runtime.layer.mjs";
+import { migrateStore } from "../serve/store/store-migrations.layer.mjs";
+import { jobs } from "./local-job-runtime.layer.mjs";
+import { localClient } from "../serve/rpc/in-process-client.layer.mjs";
+import { Duration, Layer, Predicate, Stream } from "effect";
+import { layer } from "@effect/platform-node/NodeServices";
+// src/runtime/akter-local.layer.ts
+/**
+* The local engine on a data directory. It serves the directory's serving environment, the directory itself until a
+* branch is promoted, and switches when a promote makes another serve; `LocalEnvironments` snapshots, branches and
+* promotes them.
+*/
+const local = (target) => {
+	if (Predicate.isString(target)) return local({ directory: target });
+	return localEngine(target).pipe(withJobs, Layer.provide(layer));
+};
+/** A data directory's environments and snapshots without an engine, as the CLI reads and changes them. */
+const environments = (directory) => offlineEnvironments(directory).pipe(Layer.provide(layer));
+const historyRetention = (retention) => Layer.succeed(ActorHost.historyRetention, Duration.fromInputUnsafe(retention));
+const migrate = (migration) => Stream.provide(migrateStore(migration), layer);
+export { environments, historyRetention, jobs, local, localClient, migrate };