@akterjs/effect 0.0.0-stage → 0.1.0

package/dist/host/job/job-results.service.mjs

@@ -0,0 +1,63 @@
+import { Caller, actorKind } from "../../contract/caller/caller.schema.mjs";
+import { jsonCodec } from "../../contract/json-codec.pure.mjs";
+import { CommandRunner } from "../command/command-runner.service.mjs";
+import { resultCommandId } from "../command/command-id-reuse.pure.mjs";
+import { markUndelivered, readEntry, saveResult } from "./job-journal.sql.mjs";
+import { settling, stalling } from "./undelivered-result.pure.mjs";
+import { Context, Effect, Layer, Option, Schema, String, identity } from "effect";
+import { SqlError } from "effect/sql";
+// src/host/job/job-results.service.ts
+/** A result command's journaled exit, when its handler failed or died. */
+const failedExit = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.TaggedStruct("Failure", { cause: Schema.Unknown })));
+/** The job's result is kept and the job closes, but a failed handler's state change is lost, so say why. */
+const handlerFailed = (delivering) => (failed) => Effect.forEach(Option.toArray(failed), (cause) => Effect.annotateLogs(Effect.logError("a job's result handler failed, so its state change was not applied", cause), { ...delivering }), { discard: true });
+const delivering = (runner) => Effect.fn("JobResults.deliver")(function* deliver({ executionId, job, key, measured = identity, opened, result }) {
+	const actor = opened.actor.name;
+	const prefix = `${actor}/`;
+	if (!String.startsWith(prefix)(job)) return yield* Effect.die(`${job} is not a job of ${actor}`);
+	const principal = yield* Effect.orDie(Schema.encodeEffect(jsonCodec(Caller))({
+		kind: actorKind,
+		principal: {
+			actor,
+			id: `${actor}/${key}`,
+			key
+		}
+	}));
+	const command = runner.result({
+		opened,
+		request: {
+			commandId: resultCommandId(executionId),
+			job: String.slice(prefix.length)(job),
+			key,
+			payload: result,
+			principal
+		}
+	}).pipe(Effect.map((reply) => failedExit(reply).pipe(Option.map(({ cause }) => cause))), Effect.catchIf((failure) => !SqlError.isSqlError(failure), (failure) => Effect.succeedSome(failure)), Effect.flatMap(handlerFailed({
+		actor,
+		executionId,
+		job,
+		key
+	})));
+	return yield* opened.sql.withTransaction(Effect.andThen(saveResult({
+		executionId,
+		sql: opened.sql,
+		value: result
+	}), measured(command)));
+});
+var JobResults = class extends Context.Service()("@akterjs/effect/host/job/job-results.service/JobResults", { make: Effect.gen(function* makeJobResults() {
+	const runner = yield* CommandRunner;
+	const deliver = delivering(runner);
+	const delivery = {
+		deliver,
+		mark: markUndelivered,
+		read: readEntry
+	};
+	return {
+		deliver,
+		settle: settling(delivery),
+		stall: stalling(delivery)
+	};
+}) }) {
+	static layer = Layer.effect(this, this.make).pipe(Layer.provide(CommandRunner.layer));
+};
+export { JobResults };

package/dist/host/job/job-runs.pure.d.mts

