@akterjs/effect 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,54 @@
+import { Array, Clock, Effect, Option, Ref } from "effect";
+// src/host/blob/reference/blob-transfer-upkeep.pure.ts
+const collectWith = ({ catalog, directory }) => Effect.gen(function* collectUnreferenced() {
+	const deleting = yield* catalog.deletions;
+	yield* Effect.forEach(deleting, (blob) => Effect.andThen(directory.remove(blob), catalog.finishDelete(blob)), { discard: true });
+	return deleting;
+});
+const releaseWith = (home, owner, claim) => Effect.andThen(home.catalog.release(claim), owner.transaction(owner.receipts.acknowledge(claim.claim)));
+const cancelWith = (home, owner, claim) => Effect.gen(function* abandonUpload() {
+	yield* owner.transaction(owner.receipts.cancel(claim));
+	yield* releaseWith(home, owner, claim);
+});
+const settleWith = (home) => (owner) => owner.exclusive(Effect.gen(function* drainReleases() {
+	if (yield* owner.transaction(owner.receipts.erased)) return yield* home.catalog.erase(owner.actor);
+	const now = yield* Clock.currentTimeMillis;
+	yield* owner.transaction(owner.receipts.expire(now));
+	const releases = yield* owner.transaction(owner.receipts.releases(now));
+	return yield* Effect.forEach(releases, (claim) => releaseWith(home, owner, claim), { discard: true });
+}));
+const recoverClaim = (home, owner, claim) => Effect.gen(function* reconcileUpload() {
+	const stored = yield* owner.transaction(owner.receipts.inspect(claim.claim));
+	if (Option.isSome(stored) && (stored.value.state === "prepared" || stored.value.state === "consumed")) return yield* home.catalog.complete(claim);
+	if (Option.isSome(stored)) return yield* cancelWith(home, owner, stored.value);
+	return yield* releaseWith(home, owner, claim);
+});
+const recoverUploads = Effect.fnUntraced(function* recoverUploads(home, owner) {
+	let after = "";
+	for (;;) {
+		const { active, claims } = yield* Effect.all({
+			active: Ref.get(home.uploads),
+			claims: home.catalog.pending(owner.actor, after)
+		});
+		if (!Array.isReadonlyArrayNonEmpty(claims)) return;
+		const abandoned = Array.filter(claims, (claim) => !active.has(claim.claim));
+		yield* Effect.forEach(abandoned, (claim) => recoverClaim(home, owner, claim), { discard: true });
+		after = Array.lastNonEmpty(claims).claim;
+	}
+});
+const eraseWith = (home, owner) => owner.exclusive(Effect.andThen(owner.transaction(owner.receipts.erase), home.catalog.erase(owner.actor)));
+const transferUpkeep = (home) => ({
+	cancel: (owner, claim) => owner.exclusive(cancelWith(home, owner, claim)),
+	collect: collectWith(home),
+	erase: (owner) => eraseWith(home, owner),
+	recover: (owner) => owner.exclusive(Effect.gen(function* recoverOwner() {
+		if (yield* owner.transaction(owner.receipts.erased)) return yield* home.catalog.erase(owner.actor);
+		if (yield* owner.transaction(owner.forks.pending)) {
+			yield* owner.transaction(owner.receipts.erase);
+			return yield* home.catalog.erase(owner.actor);
+		}
+		return yield* recoverUploads(home, owner);
+	})),
+	settle: settleWith(home)
+});
+export { transferUpkeep };

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

