@akterjs/effect 0.0.0-stage → 0.1.0

package/src/host/blob/reference/blob-catalog.sql.ts

@@ -0,0 +1,339 @@
+import { Array as Arr, Effect, Option } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import { BlobTransferError } from "#src/contract/file/blob-transfer.errors";
+import { blobLineage, prepareLineages } from "./blob-lineage.sql.js";
+import type { BlobLineage } from "./blob-lineage.sql.js";
+
+interface BlobClaim {
+  readonly actor: string;
+  readonly blob: string;
+  readonly claim: string;
+}
+
+interface ClaimRow extends BlobClaim {
+  readonly kind: ClaimKind;
+  readonly state: string;
+}
+
+type ClaimKind = "reader" | "reference" | "upload";
+
+interface ClaimQuery {
+  readonly actor: string;
+  readonly after?: string;
+}
+
+type CatalogEffect<Value> = Effect.Effect<Value, BlobTransferError | SqlError.SqlError>;
+
+/** A fork's target, and the actor it was forked from. */
+interface ForkedActor {
+  readonly actor: string;
+  readonly origin: string;
+}
+
+/** How an adoption proceeds: `held` when this home already has the blob ready, `copy` when its bytes must be placed. */
+type Adopted = "copy" | "held";
+
+interface StoredBlob {
+  readonly state: string;
+}
+
+interface BlobCatalog extends BlobLineage {
+  readonly abandon: (fork: ForkedActor) => Effect.Effect<void, SqlError.SqlError>;
+  readonly acquire: (claim: BlobClaim) => CatalogEffect<void>;
+  readonly adopt: (claim: BlobClaim) => CatalogEffect<Adopted>;
+  readonly beginDelete: (blob: string) => Effect.Effect<boolean, SqlError.SqlError>;
+  readonly claims: (query: ClaimQuery) => Effect.Effect<readonly BlobClaim[], SqlError.SqlError>;
+  readonly complete: (claim: BlobClaim) => CatalogEffect<void>;
+  readonly create: (claim: BlobClaim) => CatalogEffect<boolean>;
+  readonly deletions: Effect.Effect<readonly string[], SqlError.SqlError>;
+  readonly erase: (actor: string) => Effect.Effect<void, SqlError.SqlError>;
+  readonly finishDelete: (blob: string) => Effect.Effect<void, SqlError.SqlError>;
+  readonly pending: (actor: string, after?: string) => Effect.Effect<readonly BlobClaim[], SqlError.SqlError>;
+  readonly pin: (claim: BlobClaim) => CatalogEffect<void>;
+  readonly readers: (after: string) => Effect.Effect<readonly BlobClaim[], SqlError.SqlError>;
+  readonly release: (claim: BlobClaim) => CatalogEffect<void>;
+}
+
+const cleanupPageSize = 100;
+
+const missing = (blob: string): BlobTransferError =>
+  BlobTransferError.make({ blob, message: "the blob claim is unavailable or belongs to another actor" });
+
+const prepareCatalog = (sql: SqlClient.SqlClient): Effect.Effect<void, SqlError.SqlError> =>
+  sql.withTransaction(
+    Effect.gen(function* createTables() {
+      yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_actors (actor TEXT PRIMARY KEY, state TEXT NOT NULL CHECK (state IN ('active', 'erased')), parent TEXT) STRICT`;
+      yield* sql`CREATE TABLE IF NOT EXISTS akter_blobs (blob TEXT PRIMARY KEY, creation TEXT NOT NULL UNIQUE, state TEXT NOT NULL CHECK (state IN ('uploading', 'ready', 'deleting', 'deleted'))) STRICT`;
+      yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_claims (claim TEXT PRIMARY KEY, blob TEXT NOT NULL, actor TEXT NOT NULL, kind TEXT NOT NULL DEFAULT 'reference' CHECK (kind IN ('reader', 'reference', 'upload')), state TEXT NOT NULL CHECK (state IN ('active', 'released'))) STRICT`;
+      yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_claims_live ON akter_blob_claims (blob, state)`;
+      yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_claims_owner ON akter_blob_claims (actor, state, claim)`;
+      yield* sql`CREATE INDEX IF NOT EXISTS akter_blobs_deleting ON akter_blobs (state, blob)`;
+      yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_claims_uploads ON akter_blob_claims (actor, claim) WHERE kind = 'upload' AND state = 'active'`;
+      yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_claims_readers ON akter_blob_claims (claim) WHERE kind = 'reader' AND state = 'active'`;
+      yield* prepareLineages(sql);
+    }),
+  );
+
+const activeActor = (sql: SqlClient.SqlClient, { actor, blob }: BlobClaim): CatalogEffect<void> =>
+  Effect.gen(function* checkActor() {
+    yield* sql`INSERT INTO akter_blob_actors (actor, state) VALUES (${actor}, 'active') ON CONFLICT (actor) DO NOTHING`;
+    const rows = yield* sql`SELECT actor FROM akter_blob_actors WHERE actor = ${actor} AND state = 'active'`;
+
+    if (Arr.isReadonlyArrayNonEmpty(rows)) {
+      return yield* Effect.void;
+    }
+
+    return yield* missing(blob);
+  });
+
+const claimRow = (sql: SqlClient.SqlClient, claim: string): Effect.Effect<Option.Option<ClaimRow>, SqlError.SqlError> =>
+  Effect.map(
+    sql<ClaimRow>`SELECT actor, blob, claim, kind, state FROM akter_blob_claims WHERE claim = ${claim}`,
+    Arr.head,
+  );
+
+const validateClaim = (
+  sql: SqlClient.SqlClient,
+  expected: BlobClaim,
+  kinds: readonly ClaimKind[],
+): CatalogEffect<void> =>
+  Effect.flatMap(claimRow(sql, expected.claim), (row) => {
+    if (
+      Option.isSome(row) &&
+      row.value.actor === expected.actor &&
+      row.value.blob === expected.blob &&
+      Arr.contains(kinds, row.value.kind) &&
+      row.value.state === "active"
+    ) {
+      return Effect.void;
+    }
+
+    return Effect.fail(missing(expected.blob));
+  });
+
+const acquireClaim = (sql: SqlClient.SqlClient, claim: BlobClaim, kind: ClaimKind): CatalogEffect<void> =>
+  sql.withTransaction(
+    Effect.gen(function* acquireReference() {
+      yield* activeActor(sql, claim);
+      yield* sql`INSERT INTO akter_blob_claims (claim, blob, actor, kind, state) SELECT ${claim.claim}, blob, ${claim.actor}, ${kind}, 'active' FROM akter_blobs WHERE blob = ${claim.blob} AND state = 'ready' ON CONFLICT (claim) DO NOTHING`;
+      yield* validateClaim(sql, claim, [kind]);
+    }),
+  );
+
+const retryLater = (blob: string, state: string): BlobTransferError => {
+  if (state === "deleting") {
+    return BlobTransferError.make({ blob, message: "the blob is being removed from this home; retry the adoption" });
+  }
+
+  return BlobTransferError.make({ blob, message: "the blob is still being written to this home; retry the adoption" });
+};
+
+/** The decision for a claim the catalog already has: the same adoption run again. */
+const adoptedBefore = (claim: BlobClaim, row: ClaimRow): CatalogEffect<Adopted> => {
+  if (row.actor !== claim.actor || row.blob !== claim.blob || row.kind === "reader") {
+    return Effect.fail(missing(claim.blob));
+  }
+
+  if (row.state !== "active") {
+    return Effect.fail(
+      BlobTransferError.make({ blob: claim.blob, message: "the adopted claim was released; adopt under a new claim" }),
+    );
+  }
+
+  if (row.kind === "upload") {
+    return Effect.succeed("copy");
+  }
+
+  return Effect.succeed("held");
+};
+
+/** A new claim: held on a ready blob, or the creation of a blob this home lacks or already deleted. */
+const adoptedNew = (sql: SqlClient.SqlClient, claim: BlobClaim): CatalogEffect<Adopted> =>
+  Effect.gen(function* adoptNewClaim() {
+    const rows = yield* sql<StoredBlob>`SELECT state FROM akter_blobs WHERE blob = ${claim.blob}`;
+
+    const state = Option.getOrElse(
+      Option.map(Arr.head(rows), (row) => row.state),
+      () => "deleted",
+    );
+
+    if (state === "ready") {
+      yield* sql`INSERT INTO akter_blob_claims (claim, blob, actor, kind, state) VALUES (${claim.claim}, ${claim.blob}, ${claim.actor}, 'reference', 'active')`;
+
+      return "held";
+    }
+
+    if (state !== "deleted") {
+      return yield* retryLater(claim.blob, state);
+    }
+
+    yield* sql`INSERT INTO akter_blobs (blob, creation, state) VALUES (${claim.blob}, ${claim.claim}, 'uploading') ON CONFLICT (blob) DO UPDATE SET creation = excluded.creation, state = 'uploading' WHERE akter_blobs.state = 'deleted'`;
+    yield* sql`INSERT INTO akter_blob_claims (claim, blob, actor, kind, state) VALUES (${claim.claim}, ${claim.blob}, ${claim.actor}, 'upload', 'active')`;
+
+    return "copy";
+  });
+
+/**
+ * Decides, in one transaction, how `claim` takes a blob whose bytes come from another home: a claim seen before
+ * decides as it did, a ready blob gains a reference claim (`held`), and a missing or deleted blob is created as
+ * uploading under an upload claim (`copy`), which recovery releases if the copy never completes.
+ */
+const adoptBlob = (sql: SqlClient.SqlClient, claim: BlobClaim): CatalogEffect<Adopted> =>
+  sql.withTransaction(
+    Effect.gen(function* adoptClaim() {
+      yield* activeActor(sql, claim);
+
+      const row = yield* claimRow(sql, claim.claim);
+
+      if (Option.isSome(row)) {
+        return yield* adoptedBefore(claim, row.value);
+      }
+
+      return yield* adoptedNew(sql, claim);
+    }),
+  );
+
+const createBlob = (sql: SqlClient.SqlClient, claim: BlobClaim): CatalogEffect<boolean> =>
+  sql.withTransaction(
+    Effect.gen(function* allocateBlob() {
+      yield* activeActor(sql, claim);
+
+      const created = yield* sql<{
+        readonly blob: string;
+      }>`INSERT INTO akter_blobs (blob, creation, state) VALUES (${claim.blob}, ${claim.claim}, 'uploading') ON CONFLICT (blob) DO NOTHING RETURNING blob`;
+
+      yield* sql`INSERT INTO akter_blob_claims (claim, blob, actor, kind, state) SELECT ${claim.claim}, blob, ${claim.actor}, 'upload', 'active' FROM akter_blobs WHERE blob = ${claim.blob} AND creation = ${claim.claim} AND state = 'uploading' ON CONFLICT (claim) DO NOTHING`;
+      yield* validateClaim(sql, claim, ["upload"]);
+
+      return Arr.isReadonlyArrayNonEmpty(created);
+    }),
+  );
+
+const completeBlob = (sql: SqlClient.SqlClient, claim: BlobClaim): CatalogEffect<void> =>
+  sql.withTransaction(
+    Effect.gen(function* publishBlob() {
+      yield* activeActor(sql, claim);
+      yield* validateClaim(sql, claim, ["reference", "upload"]);
+      yield* sql`UPDATE akter_blobs SET state = 'ready' WHERE blob = ${claim.blob} AND state = 'uploading'`;
+      yield* sql`UPDATE akter_blob_claims SET kind = 'reference' WHERE claim = ${claim.claim}`;
+    }),
+  );
+
+const beginDelete = (sql: SqlClient.SqlClient, blob: string): Effect.Effect<boolean, SqlError.SqlError> =>
+  Effect.map(
+    sql<{
+      readonly blob: string;
+    }>`UPDATE akter_blobs SET state = 'deleting' WHERE blob = ${blob} AND state != 'deleted' AND NOT EXISTS (SELECT 1 FROM akter_blob_claims WHERE blob = ${blob} AND state = 'active') RETURNING blob`,
+    Arr.isReadonlyArrayNonEmpty,
+  );
+
+const releaseClaim = (sql: SqlClient.SqlClient, claim: BlobClaim): CatalogEffect<void> =>
+  sql.withTransaction(
+    Effect.gen(function* releaseReference() {
+      const row = yield* claimRow(sql, claim.claim);
+
+      if (Option.isNone(row)) {
+        const erased =
+          yield* sql`SELECT actor FROM akter_blob_actors WHERE actor = ${claim.actor} AND state = 'erased'`;
+
+        if (Arr.isReadonlyArrayNonEmpty(erased)) {
+          return yield* Effect.void;
+        }
+      }
+
+      if (Option.isNone(row) || row.value.actor !== claim.actor || row.value.blob !== claim.blob) {
+        return yield* missing(claim.blob);
+      }
+
+      yield* sql`UPDATE akter_blob_claims SET state = 'released' WHERE claim = ${claim.claim}`;
+
+      return yield* Effect.asVoid(beginDelete(sql, claim.blob));
+    }),
+  );
+
+const finishDelete = (sql: SqlClient.SqlClient, blob: string): Effect.Effect<void, SqlError.SqlError> =>
+  Effect.asVoid(sql`UPDATE akter_blobs SET state = 'deleted' WHERE blob = ${blob} AND state = 'deleting'`);
+
+const eraseActor = (sql: SqlClient.SqlClient, actor: string): Effect.Effect<void, SqlError.SqlError> =>
+  sql.withTransaction(
+    Effect.gen(function* eraseClaims() {
+      yield* sql`INSERT INTO akter_blob_actors (actor, state) VALUES (${actor}, 'erased') ON CONFLICT (actor) DO UPDATE SET state = 'erased'`;
+      yield* sql`UPDATE akter_blob_claims SET state = 'released' WHERE actor = ${actor} AND kind != 'reader'`;
+      yield* sql`UPDATE akter_blobs SET state = 'deleting' WHERE state != 'deleted' AND blob IN (SELECT blob FROM akter_blob_claims WHERE actor = ${actor}) AND NOT EXISTS (SELECT 1 FROM akter_blob_claims WHERE akter_blob_claims.blob = akter_blobs.blob AND akter_blob_claims.state = 'active')`;
+    }),
+  );
+
+/**
+ * Undoes an unfinished fork into an actor: its claims are released as an erase releases them, but its catalog row is
+ * deleted instead of marked erased, so a retry can fork into the same actor again. Only an actor whose row names
+ * `origin` as its parent is undone, so an actor that holds its own files, such as one created at the fork's target
+ * while the fork ran, keeps every claim.
+ */
+const abandonActor = (
+  sql: SqlClient.SqlClient,
+  { actor, origin }: ForkedActor,
+): Effect.Effect<void, SqlError.SqlError> =>
+  sql.withTransaction(
+    Effect.gen(function* abandonClaims() {
+      const forked =
+        yield* sql`SELECT actor FROM akter_blob_actors WHERE actor = ${actor} AND state = 'active' AND parent = ${origin}`;
+
+      if (!Arr.isReadonlyArrayNonEmpty(forked)) {
+        return;
+      }
+
+      yield* sql`UPDATE akter_blob_claims SET state = 'released' WHERE actor = ${actor} AND kind != 'reader'`;
+      yield* sql`UPDATE akter_blobs SET state = 'deleting' WHERE state != 'deleted' AND blob IN (SELECT blob FROM akter_blob_claims WHERE actor = ${actor}) AND NOT EXISTS (SELECT 1 FROM akter_blob_claims WHERE akter_blob_claims.blob = akter_blobs.blob AND akter_blob_claims.state = 'active')`;
+      yield* sql`DELETE FROM akter_blob_actors WHERE actor = ${actor} AND state = 'active'`;
+    }),
+  );
+
+const pendingDeletions = (sql: SqlClient.SqlClient): Effect.Effect<readonly string[], SqlError.SqlError> =>
+  Effect.map(
+    sql<{
+      readonly blob: string;
+    }>`SELECT blob FROM akter_blobs WHERE state = 'deleting' ORDER BY blob LIMIT ${cleanupPageSize}`,
+    Arr.map((row) => row.blob),
+  );
+
+const activeClaims = (
+  sql: SqlClient.SqlClient,
+  { actor, after = "" }: ClaimQuery,
+): Effect.Effect<readonly BlobClaim[], SqlError.SqlError> =>
+  sql<BlobClaim>`SELECT actor, blob, claim FROM akter_blob_claims WHERE actor = ${actor} AND state = 'active' AND claim > ${after} ORDER BY claim LIMIT ${cleanupPageSize}`;
+
+const pendingUploads = (
+  sql: SqlClient.SqlClient,
+  actor: string,
+  after: string,
+): Effect.Effect<readonly BlobClaim[], SqlError.SqlError> =>
+  sql<BlobClaim>`SELECT actor, blob, claim FROM akter_blob_claims WHERE actor = ${actor} AND kind = 'upload' AND state = 'active' AND claim > ${after} ORDER BY claim LIMIT ${cleanupPageSize}`;
+
+const readerClaims = (
+  sql: SqlClient.SqlClient,
+  after: string,
+): Effect.Effect<readonly BlobClaim[], SqlError.SqlError> =>
+  sql<BlobClaim>`SELECT actor, blob, claim FROM akter_blob_claims WHERE kind = 'reader' AND state = 'active' AND claim > ${after} ORDER BY claim LIMIT ${cleanupPageSize}`;
+
+const blobCatalog = (sql: SqlClient.SqlClient): BlobCatalog => ({
+  ...blobLineage(sql),
+  abandon: (fork) => abandonActor(sql, fork),
+  acquire: (claim) => acquireClaim(sql, claim, "reference"),
+  adopt: (claim) => adoptBlob(sql, claim),
+  beginDelete: (blob) => beginDelete(sql, blob),
+  claims: (query) => activeClaims(sql, query),
+  complete: (claim) => completeBlob(sql, claim),
+  create: (claim) => createBlob(sql, claim),
+  deletions: pendingDeletions(sql),
+  erase: (actor) => eraseActor(sql, actor),
+  finishDelete: (blob) => finishDelete(sql, blob),
+  pending: (actor, after = "") => pendingUploads(sql, actor, after),
+  pin: (claim) => acquireClaim(sql, claim, "reader"),
+  readers: (after) => readerClaims(sql, after),
+  release: (claim) => releaseClaim(sql, claim),
+});
+
+export { blobCatalog, prepareCatalog };
+
+export type { Adopted, BlobCatalog, BlobClaim, CatalogEffect, ClaimQuery, ForkedActor };