@@ -0,0 +1,103 @@
+import { ExecutionGuard } from "../upkeep/execution-authority.pure.mjs";
+import { Cause, Deferred, Effect, Exit, Fiber, FiberMap, MutableHashMap, Option, Scope } from "effect";
+import { Workflow, WorkflowEngine } from "effect/workflow";
+import { SqlClient } from "effect/sql";
+type Execute = Parameters<WorkflowEngine.Encoded["register"]> extends readonly [Workflow.Any, infer Run] ? Run : never;
+type Payload = Parameters<Execute> extends readonly [infer Input, string] ? Input : never;
+type WakeMode = "explicit" | "automatic";
+type RunResult = Workflow.Result<unknown, unknown>;
+type RunExit = Exit.Exit<RunResult>;
+type Instance = WorkflowEngine.WorkflowInstance["Service"];
+interface FinishedJob {
+  readonly executionId: string;
+  readonly job: string;
+  readonly result: string;
+}
+/** A job's run that ended with no result stored while its store was still attached, and why. */
+interface StalledJob {
+  readonly cause: Cause.Cause<unknown>;
+  readonly executionId: string;
+  readonly job: string;
+}
+interface JobStore {
+  readonly id: string;
+  readonly authority: ExecutionGuard;
+  readonly exclusive: <Success, Failure, Needs>(effect: Effect.Effect<Success, Failure, Needs>) => Effect.Effect<Success, Failure, Needs>;
+  readonly finish: (finished: FinishedJob) => Effect.Effect<void>;
+  /** Records a stalled run and schedules its next round; the engine has already forgotten the run. */
+  readonly stalled: (stalled: StalledJob) => Effect.Effect<void>;
+  readonly withSql: <Success, Failure, Needs>(use: (sql: SqlClient.SqlClient) => Effect.Effect<Success, Failure, Needs>) => Effect.Effect<Success, Failure, Needs>;
+}
+/** A job whose run is suspended now, and the journal entries it waits on (`deferred/<name>`). */
+interface Parked {
+  readonly id: string;
+  readonly waits: readonly string[];
+}
+interface Registered {
+  readonly execute: Execute;
+  readonly scope: Scope.Scope;
+  readonly workflow: Workflow.Any;
+}
+interface Execution {
+  /** When each activity of this run executing now started: while any is, its actor shouldn't close. */
+  readonly activities: number[];
+  readonly clocks: Set<string>;
+  readonly done: Deferred.Deferred<void>;
+  readonly executionId: string;
+  fiber: Option.Option<Fiber.Fiber<RunResult>>;
+  instance: Instance;
+  interrupted: boolean;
+  interruptedUnsafe: boolean;
+  readonly payload: Payload;
+  rerun: Option.Option<WakeMode>;
+  readonly scope: Scope.Closeable;
+  readonly store: JobStore;
+  /** Deferreds the current run read and found no result for, so a signal stored later has to wake it. */
+  readonly waiting: Set<string>;
+  readonly workflow: Workflow.Any;
+}
+interface Runs {
+  readonly clocks: FiberMap.FiberMap<string>;
+  readonly deferreds: WorkflowEngine.DeferredState;
+  readonly detached: WeakSet<JobStore>;
+  readonly executions: MutableHashMap.MutableHashMap<string, Execution>;
+  readonly owned: Map<JobStore, Set<Execution>>;
+  readonly record: (execution: Execution, exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void>;
+  readonly registered: MutableHashMap.MutableHashMap<string, Registered>;
+  readonly scope: Scope.Scope;
+  readonly workflowEngine: Deferred.Deferred<WorkflowEngine.WorkflowEngine["Service"]>;
+}
+interface Waking {
+  readonly executionId: string;
+  readonly mode: WakeMode;
+  readonly runs: Runs;
+}
+interface Starting {
+  readonly executionId: string;
+  readonly payload: Payload;
+  readonly runs: Runs;
+  readonly store: JobStore;
+  readonly workflow: Workflow.Any;
+}
+declare const nameOf: ({ _tag: name }: Workflow.Any) => string;
+declare const lastExit: (execution: Execution) => Option.Option<RunExit>;
+declare const resume: (waking: Waking) => Effect.Effect<void>;
+declare const startExecution: ({ executionId, payload, runs, store, workflow }: Starting) => Effect.Effect<void>;
+declare const detachStore: ({ runs, store }: {
+  readonly runs: Runs;
+  readonly store: JobStore;
+}) => Effect.Effect<void>;
+interface Clocking {
+  readonly executionId: string;
+  readonly name: string;
+  readonly runs: Runs;
+}
+declare const trackedClock: ({ executionId, name, runs }: Clocking) => Effect.Effect<string>;
+/**
+ * The journal entries a run waits on, when it is suspended now with no rerun asked for: a signal or a clock wakes it,
+ * so nothing is due for it until one of those entries is stored.
+ */
+declare const parkedOn: (execution: Execution) => Option.Option<Parked["waits"]>;
+declare const awaitRun: (execution: Execution) => Effect.Effect<RunResult>;
+declare const settled: (execution: Execution) => Effect.Effect<boolean>;
+export { type Execute, type Execution, type FinishedJob, type JobStore, type Parked, type Payload, type Registered, type RunResult, type Runs, type StalledJob, type WakeMode, awaitRun, detachStore, lastExit, nameOf, parkedOn, resume, settled, startExecution, trackedClock };

package/dist/host/job/job-runs.pure.mjs

@@ -0,0 +1,193 @@
+import { Array, Cause, Context, Deferred, Effect, Exit, Fiber, FiberMap, MutableHashMap, Option, Predicate, Scope } from "effect";
+import { Workflow, WorkflowEngine } from "effect/workflow";
+// src/host/job/job-runs.pure.ts
+const noneLeft = 0;
+const nameOf = ({ _tag: name }) => name;
+const isSuspended = (result) => Predicate.isTagged(result, "Suspended");
+const isUnwakeable = (result, mode) => Predicate.isTagged(result, "Complete") || mode === "automatic" && result.failed === true;
+const resultOf = (exit) => Exit.getSuccess(exit);
+const lastExit = (execution) => Option.flatMap(execution.fiber, (fiber) => Option.fromNullishOr(fiber.pollUnsafe()));
+const runningFiber = (execution) => Option.filter(execution.fiber, (fiber) => Predicate.isUndefined(fiber.pollUnsafe()));
+const suspendsOnFailure = (instance, exit) => Context.get(instance.workflow.annotations, Workflow.SuspendOnFailure) && Exit.isFailure(exit);
+const interruptsRun = (execution, instance, exit) => execution.interrupted && (execution.interruptedUnsafe || instance.suspended || instance.abandoned || suspendsOnFailure(instance, exit));
+const interruptOnExit = (execution, instance) => (exit) => {
+	if (!interruptsRun(execution, instance, exit)) return Effect.void;
+	instance.interrupted = true;
+	instance.suspended = false;
+	return Effect.withFiber((fiber) => Effect.interruptible(Fiber.interrupt(fiber)));
+};
+const recordResult = ({ execution, runs }) => (result) => {
+	if (Predicate.isTagged(result, "Suspended")) return Effect.void;
+	return runs.record(execution, result.exit);
+};
+const track = (runs, execution) => {
+	const mine = runs.owned.get(execution.store) ?? /* @__PURE__ */ new Set();
+	mine.add(execution);
+	runs.owned.set(execution.store, mine);
+	MutableHashMap.set(runs.executions, execution.executionId, execution);
+};
+const forget = ({ execution, runs }) => {
+	const mine = runs.owned.get(execution.store);
+	mine?.delete(execution);
+	if (mine?.size === noneLeft) runs.owned.delete(execution.store);
+	if (Option.contains(MutableHashMap.get(runs.executions, execution.executionId), execution)) MutableHashMap.remove(runs.executions, execution.executionId);
+};
+/**
+* A run that died with no result while its store is still attached, such as a defect recording its result, is
+* stalled: the engine forgets it so it can start again, and the store records it and schedules its next round. A job's
+* own defects never get here; they come back to the actor as its failed result.
+*/
+const stalledRun = ({ execution, runs }, exit) => Effect.suspend(() => {
+	if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) || runs.detached.has(execution.store)) return Effect.void;
+	forget({
+		execution,
+		runs
+	});
+	return execution.store.stalled({
+		cause: exit.cause,
+		executionId: execution.executionId,
+		job: nameOf(execution.workflow)
+	});
+});
+const finished = ({ execution, runs }) => (exit) => {
+	const result = resultOf(exit);
+	if (Option.exists(result, isSuspended)) return Effect.void;
+	const closed = Scope.close(execution.scope, Exit.void);
+	if (Option.exists(result, (found) => Predicate.isTagged(found, "Complete"))) {
+		const done = Effect.andThen(closed, Deferred.done(execution.done, Exit.void));
+		return Effect.andThen(done, Effect.sync(() => {
+			forget({
+				execution,
+				runs
+			});
+		}));
+	}
+	return Effect.andThen(closed, stalledRun({
+		execution,
+		runs
+	}, exit));
+};
+const runOf = (running, { execute }, instance) => {
+	const { execution, runs } = running;
+	return execute(execution.payload, execution.executionId).pipe(execution.store.authority, Effect.onExit(interruptOnExit(execution, instance)), Workflow.intoResult, Effect.provideServiceEffect(WorkflowEngine.WorkflowEngine, Deferred.await(runs.workflowEngine)), (effect) => runs.deferreds.trackRun(instance, effect), Effect.tap(recordResult(running)), Effect.onExit(finished(running)));
+};
+const launch = (running, entry) => {
+	const { execution } = running;
+	const scope = Scope.forkUnsafe(execution.scope);
+	const instance = WorkflowEngine.WorkflowInstance.initial(execution.workflow, execution.executionId, { scope });
+	execution.instance = instance;
+	execution.waiting.clear();
+	return Effect.map(Effect.forkIn(runOf(running, entry, instance), entry.scope), (fiber) => {
+		execution.fiber = Option.some(fiber);
+	});
+};
+const startRun = (running) => running.execution.store.authority(Effect.suspend(() => Option.match(MutableHashMap.get(running.runs.registered, nameOf(running.execution.workflow)), {
+	onNone: () => Effect.void,
+	onSome: (entry) => launch(running, entry)
+})));
+const wakeIdle = (running, mode) => {
+	const done = Option.flatMap(lastExit(running.execution), resultOf);
+	if (Option.exists(done, (result) => isUnwakeable(result, mode))) return Effect.void;
+	return startRun(running);
+};
+const requestRerun = (execution, mode) => {
+	const requested = execution.rerun;
+	if (!Option.contains(requested, "explicit")) execution.rerun = Option.some(mode);
+	return Option.isNone(requested);
+};
+const takeRerun = (execution) => {
+	const mode = Option.getOrElse(execution.rerun, () => "automatic");
+	execution.rerun = Option.none();
+	return mode;
+};
+const resume = (waking) => Effect.suspend(() => Option.match(MutableHashMap.get(waking.runs.executions, waking.executionId), {
+	onNone: () => Effect.void,
+	onSome: (execution) => execution.store.authority(Option.match(runningFiber(execution), {
+		onNone: () => wakeIdle({
+			execution,
+			runs: waking.runs
+		}, waking.mode),
+		onSome: (fiber) => {
+			if (!requestRerun(execution, waking.mode)) return Effect.void;
+			const again = Effect.suspend(() => resume({
+				...waking,
+				mode: takeRerun(execution)
+			}));
+			const rerun = Effect.andThen(Fiber.await(fiber), again);
+			return Effect.asVoid(Effect.forkIn(rerun, waking.runs.scope));
+		}
+	}))
+}));
+const startExecution = ({ executionId, payload, runs, store, workflow }) => Effect.suspend(() => {
+	if (runs.detached.has(store) || MutableHashMap.has(runs.executions, executionId)) return Effect.void;
+	const execution = {
+		activities: [],
+		clocks: /* @__PURE__ */ new Set(),
+		done: Deferred.makeUnsafe(),
+		executionId,
+		fiber: Option.none(),
+		instance: WorkflowEngine.WorkflowInstance.initial(workflow, executionId),
+		interrupted: false,
+		interruptedUnsafe: false,
+		payload,
+		rerun: Option.none(),
+		scope: Scope.makeUnsafe(),
+		store,
+		waiting: /* @__PURE__ */ new Set(),
+		workflow
+	};
+	track(runs, execution);
+	return resume({
+		executionId,
+		mode: "explicit",
+		runs
+	});
+});
+const detachRun = ({ execution, runs }) => Effect.gen(function* detachingRun() {
+	forget({
+		execution,
+		runs
+	});
+	yield* Option.match(execution.fiber, {
+		onNone: () => Effect.void,
+		onSome: Fiber.interrupt
+	});
+	yield* Effect.forEach(execution.clocks, (clock) => FiberMap.remove(runs.clocks, clock), { discard: true });
+	yield* Scope.close(execution.scope, Exit.void);
+});
+const detachStore = ({ runs, store }) => Effect.suspend(() => {
+	runs.detached.add(store);
+	const mine = Array.fromIterable(runs.owned.get(store) ?? []);
+	return Effect.forEach(mine, (execution) => detachRun({
+		execution,
+		runs
+	}), { discard: true });
+});
+const trackedClock = ({ executionId, name, runs }) => Effect.sync(() => {
+	const key = `${executionId}/${name}`;
+	Option.map(MutableHashMap.get(runs.executions, executionId), (execution) => execution.clocks.add(key));
+	return key;
+});
+/**
+* The journal entries a run waits on, when it is suspended now with no rerun asked for: a signal or a clock wakes it,
+* so nothing is due for it until one of those entries is stored.
+*/
+const parkedOn = (execution) => lastExit(execution).pipe(Option.flatMap(resultOf), Option.filter((result) => isSuspended(result) && Option.isNone(execution.rerun)), Option.map(() => Array.map(Array.fromIterable(execution.waiting), (name) => `deferred/${name}`)));
+const awaitRun = (execution) => Effect.gen(function* awaiting() {
+	const { fiber, instance } = execution;
+	if (Option.isNone(fiber)) return yield* Effect.die(`job ${execution.executionId} has no handler registered yet`);
+	const exit = yield* Fiber.await(fiber.value);
+	if (Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause) && instance.suspended) return Workflow.Suspended.make({});
+	return yield* exit;
+});
+const settled = (execution) => Effect.suspend(() => {
+	const busy = Option.filter(execution.fiber, () => Option.isNone(lastExit(execution)) || Option.isSome(execution.rerun));
+	return Option.match(busy, {
+		onNone: () => Effect.succeed(false),
+		onSome: (fiber) => {
+			const again = Effect.andThen(Effect.yieldNow, settled(execution));
+			return Effect.as(Effect.andThen(Fiber.await(fiber), again), true);
+		}
+	});
+});
+export { awaitRun, detachStore, lastExit, nameOf, parkedOn, resume, settled, startExecution, trackedClock };

