@akterjs/effect 0.0.0-stage → 0.1.0

package/src/serve/environment/environment-records.sql.ts

@@ -0,0 +1,208 @@
+import { Array as Arr, Effect, Option } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+type Sql<Value> = Effect.Effect<Value, SqlError.SqlError>;
+
+/** The environment every data directory starts with, whose store is the data directory itself. */
+const firstEnvironment = "dev";
+
+const firstSnapshot = 0;
+
+/** Where the first environment's store is, relative to the data directory. */
+const ownDirectory = ".";
+
+/** The record of a data directory's environments and snapshots, at the top of the data directory. */
+const recordFile = "environments.db";
+
+/** Where a data directory keeps each branch's store, as `environments/<name>`. */
+const environmentsFolder = "environments";
+
+/** Where a data directory keeps each snapshot's copy, as `snapshots/<id>`. */
+const snapshotsFolder = "snapshots";
+
+interface EnvironmentRow {
+  readonly created_at: number;
+  readonly directory: string;
+  readonly name: string;
+  readonly quiet: number;
+  readonly served: number;
+  readonly source: string | null;
+  readonly status: "Ready" | "Retired";
+}
+
+interface SnapshotRow {
+  readonly created_at: number;
+  readonly environment: string;
+  readonly id: string;
+  readonly name: string;
+  readonly reason: string | null;
+  readonly size_bytes: number | null;
+  readonly status: "Pending" | "Ready" | "Failed" | "Retired";
+  readonly taken_at: number | null;
+}
+
+/** Which environment serves, and the promote that made it serve, kept so a repeated promote answers the same. */
+interface ServingRow {
+  readonly environment: string;
+  readonly notice: string | null;
+  readonly previous: string | null;
+}
+
+interface Records {
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface Stamped extends Records {
+  readonly now: number;
+}
+
+interface Named extends Records {
+  readonly name: string;
+}
+
+const tables = [
+  "CREATE TABLE IF NOT EXISTS akter_environments (name TEXT PRIMARY KEY, directory TEXT NOT NULL, status TEXT NOT NULL CHECK (status IN ('Ready', 'Retired')), quiet INTEGER NOT NULL CHECK (quiet IN (0, 1)), served INTEGER NOT NULL CHECK (served IN (0, 1)), source TEXT, created_at INTEGER NOT NULL) STRICT",
+  "CREATE TABLE IF NOT EXISTS akter_snapshots (id TEXT PRIMARY KEY, name TEXT NOT NULL, environment TEXT NOT NULL, status TEXT NOT NULL CHECK (status IN ('Pending', 'Ready', 'Failed', 'Retired')), claimed INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, taken_at INTEGER, size_bytes INTEGER, reason TEXT) STRICT",
+  "CREATE TABLE IF NOT EXISTS akter_serving (slot INTEGER PRIMARY KEY CHECK (slot = 1), environment TEXT NOT NULL, previous TEXT, notice TEXT) STRICT",
+  "CREATE TABLE IF NOT EXISTS akter_snapshot_sequence (slot INTEGER PRIMARY KEY CHECK (slot = 1), next INTEGER NOT NULL) STRICT",
+];
+
+/** Creates the record's tables, and the first environment serving, not quiet, unless they exist. */
+const prepareRecords = ({ now, sql }: Stamped): Sql<void> =>
+  sql.withTransaction(
+    Effect.gen(function* preparingRecords() {
+      yield* Effect.forEach(tables, (statement) => sql.unsafe(statement), { discard: true });
+      yield* sql`INSERT OR IGNORE INTO akter_environments (name, directory, status, quiet, served, created_at) VALUES (${firstEnvironment}, ${ownDirectory}, 'Ready', 0, 1, ${now})`;
+      yield* sql`INSERT OR IGNORE INTO akter_serving (slot, environment) VALUES (1, ${firstEnvironment})`;
+      yield* sql`INSERT OR IGNORE INTO akter_snapshot_sequence (slot, next) VALUES (1, 0)`;
+    }),
+  );
+
+const environmentRows = ({ sql }: Records): Sql<readonly EnvironmentRow[]> =>
+  sql<EnvironmentRow>`SELECT name, directory, status, quiet, served, source, created_at FROM akter_environments ORDER BY name`;
+
+const environmentRow = ({ name, sql }: Named): Sql<Option.Option<EnvironmentRow>> =>
+  Effect.map(
+    sql<EnvironmentRow>`SELECT name, directory, status, quiet, served, source, created_at FROM akter_environments WHERE name = ${name}`,
+    Arr.head,
+  );
+
+const servingRow = ({ sql }: Records): Sql<ServingRow> =>
+  Effect.flatMap(sql<ServingRow>`SELECT environment, previous, notice FROM akter_serving`, (rows) =>
+    Effect.orDie(Effect.fromOption(Arr.head(rows))),
+  );
+
+interface Branching extends Named, Stamped {
+  readonly directory: string;
+  readonly source: string;
+}
+
+/** A branch starts quiet, and has never served. */
+const insertBranch = ({ directory, name, now, source, sql }: Branching): Sql<void> =>
+  Effect.asVoid(
+    sql`INSERT INTO akter_environments (name, directory, status, quiet, served, source, created_at) VALUES (${name}, ${directory}, 'Ready', 1, 0, ${source}, ${now})`,
+  );
+
+interface Promoting extends Records {
+  readonly environment: string;
+  readonly notice: string;
+  readonly previous: string;
+}
+
+/** The promoted environment serves and stops being quiet; the one it replaces turns quiet and keeps its data. */
+const markPromoted = ({ environment, notice, previous, sql }: Promoting): Sql<void> =>
+  Effect.gen(function* markingPromoted() {
+    yield* sql`UPDATE akter_environments SET quiet = 1 WHERE name = ${previous}`;
+    yield* sql`UPDATE akter_environments SET quiet = 0, served = 1 WHERE name = ${environment}`;
+    yield* sql`UPDATE akter_serving SET environment = ${environment}, previous = ${previous}, notice = ${notice}`;
+  });
+
+const retireEnvironment = ({ name, sql }: Named): Sql<void> =>
+  Effect.asVoid(sql`UPDATE akter_environments SET status = 'Retired', quiet = 1 WHERE name = ${name}`);
+
+const snapshotColumns = "id, name, environment, status, created_at, taken_at, size_bytes, reason";
+
+interface OfEnvironment extends Records {
+  readonly environment: string;
+}
+
+/** The environment's live snapshots, by name; a retired snapshot is no longer listed. */
+const liveSnapshots = ({ environment, sql }: OfEnvironment): Sql<readonly SnapshotRow[]> =>
+  sql<SnapshotRow>`SELECT ${sql.literal(snapshotColumns)} FROM akter_snapshots WHERE environment = ${environment} AND status != 'Retired' ORDER BY name`;
+
+const liveSnapshot = ({ environment, name, sql }: OfEnvironment & Named): Sql<Option.Option<SnapshotRow>> =>
+  Effect.map(
+    sql<SnapshotRow>`SELECT ${sql.literal(snapshotColumns)} FROM akter_snapshots WHERE environment = ${environment} AND name = ${name} AND status != 'Retired'`,
+    Arr.head,
+  );
+
+interface Identified extends Records {
+  readonly id: string;
+}
+
+const snapshotById = ({ id, sql }: Identified): Sql<Option.Option<SnapshotRow>> =>
+  Effect.map(sql<SnapshotRow>`SELECT ${sql.literal(snapshotColumns)} FROM akter_snapshots WHERE id = ${id}`, Arr.head);
+
+/** Takes the next snapshot id, snapshot-<n>; ids only ever grow, so a deleted snapshot's id is never reused. */
+const nextSnapshotId = ({ sql }: Records): Sql<string> =>
+  Effect.map(
+    sql<{ readonly taken: number }>`UPDATE akter_snapshot_sequence SET next = next + 1 RETURNING next - 1 AS taken`,
+    (rows) => `snapshot-${Arr.reduce(rows, firstSnapshot, (_last, row) => row.taken)}`,
+  );
+
+const insertSnapshot = ({ environment, id, name, now, sql }: Identified & Named & OfEnvironment & Stamped): Sql<void> =>
+  Effect.asVoid(
+    sql`INSERT INTO akter_snapshots (id, name, environment, status, created_at) VALUES (${id}, ${name}, ${environment}, 'Pending', ${now})`,
+  );
+
+/** Claims the environment's pending snapshots that no engine claimed yet, so only one engine takes each. */
+const claimPending = ({ environment, sql }: OfEnvironment): Sql<readonly SnapshotRow[]> =>
+  sql<SnapshotRow>`UPDATE akter_snapshots SET claimed = 1 WHERE environment = ${environment} AND status = 'Pending' AND claimed = 0 RETURNING ${sql.literal(snapshotColumns)}`;
+
+/** How a claimed snapshot ended: Ready with its size and time, or Failed with the reason. */
+interface Outcome {
+  readonly reason: Option.Option<string>;
+  readonly sizeBytes: Option.Option<number>;
+  readonly status: "Ready" | "Failed";
+  readonly takenAt: Option.Option<number>;
+}
+
+/** Settles a pending snapshot; false when it was deleted meanwhile, so its taker removes what it took. */
+const settleSnapshot = ({ id, reason, sizeBytes, sql, status, takenAt }: Identified & Outcome): Sql<boolean> => {
+  const [taken, size, why] = [Option.getOrNull(takenAt), Option.getOrNull(sizeBytes), Option.getOrNull(reason)];
+
+  return Effect.map(
+    sql<{
+      readonly id: string;
+    }>`UPDATE akter_snapshots SET status = ${status}, taken_at = ${taken}, size_bytes = ${size}, reason = ${why} WHERE id = ${id} AND status = 'Pending' RETURNING id`,
+    Arr.isReadonlyArrayNonEmpty,
+  );
+};
+
+const retireSnapshot = ({ id, sql }: Identified): Sql<void> =>
+  Effect.asVoid(sql`UPDATE akter_snapshots SET status = 'Retired' WHERE id = ${id}`);
+
+export {
+  claimPending,
+  environmentRow,
+  environmentRows,
+  firstEnvironment,
+  insertBranch,
+  insertSnapshot,
+  liveSnapshot,
+  liveSnapshots,
+  markPromoted,
+  nextSnapshotId,
+  environmentsFolder,
+  ownDirectory,
+  prepareRecords,
+  recordFile,
+  retireEnvironment,
+  retireSnapshot,
+  servingRow,
+  settleSnapshot,
+  snapshotById,
+  snapshotsFolder,
+};
+
+export type { EnvironmentRow, Outcome, ServingRow, SnapshotRow };

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

@@ -0,0 +1,116 @@
+import { DateTime, Effect, Option } from "effect";
+import type { Duration, FileSystem, Path } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import { StoreUnreadableError } from "#src/serve/store/store-unreadable.errors";
+import { environmentRow, servingRow } from "./environment-records.sql.js";
+import type { EnvironmentRow, SnapshotRow } from "./environment-records.sql.js";
+import type { AlreadyExistsError } from "./environment-already-exists.errors.js";
+import { InUseError } from "./environment-in-use.errors.js";
+import { NotFoundError } from "./environment-not-found.errors.js";
+import { EnvironmentName, SnapshotName } from "./local-environment.schema.js";
+import type { LocalEnvironment, LocalSnapshot } from "./local-environment.schema.js";
+
+/** What applies a data directory's record: the engine serving it, or nothing when none runs in this process. */
+interface Hosting {
+  /** Applies the record now: an engine switches to the environment that serves and takes its pending snapshots. */
+  readonly apply: Effect.Effect<void>;
+  /** How long a new snapshot is waited for while it is Pending, for an engine in another process to take it. */
+  readonly settleWithin: Duration.Duration;
+}
+
+/** A data directory's environments: its record, on `sql`, and the folders beside it. */
+interface Store {
+  readonly directory: string;
+  readonly fileSystem: FileSystem.FileSystem;
+  readonly hosting: Hosting;
+  readonly path: Path.Path;
+  readonly sql: SqlClient.SqlClient;
+}
+
+type Storage = SqlError.SqlError | Effect.Error<ReturnType<FileSystem.FileSystem["remove"]>>;
+
+/** What an operation on a data directory's environments can fail with. */
+type Failure = AlreadyExistsError | InUseError | NotFoundError | StoreUnreadableError;
+
+/** A failure to read or write the record or a folder, answered as the data directory being unreadable. */
+const stored =
+  ({ directory }: Pick<Store, "directory">) =>
+  <Value>(effect: Effect.Effect<Value, Failure | Storage>): Effect.Effect<Value, Failure> => {
+    const unreadable = (failure: Storage): Effect.Effect<never, StoreUnreadableError> =>
+      Effect.fail(StoreUnreadableError.make({ directory, message: failure.message }));
+
+    return Effect.catchTags(effect, { PlatformError: unreadable, SqlError: unreadable });
+  };
+
+const quietFlag = 1;
+
+interface Describing extends Pick<Store, "directory" | "path"> {
+  readonly serving: string;
+}
+
+const sourceOf = (row: EnvironmentRow): Pick<LocalEnvironment, "source"> =>
+  Option.match(Option.fromNullishOr(row.source), { onNone: () => ({}), onSome: (source) => ({ source }) });
+
+const environmentOf =
+  ({ directory, path, serving }: Describing) =>
+  (row: EnvironmentRow): LocalEnvironment => ({
+    createdAt: DateTime.makeUnsafe(row.created_at),
+    directory: path.resolve(directory, row.directory),
+    name: EnvironmentName.make(row.name),
+    quiet: row.quiet === quietFlag,
+    serving: row.name === serving,
+    status: row.status,
+    ...sourceOf(row),
+  });
+
+const takenOf = (row: SnapshotRow): Pick<LocalSnapshot, "takenAt"> =>
+  Option.match(Option.fromNullishOr(row.taken_at), {
+    onNone: () => ({}),
+    onSome: (millis) => ({ takenAt: DateTime.makeUnsafe(millis) }),
+  });
+
+const sizeOf = (row: SnapshotRow): Pick<LocalSnapshot, "sizeBytes"> =>
+  Option.match(Option.fromNullishOr(row.size_bytes), { onNone: () => ({}), onSome: (sizeBytes) => ({ sizeBytes }) });
+
+const reasonOf = (row: SnapshotRow): Pick<LocalSnapshot, "reason"> =>
+  Option.match(Option.fromNullishOr(row.reason), { onNone: () => ({}), onSome: (reason) => ({ reason }) });
+
+const snapshotOf = (row: SnapshotRow): LocalSnapshot => ({
+  createdAt: DateTime.makeUnsafe(row.created_at),
+  environment: EnvironmentName.make(row.environment),
+  id: row.id,
+  name: SnapshotName.make(row.name),
+  status: row.status,
+  ...reasonOf(row),
+  ...sizeOf(row),
+  ...takenOf(row),
+});
+
+/** The named environment, or the one that serves when no name is given, as it is recorded. */
+const recordedEnvironment = Effect.fnUntraced(function* recordedEnvironment(
+  store: Store,
+  name: EnvironmentName | undefined,
+) {
+  const serving = yield* servingRow(store);
+  const wanted = name ?? serving.environment;
+  const row = yield* environmentRow({ name: wanted, sql: store.sql });
+  const notFound = (): NotFoundError => NotFoundError.make({ key: wanted, resource: "environment" });
+
+  return yield* Effect.mapError(Effect.fromOption(row), notFound);
+});
+
+/** The environment, which must be Ready: a retired one keeps its name but holds nothing. */
+const readyEnvironment = Effect.fnUntraced(function* readyEnvironment(store: Store, name: EnvironmentName | undefined) {
+  const row = yield* recordedEnvironment(store, name);
+
+  if (row.status === "Retired") {
+    return yield* InUseError.make({ key: row.name, reason: "environmentRetired" });
+  }
+
+  return row;
+});
+
+export { environmentOf, readyEnvironment, recordedEnvironment, snapshotOf, stored };
+
+export type { Failure, Hosting, Store };

package/src/serve/environment/local-environment.schema.ts

@@ -0,0 +1,79 @@
+import { Schema } from "effect";
+
+// The rule Akter Cloud names environments and snapshots by, so a name that works on one works on the other.
+const nameSource = "[a-z](?:-?[a-z0-9])*";
+
+const longestName = 63;
+
+const isName = [Schema.isPattern(new RegExp(`^${nameSource}$`, "u")), Schema.isMaxLength(longestName)] as const;
+
+const nameRule =
+  "1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.";
+
+const EnvironmentName = Schema.String.check(...isName)
+  .pipe(Schema.brand("EnvironmentName"))
+  .annotate({ description: `An environment's name, unique in its data directory. ${nameRule}` });
+
+type EnvironmentName = typeof EnvironmentName.Type;
+
+const SnapshotName = Schema.String.check(...isName)
+  .pipe(Schema.brand("SnapshotName"))
+  .annotate({ description: `A snapshot's name, unique among its environment's live snapshots. ${nameRule}` });
+
+type SnapshotName = typeof SnapshotName.Type;
+
+const SnapshotId = Schema.String.check(Schema.isPattern(/^snapshot-\d+$/u)).annotate({
+  description: "snapshot-<n>, numbered in the order snapshots were asked for; a deleted snapshot's id is never reused.",
+});
+
+const EnvironmentStatus = Schema.Literals(["Ready", "Retired"]).annotate({
+  description: "Ready: it can serve. Retired: it was deleted; its data is gone and it keeps its name.",
+});
+
+/** One local environment: a store of its own, a directory in the data directory. */
+const LocalEnvironment = Schema.Struct({
+  createdAt: Schema.DateTimeUtcFromString,
+  directory: Schema.String.annotate({ description: "The environment's store, the folder its shards live in." }),
+  name: EnvironmentName,
+  quiet: Schema.Boolean.annotate({
+    description:
+      "No timer fires, no outbox message is delivered and no job runs while it is quiet; they are held until it is promoted.",
+  }),
+  serving: Schema.Boolean.annotate({ description: "Whether akter dev serves it at /rpc." }),
+  source: Schema.optionalKey(SnapshotId.annotate({ description: "The snapshot it was branched from." })),
+  status: EnvironmentStatus,
+});
+
+type LocalEnvironment = typeof LocalEnvironment.Type;
+
+const SnapshotStatus = Schema.Literals(["Pending", "Ready", "Failed", "Retired"]).annotate({
+  description:
+    "Pending: akter dev serving the environment takes it next. Ready: it holds the environment's data as of takenAt. Failed: reason says why. Retired: it was deleted.",
+});
+
+/** A named snapshot of one local environment: each actor's database and the environment's files. */
+const LocalSnapshot = Schema.Struct({
+  createdAt: Schema.DateTimeUtcFromString,
+  environment: EnvironmentName,
+  id: SnapshotId,
+  name: SnapshotName,
+  reason: Schema.optionalKey(Schema.String),
+  sizeBytes: Schema.optionalKey(Schema.Int),
+  status: SnapshotStatus,
+  takenAt: Schema.optionalKey(Schema.DateTimeUtcFromString),
+});
+
+type LocalSnapshot = typeof LocalSnapshot.Type;
+
+const LocalResource = Schema.Literals(["environment", "snapshot"]);
+
+/** What a promote did: which environment serves now, which served before, and what that leaves behind. */
+const Promotion = Schema.Struct({
+  environment: EnvironmentName,
+  notice: Schema.String,
+  previous: Schema.optionalKey(EnvironmentName),
+});
+
+type Promotion = typeof Promotion.Type;
+
+export { EnvironmentName, LocalEnvironment, LocalResource, LocalSnapshot, Promotion, SnapshotId, SnapshotName };

package/src/serve/environment/local-environments.service.ts

@@ -0,0 +1,268 @@
+import { Array as Arr, Clock, Context, Effect, FileSystem, Option, Path } from "effect";
+import type { Scope } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import {
+  environmentRow,
+  environmentRows,
+  environmentsFolder,
+  firstEnvironment,
+  insertBranch,
+  markPromoted,
+  prepareRecords,
+  recordFile,
+  retireEnvironment,
+  servingRow,
+  snapshotById,
+} from "./environment-records.sql.js";
+import type { EnvironmentRow } from "./environment-records.sql.js";
+import { AlreadyExistsError } from "./environment-already-exists.errors.js";
+import { InUseError } from "./environment-in-use.errors.js";
+import { environmentOf, readyEnvironment, recordedEnvironment, stored } from "./environment-store.sql.js";
+import type { Failure, Hosting, Store } from "./environment-store.sql.js";
+import { EnvironmentName } from "./local-environment.schema.js";
+import type { LocalEnvironment, Promotion, SnapshotName } from "./local-environment.schema.js";
+import { alreadyServing, promotionNotice } from "./promotion-notice.pure.js";
+import {
+  createSnapshot,
+  deleteSnapshot,
+  getSnapshot,
+  listSnapshots,
+  snapshotDirectory,
+} from "./snapshot-operations.sql.js";
+
+interface Branching {
+  /** The environment the snapshot is of; the serving one when missing. */
+  readonly from?: EnvironmentName | undefined;
+  readonly name: EnvironmentName;
+  readonly snapshot: SnapshotName;
+}
+
+type Operation<Input, Value> = (input: Input) => Effect.Effect<Value, Failure>;
+
+const partial = ".partial";
+
+const neverServed = 0;
+
+const removal = { force: true, recursive: true } as const;
+
+const describedBy = (store: Store): ((row: EnvironmentRow) => Effect.Effect<LocalEnvironment, SqlError.SqlError>) =>
+  Effect.fnUntraced(function* described(row: EnvironmentRow) {
+    const serving = yield* servingRow(store);
+
+    return environmentOf({ ...store, serving: serving.environment })(row);
+  });
+
+const listEnvironments = (store: Store): Effect.Effect<readonly LocalEnvironment[], Failure> =>
+  stored(store)(
+    Effect.gen(function* listingEnvironments() {
+      const serving = yield* servingRow(store);
+      const rows = yield* environmentRows(store);
+
+      return Arr.map(rows, environmentOf({ ...store, serving: serving.environment }));
+    }),
+  );
+
+const getEnvironment =
+  (store: Store): Operation<EnvironmentName, LocalEnvironment> =>
+  (name) =>
+    stored(store)(Effect.flatMap(recordedEnvironment(store, name), describedBy(store)));
+
+const unusedName = Effect.fnUntraced(function* unusedName(store: Store, name: EnvironmentName) {
+  const taken = yield* environmentRow({ name, sql: store.sql });
+
+  if (Option.isSome(taken)) {
+    return yield* AlreadyExistsError.make({ key: name, resource: "environment" });
+  }
+
+  return name;
+});
+
+// The Ready snapshot a branch copies.
+const branchSource = Effect.fnUntraced(function* branchSource(store: Store, { from, name, snapshot }: Branching) {
+  yield* unusedName(store, name);
+
+  const found = yield* getSnapshot(store)({ environment: from, name: snapshot });
+
+  if (found.status !== "Ready") {
+    return yield* InUseError.make({ key: snapshot, reason: "snapshotNotReady" });
+  }
+
+  return found;
+});
+
+// Copies the snapshot beside the branch's directory, then renames it into place.
+const copied = Effect.fnUntraced(function* copied(store: Store, source: string, target: string) {
+  const staging = `${target}${partial}`;
+
+  yield* store.fileSystem.remove(staging, removal);
+  yield* store.fileSystem.copy(source, staging);
+  yield* store.fileSystem.rename(staging, target);
+});
+
+/**
+ * Branches a new environment from a snapshot: a copy of the snapshot's store in a directory of its own, quiet until
+ * it is promoted, so it serves calls but fires no timer, delivers no message and runs no job. Its copy appears by one
+ * rename, so nothing reads a partial branch.
+ */
+const branch =
+  (store: Store): Operation<Branching, LocalEnvironment> =>
+  (branching) =>
+    stored(store)(
+      Effect.gen(function* branchingEnvironment() {
+        const source = yield* branchSource(store, branching);
+        const relative = store.path.join(environmentsFolder, branching.name);
+        const target = store.path.join(store.directory, relative);
+
+        yield* copied(store, snapshotDirectory(store)(source.id), target);
+
+        const now = yield* Clock.currentTimeMillis;
+        const recorded = { directory: relative, name: branching.name, now, source: source.id, sql: store.sql };
+        const insert = Effect.andThen(unusedName(store, branching.name), insertBranch(recorded));
+
+        yield* Effect.tapError(store.sql.withTransaction(insert), () => store.fileSystem.remove(target, removal));
+
+        return yield* getEnvironment(store)(branching.name);
+      }),
+    );
+
+// The snapshot a never-served branch came from, as its promote names it.
+const originOf = Effect.fnUntraced(function* originOf(store: Store, row: EnvironmentRow) {
+  const source = Option.filter(Option.fromNullishOr(row.source), () => row.served === neverServed);
+  const found = yield* Effect.forEach(Option.toArray(source), (id) => snapshotById({ id, sql: store.sql }));
+
+  return Option.map(Option.flatten(Arr.head(found)), (snapshot) => ({
+    environment: snapshot.environment,
+    id: snapshot.id,
+    name: snapshot.name,
+    takenAt: Option.fromNullishOr(snapshot.taken_at),
+  }));
+});
+
+const promotionOf = (environment: EnvironmentName, notice: string, previous: Option.Option<string>): Promotion =>
+  Option.match(previous, {
+    onNone: () => ({ environment, notice }),
+    onSome: (before) => ({ environment, notice, previous: EnvironmentName.make(before) }),
+  });
+
+const promoted = Effect.fnUntraced(function* promoted(store: Store, name: EnvironmentName) {
+  const row = yield* readyEnvironment(store, name);
+  const serving = yield* servingRow(store);
+  const previous = Option.fromNullishOr(serving.previous);
+
+  if (serving.environment === row.name) {
+    return promotionOf(name, serving.notice ?? alreadyServing(name), previous);
+  }
+
+  const origin = yield* originOf(store, row);
+  const notice = promotionNotice({ environment: name, origin, previous: serving.environment });
+
+  yield* markPromoted({ environment: name, notice, previous: serving.environment, sql: store.sql });
+
+  return promotionOf(name, notice, Option.some(serving.environment));
+});
+
+/**
+ * Promotes an environment: akter dev serves it in place of the one that served, which turns quiet and is kept as it
+ * was. Its held work runs: jobs resume from its journal and due timers fire. Promoting the environment that already
+ * serves changes nothing and answers what its promote answered.
+ */
+const promote =
+  (store: Store): Operation<EnvironmentName, Promotion> =>
+  (name) =>
+    stored(store)(
+      Effect.gen(function* promoting() {
+        const promotion = yield* store.sql.withTransaction(promoted(store, name));
+
+        yield* store.hosting.apply;
+
+        return promotion;
+      }),
+    );
+
+const deletable = Effect.fnUntraced(function* deletable(store: Store, name: EnvironmentName) {
+  const row = yield* readyEnvironment(store, name);
+  const serving = yield* servingRow(store);
+
+  if (row.name === firstEnvironment) {
+    return yield* InUseError.make({ key: name, reason: "environmentIsTheDataDirectory" });
+  }
+
+  if (row.name === serving.environment) {
+    return yield* InUseError.make({ key: name, reason: "environmentServing" });
+  }
+
+  return row;
+});
+
+/** Deletes an environment that doesn't serve: its store is removed, and it is kept as Retired, holding its name. */
+const deleteEnvironment =
+  (store: Store): Operation<EnvironmentName, LocalEnvironment> =>
+  (name) =>
+    stored(store)(
+      Effect.gen(function* deletingEnvironment() {
+        const retire = Effect.tap(deletable(store, name), () => retireEnvironment({ name, sql: store.sql }));
+        const row = yield* store.sql.withTransaction(retire);
+
+        yield* store.fileSystem.remove(store.path.resolve(store.directory, row.directory), removal);
+
+        return yield* getEnvironment(store)(name);
+      }),
+    );
+
+interface StoreOpening {
+  readonly directory: string;
+  readonly hosting: Hosting;
+  readonly open: (filename: string) => Effect.Effect<SqlClient.SqlClient, SqlError.SqlError, Scope.Scope>;
+}
+
+/** Opens a data directory's environments on its record, `environments.db`, which it creates when missing. */
+const openStore = Effect.fnUntraced(function* openStore({ directory, hosting, open }: StoreOpening) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  yield* fileSystem.makeDirectory(directory, { recursive: true });
+
+  const sql = yield* open(path.join(directory, recordFile));
+  const now = yield* Clock.currentTimeMillis;
+
+  yield* prepareRecords({ now, sql });
+
+  return { directory, fileSystem, hosting, path, sql };
+});
+
+interface Operations {
+  readonly branch: Operation<Branching, LocalEnvironment>;
+  readonly createSnapshot: ReturnType<typeof createSnapshot>;
+  readonly deleteEnvironment: Operation<EnvironmentName, LocalEnvironment>;
+  readonly deleteSnapshot: ReturnType<typeof deleteSnapshot>;
+  readonly environment: Operation<EnvironmentName, LocalEnvironment>;
+  readonly environments: Effect.Effect<readonly LocalEnvironment[], Failure>;
+  readonly promote: Operation<EnvironmentName, Promotion>;
+  readonly snapshot: ReturnType<typeof getSnapshot>;
+  readonly snapshots: ReturnType<typeof listSnapshots>;
+}
+
+/**
+ * The environments and snapshots of one data directory, named as Akter Cloud's environments and snapshots groups:
+ * snapshot an environment, branch a quiet environment from a snapshot, promote it to serve, and promote back.
+ */
+export class LocalEnvironments extends Context.Service<LocalEnvironments, Operations>()(
+  "@akterjs/effect/serve/environment/local-environments.service/LocalEnvironments",
+) {
+  public static readonly openStore = openStore;
+
+  public static readonly on = (store: Store): Operations => ({
+    branch: branch(store),
+    createSnapshot: createSnapshot(store),
+    deleteEnvironment: deleteEnvironment(store),
+    deleteSnapshot: deleteSnapshot(store),
+    environment: getEnvironment(store),
+    environments: listEnvironments(store),
+    promote: promote(store),
+    snapshot: getSnapshot(store),
+    snapshots: listSnapshots(store),
+  });
+}
+
+export type { Branching };