@akterjs/effect 0.0.0-stage → 0.1.0

package/src/serve/engine/actor-host.service.ts

@@ -0,0 +1,454 @@
+import { Array as Arr, Context, Deferred, Effect, FileSystem, Layer, Option, Scope, Semaphore } from "effect";
+import type { Path } from "effect";
+
+import { ActorRegistry } from "#src/contract/actor/actor-registry.service";
+import { ActorDatabase } from "#src/host/actor/actor-database.service";
+import type { OpenedActor } from "#src/host/actor/actor-database.service";
+import { ActorUpkeep } from "#src/host/upkeep/actor-upkeep.service";
+import { ActorHostRunners } from "#src/serve/history/actor-host-runners.service";
+import type { CommandRunner, FileUsage, Runners } from "#src/serve/history/actor-host-runners.service";
+
+import { ActorLocation } from "./actor-location.service.js";
+import type { ActorAddress } from "./actor-location.service.js";
+import {
+  blankTemplates,
+  cachedResidents,
+  fileIdentity,
+  fileSessionOf,
+  notServed,
+  readingOf,
+  unavailable,
+  unavailableUnlessErased,
+} from "./actor-residents.pure.js";
+import type { OpenFailure, Reading, Residents as ResidentCache } from "./actor-residents.pure.js";
+import { ActorForks } from "./actor-fork.service.js";
+import type { ForkCall, ForkFailure, ForkServices } from "./actor-fork.service.js";
+import { LiveReads } from "#src/serve/live/live-reads.service";
+import type { HostFailure, LiveActor } from "#src/serve/live/live-reads.service";
+import { LocalActorErasure } from "#src/serve/erasure/local-actor-erasure.service";
+
+interface ActorCall extends ActorAddress {
+  readonly member: string;
+  readonly payload: string;
+  readonly principal: string;
+}
+
+interface CommandCall extends ActorCall {
+  readonly commandId: string;
+}
+
+interface CoverageRead extends ActorAddress {
+  readonly since: number;
+}
+
+interface StepsRead extends ActorAddress {
+  readonly limit?: number;
+}
+
+interface StepRead extends ActorAddress {
+  readonly step: string;
+}
+
+type Steps = Effect.Success<ReturnType<Runners["queries"]["steps"]>>;
+
+type Step = Effect.Success<ReturnType<Runners["queries"]["step"]>>;
+
+interface HistoryRead extends CoverageRead {
+  readonly after: number;
+  readonly limit: number;
+}
+
+interface CreateCall extends CommandCall {
+  readonly mode: "create" | "ensure";
+}
+
+interface ResidentOpening {
+  readonly scope: Scope.Scope;
+  readonly send: (call: CommandCall) => Effect.Effect<string, HostFailure>;
+}
+
+type FileSession = NonNullable<OpenedActor["fileSession"]>;
+
+interface Resident {
+  readonly exclusive: FileSession["owner"]["exclusive"];
+  readonly forking: Semaphore.Semaphore;
+  readonly commit: <Success, Failure, Needs>(
+    effect: Effect.Effect<Success, Failure, Needs>,
+  ) => Effect.Effect<Success, Failure, Needs>;
+  readonly live: LiveActor;
+  readonly drain: Effect.Effect<boolean, HostFailure>;
+  readonly jobs: Effect.Success<ReturnType<ActorUpkeep["Service"]["start"]>>["jobs"];
+  readonly kick: Effect.Effect<void>;
+  readonly opened: OpenedActor;
+}
+
+type History = Effect.Success<ReturnType<Runners["queries"]["history"]>>;
+
+const oneCommandAtATime = 1;
+
+type Registered = Effect.Success<ReturnType<ActorRegistry["Service"]["lookup"]>>;
+
+const servedActor = (address: ActorAddress): Effect.Effect<Registered, OpenFailure, ActorRegistry> =>
+  Effect.mapError(
+    ActorRegistry.use((registry) => registry.lookup(address.actor)),
+    () => notServed(address),
+  );
+
+const storedActor = Effect.fnUntraced(function* storedActor(address: ActorAddress) {
+  yield* servedActor(address);
+  yield* LocalActorErasure.check(address);
+
+  const { database } = yield* ActorLocation.use((location) => Effect.succeed(location.locate(address)));
+
+  return yield* Effect.mapError(
+    FileSystem.FileSystem.use((fileSystem) => fileSystem.exists(database)),
+    unavailable(address.actor),
+  );
+});
+
+// Commands run one at a time. A fork also holds `forking` from its cut until its child has the parent's files, so no
+// Commit lands in between.
+const residentGates = Effect.fnUntraced(function* residentGates(opened: OpenedActor) {
+  const commands = yield* Semaphore.make(oneCommandAtATime);
+  const forking = yield* Semaphore.make(oneCommandAtATime);
+
+  const exclusive = Option.match(Option.fromNullishOr(opened.fileSession), {
+    onNone: () => commands.withPermits(oneCommandAtATime),
+    onSome:
+      (session: FileSession): FileSession["owner"]["exclusive"] =>
+      (effect) =>
+        session.home.transfers.admit(session.owner.exclusive(effect)),
+  });
+
+  return { exclusive, forking };
+});
+
+const keepResident = Effect.fnUntraced(function* keepResident(
+  address: ActorAddress,
+  opened: OpenedActor,
+  { scope, send }: ResidentOpening,
+) {
+  const { exclusive, forking } = yield* residentGates(opened);
+  const live = yield* LiveReads.use((reads) => reads.open({ exclusive, opened }));
+
+  let committed: Effect.Effect<void> = Effect.void;
+
+  const commit = <Success, Failure, Needs>(
+    effect: Effect.Effect<Success, Failure, Needs>,
+  ): Effect.Effect<Success, Failure, Needs> =>
+    exclusive(
+      effect.pipe(
+        Effect.tap(() => committed),
+        Effect.ensuring(live.refresh),
+      ),
+    ).pipe(forking.withPermits(oneCommandAtATime));
+
+  const kept = yield* Effect.provideService(
+    ActorUpkeep.use((upkeep) =>
+      upkeep.start({
+        exclusive: commit,
+        key: address.key,
+        lock: exclusive,
+        opened,
+        read: exclusive,
+        send: ActorUpkeep.sequentialDeliveries(send),
+      }),
+    ),
+    Scope.Scope,
+    scope,
+  );
+
+  ({ committed } = kept);
+
+  return {
+    commit,
+    drain: Effect.catchTag(kept.drain, "SqlError", (failure) => Effect.fail(unavailable(address.actor)(failure))),
+    exclusive,
+    forking,
+    jobs: kept.jobs,
+    kick: Effect.andThen(kept.kick, opened.fileSession?.kick ?? Effect.void),
+    live,
+    opened,
+  };
+});
+
+const openResident = Effect.fnUntraced(function* openResident(
+  address: ActorAddress,
+  scope: Scope.Scope,
+  send: (call: CommandCall) => Effect.Effect<string, HostFailure>,
+) {
+  const actor = yield* servedActor(address);
+
+  const { database, directory } = yield* ActorLocation.use((location) => Effect.succeed(location.locate(address)));
+
+  yield* Effect.mapError(
+    FileSystem.FileSystem.use((fileSystem) => fileSystem.makeDirectory(directory, { recursive: true })),
+    unavailable(address.actor),
+  );
+
+  const opened = yield* Effect.mapError(
+    Effect.provideService(
+      ActorDatabase.use((opener) => opener.open({ actor, filename: database, identity: fileIdentity(address) })),
+      Scope.Scope,
+      scope,
+    ),
+    unavailableUnlessErased(address.actor),
+  );
+
+  return yield* keepResident(address, opened, { scope, send });
+});
+
+const blankOf = Effect.fnUntraced(function* blankOf(address: ActorAddress, scope: Scope.Scope) {
+  const actor = yield* servedActor(address);
+
+  return yield* Effect.mapError(
+    Effect.provideService(
+      ActorDatabase.use((opener) => opener.blank(actor)),
+      Scope.Scope,
+      scope,
+    ),
+    unavailable(address.actor),
+  );
+});
+
+type FilesUnavailable = Effect.Error<ReturnType<typeof fileSessionOf>>;
+
+interface Routes {
+  /** In-process local administration only; hosted actor RPCs never expose erasure. */
+  readonly erase?: (address: ActorAddress) => Effect.Effect<void, OpenFailure>;
+  readonly command: (call: CommandCall) => Effect.Effect<string, HostFailure>;
+  readonly coveredSince: (request: CoverageRead) => Effect.Effect<number, OpenFailure>;
+  readonly history: (request: HistoryRead) => Effect.Effect<History, OpenFailure>;
+  readonly create: (call: CreateCall) => Effect.Effect<string, HostFailure>;
+  readonly currentFiles: (
+    address: ActorAddress,
+  ) => Effect.Effect<Option.Option<FileSession>, OpenFailure | FilesUnavailable, Scope.Scope>;
+  readonly drain: Effect.Effect<void, HostFailure>;
+  readonly fork: (call: ForkCall) => Effect.Effect<number, ForkFailure>;
+  readonly files: (address: ActorAddress) => Effect.Effect<FileUsage, OpenFailure>;
+  readonly query: (call: ActorCall) => Effect.Effect<string, HostFailure>;
+  readonly prepareFiles: (
+    address: ActorAddress,
+  ) => Effect.Effect<FileSession, OpenFailure | FilesUnavailable, Scope.Scope>;
+  readonly state: (address: ActorAddress) => LiveActor["state"];
+  /** One of the actor's durable computer steps, by its key. */
+  readonly step: (request: StepRead) => Effect.Effect<Step, OpenFailure>;
+  /** The actor's durable computer steps, newest first. */
+  readonly steps: (request: StepsRead) => Effect.Effect<Steps, OpenFailure>;
+  readonly subscribe: (call: ActorCall) => ReturnType<LiveActor["subscribe"]>;
+  readonly warm: (address: ActorAddress) => Effect.Effect<void, OpenFailure>;
+}
+
+type Residents = ResidentCache<Resident>;
+
+const drainPasses = 1000;
+
+const drainAll = ({ addresses, use }: Residents): Effect.Effect<void, HostFailure | OpenFailure> => {
+  const pass = Effect.gen(function* pass() {
+    const before = yield* addresses;
+    const worked = yield* Effect.forEach(before, (address) => use(address, (found) => found.drain));
+    const after = yield* addresses;
+
+    return Arr.some(worked, Boolean) || after.length > before.length;
+  });
+
+  const settled = Effect.repeat(pass, { times: drainPasses, until: (busy) => !busy });
+
+  return Effect.flatMap(settled, (busy) => {
+    if (busy) {
+      return Effect.die(`actors were still sending or firing after ${drainPasses} passes`);
+    }
+
+    return Effect.void;
+  });
+};
+
+const readRoutes = (
+  reading: Reading<Resident>,
+  queries: Runners["queries"],
+): Omit<Routes, "command" | "create" | "drain" | "fork" | "prepareFiles"> => ({
+  coveredSince: (request) =>
+    reading.read(request, (opened) =>
+      Effect.mapError(queries.coveredSince({ opened, since: request.since }), unavailable(request.actor)),
+    ),
+  currentFiles: (address) =>
+    Effect.flatMap(
+      reading.borrowExisting(address),
+      Option.match({
+        onNone: () => Effect.succeedNone,
+        onSome: (found) => Effect.asSome(fileSessionOf(found.opened)),
+      }),
+    ),
+  files: (address) =>
+    reading.read(address, (opened) => Effect.mapError(queries.files(opened), unavailable(address.actor))),
+  history: (request) =>
+    reading.read(request, (opened) =>
+      Effect.mapError(
+        queries.history({ after: request.after, limit: request.limit, opened, since: request.since }),
+        unavailable(request.actor),
+      ),
+    ),
+  query: (call) =>
+    reading.read(call, (opened) =>
+      Effect.catchTag(queries.run({ opened, request: call }), "SqlError", (failure) =>
+        Effect.fail(unavailable(call.actor)(failure)),
+      ),
+    ),
+  step: (request) =>
+    reading.read(request, (opened) => Effect.mapError(queries.step(opened, request.step), unavailable(request.actor))),
+  steps: (request) =>
+    reading.read(request, (opened) =>
+      Effect.mapError(queries.steps(opened, request.limit), unavailable(request.actor)),
+    ),
+  warm: Effect.fn("ActorHost.warm")(function* warm(address: ActorAddress) {
+    yield* reading.existing(address, () => Effect.void);
+  }),
+  ...reading.live,
+});
+
+const routes = (
+  residents: Residents,
+  { check, queries, runner }: Runners & { readonly check: (address: ActorAddress) => Effect.Effect<void, OpenFailure> },
+  reading: Reading<Resident>,
+): Omit<Routes, "fork"> => {
+  const command = Effect.fn("ActorHost.command")((call: CommandCall) =>
+    residents.use(call, ({ commit, kick, opened }) => {
+      const run = Effect.catchTag(runner.run({ opened, request: call }), "SqlError", (failure) =>
+        Effect.fail(unavailable(call.actor)(failure)),
+      );
+
+      const checked = Effect.andThen(check(call), run);
+
+      return Effect.ensuring(commit(checked), kick);
+    }),
+  );
+
+  const create = Effect.fn("ActorHost.create")((call: CreateCall) =>
+    residents.use(call, ({ commit, kick, opened }) => {
+      const run = Effect.catchTag(runner.create({ opened, request: call }), "SqlError", (failure) =>
+        Effect.fail(unavailable(call.actor)(failure)),
+      );
+
+      const checked = Effect.andThen(check(call), run);
+
+      return Effect.ensuring(commit(checked), kick);
+    }),
+  );
+
+  return {
+    command,
+    create,
+    drain: drainAll(residents),
+    prepareFiles: (address) => Effect.flatMap(residents.borrow(address), ({ opened }) => fileSessionOf(opened)),
+    ...readRoutes(reading, queries),
+  };
+};
+
+const forkRoute = (
+  residents: Residents,
+  services: Context.Context<ActorRegistry | FileSystem.FileSystem | ForkServices>,
+): Routes["fork"] => {
+  const fork = ActorForks.forkedBy({
+    identity: fileIdentity,
+    residents,
+    served: (address) => Effect.provide(servedActor(address), services),
+    stored: (address) => Effect.provide(storedActor(address), services),
+  });
+
+  return (call) => Effect.provide(fork(call), services);
+};
+
+// At start: sweeps what crashed forks left before anything can open or fork an actor, then reopens every stored actor.
+const reopenStored = Effect.fnUntraced(function* reopenStored(residents: Residents) {
+  const { list } = yield* ActorLocation;
+  const upkeep = yield* ActorUpkeep;
+
+  yield* ActorForks.sweepStaged(fileIdentity).pipe(
+    Effect.catch((error) => Effect.logWarning(`could not sweep unfinished forks: ${error.message}`)),
+  );
+
+  yield* upkeep.locateJobs((address) => Effect.orDie(Effect.map(residents.borrow(address), (found) => found.jobs)));
+
+  const reopenAll = Effect.flatMap(list, (addresses) =>
+    Effect.flatMap(
+      Effect.forEach(addresses, (address) => Effect.exit(residents.use(address, () => Effect.void))),
+      (opened) => Effect.asVoid(Effect.all(opened)),
+    ),
+  );
+
+  yield* Effect.forkScoped(upkeep.keep(reopenAll, "reopening stored actors at start"));
+});
+
+const finishErasures = (erase: LocalActorErasure["Service"]["erase"]): Effect.Effect<void, never, ActorLocation> =>
+  Effect.flatMap(
+    ActorLocation.use((location) => location.erased),
+    (addresses) => Effect.forEach(addresses, erase, { discard: true }),
+  ).pipe(Effect.ignore({ log: "Warn", message: "could not finish actor erasure" }));
+
+export class ActorHost extends Context.Service<ActorHost, Routes>()(
+  "@akterjs/effect/serve/engine/actor-host.service/ActorHost",
+) {
+  public static readonly historyRetention = ActorHostRunners.historyRetention;
+
+  public static readonly layer: Layer.Layer<
+    ActorHost,
+    never,
+    ActorDatabase | ActorLocation | ActorRegistry | CommandRunner | FileSystem.FileSystem | Path.Path
+  > = Layer.effect(
+    this,
+    Effect.gen(function* makeActorHost() {
+      const services = yield* Effect.context<
+        ActorDatabase | ActorLocation | ActorRegistry | ActorUpkeep | FileSystem.FileSystem | ForkServices | LiveReads
+      >();
+
+      const { erasure, runners, scope, self } = yield* Effect.all({
+        erasure: LocalActorErasure.make,
+        runners: ActorHostRunners.make,
+        scope: Effect.scope,
+        self: Deferred.make<Routes>(),
+      });
+
+      const send = (call: CommandCall): Effect.Effect<string, HostFailure> =>
+        Effect.flatMap(Deferred.await(self), (host) => host.command(call));
+
+      const residents = yield* cachedResidents<Resident>({
+        check: erasure.check,
+        open: (address) =>
+          erasure.open(address, (owned) =>
+            Effect.tap(Effect.provide(openResident(address, owned, send), services), runners.prune),
+          ),
+      });
+
+      const blanks = yield* Effect.all({
+        current: LiveReads.use((reads) => Effect.succeed(reads.current)),
+        template: blankTemplates({
+          build: (address, owned) => Effect.provide(blankOf(address, owned), services),
+          scope,
+        }),
+      });
+
+      const host: Routes = {
+        ...routes(
+          residents,
+          { ...runners, check: erasure.check },
+          readingOf({ blanks, residents, stored: (address) => Effect.provide(storedActor(address), services) }),
+        ),
+        erase: (address) =>
+          residents.holding(address)(Effect.andThen(erasure.erase(address), residents.forget(address))),
+        fork: forkRoute(residents, services),
+      };
+
+      yield* finishErasures(erasure.erase);
+      yield* Deferred.succeed(self, host).pipe(
+        Effect.andThen(reopenStored(residents)),
+        Effect.andThen(runners.keep(residents)),
+      );
+
+      return host;
+    }),
+  ).pipe(Layer.provide([ActorForks.computers, ActorUpkeep.layer, LiveReads.layer, ActorHostRunners.queries]));
+}
+
+export type { ActorCall, CommandCall, CreateCall, StepRead, StepsRead };
+
+export type { HostFailure } from "#src/serve/live/live-reads.service";