@@ -0,0 +1,85 @@
+import { BlobRange, Opening, SealedBlob } from "../blob-sealing.contract.mjs";
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { BlobDirectory } from "../stream/blob-directory.pure.mjs";
+import { BlobCatalog, BlobClaim } from "./blob-catalog.sql.mjs";
+import { BlobForks } from "./blob-forks.sql.mjs";
+import { BlobReceipts } from "./blob-receipts.sql.mjs";
+import { Effect, Stream } from "effect";
+import { SqlError } from "effect/sql";
+type TransferEffect<Value, Needs = never> = Effect.Effect<Value, BlobTransferError | SqlError.SqlError, Needs>;
+type Serialized = <Success, Failure, Needs>(effect: Effect.Effect<Success, Failure, Needs>) => Effect.Effect<Success, Failure, Needs>;
+type FileOperation = <Success, Failure, Needs>(effect: Effect.Effect<Success, Failure, Needs>, protect?: Serialized) => Effect.Effect<Success, Failure | BlobTransferError, Needs>;
+type DurableTransaction = <Success, Failure, Needs>(effect: Effect.Effect<Success, Failure, Needs>) => Effect.Effect<Success, Failure | SqlError.SqlError, Needs>;
+interface BlobOwner {
+  readonly actor: string;
+  readonly exclusive: Serialized;
+  readonly forks: BlobForks;
+  readonly receipts: BlobReceipts;
+  readonly snapshot: Serialized;
+  readonly transaction: DurableTransaction;
+}
+interface TransferHome {
+  readonly catalog: BlobCatalog;
+  readonly directory: BlobDirectory;
+  /** Where the home keeps its blobs, canonical, so two homes are the same home only when their roots are equal. */
+  readonly root: string;
+}
+/** The home a fork's target keeps its files in, with its own transfers. */
+interface ForkHome extends TransferHome {
+  readonly transfers: BlobTransfers;
+}
+interface Upload<Failure, Services> {
+  readonly owner: BlobOwner;
+  readonly source: Stream.Stream<Uint8Array, Failure, Services>;
+}
+interface Download {
+  readonly owner: BlobOwner;
+  readonly path: string;
+  readonly range?: BlobRange;
+}
+/**
+ * One actor's files forked into another's. The fork runs on the home `source` keeps its files in; `into` is the home
+ * `target` keeps its files in. Within one home each file gains a claim for the target and its grant is rewrapped,
+ * with no bytes copied. Into another home each blob is adopted there (`adopt`): its sealed bytes are copied unchanged
+ * under the same blob id, and the target claims it in that home.
+ */
+interface Fork {
+  readonly into: ForkHome;
+  readonly operation: string;
+  readonly source: BlobOwner;
+  readonly target: BlobOwner;
+}
+/** A file as the home it comes from records it: its size and SHA-256, and its grant for the origin. */
+type AdoptedFile = Pick<SealedBlob, "bytes" | "grant" | "sha256">;
+/**
+ * A blob another home stores, taken into this one: `claim` names the actor that will hold it here, the blob's id
+ * unchanged, since sealed frames are bound to it, and the claim to hold it by. `stored` is its bytes in this home's
+ * at-rest form, read only when this home lacks the blob.
+ */
+interface Adoption<Failure, Services> {
+  readonly claim: BlobClaim;
+  readonly file: AdoptedFile;
+  /** The actor `file.grant` is wrapped for. */
+  readonly origin: string;
+  readonly stored: Stream.Stream<Uint8Array, Failure, Services>;
+}
+interface BlobTransfers {
+  readonly admit: Serialized;
+  /** Takes a blob into this home under `adoption.claim` and answers its grant for that actor (`blob-transfer-adopt`). */
+  readonly adopt: <Failure, Services>(adoption: Adoption<Failure, Services>) => Effect.Effect<string, BlobTransferError | SqlError.SqlError | Failure, Services>;
+  readonly close: Effect.Effect<void>;
+  readonly collect: TransferEffect<readonly string[]>;
+  readonly download: (download: Download) => Stream.Stream<Uint8Array, BlobTransferError | SqlError.SqlError>;
+  readonly erase: (owner: BlobOwner) => TransferEffect<void>;
+  readonly fork: (fork: Fork) => TransferEffect<void>;
+  /**
+   * Runs `effect` while no command, upload or other file operation of this home runs, so the home's blobs and catalog
+   * stay as they are; the fiber running it may still take any actor's own lock. A snapshot copies the home under it.
+   */
+  readonly hold: Serialized;
+  readonly open: (opening: Omit<Opening, "filename">) => Stream.Stream<Uint8Array, BlobTransferError | SqlError.SqlError>;
+  readonly recover: (owner: BlobOwner) => TransferEffect<void>;
+  readonly settle: (owner: BlobOwner) => TransferEffect<void>;
+  readonly upload: <Failure, Services>(upload: Upload<Failure, Services>) => Effect.Effect<string, BlobTransferError | SqlError.SqlError | Failure, Services>;
+}
+export type { AdoptedFile, Adoption, BlobOwner, BlobTransfers, Download, DurableTransaction, FileOperation, Fork, ForkHome, Serialized, TransferEffect, TransferHome, Upload };

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,10 @@
+import { BlobHashing } from "../hash/blob-hashing.service.mjs";
+import { BlobGrants } from "./blob-grants.service.mjs";
+import { BlobSealingOperations } from "./blob-sealing.contract.mjs";
+import { Effect, FileSystem } from "effect";
+import { Aead, SecureRandom } from "effect/crypto";
+declare const sealedBlobSealing: ({ grants, hashing }: {
+  readonly grants: BlobGrants["Service"];
+  readonly hashing: BlobHashing["Service"];
+}) => Effect.Effect<BlobSealingOperations, never, FileSystem.FileSystem | Aead.Aead | SecureRandom.SecureRandom>;
+export { sealedBlobSealing };

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

