@akterjs/effect 0.0.0-stage → 0.1.0

package/dist/serve/engine/actor-holding.pure.d.mts

@@ -0,0 +1,7 @@
+import { ActorAddress } from "./actor-location.service.mjs";
+import { Effect, Scope } from "effect";
+/** Runs an effect while no resident opens at the address, so nothing creates its database meanwhile. */
+type Holding = (address: ActorAddress) => <Value, Failure, Needs>(effect: Effect.Effect<Value, Failure, Needs>) => Effect.Effect<Value, Failure, Needs>;
+/** One lock per address while anything holds it, so opening one actor never waits on another's. */
+declare const addressHolding: (idOf: (address: ActorAddress) => string) => Effect.Effect<Holding, never, Scope.Scope>;
+export { type Holding, addressHolding };

package/dist/serve/engine/actor-holding.pure.mjs

@@ -0,0 +1,9 @@
+import { Effect, RcMap, Scope, Semaphore } from "effect";
+// src/serve/engine/actor-holding.pure.ts
+const onePermit = 1;
+/** One lock per address while anything holds it, so opening one actor never waits on another's. */
+const addressHolding = (idOf) => Effect.map(RcMap.make({ lookup: (_id) => Semaphore.make(onePermit) }), (locks) => (address) => (effect) => Effect.scopedWith((scope) => {
+	const lock = Scope.provide(RcMap.get(locks, idOf(address)), scope);
+	return Effect.flatMap(lock, (held) => held.withPermits(onePermit)(effect));
+}));
+export { addressHolding };

package/dist/serve/engine/actor-host.service.d.mts

@@ -0,0 +1,66 @@
+import { FileUsagePage } from "../../contract/file/actor-files.contract.mjs";
+import { ActorRegistry } from "../../contract/actor/actor-registry.service.mjs";
+import { CommandRunner } from "../../host/command/command-runner.service.mjs";
+import { ActorDatabase, OpenedActor } from "../../host/actor/actor-database.service.mjs";
+import { Runners } from "../history/actor-host-runners.service.mjs";
+import { ActorAddress, ActorLocation } from "./actor-location.service.mjs";
+import { OpenFailure, fileSessionOf } from "./actor-residents.pure.mjs";
+import { ForkCall, ForkFailure } from "./actor-fork.service.mjs";
+import { HostFailure, LiveActor } from "../live/live-reads.service.mjs";
+import { Context, Effect, FileSystem, Layer, Option, Path, Scope } from "effect";
+interface ActorCall extends ActorAddress {
+  readonly member: string;
+  readonly payload: string;
+  readonly principal: string;
+}
+interface CommandCall extends ActorCall {
+  readonly commandId: string;
+}
+interface CoverageRead extends ActorAddress {
+  readonly since: number;
+}
+interface StepsRead extends ActorAddress {
+  readonly limit?: number;
+}
+interface StepRead extends ActorAddress {
+  readonly step: string;
+}
+type Steps = Effect.Success<ReturnType<Runners["queries"]["steps"]>>;
+type Step = Effect.Success<ReturnType<Runners["queries"]["step"]>>;
+interface HistoryRead extends CoverageRead {
+  readonly after: number;
+  readonly limit: number;
+}
+interface CreateCall extends CommandCall {
+  readonly mode: "create" | "ensure";
+}
+type FileSession = NonNullable<OpenedActor["fileSession"]>;
+type History = Effect.Success<ReturnType<Runners["queries"]["history"]>>;
+type FilesUnavailable = Effect.Error<ReturnType<typeof fileSessionOf>>;
+interface Routes {
+  /** In-process local administration only; hosted actor RPCs never expose erasure. */
+  readonly erase?: (address: ActorAddress) => Effect.Effect<void, OpenFailure>;
+  readonly command: (call: CommandCall) => Effect.Effect<string, HostFailure>;
+  readonly coveredSince: (request: CoverageRead) => Effect.Effect<number, OpenFailure>;
+  readonly history: (request: HistoryRead) => Effect.Effect<History, OpenFailure>;
+  readonly create: (call: CreateCall) => Effect.Effect<string, HostFailure>;
+  readonly currentFiles: (address: ActorAddress) => Effect.Effect<Option.Option<FileSession>, OpenFailure | FilesUnavailable, Scope.Scope>;
+  readonly drain: Effect.Effect<void, HostFailure>;
+  readonly fork: (call: ForkCall) => Effect.Effect<number, ForkFailure>;
+  readonly files: (address: ActorAddress) => Effect.Effect<FileUsagePage, OpenFailure>;
+  readonly query: (call: ActorCall) => Effect.Effect<string, HostFailure>;
+  readonly prepareFiles: (address: ActorAddress) => Effect.Effect<FileSession, OpenFailure | FilesUnavailable, Scope.Scope>;
+  readonly state: (address: ActorAddress) => LiveActor["state"];
+  /** One of the actor's durable computer steps, by its key. */
+  readonly step: (request: StepRead) => Effect.Effect<Step, OpenFailure>;
+  /** The actor's durable computer steps, newest first. */
+  readonly steps: (request: StepsRead) => Effect.Effect<Steps, OpenFailure>;
+  readonly subscribe: (call: ActorCall) => ReturnType<LiveActor["subscribe"]>;
+  readonly warm: (address: ActorAddress) => Effect.Effect<void, OpenFailure>;
+}
+declare const ActorHost_base: Context.ServiceClass<ActorHost, "@akterjs/effect/serve/engine/actor-host.service/ActorHost", Routes>;
+export declare class ActorHost extends ActorHost_base {
+  static readonly historyRetention: Context.Reference<import("effect/Duration").Duration>;
+  static readonly layer: Layer.Layer<ActorHost, never, ActorDatabase | ActorLocation | ActorRegistry | CommandRunner | FileSystem.FileSystem | Path.Path>;
+}
+export type { ActorCall, CommandCall, CreateCall, HostFailure, StepRead, StepsRead };

