@akterjs/effect 0.0.0-stage → 0.1.0

package/src/host/upkeep/actor-due.sql.ts

@@ -0,0 +1,71 @@
+import { Array as Arr, Effect, Option, Schema } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import type { Parked } from "#src/host/job/job-engine.adapter";
+
+/** 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>;
+}
+
+interface DueRow {
+  readonly jobs: number;
+  readonly messages: number;
+  readonly timer: number | null;
+}
+
+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: SqlClient.SqlClient,
+  { parked, waits }: { readonly parked: string; readonly waits: string },
+): Effect.Effect<readonly DueRow[], SqlError.SqlError> =>
+  sql<DueRow>`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: readonly Parked[]): Effect.Effect<{ readonly parked: string; readonly waits: string }> => {
+  const ids = Arr.map(parked, (job) => job.id);
+  const waits = Arr.flatMap(parked, ({ id, waits: entries }) => Arr.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,
+}: {
+  readonly parked: readonly Parked[];
+  readonly sql: SqlClient.SqlClient;
+}): Effect.Effect<DueWork, SqlError.SqlError> =>
+  Effect.gen(function* readDue() {
+    const lists = yield* listsOf(parked);
+    const rows = yield* dueRows(sql, lists);
+    const row = Arr.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 };
+
+export type { DueWork };

package/src/host/upkeep/actor-upkeep.service.ts

@@ -0,0 +1,404 @@
+import {
+  Array as Arr,
+  Clock,
+  Context,
+  Deferred,
+  Duration,
+  Effect,
+  Latch,
+  Layer,
+  Option,
+  Queue,
+  Ref,
+  Schedule,
+  Semaphore,
+} from "effect";
+import type { Cause, Scope } from "effect";
+import type { SqlError } from "effect/sql";
+
+import type { OpenedActor } from "#src/host/actor/actor-database.service";
+import { pendingThrough } from "#src/host/outbox/actor-outbox.sql";
+import { OutboxRunner } from "#src/host/outbox/outbox-runner.service";
+import type { Delivery, DeliveryBatch, DeliverySession } from "#src/host/outbox/outbox-runner.service";
+import { TimerRunner } from "#src/host/timer/timer-runner.service";
+import { JobEngine } from "#src/host/job/job-engine.adapter";
+import { JobResults } from "#src/host/job/job-results.service";
+import type { JobStore, Parked } from "#src/host/job/job-engine.adapter";
+import { dueWork } from "./actor-due.sql.js";
+import type { DueWork } from "./actor-due.sql.js";
+import { ExecutionAuthority, UpkeepGate } from "./execution-authority.pure.js";
+import type { CeilingGuard, ExecutionGuard } from "./execution-authority.pure.js";
+
+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 Runners {
+  readonly jobs: JobEngine["Service"];
+  readonly outbox: OutboxRunner["Service"];
+  readonly results: JobResults["Service"];
+  readonly timers: TimerRunner["Service"];
+}
+
+interface Signals {
+  readonly deliveries: Queue.Queue<boolean>;
+  readonly delivering: Semaphore.Semaphore;
+  readonly gate: Latch.Latch;
+  /** The soonest timer as the last kick or firing read it, so the timer loop doesn't read it again on each wake. */
+  readonly soonest: Ref.Ref<Option.Option<number>>;
+  readonly starts: Queue.Queue<boolean>;
+  readonly wakes: Queue.Queue<boolean>;
+}
+
+interface Draining<Failure> {
+  readonly gate: Latch.Latch;
+  readonly lock: Semaphore.Semaphore;
+  readonly outbox: DeliverySession<Failure>;
+  readonly store: JobStore;
+}
+
+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>;
+
+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 = <Success, Failure>(effect: Effect.Effect<Success, Failure>, what: string): Effect.Effect<void> =>
+  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 = <Failure>(
+  outbox: DeliverySession<Failure>,
+  { key, opened }: Upkeep<Failure>,
+  { deliveries, delivering: lock, gate }: Signals,
+): Effect.Effect<never> => {
+  const deliverAll = retried(
+    lock
+      .withPermits(oneDelivery)(outbox.deliver)
+      .pipe(
+        Effect.tap((delivered) => {
+          if (Arr.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 = <Failure>({ timers }: Runners, upkeep: Upkeep<Failure>, signals: Signals): Effect.Effect<never> => {
+  const { exclusive, key, opened } = upkeep;
+
+  const untilDue = (due: number): Effect.Effect<unknown> =>
+    Effect.flatMap(Clock.currentTimeMillis, (now) => {
+      const sleep = Effect.sleep(Duration.millis(Math.max(due - now, noWait)));
+
+      return Effect.raceFirst(sleep, Queue.take(signals.wakes));
+    });
+
+  // Fires only once the soonest timer is due; a wake that brings no due timer only moves the wait.
+  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));
+    // A timer's command can send messages and start jobs, like a client's, so it wakes both runners.
+    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`));
+};
+
+interface JobGuards {
+  readonly authority: ExecutionGuard;
+  readonly kick: Effect.Effect<void>;
+  readonly scope: Scope.Scope;
+}
+
+/** 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 = <Failure>(
+  { results }: Runners,
+  { exclusive, key, lock, measured, opened }: Upkeep<Failure>,
+  { authority, kick, scope }: JobGuards,
+): JobStore => {
+  const guard = <Success, Failed>(effect: Effect.Effect<Success, Failed>): Effect.Effect<Success, Failed> =>
+    authority(exclusive(effect));
+
+  const later = Effect.andThen(Effect.sleep(unrecordedRetry), kick);
+
+  const unrecorded = (cause: Cause.Cause<SqlError.SqlError>): Effect.Effect<void> =>
+    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 }: Runners, store: JobStore, { gate, starts }: Signals): Effect.Effect<never> => {
+  const held = Effect.andThen(gate.await, jobs.start(store));
+
+  return Effect.forever(Effect.andThen(Queue.take(starts), held));
+};
+
+const drainOnce = <Failure>(
+  { jobs, timers }: Runners,
+  upkeep: Upkeep<Failure>,
+  { gate, lock, outbox, store }: Draining<Failure>,
+): Effect.Effect<boolean, Failure | SqlError.SqlError> =>
+  Effect.gen(function* drainPass() {
+    // A closed gate holds the work, so a drain of a quiet actor finds nothing it may do.
+    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: readonly Queue.Queue<boolean>[]): Effect.Effect<void> =>
+  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: OpenedActor,
+  parked: Effect.Effect<readonly Parked[]>,
+): Effect.Effect<DueWork, SqlError.SqlError> =>
+  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: Effect.Effect<DueWork, SqlError.SqlError>, signals: Signals): Effect.Effect<void> =>
+  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, ...Arr.filter([signals.starts], () => jobs)]),
+      ),
+  });
+
+// What is due, in one statement: the soonest timer, or now while a message waits or a job has something to run.
+const dueSoonest = Effect.fnUntraced(function* nextDue(due: Effect.Effect<DueWork, SqlError.SqlError>) {
+  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<Failure>(
+  { outbox }: Runners,
+  upkeep: Upkeep<Failure>,
+  signals: 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) });
+
+  const committed = Effect.orDie(
+    Effect.flatMap(pendingThrough(upkeep.opened.sql), (seq) => Ref.set(through, seq)),
+  ).pipe(Effect.andThen(Queue.offer(signals.deliveries, true)), Effect.asVoid);
+
+  return { committed, session };
+});
+
+// Added before the session's work forks, so the detach runs after they stop and nothing restarts its jobs.
+const attachedJobs = <Failure>(
+  runners: Runners,
+  upkeep: Upkeep<Failure>,
+  guards: Omit<JobGuards, "scope">,
+): Effect.Effect<JobStore, never, Scope.Scope> =>
+  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<Failure>(
+  runners: Runners,
+  upkeep: Upkeep<Failure>,
+  { authority, signals }: { readonly authority: ExecutionGuard; readonly signals: Signals },
+) {
+  const store = yield* Deferred.make<JobStore>();
+  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: Runners): Start =>
+  Effect.fnUntraced(function* start<Failure>(upkeep: Upkeep<Failure>) {
+    const authority = yield* ExecutionAuthority;
+
+    const bound = {
+      ...upkeep,
+      send: (deliveries: readonly Delivery[]): ReturnType<DeliveryBatch<Failure>> => authority(upkeep.send(deliveries)),
+    };
+
+    const signals: Signals = {
+      deliveries: yield* Queue.sliding<boolean>(pendingSignal),
+      delivering: yield* Semaphore.make(oneDelivery),
+      gate: yield* UpkeepGate,
+      soonest: yield* Ref.make(Option.none<number>()),
+      starts: yield* Queue.sliding<boolean>(pendingSignal),
+      wakes: yield* Queue.sliding<boolean>(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),
+    };
+  });
+
+export class ActorUpkeep extends Context.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;
+  }
+>()("@akterjs/effect/host/upkeep/actor-upkeep.service/ActorUpkeep", {
+  make: Effect.gen(function* makeActorUpkeep() {
+    const runners: 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),
+    } as const;
+  }),
+}) {
+  public static readonly refusedTimerRetry = TimerRunner.refusedRetry;
+  public static readonly sequentialDeliveries = OutboxRunner.sequentialDeliveries;
+  public static readonly layer = Layer.effect(this, this.make).pipe(
+    Layer.provide([JobEngine.layerShared, JobResults.layer, OutboxRunner.layer, TimerRunner.layer]),
+  );
+}
+
+export type { Kept, Upkeep };

package/src/host/upkeep/execution-authority.pure.ts

@@ -0,0 +1,37 @@
+import { Context, identity, Latch } from "effect";
+import type { Effect } from "effect";
+import type { SqlError } from "effect/sql";
+
+import type { StorageLimitError } from "#src/contract/client/storage-limit.errors";
+
+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>;
+
+const ExecutionAuthority = Context.Reference<ExecutionGuard>(
+  "@akterjs/effect/host/upkeep/execution-authority.pure/ExecutionAuthority",
+  { defaultValue: (): ExecutionGuard => 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<Latch.Latch>("@akterjs/effect/host/upkeep/execution-authority.pure/UpkeepGate", {
+  defaultValue: (): Latch.Latch => Latch.makeUnsafe(true),
+});
+
+export { ExecutionAuthority, UpkeepGate };
+
+export type { CeilingGuard, ExecutionGuard };

package/src/runtime/akter-local.layer.ts

@@ -0,0 +1,49 @@
+import { layer as nodeServices } from "@effect/platform-node/NodeServices";
+import { Duration, Layer, Predicate, Stream } from "effect";
+import type { WorkflowEngine } from "effect/workflow";
+
+import { localEngine, offlineEnvironments } from "./local-engine.layer.js";
+import { ActorHost } from "#src/serve/engine/actor-host.service";
+import { withJobs } from "#src/serve/engine/job-runtime.layer";
+import { migrateStore } from "#src/serve/store/store-migrations.layer";
+import type { LocalMigration, StoreMigration } from "#src/serve/store/store-migrations.service";
+
+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.
+ */
+const local = (target: string | LocalServing): Layer.Layer<LocalServices> => {
+  if (Predicate.isString(target)) {
+    return local({ directory: target });
+  }
+
+  return localEngine(target).pipe(withJobs, Layer.provide(nodeServices));
+};
+
+/** A data directory's environments and snapshots without an engine, as the CLI reads and changes them. */
+const environments = (directory: string): Layer.Layer<Layer.Success<ReturnType<typeof offlineEnvironments>>> =>
+  offlineEnvironments(directory).pipe(Layer.provide(nodeServices));
+
+const historyRetention = (retention: Duration.Input): Layer.Layer<never> =>
+  Layer.succeed(ActorHost.historyRetention, Duration.fromInputUnsafe(retention));
+
+const migrate = (migration: LocalMigration): StoreMigration => Stream.provide(migrateStore(migration), nodeServices);
+
+export { environments, historyRetention, local, migrate };
+
+export { jobs } from "./local-job-runtime.layer.js";
+
+export { localClient } from "#src/serve/rpc/in-process-client.layer";