@@ -0,0 +1,130 @@
+import { framesOf } from "./blob-frames.pure.mjs";
+import { rangeOf } from "./blob-range.pure.mjs";
+import { BlobTransferError } from "../../contract/file/blob-transfer.errors.mjs";
+import { blobWriter } from "./stream/blob-writing.pure.mjs";
+import { exactLength } from "./stream/blob-length.pure.mjs";
+import { Effect, FileSystem, Stream } from "effect";
+import { Aead, SecureRandom } from "effect/crypto";
+// src/host/blob/sealed-blob-sealing.pure.ts
+const zeroBytes = 0;
+const oneFrame = 1;
+const frameBytes = 65536;
+const nonceBytes = 24;
+const overhead = 40;
+const stride = 65576;
+const failed = (blob) => BlobTransferError.make({
+	blob,
+	message: "the sealed file could not be opened"
+});
+const bindingOf = (blob, index, final) => new globalThis.TextEncoder().encode(`akter/blob-frame/v1/${blob.length}:${blob}/${index}/${final}`);
+const encrypt = Effect.fnUntraced(function* encrypt({ aead, blob, bytes, index, key, random }) {
+	const nonce = yield* random.randomBytes(nonceBytes);
+	const aad = bindingOf(blob, index, bytes.byteLength < frameBytes);
+	const ciphertext = yield* aead.encrypt(key, bytes, {
+		aad,
+		nonce
+	});
+	const stored = new Uint8Array(nonceBytes + ciphertext.byteLength);
+	stored.set(nonce);
+	stored.set(ciphertext, nonceBytes);
+	return stored;
+});
+const decrypt = Effect.fnUntraced(function* decrypt({ aead, blob, bytes, index, key }) {
+	const nonce = bytes.subarray(zeroBytes, nonceBytes);
+	const aad = bindingOf(blob, index, bytes.byteLength < stride);
+	return yield* aead.decrypt(key, bytes.subarray(nonceBytes), {
+		aad,
+		nonce
+	});
+});
+const selected = ({ bytes, index, range }) => {
+	const start = Math.max(zeroBytes, range.offset - index * frameBytes);
+	const end = Math.max(zeroBytes, Math.min(bytes.byteLength, range.offset + range.length - index * frameBytes));
+	return bytes.subarray(start, end);
+};
+const plaintextSize = (blob, physical) => {
+	const remainder = (physical - overhead) % stride;
+	if (physical < overhead || remainder >= frameBytes) return Effect.fail(failed(blob));
+	return Effect.succeed(Math.floor((physical - overhead) / stride) * frameBytes + remainder);
+};
+const openingWith = (fileSystem, grants, keys) => (request) => Stream.unwrap(Effect.gen(function* open() {
+	const key = yield* grants.open(request);
+	const stored = yield* Effect.mapError(fileSystem.stat(request.filename), () => failed(request.blob));
+	const bytes = yield* plaintextSize(request.blob, Number(stored.size));
+	const range = yield* rangeOf({
+		...request,
+		bytes
+	});
+	const first = Math.floor(range.offset / frameBytes);
+	const last = Math.floor((range.offset + range.length) / frameBytes);
+	const offset = first * stride;
+	const end = Math.min((last + oneFrame) * stride, Number(stored.size));
+	const source = exactLength({
+		blob: request.blob,
+		bytes: end - offset,
+		source: fileSystem.stream(request.filename, {
+			bytesToRead: end - offset,
+			offset
+		})
+	});
+	return framesOf({
+		size: stride,
+		source
+	}).pipe(Stream.filter((frame) => frame.byteLength > zeroBytes), Stream.mapEffect((frame, index) => Effect.map(decrypt({
+		...keys,
+		blob: request.blob,
+		bytes: frame,
+		index: first + index,
+		key
+	}), (opened) => selected({
+		bytes: opened,
+		index: first + index,
+		range
+	}))), Stream.mapError(() => failed(request.blob)));
+}));
+const sealedBlobSealing = ({ grants, hashing }) => Effect.gen(function* makeSealedSealing() {
+	const fileSystem = yield* FileSystem.FileSystem;
+	const write = yield* blobWriter;
+	const aead = yield* Aead.Aead;
+	const random = yield* SecureRandom.SecureRandom;
+	const seal = Effect.fnUntraced(function* seal(request) {
+		const { grant, key } = yield* grants.fresh(request);
+		const hash = yield* hashing.sha256;
+		let bytes = zeroBytes;
+		const frameSource = Effect.fnUntraced(function* frameSource(frame, index) {
+			yield* hash.update(frame);
+			bytes += frame.byteLength;
+			return yield* Effect.mapError(encrypt({
+				aead,
+				blob: request.blob,
+				bytes: frame,
+				index,
+				key,
+				random
+			}), () => failed(request.blob));
+		});
+		const source = framesOf({
+			size: frameBytes,
+			source: request.source
+		}).pipe(Stream.mapEffect(frameSource));
+		yield* write({
+			...request,
+			source
+		});
+		const sha256 = yield* hash.digest;
+		return {
+			bytes,
+			grant,
+			sha256
+		};
+	});
+	return {
+		open: openingWith(fileSystem, grants, {
+			aead,
+			random
+		}),
+		rewrap: grants.rewrap,
+		seal
+	};
+});
+export { sealedBlobSealing };

