@akterjs/effect 0.0.0-stage → 0.1.1

package/src/host/job/undelivered-result.pure.ts

@@ -0,0 +1,265 @@
+import { Cause, Clock, Duration, Effect, Option, Ref, Schedule, Schema } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import { StorageLimitError } from "#src/contract/client/storage-limit.errors";
+import type { OpenedActor } from "#src/host/actor/actor-database.service";
+import type { CeilingGuard } from "#src/host/upkeep/execution-authority.pure";
+import type { FinishedJob, StalledJob } from "./job-runs.pure.js";
+
+interface Finishing extends FinishedJob {
+  readonly key: string;
+  /**
+   * Runs the result's command against the store's storage ceiling, or undefined where there is none. Required, so a
+   * caller can't drop the store's ceiling by leaving it out.
+   */
+  readonly measured: CeilingGuard | undefined;
+  readonly opened: OpenedActor;
+}
+
+/** Why storing a result failed: its SQL, or the storage ceiling refusing a result command that grew the database. */
+type Unstored = SqlError.SqlError | StorageLimitError;
+
+interface Stalling extends StalledJob {
+  readonly key: string;
+  readonly opened: OpenedActor;
+}
+
+/** Runs one delivery attempt under the actor's execution authority and its exclusive lock. */
+type Guard = <Success, Failure>(effect: Effect.Effect<Success, Failure>) => Effect.Effect<Success, Failure>;
+
+interface Entry {
+  readonly executionId: string;
+  readonly sql: SqlClient.SqlClient;
+}
+
+/** The delivery and the two journal statements it needs, from the job's SQL. */
+interface Delivery {
+  readonly deliver: (finishing: Finishing) => Effect.Effect<void, Unstored>;
+  readonly mark: (entry: Entry & { readonly value: string }) => Effect.Effect<void, SqlError.SqlError>;
+  readonly read: (entry: Entry & { readonly entry: string }) => Effect.Effect<Option.Option<string>, SqlError.SqlError>;
+}
+
+interface Delivering {
+  readonly actor: string;
+  readonly executionId: string;
+  readonly job: string;
+  readonly key: string;
+}
+
+/**
+ * The visible state of a result the upkeep could not store yet (the job journal's 'undelivered' entry): the attempts
+ * so far, the last error and when it failed. `retrying` is true while the upkeep retries it now; once a round of
+ * retries is spent it is false, `rounds` counts the spent rounds and `next`, present only then, is when the next round
+ * starts.
+ */
+const Undelivered = Schema.fromJsonString(
+  Schema.Struct({
+    at: Schema.Int,
+    attempts: Schema.Int,
+    error: Schema.String,
+    next: Schema.optionalKey(Schema.Int),
+    retrying: Schema.Boolean,
+    rounds: Schema.Int,
+  }),
+);
+
+type UndeliveredEntry = typeof Undelivered.Type;
+
+interface Progress {
+  readonly attempts: number;
+  readonly rounds: number;
+}
+
+/** One round: from 100 ms, doubling, capped at 30 seconds, for 10 retries (about 80 seconds in all). */
+const backoff = Schedule.min([Schedule.exponential("100 millis"), Schedule.spaced("30 seconds")]);
+
+const retryLimit = 10;
+
+/** Between rounds: 5 minutes after the first, doubling, capped at an hour. Rounds never stop. */
+const firstRoundGap = Duration.toMillis("5 minutes");
+
+const longestRoundGap = Duration.toMillis("1 hour");
+
+const doubling = 2;
+
+const oneMore = 1;
+
+const noMore = 0;
+
+const fresh: Progress = { attempts: 0, rounds: 0 };
+
+const roundGap = (rounds: number): number => Math.min(firstRoundGap * doubling ** (rounds - oneMore), longestRoundGap);
+
+interface Tracking {
+  readonly delivering: Delivering;
+  readonly delivery: Delivery;
+  readonly guard: Guard;
+  readonly progress: Ref.Ref<Option.Option<Progress>>;
+  readonly sql: OpenedActor["sql"];
+}
+
+/** The attempts and rounds an earlier run of this job already spent, read once, at its first failure. */
+const progressOf = ({ delivering, delivery, guard, progress, sql }: Tracking): Effect.Effect<Progress> =>
+  Effect.flatMap(
+    Ref.get(progress),
+    Option.match({
+      onNone: () =>
+        guard(delivery.read({ entry: "undelivered", executionId: delivering.executionId, sql })).pipe(
+          Effect.flatMap(
+            Option.match({
+              onNone: () => Effect.succeed(fresh),
+              onSome: (text) => Schema.decodeEffect(Undelivered)(text),
+            }),
+          ),
+          Effect.map(({ attempts, rounds }): Progress => ({ attempts, rounds })),
+          Effect.orElseSucceed((): Progress => fresh),
+          Effect.tap((found) => Ref.set(progress, Option.some(found))),
+        ),
+      onSome: Effect.succeed,
+    }),
+  );
+
+// A refusal at the storage ceiling has no message of its own, so the journal entry says what it was.
+const unstoredText = (failure: Unstored): string => {
+  if (Schema.is(StorageLimitError)(failure)) {
+    return `the store's ${String(failure.dataBytes)} bytes reached its storage ceiling of ${String(failure.ceilingBytes)}`;
+  }
+
+  return failure.message;
+};
+
+const written = (tracking: Tracking, entry: UndeliveredEntry): Effect.Effect<void, SqlError.SqlError> =>
+  Effect.flatMap(Effect.orDie(Schema.encodeEffect(Undelivered)(entry)), (value) =>
+    tracking.guard(tracking.delivery.mark({ executionId: tracking.delivering.executionId, sql: tracking.sql, value })),
+  );
+
+/** Each failed attempt is logged and written to the job's journal, best effort: the journal may be what fails. */
+const failedAttempt =
+  (tracking: Tracking) =>
+  (failure: Unstored): Effect.Effect<void> =>
+    Effect.gen(function* failed() {
+      const before = yield* progressOf(tracking);
+      const attempts = before.attempts + oneMore;
+      const at = yield* Clock.currentTimeMillis;
+
+      yield* Ref.set(tracking.progress, Option.some({ ...before, attempts }));
+      yield* Effect.annotateLogs(Effect.logWarning("a job's result could not be stored and will be retried", failure), {
+        ...tracking.delivering,
+        attempts,
+      });
+      yield* Effect.ignore(
+        written(tracking, { at, attempts, error: unstoredText(failure), retrying: true, rounds: before.rounds }),
+      );
+    });
+
+interface Spent {
+  /** What failed, for the journal entry. */
+  readonly error: string;
+  /** The failure or cause the error log carries. */
+  readonly logged: unknown;
+  readonly message: string;
+  /** Attempts this round adds beyond those already counted. */
+  readonly more: number;
+}
+
+/**
+ * A spent round leaves the job open and due again at `next`, so the upkeep wakes the actor then, with nobody calling
+ * it. Operators see it as an error log and the `JobResults.gaveUp` span. If even this can't be written, it fails.
+ */
+const spentRound = (tracking: Tracking, spent: Spent): Effect.Effect<void, SqlError.SqlError> =>
+  Effect.gen(function* givingUp() {
+    const before = yield* progressOf(tracking);
+    const attempts = before.attempts + spent.more;
+    const rounds = before.rounds + oneMore;
+    const at = yield* Clock.currentTimeMillis;
+    const next = at + roundGap(rounds);
+
+    yield* written(tracking, { at, attempts, error: spent.error, next, retrying: false, rounds });
+    yield* Effect.annotateLogs(Effect.logError(spent.message, spent.logged), {
+      ...tracking.delivering,
+      attempts,
+      next,
+      rounds,
+    });
+  }).pipe(Effect.withSpan("JobResults.gaveUp", { attributes: { ...tracking.delivering } }));
+
+const gaveUp =
+  (tracking: Tracking) =>
+  (failure: Unstored): Effect.Effect<void, SqlError.SqlError> =>
+    spentRound(tracking, {
+      error: unstoredText(failure),
+      logged: failure,
+      message: "a job's result could not be stored after its retries, so the job stays open and is retried later",
+      more: noMore,
+    });
+
+/** A defect while delivering never retries and never dies silently: it goes to the log with the job and the actor. */
+const undeliverable =
+  (delivering: Delivering) =>
+  (cause: Cause.Cause<unknown>): Effect.Effect<void> => {
+    if (Cause.hasInterruptsOnly(cause)) {
+      return Effect.void;
+    }
+
+    return Effect.annotateLogs(Effect.logError("a job's result could not be delivered, so the job stays open", cause), {
+      ...delivering,
+    });
+  };
+
+const tracked = (
+  finishing: Omit<Delivering, "actor"> & { readonly opened: OpenedActor },
+  delivery: Delivery,
+  guard: Guard,
+): Effect.Effect<Tracking> =>
+  Effect.map(Ref.make(Option.none<Progress>()), (progress): Tracking => ({
+    delivering: {
+      actor: finishing.opened.actor.name,
+      executionId: finishing.executionId,
+      job: finishing.job,
+      key: finishing.key,
+    },
+    delivery,
+    guard,
+    progress,
+    sql: finishing.opened.sql,
+  }));
+
+/**
+ * Delivers with a round of retries. A spent round returns, so the job's run ends and the engine forgets it; the
+ * journal keeps it open with its next round's due time.
+ */
+const settling =
+  (delivery: Delivery): ((finishing: Finishing, guard: Guard) => Effect.Effect<void>) =>
+  (finishing, guard) =>
+    Effect.gen(function* settle() {
+      const tracking = yield* tracked(finishing, delivery, guard);
+
+      yield* guard(delivery.deliver(finishing)).pipe(
+        Effect.tapError(failedAttempt(tracking)),
+        Effect.retry({ schedule: backoff, times: retryLimit }),
+        Effect.catch(gaveUp(tracking)),
+        Effect.tapCause(undeliverable(tracking.delivering)),
+        Effect.orDie,
+      );
+    });
+
+/**
+ * A run that ended before its result was stored (a batch that failed under it, or a result it couldn't record) spends
+ * a round the same way: one more attempt, and the job is due again at its next round. The log carries the cause, so
+ * a bug shows as well as a full disk.
+ */
+const stalling =
+  (delivery: Delivery) =>
+  (stalled: Stalling, guard: Guard): Effect.Effect<void, SqlError.SqlError> =>
+    Effect.flatMap(tracked(stalled, delivery, guard), (tracking) =>
+      spentRound(tracking, {
+        error: Cause.pretty(stalled.cause),
+        logged: stalled.cause,
+        message: "a job's run ended before its result was stored, so the job stays open and is retried later",
+        more: oneMore,
+      }),
+    );
+
+export { settling, stalling };
+
+export type { Finishing, Guard, Stalling, Unstored };

