@akterjs/effect 0.0.0-stage → 0.1.0

package/dist/serve/engine/actor-residents.pure.mjs

@@ -0,0 +1,201 @@
+import { ActorUnavailableError } from "../../contract/client/actor-unavailable.errors.mjs";
+import { ActorErasedError } from "../../contract/actor/actor-erased.errors.mjs";
+import { InvalidRequestError } from "../../contract/client/invalid-request.errors.mjs";
+import { FilesUnavailableError } from "../../contract/file/files-unavailable.errors.mjs";
+import { addressHolding } from "./actor-holding.pure.mjs";
+import { Array, Deferred, Effect, Exit, Fiber, HashMap, MutableHashMap, Option, Schema, Scope, Semaphore, Stream, SynchronizedRef } from "effect";
+// src/serve/engine/actor-residents.pure.ts
+const blankVersion = 0;
+const bufferedInitial = 1;
+const onePermit = 1;
+const queryOnly = "PRAGMA query_only = ON";
+const fingerprint = "SELECT total_changes() AS changes, (SELECT schema_version FROM pragma_schema_version) AS tables, (SELECT user_version FROM pragma_user_version) AS stamp";
+const unavailable = (actor) => (failure) => ActorUnavailableError.make({
+	actor,
+	message: failure.message
+});
+const unavailableUnlessErased = (actor) => (failure) => {
+	if (Schema.is(ActorErasedError)(failure)) return failure;
+	return unavailable(actor)(failure);
+};
+const residentId = ({ actor, key }) => `${actor}/${key}`;
+/** The identity the local engine holds an actor's files by: its name's length, its name, then its key. */
+const fileIdentity = ({ actor, key }) => `${actor.length}:${actor}${key}`;
+const notServed = (address) => InvalidRequestError.make({
+	actor: address.actor,
+	message: `${address.actor} is not served here`
+});
+const arrive = (arrivals, id, opened) => Effect.suspend(() => {
+	const waiting = MutableHashMap.get(arrivals, id);
+	MutableHashMap.remove(arrivals, id);
+	return Option.match(waiting, {
+		onNone: () => Effect.void,
+		onSome: ({ resident, waiting: watches }) => Effect.andThen(Deferred.succeed(resident, opened), Effect.forEach(watches, Deferred.await, { discard: true }))
+	});
+});
+const residentOf = ({ arrivals, check: cacheCheck, holding, residents, scope }, open) => Effect.fnUntraced(function* resident(address) {
+	yield* cacheCheck(address);
+	const current = yield* SynchronizedRef.get(residents);
+	const cached = HashMap.get(current, residentId(address));
+	if (Option.isSome(cached)) return cached.value.value;
+	const opening = SynchronizedRef.modifyEffect(residents, (known) => Option.match(HashMap.get(known, residentId(address)), {
+		onNone: () => open(address).pipe(Effect.tap((opened) => arrive(arrivals, residentId(address), opened)), Effect.map((opened) => [opened, HashMap.set(known, residentId(address), {
+			address: {
+				actor: address.actor,
+				key: address.key
+			},
+			value: opened
+		})])),
+		onSome: (found) => Effect.succeed([found.value, known])
+	}));
+	const started = yield* Effect.forkIn(holding(address)(opening), scope);
+	return yield* Fiber.join(started);
+});
+const register = ({ arrivals, residents }, id) => SynchronizedRef.modifyEffect(residents, (current) => Effect.sync(() => {
+	const pending = Option.match(MutableHashMap.get(arrivals, id), {
+		onNone: () => Deferred.makeUnsafe(),
+		onSome: ({ resident: waiting }) => waiting
+	});
+	const ready = Deferred.makeUnsafe();
+	const found = Option.map(HashMap.get(current, id), (cached) => cached.value);
+	Option.match(found, {
+		onNone: () => {
+			const waiting = Option.match(MutableHashMap.get(arrivals, id), {
+				onNone: () => [],
+				onSome: (arrival) => arrival.waiting
+			});
+			MutableHashMap.set(arrivals, id, {
+				resident: pending,
+				waiting: Array.append(waiting, ready)
+			});
+		},
+		onSome: (cached) => Deferred.doneUnsafe(pending, Exit.succeed(cached))
+	});
+	return [{
+		current: found,
+		ready,
+		resident: pending
+	}, current];
+}));
+const release = (arrivals, id, registered) => Effect.andThen(Effect.sync(() => {
+	const found = Option.filter(MutableHashMap.get(arrivals, id), (waiting) => waiting.resident === registered.resident);
+	if (Option.isNone(found)) return;
+	const waiting = Array.filter(found.value.waiting, (ready) => ready !== registered.ready);
+	if (Array.isReadonlyArrayEmpty(waiting)) MutableHashMap.remove(arrivals, id);
+	else MutableHashMap.set(arrivals, id, {
+		resident: registered.resident,
+		waiting
+	});
+}), Deferred.succeed(registered.ready, true)).pipe(Effect.asVoid);
+const watchAt = (cache) => (address) => Effect.gen(function* watchArrival() {
+	const { current, ready, resident } = yield* Effect.acquireRelease(register(cache, residentId(address)), (held) => release(cache.arrivals, residentId(address), held));
+	return {
+		current: Option.isSome(current),
+		ready: Effect.asVoid(Deferred.succeed(ready, true)),
+		updates: (use) => Stream.unwrap(Effect.map(Deferred.await(resident), use))
+	};
+});
+const cachedResidents = ({ open, check = () => Effect.void }) => Effect.gen(function* makeCachedResidents() {
+	const residents = yield* SynchronizedRef.make(HashMap.empty());
+	const scope = yield* Effect.scope;
+	const holding = yield* addressHolding(residentId);
+	const cache = {
+		arrivals: MutableHashMap.empty(),
+		check,
+		holding,
+		residents,
+		scope
+	};
+	const borrow = residentOf(cache, open);
+	return {
+		addresses: Effect.map(SynchronizedRef.get(residents), (current) => Array.map(Array.fromIterable(HashMap.values(current)), (cached) => cached.address)),
+		borrow,
+		forget: (address) => SynchronizedRef.update(residents, (known) => HashMap.remove(known, residentId(address))),
+		holding,
+		stream: (address, use) => Stream.unwrap(Effect.map(borrow(address), use)),
+		use: (address, use) => Effect.scoped(Effect.flatMap(borrow(address), use)),
+		watch: watchAt(cache)
+	};
+});
+const markOf = ({ actor, reader }) => Effect.mapBoth(reader.unsafe(fingerprint), {
+	onFailure: unavailable(actor.name),
+	onSuccess: (rows) => Array.join(Array.map(rows, ({ changes, stamp, tables }) => `${changes}:${tables}:${stamp}`), ",")
+});
+const written = (address) => ActorUnavailableError.make({
+	actor: address.actor,
+	message: `a query wrote to ${address.actor}'s never-created template, so the template was discarded`
+});
+const builtWith = (templates, { build, scope }) => (address) => Option.match(MutableHashMap.get(templates, address.actor), {
+	onNone: () => Effect.gen(function* buildTemplate() {
+		const owned = yield* Scope.fork(scope);
+		const opened = yield* Effect.onError(build(address, owned), () => Scope.close(owned, Exit.void));
+		const template = {
+			mark: yield* markOf(opened),
+			opened,
+			scope: owned
+		};
+		MutableHashMap.set(templates, address.actor, template);
+		return template;
+	}),
+	onSome: Effect.succeed
+});
+const blankTemplates = (templating) => Effect.map(Semaphore.make(onePermit), (permit) => {
+	const templates = MutableHashMap.empty();
+	const built = builtWith(templates, templating);
+	return (address, use) => permit.withPermits(onePermit)(Effect.gen(function* guardedRead() {
+		const template = yield* built(address);
+		yield* Effect.mapError(template.opened.reader.unsafe(queryOnly), unavailable(address.actor));
+		const exit = yield* Effect.exit(use(template.opened));
+		const mark = yield* Effect.exit(markOf(template.opened));
+		if (Exit.isSuccess(mark) && mark.value === template.mark) return yield* exit;
+		MutableHashMap.remove(templates, address.actor);
+		yield* Scope.close(template.scope, Exit.void);
+		return yield* written(address);
+	}));
+});
+const attached = (watch, updates) => watch.updates(({ live }) => updates(live)).pipe(Stream.tap(() => watch.ready), Stream.filter((update) => update.version > blankVersion), Stream.ensuring(watch.ready));
+const liveOf = (reads, address, { first, updates }) => Stream.unwrap(Effect.flatMap(reads.stored(address), (stored) => {
+	if (stored) return Effect.succeed(reads.stream(address, ({ live }) => updates(live)));
+	return Effect.gen(function* watchBeforeArrival() {
+		const watch = yield* reads.watch(address);
+		if (watch.current) return watch.updates(({ live }) => updates(live));
+		const blank = yield* reads.template(address, (opened) => first(reads.current(opened)));
+		return Stream.concat(Stream.succeed(blank), attached(watch, updates)).pipe(Stream.buffer({ capacity: bufferedInitial }));
+	});
+}));
+const liveRoutes = (reads) => ({
+	state: (address) => liveOf(reads, address, {
+		first: (blank) => blank.state,
+		updates: (live) => live.state
+	}),
+	subscribe: (call) => liveOf(reads, call, {
+		first: (blank) => blank.subscribe(call),
+		updates: (live) => live.subscribe(call)
+	})
+});
+const existingWith = (resident, stored) => (address) => Effect.gen(function* existing() {
+	if (!(yield* stored(address))) return Option.none();
+	return yield* Effect.asSome(resident(address));
+});
+const readingOf = ({ blanks, residents, stored }) => {
+	const { current, template } = blanks;
+	const borrowExisting = existingWith(residents.borrow, stored);
+	const existing = (address, use) => Effect.scoped(Effect.flatMap(borrowExisting(address), use));
+	return {
+		borrowExisting,
+		existing,
+		live: liveRoutes({
+			current,
+			stored,
+			stream: residents.stream,
+			template,
+			watch: residents.watch
+		}),
+		read: (address, use) => existing(address, Option.match({
+			onNone: () => template(address, use),
+			onSome: ({ opened }) => use(opened)
+		}))
+	};
+};
+const fileSessionOf = ({ fileSession }) => Effect.fromOption(Option.fromNullishOr(fileSession)).pipe(Effect.mapError(() => FilesUnavailableError.make({ message: "files aren't available on this host" })));
+export { blankTemplates, cachedResidents, fileIdentity, fileSessionOf, notServed, readingOf, unavailable, unavailableUnlessErased };