package/dist/serve/engine/actor-host.service.mjs

@@ -0,0 +1,209 @@
+import { ActorRegistry } from "../../contract/actor/actor-registry.service.mjs";
+import { ActorDatabase } from "../../host/actor/actor-database.service.mjs";
+import { ActorUpkeep } from "../../host/upkeep/actor-upkeep.service.mjs";
+import { ActorHostRunners } from "../history/actor-host-runners.service.mjs";
+import { ActorLocation } from "./actor-location.service.mjs";
+import { blankTemplates, cachedResidents, fileIdentity, fileSessionOf, notServed, readingOf, unavailable, unavailableUnlessErased } from "./actor-residents.pure.mjs";
+import { ActorForks } from "./actor-fork.service.mjs";
+import { LiveReads } from "../live/live-reads.service.mjs";
+import { LocalActorErasure } from "../erasure/local-actor-erasure.service.mjs";
+import { Array, Context, Deferred, Effect, FileSystem, Layer, Option, Scope, Semaphore } from "effect";
+// src/serve/engine/actor-host.service.ts
+const oneCommandAtATime = 1;
+const servedActor = (address) => Effect.mapError(ActorRegistry.use((registry) => registry.lookup(address.actor)), () => notServed(address));
+const storedActor = Effect.fnUntraced(function* storedActor(address) {
+	yield* servedActor(address);
+	yield* LocalActorErasure.check(address);
+	const { database } = yield* ActorLocation.use((location) => Effect.succeed(location.locate(address)));
+	return yield* Effect.mapError(FileSystem.FileSystem.use((fileSystem) => fileSystem.exists(database)), unavailable(address.actor));
+});
+const residentGates = Effect.fnUntraced(function* residentGates(opened) {
+	const commands = yield* Semaphore.make(oneCommandAtATime);
+	const forking = yield* Semaphore.make(oneCommandAtATime);
+	return {
+		exclusive: Option.match(Option.fromNullishOr(opened.fileSession), {
+			onNone: () => commands.withPermits(oneCommandAtATime),
+			onSome: (session) => (effect) => session.home.transfers.admit(session.owner.exclusive(effect))
+		}),
+		forking
+	};
+});
+const keepResident = Effect.fnUntraced(function* keepResident(address, opened, { scope, send }) {
+	const { exclusive, forking } = yield* residentGates(opened);
+	const live = yield* LiveReads.use((reads) => reads.open({
+		exclusive,
+		opened
+	}));
+	let committed = Effect.void;
+	const commit = (effect) => exclusive(effect.pipe(Effect.tap(() => committed), Effect.ensuring(live.refresh))).pipe(forking.withPermits(oneCommandAtATime));
+	const kept = yield* Effect.provideService(ActorUpkeep.use((upkeep) => upkeep.start({
+		exclusive: commit,
+		key: address.key,
+		lock: exclusive,
+		opened,
+		read: exclusive,
+		send: ActorUpkeep.sequentialDeliveries(send)
+	})), Scope.Scope, scope);
+	({committed} = kept);
+	return {
+		commit,
+		drain: Effect.catchTag(kept.drain, "SqlError", (failure) => Effect.fail(unavailable(address.actor)(failure))),
+		exclusive,
+		forking,
+		jobs: kept.jobs,
+		kick: Effect.andThen(kept.kick, opened.fileSession?.kick ?? Effect.void),
+		live,
+		opened
+	};
+});
+const openResident = Effect.fnUntraced(function* openResident(address, scope, send) {
+	const actor = yield* servedActor(address);
+	const { database, directory } = yield* ActorLocation.use((location) => Effect.succeed(location.locate(address)));
+	yield* Effect.mapError(FileSystem.FileSystem.use((fileSystem) => fileSystem.makeDirectory(directory, { recursive: true })), unavailable(address.actor));
+	const opened = yield* Effect.mapError(Effect.provideService(ActorDatabase.use((opener) => opener.open({
+		actor,
+		filename: database,
+		identity: fileIdentity(address)
+	})), Scope.Scope, scope), unavailableUnlessErased(address.actor));
+	return yield* keepResident(address, opened, {
+		scope,
+		send
+	});
+});
+const blankOf = Effect.fnUntraced(function* blankOf(address, scope) {
+	const actor = yield* servedActor(address);
+	return yield* Effect.mapError(Effect.provideService(ActorDatabase.use((opener) => opener.blank(actor)), Scope.Scope, scope), unavailable(address.actor));
+});
+const drainPasses = 1e3;
+const drainAll = ({ addresses, use }) => {
+	const pass = Effect.gen(function* pass() {
+		const before = yield* addresses;
+		const worked = yield* Effect.forEach(before, (address) => use(address, (found) => found.drain));
+		const after = yield* addresses;
+		return Array.some(worked, Boolean) || after.length > before.length;
+	});
+	const settled = Effect.repeat(pass, {
+		times: drainPasses,
+		until: (busy) => !busy
+	});
+	return Effect.flatMap(settled, (busy) => {
+		if (busy) return Effect.die(`actors were still sending or firing after ${drainPasses} passes`);
+		return Effect.void;
+	});
+};
+const readRoutes = (reading, queries) => ({
+	coveredSince: (request) => reading.read(request, (opened) => Effect.mapError(queries.coveredSince({
+		opened,
+		since: request.since
+	}), unavailable(request.actor))),
+	currentFiles: (address) => Effect.flatMap(reading.borrowExisting(address), Option.match({
+		onNone: () => Effect.succeedNone,
+		onSome: (found) => Effect.asSome(fileSessionOf(found.opened))
+	})),
+	files: (address) => reading.read(address, (opened) => Effect.mapError(queries.files(opened), unavailable(address.actor))),
+	history: (request) => reading.read(request, (opened) => Effect.mapError(queries.history({
+		after: request.after,
+		limit: request.limit,
+		opened,
+		since: request.since
+	}), unavailable(request.actor))),
+	query: (call) => reading.read(call, (opened) => Effect.catchTag(queries.run({
+		opened,
+		request: call
+	}), "SqlError", (failure) => Effect.fail(unavailable(call.actor)(failure)))),
+	step: (request) => reading.read(request, (opened) => Effect.mapError(queries.step(opened, request.step), unavailable(request.actor))),
+	steps: (request) => reading.read(request, (opened) => Effect.mapError(queries.steps(opened, request.limit), unavailable(request.actor))),
+	warm: Effect.fn("ActorHost.warm")(function* warm(address) {
+		yield* reading.existing(address, () => Effect.void);
+	}),
+	...reading.live
+});
+const routes = (residents, { check, queries, runner }, reading) => {
+	return {
+		command: Effect.fn("ActorHost.command")((call) => residents.use(call, ({ commit, kick, opened }) => {
+			const run = Effect.catchTag(runner.run({
+				opened,
+				request: call
+			}), "SqlError", (failure) => Effect.fail(unavailable(call.actor)(failure)));
+			const checked = Effect.andThen(check(call), run);
+			return Effect.ensuring(commit(checked), kick);
+		})),
+		create: Effect.fn("ActorHost.create")((call) => residents.use(call, ({ commit, kick, opened }) => {
+			const run = Effect.catchTag(runner.create({
+				opened,
+				request: call
+			}), "SqlError", (failure) => Effect.fail(unavailable(call.actor)(failure)));
+			const checked = Effect.andThen(check(call), run);
+			return Effect.ensuring(commit(checked), kick);
+		})),
+		drain: drainAll(residents),
+		prepareFiles: (address) => Effect.flatMap(residents.borrow(address), ({ opened }) => fileSessionOf(opened)),
+		...readRoutes(reading, queries)
+	};
+};
+const forkRoute = (residents, services) => {
+	const fork = ActorForks.forkedBy({
+		identity: fileIdentity,
+		residents,
+		served: (address) => Effect.provide(servedActor(address), services),
+		stored: (address) => Effect.provide(storedActor(address), services)
+	});
+	return (call) => Effect.provide(fork(call), services);
+};
+const reopenStored = Effect.fnUntraced(function* reopenStored(residents) {
+	const { list } = yield* ActorLocation;
+	const upkeep = yield* ActorUpkeep;
+	yield* ActorForks.sweepStaged(fileIdentity).pipe(Effect.catch((error) => Effect.logWarning(`could not sweep unfinished forks: ${error.message}`)));
+	yield* upkeep.locateJobs((address) => Effect.orDie(Effect.map(residents.borrow(address), (found) => found.jobs)));
+	const reopenAll = Effect.flatMap(list, (addresses) => Effect.flatMap(Effect.forEach(addresses, (address) => Effect.exit(residents.use(address, () => Effect.void))), (opened) => Effect.asVoid(Effect.all(opened))));
+	yield* Effect.forkScoped(upkeep.keep(reopenAll, "reopening stored actors at start"));
+});
+const finishErasures = (erase) => Effect.flatMap(ActorLocation.use((location) => location.erased), (addresses) => Effect.forEach(addresses, erase, { discard: true })).pipe(Effect.ignore({
+	log: "Warn",
+	message: "could not finish actor erasure"
+}));
+var ActorHost = class extends Context.Service()("@akterjs/effect/serve/engine/actor-host.service/ActorHost") {
+	static historyRetention = ActorHostRunners.historyRetention;
+	static layer = Layer.effect(this, Effect.gen(function* makeActorHost() {
+		const services = yield* Effect.context();
+		const { erasure, runners, scope, self } = yield* Effect.all({
+			erasure: LocalActorErasure.make,
+			runners: ActorHostRunners.make,
+			scope: Effect.scope,
+			self: Deferred.make()
+		});
+		const send = (call) => Effect.flatMap(Deferred.await(self), (host) => host.command(call));
+		const residents = yield* cachedResidents({
+			check: erasure.check,
+			open: (address) => erasure.open(address, (owned) => Effect.tap(Effect.provide(openResident(address, owned, send), services), runners.prune))
+		});
+		const blanks = yield* Effect.all({
+			current: LiveReads.use((reads) => Effect.succeed(reads.current)),
+			template: blankTemplates({
+				build: (address, owned) => Effect.provide(blankOf(address, owned), services),
+				scope
+			})
+		});
+		const host = {
+			...routes(residents, {
+				...runners,
+				check: erasure.check
+			}, readingOf({
+				blanks,
+				residents,
+				stored: (address) => Effect.provide(storedActor(address), services)
+			})),
+			erase: (address) => residents.holding(address)(Effect.andThen(erasure.erase(address), residents.forget(address))),
+			fork: forkRoute(residents, services)
+		};
+		yield* finishErasures(erasure.erase);
+		yield* Deferred.succeed(self, host).pipe(Effect.andThen(reopenStored(residents)), Effect.andThen(runners.keep(residents)));
+		return host;
+	})).pipe(Layer.provide([
+		ActorForks.computers,
+		ActorUpkeep.layer,
+		LiveReads.layer,
+		ActorHostRunners.queries
+	]));
+};
+export { ActorHost };