package/src/host/blob/reference/blob-coordinator.pure.ts

@@ -0,0 +1,217 @@
+import { Clock, Effect, Exit, Function as Fn, Ref, Semaphore, TxReentrantLock } from "effect";
+import { SecureRandom } from "effect/crypto";
+import type { SqlError } from "effect/sql";
+
+import { BlobTransferError } from "#src/contract/file/blob-transfer.errors";
+import { adoptWith } from "./blob-transfer-adopt.pure.js";
+import type { AdoptionHome } from "./blob-transfer-adopt.pure.js";
+import { blobReads } from "./blob-reads.pure.js";
+import { forkWith } from "./blob-transfer-fork.pure.js";
+import { transferUpkeep } from "./blob-transfer-upkeep.pure.js";
+import type { TransferUpkeep } from "./blob-transfer-upkeep.pure.js";
+import type { UploadReservation } from "./blob-receipts.sql.js";
+import type { BlobOwner, BlobTransfers, FileOperation, TransferHome, Upload } from "./blob-transfer.pure.js";
+
+const oneFileOperation = 1;
+
+/** How long a sealed upload waits for a command to attach it before it is canceled and its blob collected. */
+const receiptLifetimeMillis = 3_600_000;
+
+/** Uploads one actor may hold that no command has attached yet; past it, a new upload is refused. */
+const unattachedReceipts = 16;
+
+interface Operations {
+  readonly admissions: TxReentrantLock.TxReentrantLock;
+  readonly closed: Ref.Ref<boolean>;
+  readonly operations: Semaphore.Semaphore;
+  readonly uploads: Ref.Ref<Set<string>>;
+}
+
+interface UploadHome extends TransferHome {
+  readonly run: FileOperation;
+  readonly uploads: Ref.Ref<Set<string>>;
+}
+
+interface UploadAllocation {
+  readonly allocated: Ref.Ref<boolean>;
+  readonly owner: BlobOwner;
+  readonly reservation: UploadReservation;
+}
+
+const freshOperations: Effect.Effect<Operations> = Effect.suspend(() =>
+  Effect.all({
+    admissions: TxReentrantLock.make(),
+    closed: Ref.make(false),
+    operations: Semaphore.make(oneFileOperation),
+    uploads: Ref.make(new Set<string>()),
+  }),
+);
+
+const operationWith =
+  (state: Operations, mode: "shared" | "exclusive" | "closing"): FileOperation =>
+  (effect, protect = Fn.identity) => {
+    const checked = Effect.gen(function* runFileOperation() {
+      const disposed = yield* Ref.get(state.closed);
+
+      if (disposed && mode !== "closing") {
+        return yield* BlobTransferError.make({ blob: "", message: "the file home is closed" });
+      }
+
+      return yield* effect;
+    });
+
+    const guarded = protect(state.operations.withPermits(oneFileOperation)(checked));
+
+    if (mode === "shared") {
+      return TxReentrantLock.withReadLock(state.admissions, guarded);
+    }
+
+    return TxReentrantLock.withWriteLock(state.admissions, guarded);
+  };
+
+const completedUpload = Effect.fnUntraced(function* completedUpload<Failure, Services>(
+  home: UploadHome,
+  reservation: UploadReservation,
+  { owner, source }: Upload<Failure, Services>,
+): Effect.fn.Return<string, BlobTransferError | SqlError.SqlError | Failure, Services> {
+  const sealed = yield* home.directory.publish({ actor: owner.actor, blob: reservation.blob, source });
+
+  return yield* home.run(
+    Effect.gen(function* prepareReceipt() {
+      const now = yield* Clock.currentTimeMillis;
+
+      yield* owner.exclusive(
+        owner.transaction(
+          owner.receipts.complete({ expiresAt: now + receiptLifetimeMillis, receipt: reservation.receipt, sealed }),
+        ),
+      );
+      yield* home.catalog.complete(reservation);
+
+      return reservation.receipt;
+    }),
+  );
+});
+
+const reserveUpload = Effect.fnUntraced(function* reserveUpload(
+  home: UploadHome,
+  { allocated, owner, reservation }: UploadAllocation,
+) {
+  const prepare = owner.exclusive(
+    Effect.gen(function* prepareUpload() {
+      yield* owner.receipts.active;
+
+      const created = yield* home.catalog.create(reservation);
+
+      if (!created) {
+        return yield* BlobTransferError.make({
+          blob: reservation.blob,
+          message: "the generated upload identity is already in use",
+        });
+      }
+
+      yield* Ref.set(allocated, true);
+      yield* Ref.update(home.uploads, (uploads) => new Set(uploads).add(reservation.claim));
+
+      const now = yield* Clock.currentTimeMillis;
+
+      return yield* owner.transaction(owner.receipts.reserve(reservation, { now, unattached: unattachedReceipts }));
+    }),
+  );
+
+  return yield* home.run(prepare);
+});
+
+const uploadWith = (
+  home: UploadHome,
+  random: SecureRandom.SecureRandom["Service"],
+  upkeep: TransferUpkeep,
+): BlobTransfers["upload"] =>
+  Effect.fnUntraced(function* upload<Failure, Services>({
+    owner,
+    source,
+  }: Upload<Failure, Services>): Effect.fn.Return<string, BlobTransferError | SqlError.SqlError | Failure, Services> {
+    const identifiers = yield* Effect.all({ blob: random.uuidV4(), claim: random.uuidV4(), receipt: random.uuidV4() });
+    const reservation: UploadReservation = { ...identifiers, actor: owner.actor, expiresAt: Number.MAX_SAFE_INTEGER };
+    const allocated = yield* Ref.make(false);
+
+    const prepare = reserveUpload(home, { allocated, owner, reservation });
+
+    return yield* Effect.andThen(prepare, completedUpload(home, reservation, { owner, source })).pipe(
+      Effect.onExit((exit) => {
+        if (Exit.isSuccess(exit)) {
+          return Effect.void;
+        }
+
+        return Effect.flatMap(Ref.get(allocated), (created) => {
+          if (created) {
+            const cleanup = Effect.andThen(upkeep.cancel(owner, reservation), Effect.asVoid(upkeep.collect));
+
+            return home.run(cleanup);
+          }
+
+          return Effect.void;
+        });
+      }),
+      Effect.ensuring(
+        Ref.update(home.uploads, (uploads) => {
+          const remaining = new Set(uploads);
+
+          remaining.delete(reservation.claim);
+
+          return remaining;
+        }),
+      ),
+    );
+  });
+
+/** What a home's transfers seal and hash with, beside the home itself. */
+interface TransferServices extends Pick<AdoptionHome, "hashing" | "sealing"> {
+  readonly home: TransferHome;
+}
+
+const blobTransfers = ({
+  hashing,
+  home,
+  sealing,
+}: TransferServices): Effect.Effect<BlobTransfers, never, SecureRandom.SecureRandom> =>
+  Effect.gen(function* makeBlobTransfers() {
+    const random = yield* SecureRandom.SecureRandom;
+
+    const state = yield* freshOperations;
+
+    const running = {
+      closing: operationWith(state, "closing"),
+      exclusive: operationWith(state, "exclusive"),
+      shared: operationWith(state, "shared"),
+    };
+
+    const admit: BlobTransfers["admit"] = (effect) => TxReentrantLock.withReadLock(state.admissions, effect);
+
+    const upkeep = transferUpkeep({ ...home, run: running.shared, uploads: state.uploads });
+
+    const upload = uploadWith({ ...home, run: running.shared, uploads: state.uploads }, random, upkeep);
+    const fork = forkWith({ home, random, sealing });
+    const adopt = adoptWith({ ...home, hashing, run: running.shared, sealing, uploads: state.uploads });
+    const reads = yield* blobReads({ home, random });
+
+    return {
+      admit,
+      adopt: (request) => admit(adopt(request)),
+      close: running.closing(Ref.set(state.closed, true)).pipe(Effect.orDie, Effect.andThen(reads.close)),
+      collect: running.shared(upkeep.collect),
+      download: reads.download,
+      erase: (owner) => running.exclusive(upkeep.erase(owner), owner.snapshot),
+      fork: (request) => running.exclusive(fork(request)),
+      hold: (effect) => TxReentrantLock.withWriteLock(state.admissions, effect),
+      open: reads.open,
+      recover: (owner) => {
+        const recovered = Effect.andThen(reads.recover, upkeep.recover(owner));
+
+        return running.shared(recovered, owner.snapshot);
+      },
+      settle: (owner) => running.shared(upkeep.settle(owner), owner.snapshot),
+      upload: (request) => admit(upload(request)),
+    };
+  });
+
+export { blobTransfers };

