@akterjs/effect 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,15 @@
+import { BlobTransfers, TransferEffect, TransferHome } from "./blob-transfer.pure.mjs";
+import { Effect } from "effect";
+import { SecureRandom } from "effect/crypto";
+interface ReadSource {
+  readonly home: TransferHome;
+  readonly random: SecureRandom.SecureRandom["Service"];
+}
+interface BlobReads {
+  readonly close: Effect.Effect<void>;
+  readonly download: BlobTransfers["download"];
+  readonly open: BlobTransfers["open"];
+  readonly recover: TransferEffect<void>;
+}
+declare const blobReads: ({ home, random }: ReadSource) => Effect.Effect<BlobReads>;
+export { type BlobReads, blobReads };

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

@@ -0,0 +1,97 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Array, Deferred, Effect, Option, Ref, Semaphore, Stream } from "effect";
+// src/host/blob/reference/blob-reads.pure.ts
+const oneRegistryOperation = 1;
+const noReaders = 0;
+const pinWith = (state, opening) => state.guard.withPermits(oneRegistryOperation)(Effect.gen(function* acquireRead() {
+	if (yield* Ref.get(state.closed)) return yield* BlobTransferError.make({
+		blob: "",
+		message: "the file home is closed"
+	});
+	const claim = yield* state.random.uuidV4();
+	const lease = {
+		actor: opening.actor,
+		blob: opening.blob,
+		claim,
+		grant: opening.grant
+	};
+	yield* state.home.catalog.pin(lease);
+	yield* Ref.update(state.active, (active) => new Set(active).add(claim));
+	return lease;
+}));
+const lookupWith = ({ owner, path }) => Effect.gen(function* lookupDownload() {
+	const lookup = Effect.andThen(owner.receipts.active, owner.receipts.link(path));
+	const found = yield* owner.exclusive(owner.transaction(lookup));
+	const linked = yield* Effect.fromOption(found).pipe(Effect.mapError(() => BlobTransferError.make({
+		blob: "",
+		message: "the actor file does not exist"
+	})));
+	return {
+		actor: owner.actor,
+		blob: linked.blob,
+		grant: linked.grant
+	};
+});
+const forgetWith = (state, claim) => Effect.gen(function* forgetRead() {
+	const remaining = yield* Ref.modify(state.active, (active) => {
+		const next = new Set(active);
+		next.delete(claim);
+		return [next.size, next];
+	});
+	if ((yield* Ref.get(state.closed)) && remaining === noReaders) yield* Deferred.succeed(state.drained, true);
+});
+const releaseWith = (state, lease) => {
+	const released = state.home.catalog.release(lease).pipe(Effect.ensuring(forgetWith(state, lease.claim)));
+	return state.guard.withPermits(oneRegistryOperation)(released);
+};
+const readWith = (state, acquire, range) => Stream.unwrap(Effect.gen(function* openDownload() {
+	const lease = yield* Effect.acquireRelease(acquire, (held) => Effect.orDie(releaseWith(state, held)));
+	const opening = {
+		actor: lease.actor,
+		blob: lease.blob,
+		grant: lease.grant
+	};
+	return Option.match(Option.fromNullishOr(range), {
+		onNone: () => state.home.directory.open(opening),
+		onSome: (requested) => state.home.directory.open({
+			...opening,
+			range: requested
+		})
+	});
+}));
+const closeWith = (state) => Effect.gen(function* closeReads() {
+	yield* state.guard.withPermits(oneRegistryOperation)(Effect.gen(function* refuseReads() {
+		yield* Ref.set(state.closed, true);
+		if ((yield* Ref.get(state.active)).size === noReaders) yield* Deferred.succeed(state.drained, true);
+	}));
+	yield* Deferred.await(state.drained);
+});
+const recoverWith = (state) => state.guard.withPermits(oneRegistryOperation)(Effect.gen(function* recoverReads() {
+	let after = "";
+	for (;;) {
+		const readers = yield* state.home.catalog.readers(after);
+		if (!Array.isReadonlyArrayNonEmpty(readers)) return;
+		const active = yield* Ref.get(state.active);
+		yield* Effect.forEach(Array.filter(readers, (reader) => !active.has(reader.claim)), (reader) => state.home.catalog.release(reader), { discard: true });
+		after = Array.lastNonEmpty(readers).claim;
+	}
+}));
+const blobReads = ({ home, random }) => Effect.gen(function* makeBlobReads() {
+	const state = {
+		...yield* Effect.all({
+			active: Ref.make(/* @__PURE__ */ new Set()),
+			closed: Ref.make(false),
+			drained: Deferred.make(),
+			guard: Semaphore.make(oneRegistryOperation)
+		}),
+		home,
+		random
+	};
+	return {
+		close: closeWith(state),
+		download: (request) => readWith(state, Effect.flatMap(lookupWith(request), (opening) => pinWith(state, opening)), request.range),
+		open: (opening) => readWith(state, pinWith(state, opening), opening.range),
+		recover: recoverWith(state)
+	};
+});
+export { blobReads };

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