package/dist/host/job/undelivered-result.pure.d.mts

@@ -0,0 +1,49 @@
+import { StorageLimitError } from "../../contract/client/storage-limit.errors.mjs";
+import { OpenedActor } from "../actor/actor-database.service.mjs";
+import { CeilingGuard } from "../upkeep/execution-authority.pure.mjs";
+import { FinishedJob, StalledJob } from "./job-runs.pure.mjs";
+import { Effect, Option } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+interface Finishing extends FinishedJob {
+  readonly key: string;
+  /**
+   * Runs the result's command against the store's storage ceiling, or undefined where there is none. Required, so a
+   * caller can't drop the store's ceiling by leaving it out.
+   */
+  readonly measured: CeilingGuard | undefined;
+  readonly opened: OpenedActor;
+}
+/** Why storing a result failed: its SQL, or the storage ceiling refusing a result command that grew the database. */
+type Unstored = SqlError.SqlError | StorageLimitError;
+interface Stalling extends StalledJob {
+  readonly key: string;
+  readonly opened: OpenedActor;
+}
+/** Runs one delivery attempt under the actor's execution authority and its exclusive lock. */
+type Guard = <Success, Failure>(effect: Effect.Effect<Success, Failure>) => Effect.Effect<Success, Failure>;
+interface Entry {
+  readonly executionId: string;
+  readonly sql: SqlClient.SqlClient;
+}
+/** The delivery and the two journal statements it needs, from the job's SQL. */
+interface Delivery {
+  readonly deliver: (finishing: Finishing) => Effect.Effect<void, Unstored>;
+  readonly mark: (entry: Entry & {
+    readonly value: string;
+  }) => Effect.Effect<void, SqlError.SqlError>;
+  readonly read: (entry: Entry & {
+    readonly entry: string;
+  }) => Effect.Effect<Option.Option<string>, SqlError.SqlError>;
+}
+/**
+ * Delivers with a round of retries. A spent round returns, so the job's run ends and the engine forgets it; the
+ * journal keeps it open with its next round's due time.
+ */
+declare const settling: (delivery: Delivery) => ((finishing: Finishing, guard: Guard) => Effect.Effect<void>);
+/**
+ * A run that ended before its result was stored (a batch that failed under it, or a result it couldn't record) spends
+ * a round the same way: one more attempt, and the job is due again at its next round. The log carries the cause, so
+ * a bug shows as well as a full disk.
+ */
+declare const stalling: (delivery: Delivery) => (stalled: Stalling, guard: Guard) => Effect.Effect<void, SqlError.SqlError>;
+export { type Finishing, type Guard, type Stalling, type Unstored, settling, stalling };

