@akterjs/effect 0.0.0-stage → 0.1.0

package/dist/serve/environment/local-environment.schema.d.mts

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+declare const EnvironmentName: Schema.brand<Schema.String, "EnvironmentName">;
+type EnvironmentName = typeof EnvironmentName.Type;
+declare const SnapshotName: Schema.brand<Schema.String, "SnapshotName">;
+type SnapshotName = typeof SnapshotName.Type;
+declare const SnapshotId: Schema.String;
+/** One local environment: a store of its own, a directory in the data directory. */
+declare const LocalEnvironment: Schema.Struct<{
+  readonly createdAt: Schema.DateTimeUtcFromString;
+  readonly directory: Schema.String;
+  readonly name: Schema.brand<Schema.String, "EnvironmentName">;
+  readonly quiet: Schema.Boolean;
+  readonly serving: Schema.Boolean;
+  readonly source: Schema.optionalKey<Schema.String>;
+  readonly status: Schema.Literals<readonly ["Ready", "Retired"]>;
+}>;
+type LocalEnvironment = typeof LocalEnvironment.Type;
+/** A named snapshot of one local environment: each actor's database and the environment's files. */
+declare const LocalSnapshot: Schema.Struct<{
+  readonly createdAt: Schema.DateTimeUtcFromString;
+  readonly environment: Schema.brand<Schema.String, "EnvironmentName">;
+  readonly id: Schema.String;
+  readonly name: Schema.brand<Schema.String, "SnapshotName">;
+  readonly reason: Schema.optionalKey<Schema.String>;
+  readonly sizeBytes: Schema.optionalKey<Schema.Int>;
+  readonly status: Schema.Literals<readonly ["Pending", "Ready", "Failed", "Retired"]>;
+  readonly takenAt: Schema.optionalKey<Schema.DateTimeUtcFromString>;
+}>;
+type LocalSnapshot = typeof LocalSnapshot.Type;
+declare const LocalResource: Schema.Literals<readonly ["environment", "snapshot"]>;
+/** What a promote did: which environment serves now, which served before, and what that leaves behind. */
+declare const Promotion: Schema.Struct<{
+  readonly environment: Schema.brand<Schema.String, "EnvironmentName">;
+  readonly notice: Schema.String;
+  readonly previous: Schema.optionalKey<Schema.brand<Schema.String, "EnvironmentName">>;
+}>;
+type Promotion = typeof Promotion.Type;
+export { EnvironmentName, LocalEnvironment, LocalResource, LocalSnapshot, Promotion, SnapshotId, SnapshotName };