package/dist/serve/engine/actor-shard.pure.d.mts

@@ -0,0 +1,4 @@
+declare const shardCount = 300;
+declare const shardOf: (id: string) => number;
+declare const shardDirectory: (id: string) => string;
+export { shardCount, shardDirectory, shardOf };

package/dist/serve/engine/actor-shard.pure.mjs

@@ -0,0 +1,8 @@
+import { Hash, String as String$1 } from "effect";
+// src/serve/engine/actor-shard.pure.ts
+const shardCount = 300;
+const firstShard = 1;
+const shardDigits = 3;
+const shardOf = (id) => Math.abs(Hash.string(id) % 300) + firstShard;
+const shardDirectory = (id) => String$1.padStart(shardDigits, "0")(String(shardOf(id)));
+export { shardCount, shardDirectory, shardOf };

package/dist/serve/engine/actor-state.pure.d.mts

@@ -0,0 +1,17 @@
+import { LiveUpdate } from "../../contract/client/actor-rpc.contract.mjs";
+import { HostedError } from "../../contract/hosted/hosted-error.contract.mjs";
+import { CallersSchemas, StateFields, StateSchema } from "../../contract/actor/actor.contract.mjs";
+import { Option, Stream } from "effect";
+interface StatefulActor {
+  readonly callers: CallersSchemas;
+  readonly initial: Option.Option<() => StateFields>;
+  readonly name: string;
+  readonly state: StateSchema;
+}
+interface StateWatch<Failure> {
+  readonly actor: StatefulActor;
+  readonly principal: string;
+  readonly updates: Stream.Stream<LiveUpdate<Option.Option<string>>, Failure>;
+}
+declare const stateUpdates: <Failure>({ actor, principal, updates }: StateWatch<Failure>) => Stream.Stream<LiveUpdate<StateFields>, Failure | HostedError>;
+export { type StatefulActor, stateUpdates };