package/dist/host/job/undelivered-result.pure.mjs

@@ -0,0 +1,147 @@
+import { StorageLimitError } from "../../contract/client/storage-limit.errors.mjs";
+import { Cause, Clock, Duration, Effect, Option, Ref, Schedule, Schema } from "effect";
+// src/host/job/undelivered-result.pure.ts
+/**
+* The visible state of a result the upkeep could not store yet (the job journal's 'undelivered' entry): the attempts
+* so far, the last error and when it failed. `retrying` is true while the upkeep retries it now; once a round of
+* retries is spent it is false, `rounds` counts the spent rounds and `next`, present only then, is when the next round
+* starts.
+*/
+const Undelivered = Schema.fromJsonString(Schema.Struct({
+	at: Schema.Int,
+	attempts: Schema.Int,
+	error: Schema.String,
+	next: Schema.optionalKey(Schema.Int),
+	retrying: Schema.Boolean,
+	rounds: Schema.Int
+}));
+/** One round: from 100 ms, doubling, capped at 30 seconds, for 10 retries (about 80 seconds in all). */
+const backoff = Schedule.min([Schedule.exponential("100 millis"), Schedule.spaced("30 seconds")]);
+const retryLimit = 10;
+/** Between rounds: 5 minutes after the first, doubling, capped at an hour. Rounds never stop. */
+const firstRoundGap = Duration.toMillis("5 minutes");
+const longestRoundGap = Duration.toMillis("1 hour");
+const doubling = 2;
+const oneMore = 1;
+const noMore = 0;
+const fresh = {
+	attempts: 0,
+	rounds: 0
+};
+const roundGap = (rounds) => Math.min(firstRoundGap * doubling ** (rounds - oneMore), longestRoundGap);
+/** The attempts and rounds an earlier run of this job already spent, read once, at its first failure. */
+const progressOf = ({ delivering, delivery, guard, progress, sql }) => Effect.flatMap(Ref.get(progress), Option.match({
+	onNone: () => guard(delivery.read({
+		entry: "undelivered",
+		executionId: delivering.executionId,
+		sql
+	})).pipe(Effect.flatMap(Option.match({
+		onNone: () => Effect.succeed(fresh),
+		onSome: (text) => Schema.decodeEffect(Undelivered)(text)
+	})), Effect.map(({ attempts, rounds }) => ({
+		attempts,
+		rounds
+	})), Effect.orElseSucceed(() => fresh), Effect.tap((found) => Ref.set(progress, Option.some(found)))),
+	onSome: Effect.succeed
+}));
+const unstoredText = (failure) => {
+	if (Schema.is(StorageLimitError)(failure)) return `the store's ${String(failure.dataBytes)} bytes reached its storage ceiling of ${String(failure.ceilingBytes)}`;
+	return failure.message;
+};
+const written = (tracking, entry) => Effect.flatMap(Effect.orDie(Schema.encodeEffect(Undelivered)(entry)), (value) => tracking.guard(tracking.delivery.mark({
+	executionId: tracking.delivering.executionId,
+	sql: tracking.sql,
+	value
+})));
+/** Each failed attempt is logged and written to the job's journal, best effort: the journal may be what fails. */
+const failedAttempt = (tracking) => (failure) => Effect.gen(function* failed() {
+	const before = yield* progressOf(tracking);
+	const attempts = before.attempts + oneMore;
+	const at = yield* Clock.currentTimeMillis;
+	yield* Ref.set(tracking.progress, Option.some({
+		...before,
+		attempts
+	}));
+	yield* Effect.annotateLogs(Effect.logWarning("a job's result could not be stored and will be retried", failure), {
+		...tracking.delivering,
+		attempts
+	});
+	yield* Effect.ignore(written(tracking, {
+		at,
+		attempts,
+		error: unstoredText(failure),
+		retrying: true,
+		rounds: before.rounds
+	}));
+});
+/**
+* A spent round leaves the job open and due again at `next`, so the upkeep wakes the actor then, with nobody calling
+* it. Operators see it as an error log and the `JobResults.gaveUp` span. If even this can't be written, it fails.
+*/
+const spentRound = (tracking, spent) => Effect.gen(function* givingUp() {
+	const before = yield* progressOf(tracking);
+	const attempts = before.attempts + spent.more;
+	const rounds = before.rounds + oneMore;
+	const at = yield* Clock.currentTimeMillis;
+	const next = at + roundGap(rounds);
+	yield* written(tracking, {
+		at,
+		attempts,
+		error: spent.error,
+		next,
+		retrying: false,
+		rounds
+	});
+	yield* Effect.annotateLogs(Effect.logError(spent.message, spent.logged), {
+		...tracking.delivering,
+		attempts,
+		next,
+		rounds
+	});
+}).pipe(Effect.withSpan("JobResults.gaveUp", { attributes: { ...tracking.delivering } }));
+const gaveUp = (tracking) => (failure) => spentRound(tracking, {
+	error: unstoredText(failure),
+	logged: failure,
+	message: "a job's result could not be stored after its retries, so the job stays open and is retried later",
+	more: noMore
+});
+/** A defect while delivering never retries and never dies silently: it goes to the log with the job and the actor. */
+const undeliverable = (delivering) => (cause) => {
+	if (Cause.hasInterruptsOnly(cause)) return Effect.void;
+	return Effect.annotateLogs(Effect.logError("a job's result could not be delivered, so the job stays open", cause), { ...delivering });
+};
+const tracked = (finishing, delivery, guard) => Effect.map(Ref.make(Option.none()), (progress) => ({
+	delivering: {
+		actor: finishing.opened.actor.name,
+		executionId: finishing.executionId,
+		job: finishing.job,
+		key: finishing.key
+	},
+	delivery,
+	guard,
+	progress,
+	sql: finishing.opened.sql
+}));
+/**
+* Delivers with a round of retries. A spent round returns, so the job's run ends and the engine forgets it; the
+* journal keeps it open with its next round's due time.
+*/
+const settling = (delivery) => (finishing, guard) => Effect.gen(function* settle() {
+	const tracking = yield* tracked(finishing, delivery, guard);
+	yield* guard(delivery.deliver(finishing)).pipe(Effect.tapError(failedAttempt(tracking)), Effect.retry({
+		schedule: backoff,
+		times: retryLimit
+	}), Effect.catch(gaveUp(tracking)), Effect.tapCause(undeliverable(tracking.delivering)), Effect.orDie);
+});
+/**
+* A run that ended before its result was stored (a batch that failed under it, or a result it couldn't record) spends
+* a round the same way: one more attempt, and the job is due again at its next round. The log carries the cause, so
+* a bug shows as well as a full disk.
+*/
+const stalling = (delivery) => (stalled, guard) => Effect.flatMap(tracked(stalled, delivery, guard), (tracking) => spentRound(tracking, {
+	error: Cause.pretty(stalled.cause),
+	logged: stalled.cause,
+	message: "a job's run ended before its result was stored, so the job stays open and is retried later",
+	more: oneMore
+}));
+export { settling, stalling };

