@akterjs/effect 0.0.0-stage → 0.1.1

package/dist/host/blob/export/blob-export-holds.sql.d.mts

@@ -0,0 +1,49 @@
+import { Effect, Option } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+/** The actor's own connection, which every hold is read and written on. */
+interface OnActor {
+  readonly sql: SqlClient.SqlClient;
+}
+/** A snapshot's hold on the actor's files, kept until `now + lifetimeMillis`. */
+interface ExportHold extends OnActor {
+  readonly lifetimeMillis: number;
+  readonly now: number;
+  readonly snapshot: string;
+}
+/** A page of a snapshot's held files after the SHA-256 `after` (the start when missing). */
+interface HeldPage extends OnActor {
+  readonly after?: string;
+  readonly snapshot: string;
+}
+/** One held file as an export lists it: only its content's SHA-256 and size, never a claim or a grant. */
+interface ExportedFile {
+  readonly bytes: number;
+  readonly sha256: string;
+}
+interface HeldLookup extends OnActor {
+  readonly now: number;
+  readonly sha256: string;
+  readonly snapshot: string;
+}
+/** What an engine needs to open a held file for the actor: its blob, the claim holding it, and its grant. */
+interface HeldBlob {
+  readonly actor: string;
+  readonly blob: string;
+  readonly bytes: number;
+  readonly claim: string;
+  readonly grant: string;
+}
+/**
+ * Holds every file the actor keeps, at the cut an export snapshot takes, for `lifetimeMillis` after `now`: its
+ * linked files, the files its ancestry keeps from a fork, and the receipts its command history keeps. While a hold
+ * lasts, a removed file's claim is not released, so its blob stays to be downloaded; once it expires, the release
+ * goes ahead. A new hold replaces the actor's previous one, whose snapshot is gone. Run it on the actor's own
+ * connection, in the same turn as the snapshot, so no file changes between the two. (`WHERE true` keeps SQLite from
+ * reading the upsert's `ON CONFLICT` as a join constraint.)
+ */
+declare const holdExportFiles: ({ lifetimeMillis, now, snapshot, sql }: ExportHold) => Effect.Effect<void, SqlError.SqlError>;
+/** A page of a snapshot's held files, one entry per distinct SHA-256, in SHA-256 order. */
+declare const heldExportFiles: ({ after, snapshot, sql }: HeldPage) => Effect.Effect<readonly ExportedFile[], SqlError.SqlError>;
+/** The blob that holds a snapshot's file with this SHA-256, or none once the hold has expired at `now`. */
+declare const heldExportFile: ({ now, sha256, snapshot, sql }: HeldLookup) => Effect.Effect<Option.Option<HeldBlob>, SqlError.SqlError>;
+export { type ExportHold, type ExportedFile, type HeldBlob, type HeldLookup, type HeldPage, heldExportFile, heldExportFiles, holdExportFiles };

package/dist/host/blob/export/blob-export-holds.sql.mjs