@@ -0,0 +1,71 @@
+import { SealedBlob } from "../blob-sealing.contract.mjs";
+import { BlobClaim, CatalogEffect } from "./blob-catalog.sql.mjs";
+import { Effect, Option } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+interface UploadReservation extends BlobClaim {
+  readonly expiresAt: number;
+  readonly receipt: string;
+}
+interface PreparedReceipt extends UploadReservation, SealedBlob {}
+interface ReceiptRow extends PreparedReceipt {
+  readonly state: string;
+}
+interface BlobLink extends BlobClaim, SealedBlob {
+  readonly path: string;
+  readonly writtenAt: number;
+}
+interface Attaching {
+  readonly actor: string;
+  readonly now: number;
+  readonly path: string;
+  readonly receipt: string;
+}
+interface Preparing {
+  readonly actor: string;
+  readonly expiresAt?: number;
+  readonly receipt: string;
+  readonly sealed: SealedBlob;
+}
+/** What a new upload is admitted against: the time, and how many unattached uploads one actor may hold. */
+interface UploadAdmission {
+  readonly now: number;
+  readonly unattached: number;
+}
+interface ReceiptStorage {
+  readonly actor: string;
+  readonly sql: SqlClient.SqlClient;
+}
+interface BlobReceipts {
+  readonly acknowledge: (claim: string) => Effect.Effect<void, SqlError.SqlError>;
+  readonly active: CatalogEffect<void>;
+  readonly attach: (attaching: Omit<Attaching, "actor">) => CatalogEffect<BlobLink>;
+  readonly cancel: (reservation: Pick<UploadReservation, "claim" | "receipt">) => Effect.Effect<void, SqlError.SqlError>;
+  readonly complete: (preparing: Omit<Preparing, "actor">) => CatalogEffect<void>;
+  readonly erase: Effect.Effect<void, SqlError.SqlError>;
+  readonly erased: Effect.Effect<boolean, SqlError.SqlError>;
+  readonly expire: (now: number) => CatalogEffect<void>;
+  readonly link: (path: string) => Effect.Effect<Option.Option<BlobLink>, SqlError.SqlError>;
+  readonly inspect: (claim: string) => Effect.Effect<Option.Option<ReceiptRow>, SqlError.SqlError>;
+  readonly register: CatalogEffect<void>;
+  /** Released claims ready to drop from the catalog at `now`: none still in use, and none under an unexpired hold. */
+  readonly releases: (now: number) => Effect.Effect<readonly BlobClaim[], SqlError.SqlError>;
+  readonly resume: CatalogEffect<void>;
+  /** Records a new upload, refused while the actor holds `admission.unattached` receipts still unattached. */
+  readonly reserve: (reservation: Omit<UploadReservation, "actor">, admission: UploadAdmission) => CatalogEffect<void>;
+  readonly remove: (path: string) => CatalogEffect<void>;
+}
+declare const prepareReceipts: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError.SqlError>;
+/**
+ * Empties the file tables of a database copied from another actor, such as a fork's staged copy, before anything
+ * opens it as a blob owner. Their rows name the source actor, its claims and its grants; the fork then inherits the
+ * files under the copy's own claims and grants.
+ */
+declare const clearCopiedFiles: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError.SqlError>;
+/**
+ * Blanks every grant of a database that leaves its engine in an archive and drops its export holds, then rewrites the
+ * file, so no wrapped file key stays in it, not even in free pages. A grant only opens its blob in the engine that
+ * wrapped it; the importing engine adopts the files under its own.
+ */
+declare const stripArchivedFiles: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError.SqlError>;
+declare const blobReceipts: ({ actor, sql }: ReceiptStorage) => BlobReceipts;
+export { type BlobLink, type BlobReceipts, type PreparedReceipt, type ReceiptRow, type UploadAdmission, type UploadReservation, blobReceipts, clearCopiedFiles, prepareReceipts, stripArchivedFiles };

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