package/dist/host/layout/actor-layout.sql.d.mts

@@ -0,0 +1,8 @@
+import { Effect, Option } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+type Sql<Value> = Effect.Effect<Value, SqlError.SqlError>;
+declare const createLayout: (sql: SqlClient.SqlClient) => Sql<void>;
+/** Adds to a store made by an earlier engine at this layout version what this engine's layout has since gained. */
+declare const upgradeLayout: (sql: SqlClient.SqlClient) => Sql<void>;
+declare const storedLayoutVersion: (sql: SqlClient.SqlClient) => Sql<Option.Option<number>>;
+export { createLayout, storedLayoutVersion, upgradeLayout };

package/dist/host/layout/actor-layout.sql.mjs

@@ -0,0 +1,33 @@
+import "./layout-version.pure.mjs";
+import { prepareReceipts } from "../blob/reference/blob-receipts.sql.mjs";
+import { prepareOpenJobs } from "../job/job-journal.sql.mjs";
+import { Array, Effect, Option } from "effect";
+// src/host/layout/actor-layout.sql.ts
+const layoutTables = [
+	"CREATE TABLE akter_meta (key TEXT PRIMARY KEY, value ANY NOT NULL) STRICT",
+	"CREATE TABLE akter_migrations (version INTEGER PRIMARY KEY, hash TEXT NOT NULL, applied_at INTEGER NOT NULL) STRICT",
+	"CREATE TABLE akter_state (id INTEGER PRIMARY KEY CHECK (id = 1), value TEXT NOT NULL) STRICT",
+	"CREATE TABLE akter_commands (seq INTEGER PRIMARY KEY, command_id TEXT NOT NULL UNIQUE, command TEXT NOT NULL, payload TEXT NOT NULL, principal TEXT NOT NULL, exit TEXT NOT NULL, ids TEXT NOT NULL, times TEXT NOT NULL, files TEXT NOT NULL DEFAULT '[]', at INTEGER NOT NULL) STRICT",
+	"CREATE TABLE akter_timers (id TEXT PRIMARY KEY, due_at INTEGER NOT NULL, command TEXT NOT NULL, payload TEXT NOT NULL, principal TEXT NOT NULL) STRICT",
+	"CREATE INDEX akter_timers_due ON akter_timers (due_at)",
+	"CREATE TABLE akter_outbox (seq INTEGER PRIMARY KEY AUTOINCREMENT, command_id TEXT NOT NULL UNIQUE, actor TEXT NOT NULL, key TEXT NOT NULL, member TEXT NOT NULL, payload TEXT NOT NULL) STRICT",
+	"CREATE TABLE akter_failed_deliveries (command_id TEXT PRIMARY KEY, actor TEXT NOT NULL, key TEXT NOT NULL, member TEXT NOT NULL, error TEXT NOT NULL, at INTEGER NOT NULL) STRICT",
+	"CREATE TABLE akter_workflow (execution_id TEXT NOT NULL, entry TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (execution_id, entry)) STRICT"
+];
+const createLayout = (sql) => Effect.gen(function* creatingLayout() {
+	yield* Effect.forEach(layoutTables, (statement) => sql.unsafe(statement), { discard: true });
+	yield* prepareReceipts(sql);
+	yield* prepareOpenJobs(sql);
+	yield* sql`INSERT INTO akter_meta (key, value) VALUES ('layout', ${3})`;
+});
+/** Adds to a store made by an earlier engine at this layout version what this engine's layout has since gained. */
+const upgradeLayout = (sql) => prepareOpenJobs(sql);
+const recordedVersion = (sql) => Effect.map(sql`SELECT value FROM akter_meta WHERE key = 'layout'`, (rows) => Option.match(Array.head(rows), {
+	onNone: () => 0,
+	onSome: (row) => row.value
+}));
+const storedLayoutVersion = (sql) => Effect.flatMap(sql`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'akter_meta'`, (tables) => Array.match(tables, {
+	onEmpty: () => Effect.succeedNone,
+	onNonEmpty: () => Effect.asSome(recordedVersion(sql))
+}));
+export { createLayout, storedLayoutVersion, upgradeLayout };