package/dist/host/blob/stream/blob-directory.pure.d.mts

@@ -0,0 +1,18 @@
+import { Opening, SealedBlob, Sealing } from "../blob-sealing.contract.mjs";
+import { BlobSealing } from "../blob-sealing.service.mjs";
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Effect, FileSystem, Path, Stream } from "effect";
+interface BlobDirectory {
+  readonly open: (opening: Omit<Opening, "filename">) => Stream.Stream<Uint8Array, BlobTransferError>;
+  /** Writes `source` as the blob's stored bytes, unchanged, replacing a partial file an interrupted write left. */
+  readonly place: <Failure, Services>(placing: Pick<Sealing<Failure, Services>, "blob" | "source">) => Effect.Effect<void, BlobTransferError | Failure, Services>;
+  readonly publish: <Failure, Services>(sealing: Omit<Sealing<Failure, Services>, "filename">) => Effect.Effect<SealedBlob, BlobTransferError | Failure, Services>;
+  readonly remove: (blob: string) => Effect.Effect<void, BlobTransferError>;
+  /** The blob's bytes as this home stores them, sealed or not, for another home to place unchanged. */
+  readonly stored: (blob: string) => Stream.Stream<Uint8Array, BlobTransferError>;
+}
+declare const blobDirectory: ({ store, sealing }: {
+  readonly store: string;
+  readonly sealing: BlobSealing["Service"];
+}) => Effect.Effect<BlobDirectory, BlobTransferError, FileSystem.FileSystem | Path.Path>;
+export { type BlobDirectory, blobDirectory };

package/dist/host/blob/stream/blob-directory.pure.mjs

@@ -0,0 +1,84 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { blobWriter } from "./blob-writing.pure.mjs";
+import { Effect, Exit, FileSystem, Path, Schema, Stream } from "effect";
+// src/host/blob/stream/blob-directory.pure.ts
+const failed = (blob, message) => BlobTransferError.make({
+	blob,
+	message
+});
+const blobId = Schema.String.check(Schema.isUUID());
+const syncDirectory = (directory) => directory.fileSystem.open(directory.root, { flag: "r" }).pipe(Effect.flatMap((opened) => opened.sync), Effect.scoped, Effect.mapError(() => failed("", "the blob directory could not be synced")));
+const filenameOf = (directory, blob) => Schema.decodeEffect(blobId)(blob).pipe(Effect.mapBoth({
+	onFailure: () => failed(blob, "a blob id must be an opaque UUID"),
+	onSuccess: (valid) => directory.path.join(directory.root, valid)
+}));
+const openingFilename = (directory, blob) => Effect.gen(function* resolveBlob() {
+	const filename = yield* filenameOf(directory, blob);
+	if ((yield* Effect.mapError(directory.fileSystem.realPath(filename), () => failed(blob, "the blob could not be resolved"))) !== filename) return yield* failed(blob, "the blob must not redirect outside its location");
+	return filename;
+});
+const prepareDirectory = Effect.fnUntraced(function* prepareDirectory(directory) {
+	yield* Effect.mapError(directory.fileSystem.makeDirectory(directory.root, { recursive: true }), () => failed("", "the blob directory could not be created"));
+	if ((yield* Effect.mapError(directory.fileSystem.realPath(directory.root), () => failed("", "the blob directory could not be resolved"))) !== directory.root) return yield* failed("", "the blob directory must not redirect outside the store");
+	yield* syncDirectory({
+		...directory,
+		root: directory.path.dirname(directory.root)
+	});
+	return yield* syncDirectory(directory);
+});
+const removeBlob = (directory, blob) => Effect.gen(function* removeBlobFile() {
+	const filename = yield* filenameOf(directory, blob);
+	yield* Effect.mapError(directory.fileSystem.remove(filename, { force: true }), () => failed(blob, "the blob could not be removed"));
+	yield* syncDirectory(directory);
+});
+/** Syncs the directory after a blob's file was written, removing the file when the sync fails. */
+const syncedOrRemoved = (directory, blob) => syncDirectory(directory).pipe(Effect.onExit((exit) => {
+	if (Exit.isSuccess(exit)) return Effect.void;
+	return removeBlob(directory, blob);
+}));
+const publishWith = (directory, sealing) => Effect.fnUntraced(function* publish(request) {
+	const filename = yield* filenameOf(directory, request.blob);
+	const sealed = yield* sealing.seal({
+		...request,
+		filename
+	});
+	yield* syncedOrRemoved(directory, request.blob);
+	return sealed;
+});
+const placeWith = (directory, write) => Effect.fnUntraced(function* place({ blob, source }) {
+	const filename = yield* filenameOf(directory, blob);
+	yield* Effect.mapError(directory.fileSystem.remove(filename, { force: true }), () => failed(blob, "the leftover blob could not be removed"));
+	yield* write({
+		blob,
+		filename,
+		source
+	});
+	return yield* syncedOrRemoved(directory, blob);
+});
+const storedWith = (directory) => (blob) => {
+	const read = (filename) => Stream.mapError(directory.fileSystem.stream(filename), () => failed(blob, "the stored blob could not be read"));
+	return Stream.unwrap(Effect.map(openingFilename(directory, blob), read));
+};
+const blobDirectory = ({ store, sealing }) => Effect.gen(function* openBlobDirectory() {
+	const fileSystem = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const parent = yield* Effect.mapError(fileSystem.realPath(store), () => failed("", "the store could not be resolved"));
+	const directory = {
+		fileSystem,
+		path,
+		root: path.join(parent, "blobs")
+	};
+	const write = yield* blobWriter;
+	yield* prepareDirectory(directory);
+	return {
+		open: (opening) => Stream.unwrap(Effect.map(openingFilename(directory, opening.blob), (filename) => sealing.open({
+			...opening,
+			filename
+		}))),
+		place: placeWith(directory, write),
+		publish: publishWith(directory, sealing),
+		remove: (blob) => removeBlob(directory, blob),
+		stored: storedWith(directory)
+	};
+});
+export { blobDirectory };

