@akterjs/effect 0.0.0-stage → 0.1.0

package/src/host/computer/local-computers.adapter.ts

@@ -0,0 +1,379 @@
+import {
+  Array as Arr,
+  Clock,
+  Context,
+  Effect,
+  FileSystem,
+  MutableHashMap,
+  Option,
+  Path,
+  Semaphore,
+  String as Str,
+} from "effect";
+
+import { ActorComputerClients } from "#src/contract/computer/computer-client.adapter";
+import type {
+  ComputerAddress,
+  ComputerClient,
+  ComputerClientFailure,
+  ComputerFork,
+  ComputerHold,
+} from "#src/contract/computer/computer-client.contract";
+import { ComputerHeldError } from "#src/contract/computer/computer-held.errors";
+import { ComputersUnavailableError } from "#src/contract/computer/computers-unavailable.errors";
+import { logPageLines } from "#src/contract/computer/computer.schema";
+import type { Computer, ComputerSpec, ExecRequest, ExecResult } from "#src/contract/computer/computer.schema";
+import { localLog } from "./local-computer-log.layer.js";
+import type { LocalLog } from "./local-computer-log.layer.js";
+import {
+  admitted,
+  computerOf,
+  findRecord,
+  keySegment,
+  listed,
+  movedTo,
+  notHeld,
+  placeOf,
+  present,
+  recordFor,
+  saveRecord,
+} from "./local-computer-records.layer.js";
+import type { Failing, Place, Store } from "./local-computer-records.layer.js";
+import { runStep } from "./local-step.layer.js";
+import type { StepServices } from "./local-step.layer.js";
+import { localComputerFile } from "./local-computer-files.layer.js";
+
+/** Steps on one computer share it; anything that moves, forks or removes it takes every permit. */
+const allPermits = 8;
+const onePermit = 1;
+const fromStart = 0;
+
+type Answer<Value> = Effect.Effect<Value, Failing, StepServices>;
+
+interface Local extends Store {
+  readonly locks: MutableHashMap.MutableHashMap<string, Semaphore.Semaphore>;
+  readonly log: LocalLog;
+}
+
+const locked =
+  (local: Local, place: Place, permits: number) =>
+  <Value, Failure, Services>(
+    effect: Effect.Effect<Value, Failure, Services>,
+  ): Effect.Effect<Value, Failure, Services> =>
+    Effect.suspend(() => {
+      const found = MutableHashMap.get(local.locks, place.directory);
+      const lock = Option.getOrElse(found, () => Semaphore.makeUnsafe(allPermits));
+
+      MutableHashMap.set(local.locks, place.directory, lock);
+
+      return lock.withPermits(permits)(effect);
+    });
+
+const heldNote = (hold: string | undefined, verb: string): string =>
+  Option.match(Option.fromUndefinedOr(hold), { onNone: () => "", onSome: (held) => ` (${verb} ${held})` });
+
+const made = Effect.fnUntraced(function* made(local: Local, place: Place, spec: ComputerSpec) {
+  const fs = yield* FileSystem.FileSystem;
+  const { image, size } = spec;
+
+  yield* fs.makeDirectory(place.disk, { recursive: true });
+
+  const createdAt = yield* Clock.currentTimeMillis;
+  const record = yield* saveRecord(place, { createdAt, spec, state: "running" });
+  const message = `starting from ${image}, ${String(size.vcpu)} vCPU and ${String(size.memoryMib)} MiB`;
+
+  yield* local.log.note(place, "info", message);
+
+  return yield* computerOf(place, record);
+});
+
+/** An existing computer keeps its image and size and takes the new spec's egress and secrets. */
+const ensureIn = (local: Local, place: Place, spec: ComputerSpec): Answer<Computer> =>
+  Effect.flatMap(findRecord(place), (found) =>
+    Option.match(found, {
+      onNone: () => admitted({ computer: spec.name, store: local })(made(local, place, spec)),
+      onSome: (record) =>
+        Effect.gen(function* ensureExisting() {
+          yield* notHeld(record);
+          yield* present(place);
+
+          const keeping = { ...spec, image: record.spec.image, size: record.spec.size };
+          const saved = yield* saveRecord(place, { ...record, spec: keeping });
+
+          return yield* computerOf(place, saved);
+        }),
+    }),
+  );
+
+/** A step starts its computer first when it is paused or stopped, as the hosted engine does. */
+const execIn = (local: Local, place: Place, request: ExecRequest): Answer<ExecResult> =>
+  Effect.gen(function* execInComputer() {
+    const record = yield* recordFor(place);
+
+    yield* notHeld(record);
+    yield* movedTo(place, record, "running");
+
+    const step = local.path.join(place.steps, keySegment(request.key));
+    const result = yield* runStep({ disk: place.disk, step }, request);
+
+    yield* local.log.step(place, request.key, result);
+
+    return result;
+  });
+
+/** A pause moves a live computer to paused, but a stopped one stays stopped, with or without a hold. */
+const pausedState = (record: Computered): Computered["state"] => {
+  if (record.state === "stopped") {
+    return "stopped";
+  }
+
+  return "paused";
+};
+
+/**
+ * A hold keeps the computer paused, or stopped when it was stopped; the same hold sent again is a resend, any other
+ * is refused.
+ */
+const pauseIn = (local: Local, place: Place, { hold }: ComputerHold): Answer<Computer> =>
+  Effect.gen(function* pauseComputer() {
+    const record = yield* recordFor(place);
+    const holding = Option.fromUndefinedOr(hold);
+    const taken = Option.fromUndefinedOr(record.hold);
+    const other = Option.filter(taken, (held) => !Option.contains(holding, held.hold));
+
+    if (Option.isSome(other)) {
+      return yield* ComputerHeldError.make({ computer: place.name, hold: other.value.hold });
+    }
+
+    const kept = Option.match(
+      Option.filter(holding, () => Option.isNone(taken)),
+      {
+        onNone: () => record,
+        onSome: (held) => ({ ...record, hold: { from: record.state, hold: held } }),
+      },
+    );
+
+    const paused = yield* movedTo(place, kept, pausedState(kept));
+
+    yield* local.log.note(place, "info", `${paused.state}${heldNote(hold, "held by")}`);
+
+    return yield* computerOf(place, paused);
+  });
+
+interface Releasing {
+  readonly hold: string | undefined;
+  readonly record: Computered;
+}
+
+const released = (local: Local, place: Place, { hold, record }: Releasing): Answer<Computer> =>
+  Effect.gen(function* releaseComputer() {
+    const { hold: taken, ...rest } = record;
+
+    const target = Option.match(Option.fromUndefinedOr(taken), {
+      onNone: () => "running" as const,
+      onSome: ({ from }) => from,
+    });
+
+    const resumed = yield* movedTo(place, rest, target);
+
+    yield* local.log.note(place, "info", `resumed${heldNote(hold, "released by")}`);
+
+    return yield* computerOf(place, resumed);
+  });
+
+type Computered = Effect.Success<ReturnType<typeof recordFor>>;
+
+/**
+ * A resume with the computer's hold returns it where the held pause found it; any other resume of a held computer is
+ * refused, and a resume carrying a hold on a computer no longer held is a resend after the release.
+ */
+const resumeIn = (local: Local, place: Place, { hold }: ComputerHold): Answer<Computer> =>
+  Effect.gen(function* resumeComputer() {
+    const record = yield* recordFor(place);
+    const taken = Option.fromUndefinedOr(record.hold);
+    const holding = Option.fromUndefinedOr(hold);
+
+    if (Option.isNone(taken) && Option.isSome(holding)) {
+      return yield* computerOf(place, record);
+    }
+
+    const refusing = Option.filter(taken, (held) => !Option.contains(holding, held.hold));
+
+    if (Option.isSome(refusing)) {
+      return yield* ComputerHeldError.make({ computer: place.name, hold: refusing.value.hold });
+    }
+
+    return yield* released(local, place, { hold, record });
+  });
+
+const stopIn = (local: Local, place: Place): Answer<Computer> =>
+  Effect.gen(function* stopComputer() {
+    const record = yield* recordFor(place);
+    const stopped = yield* movedTo(place, record, "stopped");
+
+    yield* local.log.note(place, "info", "stopped");
+
+    return yield* computerOf(place, stopped);
+  });
+
+/** Removes the computer with its disk; its log stays. A resend finds nothing to remove. */
+const removeIn = (local: Local, place: Place): Effect.Effect<void, Failing, FileSystem.FileSystem> =>
+  Effect.gen(function* removeComputer() {
+    const fs = yield* FileSystem.FileSystem;
+    const found = yield* findRecord(place);
+
+    if (Option.isNone(found)) {
+      return;
+    }
+
+    yield* fs.remove(place.directory, { recursive: true });
+    yield* local.log.note(place, "info", "deleted with its disk");
+  });
+
+const copied = Effect.fnUntraced(function* copied(source: Place, target: Place, spec: ComputerSpec) {
+  const fs = yield* FileSystem.FileSystem;
+
+  yield* fs.makeDirectory(target.directory, { recursive: true });
+  yield* fs.copy(source.disk, target.disk);
+
+  const createdAt = yield* Clock.currentTimeMillis;
+
+  return yield* saveRecord(target, { createdAt, spec, state: "running" });
+});
+
+/** Copies the computer's disk to the target actor under its name or a new one; a resend finds the copy made. */
+const forkIn = (local: Local, place: Place, fork: ComputerFork): Answer<Computer> =>
+  Effect.gen(function* forkComputer() {
+    const record = yield* recordFor(place);
+    const name = fork.name ?? record.spec.name;
+    const target = placeOf(local)(fork.into, name);
+    const existing = yield* findRecord(target);
+
+    if (Option.isSome(existing)) {
+      return yield* computerOf(target, existing.value);
+    }
+
+    yield* present(place);
+
+    const forked = yield* admitted({ computer: name, store: local })(copied(place, target, { ...record.spec, name }));
+
+    yield* local.log.note(place, "info", `forked into ${fork.into.actor}/${fork.into.key}${heldNote(fork.name, "as")}`);
+
+    return yield* computerOf(target, forked);
+  });
+
+const getIn = (place: Place): Answer<Computer> =>
+  Effect.flatMap(recordFor(place), (record) => computerOf(place, record));
+
+const listIn = (
+  local: Local,
+  address: ComputerAddress,
+): Effect.Effect<readonly Computer[], Failing, FileSystem.FileSystem> =>
+  Effect.gen(function* listComputers() {
+    const names = yield* listed(placeOf(local)(address, "").actor);
+    const places = Arr.map(Arr.sort(names, Str.Order), (name) => placeOf(local)(address, name));
+
+    const found = yield* Effect.forEach(places, (place) =>
+      Effect.map(
+        findRecord(place),
+        Option.map((record) => ({ place, record })),
+      ),
+    );
+
+    return yield* Effect.forEach(Arr.getSomes(found), ({ place, record }) => computerOf(place, record));
+  });
+
+const unavailable = (): ComputersUnavailableError =>
+  ComputersUnavailableError.make({ message: "the local computer directory is unavailable" });
+
+/** Runs one operation with the engine's services, answering a directory or decoding failure as unavailable. */
+const answeredWith =
+  (services: Context.Context<StepServices>) =>
+  <Value>(answer: Answer<Value>): Effect.Effect<Value, ComputerClientFailure> =>
+    answer.pipe(
+      Effect.catchTags({
+        PlatformError: () => Effect.fail(unavailable()),
+        SchemaError: () => Effect.fail(unavailable()),
+      }),
+      Effect.provideContext(services),
+    );
+
+type Answered = ReturnType<typeof answeredWith>;
+
+const clientFor =
+  (local: Local, answered: Answered) =>
+  (address: ComputerAddress): ComputerClient => {
+    const at = (name: string): Place => placeOf(local)(address, name);
+
+    const holding =
+      (permits: number) =>
+      <Value>(name: string, use: (place: Place) => Answer<Value>): Effect.Effect<Value, ComputerClientFailure> => {
+        const place = at(name);
+        const held = locked(local, place, permits);
+
+        return answered(held(use(place)));
+      };
+
+    const moving = holding(allPermits);
+
+    return {
+      ensure: (spec) => moving(spec.name, (place) => ensureIn(local, place, spec)),
+      exec: (computer, request) => holding(onePermit)(computer, (place) => execIn(local, place, request)),
+      files: (computer, request) => moving(computer, (place) => localComputerFile(place, request)),
+      fork: (computer, fork) => moving(computer, (place) => forkIn(local, place, fork)),
+      get: (computer) => answered(getIn(at(computer))),
+      list: answered(listIn(local, address)),
+      pause: (computer, hold = {}) => moving(computer, (place) => pauseIn(local, place, hold)),
+      remove: (computer) => moving(computer, (place) => removeIn(local, place)),
+      resume: (computer, hold = {}) => moving(computer, (place) => resumeIn(local, place, hold)),
+      stop: (computer) => moving(computer, (place) => stopIn(local, place)),
+    };
+  };
+
+/**
+ * Computers on the local disk, under `root`: each one a directory holding its record, its disk and its steps, under
+ * the actor's type and key. A step runs as `sh -c` with the disk as its home, once by its key, and a computer keeps
+ * its files across pause, resume, stop and engine restarts. It keeps no process past the step that started it, and
+ * its egress, ingress and credential bindings are recorded, not enforced: the local engine is not a sandbox.
+ */
+const localAt = Effect.fnUntraced(function* localAt(root: string) {
+  const path = yield* Path.Path;
+  const admission = yield* Semaphore.make(onePermit);
+
+  return {
+    admission,
+    locks: MutableHashMap.empty<string, Semaphore.Semaphore>(),
+    log: localLog(path),
+    path,
+    root,
+  } satisfies Local;
+});
+
+/** The erasure path uses the same disk-and-record removal as computer.remove, after the actor's jobs have stopped. */
+const removeLocalActorComputers = Effect.fnUntraced(function* removeLocalActorComputers(
+  root: string,
+  address: ComputerAddress,
+) {
+  const local = yield* localAt(root);
+  const computers = yield* listIn(local, address);
+  yield* Effect.forEach(computers, ({ name }) => removeIn(local, placeOf(local)(address, name)), { discard: true });
+});
+
+const localComputers = Effect.fnUntraced(function* localComputers(root: string) {
+  const services = yield* Effect.context<StepServices>();
+  const local = yield* localAt(root);
+  const answered = answeredWith(services);
+
+  return ActorComputerClients.of({
+    connect: clientFor(local, answered),
+    logs: (address, computer, page) =>
+      answered(local.log.page(placeOf(local)(address, computer), page.after ?? fromStart, page.limit ?? logPageLines)),
+  });
+});
+
+export class LocalComputers extends Context.Service<LocalComputers, ActorComputerClients["Service"]>()(
+  "@akterjs/effect/host/computer/local-computers.adapter/LocalComputers",
+) {
+  public static readonly make = localComputers;
+  public static readonly remove = removeLocalActorComputers;
+}