@@ -0,0 +1,25 @@
+import { prepareReceipts } from "../reference/blob-receipts.sql.mjs";
+import { Array, Effect } from "effect";
+// src/host/blob/export/blob-export-holds.sql.ts
+const exportPageSize = 100;
+/**
+* Holds every file the actor keeps, at the cut an export snapshot takes, for `lifetimeMillis` after `now`: its
+* linked files, the files its ancestry keeps from a fork, and the receipts its command history keeps. While a hold
+* lasts, a removed file's claim is not released, so its blob stays to be downloaded; once it expires, the release
+* goes ahead. A new hold replaces the actor's previous one, whose snapshot is gone. Run it on the actor's own
+* connection, in the same turn as the snapshot, so no file changes between the two. (`WHERE true` keeps SQLite from
+* reading the upsert's `ON CONFLICT` as a join constraint.)
+*/
+const holdExportFiles = ({ lifetimeMillis, now, snapshot, sql }) => sql.withTransaction(Effect.gen(function* holdFiles() {
+	const expiresAt = now + lifetimeMillis;
+	yield* prepareReceipts(sql);
+	yield* sql`DELETE FROM akter_blob_export_holds`;
+	yield* sql`INSERT INTO akter_blob_export_holds (snapshot, claim, actor, blob, bytes, sha256, grant, expires_at) SELECT ${snapshot}, claim, actor, blob, bytes, sha256, grant, ${expiresAt} FROM akter_blob_links WHERE true ON CONFLICT DO NOTHING`;
+	yield* sql`INSERT INTO akter_blob_export_holds (snapshot, claim, actor, blob, bytes, sha256, grant, expires_at) SELECT ${snapshot}, claim, actor, blob, bytes, sha256, grant, ${expiresAt} FROM akter_blob_ancestry WHERE true ON CONFLICT DO NOTHING`;
+	yield* sql`INSERT INTO akter_blob_export_holds (snapshot, claim, actor, blob, bytes, sha256, grant, expires_at) SELECT ${snapshot}, claim, actor, blob, bytes, sha256, grant, ${expiresAt} FROM akter_blob_receipts AS receipt WHERE EXISTS (SELECT 1 FROM akter_blob_history WHERE claim = receipt.claim) ON CONFLICT DO NOTHING`;
+}));
+/** A page of a snapshot's held files, one entry per distinct SHA-256, in SHA-256 order. */
+const heldExportFiles = ({ after = "", snapshot, sql }) => sql`SELECT DISTINCT sha256, bytes FROM akter_blob_export_holds WHERE snapshot = ${snapshot} AND sha256 > ${after} ORDER BY sha256 LIMIT ${exportPageSize}`;
+/** The blob that holds a snapshot's file with this SHA-256, or none once the hold has expired at `now`. */
+const heldExportFile = ({ now, sha256, snapshot, sql }) => Effect.map(sql`SELECT actor, blob, bytes, claim, grant FROM akter_blob_export_holds WHERE snapshot = ${snapshot} AND sha256 = ${sha256} AND expires_at > ${now} ORDER BY claim LIMIT 1`, Array.head);
+export { heldExportFile, heldExportFiles, holdExportFiles };

package/dist/host/blob/plain-blob-sealing.pure.d.mts

@@ -0,0 +1,5 @@
+import { BlobHashing } from "../hash/blob-hashing.service.mjs";
+import { BlobSealingOperations } from "./blob-sealing.contract.mjs";
+import { Effect, FileSystem } from "effect";
+declare const plainBlobSealing: (hashing: BlobHashing["Service"]) => Effect.Effect<BlobSealingOperations, never, FileSystem.FileSystem>;
+export { plainBlobSealing };

package/dist/host/blob/plain-blob-sealing.pure.mjs

@@ -0,0 +1,55 @@
+import { rangeOf } from "./blob-range.pure.mjs";
+import { BlobTransferError } from "../../contract/file/blob-transfer.errors.mjs";
+import { exactLength } from "./stream/blob-length.pure.mjs";
+import { blobWriter } from "./stream/blob-writing.pure.mjs";
+import { Effect, FileSystem, Stream } from "effect";
+// src/host/blob/plain-blob-sealing.pure.ts
+const zeroBytes = 0;
+const failed = (blob, message) => BlobTransferError.make({
+	blob,
+	message
+});
+const sealingWith = (write, hashing) => Effect.fnUntraced(function* seal(request) {
+	const hash = yield* hashing.sha256;
+	let bytes = zeroBytes;
+	const source = Stream.tap(request.source, (chunk) => {
+		bytes += chunk.byteLength;
+		return hash.update(chunk);
+	});
+	yield* write({
+		...request,
+		source
+	});
+	const sha256 = yield* hash.digest;
+	return {
+		bytes,
+		grant: "",
+		sha256
+	};
+});
+const openingWith = (fileSystem) => (request) => Stream.unwrap(Effect.gen(function* open() {
+	const stored = yield* Effect.mapError(fileSystem.stat(request.filename), () => failed(request.blob, "the file could not be opened"));
+	const range = yield* rangeOf({
+		...request,
+		bytes: Number(stored.size)
+	});
+	const source = fileSystem.stream(request.filename, {
+		bytesToRead: range.length,
+		offset: range.offset
+	});
+	return exactLength({
+		blob: request.blob,
+		bytes: range.length,
+		source
+	}).pipe(Stream.map((bytes) => new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)), Stream.mapError(() => failed(request.blob, "the file could not be read")));
+}));
+const plainBlobSealing = (hashing) => Effect.gen(function* makePlainSealing() {
+	const fileSystem = yield* FileSystem.FileSystem;
+	const write = yield* blobWriter;
+	return {
+		open: openingWith(fileSystem),
+		rewrap: () => Effect.succeed(""),
+		seal: sealingWith(write, hashing)
+	};
+});
+export { plainBlobSealing };