package/dist/serve/engine/actor-state.pure.mjs

@@ -0,0 +1,20 @@
+import { admit } from "../../contract/caller/caller-admission.pure.mjs";
+import { startingState } from "../../contract/hosted/hosted-request.pure.mjs";
+import { Effect, Option, Stream } from "effect";
+// src/serve/engine/actor-state.pure.ts
+const stateMember = "state";
+const stateUpdates = ({ actor, principal, updates }) => {
+	const admitted = admit({
+		actor: actor.name,
+		allowed: Option.none(),
+		callers: actor.callers,
+		member: stateMember,
+		principal
+	});
+	const decoded = Stream.mapEffect(updates, ({ value, version }) => Effect.map(startingState(actor, value), (state) => ({
+		value: state,
+		version
+	})));
+	return Stream.unwrap(Effect.as(admitted, decoded));
+};
+export { stateUpdates };

package/dist/serve/engine/actors-not-hosted.errors.d.mts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+declare const ActorsNotHostedError_base: Schema.Class<ActorsNotHostedError, Schema.TaggedStruct<"ActorsNotHostedError", {
+  readonly actors: Schema.$Array<Schema.String>;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class ActorsNotHostedError extends ActorsNotHostedError_base {}
+export {};

package/dist/serve/engine/actors-not-hosted.errors.mjs

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+// src/serve/engine/actors-not-hosted.errors.ts
+var ActorsNotHostedError = class extends Schema.TaggedError()("ActorsNotHostedError", {
+	actors: Schema.Array(Schema.String),
+	message: Schema.String
+}) {};
+export { ActorsNotHostedError };

package/dist/serve/engine/job-runtime.layer.d.mts

@@ -0,0 +1,6 @@
+import { JobEngine } from "../../host/job/job-engine.adapter.mjs";
+import { Layer } from "effect";
+import { WorkflowEngine } from "effect/workflow";
+type JobServices = JobEngine | WorkflowEngine.WorkflowEngine;
+declare const withJobs: <Output, Failure, Needs>(layer: Layer.Layer<Output, Failure, Needs>) => Layer.Layer<Output | JobServices, Failure, Exclude<Needs, JobServices>>;
+export { withJobs };

package/dist/serve/engine/job-runtime.layer.mjs

@@ -0,0 +1,5 @@
+import { JobEngine } from "../../host/job/job-engine.adapter.mjs";
+import { Layer } from "effect";
+// src/serve/engine/job-runtime.layer.ts
+const withJobs = (layer) => Layer.provideMerge(layer, JobEngine.layerWorkflow);
+export { withJobs };

package/dist/serve/environment/environment-already-exists.errors.d.mts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+declare const AlreadyExistsError_base: Schema.Class<AlreadyExistsError, Schema.TaggedStruct<"AlreadyExistsError", {
+  readonly key: Schema.String;
+  readonly resource: Schema.Literals<readonly ["environment", "snapshot"]>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** The name is taken: by a live snapshot of the environment, or by an environment, retired ones included. */
+export declare class AlreadyExistsError extends AlreadyExistsError_base {}
+export {};

package/dist/serve/environment/environment-already-exists.errors.mjs

@@ -0,0 +1,9 @@
+import { LocalResource } from "./local-environment.schema.mjs";
+import { Schema } from "effect";
+// src/serve/environment/environment-already-exists.errors.ts
+/** The name is taken: by a live snapshot of the environment, or by an environment, retired ones included. */
+var AlreadyExistsError = class extends Schema.TaggedError()("AlreadyExistsError", {
+	key: Schema.String,
+	resource: LocalResource
+}) {};
+export { AlreadyExistsError };

package/dist/serve/environment/environment-in-use.errors.d.mts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+declare const InUseError_base: Schema.Class<InUseError, Schema.TaggedStruct<"InUseError", {
+  readonly key: Schema.String;
+  readonly reason: Schema.Literals<readonly ["environmentServing", "environmentRetired", "environmentIsTheDataDirectory", "snapshotNotReady"]>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** Something the operation needs is in the way, as Akter Cloud's InUseError says. */
+export declare class InUseError extends InUseError_base {}
+export {};

package/dist/serve/environment/environment-in-use.errors.mjs

@@ -0,0 +1,14 @@
+import { Schema } from "effect";
+// src/serve/environment/environment-in-use.errors.ts
+const InUseReason = Schema.Literals([
+	"environmentServing",
+	"environmentRetired",
+	"environmentIsTheDataDirectory",
+	"snapshotNotReady"
+]).annotate({ description: "environmentServing: promote another environment first; environmentRetired: the environment named by key was deleted and keeps its name; environmentIsTheDataDirectory: the data directory's own environment can't be deleted, delete the directory instead; snapshotNotReady: the snapshot named by key is not Ready, so nothing can branch from it." });
+/** Something the operation needs is in the way, as Akter Cloud's InUseError says. */
+var InUseError = class extends Schema.TaggedError()("InUseError", {
+	key: Schema.String,
+	reason: InUseReason
+}) {};
+export { InUseError };

package/dist/serve/environment/environment-not-found.errors.d.mts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+declare const NotFoundError_base: Schema.Class<NotFoundError, Schema.TaggedStruct<"NotFoundError", {
+  readonly key: Schema.String;
+  readonly resource: Schema.Literals<readonly ["environment", "snapshot"]>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** No live environment or snapshot has that name: the same error, with the same fields, Akter Cloud answers. */
+export declare class NotFoundError extends NotFoundError_base {}
+export {};

package/dist/serve/environment/environment-not-found.errors.mjs

@@ -0,0 +1,9 @@
+import { LocalResource } from "./local-environment.schema.mjs";
+import { Schema } from "effect";
+// src/serve/environment/environment-not-found.errors.ts
+/** No live environment or snapshot has that name: the same error, with the same fields, Akter Cloud answers. */
+var NotFoundError = class extends Schema.TaggedError()("NotFoundError", {
+	key: Schema.String,
+	resource: LocalResource
+}) {};
+export { NotFoundError };

package/dist/serve/environment/environment-records.sql.d.mts

@@ -0,0 +1,92 @@
+import { Effect, Option } from "effect";
+import { 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. */
+declare const firstEnvironment = "dev";
+/** Where the first environment's store is, relative to the data directory. */
+declare const ownDirectory = ".";
+/** The record of a data directory's environments and snapshots, at the top of the data directory. */
+declare const recordFile = "environments.db";
+/** Where a data directory keeps each branch's store, as `environments/<name>`. */
+declare const environmentsFolder = "environments";
+/** Where a data directory keeps each snapshot's copy, as `snapshots/<id>`. */
+declare 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;
+}
+/** Creates the record's tables, and the first environment serving, not quiet, unless they exist. */
+declare const prepareRecords: ({ now, sql }: Stamped) => Sql<void>;
+declare const environmentRows: ({ sql }: Records) => Sql<readonly EnvironmentRow[]>;
+declare const environmentRow: ({ name, sql }: Named) => Sql<Option.Option<EnvironmentRow>>;
+declare const servingRow: ({ sql }: Records) => Sql<ServingRow>;
+interface Branching extends Named, Stamped {
+  readonly directory: string;
+  readonly source: string;
+}
+/** A branch starts quiet, and has never served. */
+declare const insertBranch: ({ directory, name, now, source, sql }: Branching) => Sql<void>;
+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. */
+declare const markPromoted: ({ environment, notice, previous, sql }: Promoting) => Sql<void>;
+declare const retireEnvironment: ({ name, sql }: Named) => Sql<void>;
+interface OfEnvironment extends Records {
+  readonly environment: string;
+}
+/** The environment's live snapshots, by name; a retired snapshot is no longer listed. */
+declare const liveSnapshots: ({ environment, sql }: OfEnvironment) => Sql<readonly SnapshotRow[]>;
+declare const liveSnapshot: ({ environment, name, sql }: OfEnvironment & Named) => Sql<Option.Option<SnapshotRow>>;
+interface Identified extends Records {
+  readonly id: string;
+}
+declare const snapshotById: ({ id, sql }: Identified) => Sql<Option.Option<SnapshotRow>>;
+/** Takes the next snapshot id, snapshot-<n>; ids only ever grow, so a deleted snapshot's id is never reused. */
+declare const nextSnapshotId: ({ sql }: Records) => Sql<string>;
+declare const insertSnapshot: ({ environment, id, name, now, sql }: Identified & Named & OfEnvironment & Stamped) => Sql<void>;
+/** Claims the environment's pending snapshots that no engine claimed yet, so only one engine takes each. */
+declare const claimPending: ({ environment, sql }: OfEnvironment) => Sql<readonly SnapshotRow[]>;
+/** 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. */
+declare const settleSnapshot: ({ id, reason, sizeBytes, sql, status, takenAt }: Identified & Outcome) => Sql<boolean>;
+declare const retireSnapshot: ({ id, sql }: Identified) => Sql<void>;
+export { type EnvironmentRow, type Outcome, type ServingRow, type SnapshotRow, claimPending, environmentRow, environmentRows, environmentsFolder, firstEnvironment, insertBranch, insertSnapshot, liveSnapshot, liveSnapshots, markPromoted, nextSnapshotId, ownDirectory, prepareRecords, recordFile, retireEnvironment, retireSnapshot, servingRow, settleSnapshot, snapshotById, snapshotsFolder };

package/dist/serve/environment/environment-records.sql.mjs

@@ -0,0 +1,59 @@
+import { Array, Effect, Option } from "effect";
+// src/serve/environment/environment-records.sql.ts
+/** 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";
+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 }) => 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 (${"dev"}, ${"."}, 'Ready', 0, 1, ${now})`;
+	yield* sql`INSERT OR IGNORE INTO akter_serving (slot, environment) VALUES (1, ${"dev"})`;
+	yield* sql`INSERT OR IGNORE INTO akter_snapshot_sequence (slot, next) VALUES (1, 0)`;
+}));
+const environmentRows = ({ sql }) => sql`SELECT name, directory, status, quiet, served, source, created_at FROM akter_environments ORDER BY name`;
+const environmentRow = ({ name, sql }) => Effect.map(sql`SELECT name, directory, status, quiet, served, source, created_at FROM akter_environments WHERE name = ${name}`, Array.head);
+const servingRow = ({ sql }) => Effect.flatMap(sql`SELECT environment, previous, notice FROM akter_serving`, (rows) => Effect.orDie(Effect.fromOption(Array.head(rows))));
+/** A branch starts quiet, and has never served. */
+const insertBranch = ({ directory, name, now, source, sql }) => Effect.asVoid(sql`INSERT INTO akter_environments (name, directory, status, quiet, served, source, created_at) VALUES (${name}, ${directory}, 'Ready', 1, 0, ${source}, ${now})`);
+/** The promoted environment serves and stops being quiet; the one it replaces turns quiet and keeps its data. */
+const markPromoted = ({ environment, notice, previous, sql }) => 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 }) => 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";
+/** The environment's live snapshots, by name; a retired snapshot is no longer listed. */
+const liveSnapshots = ({ environment, sql }) => sql`SELECT ${sql.literal(snapshotColumns)} FROM akter_snapshots WHERE environment = ${environment} AND status != 'Retired' ORDER BY name`;
+const liveSnapshot = ({ environment, name, sql }) => Effect.map(sql`SELECT ${sql.literal(snapshotColumns)} FROM akter_snapshots WHERE environment = ${environment} AND name = ${name} AND status != 'Retired'`, Array.head);
+const snapshotById = ({ id, sql }) => Effect.map(sql`SELECT ${sql.literal(snapshotColumns)} FROM akter_snapshots WHERE id = ${id}`, Array.head);
+/** Takes the next snapshot id, snapshot-<n>; ids only ever grow, so a deleted snapshot's id is never reused. */
+const nextSnapshotId = ({ sql }) => Effect.map(sql`UPDATE akter_snapshot_sequence SET next = next + 1 RETURNING next - 1 AS taken`, (rows) => `snapshot-${Array.reduce(rows, firstSnapshot, (_last, row) => row.taken)}`);
+const insertSnapshot = ({ environment, id, name, now, sql }) => 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 }) => sql`UPDATE akter_snapshots SET claimed = 1 WHERE environment = ${environment} AND status = 'Pending' AND claimed = 0 RETURNING ${sql.literal(snapshotColumns)}`;
+/** 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 }) => {
+	const [taken, size, why] = [
+		Option.getOrNull(takenAt),
+		Option.getOrNull(sizeBytes),
+		Option.getOrNull(reason)
+	];
+	return Effect.map(sql`UPDATE akter_snapshots SET status = ${status}, taken_at = ${taken}, size_bytes = ${size}, reason = ${why} WHERE id = ${id} AND status = 'Pending' RETURNING id`, Array.isReadonlyArrayNonEmpty);
+};
+const retireSnapshot = ({ id, sql }) => Effect.asVoid(sql`UPDATE akter_snapshots SET status = 'Retired' WHERE id = ${id}`);
+export { claimPending, environmentRow, environmentRows, environmentsFolder, firstEnvironment, insertBranch, insertSnapshot, liveSnapshot, liveSnapshots, markPromoted, nextSnapshotId, ownDirectory, prepareRecords, recordFile, retireEnvironment, retireSnapshot, servingRow, settleSnapshot, snapshotById, snapshotsFolder };

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

@@ -0,0 +1,38 @@
+import { StoreUnreadableError } from "../store/store-unreadable.errors.mjs";
+import { EnvironmentRow, SnapshotRow } from "./environment-records.sql.mjs";
+import { AlreadyExistsError } from "./environment-already-exists.errors.mjs";
+import { InUseError } from "./environment-in-use.errors.mjs";
+import { NotFoundError } from "./environment-not-found.errors.mjs";
+import { LocalEnvironment, LocalSnapshot } from "./local-environment.schema.mjs";
+import { Duration, Effect, FileSystem, Path } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+/** 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. */
+declare const stored: ({ directory }: Pick<Store, "directory">) => <Value>(effect: Effect.Effect<Value, Failure | Storage>) => Effect.Effect<Value, Failure>;
+interface Describing extends Pick<Store, "directory" | "path"> {
+  readonly serving: string;
+}
+declare const environmentOf: ({ directory, path, serving }: Describing) => (row: EnvironmentRow) => LocalEnvironment;
+declare const snapshotOf: (row: SnapshotRow) => LocalSnapshot;
+/** The named environment, or the one that serves when no name is given, as it is recorded. */
+declare const recordedEnvironment: (store: Store, name: (string & import("effect/Brand").Brand<"EnvironmentName">) | undefined) => Effect.Effect<EnvironmentRow, NotFoundError | SqlError.SqlError, never>;
+/** The environment, which must be Ready: a retired one keeps its name but holds nothing. */
+declare const readyEnvironment: (store: Store, name: (string & import("effect/Brand").Brand<"EnvironmentName">) | undefined) => Effect.Effect<EnvironmentRow, InUseError | NotFoundError | SqlError.SqlError, never>;
+export { type Failure, type Hosting, type Store, environmentOf, readyEnvironment, recordedEnvironment, snapshotOf, stored };

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

