@akterjs/effect 0.0.0-stage → 0.1.0

package/src/serve/environment/promotion-notice.pure.ts

@@ -0,0 +1,63 @@
+import { Array as Arr, DateTime, Option } from "effect";
+
+/** The snapshot a branch came from, as the promote names it. */
+interface Origin {
+  readonly environment: string;
+  readonly id: string;
+  readonly name: string;
+  readonly takenAt: Option.Option<number>;
+}
+
+interface Promoting {
+  readonly environment: string;
+  /** The snapshot it was branched from, when it never served before. */
+  readonly origin: Option.Option<Origin>;
+  readonly previous: string;
+}
+
+const takenWhen = (takenAt: Option.Option<number>): string =>
+  Option.match(takenAt, {
+    onNone: () => "",
+    onSome: (millis) => `, taken at ${DateTime.formatIso(DateTime.makeUnsafe(millis))}`,
+  });
+
+const fromSnapshot = ({ environment }: Promoting, origin: Origin): string =>
+  `It holds ${origin.environment}'s data as of snapshot ${origin.name} (${origin.id}${takenWhen(origin.takenAt)}): writes made to ${origin.environment} after that snapshot are not in ${environment}.`;
+
+const resumed = (origin: Option.Option<Origin>): string =>
+  Option.match(origin, {
+    onNone: () => "Its held jobs resume from its journal, and its timers that came due fire now.",
+    onSome: () => "Its jobs resume from the snapshot's journal, and its timers that came due fire now.",
+  });
+
+/**
+ * What a promote leaves behind, said by the promote itself: the writes the newly serving environment doesn't hold,
+ * that its held work now runs, and that the environment it replaced is kept as it was.
+ */
+const promotionNotice = (promoting: Promoting): string => {
+  const { environment, origin, previous } = promoting;
+  const snapshotCatch = Option.map(origin, (found) => fromSnapshot(promoting, found));
+
+  const servedCatch = Option.liftPredicate(
+    `Writes ${previous} took while it served are not in ${environment}.`,
+    () => Option.isNone(origin) || Option.exists(origin, (found) => found.environment !== previous),
+  );
+
+  return Arr.join(
+    [
+      `${environment} now serves in place of ${previous}.`,
+      ...Option.toArray(snapshotCatch),
+      ...Option.toArray(servedCatch),
+      resumed(origin),
+      `${previous} is kept as it was, quiet, until you delete it or promote it again.`,
+    ],
+    " ",
+  );
+};
+
+/** What a promote of the environment that already serves answers when no promote ever made it serve. */
+const alreadyServing = (environment: string): string => `${environment} already serves; nothing changed.`;
+
+export { alreadyServing, promotionNotice };
+
+export type { Origin };

package/src/serve/environment/snapshot-operations.sql.ts