package/dist/host/blob/stream/blob-length.pure.d.mts

@@ -0,0 +1,9 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Stream } from "effect";
+interface Reading<Failure, Services> {
+  readonly blob: string;
+  readonly bytes: number;
+  readonly source: Stream.Stream<Uint8Array, Failure, Services>;
+}
+declare const exactLength: <Failure, Services>({ blob, bytes, source }: Reading<Failure, Services>) => Stream.Stream<Uint8Array, Failure | BlobTransferError, Services>;
+export { exactLength };

package/dist/host/blob/stream/blob-length.pure.mjs

@@ -0,0 +1,19 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Effect, Stream } from "effect";
+// src/host/blob/stream/blob-length.pure.ts
+const zeroBytes = 0;
+const exactLength = ({ blob, bytes, source }) => Stream.suspend(() => {
+	let read = zeroBytes;
+	const counted = Stream.tap(source, (chunk) => Effect.sync(() => {
+		read += chunk.byteLength;
+	}));
+	const finished = Effect.suspend(() => {
+		if (read !== bytes) return Effect.fail(BlobTransferError.make({
+			blob,
+			message: "the file ended before the requested bytes were read"
+		}));
+		return Effect.void;
+	});
+	return Stream.concat(counted, Stream.drain(Stream.fromEffect(finished)));
+});
+export { exactLength };

package/dist/host/blob/stream/blob-writing.pure.d.mts

@@ -0,0 +1,8 @@
+import { Sealing } from "../blob-sealing.contract.mjs";
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Effect, FileSystem } from "effect";
+/** What a blob write needs: the bytes and where they go. Placing bytes as they are needs no actor. */
+type BlobWrite<Failure, Services> = Pick<Sealing<Failure, Services>, "blob" | "filename" | "source">;
+type WriteBlob = <Failure, Services>(sealing: BlobWrite<Failure, Services>) => Effect.Effect<void, BlobTransferError | Failure, Services>;
+declare const blobWriter: Effect.Effect<WriteBlob, never, FileSystem.FileSystem>;
+export { type WriteBlob, blobWriter };

package/dist/host/blob/stream/blob-writing.pure.mjs

