@akterjs/effect 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,66 @@
+import { Array as Arr, Effect, Option, Order, Record as Rec, pipe } from "effect";
+
+import type { Migration, Migrations } from "#src/contract/actor/actor.contract";
+
+import { MigrationEditedError } from "./migration-edited.errors.js";
+import { MigrationMissingError } from "./migration-missing.errors.js";
+
+interface AppliedMigration {
+  readonly hash: string;
+  readonly version: number;
+}
+
+interface DeclaredMigration extends AppliedMigration {
+  readonly run: Migration;
+}
+
+interface MigrationHistory {
+  readonly actor: string;
+  readonly applied: readonly AppliedMigration[];
+  readonly declared: readonly DeclaredMigration[];
+}
+
+type NumberedMigration = readonly [number, Migration];
+
+const firstVersion = 1;
+
+const orderedMigrations = (migrations: Migrations): readonly NumberedMigration[] =>
+  pipe(
+    Rec.toEntries(migrations),
+    Arr.map(([version, run]): NumberedMigration => [Number(version), run]),
+    Arr.sortWith(([version]) => version, Order.Number),
+  );
+
+const conflictError = (history: MigrationHistory, version: number): MigrationEditedError | MigrationMissingError => {
+  if (version > history.declared.length) {
+    return MigrationMissingError.make({ actor: history.actor, version });
+  }
+
+  return MigrationEditedError.make({ actor: history.actor, version });
+};
+
+const pendingMigrations = (
+  history: MigrationHistory,
+): Effect.Effect<readonly DeclaredMigration[], MigrationEditedError | MigrationMissingError> => {
+  const gap = Arr.findFirstIndex(history.declared, (migration, index) => migration.version !== index + firstVersion);
+
+  if (Option.isSome(gap)) {
+    return Effect.fail(MigrationMissingError.make({ actor: history.actor, version: gap.value + firstVersion }));
+  }
+
+  const conflict = Arr.findFirst(history.applied, (applied) =>
+    Option.match(Arr.get(history.declared, applied.version - firstVersion), {
+      onNone: () => true,
+      onSome: (declared) => declared.hash !== applied.hash,
+    }),
+  );
+
+  return Option.match(conflict, {
+    onNone: () => Effect.succeed(Arr.drop(history.declared, history.applied.length)),
+    onSome: (applied) => Effect.fail(conflictError(history, applied.version)),
+  });
+};
+
+export { orderedMigrations, pendingMigrations };
+
+export type { AppliedMigration, DeclaredMigration };

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