@@ -0,0 +1,210 @@
+import { Array as Arr, Clock, Duration, Effect, Option, Schedule } from "effect";
+import type { SqlError } from "effect/sql";
+
+import {
+  claimPending,
+  insertSnapshot,
+  liveSnapshot,
+  liveSnapshots,
+  nextSnapshotId,
+  retireSnapshot,
+  settleSnapshot,
+  snapshotById,
+  snapshotsFolder,
+} from "./environment-records.sql.js";
+import type { Outcome, SnapshotRow } from "./environment-records.sql.js";
+import { AlreadyExistsError } from "./environment-already-exists.errors.js";
+import { NotFoundError } from "./environment-not-found.errors.js";
+import { readyEnvironment, recordedEnvironment, snapshotOf, stored } from "./environment-store.sql.js";
+import type { Failure, Store } from "./environment-store.sql.js";
+import type { EnvironmentName, LocalSnapshot, SnapshotName } from "./local-environment.schema.js";
+
+interface Snapshotting {
+  /** The environment the snapshot is of; the serving one when missing. */
+  readonly environment?: EnvironmentName | undefined;
+  readonly name: SnapshotName;
+}
+
+type Operation<Input, Value> = (input: Input) => Effect.Effect<Value, Failure>;
+
+const partial = ".partial";
+
+const checkEvery: Duration.Input = "200 millis";
+
+const removal = { force: true, recursive: true } as const;
+
+/** Where a snapshot's copy is kept in the data directory, by its id. */
+const snapshotDirectory =
+  ({ directory, path }: Pick<Store, "directory" | "path">) =>
+  (id: string): string =>
+    path.join(directory, snapshotsFolder, id);
+
+const liveNamed = Effect.fnUntraced(function* liveNamed(store: Store, { environment, name }: Snapshotting) {
+  const row = yield* recordedEnvironment(store, environment);
+  const found = yield* liveSnapshot({ environment: row.name, name, sql: store.sql });
+  const notFound = (): NotFoundError => NotFoundError.make({ key: name, resource: "snapshot" });
+
+  return yield* Effect.mapError(Effect.fromOption(found), notFound);
+});
+
+// A snapshot by the id the record gave it, which the record keeps for good.
+const byId =
+  ({ sql }: Pick<Store, "sql">) =>
+  (id: string): Effect.Effect<SnapshotRow, SqlError.SqlError> =>
+    Effect.flatMap(snapshotById({ id, sql }), (found) => Effect.orDie(Effect.fromOption(found)));
+
+/** The environment's live snapshots, by name. */
+const listSnapshots =
+  (store: Store): ((environment?: EnvironmentName) => Effect.Effect<readonly LocalSnapshot[], Failure>) =>
+  (environment) =>
+    stored(store)(
+      Effect.gen(function* listingSnapshots() {
+        const row = yield* recordedEnvironment(store, environment);
+        const live = yield* liveSnapshots({ environment: row.name, sql: store.sql });
+
+        return Arr.map(live, snapshotOf);
+      }),
+    );
+
+const getSnapshot =
+  (store: Store): Operation<Snapshotting, LocalSnapshot> =>
+  (snapshotting) =>
+    stored(store)(Effect.map(liveNamed(store, snapshotting), snapshotOf));
+
+// Records the snapshot as Pending under a fresh id, unless a live snapshot of the environment has its name.
+const recordPending = Effect.fnUntraced(function* recordPending(store: Store, { environment, name }: Snapshotting) {
+  const row = yield* readyEnvironment(store, environment);
+  const taken = yield* liveSnapshot({ environment: row.name, name, sql: store.sql });
+
+  if (Option.isSome(taken)) {
+    return yield* AlreadyExistsError.make({ key: name, resource: "snapshot" });
+  }
+
+  const id = yield* nextSnapshotId(store);
+  const now = yield* Clock.currentTimeMillis;
+
+  yield* insertSnapshot({ environment: row.name, id, name, now, sql: store.sql });
+
+  return id;
+});
+
+const pending = (row: SnapshotRow): boolean => row.status === "Pending";
+
+// Waits, up to the hosting's limit, for the engine that serves the environment to take the snapshot.
+const settled = (store: Store, id: string): Effect.Effect<SnapshotRow, SqlError.SqlError> => {
+  const read = byId(store)(id);
+  const waiting = Effect.repeat(read, { schedule: Schedule.spaced(checkEvery), while: pending });
+
+  if (!Duration.isGreaterThan(store.hosting.settleWithin, Duration.zero)) {
+    return read;
+  }
+
+  return Effect.andThen(Effect.timeoutOption(waiting, store.hosting.settleWithin), read);
+};
+
+/**
+ * Asks for a snapshot of an environment. The engine serving it takes it, under each actor's command lock; one in this
+ * process takes it before this answers, and one in another process within a moment. Until then it is Pending.
+ */
+const createSnapshot =
+  (store: Store): Operation<Snapshotting, LocalSnapshot> =>
+  (snapshotting) =>
+    stored(store)(
+      Effect.gen(function* creatingSnapshot() {
+        const id = yield* store.sql.withTransaction(recordPending(store, snapshotting));
+
+        yield* store.hosting.apply;
+
+        const row = yield* settled(store, id);
+
+        return snapshotOf(row);
+      }),
+    );
+
+/** Retires the snapshot: it can no longer be used, its name is free again, and its copy is removed. */
+const deleteSnapshot =
+  (store: Store): Operation<Snapshotting, LocalSnapshot> =>
+  (snapshotting) =>
+    stored(store)(
+      Effect.gen(function* deletingSnapshot() {
+        const found = yield* liveNamed(store, snapshotting);
+
+        yield* retireSnapshot({ id: found.id, sql: store.sql });
+        yield* store.fileSystem.remove(snapshotDirectory(store)(found.id), removal);
+
+        const retired = yield* byId(store)(found.id);
+
+        return snapshotOf(retired);
+      }),
+    );
+
+/** Cuts the environment's store into a directory and answers the bytes the copy holds. */
+type Cut = (into: string) => Effect.Effect<number, { readonly message: string }>;
+
+interface Taking {
+  readonly cut: Cut;
+  readonly store: Store;
+}
+
+const failedWith = (failure: { readonly message: string }): Outcome => ({
+  reason: Option.some(failure.message),
+  sizeBytes: Option.none(),
+  status: "Failed",
+  takenAt: Option.none(),
+});
+
+// Cuts the store beside the snapshot's directory and renames the copy into place, so nothing reads a partial one.
+const taken = Effect.fnUntraced(function* taken({ cut, store }: Taking, final: string) {
+  const staging = `${final}${partial}`;
+
+  yield* store.fileSystem.remove(staging, removal);
+  yield* store.fileSystem.makeDirectory(staging, { recursive: true });
+
+  const sizeBytes = yield* cut(staging);
+
+  yield* store.fileSystem.rename(staging, final);
+
+  const takenAt = yield* Clock.currentTimeMillis;
+
+  const ready: Outcome = {
+    reason: Option.none(),
+    sizeBytes: Option.some(sizeBytes),
+    status: "Ready",
+    takenAt: Option.some(takenAt),
+  };
+
+  return ready;
+});
+
+// Takes one claimed snapshot: Ready once its copy is in place, or Failed with the reason and nothing left behind.
+const takeOne =
+  (taking: Taking) =>
+  ({ id }: SnapshotRow): Effect.Effect<void, Failure | SqlError.SqlError> =>
+    Effect.gen(function* takingOne() {
+      const { fileSystem } = taking.store;
+      const final = snapshotDirectory(taking.store)(id);
+
+      const failed = (failure: { readonly message: string }): Effect.Effect<Outcome> =>
+        Effect.as(Effect.ignore(fileSystem.remove(`${final}${partial}`, removal)), failedWith(failure));
+
+      const outcome: Outcome = yield* taken(taking, final).pipe(Effect.catch(failed));
+      const settledNow = yield* settleSnapshot({ ...outcome, id, sql: taking.store.sql });
+
+      if (!settledNow) {
+        yield* Effect.ignore(fileSystem.remove(final, removal));
+      }
+    });
+
+/** Takes every pending snapshot of the environment an engine serves, each claimed first so it is taken once. */
+const takePending =
+  (taking: Taking) =>
+  (environment: string): Effect.Effect<void, Failure> =>
+    stored(taking.store)(
+      Effect.flatMap(claimPending({ environment, sql: taking.store.sql }), (claimed) =>
+        Effect.forEach(claimed, takeOne(taking), { discard: true }),
+      ),
+    );
+
+export { createSnapshot, deleteSnapshot, getSnapshot, listSnapshots, snapshotDirectory, takePending };
+
+export type { Cut, Snapshotting, Taking };