package/src/serve/engine/actor-location.service.ts

@@ -0,0 +1,219 @@
+import { Array as Arr, Context, Effect, FileSystem, Layer, Option, Order, Path, String as Str } from "effect";
+import { shardDirectory } from "./actor-shard.pure.js";
+import { StoreUnreadableError } from "#src/serve/store/store-unreadable.errors";
+
+interface ActorAddress {
+  readonly actor: string;
+  readonly key: string;
+}
+
+interface Staging {
+  readonly address: ActorAddress;
+  readonly fork: string;
+}
+
+interface ActorFiles {
+  readonly database: string;
+  readonly directory: string;
+}
+
+/** A fork's staged copy left beside its child's directory, named by the fork's id. */
+interface StagedFork {
+  readonly files: ActorFiles;
+  readonly fork: string;
+}
+
+const dotsOnly = /^\.*$/u;
+
+const emptyKey = "%";
+
+const databaseFile = "actor.db";
+
+// A fork's staged copy sits beside its child's directory under a name no key encodes to, because encodeURIComponent
+// Always escapes "@", so `list` never reads it as an actor.
+const stagedPrefix = "@fork-";
+
+const actorDatabase = /^\d+\/(?<actor>[^/]+)\/(?<segment>[^/]+)\/actor\.db$/u;
+
+const byActorThenKey = Order.combine(
+  Order.mapInput(Order.String, (address: ActorAddress) => address.actor),
+  Order.mapInput(Order.String, (address: ActorAddress) => address.key),
+);
+
+const keySegment = (key: string): string => {
+  const encoded = encodeURIComponent(key);
+
+  if (encoded === "") {
+    return emptyKey;
+  }
+
+  if (dotsOnly.test(encoded)) {
+    return Str.replaceAll(".", "%2E")(encoded);
+  }
+
+  return encoded;
+};
+
+const decodeKey = Option.liftThrowable(decodeURIComponent);
+
+const keyOf = (segment: string): Option.Option<string> => {
+  if (segment === emptyKey) {
+    return Option.some("");
+  }
+
+  return decodeKey(segment);
+};
+
+const addressOf = (entry: string): Option.Option<ActorAddress> => {
+  const groups = actorDatabase.exec(entry)?.groups;
+  const actor = Option.fromNullishOr(groups?.actor);
+  const segment = Option.flatMap(Option.fromNullishOr(groups?.segment), keyOf);
+
+  return Option.all({ actor, key: segment }).pipe(
+    Option.filter(
+      (address) =>
+        entry === `${shardDirectory(address.key)}/${address.actor}/${keySegment(address.key)}/${databaseFile}`,
+    ),
+  );
+};
+
+const filesAt = (path: Path.Path, home: string): ActorFiles => ({
+  database: path.join(home, databaseFile),
+  directory: home,
+});
+
+const stagedAt = (path: Path.Path, directory: string): Option.Option<StagedFork> => {
+  const name = path.basename(directory);
+
+  return Option.map(decodeKey(Str.slice(stagedPrefix.length)(name)), (fork) => ({
+    files: filesAt(path, directory),
+    fork,
+  }));
+};
+
+type ShardsFailure = Effect.Error<ReturnType<FileSystem.FileSystem["exists"]>>;
+
+interface Shards {
+  readonly fileSystem: FileSystem.FileSystem;
+  readonly path: Path.Path;
+  readonly root: string;
+}
+
+const shardsPresent = ({ fileSystem, root }: Shards): Effect.Effect<boolean, ShardsFailure> =>
+  Effect.gen(function* isShardsDirectory() {
+    if (!(yield* fileSystem.exists(root))) {
+      return false;
+    }
+
+    const found = yield* fileSystem.lstat(root);
+
+    return found.type === "Directory";
+  });
+
+const stagedIn = (shards: Shards): Effect.Effect<readonly StagedFork[], ShardsFailure> =>
+  Effect.gen(function* listStaged() {
+    if (!(yield* shardsPresent(shards))) {
+      return [];
+    }
+
+    const entries = yield* shards.fileSystem.glob(`*/*/${stagedPrefix}*/`, { root: shards.root });
+
+    return Arr.getSomes(Arr.map(entries, (entry) => stagedAt(shards.path, shards.path.join(shards.root, entry))));
+  });
+
+const erasedIn = (shards: Shards): Effect.Effect<readonly ActorAddress[], ShardsFailure> =>
+  Effect.gen(function* erasedActors() {
+    if (!(yield* shardsPresent(shards))) {
+      return [];
+    }
+
+    const entries = yield* shards.fileSystem.glob("**/actor.db.erased", { dot: true, root: shards.root });
+
+    return Arr.getSomes(
+      Arr.map(entries, (entry) => {
+        const database = Str.replace(/\.erased$/u, "")(entry);
+
+        return addressOf(Str.replaceAll(shards.path.sep, "/")(database));
+      }),
+    );
+  });
+
+const placesIn = (path: Path.Path, shards: string): Pick<ActorLocation["Service"], "locate" | "stage"> => {
+  const kindOf = ({ actor, key }: ActorAddress): string => path.join(shards, shardDirectory(key), actor);
+
+  return {
+    locate: (address) => filesAt(path, path.join(kindOf(address), keySegment(address.key))),
+    stage: ({ address, fork }) =>
+      filesAt(path, path.join(kindOf(address), `${stagedPrefix}${encodeURIComponent(fork)}`)),
+  };
+};
+
+export class ActorLocation extends Context.Service<
+  ActorLocation,
+  {
+    /** The directory the store's local computers live in, under each actor's type and key. */
+    readonly computers: string;
+    readonly erased: Effect.Effect<readonly ActorAddress[], StoreUnreadableError>;
+    readonly list: Effect.Effect<readonly ActorAddress[], StoreUnreadableError>;
+    readonly locate: (address: ActorAddress) => ActorFiles;
+    readonly stage: (staging: Staging) => ActorFiles;
+    /** Every fork's staged copy still on disk, which only a fork that never published leaves. */
+    readonly staged: Effect.Effect<readonly StagedFork[], StoreUnreadableError>;
+  }
+>()("@akterjs/effect/serve/engine/actor-location.service/ActorLocation") {
+  /**
+   * An actor named as `<Actor>/<key segment>`, the form Akter Cloud also writes, such as a fork's `fork.origin`, so
+   * one parser reads either engine's export.
+   */
+  public static readonly named = ({ actor, key }: ActorAddress): string => `${actor}/${keySegment(key)}`;
+
+  public static readonly directory = (
+    directory: string,
+  ): Layer.Layer<ActorLocation, never, FileSystem.FileSystem | Path.Path> =>
+    Layer.effect(
+      this,
+      Effect.gen(function* makeActorLocation() {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const shards = path.join(directory, "shards");
+
+        const at = { fileSystem, path, root: shards };
+
+        const unreadable = (failure: { readonly message: string }): StoreUnreadableError =>
+          StoreUnreadableError.make({ directory, message: failure.message });
+
+        const list = Effect.gen(function* list() {
+          if (!(yield* shardsPresent(at))) {
+            return [];
+          }
+
+          const entries = yield* fileSystem.glob("**/actor.db", { dot: true, root: shards });
+
+          const files = yield* Effect.filter(entries, (entry) =>
+            Effect.gen(function* readableActor() {
+              const stored = path.join(shards, entry);
+
+              return (
+                (yield* fileSystem.lstat(stored)).type === "File" && !(yield* fileSystem.exists(`${stored}.erased`))
+              );
+            }),
+          );
+
+          return Arr.sort(
+            Arr.getSomes(Arr.map(files, (entry) => addressOf(Str.replaceAll(path.sep, "/")(entry)))),
+            byActorThenKey,
+          );
+        }).pipe(Effect.mapError(unreadable));
+
+        return {
+          computers: path.join(directory, "computers"),
+          erased: Effect.mapError(erasedIn(at), unreadable),
+          list,
+          staged: Effect.mapError(stagedIn(at), unreadable),
+          ...placesIn(path, shards),
+        };
+      }),
+    );
+}
+
+export type { ActorAddress, ActorFiles, StagedFork };