package/src/host/computer/local-step.layer.ts

@@ -0,0 +1,174 @@
+import { Duration, Effect, Fiber, FileSystem, Option, Path, Schema, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+
+import { ExecRan, ExecUnknown, execLimits } from "#src/contract/computer/computer.schema";
+import type { ExecRequest, ExecResult } from "#src/contract/computer/computer.schema";
+import { StatusJson } from "./local-computer.schema.js";
+
+/** Where one step runs and records itself on a local computer. */
+interface StepPlace {
+  /** The computer's disk: its home and the directory a step's `cwd` is resolved under. */
+  readonly disk: string;
+  /** The step's own directory, named by its key: its whole output and, once it ends, its status. */
+  readonly step: string;
+}
+
+type StepServices = ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path;
+
+type Handle = ChildProcessSpawner.ChildProcessHandle;
+
+/** A fixed search path, so a step finds the same tools whatever environment `akter dev` was started in. */
+const searchPath = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin";
+
+const bothStreams = 2;
+
+const oneMore = 1;
+
+const start = 0;
+
+const decoder = new globalThis.TextDecoder();
+
+const encodeStatus = Schema.encodeEffect(StatusJson);
+
+const decodeStatus = Schema.decodeUnknownEffect(StatusJson);
+
+const exitField = (exitCode: Option.Option<number>): { readonly exitCode?: number } =>
+  Option.match(exitCode, { onNone: () => ({}), onSome: (code) => ({ exitCode: code }) });
+
+/** At most `execLimits.outputBytes` of a stream file, and whether the file held more. */
+const head = Effect.fnUntraced(function* head(file: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const opened = yield* fs.open(file);
+  const read = yield* opened.readAlloc(execLimits.outputBytes + oneMore);
+  const bytes = Option.getOrElse(read, () => new Uint8Array());
+
+  return {
+    over: bytes.byteLength > execLimits.outputBytes,
+    text: decoder.decode(bytes.subarray(start, execLimits.outputBytes)),
+  };
+}, Effect.scoped);
+
+const ranFrom = Effect.fnUntraced(function* ranFrom(step: string, exitCode: Option.Option<number>) {
+  const path = yield* Path.Path;
+  const stdout = yield* head(path.join(step, "stdout"));
+  const stderr = yield* head(path.join(step, "stderr"));
+
+  const ran: ExecResult = ExecRan.make({
+    ...exitField(exitCode),
+    stderr: stderr.text,
+    stdout: stdout.text,
+    truncated: stdout.over || stderr.over,
+  });
+
+  return ran;
+});
+
+/**
+ * The step was sent before: its recorded outcome when it ended, or `Unknown` when it started and never recorded one,
+ * because the engine stopped while it ran or it is running now. It never runs again.
+ */
+const readBack = Effect.fnUntraced(function* readBack(step: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const recorded = fs.readFileString(path.join(step, "status"));
+  const status = yield* Effect.option(Effect.flatMap(recorded, decodeStatus));
+
+  return yield* Option.match(status, {
+    onNone: () => Effect.succeed<ExecResult>(ExecUnknown.make({})),
+    onSome: ({ exitCode }) => ranFrom(step, Option.fromUndefinedOr(exitCode)),
+  });
+});
+
+const stdinOf = (request: ExecRequest): ChildProcess.CommandInput =>
+  Option.match(Option.fromUndefinedOr(request.stdin), {
+    onNone: () => "ignore",
+    onSome: (bytes) => Stream.make(bytes),
+  });
+
+/** Writes each of the step's streams whole into its directory, while it runs. */
+const recordOutput = Effect.fnUntraced(function* recordOutput(handle: Handle, step: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const stdout = Stream.run(handle.stdout, fs.sink(path.join(step, "stdout")));
+  const stderr = Stream.run(handle.stderr, fs.sink(path.join(step, "stderr")));
+
+  return yield* Effect.forkChild(Effect.all([stdout, stderr], { concurrency: bothStreams }));
+});
+
+const spawned = Effect.fnUntraced(function* spawned({ disk }: StepPlace, request: ExecRequest) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const cwd = path.join(disk, request.cwd ?? ".");
+  const env = { HOME: disk, LANG: "C.UTF-8", PATH: searchPath };
+
+  yield* fs.makeDirectory(cwd, { recursive: true });
+
+  return yield* spawner.spawn(
+    ChildProcess.make("sh", ["-c", request.command], { cwd, env, extendEnv: false, stdin: stdinOf(request) }),
+  );
+});
+
+/** Writes the step's end last, so a step with a status is a step that ended. */
+const recordStatus = Effect.fnUntraced(function* recordStatus(step: string, exitCode: Option.Option<number>) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const status = yield* exitCode.pipe(exitField, encodeStatus);
+
+  yield* fs.writeFileString(path.join(step, "status"), status);
+
+  return exitCode;
+});
+
+/**
+ * Runs the step's command with `sh` in its own process group, under the computer's disk. Past its time limit the
+ * group is killed and the step ends without an exit code. When the step ends its group ends too, because a process it
+ * left behind could hold its output open, so a local computer keeps no process past the step that started it.
+ */
+const run = Effect.fnUntraced(function* run(place: StepPlace, request: ExecRequest) {
+  const handle = yield* spawned(place, request);
+  const output = yield* recordOutput(handle, place.step);
+
+  const ended = yield* Effect.timeoutOption(
+    handle.exitCode,
+    Duration.seconds(request.timeoutSeconds ?? execLimits.seconds),
+  );
+
+  yield* Effect.ignore(handle.kill({ killSignal: "SIGKILL" }));
+  yield* Fiber.join(output);
+
+  return yield* recordStatus(place.step, Option.map(ended, Number));
+}, Effect.scoped);
+
+/** Makes the step's directory, which fails when it exists: only the first send of a key gets to run it. */
+const claim = Effect.fnUntraced(function* claim(step: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  yield* fs.makeDirectory(path.dirname(step), { recursive: true });
+
+  return yield* fs.makeDirectory(step).pipe(
+    Effect.as(true),
+    Effect.catchReason("PlatformError", "AlreadyExists", () => Effect.succeed(false)),
+  );
+});
+
+/**
+ * Runs one step once by its key. A step sent again reads its outcome back instead of running a second time, the same
+ * contract the hosted engine keeps.
+ */
+const runStep = Effect.fnUntraced(function* runStep(place: StepPlace, request: ExecRequest) {
+  const claimed = yield* claim(place.step);
+
+  if (!claimed) {
+    return yield* readBack(place.step);
+  }
+
+  const exitCode = yield* run(place, request);
+
+  return yield* ranFrom(place.step, exitCode);
+});
+
+export { runStep };
+
+export type { StepPlace, StepServices };