package/src/serve/environment/store-snapshot.sql.ts

@@ -0,0 +1,128 @@
+import { Array as Arr, Effect, FileSystem, Path } from "effect";
+import type { SqlError } from "effect/sql";
+
+import type { LocalBlobHome } from "#src/host/file/local-blob-home.service";
+import type { SqliteDriver } from "#src/host/sqlite/sqlite-driver.service";
+import type { ActorHost } from "#src/serve/engine/actor-host.service";
+import type { ActorAddress, ActorLocation } from "#src/serve/engine/actor-location.service";
+
+/** One environment's store, cut into a snapshot's directory by the engine that serves it. */
+interface StoreCut {
+  /** Opens a database no engine writes, such as the file home's catalog, on a connection of its own. */
+  readonly driver: SqliteDriver["Service"];
+  readonly home: LocalBlobHome;
+  readonly host: ActorHost["Service"];
+  readonly into: string;
+  readonly location: ActorLocation["Service"];
+  /** The environment's store: the directory its `shards` and `files-home` are in. */
+  readonly store: string;
+}
+
+const filesHome = "files-home";
+
+const catalogFile = "catalog.sqlite";
+
+const blobsDirectory = "blobs";
+
+// A home keeps each blob under its id, a UUID; anything else in it, such as its lock or catalog, is not a blob.
+const blobName = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu;
+
+const noBytes = 0;
+
+/** Where an actor's database goes in the snapshot: the same path under `into` as under the store. */
+const targetOf = Effect.fnUntraced(function* targetOf({ into, location, store }: StoreCut, address: ActorAddress) {
+  const path = yield* Path.Path;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const target = path.join(into, path.relative(store, location.locate(address).database));
+
+  yield* fileSystem.makeDirectory(path.dirname(target), { recursive: true });
+
+  return target;
+});
+
+/** A consistent copy of a database no engine writes, read through a connection of its own. */
+interface Vacuuming {
+  readonly driver: SqliteDriver["Service"];
+  readonly source: string;
+  readonly target: string;
+}
+
+const vacuumed = ({ driver, source, target }: Vacuuming): Effect.Effect<void, SqlError.SqlError> =>
+  Effect.scoped(Effect.flatMap(driver.open(source), (sql) => Effect.asVoid(sql`VACUUM INTO ${target}`)));
+
+/**
+ * Copies one actor's database under its command lock, so the copy holds every command committed before it and none
+ * after. An actor whose type the app no longer serves has no engine writing it, so a plain copy is consistent.
+ */
+const copyActor = Effect.fnUntraced(function* copyActor(cut: StoreCut, address: ActorAddress) {
+  const target = yield* targetOf(cut, address);
+
+  const locked = Effect.scoped(
+    Effect.flatMap(cut.host.prepareFiles(address), ({ home, owner, sql }) =>
+      home.transfers.admit(owner.exclusive(sql`VACUUM INTO ${target}`)),
+    ),
+  );
+
+  const source = cut.location.locate(address).database;
+
+  yield* Effect.catchTag(locked, "InvalidRequestError", () => vacuumed({ driver: cut.driver, source, target }));
+});
+
+/** Copies the environment's files: every blob, and the catalog of their claims, as one consistent copy. */
+const copyFiles = Effect.fnUntraced(function* copyFiles({ driver, home, into }: StoreCut) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const [source, target] = [path.join(home.root, blobsDirectory), path.join(into, filesHome, blobsDirectory)];
+  const entries = yield* fileSystem.readDirectory(source);
+  const blobs = Arr.filter(entries, (entry) => blobName.test(entry));
+
+  const copyBlob = (blob: string): ReturnType<typeof fileSystem.copyFile> =>
+    fileSystem.copyFile(path.join(source, blob), path.join(target, blob));
+
+  yield* fileSystem.makeDirectory(target, { recursive: true });
+  yield* Effect.forEach(blobs, copyBlob, { discard: true });
+  const catalog = { source: path.join(home.root, catalogFile), target: path.join(into, filesHome, catalogFile) };
+
+  yield* vacuumed({ driver, ...catalog });
+});
+
+/** The bytes a snapshot's directory holds, which the snapshot reports as its size. */
+const sizeOf = Effect.fnUntraced(function* sizeOf(directory: string) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const entries = yield* fileSystem.readDirectory(directory, { recursive: true });
+  const stats = yield* Effect.forEach(entries, (entry) => fileSystem.stat(path.join(directory, entry)));
+
+  return Arr.reduce(stats, noBytes, (total, entry) => {
+    if (entry.type === "File") {
+      return total + Number(entry.size);
+    }
+
+    return total;
+  });
+});
+
+/**
+ * Cuts a served store into `into`: each actor's database is copied under that actor's command lock, consistent on
+ * its own, the guarantee an Archil checkpoint gives each database too. The whole cut runs under the file home's hold,
+ * so no file is written, claimed or collected between the first copy and the last, and every blob a copied database
+ * names is in the snapshot. Each actor is opened before the hold, so the hold never waits on opening one.
+ */
+const cutStore = Effect.fnUntraced(function* cutStore(cut: StoreCut) {
+  const addresses = yield* cut.location.list;
+
+  yield* Effect.forEach(addresses, (address) => Effect.ignore(cut.host.warm(address)), { discard: true });
+
+  const copies = Effect.andThen(
+    Effect.forEach(addresses, (address) => copyActor(cut, address), { discard: true }),
+    copyFiles(cut),
+  );
+
+  yield* cut.home.transfers.hold(copies);
+
+  return yield* sizeOf(cut.into);
+});
+
+export { cutStore };
+
+export type { StoreCut };