@@ -0,0 +1,176 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Array, Effect, Option } from "effect";
+// src/host/blob/reference/blob-receipts.sql.ts
+const unavailable = (blob) => BlobTransferError.make({
+	blob,
+	message: "the upload receipt is unavailable, expired, or already attached"
+});
+const cleanupPageSize = 100;
+/**
+* The tables that keep files past their links: command history, a fork's ancestry, and an export snapshot's holds.
+* A hold keeps a claim from being released until `expires_at`, so a file removed after a snapshot is still there to
+* download; it never outlives its expiry, and erasing the actor drops it.
+*/
+const prepareRetention = (sql) => Effect.gen(function* createRetentionTables() {
+	yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_history (command_id TEXT NOT NULL, claim TEXT NOT NULL, actor TEXT NOT NULL, blob TEXT NOT NULL, PRIMARY KEY (command_id, claim)) STRICT`;
+	yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_history_claim ON akter_blob_history (claim)`;
+	yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_ancestry (claim TEXT PRIMARY KEY, actor TEXT NOT NULL, blob TEXT NOT NULL, bytes INTEGER NOT NULL, sha256 TEXT NOT NULL, grant TEXT NOT NULL) STRICT`;
+	yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_ancestry_actor ON akter_blob_ancestry (actor, claim)`;
+	yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_export_holds (snapshot TEXT NOT NULL, claim TEXT NOT NULL, actor TEXT NOT NULL, blob TEXT NOT NULL, bytes INTEGER NOT NULL, sha256 TEXT NOT NULL, grant TEXT NOT NULL, expires_at INTEGER NOT NULL, PRIMARY KEY (snapshot, claim)) STRICT`;
+	yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_export_holds_claim ON akter_blob_export_holds (claim, expires_at)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_export_holds_file ON akter_blob_export_holds (snapshot, sha256)`;
+});
+const prepareReceipts = (sql) => sql.withTransaction(Effect.gen(function* createReceiptTables() {
+	yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_owners (id INTEGER PRIMARY KEY CHECK (id = 1), actor TEXT NOT NULL UNIQUE, state TEXT NOT NULL CHECK (state IN ('preparing', 'active', 'erased'))) STRICT`;
+	yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_fork (id INTEGER PRIMARY KEY CHECK (id = 1), origin TEXT NOT NULL, operation TEXT NOT NULL, state TEXT NOT NULL CHECK (state IN ('preparing', 'active', 'aborted'))) STRICT`;
+	yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_receipts (receipt TEXT PRIMARY KEY, actor TEXT NOT NULL, blob TEXT NOT NULL, claim TEXT NOT NULL UNIQUE, expires_at INTEGER NOT NULL, bytes INTEGER NOT NULL DEFAULT 0, sha256 TEXT NOT NULL DEFAULT '', grant TEXT NOT NULL DEFAULT '', state TEXT NOT NULL CHECK (state IN ('uploading', 'prepared', 'consumed', 'canceled'))) STRICT`;
+	yield* sql`CREATE INDEX IF NOT EXISTS akter_blob_receipts_expiry ON akter_blob_receipts (actor, expires_at, receipt) WHERE state IN ('uploading', 'prepared')`;
+	yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_links (path TEXT PRIMARY KEY, actor TEXT NOT NULL, blob TEXT NOT NULL, claim TEXT NOT NULL UNIQUE, bytes INTEGER NOT NULL, sha256 TEXT NOT NULL, grant TEXT NOT NULL, written_at INTEGER NOT NULL) STRICT`;
+	yield* sql`CREATE TABLE IF NOT EXISTS akter_blob_releases (claim TEXT PRIMARY KEY, actor TEXT NOT NULL, blob TEXT NOT NULL) STRICT`;
+	yield* prepareRetention(sql);
+}));
+const copiedFileTables = [
+	"akter_blob_owners",
+	"akter_blob_fork",
+	"akter_blob_receipts",
+	"akter_blob_links",
+	"akter_blob_releases",
+	"akter_blob_history",
+	"akter_blob_ancestry",
+	"akter_blob_export_holds"
+];
+/**
+* Empties the file tables of a database copied from another actor, such as a fork's staged copy, before anything
+* opens it as a blob owner. Their rows name the source actor, its claims and its grants; the fork then inherits the
+* files under the copy's own claims and grants.
+*/
+const clearCopiedFiles = (sql) => sql.withTransaction(Effect.andThen(prepareReceipts(sql), Effect.forEach(copiedFileTables, (table) => sql.unsafe(`DELETE FROM ${table}`), { discard: true })));
+/**
+* Blanks every grant of a database that leaves its engine in an archive and drops its export holds, then rewrites the
+* file, so no wrapped file key stays in it, not even in free pages. A grant only opens its blob in the engine that
+* wrapped it; the importing engine adopts the files under its own.
+*/
+const stripArchivedFiles = (sql) => Effect.andThen(sql.withTransaction(Effect.gen(function* blankGrants() {
+	yield* prepareReceipts(sql);
+	yield* sql`UPDATE akter_blob_links SET grant = ''`;
+	yield* sql`UPDATE akter_blob_ancestry SET grant = ''`;
+	yield* sql`UPDATE akter_blob_receipts SET grant = ''`;
+	yield* sql`DELETE FROM akter_blob_export_holds`;
+})), sql`VACUUM`);
+const activeOwner = (sql, actor) => Effect.flatMap(sql`SELECT actor FROM akter_blob_owners WHERE actor = ${actor} AND state = 'active'`, (rows) => {
+	if (Array.isReadonlyArrayNonEmpty(rows)) return Effect.void;
+	return Effect.fail(unavailable(""));
+});
+const registerOwner = (sql, actor) => sql.withTransaction(Effect.gen(function* registerActor() {
+	yield* sql`INSERT INTO akter_blob_owners (id, actor, state) VALUES (1, ${actor}, 'active') ON CONFLICT DO NOTHING`;
+	yield* activeOwner(sql, actor);
+}));
+const erasedOwner = (sql, actor) => Effect.map(sql`SELECT actor FROM akter_blob_owners WHERE actor = ${actor} AND state = 'erased'`, Array.isReadonlyArrayNonEmpty);
+const resumeOwner = (sql, actor) => sql.withTransaction(Effect.gen(function* resumeActor() {
+	yield* sql`INSERT INTO akter_blob_owners (id, actor, state) VALUES (1, ${actor}, 'active') ON CONFLICT DO NOTHING`;
+	const existing = yield* sql`SELECT actor FROM akter_blob_owners WHERE id = 1 AND actor = ${actor}`;
+	if (Array.isReadonlyArrayNonEmpty(existing)) return yield* Effect.void;
+	return yield* unavailable("");
+}));
+const receiptRow = (sql, actor, receipt) => sql`SELECT actor, blob, claim, receipt, expires_at AS expiresAt, bytes, sha256, grant, state FROM akter_blob_receipts WHERE actor = ${actor} AND receipt = ${receipt}`.pipe(Effect.map(Array.head), Effect.flatMap(Option.match({
+	onNone: () => Effect.fail(unavailable("")),
+	onSome: Effect.succeed
+})));
+const tooManyUnattached = (blob, unattached) => BlobTransferError.make({
+	blob,
+	message: `the actor already holds ${String(unattached)} uploads no command has attached; attach one, or wait for one to expire`
+});
+/** Refuses a new upload while the actor holds `unattached` receipts that are unexpired and not yet attached. */
+const admitUpload = (sql, { blob, actor }, { now, unattached }) => Effect.flatMap(sql`SELECT receipt FROM akter_blob_receipts WHERE actor = ${actor} AND state IN ('uploading', 'prepared') AND expires_at > ${now} LIMIT ${unattached}`, (held) => {
+	if (held.length < unattached) return Effect.void;
+	return Effect.fail(tooManyUnattached(blob, unattached));
+});
+const reserveReceipt = (sql, reservation, admission) => sql.withTransaction(Effect.gen(function* reserveUpload() {
+	yield* activeOwner(sql, reservation.actor);
+	yield* admitUpload(sql, reservation, admission);
+	yield* sql`INSERT INTO akter_blob_receipts (receipt, actor, blob, claim, expires_at, state) VALUES (${reservation.receipt}, ${reservation.actor}, ${reservation.blob}, ${reservation.claim}, ${reservation.expiresAt}, 'uploading')`;
+}));
+const completeReceipt = (sql, { actor, expiresAt, receipt, sealed }) => sql.withTransaction(Effect.gen(function* completeUpload() {
+	yield* activeOwner(sql, actor);
+	const stored = yield* receiptRow(sql, actor, receipt);
+	if (stored.state !== "uploading") return yield* unavailable(stored.blob);
+	return yield* Effect.asVoid(sql`UPDATE akter_blob_receipts SET bytes = ${sealed.bytes}, sha256 = ${sealed.sha256}, grant = ${sealed.grant}, expires_at = ${expiresAt ?? stored.expiresAt}, state = 'prepared' WHERE receipt = ${receipt}`);
+}));
+const cancelReceipt = (sql, actor, { claim, receipt }) => sql.withTransaction(Effect.gen(function* cancelUpload() {
+	yield* sql`INSERT INTO akter_blob_releases (claim, actor, blob) SELECT claim, actor, blob FROM akter_blob_receipts WHERE actor = ${actor} AND receipt = ${receipt} AND claim = ${claim} AND state IN ('uploading', 'prepared') ON CONFLICT (claim) DO NOTHING`;
+	yield* sql`UPDATE akter_blob_receipts SET state = 'canceled' WHERE actor = ${actor} AND receipt = ${receipt} AND claim = ${claim} AND state IN ('uploading', 'prepared')`;
+}));
+const inspectClaim = (sql, actor, claim) => Effect.map(sql`SELECT actor, blob, claim, receipt, expires_at AS expiresAt, bytes, sha256, grant, state FROM akter_blob_receipts WHERE actor = ${actor} AND claim = ${claim}`, Array.head);
+const linkAt = (sql, actor, path) => Effect.map(sql`SELECT actor, blob, claim, bytes, sha256, grant, path, written_at AS writtenAt FROM akter_blob_links WHERE actor = ${actor} AND path = ${path} AND EXISTS (SELECT 1 FROM akter_blob_owners WHERE actor = ${actor} AND state = 'active')`, Array.head);
+const attachReceipt = (sql, { actor, now, path, receipt }) => sql.withTransaction(Effect.gen(function* attachUpload() {
+	yield* activeOwner(sql, actor);
+	const stored = yield* receiptRow(sql, actor, receipt);
+	if (stored.state !== "prepared" || stored.expiresAt <= now) return yield* unavailable(stored.blob);
+	yield* sql`INSERT INTO akter_blob_releases (claim, actor, blob) SELECT claim, actor, blob FROM akter_blob_links AS link WHERE actor = ${actor} AND path = ${path} AND NOT EXISTS (SELECT 1 FROM akter_blob_history WHERE claim = link.claim) ON CONFLICT (claim) DO NOTHING`;
+	yield* sql`INSERT INTO akter_blob_links (path, actor, blob, claim, bytes, sha256, grant, written_at) VALUES (${path}, ${actor}, ${stored.blob}, ${stored.claim}, ${stored.bytes}, ${stored.sha256}, ${stored.grant}, ${now}) ON CONFLICT (path) DO UPDATE SET actor = excluded.actor, blob = excluded.blob, claim = excluded.claim, bytes = excluded.bytes, sha256 = excluded.sha256, grant = excluded.grant, written_at = excluded.written_at`;
+	yield* sql`UPDATE akter_blob_receipts SET state = 'consumed' WHERE receipt = ${receipt}`;
+	return {
+		actor,
+		blob: stored.blob,
+		bytes: stored.bytes,
+		claim: stored.claim,
+		grant: stored.grant,
+		path,
+		sha256: stored.sha256,
+		writtenAt: now
+	};
+}));
+const removeLink = (sql, actor, path) => sql.withTransaction(Effect.gen(function* removeFile() {
+	yield* activeOwner(sql, actor);
+	yield* sql`INSERT INTO akter_blob_releases (claim, actor, blob) SELECT claim, actor, blob FROM akter_blob_links AS link WHERE actor = ${actor} AND path = ${path} AND NOT EXISTS (SELECT 1 FROM akter_blob_history WHERE claim = link.claim) ON CONFLICT (claim) DO NOTHING`;
+	yield* sql`DELETE FROM akter_blob_links WHERE actor = ${actor} AND path = ${path}`;
+}));
+const cancelExpired = (sql, actor, now) => sql.withTransaction(Effect.gen(function* expireUploads() {
+	yield* activeOwner(sql, actor);
+	yield* sql`INSERT INTO akter_blob_releases (claim, actor, blob) SELECT claim, actor, blob FROM akter_blob_receipts WHERE receipt IN (SELECT receipt FROM akter_blob_receipts WHERE actor = ${actor} AND state IN ('uploading', 'prepared') AND expires_at <= ${now} ORDER BY expires_at, receipt LIMIT ${cleanupPageSize}) ON CONFLICT (claim) DO NOTHING`;
+	yield* sql`UPDATE akter_blob_receipts SET state = 'canceled' WHERE receipt IN (SELECT receipt FROM akter_blob_receipts WHERE actor = ${actor} AND state IN ('uploading', 'prepared') AND expires_at <= ${now} ORDER BY expires_at, receipt LIMIT ${cleanupPageSize})`;
+}));
+const eraseOwner = (sql, actor) => sql.withTransaction(Effect.gen(function* eraseActorFiles() {
+	yield* sql`INSERT INTO akter_blob_owners (id, actor, state) VALUES (1, ${actor}, 'erased') ON CONFLICT (actor) DO UPDATE SET state = 'erased'`;
+	yield* sql`INSERT INTO akter_blob_releases (claim, actor, blob) SELECT claim, actor, blob FROM akter_blob_receipts WHERE actor = ${actor} ON CONFLICT (claim) DO NOTHING`;
+	yield* sql`INSERT INTO akter_blob_releases (claim, actor, blob) SELECT claim, actor, blob FROM akter_blob_links WHERE actor = ${actor} ON CONFLICT (claim) DO NOTHING`;
+	yield* sql`INSERT INTO akter_blob_releases (claim, actor, blob) SELECT claim, actor, blob FROM akter_blob_ancestry WHERE actor = ${actor} ON CONFLICT (claim) DO NOTHING`;
+	yield* sql`UPDATE akter_blob_receipts SET state = 'canceled' WHERE actor = ${actor}`;
+	yield* sql`DELETE FROM akter_blob_links WHERE actor = ${actor}`;
+	yield* sql`DELETE FROM akter_blob_history WHERE actor = ${actor}`;
+	yield* sql`DELETE FROM akter_blob_ancestry WHERE actor = ${actor}`;
+	yield* sql`DELETE FROM akter_blob_export_holds`;
+	yield* sql`UPDATE akter_blob_fork SET state = 'aborted'`;
+}));
+const pendingReleases = (sql, actor, now) => sql`SELECT actor, blob, claim FROM akter_blob_releases AS pending WHERE actor = ${actor} AND NOT EXISTS (SELECT 1 FROM akter_blob_history WHERE claim = pending.claim) AND NOT EXISTS (SELECT 1 FROM akter_blob_links WHERE claim = pending.claim) AND NOT EXISTS (SELECT 1 FROM akter_blob_ancestry WHERE claim = pending.claim) AND NOT EXISTS (SELECT 1 FROM akter_blob_receipts WHERE claim = pending.claim AND state IN ('uploading', 'prepared')) AND NOT EXISTS (SELECT 1 FROM akter_blob_export_holds WHERE claim = pending.claim AND expires_at > ${now}) ORDER BY claim LIMIT ${cleanupPageSize}`;
+const acknowledgeRelease = (sql, { actor, claim }) => Effect.asVoid(sql`DELETE FROM akter_blob_releases WHERE actor = ${actor} AND claim = ${claim}`);
+const blobReceipts = ({ actor, sql }) => ({
+	acknowledge: (claim) => acknowledgeRelease(sql, {
+		actor,
+		claim
+	}),
+	active: activeOwner(sql, actor),
+	attach: (attaching) => attachReceipt(sql, {
+		...attaching,
+		actor
+	}),
+	cancel: (reservation) => cancelReceipt(sql, actor, reservation),
+	complete: (preparing) => completeReceipt(sql, {
+		...preparing,
+		actor
+	}),
+	erase: eraseOwner(sql, actor),
+	erased: erasedOwner(sql, actor),
+	expire: (now) => cancelExpired(sql, actor, now),
+	inspect: (claim) => inspectClaim(sql, actor, claim),
+	link: (path) => linkAt(sql, actor, path),
+	register: registerOwner(sql, actor),
+	releases: (now) => pendingReleases(sql, actor, now),
+	remove: (path) => removeLink(sql, actor, path),
+	reserve: (reservation, admission) => reserveReceipt(sql, {
+		...reservation,
+		actor
+	}, admission),
+	resume: resumeOwner(sql, actor)
+});
+export { blobReceipts, clearCopiedFiles, prepareReceipts, stripArchivedFiles };