package/src/host/layout/actor-layout.sql.ts

@@ -0,0 +1,45 @@
+import { Array as Arr, Effect, Option } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import { layoutVersion, missingLayout } from "./layout-version.pure.js";
+import { prepareReceipts } from "#src/host/blob/reference/blob-receipts.sql";
+import { prepareOpenJobs } from "#src/host/job/job-journal.sql";
+
+type Sql<Value> = Effect.Effect<Value, SqlError.SqlError>;
+
+const layoutTables: readonly string[] = [
+  "CREATE TABLE akter_meta (key TEXT PRIMARY KEY, value ANY NOT NULL) STRICT",
+  "CREATE TABLE akter_migrations (version INTEGER PRIMARY KEY, hash TEXT NOT NULL, applied_at INTEGER NOT NULL) STRICT",
+  "CREATE TABLE akter_state (id INTEGER PRIMARY KEY CHECK (id = 1), value TEXT NOT NULL) STRICT",
+  "CREATE TABLE akter_commands (seq INTEGER PRIMARY KEY, command_id TEXT NOT NULL UNIQUE, command TEXT NOT NULL, payload TEXT NOT NULL, principal TEXT NOT NULL, exit TEXT NOT NULL, ids TEXT NOT NULL, times TEXT NOT NULL, files TEXT NOT NULL DEFAULT '[]', at INTEGER NOT NULL) STRICT",
+  "CREATE TABLE akter_timers (id TEXT PRIMARY KEY, due_at INTEGER NOT NULL, command TEXT NOT NULL, payload TEXT NOT NULL, principal TEXT NOT NULL) STRICT",
+  "CREATE INDEX akter_timers_due ON akter_timers (due_at)",
+  "CREATE TABLE akter_outbox (seq INTEGER PRIMARY KEY AUTOINCREMENT, command_id TEXT NOT NULL UNIQUE, actor TEXT NOT NULL, key TEXT NOT NULL, member TEXT NOT NULL, payload TEXT NOT NULL) STRICT",
+  "CREATE TABLE akter_failed_deliveries (command_id TEXT PRIMARY KEY, actor TEXT NOT NULL, key TEXT NOT NULL, member TEXT NOT NULL, error TEXT NOT NULL, at INTEGER NOT NULL) STRICT",
+  "CREATE TABLE akter_workflow (execution_id TEXT NOT NULL, entry TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (execution_id, entry)) STRICT",
+];
+
+const createLayout = (sql: SqlClient.SqlClient): Sql<void> =>
+  Effect.gen(function* creatingLayout() {
+    yield* Effect.forEach(layoutTables, (statement) => sql.unsafe(statement), { discard: true });
+    yield* prepareReceipts(sql);
+    yield* prepareOpenJobs(sql);
+    yield* sql`INSERT INTO akter_meta (key, value) VALUES ('layout', ${layoutVersion})`;
+  });
+
+/** Adds to a store made by an earlier engine at this layout version what this engine's layout has since gained. */
+const upgradeLayout = (sql: SqlClient.SqlClient): Sql<void> => prepareOpenJobs(sql);
+
+const recordedVersion = (sql: SqlClient.SqlClient): Sql<number> =>
+  Effect.map(sql<{ readonly value: number }>`SELECT value FROM akter_meta WHERE key = 'layout'`, (rows) =>
+    Option.match(Arr.head(rows), { onNone: () => missingLayout, onSome: (row) => row.value }),
+  );
+
+const storedLayoutVersion = (sql: SqlClient.SqlClient): Sql<Option.Option<number>> =>
+  Effect.flatMap(
+    sql<{ readonly name: string }>`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'akter_meta'`,
+    (tables) =>
+      Arr.match(tables, { onEmpty: () => Effect.succeedNone, onNonEmpty: () => Effect.asSome(recordedVersion(sql)) }),
+  );
+
+export { createLayout, storedLayoutVersion, upgradeLayout };