package/dist/serve/environment/local-environment.schema.mjs

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+// src/serve/environment/local-environment.schema.ts
+const isName = [Schema.isPattern(new RegExp(`^[a-z](?:-?[a-z0-9])*$`, "u")), Schema.isMaxLength(63)];
+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}` });
+const SnapshotName = Schema.String.check(...isName).pipe(Schema.brand("SnapshotName")).annotate({ description: `A snapshot's name, unique among its environment's live snapshots. ${nameRule}` });
+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
+});
+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)
+});
+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)
+});
+export { EnvironmentName, LocalEnvironment, LocalResource, LocalSnapshot, Promotion, SnapshotId, SnapshotName };

package/dist/serve/environment/local-environments.service.d.mts

@@ -0,0 +1,44 @@
+import { Failure, Hosting, Store } from "./environment-store.sql.mjs";
+import { EnvironmentName, LocalEnvironment, Promotion, SnapshotName } from "./local-environment.schema.mjs";
+import { createSnapshot, deleteSnapshot, getSnapshot, listSnapshots } from "./snapshot-operations.sql.mjs";
+import { Context, Effect, FileSystem, Path, Scope } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+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>;
+interface StoreOpening {
+  readonly directory: string;
+  readonly hosting: Hosting;
+  readonly open: (filename: string) => Effect.Effect<SqlClient.SqlClient, SqlError.SqlError, Scope.Scope>;
+}
+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>;
+}
+declare const LocalEnvironments_base: Context.ServiceClass<LocalEnvironments, "@akterjs/effect/serve/environment/local-environments.service/LocalEnvironments", Operations>;
+/**
+ * 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 declare class LocalEnvironments extends LocalEnvironments_base {
+  static readonly openStore: (args_0: StoreOpening) => Effect.Effect<{
+    directory: string;
+    fileSystem: FileSystem.FileSystem;
+    hosting: Hosting;
+    path: Path.Path;
+    sql: SqlClient.SqlClient;
+  }, import("effect/PlatformError").PlatformError | SqlError.SqlError, FileSystem.FileSystem | Path.Path | Scope.Scope>;
+  static readonly on: (store: Store) => Operations;
+}
+export type { Branching };

package/dist/serve/environment/local-environments.service.mjs

@@ -0,0 +1,196 @@
+import { environmentRow, environmentRows, environmentsFolder, insertBranch, markPromoted, prepareRecords, recordFile, retireEnvironment, servingRow, snapshotById } from "./environment-records.sql.mjs";
+import { AlreadyExistsError } from "./environment-already-exists.errors.mjs";
+import { InUseError } from "./environment-in-use.errors.mjs";
+import { environmentOf, readyEnvironment, recordedEnvironment, stored } from "./environment-store.sql.mjs";
+import { EnvironmentName } from "./local-environment.schema.mjs";
+import { alreadyServing, promotionNotice } from "./promotion-notice.pure.mjs";
+import { createSnapshot, deleteSnapshot, getSnapshot, listSnapshots, snapshotDirectory } from "./snapshot-operations.sql.mjs";
+import { Array, Clock, Context, Effect, FileSystem, Option, Path } from "effect";
+// src/serve/environment/local-environments.service.ts
+const partial = ".partial";
+const neverServed = 0;
+const removal = {
+	force: true,
+	recursive: true
+};
+const describedBy = (store) => Effect.fnUntraced(function* described(row) {
+	const serving = yield* servingRow(store);
+	return environmentOf({
+		...store,
+		serving: serving.environment
+	})(row);
+});
+const listEnvironments = (store) => stored(store)(Effect.gen(function* listingEnvironments() {
+	const serving = yield* servingRow(store);
+	const rows = yield* environmentRows(store);
+	return Array.map(rows, environmentOf({
+		...store,
+		serving: serving.environment
+	}));
+}));
+const getEnvironment = (store) => (name) => stored(store)(Effect.flatMap(recordedEnvironment(store, name), describedBy(store)));
+const unusedName = Effect.fnUntraced(function* unusedName(store, name) {
+	const taken = yield* environmentRow({
+		name,
+		sql: store.sql
+	});
+	if (Option.isSome(taken)) return yield* AlreadyExistsError.make({
+		key: name,
+		resource: "environment"
+	});
+	return name;
+});
+const branchSource = Effect.fnUntraced(function* branchSource(store, { from, name, snapshot }) {
+	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;
+});
+const copied = Effect.fnUntraced(function* copied(store, source, target) {
+	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) => (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);
+}));
+const originOf = Effect.fnUntraced(function* originOf(store, row) {
+	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(Array.head(found)), (snapshot) => ({
+		environment: snapshot.environment,
+		id: snapshot.id,
+		name: snapshot.name,
+		takenAt: Option.fromNullishOr(snapshot.taken_at)
+	}));
+});
+const promotionOf = (environment, notice, previous) => Option.match(previous, {
+	onNone: () => ({
+		environment,
+		notice
+	}),
+	onSome: (before) => ({
+		environment,
+		notice,
+		previous: EnvironmentName.make(before)
+	})
+});
+const promoted = Effect.fnUntraced(function* promoted(store, name) {
+	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) => (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, name) {
+	const row = yield* readyEnvironment(store, name);
+	const serving = yield* servingRow(store);
+	if (row.name === "dev") 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) => (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);
+}));
+/** 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 }) {
+	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
+	};
+});
+/**
+* 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.
+*/
+var LocalEnvironments = class extends Context.Service()("@akterjs/effect/serve/environment/local-environments.service/LocalEnvironments") {
+	static openStore = openStore;
+	static on = (store) => ({
+		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 { LocalEnvironments };

package/dist/serve/environment/promotion-notice.pure.d.mts

@@ -0,0 +1,22 @@
+import { 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;
+}
+/**
+ * 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.
+ */
+declare const promotionNotice: (promoting: Promoting) => string;
+/** What a promote of the environment that already serves answers when no promote ever made it serve. */
+declare const alreadyServing: (environment: string) => string;
+export { type Origin, alreadyServing, promotionNotice };

package/dist/serve/environment/promotion-notice.pure.mjs

@@ -0,0 +1,30 @@
+import { Array, DateTime, Option } from "effect";
+// src/serve/environment/promotion-notice.pure.ts
+const takenWhen = (takenAt) => Option.match(takenAt, {
+	onNone: () => "",
+	onSome: (millis) => `, taken at ${DateTime.formatIso(DateTime.makeUnsafe(millis))}`
+});
+const fromSnapshot = ({ environment }, origin) => `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.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) => {
+	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 Array.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) => `${environment} already serves; nothing changed.`;
+export { alreadyServing, promotionNotice };