package/dist/serve/engine/actor-location.service.d.mts

@@ -0,0 +1,38 @@
+import { StoreUnreadableError } from "../store/store-unreadable.errors.mjs";
+import { Context, Effect, FileSystem, Layer, Path } from "effect";
+interface ActorAddress {
+  readonly actor: string;
+  readonly key: string;
+}
+interface Staging {
+  readonly address: ActorAddress;
+  readonly fork: string;
+}
+interface ActorFiles {
+  readonly database: string;
+  readonly directory: string;
+}
+/** A fork's staged copy left beside its child's directory, named by the fork's id. */
+interface StagedFork {
+  readonly files: ActorFiles;
+  readonly fork: string;
+}
+declare const ActorLocation_base: Context.ServiceClass<ActorLocation, "@akterjs/effect/serve/engine/actor-location.service/ActorLocation", {
+  /** The directory the store's local computers live in, under each actor's type and key. */
+  readonly computers: string;
+  readonly erased: Effect.Effect<readonly ActorAddress[], StoreUnreadableError>;
+  readonly list: Effect.Effect<readonly ActorAddress[], StoreUnreadableError>;
+  readonly locate: (address: ActorAddress) => ActorFiles;
+  readonly stage: (staging: Staging) => ActorFiles;
+  /** Every fork's staged copy still on disk, which only a fork that never published leaves. */
+  readonly staged: Effect.Effect<readonly StagedFork[], StoreUnreadableError>;
+}>;
+export declare class ActorLocation extends ActorLocation_base {
+  /**
+   * An actor named as `<Actor>/<key segment>`, the form Akter Cloud also writes, such as a fork's `fork.origin`, so
+   * one parser reads either engine's export.
+   */
+  static readonly named: ({ actor, key }: ActorAddress) => string;
+  static readonly directory: (directory: string) => Layer.Layer<ActorLocation, never, FileSystem.FileSystem | Path.Path>;
+}
+export type { ActorAddress, ActorFiles, StagedFork };