package/src/host/file/actor-file-storage.sql.ts

@@ -0,0 +1,79 @@
+import { Effect, Option, Stream } from "effect";
+import type { SqlClient } from "effect/sql";
+
+import type { FileFailure, FileRef, FileStorage } from "#src/contract/file/actor-files.contract";
+import { FilesUnavailableError } from "#src/contract/file/files-unavailable.errors";
+import { FileNotFoundError } from "#src/contract/file/file-not-found.errors";
+import { filePathOf } from "#src/contract/file/file-path.pure";
+import { fileListingOf } from "#src/contract/file/file-listing.pure";
+import { blobReceipts } from "#src/host/blob/reference/blob-receipts.sql";
+import { filePage, fileUsagePage } from "#src/host/blob/reference/blob-file-page.sql";
+import type { Opening } from "#src/host/blob/blob-sealing.contract";
+
+interface FileAccess {
+  readonly actor: string;
+  readonly open: (opening: Omit<Opening, "filename">) => Stream.Stream<Uint8Array, FileFailure>;
+}
+
+interface FileOpening extends FileAccess {
+  readonly sql: SqlClient.SqlClient;
+}
+
+const unavailable = Effect.fail(FilesUnavailableError.make({ message: "files aren't available on this host" }));
+
+const unavailableFileStorage: FileStorage = {
+  attach: () => unavailable,
+  available: unavailable,
+  fileUsage: () => unavailable,
+  list: () => unavailable,
+  read: () => Stream.fromEffect(unavailable),
+  remove: () => unavailable,
+};
+
+const emptyFileStorage: FileStorage = {
+  ...unavailableFileStorage,
+  available: Effect.void,
+  fileUsage: (listing = {}) => Effect.as(fileListingOf(listing), { bytes: 0n, cursor: Option.none(), entries: [] }),
+  list: (listing = {}) => Effect.as(fileListingOf(listing), { cursor: Option.none(), entries: [] }),
+  read: (path) =>
+    Stream.fromEffect(Effect.flatMap(filePathOf(path), (valid) => FileNotFoundError.make({ path: valid }))),
+};
+
+const refOf = ({ path, bytes, sha256, writtenAt }: FileRef): FileRef => ({ bytes, path, sha256, writtenAt });
+
+const actorFileStorage = ({ actor, open, sql }: FileOpening): FileStorage => {
+  const receipts = blobReceipts({ actor, sql });
+
+  const available = Effect.mapError(receipts.active, () =>
+    FilesUnavailableError.make({ message: "the actor's files are unavailable" }),
+  );
+
+  return {
+    attach: ({ now, path, receipt }) =>
+      Effect.flatMap(filePathOf(path), (valid) => Effect.map(receipts.attach({ now, path: valid, receipt }), refOf)),
+    available,
+    fileUsage: (listing = {}) => Effect.andThen(available, fileUsagePage({ actor, listing, sql })),
+    list: (listing = {}) => Effect.andThen(available, filePage({ actor, listing, sql })),
+    read: (path, range) =>
+      Stream.unwrap(
+        Effect.gen(function* readFile() {
+          yield* available;
+          const valid = yield* filePathOf(path);
+          const link = yield* receipts.link(valid);
+          const found = yield* Effect.mapError(Effect.fromOption(link), () => FileNotFoundError.make({ path: valid }));
+
+          const opening = { actor, blob: found.blob, grant: found.grant };
+
+          return Option.match(Option.fromNullishOr(range), {
+            onNone: () => open(opening),
+            onSome: (requested) => open({ ...opening, range: requested }),
+          });
+        }),
+      ),
+    remove: (path) => Effect.flatMap(filePathOf(path), receipts.remove),
+  };
+};
+
+export { actorFileStorage, emptyFileStorage, unavailableFileStorage };
+
+export type { FileAccess, FileOpening };