package/dist/serve/environment/snapshot-operations.sql.d.mts

@@ -0,0 +1,32 @@
+import { Failure, Store } from "./environment-store.sql.mjs";
+import { EnvironmentName, LocalSnapshot, SnapshotName } from "./local-environment.schema.mjs";
+import { Effect } from "effect";
+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>;
+/** Where a snapshot's copy is kept in the data directory, by its id. */
+declare const snapshotDirectory: ({ directory, path }: Pick<Store, "directory" | "path">) => (id: string) => string;
+/** The environment's live snapshots, by name. */
+declare const listSnapshots: (store: Store) => ((environment?: EnvironmentName) => Effect.Effect<readonly LocalSnapshot[], Failure>);
+declare const getSnapshot: (store: Store) => Operation<Snapshotting, LocalSnapshot>;
+/**
+ * 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.
+ */
+declare const createSnapshot: (store: Store) => Operation<Snapshotting, LocalSnapshot>;
+/** Retires the snapshot: it can no longer be used, its name is free again, and its copy is removed. */
+declare const deleteSnapshot: (store: Store) => Operation<Snapshotting, LocalSnapshot>;
+/** 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;
+}
+/** Takes every pending snapshot of the environment an engine serves, each claimed first so it is taken once. */
+declare const takePending: (taking: Taking) => (environment: string) => Effect.Effect<void, Failure>;
+export { type Cut, type Snapshotting, type Taking, createSnapshot, deleteSnapshot, getSnapshot, listSnapshots, snapshotDirectory, takePending };

package/dist/serve/environment/snapshot-operations.sql.mjs