@@ -0,0 +1,15 @@
+import { BlobTransferError } from "../../../contract/file/blob-transfer.errors.mjs";
+import { Effect, Exit, FileSystem, Stream } from "effect";
+// src/host/blob/stream/blob-writing.pure.ts
+const failed = (blob, message) => BlobTransferError.make({
+	blob,
+	message
+});
+const blobWriter = Effect.map(FileSystem.FileSystem, (fileSystem) => Effect.fnUntraced(function* writeBlob({ blob, filename, source }) {
+	const file = yield* Effect.mapError(fileSystem.open(filename, { flag: "wx" }), () => failed(blob, "the upload destination could not be opened"));
+	yield* Stream.runForEach(source, (bytes) => Effect.mapError(file.writeAll(bytes), () => failed(blob, "the upload could not be written"))).pipe(Effect.andThen(Effect.mapError(file.sync, () => failed(blob, "the upload could not be synced"))), Effect.onExit((exit) => {
+		if (Exit.isSuccess(exit)) return Effect.void;
+		return Effect.mapError(fileSystem.remove(filename, { force: true }), () => failed(blob, "the incomplete upload could not be removed"));
+	}));
+}, Effect.scoped));
+export { blobWriter };

package/dist/host/command/batch/command-batch.sql.d.mts

@@ -0,0 +1,61 @@
+import { RecordedCommand } from "../command-journal.sql.mjs";
+import { Context, Effect, HashMap, HashSet, Option, Ref } from "effect";
+import { SqlClient, SqlError } from "effect/sql";
+/**
+ * The journal of one engine batch, kept in memory so a command's bookkeeping needs no round trip of its own.
+ *
+ * An engine that runs many commands in one transaction (akter-cloud) provides `CommandBatch` around each of them.
+ * The first command reads the actor's state, the batch's recorded command ids and the last seq once; later ones read
+ * them from here. Their state and journal writes go to `held`, a client whose statements the engine sends ahead of the
+ * next statement that reaches SQLite, or with the commit, so a handler's own SQL still sees every earlier write. Only
+ * the engine writes `akter_*` tables (handler writes to them are refused), which is what makes the cache sound.
+ */
+interface Journal {
+  /** Command ids whose journal rows were read at the start of the batch, recorded or not. */
+  readonly known: HashSet.HashSet<string>;
+  readonly nextSeq: number;
+  readonly recorded: HashMap.HashMap<string, RecordedCommand>;
+  /** The seq each command recorded in this batch was given. */
+  readonly seqs: HashMap.HashMap<string, number>;
+  readonly state: Option.Option<string>;
+}
+interface Batch {
+  readonly commandIds: readonly string[];
+  /** The journal including the running command. */
+  readonly current: Ref.Ref<Option.Option<Journal>>;
+  readonly held: SqlClient.SqlClient;
+  /** The journal as of the last command the engine kept. */
+  readonly kept: Ref.Ref<Option.Option<Journal>>;
+}
+declare const CommandBatch: Context.Reference<Option.Option<Batch>>;
+declare const CommandBatchJournal: {
+  /** Forgets the journal, so the next command reads it again; after journal pruning, for one. */
+  readonly forget: Effect.Effect<void, never, never>;
+  /** Notes a journal row and returns the seq it is written with, or none outside a batch. */
+  readonly record: (commandId: string, recorded: RecordedCommand) => Effect.Effect<Option.Option<number>>;
+  /** The recorded outcome of `commandId`, from the batch journal when it answers for the id. */
+  readonly recorded: (sql: SqlClient.SqlClient, commandId: string, read: Effect.Effect<Option.Option<RecordedCommand>, SqlError.SqlError>) => Effect.Effect<Option.Option<RecordedCommand>, SqlError.SqlError>;
+  /** Notes a state the running command saved. */
+  readonly saved: (value: string) => Effect.Effect<void>;
+  /** The seq a command recorded in this batch was given, or none when the batch did not record it. */
+  readonly seq: (commandId: string) => Effect.Effect<Option.Option<number>>;
+  /** The actor's current state, from the batch journal when there is one. */
+  readonly state: (sql: SqlClient.SqlClient, read: Effect.Effect<Option.Option<string>, SqlError.SqlError>) => Effect.Effect<Option.Option<string>, SqlError.SqlError>;
+  /** The client for the running command's journal and state writes: the batch's held client, or `sql` itself. */
+  readonly writer: (sql: SqlClient.SqlClient) => Effect.Effect<SqlClient.SqlClient>;
+};
+/** Opens the in-memory journal of one engine batch over `held`, the client whose writes the engine holds. */
+declare const commandBatch: (args_0: {
+  readonly commandIds: readonly string[];
+  readonly held: SqlClient.SqlClient;
+}) => Effect.Effect<{
+  commandIds: readonly string[];
+  current: Ref.Ref<Option.Option<Journal>>;
+  held: SqlClient.SqlClient;
+  kept: Ref.Ref<Option.Option<Journal>>;
+}, never, never>;
+/** The engine kept the running command: its journal changes stand. */
+declare const keepCommand: (batch: Batch) => Effect.Effect<void>;
+/** The engine rolled the running command back: its journal changes go with it. */
+declare const dropCommand: (batch: Batch) => Effect.Effect<void>;
+export { CommandBatch, CommandBatchJournal, type Batch as CommandBatchScope, commandBatch, dropCommand, keepCommand };