package/dist/host/blob/reference/blob-transfer-adopt.pure.d.mts

@@ -0,0 +1,21 @@
+import { BlobSealing } from "../blob-sealing.service.mjs";
+import { BlobHashing } from "../../hash/blob-hashing.service.mjs";
+import { BlobTransfers, FileOperation, TransferHome } from "./blob-transfer.pure.mjs";
+import { Ref } from "effect";
+interface AdoptionHome extends TransferHome {
+  readonly hashing: BlobHashing["Service"];
+  readonly run: FileOperation;
+  readonly sealing: BlobSealing["Service"];
+  readonly uploads: Ref.Ref<Set<string>>;
+}
+/**
+ * Takes a blob another home stores into this one under `adoption.claim`, and answers the grant that opens it for the
+ * claim's actor. The grant is rewrapped from `origin` first. A blob this home already has ready gains a reference
+ * claim and `stored` is never read; otherwise its bytes are placed as they are, read back through the new grant and
+ * checked against the file's size and SHA-256 before the blob is ready. Adopting the same claim again does the same
+ * thing again, so a retry after a crash finishes or repeats the copy. A copy that fails releases its upload claim and
+ * removes its file; one cut short by a crash is released by upload recovery when the actor's files next open. Nothing
+ * is written to the actor's own database: the caller records the returned grant with the file.
+ */
+declare const adoptWith: (home: AdoptionHome) => BlobTransfers["adopt"];
+export { type AdoptionHome, adoptWith };