package/src/host/blob/reference/blob-file-page.sql.ts

@@ -0,0 +1,48 @@
+import { Array as Arr, Effect, Option, String as Str } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import type { FileListing, FilePage, FileRef, FileUsagePage } from "#src/contract/file/actor-files.contract";
+import type { InvalidFileRequestError } from "#src/contract/file/invalid-file-request.errors";
+import { fileListingOf } from "#src/contract/file/file-listing.pure";
+
+interface PageQuery {
+  readonly actor: string;
+  readonly listing: FileListing;
+  readonly sql: SqlClient.SqlClient;
+}
+
+type PageEffect<Value> = Effect.Effect<Value, InvalidFileRequestError | SqlError.SqlError>;
+
+const lookAhead = 1;
+
+const noBytes = 0n;
+
+const filePage = ({ actor, listing, sql }: PageQuery): PageEffect<FilePage> =>
+  Effect.gen(function* pageFiles() {
+    const { cursor, limit, prefix } = yield* fileListingOf(listing);
+
+    return yield* Effect.map(
+      sql<FileRef>`SELECT path, bytes, sha256, written_at AS writtenAt FROM akter_blob_links WHERE actor = ${actor} AND path >= ${prefix} AND path > ${cursor} AND EXISTS (SELECT 1 FROM akter_blob_owners WHERE actor = ${actor} AND state = 'active') ORDER BY path LIMIT ${limit + lookAhead}`,
+      (rows) => {
+        const matching = Arr.takeWhile(rows, (file) => Str.startsWith(prefix)(file.path));
+        const entries = Arr.take(matching, limit);
+
+        const next = Arr.last(entries).pipe(
+          Option.filter(() => matching.length > limit),
+          Option.map((file) => file.path),
+        );
+
+        return { cursor: next, entries };
+      },
+    );
+  });
+
+const fileUsagePage = (query: PageQuery): PageEffect<FileUsagePage> =>
+  Effect.map(filePage(query), (page) => ({
+    ...page,
+    bytes: Arr.reduce(page.entries, noBytes, (total, file) => total + BigInt(file.bytes)),
+  }));
+
+export { filePage, fileUsagePage };
+
+export type { PageQuery };