package/src/serve/erasure/local-actor-erasure.service.ts

@@ -0,0 +1,170 @@
+import {
+  Context,
+  Effect,
+  Exit,
+  FileSystem,
+  MutableHashMap,
+  MutableHashSet,
+  Option,
+  Predicate,
+  Scope,
+  Semaphore,
+} from "effect";
+import type { Path } from "effect";
+
+import { ActorErasedError } from "#src/contract/actor/actor-erased.errors";
+import { ActorRegistry } from "#src/contract/actor/actor-registry.service";
+import { ActorDatabase } from "#src/host/actor/actor-database.service";
+import { LocalComputers } from "#src/host/computer/local-computers.adapter";
+import { ActorLocation } from "#src/serve/engine/actor-location.service";
+import type { ActorAddress } from "#src/serve/engine/actor-location.service";
+import { fileIdentity, notServed, unavailable } from "#src/serve/engine/actor-residents.pure";
+import type { OpenFailure } from "#src/serve/engine/actor-residents.pure";
+
+interface Resident {
+  readonly forking: Semaphore.Semaphore;
+  readonly exclusive: <Value, Failure>(effect: Effect.Effect<Value, Failure>) => Effect.Effect<Value, Failure>;
+}
+
+interface Erasing {
+  readonly location: ActorLocation["Service"];
+  readonly databases: ActorDatabase["Service"];
+  readonly registry: ActorRegistry["Service"];
+  readonly fs: FileSystem.FileSystem;
+  readonly parent: Scope.Scope;
+  readonly erased: MutableHashSet.MutableHashSet<string>;
+  readonly services: Context.Context<ActorLocation | FileSystem.FileSystem | Path.Path>;
+  readonly residents: MutableHashMap.MutableHashMap<
+    string,
+    { readonly mark: Effect.Effect<void, OpenFailure>; readonly close: Effect.Effect<void> }
+  >;
+}
+
+const oneErasureAtATime = 1;
+
+/** The marker is also the durable cleanup intent. It survives deleting the database and reserves the erased key. */
+const notErased = Effect.fnUntraced(function* notErased(address: ActorAddress) {
+  const location = yield* ActorLocation;
+  const fs = yield* FileSystem.FileSystem;
+
+  const marked = yield* Effect.mapError(
+    fs.exists(`${location.locate(address).database}.erased`),
+    unavailable(address.actor),
+  );
+
+  if (marked) {
+    return yield* ActorErasedError.make({ actor: address.actor });
+  }
+
+  return yield* Effect.void;
+});
+
+const marker = ({ erased, fs, location }: Erasing, address: ActorAddress): Effect.Effect<void, OpenFailure> => {
+  const id = ActorLocation.named(address);
+
+  return Effect.mapError(
+    fs.writeFileString(`${location.locate(address).database}.erased`, "erased\n"),
+    unavailable(address.actor),
+  ).pipe(Effect.tap(() => Effect.sync(() => MutableHashSet.add(erased, id))));
+};
+
+const openErasable = <Value extends Resident>(
+  erasing: Erasing,
+  address: ActorAddress,
+  build: (scope: Scope.Closeable) => Effect.Effect<Value, OpenFailure>,
+): Effect.Effect<Value, OpenFailure> =>
+  Effect.gen(function* openActor() {
+    yield* erasing.registry.lookup(address.actor).pipe(Effect.mapError(() => notServed(address)));
+    yield* Effect.provide(notErased(address), erasing.services);
+    const scope = yield* Scope.fork(erasing.parent);
+    const resident = yield* Effect.onError(build(scope), () => Scope.close(scope, Exit.void));
+    const marked = resident.exclusive(marker(erasing, address));
+    MutableHashMap.set(erasing.residents, ActorLocation.named(address), {
+      close: Scope.close(scope, Exit.void),
+      mark: resident.forking.withPermits(oneErasureAtATime)(marked),
+    });
+
+    return resident;
+  });
+
+const releaseFiles = Effect.fnUntraced(function* releaseFiles(
+  { databases, fs, location }: Erasing,
+  address: ActorAddress,
+  actor: Effect.Success<ReturnType<ActorRegistry["Service"]["lookup"]>>,
+) {
+  const { database } = location.locate(address);
+
+  if (yield* fs.exists(database)) {
+    const opened = yield* databases.open({ actor, filename: database, identity: fileIdentity(address) });
+    const session = Option.fromNullishOr(opened.fileSession);
+    yield* Effect.forEach(Option.toArray(session), ({ home, owner }) => home.transfers.erase(owner));
+  }
+});
+
+const eraseLocal = Effect.fnUntraced(function* eraseLocal(erasing: Erasing, address: ActorAddress) {
+  const actor = yield* erasing.registry.lookup(address.actor).pipe(Effect.mapError(() => notServed(address)));
+  const { fs, location, residents, services } = erasing;
+  const files = location.locate(address);
+  const known = MutableHashMap.get(residents, ActorLocation.named(address));
+  yield* fs.makeDirectory(files.directory, { recursive: true });
+  yield* Option.match(known, { onNone: () => marker(erasing, address), onSome: ({ mark }) => mark });
+  yield* Effect.forEach(Option.toArray(known), ({ close }) => close);
+
+  // Stop jobs before releasing computers; a retry after a lost reply removes the same computers again.
+  yield* Effect.provide(LocalComputers.remove(location.computers, address), services);
+  yield* Effect.scoped(releaseFiles(erasing, address, actor));
+  yield* Effect.forEach(["", "-wal", "-shm"], (suffix) => fs.remove(`${files.database}${suffix}`, { force: true }));
+});
+
+/** Local, in-process erasure only: no app RPC or Cloud approval boundary is added or bypassed. */
+const localActorErasure = Effect.gen(function* localActorErasure() {
+  const store = yield* Effect.all({
+    databases: ActorDatabase,
+    fs: FileSystem.FileSystem,
+    location: ActorLocation,
+    parent: Effect.scope,
+    registry: ActorRegistry,
+  });
+
+  const services = yield* Effect.context<ActorLocation | FileSystem.FileSystem | Path.Path>();
+  const residents: Erasing["residents"] = MutableHashMap.empty();
+  const serial = yield* Semaphore.make(oneErasureAtATime);
+  const erased = MutableHashSet.empty<string>();
+  const erasing: Erasing = { ...store, erased, residents, services };
+
+  return {
+    check: (address: ActorAddress): Effect.Effect<void, OpenFailure> =>
+      Effect.suspend(() => {
+        if (MutableHashSet.has(erased, ActorLocation.named(address))) {
+          return ActorErasedError.make({ actor: address.actor });
+        }
+
+        return Effect.void;
+      }),
+    erase: (address: ActorAddress): Effect.Effect<void, OpenFailure> => {
+      const cleanup = eraseLocal(erasing, address).pipe(
+        Effect.mapError((failure) => {
+          if (Predicate.isTagged(failure, "InvalidRequestError") || Predicate.isTagged(failure, "ActorErasedError")) {
+            return failure;
+          }
+
+          return unavailable(address.actor)(failure);
+        }),
+        Effect.tap(() => Effect.sync(() => MutableHashMap.remove(residents, ActorLocation.named(address)))),
+      );
+
+      return serial.withPermits(oneErasureAtATime)(cleanup);
+    },
+    open: <Value extends Resident>(
+      address: ActorAddress,
+      build: (scope: Scope.Closeable) => Effect.Effect<Value, OpenFailure>,
+    ): Effect.Effect<Value, OpenFailure> => openErasable(erasing, address, build),
+  };
+});
+
+export class LocalActorErasure extends Context.Service<LocalActorErasure, Effect.Success<typeof localActorErasure>>()(
+  "@akterjs/effect/serve/erasure/local-actor-erasure.service/LocalActorErasure",
+) {
+  public static readonly make = localActorErasure;
+  public static readonly check = notErased;
+}