package/dist/serve/engine/actor-location.service.mjs

@@ -0,0 +1,109 @@
+import { shardDirectory } from "./actor-shard.pure.mjs";
+import { StoreUnreadableError } from "../store/store-unreadable.errors.mjs";
+import { Array, Context, Effect, FileSystem, Layer, Option, Order, Path, String } from "effect";
+// src/serve/engine/actor-location.service.ts
+const dotsOnly = /^\.*$/u;
+const emptyKey = "%";
+const databaseFile = "actor.db";
+const stagedPrefix = "@fork-";
+const actorDatabase = /^\d+\/(?<actor>[^/]+)\/(?<segment>[^/]+)\/actor\.db$/u;
+const byActorThenKey = Order.combine(Order.mapInput(Order.String, (address) => address.actor), Order.mapInput(Order.String, (address) => address.key));
+const keySegment = (key) => {
+	const encoded = encodeURIComponent(key);
+	if (encoded === "") return emptyKey;
+	if (dotsOnly.test(encoded)) return String.replaceAll(".", "%2E")(encoded);
+	return encoded;
+};
+const decodeKey = Option.liftThrowable(decodeURIComponent);
+const keyOf = (segment) => {
+	if (segment === emptyKey) return Option.some("");
+	return decodeKey(segment);
+};
+const addressOf = (entry) => {
+	const groups = actorDatabase.exec(entry)?.groups;
+	const actor = Option.fromNullishOr(groups?.actor);
+	const segment = Option.flatMap(Option.fromNullishOr(groups?.segment), keyOf);
+	return Option.all({
+		actor,
+		key: segment
+	}).pipe(Option.filter((address) => entry === `${shardDirectory(address.key)}/${address.actor}/${keySegment(address.key)}/${databaseFile}`));
+};
+const filesAt = (path, home) => ({
+	database: path.join(home, databaseFile),
+	directory: home
+});
+const stagedAt = (path, directory) => {
+	const name = path.basename(directory);
+	return Option.map(decodeKey(String.slice(6)(name)), (fork) => ({
+		files: filesAt(path, directory),
+		fork
+	}));
+};
+const shardsPresent = ({ fileSystem, root }) => Effect.gen(function* isShardsDirectory() {
+	if (!(yield* fileSystem.exists(root))) return false;
+	return (yield* fileSystem.lstat(root)).type === "Directory";
+});
+const stagedIn = (shards) => Effect.gen(function* listStaged() {
+	if (!(yield* shardsPresent(shards))) return [];
+	const entries = yield* shards.fileSystem.glob(`*/*/${stagedPrefix}*/`, { root: shards.root });
+	return Array.getSomes(Array.map(entries, (entry) => stagedAt(shards.path, shards.path.join(shards.root, entry))));
+});
+const erasedIn = (shards) => Effect.gen(function* erasedActors() {
+	if (!(yield* shardsPresent(shards))) return [];
+	const entries = yield* shards.fileSystem.glob("**/actor.db.erased", {
+		dot: true,
+		root: shards.root
+	});
+	return Array.getSomes(Array.map(entries, (entry) => {
+		const database = String.replace(/\.erased$/u, "")(entry);
+		return addressOf(String.replaceAll(shards.path.sep, "/")(database));
+	}));
+});
+const placesIn = (path, shards) => {
+	const kindOf = ({ actor, key }) => path.join(shards, shardDirectory(key), actor);
+	return {
+		locate: (address) => filesAt(path, path.join(kindOf(address), keySegment(address.key))),
+		stage: ({ address, fork }) => filesAt(path, path.join(kindOf(address), `${stagedPrefix}${encodeURIComponent(fork)}`))
+	};
+};
+var ActorLocation = class extends Context.Service()("@akterjs/effect/serve/engine/actor-location.service/ActorLocation") {
+	/**
+	* An actor named as `<Actor>/<key segment>`, the form Akter Cloud also writes, such as a fork's `fork.origin`, so
+	* one parser reads either engine's export.
+	*/
+	static named = ({ actor, key }) => `${actor}/${keySegment(key)}`;
+	static directory = (directory) => Layer.effect(this, Effect.gen(function* makeActorLocation() {
+		const fileSystem = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const shards = path.join(directory, "shards");
+		const at = {
+			fileSystem,
+			path,
+			root: shards
+		};
+		const unreadable = (failure) => StoreUnreadableError.make({
+			directory,
+			message: failure.message
+		});
+		const list = Effect.gen(function* list() {
+			if (!(yield* shardsPresent(at))) return [];
+			const entries = yield* fileSystem.glob("**/actor.db", {
+				dot: true,
+				root: shards
+			});
+			const files = yield* Effect.filter(entries, (entry) => Effect.gen(function* readableActor() {
+				const stored = path.join(shards, entry);
+				return (yield* fileSystem.lstat(stored)).type === "File" && !(yield* fileSystem.exists(`${stored}.erased`));
+			}));
+			return Array.sort(Array.getSomes(Array.map(files, (entry) => addressOf(String.replaceAll(path.sep, "/")(entry)))), byActorThenKey);
+		}).pipe(Effect.mapError(unreadable));
+		return {
+			computers: path.join(directory, "computers"),
+			erased: Effect.mapError(erasedIn(at), unreadable),
+			list,
+			staged: Effect.mapError(stagedIn(at), unreadable),
+			...placesIn(path, shards)
+		};
+	}));
+};
+export { ActorLocation };