package/dist/host/blob/reference/blob-transfer-adopt.pure.mjs

@@ -0,0 +1,68 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Effect, Exit, Ref, Stream } from "effect";
+// src/host/blob/reference/blob-transfer-adopt.pure.ts
+const noBytes = 0;
+const mismatched = (blob) => BlobTransferError.make({
+	blob,
+	message: "the adopted bytes do not match the file's size and SHA-256"
+});
+/** Reads the placed blob back as its new holder, so a wrong grant, blob id or byte fails before the blob is ready. */
+const verified = Effect.fnUntraced(function* verified(home, { claim, file, grant }) {
+	const hash = yield* home.hashing.sha256;
+	const counted = yield* Ref.make(noBytes);
+	const read = home.directory.open({
+		actor: claim.actor,
+		blob: claim.blob,
+		grant
+	});
+	yield* Stream.runForEach(read, (chunk) => Effect.andThen(Ref.update(counted, (bytes) => bytes + chunk.byteLength), hash.update(chunk)));
+	const bytes = yield* Ref.get(counted);
+	const sha256 = yield* hash.digest;
+	if (bytes !== file.bytes || sha256 !== file.sha256) return yield* mismatched(claim.blob);
+	return yield* Effect.void;
+});
+/** Releases the upload claim of a copy that failed and removes what it placed; the blob was this claim's alone. */
+const discarded = (home, claim) => home.run(Effect.andThen(home.catalog.release(claim), home.directory.remove(claim.blob)));
+const copied = (home, { claim, file, stored }, grant) => Effect.gen(function* copyBlob() {
+	yield* home.directory.place({
+		blob: claim.blob,
+		source: stored
+	});
+	yield* verified(home, {
+		claim,
+		file,
+		grant
+	});
+	yield* home.run(home.catalog.complete(claim));
+}).pipe(Effect.onExit((exit) => {
+	if (Exit.isSuccess(exit)) return Effect.void;
+	return discarded(home, claim);
+}));
+/** Keeps the claim out of upload recovery while this adoption runs, as an upload in flight is. */
+const tracked = (home, claim, effect) => Effect.andThen(Ref.update(home.uploads, (uploads) => new Set(uploads).add(claim)), effect).pipe(Effect.ensuring(Ref.update(home.uploads, (uploads) => {
+	const remaining = new Set(uploads);
+	remaining.delete(claim);
+	return remaining;
+})));
+const adopted = (home, adoption) => Effect.gen(function* adoptBlob() {
+	const { claim, file, origin } = adoption;
+	const grant = yield* home.sealing.rewrap({
+		blob: claim.blob,
+		from: origin,
+		grant: file.grant,
+		to: claim.actor
+	});
+	if ((yield* home.run(home.catalog.adopt(claim))) === "copy") yield* copied(home, adoption, grant);
+	return grant;
+});
+/**
+* Takes a blob another home stores into this one under `adoption.claim`, and answers the grant that opens it for the
+* claim's actor. The grant is rewrapped from `origin` first. A blob this home already has ready gains a reference
+* claim and `stored` is never read; otherwise its bytes are placed as they are, read back through the new grant and
+* checked against the file's size and SHA-256 before the blob is ready. Adopting the same claim again does the same
+* thing again, so a retry after a crash finishes or repeats the copy. A copy that fails releases its upload claim and
+* removes its file; one cut short by a crash is released by upload recovery when the actor's files next open. Nothing
+* is written to the actor's own database: the caller records the returned grant with the file.
+*/
+const adoptWith = (home) => (adoption) => tracked(home, adoption.claim.claim, adopted(home, adoption));
+export { adoptWith };