package/src/serve/history/actor-host-runners.service.ts

@@ -0,0 +1,85 @@
+import { Clock, Context, Duration, Effect, Schedule } from "effect";
+import type { Scope } from "effect";
+
+import { CommandRunner } from "#src/host/command/command-runner.service";
+import { QueryRunner } from "#src/host/query/query-runner.service";
+
+import type { OpenedActor } from "#src/host/actor/actor-database.service";
+import type { Residents } from "#src/serve/engine/actor-residents.pure";
+
+interface Prunable {
+  readonly opened: OpenedActor;
+  readonly exclusive: <Value, Failure>(effect: Effect.Effect<Value, Failure>) => Effect.Effect<Value, Failure>;
+}
+
+interface Runners {
+  readonly queries: QueryRunner["Service"];
+  readonly runner: CommandRunner["Service"];
+  readonly prune: (resident: Prunable) => Effect.Effect<void>;
+  readonly keep: (residents: Residents<Prunable>) => Effect.Effect<void, never, Scope.Scope>;
+}
+
+/** Prunes on open and hourly, through the same resident serializer as commands. */
+const actorHostRunners: Effect.Effect<Runners, never, CommandRunner | QueryRunner> = Effect.gen(
+  function* actorHostRunners() {
+    const runner = yield* CommandRunner;
+    const queries = yield* QueryRunner;
+    const retention = yield* CommandRunner.historyRetention;
+
+    const prune = ({ exclusive, opened }: Prunable): Effect.Effect<void> => {
+      if (!Duration.isFinite(retention)) {
+        return Effect.void;
+      }
+
+      const pruning = Effect.flatMap(Clock.currentTimeMillis, (now) =>
+        runner.prune({ before: now - Duration.toMillis(retention), opened }),
+      );
+
+      return exclusive(
+        pruning.pipe(
+          Effect.catchTag("SqlError", (failure) =>
+            Effect.logWarning(`could not prune the history of ${opened.actor.name}: ${failure.message}`),
+          ),
+        ),
+      );
+    };
+
+    const keep = ({ addresses, use }: Residents<Prunable>): Effect.Effect<void, never, Scope.Scope> => {
+      if (!Duration.isFinite(retention)) {
+        return Effect.void;
+      }
+
+      const pass = Effect.flatMap(addresses, (current) =>
+        Effect.forEach(
+          current,
+          (address) =>
+            use(address, prune).pipe(
+              Effect.catchTag("ActorErasedError", () => Effect.void),
+              Effect.orDie,
+            ),
+          { discard: true },
+        ),
+      );
+
+      const repeated = Effect.repeat(pass, Schedule.spaced("1 hour"));
+
+      return Effect.asVoid(Effect.forkScoped(repeated));
+    };
+
+    return { keep, prune, queries, runner };
+  },
+);
+
+export class ActorHostRunners extends Context.Service<ActorHostRunners, Runners>()(
+  "@akterjs/effect/serve/history/actor-host-runners.service/ActorHostRunners",
+) {
+  public static readonly make = actorHostRunners;
+  public static readonly historyRetention = CommandRunner.historyRetention;
+  public static readonly queries = QueryRunner.layer;
+}
+
+export type { Runners };
+
+export type { FileUsage } from "#src/host/query/query-runner.service";
+
+export type { CommandRunner } from "#src/host/command/command-runner.service";

package/src/serve/hosted/hosted-app-build.errors.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+
+/**
+ * A host refuses to load an app's bundle because the akter it was built with is one the host doesn't serve: a job
+ * from before jobs carried their codecs, or an actor whose host interface version is outside the host's window. The
+ * reason names what to do, which is always to deploy the app again with a current akter.
+ */
+export class HostedAppBuildError extends Schema.TaggedError<HostedAppBuildError, { readonly brand: unique symbol }>()(
+  "HostedAppBuildError",
+  { reason: Schema.String },
+) {}