@@ -0,0 +1,98 @@
+import { Effect } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import type { OutboxMessage } from "#src/contract/command/outbox.schema";
+
+interface MessageWrite {
+  readonly messages: readonly OutboxMessage[];
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface MessageRemoval {
+  readonly seq: number;
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface FailedDelivery extends MessageRemoval {
+  readonly at: number;
+  readonly error: string;
+  readonly message: PendingMessage;
+}
+
+interface PendingMessage extends OutboxMessage {
+  readonly seq: number;
+}
+
+type Sql<Value> = Effect.Effect<Value, SqlError.SqlError>;
+
+const noSequence = 0;
+const deliveryBytes = 262_144;
+
+const saveMessages = ({ messages, sql }: MessageWrite): Sql<void> =>
+  Effect.forEach(
+    messages,
+    (message) =>
+      sql`INSERT INTO akter_outbox (command_id, actor, key, member, payload) VALUES (${message.commandId}, ${message.actor}, ${message.key}, ${message.member}, ${message.payload})`,
+    { discard: true },
+  );
+
+const pendingMessages = (sql: SqlClient.SqlClient): Sql<readonly PendingMessage[]> =>
+  sql<PendingMessage>`SELECT seq, command_id AS "commandId", actor, key, member, payload FROM akter_outbox ORDER BY seq`;
+
+const pendingThrough = (sql: SqlClient.SqlClient): Sql<number> =>
+  Effect.map(
+    sql<{ readonly seq: number }>`SELECT coalesce(max(seq), 0) AS seq FROM akter_outbox`,
+    (rows) => rows[noSequence]?.seq ?? noSequence,
+  );
+
+const removeMessage = ({ seq, sql }: MessageRemoval): Sql<void> =>
+  Effect.asVoid(sql`DELETE FROM akter_outbox WHERE seq = ${seq}`);
+
+const pendingWindow = ({
+  after,
+  principal,
+  sql,
+  through = Number.MAX_SAFE_INTEGER,
+}: {
+  readonly after: number;
+  readonly principal: string;
+  readonly sql: SqlClient.SqlClient;
+  readonly through?: number;
+}): Sql<readonly PendingMessage[]> =>
+  sql<PendingMessage>`WITH RECURSIVE candidates(seq, bytes) AS (
+    SELECT seq, bytes FROM (
+      SELECT seq, length(CAST(command_id AS BLOB)) + length(CAST(actor AS BLOB)) + length(CAST(key AS BLOB))
+        + length(CAST(member AS BLOB)) + length(CAST(payload AS BLOB)) + length(CAST(${principal} AS BLOB)) AS bytes
+      FROM akter_outbox WHERE seq > ${after} AND seq <= ${through} ORDER BY seq LIMIT 1
+    ) UNION ALL
+    SELECT next.seq, previous.bytes + next.bytes FROM candidates previous JOIN (
+      SELECT seq, length(CAST(command_id AS BLOB)) + length(CAST(actor AS BLOB)) + length(CAST(key AS BLOB))
+        + length(CAST(member AS BLOB)) + length(CAST(payload AS BLOB)) + length(CAST(${principal} AS BLOB)) AS bytes
+      FROM akter_outbox
+    ) next ON next.seq = (SELECT seq FROM akter_outbox WHERE seq > previous.seq AND seq <= ${through} ORDER BY seq LIMIT 1)
+    WHERE previous.bytes + next.bytes <= ${deliveryBytes}
+  ) SELECT seq, command_id AS "commandId", actor, key, member, payload FROM akter_outbox
+    WHERE seq IN (SELECT seq FROM candidates) ORDER BY seq`;
+
+const removePrefix = ({ seq, sql }: MessageRemoval): Sql<void> =>
+  Effect.asVoid(sql`DELETE FROM akter_outbox WHERE seq <= ${seq}`);
+
+const recordFailedDelivery = ({ at, error, message, seq, sql }: FailedDelivery): Sql<void> =>
+  sql.withTransaction(
+    Effect.andThen(
+      sql`INSERT INTO akter_failed_deliveries (command_id, actor, key, member, error, at) VALUES (${message.commandId}, ${message.actor}, ${message.key}, ${message.member}, ${error}, ${at})`,
+      removeMessage({ seq, sql }),
+    ),
+  );
+
+export {
+  pendingMessages,
+  pendingThrough,
+  pendingWindow,
+  recordFailedDelivery,
+  removeMessage,
+  removePrefix,
+  saveMessages,
+};
+
+export type { PendingMessage };

package/src/host/outbox/outbox-acknowledgements.sql.ts

@@ -0,0 +1,93 @@
+import { Effect, Fiber, Option } from "effect";
+import type { Scope } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import { removePrefix } from "./actor-outbox.sql.js";
+
+type Exclusive = <Value, Failure>(effect: Effect.Effect<Value, Failure>) => Effect.Effect<Value, Failure>;
+
+interface Acknowledgements {
+  readonly acknowledge: (seq: number) => Effect.Effect<void, SqlError.SqlError, Scope.Scope>;
+  readonly flush: Effect.Effect<void, SqlError.SqlError>;
+}
+
+interface State {
+  committed: number;
+  pending: Option.Option<Fiber.Fiber<number, SqlError.SqlError>>;
+  through: number;
+}
+
+interface Writing {
+  readonly state: State;
+  readonly write: Effect.Effect<number, SqlError.SqlError>;
+}
+
+const noAcknowledgements = 0;
+
+const queuePrefix = Effect.fnUntraced(function* queuePrefix({ state, write }: Writing, seq: number) {
+  state.through = Math.max(state.through, seq);
+
+  if (state.through <= state.committed) {
+    return;
+  }
+
+  if (Option.isSome(state.pending)) {
+    const previous = state.pending.value;
+
+    if (Option.isNone(Option.fromNullishOr(previous.pollUnsafe()))) {
+      return;
+    }
+
+    state.pending = Option.none();
+    yield* Fiber.join(previous);
+  }
+
+  state.pending = yield* Effect.asSome(Effect.forkScoped(write));
+});
+
+const flushPrefix = ({ state, write }: Writing): Effect.Effect<void, SqlError.SqlError> =>
+  Effect.gen(function* flushPendingPrefix() {
+    if (Option.isSome(state.pending)) {
+      const pending = state.pending.value;
+
+      state.pending = Option.none();
+      yield* Fiber.join(pending);
+    }
+
+    if (state.committed < state.through) {
+      yield* write;
+    }
+  });
+
+const acknowledgements = ({
+  exclusive,
+  sql,
+}: {
+  readonly exclusive: Exclusive;
+  readonly sql: SqlClient.SqlClient;
+}): Effect.Effect<Acknowledgements> =>
+  Effect.sync(() => {
+    const state: State = { committed: noAcknowledgements, pending: Option.none(), through: noAcknowledgements };
+
+    const write = exclusive(
+      Effect.suspend(() => {
+        const seq = state.through;
+
+        return Effect.as(removePrefix({ seq, sql }), seq);
+      }),
+    ).pipe(
+      Effect.tap((seq) =>
+        Effect.sync(() => {
+          state.committed = Math.max(state.committed, seq);
+        }),
+      ),
+    );
+
+    const writing = { state, write };
+
+    return { acknowledge: (seq) => queuePrefix(writing, seq), flush: flushPrefix(writing) };
+  });
+
+export { acknowledgements };
+
+export type { Acknowledgements };

package/src/host/outbox/outbox-runner.service.ts

@@ -0,0 +1,253 @@
+import { Array as Arr, Clock, Context, Effect, Layer, Option, Predicate, Result, Schema, Scope } from "effect";
+import type { SqlError } from "effect/sql";
+
+import type { HostedError } from "#src/contract/actor/actor.contract";
+import { Caller, actorKind } from "#src/contract/caller/caller.schema";
+import { jsonCodec } from "#src/contract/json-codec.pure";
+import type { OutboxMessage } from "#src/contract/command/outbox.schema";
+import type { OpenedActor } from "#src/host/actor/actor-database.service";
+import { pendingThrough, pendingWindow, recordFailedDelivery } from "./actor-outbox.sql.js";
+import type { PendingMessage } from "./actor-outbox.sql.js";
+import { acknowledgements } from "./outbox-acknowledgements.sql.js";
+import type { Acknowledgements } from "./outbox-acknowledgements.sql.js";
+
+interface Delivery extends OutboxMessage {
+  readonly principal: string;
+}
+
+type DeliveryBatch<Failure> = (
+  deliveries: readonly Delivery[],
+) => Effect.Effect<readonly Result.Result<void, Failure>[], Failure>;
+
+interface Delivering<Failure> {
+  readonly exclusive: <Success, Error, Needs>(
+    effect: Effect.Effect<Success, Error, Needs>,
+  ) => Effect.Effect<Success, Error, Needs>;
+  readonly key: string;
+  readonly opened: OpenedActor;
+  readonly send: DeliveryBatch<Failure>;
+}
+
+interface Producing<Failure> extends Delivering<Failure> {
+  readonly committed: Effect.Effect<number>;
+  readonly read: Delivering<Failure>["exclusive"];
+}
+
+interface DeliverySession<Failure> {
+  readonly deliver: Effect.Effect<readonly string[], Failure | SqlError.SqlError>;
+  readonly flush: Effect.Effect<void, SqlError.SqlError>;
+}
+
+interface Settled {
+  readonly ids: string[];
+  prefix: readonly PendingMessage[];
+  through: number;
+}
+
+interface Settling<Failure> {
+  readonly acknowledger: Acknowledgements;
+  readonly delivering: Delivering<Failure>;
+}
+
+const noSequence = 0;
+const targetWindow = 64;
+
+const refusals: readonly HostedError["_tag"][] = [
+  "ActorAlreadyExistsError",
+  "ActorNotCreatedError",
+  "CallerNotAllowedError",
+  "CommandIdExpiredError",
+  "InvalidRequestError",
+];
+
+const refused = Effect.fnUntraced(function* refused(opened: OpenedActor, message: PendingMessage, error: string) {
+  const at = yield* Clock.currentTimeMillis;
+
+  yield* recordFailedDelivery({ at, error, message, seq: message.seq, sql: opened.sql });
+  yield* Effect.logWarning(`${message.commandId} was refused by ${message.actor}/${message.key} with ${error}`);
+});
+
+const sequentialDeliveries = <Failure, Needs>(
+  send: (delivery: Delivery) => Effect.Effect<unknown, Failure, Needs>,
+): ((deliveries: readonly Delivery[]) => Effect.Effect<readonly Result.Result<void, Failure>[], never, Needs>) =>
+  Effect.fnUntraced(function* sendSequential(deliveries: readonly Delivery[]) {
+    const results: Result.Result<void, Failure>[] = [];
+
+    for (const delivery of deliveries) {
+      const result = yield* Effect.result(Effect.asVoid(send(delivery)));
+
+      results.push(result);
+
+      if (Result.isFailure(result)) {
+        break;
+      }
+    }
+
+    return results;
+  });
+
+const flushSettled = Effect.fnUntraced(function* flushSettled(acknowledger: Acknowledgements, state: Settled) {
+  const last = Arr.last(state.prefix);
+
+  if (Option.isSome(last)) {
+    yield* acknowledger.acknowledge(last.value.seq);
+    state.ids.push(...Arr.map(state.prefix, (message) => message.commandId));
+    state.through = last.value.seq;
+    state.prefix = [];
+  }
+});
+
+const settleOne = Effect.fnUntraced(function* settleOne<Failure>(
+  { acknowledger, delivering }: Settling<Failure>,
+  state: Settled,
+  [message, result]: readonly [PendingMessage, Result.Result<void, Failure>],
+) {
+  if (Result.isSuccess(result) || Predicate.isTagged(result.failure, "HandlerFailedError")) {
+    state.prefix = Arr.append(state.prefix, message);
+
+    return;
+  }
+
+  yield* flushSettled(acknowledger, state);
+  const refusal = Arr.findFirst(refusals, (tag) => Predicate.isTagged(result.failure, tag));
+
+  yield* Option.match(refusal, {
+    onNone: () => Effect.fail(result.failure),
+    onSome: (error) =>
+      Effect.andThen(acknowledger.flush, delivering.exclusive(refused(delivering.opened, message, error))),
+  });
+  state.ids.push(message.commandId);
+  state.through = message.seq;
+});
+
+const settleWindow = Effect.fnUntraced(function* settleWindow<Failure>(
+  kit: Settling<Failure>,
+  messages: readonly PendingMessage[],
+  results: readonly Result.Result<void, Failure>[],
+) {
+  const state: Settled = { ids: [], prefix: [], through: noSequence };
+
+  yield* Effect.forEach(Arr.zip(messages, results), (entry) => settleOne(kit, state, entry), { discard: true });
+  yield* flushSettled(kit.acknowledger, state);
+
+  if (Arr.isReadonlyArrayEmpty(state.ids)) {
+    return yield* Effect.die("the target batch returned no acknowledgement");
+  }
+
+  return state;
+});
+
+const sendWindow = Effect.fnUntraced(function* sendWindow<Failure>(
+  kit: Settling<Failure>,
+  messages: readonly PendingMessage[],
+  principal: string,
+) {
+  const deliveries = Arr.map(messages, ({ seq: _seq, ...outgoing }) => ({ ...outgoing, principal }));
+  const sent = yield* Effect.result(kit.delivering.send(deliveries));
+
+  const results = Result.match(sent, {
+    onFailure: (failure) => [Result.fail(failure)],
+    onSuccess: (outcomes) => outcomes,
+  });
+
+  return yield* settleWindow(kit, messages, results);
+});
+
+const deliverBlock = Effect.fnUntraced(function* deliverBlock<Failure>(
+  kit: Settling<Failure>,
+  pending: readonly PendingMessage[],
+  principal: string,
+) {
+  const state: Settled = { ids: [], prefix: pending, through: noSequence };
+
+  while (Arr.isReadonlyArrayNonEmpty(state.prefix)) {
+    const [first] = state.prefix;
+
+    const window = Arr.take(
+      Arr.takeWhile(state.prefix, (message) => message.actor === first.actor && message.key === first.key),
+      targetWindow,
+    );
+
+    const settled = yield* sendWindow(kit, window, principal);
+
+    state.ids.push(...settled.ids);
+    state.through = settled.through;
+    state.prefix = Arr.drop(state.prefix, settled.ids.length);
+  }
+
+  return state;
+});
+
+const open = Effect.fnUntraced(function* open<Failure>(delivering: Producing<Failure>) {
+  const scope = yield* Effect.scope;
+  const actor = delivering.opened.actor.name;
+
+  const principal = yield* Effect.orDie(
+    Schema.encodeEffect(jsonCodec(Caller))({
+      kind: actorKind,
+      principal: { actor, id: `${actor}/${delivering.key}`, key: delivering.key },
+    }),
+  );
+
+  const acknowledger = yield* acknowledgements({ exclusive: delivering.exclusive, sql: delivering.opened.sql });
+  let after = noSequence;
+
+  // Nothing committed past what this session delivered needs no SQL: seq only grows (AUTOINCREMENT).
+  const pendingAfter = (through: number): Effect.Effect<readonly PendingMessage[], SqlError.SqlError> => {
+    if (through <= after) {
+      return Effect.succeed([]);
+    }
+
+    return pendingWindow({ after, principal, sql: delivering.opened.sql, through });
+  };
+
+  const deliver = Effect.gen(function* nextBlock() {
+    const pending = yield* delivering.read(Effect.flatMap(delivering.committed, pendingAfter));
+
+    const settled = yield* deliverBlock({ acknowledger, delivering }, pending, principal);
+
+    if (Arr.isReadonlyArrayNonEmpty(settled.ids)) {
+      after = settled.through;
+    } else {
+      yield* acknowledger.flush;
+    }
+
+    return settled.ids;
+  }).pipe(Scope.provide(scope));
+
+  return { deliver, flush: acknowledger.flush };
+});
+
+const deliver = <Failure>(
+  delivering: Delivering<Failure>,
+): Effect.Effect<readonly string[], Failure | SqlError.SqlError> =>
+  Effect.scoped(
+    Effect.gen(function* deliverOnce() {
+      const through = yield* delivering.exclusive(pendingThrough(delivering.opened.sql));
+      const session = yield* open({ ...delivering, committed: Effect.succeed(through), read: delivering.exclusive });
+      const result = yield* Effect.exit(session.deliver);
+
+      yield* session.flush;
+
+      return yield* result;
+    }),
+  );
+
+export class OutboxRunner extends Context.Service<
+  OutboxRunner,
+  {
+    readonly deliver: <Failure>(
+      delivering: Delivering<Failure>,
+    ) => Effect.Effect<readonly string[], Failure | SqlError.SqlError>;
+    readonly open: <Failure>(
+      delivering: Producing<Failure>,
+    ) => Effect.Effect<DeliverySession<Failure>, never, Scope.Scope>;
+  }
+>()("@akterjs/effect/host/outbox/outbox-runner.service/OutboxRunner", {
+  make: Effect.succeed({ deliver, open }),
+}) {
+  public static readonly sequentialDeliveries = sequentialDeliveries;
+  public static readonly layer = Layer.effect(this, this.make);
+}
+
+export type { Delivery, DeliveryBatch, DeliverySession };

package/src/host/query/query-policy.pure.ts

@@ -0,0 +1,31 @@
+import { Context, Option, String as Str } from "effect";
+import type { SqlError } from "effect/sql";
+
+interface QueryReadScope {
+  readonly refusal: () => Option.Option<SqlError.SqlError>;
+  readonly refuse: (failure: SqlError.SqlError) => void;
+}
+
+const QueryReadOnly = Context.Reference<Option.Option<QueryReadScope>>(
+  "@akterjs/effect/host/query/query-policy.pure/QueryReadOnly",
+  {
+    defaultValue: Option.none,
+  },
+);
+
+/**
+ * True while a statement comes from an actor's own handler code. A handler may read the engine-owned `akter_*`
+ * tables but never write them; the engine's own journal, state and outbox writes run with this false.
+ */
+const HandlerSql = Context.Reference<boolean>("@akterjs/effect/host/query/query-policy.pure/HandlerSql", {
+  defaultValue: () => false,
+});
+
+const engineTablePrefix = "akter_";
+
+/** Whether a write to `table` in the main database is refused to handler SQL. */
+const engineOwned = (table: string): boolean => Str.startsWith(engineTablePrefix)(Str.toLowerCase(table));
+
+export { engineOwned, HandlerSql, QueryReadOnly };
+
+export type { QueryReadScope };

package/src/host/query/query-runner.service.ts

@@ -0,0 +1,132 @@
+import { Clock, Context, Effect, Layer, Option, Record as Rec } from "effect";
+import type { SqlError } from "effect/sql";
+
+import type { JournalWindow } from "#src/contract/history/actor-journal.service";
+import type { HostedError } from "#src/contract/actor/actor.contract";
+
+import type { OpenedActor } from "#src/host/actor/actor-database.service";
+import { currentState, journalSince, prunedBefore } from "#src/host/command/command-journal.sql";
+import { fileUsagePage } from "#src/host/blob/reference/blob-file-page.sql";
+import type { FileListing } from "#src/contract/file/actor-files.contract";
+import { stepByKey, stepsPage } from "#src/host/computer/computer-steps.sql";
+import { QueryReadOnly } from "./query-policy.pure.js";
+import type { QueryReadScope } from "./query-policy.pure.js";
+
+interface QueryRequest {
+  readonly key: string;
+  readonly member: string;
+  readonly payload: string;
+  readonly principal: string;
+}
+
+interface Querying {
+  readonly opened: OpenedActor;
+  readonly request: QueryRequest;
+}
+
+interface CoverageReading {
+  readonly opened: OpenedActor;
+  readonly since: number;
+}
+
+interface HistoryReading extends CoverageReading {
+  readonly after: number;
+  readonly limit: number;
+}
+
+const coveredSince = ({ opened, since }: CoverageReading): Effect.Effect<number, SqlError.SqlError> =>
+  Effect.map(prunedBefore(opened.reader), (cut) =>
+    Math.max(
+      since,
+      Option.getOrElse(cut, () => since),
+    ),
+  );
+
+const history = Effect.fn("QueryRunner.history")(function* history(reading: HistoryReading) {
+  const entries = yield* journalSince({
+    after: reading.after,
+    limit: reading.limit,
+    since: reading.since,
+    sql: reading.opened.reader,
+  });
+
+  const covered = yield* coveredSince(reading);
+
+  return { coveredSince: covered, entries };
+});
+
+const runLocked = Effect.fn("QueryRunner.runLocked")(function* run({
+  opened: { actor, files, reader },
+  request,
+}: Querying) {
+  const policy = { refused: Option.none<SqlError.SqlError>() };
+
+  const scope: QueryReadScope = {
+    refusal: () => policy.refused,
+    refuse: (failure) => {
+      if (Option.isNone(policy.refused)) {
+        policy.refused = Option.some(failure);
+      }
+    },
+  };
+
+  const reading = reader
+    .withTransaction(
+      Effect.gen(function* snapshot() {
+        const state = yield* currentState(reader);
+
+        return yield* actor.runQuery(
+          { ...request, state },
+          {
+            files: files(reader),
+            id: Effect.die(`${actor.name}: a query never mints ids`),
+            key: request.key,
+            now: Clock.currentTimeMillis,
+            sql: reader,
+          },
+        );
+      }),
+    )
+    .pipe(Effect.provideService(QueryReadOnly, Option.some(scope)));
+
+  const exit = yield* Effect.exit(reading);
+
+  return yield* Option.match(scope.refusal(), { onNone: () => exit, onSome: Effect.fail });
+});
+
+const run = (querying: Querying): ReturnType<typeof runLocked> =>
+  Option.match(Option.fromNullishOr(querying.opened.fileSession), {
+    onNone: () => runLocked(querying),
+    onSome: ({ home, owner }) => home.transfers.admit(owner.snapshot(runLocked(querying))),
+  });
+
+export class QueryRunner extends Context.Service<
+  QueryRunner,
+  {
+    readonly coveredSince: (reading: CoverageReading) => Effect.Effect<number, SqlError.SqlError>;
+    readonly files: (opened: OpenedActor, listing?: FileListing) => ReturnType<typeof fileUsagePage>;
+    readonly history: (reading: HistoryReading) => Effect.Effect<JournalWindow, SqlError.SqlError>;
+    readonly run: (querying: Querying) => Effect.Effect<string, HostedError | SqlError.SqlError>;
+    readonly runLocked: (querying: Querying) => Effect.Effect<string, HostedError | SqlError.SqlError>;
+    /** The actor's durable computer steps, newest first, without output (`Akter`'s `step`). */
+    readonly steps: (opened: OpenedActor, limit?: number) => ReturnType<typeof stepsPage>;
+    /** One durable computer step by its key, with its output. */
+    readonly step: (opened: OpenedActor, step: string) => ReturnType<typeof stepByKey>;
+  }
+>()("@akterjs/effect/host/query/query-runner.service/QueryRunner") {
+  public static readonly layer = Layer.succeed(this, {
+    coveredSince,
+    files: (opened: OpenedActor, listing: FileListing = {}) =>
+      fileUsagePage({ actor: opened.fileSession?.owner.actor ?? "", listing, sql: opened.reader }),
+    history,
+    run,
+    runLocked,
+    step: (opened: OpenedActor, step: string) => stepByKey({ sql: opened.reader, step }),
+    steps: (opened: OpenedActor, limit?: number) =>
+      stepsPage({ ...Rec.getSomes({ limit: Option.fromUndefinedOr(limit) }), sql: opened.reader }),
+  });
+}
+
+export type { QueryRequest };
+
+export type { FileUsagePage as FileUsage } from "#src/contract/file/actor-files.contract";