package/dist/host/blob/reference/blob-transfer-fork.pure.d.mts

@@ -0,0 +1,15 @@
+import { BlobSealing } from "../blob-sealing.service.mjs";
+import { BlobTransfers, TransferHome } from "./blob-transfer.pure.mjs";
+import { SecureRandom } from "effect/crypto";
+interface ForkServices {
+  readonly home: TransferHome;
+  readonly random: SecureRandom.SecureRandom["Service"];
+  readonly sealing: BlobSealing["Service"];
+}
+/**
+ * Forks the source's files into the target, in the target's home. The source's catalog refuses a fork from an erased
+ * actor, the target's refuses one into an erased or already bound actor, and the target's catalog records the
+ * lineage. A fork that fails partway gives the target's claims back.
+ */
+declare const forkWith: (services: ForkServices) => BlobTransfers["fork"];
+export { forkWith };

package/dist/host/blob/reference/blob-transfer-fork.pure.mjs

@@ -0,0 +1,125 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Array, Effect, Exit, Ref } from "effect";
+// src/host/blob/reference/blob-transfer-fork.pure.ts
+const familyOf = ({ source, target }) => ({
+	actor: target.actor,
+	origin: source.actor
+});
+/** Within one home the blob is shared: its grant is rewrapped from the source to the target, and the target claims it. */
+const withinHome = ({ home, random, sealing }, fork) => ({
+	catalog: home.catalog,
+	checkLineage: home.catalog.checkFork(familyOf(fork)),
+	claim: Effect.fnUntraced(function* claimWithinHome(file) {
+		const claim = yield* random.uuidV4();
+		const { source, target } = fork;
+		const grant = yield* sealing.rewrap({
+			blob: file.blob,
+			from: source.actor,
+			grant: file.grant,
+			to: target.actor
+		});
+		yield* home.catalog.acquire({
+			actor: target.actor,
+			blob: file.blob,
+			claim
+		});
+		return {
+			claim,
+			grant
+		};
+	})
+});
+/**
+* Into another home the source's sealed blob is adopted there, its bytes copied unchanged under the same blob id, and
+* the target claims it in that home; the frames are never re-encrypted.
+*/
+const intoHome = ({ home, random }, fork) => ({
+	catalog: fork.into.catalog,
+	checkLineage: Effect.andThen(home.catalog.checkFork(familyOf(fork)), fork.into.catalog.checkFork(familyOf(fork))),
+	claim: Effect.fnUntraced(function* claimIntoHome(file) {
+		const { into, source, target } = fork;
+		const claim = yield* random.uuidV4();
+		return {
+			claim,
+			grant: yield* into.transfers.adopt({
+				claim: {
+					actor: target.actor,
+					blob: file.blob,
+					claim
+				},
+				file,
+				origin: source.actor,
+				stored: home.directory.stored(file.blob)
+			})
+		};
+	})
+});
+const inheritWith = (claims, fork) => Effect.fnUntraced(function* inheritFile(file) {
+	const { claim, grant } = yield* claims.claim(file);
+	yield* fork.target.transaction(fork.target.forks.inherit({
+		...file,
+		claim,
+		grant
+	}));
+});
+const copyPaths = Effect.fnUntraced(function* copyPaths(claims, fork) {
+	let after = "";
+	for (;;) {
+		const files = yield* fork.source.transaction(fork.source.forks.entries(after));
+		if (!Array.isReadonlyArrayNonEmpty(files)) return;
+		yield* Effect.forEach(files, inheritWith(claims, fork), { discard: true });
+		after = Array.lastNonEmpty(files).path;
+	}
+});
+const checkTarget = Effect.fnUntraced(function* checkTarget(claims, fork) {
+	if (!(yield* fork.target.forks.begin({
+		operation: fork.operation,
+		origin: fork.source.actor
+	}))) return false;
+	yield* claims.checkLineage;
+	return true;
+});
+/**
+* Undoes an unfinished fork into the target: its claims are released and its catalog entry removed, so a retry can
+* fork into the same actor. A target whose fork already finished is left alone; erasing it is `erase`.
+*/
+const abandonWith = (catalog, fork) => Effect.flatMap(fork.target.transaction(fork.target.forks.pending), (preparing) => {
+	if (!preparing) return Effect.void;
+	return Effect.andThen(fork.target.transaction(fork.target.receipts.erase), catalog.abandon(familyOf(fork)));
+});
+const claimsFor = (services, fork) => {
+	if (fork.into.root === services.home.root) return withinHome(services, fork);
+	return intoHome(services, fork);
+};
+/**
+* Forks the source's files into the target, in the target's home. The source's catalog refuses a fork from an erased
+* actor, the target's refuses one into an erased or already bound actor, and the target's catalog records the
+* lineage. A fork that fails partway gives the target's claims back.
+*/
+const forkWith = (services) => Effect.fnUntraced(function* forkFiles(fork) {
+	if (fork.source.actor === fork.target.actor) return yield* BlobTransferError.make({
+		blob: "",
+		message: "an actor cannot fork its files into itself"
+	});
+	const claims = claimsFor(services, fork);
+	const started = yield* Ref.make(false);
+	const identity = {
+		operation: fork.operation,
+		origin: fork.source.actor
+	};
+	const prepare = Effect.gen(function* activateInheritedFiles() {
+		if (!(yield* fork.target.transaction(checkTarget(claims, fork)))) return;
+		yield* Ref.set(started, true);
+		yield* claims.catalog.recordFork(familyOf(fork));
+		yield* fork.source.exclusive(Effect.andThen(fork.source.receipts.active, copyPaths(claims, fork)));
+		yield* fork.target.transaction(fork.target.forks.activate(identity));
+	});
+	return yield* fork.target.exclusive(prepare).pipe(Effect.onExit((exit) => {
+		if (Exit.isSuccess(exit)) return Effect.void;
+		return Effect.flatMap(Ref.get(started), (created) => {
+			if (!created) return Effect.void;
+			return fork.target.exclusive(abandonWith(claims.catalog, fork));
+		});
+	}));
+});
+export { forkWith };

package/dist/host/blob/reference/blob-transfer-upkeep.pure.d.mts

@@ -0,0 +1,18 @@
+import { BlobClaim } from "./blob-catalog.sql.mjs";
+import { BlobOwner, FileOperation, TransferEffect, TransferHome } from "./blob-transfer.pure.mjs";
+import { Ref } from "effect";
+interface UpkeepHome extends TransferHome {
+  readonly run: FileOperation;
+  readonly uploads: Ref.Ref<Set<string>>;
+}
+interface TransferUpkeep {
+  readonly cancel: (owner: BlobOwner, claim: BlobClaim & {
+    readonly receipt: string;
+  }) => TransferEffect<void>;
+  readonly collect: TransferEffect<readonly string[]>;
+  readonly erase: (owner: BlobOwner) => TransferEffect<void>;
+  readonly recover: (owner: BlobOwner) => TransferEffect<void>;
+  readonly settle: (owner: BlobOwner) => TransferEffect<void>;
+}
+declare const transferUpkeep: (home: UpkeepHome) => TransferUpkeep;
+export { type TransferUpkeep, transferUpkeep };