@@ -0,0 +1,131 @@
+import { claimPending, insertSnapshot, liveSnapshot, liveSnapshots, nextSnapshotId, retireSnapshot, settleSnapshot, snapshotById, snapshotsFolder } from "./environment-records.sql.mjs";
+import { AlreadyExistsError } from "./environment-already-exists.errors.mjs";
+import { NotFoundError } from "./environment-not-found.errors.mjs";
+import { readyEnvironment, recordedEnvironment, snapshotOf, stored } from "./environment-store.sql.mjs";
+import { Array, Clock, Duration, Effect, Option, Schedule } from "effect";
+// src/serve/environment/snapshot-operations.sql.ts
+const partial = ".partial";
+const checkEvery = "200 millis";
+const removal = {
+	force: true,
+	recursive: true
+};
+/** Where a snapshot's copy is kept in the data directory, by its id. */
+const snapshotDirectory = ({ directory, path }) => (id) => path.join(directory, snapshotsFolder, id);
+const liveNamed = Effect.fnUntraced(function* liveNamed(store, { environment, name }) {
+	const row = yield* recordedEnvironment(store, environment);
+	const found = yield* liveSnapshot({
+		environment: row.name,
+		name,
+		sql: store.sql
+	});
+	const notFound = () => NotFoundError.make({
+		key: name,
+		resource: "snapshot"
+	});
+	return yield* Effect.mapError(Effect.fromOption(found), notFound);
+});
+const byId = ({ sql }) => (id) => Effect.flatMap(snapshotById({
+	id,
+	sql
+}), (found) => Effect.orDie(Effect.fromOption(found)));
+/** The environment's live snapshots, by name. */
+const listSnapshots = (store) => (environment) => stored(store)(Effect.gen(function* listingSnapshots() {
+	const row = yield* recordedEnvironment(store, environment);
+	const live = yield* liveSnapshots({
+		environment: row.name,
+		sql: store.sql
+	});
+	return Array.map(live, snapshotOf);
+}));
+const getSnapshot = (store) => (snapshotting) => stored(store)(Effect.map(liveNamed(store, snapshotting), snapshotOf));
+const recordPending = Effect.fnUntraced(function* recordPending(store, { environment, name }) {
+	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) => row.status === "Pending";
+const settled = (store, id) => {
+	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) => (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) => (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);
+}));
+const failedWith = (failure) => ({
+	reason: Option.some(failure.message),
+	sizeBytes: Option.none(),
+	status: "Failed",
+	takenAt: Option.none()
+});
+const taken = Effect.fnUntraced(function* taken({ cut, store }, final) {
+	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;
+	return {
+		reason: Option.none(),
+		sizeBytes: Option.some(sizeBytes),
+		status: "Ready",
+		takenAt: Option.some(takenAt)
+	};
+});
+const takeOne = (taking) => ({ id }) => Effect.gen(function* takingOne() {
+	const { fileSystem } = taking.store;
+	const final = snapshotDirectory(taking.store)(id);
+	const failed = (failure) => Effect.as(Effect.ignore(fileSystem.remove(`${final}${partial}`, removal)), failedWith(failure));
+	const outcome = yield* taken(taking, final).pipe(Effect.catch(failed));
+	if (!(yield* settleSnapshot({
+		...outcome,
+		id,
+		sql: taking.store.sql
+	}))) 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) => (environment) => 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 };

package/dist/serve/environment/store-snapshot.sql.d.mts

@@ -0,0 +1,32 @@
+import { ActorErasedError } from "../../contract/actor/actor-erased.errors.mjs";
+import { ActorUnavailableError } from "../../contract/client/actor-unavailable.errors.mjs";
+import { FilesUnavailableError } from "../../contract/file/files-unavailable.errors.mjs";
+import "../../runtime/akter.layer.mjs";
+import "../../contract/akter.service.mjs";
+import { LocalBlobHome } from "../../host/file/blob-home.sql.mjs";
+import { StoreUnreadableError } from "../store/store-unreadable.errors.mjs";
+import "../../host/file/local-blob-home.service.mjs";
+import { SqliteDriver } from "../../host/sqlite/sqlite-driver.service.mjs";
+import { ActorHost } from "../engine/actor-host.service.mjs";
+import { ActorLocation } from "../engine/actor-location.service.mjs";
+import { Effect, FileSystem, Path } from "effect";
+import { SqlError } from "effect/sql";
+/** 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;
+}
+/**
+ * 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.
+ */
+declare const cutStore: (cut: StoreCut) => Effect.Effect<number, ActorErasedError | ActorUnavailableError | FilesUnavailableError | import("effect/PlatformError").PlatformError | SqlError.SqlError | StoreUnreadableError, FileSystem.FileSystem | Path.Path>;
+export { type StoreCut, cutStore };

package/dist/serve/environment/store-snapshot.sql.mjs

@@ -0,0 +1,74 @@
+import { Array, Effect, FileSystem, Path } from "effect";
+// src/serve/environment/store-snapshot.sql.ts
+const filesHome = "files-home";
+const catalogFile = "catalog.sqlite";
+const blobsDirectory = "blobs";
+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 }, address) {
+	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;
+});
+const vacuumed = ({ driver, source, target }) => 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, address) {
+	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 }) {
+	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 = Array.filter(entries, (entry) => blobName.test(entry));
+	const copyBlob = (blob) => 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) {
+	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 Array.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) {
+	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 };