package/dist/host/command/batch/command-batch.sql.mjs

@@ -0,0 +1,100 @@
+import { Array, Context, Effect, HashMap, HashSet, Option, Ref, Schema } from "effect";
+// src/host/command/batch/command-batch.sql.ts
+const CommandBatch = Context.Reference("@akterjs/effect/host/command/batch/command-batch.sql/CommandBatch", { defaultValue: Option.none });
+const firstSeq = 1;
+const nextOf = 1;
+const IdList = Schema.fromJsonString(Schema.Array(Schema.String));
+const journalRows = (sql, ids) => sql`SELECT command_id AS "commandId", command, exit, principal FROM akter_commands WHERE command_id IN (SELECT value FROM json_each(${ids}))`;
+const readJournal = Effect.fnUntraced(function* readJournal(sql, commandIds) {
+	const ids = yield* Effect.orDie(Schema.encodeEffect(IdList)(commandIds));
+	const [states, rows, last] = yield* Effect.all([
+		sql`SELECT value FROM akter_state WHERE id = 1`,
+		journalRows(sql, ids),
+		sql`SELECT coalesce(max(seq), 0) AS seq FROM akter_commands`
+	]);
+	return {
+		known: HashSet.fromIterable(commandIds),
+		nextSeq: Option.match(Array.head(last), {
+			onNone: () => firstSeq,
+			onSome: (row) => row.seq + nextOf
+		}),
+		recorded: HashMap.fromIterable(Array.map(rows, ({ commandId, ...recorded }) => [commandId, recorded])),
+		seqs: HashMap.empty(),
+		state: Option.map(Array.head(states), (row) => row.value)
+	};
+});
+/** The batch's journal, read on first use with the engine's real client. */
+const journalOf = (sql) => Effect.flatMap(CommandBatch, (batch) => Option.match(batch, {
+	onNone: () => Effect.succeedNone,
+	onSome: (open) => Effect.flatMap(Ref.get(open.current), (current) => Option.match(current, {
+		onNone: () => Effect.tap(readJournal(sql, open.commandIds), (read) => Effect.andThen(Ref.set(open.current, Option.some(read)), Ref.set(open.kept, Option.some(read)))).pipe(Effect.map((read) => Option.some([open, read]))),
+		onSome: (journal) => Effect.succeedSome([open, journal])
+	}))
+}));
+const update = (change) => Effect.flatMap(CommandBatch, (batch) => Option.match(batch, {
+	onNone: () => Effect.void,
+	onSome: (open) => Ref.update(open.current, Option.map(change))
+}));
+/** Whether a batch journal answers for this command id: it was read at the start or recorded since. */
+const answers = (journal, commandId) => HashSet.has(journal.known, commandId) || HashMap.has(journal.recorded, commandId);
+const CommandBatchJournal = {
+	/** Forgets the journal, so the next command reads it again; after journal pruning, for one. */
+	forget: Effect.flatMap(CommandBatch, (batch) => Option.match(batch, {
+		onNone: () => Effect.void,
+		onSome: (open) => Effect.andThen(Ref.set(open.current, Option.none()), Ref.set(open.kept, Option.none()))
+	})),
+	/** Notes a journal row and returns the seq it is written with, or none outside a batch. */
+	record: (commandId, recorded) => Effect.flatMap(CommandBatch, (batch) => Option.match(batch, {
+		onNone: () => Effect.succeedNone,
+		onSome: (open) => Ref.modify(open.current, (current) => Option.match(current, {
+			onNone: () => [Option.none(), current],
+			onSome: (journal) => [Option.some(journal.nextSeq), Option.some({
+				...journal,
+				nextSeq: journal.nextSeq + nextOf,
+				recorded: HashMap.set(journal.recorded, commandId, recorded),
+				seqs: HashMap.set(journal.seqs, commandId, journal.nextSeq)
+			})]
+		}))
+	})),
+	/** The recorded outcome of `commandId`, from the batch journal when it answers for the id. */
+	recorded: (sql, commandId, read) => Effect.flatMap(journalOf(sql), (opened) => Option.match(Option.filter(opened, ([, journal]) => answers(journal, commandId)), {
+		onNone: () => read,
+		onSome: ([, journal]) => Effect.succeed(HashMap.get(journal.recorded, commandId))
+	})),
+	/** Notes a state the running command saved. */
+	saved: (value) => update((journal) => ({
+		...journal,
+		state: Option.some(value)
+	})),
+	/** The seq a command recorded in this batch was given, or none when the batch did not record it. */
+	seq: (commandId) => Effect.flatMap(CommandBatch, (batch) => Option.match(batch, {
+		onNone: () => Effect.succeedNone,
+		onSome: (open) => Effect.map(Ref.get(open.current), Option.flatMap((journal) => HashMap.get(journal.seqs, commandId)))
+	})),
+	/** The actor's current state, from the batch journal when there is one. */
+	state: (sql, read) => Effect.flatMap(journalOf(sql), Option.match({
+		onNone: () => read,
+		onSome: ([, journal]) => Effect.succeed(journal.state)
+	})),
+	/** The client for the running command's journal and state writes: the batch's held client, or `sql` itself. */
+	writer: (sql) => Effect.map(CommandBatch, Option.match({
+		onNone: () => sql,
+		onSome: (open) => open.held
+	}))
+};
+const noJournal = () => Ref.make(Option.none());
+/** Opens the in-memory journal of one engine batch over `held`, the client whose writes the engine holds. */
+const commandBatch = Effect.fnUntraced(function* commandBatch({ commandIds, held }) {
+	const [current, kept] = yield* Effect.all([noJournal(), noJournal()]);
+	return {
+		commandIds,
+		current,
+		held,
+		kept
+	};
+});
+/** The engine kept the running command: its journal changes stand. */
+const keepCommand = (batch) => Effect.flatMap(Ref.get(batch.current), (current) => Ref.set(batch.kept, current));
+/** The engine rolled the running command back: its journal changes go with it. */
+const dropCommand = (batch) => Effect.flatMap(Ref.get(batch.kept), (kept) => Ref.set(batch.current, kept));
+export { CommandBatch, CommandBatchJournal, commandBatch, dropCommand, keepCommand };