package/src/host/layout/layout-version.errors.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+
+export class LayoutVersionError extends Schema.TaggedError<LayoutVersionError, { readonly brand: unique symbol }>()(
+  "LayoutVersionError",
+  {
+    actor: Schema.String,
+    found: Schema.Int,
+    supported: Schema.Int,
+  },
+) {}

package/src/host/layout/layout-version.pure.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+
+import { LayoutVersionError } from "./layout-version.errors.js";
+
+interface FoundLayout {
+  readonly actor: string;
+  readonly found: number;
+}
+
+const layoutVersion = 3;
+
+const missingLayout = 0;
+
+const checkLayoutVersion = ({ actor, found }: FoundLayout): Effect.Effect<void, LayoutVersionError> => {
+  if (found === layoutVersion) {
+    return Effect.void;
+  }
+
+  return Effect.fail(LayoutVersionError.make({ actor, found, supported: layoutVersion }));
+};
+
+export { checkLayoutVersion, layoutVersion, missingLayout };

package/src/host/migration/actor-migrations.service.ts

@@ -0,0 +1,159 @@
+import { Clock, Context, Effect, Layer, Option } from "effect";
+import type { SqlClient } from "effect/sql";
+
+import type { HostedActor } from "#src/contract/actor/actor.contract";
+
+import { createLayout, storedLayoutVersion, upgradeLayout } from "#src/host/layout/actor-layout.sql";
+import {
+  appliedMigrations,
+  recordMigration,
+  reservedObjects,
+  upgradeStoredState,
+} from "#src/host/actor/actor-records.sql";
+import { checkLayoutVersion } from "#src/host/layout/layout-version.pure";
+import { migrationFailure } from "./migration-failure.pure.js";
+import { MigrationHasher } from "./migration-hasher.adapter.js";
+import { orderedMigrations, pendingMigrations } from "./migration-plan.pure.js";
+import type { DeclaredMigration } from "./migration-plan.pure.js";
+import { checkReserved } from "#src/host/actor/reserved-names.pure";
+
+interface Preparing {
+  readonly actor: HostedActor;
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface PreparingActor extends Preparing {
+  readonly declared: readonly DeclaredMigration[];
+}
+
+interface Reserving extends PreparingActor {
+  readonly reserved: readonly string[];
+}
+
+interface MigrationStep {
+  readonly from: number;
+  readonly to: number;
+}
+
+interface Applying {
+  readonly actor: string;
+  readonly migration: DeclaredMigration;
+  readonly reserved: readonly string[];
+  readonly sql: SqlClient.SqlClient;
+}
+
+const akterTables = "akter_";
+
+const HostTables = Context.Reference<Option.Option<string>>(
+  "@akterjs/effect/host/migration/actor-migrations.service/HostTables",
+  { defaultValue: () => Option.none() },
+);
+
+const migrationStep = (applied: readonly unknown[], pending: readonly unknown[]): MigrationStep => ({
+  from: applied.length,
+  to: applied.length + pending.length,
+});
+
+const ensureLayout = Effect.fnUntraced(function* ensureLayout({ actor, sql }: Preparing) {
+  const stored = yield* storedLayoutVersion(sql);
+
+  if (Option.isNone(stored)) {
+    return yield* createLayout(sql);
+  }
+
+  yield* checkLayoutVersion({ actor: actor.name, found: stored.value });
+
+  return yield* upgradeLayout(sql);
+});
+
+const applyMigration = Effect.fnUntraced(function* applyMigration({ actor, migration, reserved, sql }: Applying) {
+  const before = yield* reservedObjects({ prefixes: reserved, sql });
+
+  yield* Effect.mapError(migration.run(sql), (error) => migrationFailure({ actor, error, version: migration.version }));
+
+  const after = yield* reservedObjects({ prefixes: reserved, sql });
+
+  yield* checkReserved({ actor, after, before, version: migration.version });
+
+  const at = yield* Clock.currentTimeMillis;
+
+  yield* recordMigration({ row: { at, hash: migration.hash, version: migration.version }, sql });
+});
+
+const prepareActor = Effect.fnUntraced(function* prepareActor({ actor, declared, reserved, sql }: Reserving) {
+  yield* ensureLayout({ actor, sql });
+
+  const applied = yield* appliedMigrations(sql);
+  const pending = yield* pendingMigrations({ actor: actor.name, applied, declared });
+
+  yield* Effect.forEach(pending, (migration) => applyMigration({ actor: actor.name, migration, reserved, sql }), {
+    discard: true,
+  });
+  yield* upgradeStoredState({ actor, sql });
+
+  return migrationStep(applied, pending);
+});
+
+const planActor = Effect.fnUntraced(function* planActor({ actor, declared, sql }: PreparingActor) {
+  const stored = yield* storedLayoutVersion(sql);
+
+  const applied = yield* Option.match(stored, {
+    onNone: () => Effect.succeed([]),
+    onSome: (found) => Effect.andThen(checkLayoutVersion({ actor: actor.name, found }), appliedMigrations(sql)),
+  });
+
+  const pending = yield* pendingMigrations({ actor: actor.name, applied, declared });
+
+  return migrationStep(applied, pending);
+});
+
+type ActorOpenError = Effect.Error<ReturnType<typeof prepareActor>>;
+
+export class ActorMigrations extends Context.Service<
+  ActorMigrations,
+  {
+    readonly apply: (preparing: PreparingActor) => Effect.Effect<MigrationStep, ActorOpenError>;
+    readonly declare: (actor: HostedActor) => Effect.Effect<readonly DeclaredMigration[], ActorOpenError>;
+    readonly plan: (preparing: Preparing) => Effect.Effect<MigrationStep, ActorOpenError>;
+    readonly prepare: (preparing: Preparing) => Effect.Effect<MigrationStep, ActorOpenError>;
+  }
+>()("@akterjs/effect/host/migration/actor-migrations.service/ActorMigrations", {
+  make: Effect.gen(function* makeActorMigrations() {
+    const hasher = yield* MigrationHasher;
+    const hostTables = yield* HostTables;
+    const reserved = [akterTables, ...Option.toArray(hostTables)];
+
+    const declare = Effect.fnUntraced(function* declare(actor: HostedActor) {
+      return yield* Effect.forEach(orderedMigrations(actor.migrations), ([version, run]) =>
+        Effect.mapBoth(hasher.hash(run), {
+          onFailure: (error) => migrationFailure({ actor: actor.name, error, version }),
+          onSuccess: (hash): DeclaredMigration => ({ hash, run, version }),
+        }),
+      );
+    });
+
+    const plan = Effect.fn("ActorMigrations.plan")(function* plan({ actor, sql }: Preparing) {
+      const declared = yield* declare(actor);
+
+      return yield* planActor({ actor, declared, sql });
+    });
+
+    const apply = Effect.fn("ActorMigrations.apply")(function* apply(preparing: PreparingActor) {
+      return yield* preparing.sql.withTransaction(prepareActor({ ...preparing, reserved }));
+    });
+
+    const prepare = Effect.fn("ActorMigrations.prepare")(function* prepare({ actor, sql }: Preparing) {
+      const declared = yield* declare(actor);
+
+      return yield* apply({ actor, declared, sql });
+    });
+
+    return { apply, declare, plan, prepare } as const;
+  }),
+}) {
+  public static readonly hostTables = HostTables;
+
+  public static readonly layer = Layer.effect(this, this.make).pipe(Layer.provide(MigrationHasher.layer));
+}
+
+export type { ActorOpenError, MigrationStep, PreparingActor };

package/src/host/migration/migration-edited.errors.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+
+export class MigrationEditedError extends Schema.TaggedError<MigrationEditedError, { readonly brand: unique symbol }>()(
+  "MigrationEditedError",
+  {
+    actor: Schema.String,
+    version: Schema.Int,
+  },
+) {}

package/src/host/migration/migration-failed.errors.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+
+export class MigrationFailedError extends Schema.TaggedError<MigrationFailedError, { readonly brand: unique symbol }>()(
+  "MigrationFailedError",
+  {
+    actor: Schema.String,
+    message: Schema.String,
+    sqliteCode: Schema.optional(Schema.Int),
+    sqliteMessage: Schema.optional(Schema.String),
+    version: Schema.Int,
+  },
+) {}

package/src/host/migration/migration-failure.pure.ts

@@ -0,0 +1,28 @@
+import { Option } from "effect";
+import type { SqlError } from "effect/sql";
+
+import { MigrationFailedError } from "./migration-failed.errors.js";
+import { reasonText, sqliteReason } from "#src/host/sqlite/sqlite-reason.pure";
+
+interface FailedMigration {
+  readonly actor: string;
+  readonly error: SqlError.SqlError;
+  readonly version: number;
+}
+
+const migrationFailure = ({ actor, error, version }: FailedMigration): MigrationFailedError =>
+  Option.match(sqliteReason(error.reason.cause), {
+    onNone: () => MigrationFailedError.make({ actor, message: error.message, version }),
+    onSome: (reason) =>
+      MigrationFailedError.make({
+        actor,
+        message: `migration ${version} failed: ${reasonText(reason)}`,
+        sqliteCode: reason.code,
+        sqliteMessage: reason.message,
+        version,
+      }),
+  });
+
+export { migrationFailure };
+
+export type { FailedMigration };

package/src/host/migration/migration-hasher.adapter.ts

@@ -0,0 +1,70 @@
+import { Array as Arr, Context, Effect, Layer, Ref, Stream } from "effect";
+import { Digest } from "effect/crypto";
+import { Reactivity } from "effect/reactivity";
+import { SqlClient, Statement } from "effect/sql";
+import type { SqlConnection, SqlError } from "effect/sql";
+
+import type { Migration } from "#src/contract/actor/actor.contract";
+
+const recorder = (statements: Ref.Ref<readonly string[]>): SqlConnection.Connection => {
+  const record: SqlConnection.Connection["executeValues"] = (sql, params) =>
+    Effect.as(
+      Ref.update(statements, (recorded) => Arr.appendAll(recorded, [sql, ...Arr.map(params, String)])),
+      [],
+    );
+
+  return {
+    execute: record,
+    executeRaw: record,
+    executeStream: () => Stream.empty,
+    executeUnprepared: record,
+    executeValues: record,
+    executeValuesUnprepared: record,
+  };
+};
+
+const recordedStatements = Effect.fnUntraced(function* recordedStatements(migration: Migration) {
+  const statements = yield* Ref.make<readonly string[]>([]);
+
+  const reactivity = yield* Reactivity.make;
+
+  const recording = SqlClient.make({
+    acquirer: Effect.succeed(recorder(statements)),
+    compiler: Statement.makeCompilerSqlite(),
+    driver: "akter-migration-hasher",
+    spanAttributes: [],
+  });
+
+  const client = yield* Effect.provideService(recording, Reactivity.Reactivity, reactivity);
+
+  yield* migration(client);
+
+  return yield* Ref.get(statements);
+});
+
+const hashMigration = Effect.fnUntraced(function* hashMigration(
+  digest: Digest.Digest["Service"],
+  migration: Migration,
+) {
+  const recorded = yield* recordedStatements(migration);
+  const text = new globalThis.TextEncoder().encode(Arr.join(recorded, "\u0000"));
+
+  return yield* digest.digestHex(Digest.sha256, text);
+});
+
+export class MigrationHasher extends Context.Service<
+  MigrationHasher,
+  {
+    readonly hash: (migration: Migration) => Effect.Effect<string, SqlError.SqlError>;
+  }
+>()("@akterjs/effect/host/migration/migration-hasher.adapter/MigrationHasher", {
+  make: Effect.gen(function* makeMigrationHasher() {
+    const digest = yield* Digest.Digest;
+
+    return {
+      hash: (migration: Migration): Effect.Effect<string, SqlError.SqlError> => hashMigration(digest, migration),
+    } as const;
+  }),
+}) {
+  public static readonly layer = Layer.effect(this, this.make).pipe(Layer.provide(Digest.layerWebCrypto));
+}

package/src/host/migration/migration-missing.errors.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+
+export class MigrationMissingError extends Schema.TaggedError<
+  MigrationMissingError,
+  { readonly brand: unique symbol }
+>()("MigrationMissingError", {
+  actor: Schema.String,
+  version: Schema.Int,
+}) {}