package/src/host/file/actor-files.sql.ts

@@ -0,0 +1,15 @@
+import type { Effect } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+interface FileDigest {
+  readonly bytes: number;
+  readonly path: string;
+  readonly sha256: string;
+}
+
+const fileDigests = (sql: SqlClient.SqlClient): Effect.Effect<readonly FileDigest[], SqlError.SqlError> =>
+  sql<FileDigest>`SELECT path, sha256, bytes FROM akter_blob_links ORDER BY path`;
+
+export { fileDigests };
+
+export type { FileDigest };

package/src/host/file/blob-home-lock.pure.ts

@@ -0,0 +1,23 @@
+import { Effect, Path } from "effect";
+import type { Scope } from "effect";
+import type { SqlError } from "effect/sql";
+
+import type { SqliteDriver } from "#src/host/sqlite/sqlite-driver.service";
+
+const acquireBlobHome = ({
+  directory,
+  driver,
+}: {
+  readonly directory: string;
+  readonly driver: SqliteDriver["Service"];
+}): Effect.Effect<void, SqlError.SqlError, Path.Path | Scope.Scope> =>
+  Effect.gen(function* acquireLocalBlobHome() {
+    const path = yield* Path.Path;
+    const sql = yield* driver.open(path.join(directory, "blob-home.lock.sqlite"));
+
+    yield* sql.unsafe("PRAGMA busy_timeout = 0");
+    yield* sql.unsafe("BEGIN IMMEDIATE");
+    yield* Effect.addFinalizer(() => Effect.orDie(sql.unsafe("ROLLBACK")));
+  });
+
+export { acquireBlobHome };