package/dist/host/command/command-context.adapter.d.mts

@@ -0,0 +1,47 @@
+import { CommandEnvironment } from "../../contract/actor/actor.contract.mjs";
+import { FileStorage } from "../../contract/file/actor-files.contract.mjs";
+import { Context, Effect, Layer, Ref, Schema } from "effect";
+import { SecureRandom } from "effect/crypto";
+import { SqlClient } from "effect/sql";
+interface Tracking {
+  readonly files: FileStorage;
+  readonly key: string;
+  readonly sql: SqlClient.SqlClient;
+}
+interface TrackedContext {
+  readonly environment: CommandEnvironment;
+  readonly recorded: Effect.Effect<typeof RecordedContext.Encoded>;
+}
+declare const RecordedContext: Schema.Struct<{
+  readonly files: Schema.fromJsonString<Schema.toCodecJson<Schema.$Array<Schema.Struct<{
+    readonly receipt: Schema.String;
+    readonly row: Schema.Option<Schema.Struct<{
+      readonly actor: Schema.String;
+      readonly blob: Schema.String;
+      readonly bytes: Schema.Int;
+      readonly claim: Schema.String;
+      readonly expiresAt: Schema.Int;
+      readonly grant: Schema.String;
+      readonly receipt: Schema.String;
+      readonly sha256: Schema.String;
+      readonly state: Schema.Literals<readonly ["uploading", "prepared", "consumed", "canceled"]>;
+    }>>;
+  }>>>>;
+  readonly ids: Schema.fromJsonString<Schema.$Array<Schema.String>>;
+  readonly times: Schema.fromJsonString<Schema.$Array<Schema.Int>>;
+}>;
+type RecordedValues = typeof RecordedContext.Encoded;
+declare const CommandContext_base: Context.ServiceClass<CommandContext, "@akterjs/effect/host/command/command-context.adapter/CommandContext", {
+  readonly track: (tracking: Tracking) => Effect.Effect<TrackedContext>;
+}> & {
+  readonly make: Effect.Effect<{
+    readonly track: (tracking: Tracking) => Effect.Effect<TrackedContext>;
+  }, never, SecureRandom.SecureRandom>;
+};
+export declare class CommandContext extends CommandContext_base {
+  static readonly layer: Layer.Layer<CommandContext, never, never>;
+  /** Whether a failed statement's message reaches the caller or only the host's log. */
+  static readonly statementDetail: Context.Reference<"logged" | "shown">;
+  static replaying(random: SecureRandom.SecureRandom["Service"], script: Ref.Ref<RecordedValues>): CommandContext["Service"];
+}
+export type { RecordedValues };