package/dist/serve/engine/actor-residents.pure.d.mts

@@ -0,0 +1,92 @@
+import { ActorUnavailableError } from "../../contract/client/actor-unavailable.errors.mjs";
+import { ActorErasedError } from "../../contract/actor/actor-erased.errors.mjs";
+import { InvalidRequestError } from "../../contract/client/invalid-request.errors.mjs";
+import { FilesUnavailableError } from "../../contract/file/files-unavailable.errors.mjs";
+import { OpenedActor } from "../../host/actor/actor-database.service.mjs";
+import { QueryRequest } from "../../host/query/query-runner.service.mjs";
+import { Holding } from "./actor-holding.pure.mjs";
+import { ActorAddress } from "./actor-location.service.mjs";
+import { LiveActor, LiveReading } from "../live/live-reads.service.mjs";
+import { Deferred, Effect, HashMap, MutableHashMap, Option, Scope, Stream, SynchronizedRef } from "effect";
+type OpenFailure = ActorErasedError | ActorUnavailableError | InvalidRequestError;
+type Lookup<Value> = (address: ActorAddress) => Effect.Effect<Value, OpenFailure>;
+type Borrow<Value> = (address: ActorAddress) => Effect.Effect<Value, OpenFailure, Scope.Scope>;
+interface Held {
+  readonly live: LiveActor;
+  readonly opened: OpenedActor;
+}
+interface Cached<Resident> {
+  readonly address: ActorAddress;
+  readonly value: Resident;
+}
+type Using<Resident> = <Value, Failure, Needs>(address: ActorAddress, use: (resident: Resident) => Effect.Effect<Value, Failure, Needs>) => Effect.Effect<Value, Failure | OpenFailure, Needs>;
+type Streaming<Resident> = <Value, Failure, Needs>(address: ActorAddress, use: (resident: Resident) => Stream.Stream<Value, Failure, Needs>) => Stream.Stream<Value, Failure | OpenFailure, Needs>;
+interface Residents<Resident> {
+  readonly addresses: Effect.Effect<readonly ActorAddress[]>;
+  readonly borrow: Borrow<Resident>;
+  readonly forget: (address: ActorAddress) => Effect.Effect<void>;
+  /** Runs `effect` while no resident opens at `address`, so nothing creates its database meanwhile. */
+  readonly holding: Holding;
+  readonly use: Using<Resident>;
+  readonly stream: Streaming<Resident>;
+  readonly watch: (address: ActorAddress) => Effect.Effect<ResidentWatch<Resident>, never, Scope.Scope>;
+}
+interface Arrival<Resident> {
+  readonly resident: Deferred.Deferred<Resident>;
+  readonly waiting: readonly Deferred.Deferred<boolean>[];
+}
+interface ResidentWatch<Resident> {
+  readonly updates: <Value, Failure, Needs>(use: (resident: Resident) => Stream.Stream<Value, Failure, Needs>) => Stream.Stream<Value, Failure, Needs>;
+  readonly current: boolean;
+  readonly ready: Effect.Effect<void>;
+}
+interface Cache<Resident> {
+  readonly arrivals: MutableHashMap.MutableHashMap<string, Arrival<Resident>>;
+  readonly check: (address: ActorAddress) => Effect.Effect<void, OpenFailure>;
+  readonly holding: Holding;
+  readonly residents: SynchronizedRef.SynchronizedRef<HashMap.HashMap<string, Cached<Resident>>>;
+  readonly scope: Scope.Scope;
+}
+type Guarded = <Value, Failure>(address: ActorAddress, use: (opened: OpenedActor) => Effect.Effect<Value, Failure>) => Effect.Effect<Value, Failure | OpenFailure>;
+type Build = (address: ActorAddress, scope: Scope.Scope) => Effect.Effect<OpenedActor, OpenFailure>;
+interface Templating {
+  readonly build: Build;
+  readonly scope: Scope.Scope;
+}
+interface Blanks {
+  readonly current: (opened: OpenedActor) => LiveReading;
+  readonly template: Guarded;
+}
+interface LiveRoutes {
+  readonly state: (address: ActorAddress) => LiveActor["state"];
+  readonly subscribe: (call: ActorAddress & QueryRequest) => ReturnType<LiveActor["subscribe"]>;
+}
+interface Reading<Resident> {
+  readonly borrowExisting: Borrow<Option.Option<Resident>>;
+  readonly existing: <Value, Failure, Needs>(address: ActorAddress, use: (resident: Option.Option<Resident>) => Effect.Effect<Value, Failure, Needs>) => Effect.Effect<Value, Failure | OpenFailure, Needs>;
+  readonly live: LiveRoutes;
+  readonly read: Guarded;
+}
+declare const unavailable: (actor: string) => (failure: {
+  readonly message: string;
+}) => ActorUnavailableError;
+declare const unavailableUnlessErased: (actor: string) => (failure: ActorErasedError | {
+  readonly message: string;
+}) => ActorErasedError | ActorUnavailableError;
+/** The identity the local engine holds an actor's files by: its name's length, its name, then its key. */
+declare const fileIdentity: ({ actor, key }: ActorAddress) => string;
+declare const notServed: (address: ActorAddress) => InvalidRequestError;
+declare const cachedResidents: <Resident>({ open, check }: {
+  readonly open: Lookup<Resident>;
+  readonly check?: Cache<Resident>["check"];
+}) => Effect.Effect<Residents<Resident>, never, Scope.Scope>;
+declare const blankTemplates: (templating: Templating) => Effect.Effect<Guarded>;
+interface ReadingParts<Resident> {
+  readonly blanks: Blanks;
+  readonly residents: Residents<Resident>;
+  readonly stored: Lookup<boolean>;
+}
+declare const readingOf: <Resident extends Held>({ blanks, residents, stored }: ReadingParts<Resident>) => Reading<Resident>;
+type FileSession = NonNullable<OpenedActor["fileSession"]>;
+declare const fileSessionOf: ({ fileSession }: OpenedActor) => Effect.Effect<FileSession, FilesUnavailableError>;
+export { type OpenFailure, type Reading, type Residents, blankTemplates, cachedResidents, fileIdentity, fileSessionOf, notServed, readingOf, unavailable, unavailableUnlessErased };