package/dist/host/layout/layout-version.errors.d.mts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+declare const LayoutVersionError_base: Schema.Class<LayoutVersionError, Schema.TaggedStruct<"LayoutVersionError", {
+  readonly actor: Schema.String;
+  readonly found: Schema.Int;
+  readonly supported: Schema.Int;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class LayoutVersionError extends LayoutVersionError_base {}
+export {};

package/dist/host/layout/layout-version.errors.mjs

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+// src/host/layout/layout-version.errors.ts
+var LayoutVersionError = class extends Schema.TaggedError()("LayoutVersionError", {
+	actor: Schema.String,
+	found: Schema.Int,
+	supported: Schema.Int
+}) {};
+export { LayoutVersionError };

package/dist/host/layout/layout-version.pure.d.mts

@@ -0,0 +1,10 @@
+import { LayoutVersionError } from "./layout-version.errors.mjs";
+import { Effect } from "effect";
+interface FoundLayout {
+  readonly actor: string;
+  readonly found: number;
+}
+declare const layoutVersion = 3;
+declare const missingLayout = 0;
+declare const checkLayoutVersion: ({ actor, found }: FoundLayout) => Effect.Effect<void, LayoutVersionError>;
+export { checkLayoutVersion, layoutVersion, missingLayout };

package/dist/host/layout/layout-version.pure.mjs

@@ -0,0 +1,14 @@
+import { LayoutVersionError } from "./layout-version.errors.mjs";
+import { Effect } from "effect";
+// src/host/layout/layout-version.pure.ts
+const layoutVersion = 3;
+const missingLayout = 0;
+const checkLayoutVersion = ({ actor, found }) => {
+	if (found === 3) return Effect.void;
+	return Effect.fail(LayoutVersionError.make({
+		actor,
+		found,
+		supported: 3
+	}));
+};
+export { checkLayoutVersion, layoutVersion, missingLayout };