@@ -0,0 +1,78 @@
+import { StoreUnreadableError } from "../store/store-unreadable.errors.mjs";
+import { environmentRow, servingRow } from "./environment-records.sql.mjs";
+import { InUseError } from "./environment-in-use.errors.mjs";
+import { NotFoundError } from "./environment-not-found.errors.mjs";
+import { EnvironmentName, SnapshotName } from "./local-environment.schema.mjs";
+import { DateTime, Effect, Option } from "effect";
+// src/serve/environment/environment-store.sql.ts
+/** A failure to read or write the record or a folder, answered as the data directory being unreadable. */
+const stored = ({ directory }) => (effect) => {
+	const unreadable = (failure) => Effect.fail(StoreUnreadableError.make({
+		directory,
+		message: failure.message
+	}));
+	return Effect.catchTags(effect, {
+		PlatformError: unreadable,
+		SqlError: unreadable
+	});
+};
+const quietFlag = 1;
+const sourceOf = (row) => Option.match(Option.fromNullishOr(row.source), {
+	onNone: () => ({}),
+	onSome: (source) => ({ source })
+});
+const environmentOf = ({ directory, path, serving }) => (row) => ({
+	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) => Option.match(Option.fromNullishOr(row.taken_at), {
+	onNone: () => ({}),
+	onSome: (millis) => ({ takenAt: DateTime.makeUnsafe(millis) })
+});
+const sizeOf = (row) => Option.match(Option.fromNullishOr(row.size_bytes), {
+	onNone: () => ({}),
+	onSome: (sizeBytes) => ({ sizeBytes })
+});
+const reasonOf = (row) => Option.match(Option.fromNullishOr(row.reason), {
+	onNone: () => ({}),
+	onSome: (reason) => ({ reason })
+});
+const snapshotOf = (row) => ({
+	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, name) {
+	const serving = yield* servingRow(store);
+	const wanted = name ?? serving.environment;
+	const row = yield* environmentRow({
+		name: wanted,
+		sql: store.sql
+	});
+	const notFound = () => 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, name) {
+	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 };