package/dist/host/blob/reference/blob-catalog.sql.d.mts

@@ -0,0 +1,40 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { BlobLineage } from "./blob-lineage.sql.mjs";
+import { Effect } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+interface BlobClaim {
+  readonly actor: string;
+  readonly blob: string;
+  readonly claim: string;
+}
+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 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>;
+}
+declare const prepareCatalog: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError.SqlError>;
+declare const blobCatalog: (sql: SqlClient.SqlClient) => BlobCatalog;
+export { type Adopted, type BlobCatalog, type BlobClaim, type CatalogEffect, type ClaimQuery, type ForkedActor, blobCatalog, prepareCatalog };

package/dist/host/blob/reference/blob-catalog.sql.mjs

@@ -0,0 +1,145 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { blobLineage, prepareLineages } from "./blob-lineage.sql.mjs";
+import { Array, Effect, Option } from "effect";
+// src/host/blob/reference/blob-catalog.sql.ts
+const cleanupPageSize = 100;
+const missing = (blob) => BlobTransferError.make({
+	blob,
+	message: "the blob claim is unavailable or belongs to another actor"
+});
+const prepareCatalog = (sql) => 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, { actor, blob }) => 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 (Array.isReadonlyArrayNonEmpty(rows)) return yield* Effect.void;
+	return yield* missing(blob);
+});
+const claimRow = (sql, claim) => Effect.map(sql`SELECT actor, blob, claim, kind, state FROM akter_blob_claims WHERE claim = ${claim}`, Array.head);
+const validateClaim = (sql, expected, kinds) => Effect.flatMap(claimRow(sql, expected.claim), (row) => {
+	if (Option.isSome(row) && row.value.actor === expected.actor && row.value.blob === expected.blob && Array.contains(kinds, row.value.kind) && row.value.state === "active") return Effect.void;
+	return Effect.fail(missing(expected.blob));
+});
+const acquireClaim = (sql, claim, kind) => 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, state) => {
+	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, row) => {
+	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, claim) => Effect.gen(function* adoptNewClaim() {
+	const rows = yield* sql`SELECT state FROM akter_blobs WHERE blob = ${claim.blob}`;
+	const state = Option.getOrElse(Option.map(Array.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, claim) => 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, claim) => sql.withTransaction(Effect.gen(function* allocateBlob() {
+	yield* activeActor(sql, claim);
+	const created = yield* sql`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 Array.isReadonlyArrayNonEmpty(created);
+}));
+const completeBlob = (sql, claim) => 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, blob) => Effect.map(sql`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`, Array.isReadonlyArrayNonEmpty);
+const releaseClaim = (sql, claim) => 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 (Array.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, blob) => Effect.asVoid(sql`UPDATE akter_blobs SET state = 'deleted' WHERE blob = ${blob} AND state = 'deleting'`);
+const eraseActor = (sql, actor) => 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, { actor, origin }) => 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 (!Array.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) => Effect.map(sql`SELECT blob FROM akter_blobs WHERE state = 'deleting' ORDER BY blob LIMIT ${cleanupPageSize}`, Array.map((row) => row.blob));
+const activeClaims = (sql, { actor, after = "" }) => sql`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, actor, after) => sql`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, after) => sql`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) => ({
+	...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 };

package/dist/host/blob/reference/blob-coordinator.pure.d.mts

@@ -0,0 +1,10 @@
+import { AdoptionHome } from "./blob-transfer-adopt.pure.mjs";
+import { BlobTransfers, TransferHome } from "./blob-transfer.pure.mjs";
+import { Effect } from "effect";
+import { SecureRandom } from "effect/crypto";
+/** What a home's transfers seal and hash with, beside the home itself. */
+interface TransferServices extends Pick<AdoptionHome, "hashing" | "sealing"> {
+  readonly home: TransferHome;
+}
+declare const blobTransfers: ({ hashing, home, sealing }: TransferServices) => Effect.Effect<BlobTransfers, never, SecureRandom.SecureRandom>;
+export { blobTransfers };

package/dist/host/blob/reference/blob-coordinator.pure.mjs

@@ -0,0 +1,153 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { adoptWith } from "./blob-transfer-adopt.pure.mjs";
+import { blobReads } from "./blob-reads.pure.mjs";
+import { forkWith } from "./blob-transfer-fork.pure.mjs";
+import { transferUpkeep } from "./blob-transfer-upkeep.pure.mjs";
+import { Clock, Effect, Exit, Function, Ref, Semaphore, TxReentrantLock } from "effect";
+import { SecureRandom } from "effect/crypto";
+// src/host/blob/reference/blob-coordinator.pure.ts
+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 = 36e5;
+/** Uploads one actor may hold that no command has attached yet; past it, a new upload is refused. */
+const unattachedReceipts = 16;
+const freshOperations = Effect.suspend(() => Effect.all({
+	admissions: TxReentrantLock.make(),
+	closed: Ref.make(false),
+	operations: Semaphore.make(oneFileOperation),
+	uploads: Ref.make(/* @__PURE__ */ new Set())
+}));
+const operationWith = (state, mode) => (effect, protect = Function.identity) => {
+	const checked = Effect.gen(function* runFileOperation() {
+		if ((yield* Ref.get(state.closed)) && 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(home, reservation, { owner, source }) {
+	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, { allocated, owner, reservation }) {
+	const prepare = owner.exclusive(Effect.gen(function* prepareUpload() {
+		yield* owner.receipts.active;
+		if (!(yield* home.catalog.create(reservation))) 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, random, upkeep) => Effect.fnUntraced(function* upload({ owner, source }) {
+	const reservation = {
+		...yield* Effect.all({
+			blob: random.uuidV4(),
+			claim: random.uuidV4(),
+			receipt: random.uuidV4()
+		}),
+		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;
+	})));
+});
+const blobTransfers = ({ hashing, home, sealing }) => 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 = (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/dist/host/blob/reference/blob-file-page.sql.d.mts

@@ -0,0 +1,13 @@
+import { FileListing, FilePage, FileUsagePage } from "../../../contract/file/actor-files.contract.mjs";
+import { InvalidFileRequestError } from "../../../contract/file/invalid-file-request.errors.mjs";
+import { Effect } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+interface PageQuery {
+  readonly actor: string;
+  readonly listing: FileListing;
+  readonly sql: SqlClient.SqlClient;
+}
+type PageEffect<Value> = Effect.Effect<Value, InvalidFileRequestError | SqlError.SqlError>;
+declare const filePage: ({ actor, listing, sql }: PageQuery) => PageEffect<FilePage>;
+declare const fileUsagePage: (query: PageQuery) => PageEffect<FileUsagePage>;
+export { type PageQuery, filePage, fileUsagePage };

package/dist/host/blob/reference/blob-file-page.sql.mjs

@@ -0,0 +1,21 @@
+import { fileListingOf } from "../../../contract/file/file-listing.pure.mjs";
+import { Array, Effect, Option, String } from "effect";
+// src/host/blob/reference/blob-file-page.sql.ts
+const lookAhead = 1;
+const noBytes = 0n;
+const filePage = ({ actor, listing, sql }) => Effect.gen(function* pageFiles() {
+	const { cursor, limit, prefix } = yield* fileListingOf(listing);
+	return yield* Effect.map(sql`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 = Array.takeWhile(rows, (file) => String.startsWith(prefix)(file.path));
+		const entries = Array.take(matching, limit);
+		return {
+			cursor: Array.last(entries).pipe(Option.filter(() => matching.length > limit), Option.map((file) => file.path)),
+			entries
+		};
+	});
+});
+const fileUsagePage = (query) => Effect.map(filePage(query), (page) => ({
+	...page,
+	bytes: Array.reduce(page.entries, noBytes, (total, file) => total + BigInt(file.bytes))
+}));
+export { filePage, fileUsagePage };

package/dist/host/blob/reference/blob-forks.sql.d.mts

@@ -0,0 +1,21 @@
+import { CatalogEffect } from "./blob-catalog.sql.mjs";
+import { BlobLink } from "./blob-receipts.sql.mjs";
+import { Effect } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+interface ForkIdentity {
+  readonly operation: string;
+  readonly origin: string;
+}
+interface ForkStorage {
+  readonly actor: string;
+  readonly sql: SqlClient.SqlClient;
+}
+interface BlobForks {
+  readonly activate: (fork: ForkIdentity) => CatalogEffect<void>;
+  readonly begin: (fork: ForkIdentity) => CatalogEffect<boolean>;
+  readonly entries: (after: string) => Effect.Effect<readonly BlobLink[], SqlError.SqlError>;
+  readonly inherit: (file: Omit<BlobLink, "actor">) => CatalogEffect<void>;
+  readonly pending: Effect.Effect<boolean, SqlError.SqlError>;
+}
+declare const blobForks: (storage: ForkStorage) => BlobForks;
+export { type BlobForks, type ForkIdentity, blobForks };

package/dist/host/blob/reference/blob-forks.sql.mjs

@@ -0,0 +1,40 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Array, Effect, Option } from "effect";
+// src/host/blob/reference/blob-forks.sql.ts
+const metadataPageSize = 100;
+const refused = () => BlobTransferError.make({
+	blob: "",
+	message: "the file fork target is not available for this operation"
+});
+const ownerIn = ({ actor, sql }, state) => Effect.map(sql`SELECT actor FROM akter_blob_owners WHERE actor = ${actor} AND state = ${state}`, Array.isReadonlyArrayNonEmpty);
+const recordedFork = (sql) => Effect.map(sql`SELECT origin, operation, state FROM akter_blob_fork WHERE id = 1`, Array.head);
+const forkMatches = (row, expected) => row.origin === expected.origin && row.operation === expected.operation;
+const beginFork = (storage, fork) => storage.sql.withTransaction(Effect.gen(function* prepareFork() {
+	const active = yield* ownerIn(storage, "active");
+	const recorded = yield* recordedFork(storage.sql);
+	if (active && Option.isSome(recorded) && forkMatches(recorded.value, fork) && recorded.value.state === "active") return false;
+	const occupied = yield* storage.sql`SELECT path FROM akter_blob_links UNION ALL SELECT receipt FROM akter_blob_receipts UNION ALL SELECT claim FROM akter_blob_ancestry LIMIT 1`;
+	if (!active || Option.isSome(recorded) || Array.isReadonlyArrayNonEmpty(occupied)) return yield* refused();
+	yield* storage.sql`INSERT INTO akter_blob_fork (id, origin, operation, state) VALUES (1, ${fork.origin}, ${fork.operation}, 'preparing')`;
+	yield* storage.sql`UPDATE akter_blob_owners SET state = 'preparing' WHERE actor = ${storage.actor}`;
+	return true;
+}));
+const inheritFile = (storage, file) => storage.sql.withTransaction(Effect.gen(function* inheritFileLink() {
+	if (!(yield* ownerIn(storage, "preparing"))) return yield* refused();
+	return yield* Effect.asVoid(storage.sql`INSERT INTO akter_blob_links (path, actor, blob, claim, bytes, sha256, grant, written_at) VALUES (${file.path}, ${storage.actor}, ${file.blob}, ${file.claim}, ${file.bytes}, ${file.sha256}, ${file.grant}, ${file.writtenAt})`);
+}));
+const activateFork = (storage, fork) => storage.sql.withTransaction(Effect.gen(function* activateFileFork() {
+	const recorded = yield* recordedFork(storage.sql);
+	if (!(yield* ownerIn(storage, "preparing")) || Option.isNone(recorded) || recorded.value.state !== "preparing" || !forkMatches(recorded.value, fork)) return yield* refused();
+	yield* storage.sql`UPDATE akter_blob_fork SET state = 'active' WHERE id = 1`;
+	return yield* Effect.asVoid(storage.sql`UPDATE akter_blob_owners SET state = 'active' WHERE actor = ${storage.actor}`);
+}));
+const inheritedEntries = ({ actor, sql }, after) => sql`SELECT path, actor, blob, claim, bytes, sha256, grant, written_at AS writtenAt FROM akter_blob_links WHERE actor = ${actor} AND path > ${after} AND EXISTS (SELECT 1 FROM akter_blob_owners WHERE actor = ${actor} AND state = 'active') ORDER BY path LIMIT ${metadataPageSize}`;
+const blobForks = (storage) => ({
+	activate: (fork) => activateFork(storage, fork),
+	begin: (fork) => beginFork(storage, fork),
+	entries: (after) => inheritedEntries(storage, after),
+	inherit: (file) => inheritFile(storage, file),
+	pending: ownerIn(storage, "preparing")
+});
+export { blobForks };

package/dist/host/blob/reference/blob-lineage.sql.d.mts

@@ -0,0 +1,14 @@
+import { CatalogEffect } from "./blob-catalog.sql.mjs";
+import { Effect } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+interface LineageFork {
+  readonly actor: string;
+  readonly origin: string;
+}
+interface BlobLineage {
+  readonly checkFork: (fork: LineageFork) => CatalogEffect<void>;
+  readonly recordFork: (fork: LineageFork) => CatalogEffect<void>;
+}
+declare const prepareLineages: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError.SqlError>;
+declare const blobLineage: (sql: SqlClient.SqlClient) => BlobLineage;
+export { type BlobLineage, blobLineage, prepareLineages };

package/dist/host/blob/reference/blob-lineage.sql.mjs

@@ -0,0 +1,24 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Array, Effect } from "effect";
+// src/host/blob/reference/blob-lineage.sql.ts
+const prepareLineages = (sql) => Effect.asVoid(sql`CREATE INDEX IF NOT EXISTS akter_blob_actors_parent ON akter_blob_actors (parent, actor)`);
+const checkFork = (sql, { actor, origin }) => sql.withTransaction(Effect.gen(function* checkLineage() {
+	const erased = yield* sql`SELECT actor FROM akter_blob_actors WHERE actor IN (${actor}, ${origin}) AND state = 'erased'`;
+	const rebound = yield* sql`SELECT actor FROM akter_blob_actors WHERE actor = ${actor} AND parent IS NOT NULL AND parent != ${origin}`;
+	const cyclic = yield* sql`WITH RECURSIVE ancestry(actor) AS (SELECT ${origin} UNION SELECT parent FROM akter_blob_actors JOIN ancestry ON akter_blob_actors.actor = ancestry.actor WHERE parent IS NOT NULL) SELECT actor FROM ancestry WHERE actor = ${actor}`;
+	if (Array.isReadonlyArrayNonEmpty(erased) || Array.isReadonlyArrayNonEmpty(rebound) || Array.isReadonlyArrayNonEmpty(cyclic)) return yield* BlobTransferError.make({
+		blob: "",
+		message: "the fork lineage is erased, cyclic, or already bound"
+	});
+	return yield* Effect.void;
+}));
+const recordFork = (sql, fork) => sql.withTransaction(Effect.gen(function* recordLineage() {
+	yield* checkFork(sql, fork);
+	yield* sql`INSERT INTO akter_blob_actors (actor, state) VALUES (${fork.origin}, 'active') ON CONFLICT DO NOTHING`;
+	yield* sql`INSERT INTO akter_blob_actors (actor, state, parent) VALUES (${fork.actor}, 'active', ${fork.origin}) ON CONFLICT (actor) DO UPDATE SET parent = excluded.parent`;
+}));
+const blobLineage = (sql) => ({
+	checkFork: (fork) => checkFork(sql, fork),
+	recordFork: (fork) => recordFork(sql, fork)
+});
+export { blobLineage, prepareLineages };