@akterjs/effect 0.0.0-stage → 0.1.1

package/src/contract/actor/actor-definition.pure.ts

@@ -0,0 +1,157 @@
+import { Array as Arr, Context, Option, Record as Rec, Schema, pipe } from "effect";
+import type { Effect } from "effect";
+import { Rpc, RpcGroup } from "effect/rpc";
+
+import type {
+  ActorDefinition,
+  ActorHandlers,
+  AddressedCommand,
+  AddressedCommands,
+  ActorOptions,
+  DefinitionOf,
+  HostedActor,
+  PrincipalOf,
+  StateFields,
+} from "./actor.contract.js";
+import {
+  computerRpcsOf,
+  creationErrors,
+  creationModesOf,
+  fileRpcsOf,
+  forkRpcOf,
+} from "#src/contract/client/actor-rpc.contract";
+import type { ActorRpcs, CreationMode } from "#src/contract/client/actor-rpc.contract";
+import { Authentication } from "#src/contract/caller/authentication.api";
+import { CommandId } from "#src/contract/command/command-id.schema";
+import { declaredSchema } from "#src/contract/command/command.contract";
+import type { PlainSchema } from "#src/contract/command/command.contract";
+import { HostedFailure } from "#src/contract/hosted/hosted-failure.schema";
+import { Principal } from "#src/contract/caller/principal.schema";
+import { rejectInvalidSecrets, rejectReserved } from "./actor-names.pure.js";
+import type { Declaring } from "./actor-names.pure.js";
+
+function definitionOf<Options extends ActorOptions>(declaring: Declaring<Options>): DefinitionOf<Options>;
+function definitionOf(declaring: Declaring<ActorOptions>): ActorDefinition {
+  const { options } = declaring;
+
+  rejectReserved(declaring);
+  rejectInvalidSecrets(declaring);
+
+  return {
+    callers: options.callers ?? { user: Principal },
+    commands: options.commands,
+    create: pipe(
+      Option.fromNullishOr(options.create),
+      Option.match({ onNone: (): PlainSchema => Schema.Never, onSome: (input): PlainSchema => declaredSchema(input) }),
+    ),
+    // A declaration admitting no caller kind, as the plain SDK compiles an actor without files to, is none.
+    fileAccess: Option.filter(Option.fromNullishOr(options.files), (declared) =>
+      Option.exists(declared.callers, Arr.isReadonlyArrayNonEmpty),
+    ),
+    jobs: options.jobs ?? {},
+    key: options.key,
+    queries: options.queries ?? {},
+    secrets: Arr.dedupe(options.secrets ?? []),
+    state: options.state,
+  };
+}
+
+interface Naming<Name extends string, Definition extends ActorDefinition> {
+  readonly definition: Definition;
+  readonly name: Name;
+}
+
+function commandsOf<Name extends string, Definition extends ActorDefinition>(
+  naming: Naming<Name, Definition>,
+): AddressedCommands<Name, Definition>;
+function commandsOf({ definition, name }: Naming<string, ActorDefinition>): Readonly<Record<string, AddressedCommand>> {
+  return Rec.map(definition.commands, (declaration, member) => ({
+    ...declaration,
+    address: { actor: name, key: definition.key, member },
+  }));
+}
+
+function initialOf<Options extends ActorOptions>(options: Options): Option.Option<() => Options["state"]["Type"]>;
+function initialOf(options: ActorOptions): Option.Option<() => StateFields> {
+  return Option.fromNullishOr(options.initial);
+}
+
+function principalOf<Definition extends ActorDefinition, Needs>(
+  principal: Effect.Effect<Principal, never, Needs>,
+): Effect.Effect<PrincipalOf<Definition>, never, Needs>;
+function principalOf<Needs>(principal: Effect.Effect<Principal, never, Needs>): Effect.Effect<Principal, never, Needs> {
+  return principal;
+}
+
+const handlersKey = <Name extends string>(name: Name): Context.Key<ActorHandlers<Name>, HostedActor> =>
+  Context.Service<ActorHandlers<Name>, HostedActor>(`@akterjs/effect/contract/actor-handlers/${name}`);
+
+const failureOf = (declared: PlainSchema): PlainSchema => Schema.Union([declared, HostedFailure]);
+
+const updateOf = (value: PlainSchema): PlainSchema => Schema.Struct({ value, version: Schema.Int });
+
+const subscriptionTag = (name: string, member: string): `${string}/${string}/subscribe` =>
+  `${name}/${member}/subscribe`;
+
+const creationTag = (name: string, mode: CreationMode): `${string}/${string}` => `${name}/${mode}`;
+
+const created: PlainSchema = Schema.Void;
+
+const warmTag = (name: string): `${string}/warm` => `${name}/warm`;
+
+interface NamedDefinition {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+}
+
+const rpcsOf = ({ definition, name }: NamedDefinition): ActorRpcs =>
+  RpcGroup.make(
+    ...Arr.map(Rec.toEntries(definition.commands), ([member, declaration]) =>
+      Rpc.make(`${name}/${member}`, {
+        error: failureOf(declaration.error),
+        payload: { commandId: CommandId, key: definition.key, payload: declaration.payload },
+        success: declaration.success,
+      }),
+    ),
+    ...Arr.map(Rec.toEntries(definition.queries), ([member, declaration]) =>
+      Rpc.make(`${name}/${member}`, {
+        error: failureOf(declaration.error),
+        payload: { key: definition.key, payload: declaration.payload },
+        success: declaration.success,
+      }),
+    ),
+    ...Arr.map(Rec.toEntries(definition.queries), ([member, declaration]) =>
+      Rpc.make(subscriptionTag(name, member), {
+        error: failureOf(declaration.error),
+        payload: { key: definition.key, payload: declaration.payload },
+        stream: true,
+        success: updateOf(declaration.success),
+      }),
+    ),
+    ...Arr.map(creationModesOf(definition.create), (mode) =>
+      Rpc.make(creationTag(name, mode), {
+        error: failureOf(creationErrors[mode]),
+        payload: { commandId: CommandId, key: definition.key, payload: definition.create },
+        success: created,
+      }),
+    ),
+    Rpc.make(warmTag(name), {
+      error: failureOf(Schema.Never),
+      payload: { key: definition.key },
+    }),
+    Rpc.make(subscriptionTag(name, "state"), {
+      error: failureOf(Schema.Never),
+      payload: { key: definition.key },
+      stream: true,
+      success: updateOf(definition.state),
+    }),
+    ...Option.match(definition.fileAccess, { onNone: () => [], onSome: () => fileRpcsOf(name) }),
+    forkRpcOf({ actor: name, key: definition.key }),
+    ...computerRpcsOf(name),
+  ).middleware(Authentication);
+
+export { reservedMembers } from "./actor-names.pure.js";
+
+export { fileAccess } from "#src/contract/file/access/file-access.contract";
+
+export { commandsOf, definitionOf, handlersKey, initialOf, principalOf, rpcsOf };

package/src/contract/actor/actor-erased.errors.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+
+export class ActorErasedError extends Schema.TaggedError<ActorErasedError, { readonly brand: unique symbol }>()(
+  "ActorErasedError",
+  {
+    actor: Schema.String,
+  },
+) {}

package/src/contract/actor/actor-names.pure.ts

@@ -0,0 +1,64 @@
+import { Array as Arr, Option, Record as Rec, Schema } from "effect";
+
+import type { ActorOptions, ReservedMember } from "./actor.contract.js";
+import { ReservedMemberError } from "./reserved-member.errors.js";
+import { InvalidSecretNameError } from "#src/contract/secret/invalid-secret-name.errors";
+import { SecretName } from "#src/contract/secret/secret.schema";
+
+const isSecretName = Schema.is(SecretName);
+
+/** Every name the actor object and its clients use, so no command or query may take one. */
+const reservedMembers: readonly ReservedMember[] = [
+  "callers",
+  "client",
+  "commands",
+  "computer",
+  "create",
+  "ensure",
+  "files",
+  "fork",
+  "handlers",
+  "history",
+  "historyStream",
+  "initial",
+  "jobs",
+  "key",
+  "name",
+  "principal",
+  "queries",
+  "rpcs",
+  "secret",
+  "secrets",
+  "state",
+  "then",
+  "toLayer",
+  "update",
+  "warm",
+];
+
+interface Declaring<Options extends ActorOptions> {
+  readonly name: string;
+  readonly options: Options;
+}
+
+const rejectReserved = ({ name, options }: Declaring<ActorOptions>): void => {
+  const members = [...Rec.keys(options.commands), ...Rec.keys(options.queries ?? {})];
+  const reserved = Arr.findFirst(members, (member) => Arr.contains(reservedMembers, member));
+
+  if (Option.isSome(reserved)) {
+    throw ReservedMemberError.make({ actor: name, member: reserved.value });
+  }
+};
+
+/** A secret name no environment could set is a mistake in the declaration, refused where the actor is made. */
+const rejectInvalidSecrets = ({ name, options }: Declaring<ActorOptions>): void => {
+  const invalid = Arr.findFirst(options.secrets ?? [], (secret) => !isSecretName(secret));
+
+  if (Option.isSome(invalid)) {
+    throw InvalidSecretNameError.make({ actor: name, secret: invalid.value });
+  }
+};
+
+export { rejectInvalidSecrets, rejectReserved, reservedMembers };
+
+export type { Declaring };

package/src/contract/actor/actor-not-created.errors.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+
+export class ActorNotCreatedError extends Schema.TaggedError<ActorNotCreatedError, { readonly brand: unique symbol }>()(
+  "ActorNotCreatedError",
+  {
+    actor: Schema.String,
+  },
+) {}

package/src/contract/actor/actor-not-registered.errors.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+
+export class ActorNotRegisteredError extends Schema.TaggedError<
+  ActorNotRegisteredError,
+  { readonly brand: unique symbol }
+>()("ActorNotRegisteredError", {
+  actor: Schema.String,
+}) {}

package/src/contract/actor/actor-registry.service.ts

@@ -0,0 +1,35 @@
+import { Context, Effect, HashMap, Layer, Option, Ref } from "effect";
+
+import type { HostedActor } from "./actor.contract.js";
+import { ActorNotRegisteredError } from "./actor-not-registered.errors.js";
+
+export class ActorRegistry extends Context.Service<
+  ActorRegistry,
+  {
+    readonly lookup: (name: string) => Effect.Effect<HostedActor, ActorNotRegisteredError>;
+    readonly register: (actor: HostedActor) => Effect.Effect<void>;
+  }
+>()("@akterjs/effect/contract/actor/actor-registry.service/ActorRegistry", {
+  make: Effect.gen(function* makeActorRegistry() {
+    const actors = yield* Ref.make(HashMap.empty<string, HostedActor>());
+
+    const register = Effect.fn("ActorRegistry.register")(function* register(actor: HostedActor) {
+      yield* Ref.update(actors, HashMap.set(actor.name, actor));
+    });
+
+    const lookup = Effect.fn("ActorRegistry.lookup")(function* lookup(name: string) {
+      const current = yield* Ref.get(actors);
+      const found = HashMap.get(current, name);
+
+      if (Option.isNone(found)) {
+        return yield* ActorNotRegisteredError.make({ actor: name });
+      }
+
+      return found.value;
+    });
+
+    return { lookup, register } as const;
+  }),
+}) {
+  public static readonly layer = Layer.effect(this, this.make);
+}

package/src/contract/actor/actor.contract.ts

@@ -0,0 +1,409 @@
+import type { Context, Effect, Exit, Layer, Option, Schema } from "effect";
+import type { SqlClient, SqlError } from "effect/sql";
+
+import type { ClientOf, ComputerClientOf, FileClientOf, SecretOf } from "#src/contract/client/actor-client.adapter";
+import type { ActorRpcs } from "#src/contract/client/actor-rpc.contract";
+import type { ActorState, FileStorage } from "#src/contract/state/actor-state.service";
+import type { Akter } from "#src/contract/akter.service";
+import type {
+  ActorJobs,
+  AnyCommand,
+  AnyQuery,
+  Declared,
+  DeclaredSchema,
+  Jobs,
+  NoJobs,
+  PlainSchema,
+} from "#src/contract/command/command.contract";
+import type {
+  FileAccess,
+  FileAccessDeniedError,
+  FileAccessRequest,
+} from "#src/contract/file/access/file-access.contract";
+import type { HostedError, HostedOutcome, StateUnreadableError } from "#src/contract/hosted/hosted-error.contract";
+import type { Principal } from "#src/contract/caller/principal.schema";
+
+type Decoded = PlainSchema["Type"];
+
+type StateFields = Readonly<Record<string, Decoded>>;
+
+type KeySchema = PlainSchema & { readonly Encoded: string };
+
+type StateSchema = PlainSchema & { readonly Type: StateFields };
+
+type PrincipalSchema = PlainSchema & { readonly Type: Principal };
+
+type CallersSchemas = Readonly<Record<string, PrincipalSchema>>;
+
+type DefaultCallers = Readonly<Record<"user", typeof Principal>>;
+
+interface CommandAddress<
+  Name extends string = string,
+  Key extends KeySchema = KeySchema,
+  Member extends string = string,
+> {
+  readonly actor: Name;
+  readonly key: Key;
+  readonly member: Member;
+}
+
+interface AddressedCommand extends AnyCommand {
+  readonly address: CommandAddress;
+}
+
+interface ActorDefinition {
+  readonly callers: CallersSchemas;
+  readonly commands: Readonly<Record<string, AnyCommand>>;
+  readonly create: PlainSchema;
+  /** Which caller kinds may make file calls, as `Akter.fileAccess` declared it; none means the actor has no file calls. */
+  readonly fileAccess: Option.Option<FileAccess>;
+  readonly jobs: Jobs;
+  readonly key: KeySchema;
+  readonly queries: Readonly<Record<string, AnyQuery>>;
+  /** The secrets the actor's job activities may read, by name. Nothing reads one it doesn't list. */
+  readonly secrets: readonly string[];
+  readonly state: StateSchema;
+}
+
+interface ActorOptions {
+  readonly callers?: CallersSchemas;
+  readonly commands: Readonly<Record<string, AnyCommand>>;
+  readonly create?: Declared;
+  readonly files?: FileAccess;
+  readonly initial?: () => StateFields;
+  readonly jobs?: Jobs;
+  readonly key: KeySchema;
+  readonly queries?: Readonly<Record<string, AnyQuery>>;
+  readonly secrets?: readonly string[];
+  readonly state: StateSchema;
+}
+
+type NoQueries = Readonly<Record<string, never>>;
+
+interface TypeError<Message extends string> {
+  readonly "Akter type error": Message;
+}
+
+interface DefinitionOf<Options extends ActorOptions> {
+  readonly callers: Options extends { readonly callers: infer Callers extends CallersSchemas }
+    ? Callers
+    : DefaultCallers;
+  readonly commands: Options["commands"];
+  readonly create: Options extends { readonly create: infer Input extends Declared }
+    ? DeclaredSchema<Input>
+    : Schema.Never;
+  readonly fileAccess: Options extends { readonly files: infer Files extends FileAccess }
+    ? Option.Some<Files>
+    : Option.None<never>;
+  readonly jobs: Options extends { readonly jobs: infer Declaring extends Jobs } ? Declaring : NoJobs;
+  readonly key: Options["key"];
+  readonly queries: Options extends { readonly queries: infer Queries extends Readonly<Record<string, AnyQuery>> }
+    ? Queries
+    : NoQueries;
+  readonly secrets: Options extends { readonly secrets: infer Names extends readonly string[] } ? Names : readonly [];
+  readonly state: Options["state"];
+}
+
+type CreationCheck<Options extends ActorOptions> = Options extends { readonly initial: () => infer Initial }
+  ? Options extends { readonly create: Declared }
+    ? TypeError<"declare initial or create, not both">
+    : Initial extends Options["state"]["Type"]
+      ? unknown
+      : TypeError<"initial must return the state">
+  : Options extends { readonly create: Declared }
+    ? unknown
+    : TypeError<"declare initial or create">;
+
+type MemberNamesCheck<Options extends ActorOptions> = Options extends {
+  readonly queries: infer Queries extends Readonly<Record<string, AnyQuery>>;
+}
+  ? [Extract<keyof Options["commands"], keyof Queries>] extends [never]
+    ? unknown
+    : TypeError<`'${Extract<keyof Options["commands"], keyof Queries> & string}' is both a command and a query`>
+  : unknown;
+
+type KindsOf<Members extends Readonly<Record<string, AnyCommand | AnyQuery>>> = {
+  readonly [Name in keyof Members]: Extract<Members[Name]["callers"], { readonly _tag: "Some" }>["value"][number];
+}[keyof Members];
+
+type FileKindsOf<Options extends ActorOptions> = Options extends { readonly files: FileAccess<infer Kinds> }
+  ? Kinds
+  : never;
+
+type UndeclaredKinds<Options extends ActorOptions> = Exclude<
+  KindsOf<Options["commands"]> | KindsOf<DefinitionOf<Options>["queries"]> | FileKindsOf<Options>,
+  keyof DefinitionOf<Options>["callers"]
+>;
+
+type ReservedMember =
+  | "callers"
+  | "client"
+  | "commands"
+  | "computer"
+  | "create"
+  | "ensure"
+  | "files"
+  | "fork"
+  | "handlers"
+  | "history"
+  | "historyStream"
+  | "initial"
+  | "jobs"
+  | "key"
+  | "name"
+  | "principal"
+  | "queries"
+  | "rpcs"
+  | "secret"
+  | "secrets"
+  | "state"
+  | "then"
+  | "toLayer"
+  | "update"
+  | "warm";
+
+type ReservedOf<Options extends ActorOptions> = Extract<
+  keyof Options["commands"] | keyof DefinitionOf<Options>["queries"],
+  ReservedMember
+>;
+
+type ReservedNamesCheck<Options extends ActorOptions> = [ReservedOf<Options>] extends [never]
+  ? unknown
+  : TypeError<`'${ReservedOf<Options> & string}' is a reserved member name`>;
+
+type CallersCheck<Options extends ActorOptions> = [UndeclaredKinds<Options>] extends [never]
+  ? unknown
+  : TypeError<`'${UndeclaredKinds<Options>}' is not a declared caller`>;
+
+type OptionsCheck<Options extends ActorOptions> = CreationCheck<Options> &
+  MemberNamesCheck<Options> &
+  ReservedNamesCheck<Options> &
+  CallersCheck<Options>;
+
+type StateOf<Definition extends ActorDefinition> = Definition["state"]["Type"];
+
+type PrincipalOf<Definition extends ActorDefinition> = Definition["callers"][keyof Definition["callers"]]["Type"];
+
+type ScopeFailure = Effect.Error<FileStorage["available"]> | SqlError.SqlError;
+
+type CommandHandler<Definition extends ActorDefinition, Name extends keyof Definition["commands"]> = (
+  state: StateOf<Definition>,
+  payload: Definition["commands"][Name]["payload"]["Type"],
+) => Effect.Effect<
+  Definition["commands"][Name]["success"]["Type"],
+  Definition["commands"][Name]["error"]["Type"] | ScopeFailure,
+  Akter | ActorState
+>;
+
+type QueryHandler<Definition extends ActorDefinition, Name extends keyof Definition["queries"]> = (
+  state: StateOf<Definition>,
+  payload: Definition["queries"][Name]["payload"]["Type"],
+) => Effect.Effect<
+  Definition["queries"][Name]["success"]["Type"],
+  Definition["queries"][Name]["error"]["Type"] | ScopeFailure,
+  Akter
+>;
+
+/** The job a result belongs to: `id` is the id `Akter.start` returned when the job was started. */
+interface FinishedJob {
+  readonly id: string;
+}
+
+type ResultHandler<Definition extends ActorDefinition, Name extends keyof Definition["jobs"]> = (
+  state: StateOf<Definition>,
+  result: Exit.Exit<Definition["jobs"][Name]["success"]["Type"], Definition["jobs"][Name]["error"]["Type"]>,
+  job: FinishedJob,
+) => Effect.Effect<void, ScopeFailure, Akter | ActorState>;
+
+/** Decides one file call from the actor's state and the verified caller (`Actor.principal`), never the request. */
+type FileAuthorizer<Definition extends ActorDefinition> = (
+  state: StateOf<Definition>,
+  request: (typeof FileAccessRequest)["Type"],
+) => Effect.Effect<void, FileAccessDeniedError | ScopeFailure, Akter>;
+
+interface FileRules<Definition extends ActorDefinition> {
+  readonly authorize: FileAuthorizer<Definition>;
+}
+
+type CreateHandler<Definition extends ActorDefinition> = (
+  input: Definition["create"]["Type"],
+) => Effect.Effect<StateOf<Definition>, ScopeFailure, Akter>;
+
+type Migration = (sql: SqlClient.SqlClient) => Effect.Effect<unknown, SqlError.SqlError>;
+
+type Migrations = Readonly<Record<number, Migration>>;
+
+interface StateMigration<Current> {
+  readonly upgrade: (stored: string) => Effect.Effect<Current, Schema.SchemaError>;
+}
+
+interface Implementation<Definition extends ActorDefinition> {
+  readonly commands: { readonly [Name in keyof Definition["commands"]]: CommandHandler<Definition, Name> };
+  readonly create?: CreateHandler<Definition>;
+  readonly files?: Definition["fileAccess"] extends Option.None<unknown> ? never : FileRules<Definition>;
+  readonly migrations?: Migrations;
+  readonly queries?: { readonly [Name in keyof Definition["queries"]]: QueryHandler<Definition, Name> };
+  readonly results?: { readonly [Name in keyof Definition["jobs"]]: ResultHandler<Definition, Name> };
+  readonly state?: StateMigration<StateOf<Definition>>;
+}
+
+type ImplementationCheck<Definition extends ActorDefinition> = (Definition["queries"] extends NoQueries
+  ? unknown
+  : { readonly queries: unknown }) &
+  (Definition["create"] extends Schema.Never ? unknown : { readonly create: unknown }) &
+  (Definition["fileAccess"] extends Option.None<unknown> ? unknown : { readonly files: unknown }) &
+  (Definition["jobs"] extends NoJobs ? unknown : { readonly results: unknown });
+
+declare const actorHandlersBrand: unique symbol;
+
+interface ActorHandlers<Name extends string> {
+  readonly [actorHandlersBrand]: Name;
+}
+
+type AddressedCommands<Name extends string, Definition extends ActorDefinition> = {
+  readonly [Member in keyof Definition["commands"]]: Definition["commands"][Member] & {
+    readonly address: CommandAddress<Name, Definition["key"], Member & string>;
+  };
+};
+
+interface Actor<Name extends string, Definition extends ActorDefinition> {
+  readonly callers: Definition["callers"];
+  readonly client: ClientOf<Definition>;
+  /** The actor's computers, for a job activity or the host. */
+  readonly computer: ComputerClientOf<Definition>;
+  /** Which caller kinds may make file calls, as `Akter.fileAccess` declared them. */
+  readonly fileAccess: Definition["fileAccess"];
+  readonly files: FileClientOf<Definition>;
+  readonly commands: AddressedCommands<Name, Definition>;
+  readonly create: Definition["create"];
+  readonly handlers: Context.Key<ActorHandlers<Name>, HostedActor>;
+  readonly initial: Option.Option<() => StateOf<Definition>>;
+  readonly jobs: ActorJobs<Name, Definition["jobs"]>;
+  readonly key: Definition["key"];
+  readonly name: Name;
+  readonly principal: Effect.Effect<PrincipalOf<Definition>, never, Akter>;
+  readonly queries: Definition["queries"];
+  readonly rpcs: ActorRpcs;
+  /** One of the actor's declared secrets, for a job activity: never from a command, query or result handler. */
+  readonly secret: SecretOf<Definition>;
+  readonly secrets: Definition["secrets"];
+  readonly state: Definition["state"];
+  readonly toLayer: (
+    implementation: Implementation<Definition> & ImplementationCheck<Definition>,
+  ) => Layer.Layer<ActorHandlers<Name>>;
+  readonly update: (patch: Partial<StateOf<Definition>>) => Effect.Effect<void, never, ActorState>;
+}
+
+type ImplementationOf<Target> =
+  Target extends Actor<infer _Name extends string, infer Definition>
+    ? Implementation<Definition> & ImplementationCheck<Definition>
+    : never;
+
+interface CommandScope {
+  readonly files: FileStorage;
+  readonly id: Effect.Effect<string>;
+  readonly key: string;
+  readonly now: Effect.Effect<number>;
+  readonly principal: Principal;
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface CommandEnvironment {
+  readonly files: FileStorage;
+  readonly id: Effect.Effect<string>;
+  readonly key: string;
+  readonly now: Effect.Effect<number>;
+  readonly sql: SqlClient.SqlClient;
+}
+
+interface HostedRequest {
+  readonly member: string;
+  readonly payload: string;
+  readonly principal: string;
+  readonly state: Option.Option<string>;
+}
+
+/** A job's result, delivered as a command to the actor that started the job. */
+interface HostedResult extends HostedRequest {
+  /** The id `Akter.start` returned for the job. */
+  readonly jobId: string;
+}
+
+interface HostedActor {
+  readonly callers: CallersSchemas;
+  /**
+   * Which caller kinds may make file calls; none means the actor has no file calls. A bundle built before contracts
+   * declared file calls registers no such field, and a host reads that as none, so its file calls are refused.
+   */
+  readonly fileAccess?: Option.Option<FileAccess> | undefined;
+  /** The host interface version the actor was built with (`host-interface.pure.ts`); absent, it is 0. */
+  readonly hostInterface?: number | undefined;
+  readonly initial: Option.Option<() => StateFields>;
+  /**
+   * The actor's key schema. A host decodes a file or computer request's key by its encoded side only, since the bundle's
+   * own copy of effect built it (`hosted-file-rpcs.layer.ts`).
+   */
+  readonly key: KeySchema;
+  readonly migrations: Migrations;
+  readonly name: string;
+  /** The secrets the actor declares; a host opens only these. Absent in builds from before secrets, meaning none. */
+  readonly secrets?: readonly string[] | undefined;
+  readonly state: StateSchema;
+  readonly runCreate: (
+    request: HostedRequest,
+    environment: CommandEnvironment,
+  ) => Effect.Effect<HostedOutcome, HostedError>;
+  readonly runCommand: (
+    request: HostedRequest,
+    environment: CommandEnvironment,
+  ) => Effect.Effect<HostedOutcome, HostedError>;
+  readonly readState: (
+    principal: string,
+  ) => Effect.Effect<(stored: Option.Option<string>) => Effect.Effect<string, HostedError>, HostedError>;
+  readonly runQuery: (request: HostedRequest, environment: CommandEnvironment) => Effect.Effect<string, HostedError>;
+  readonly runResult: (
+    request: HostedResult,
+    environment: CommandEnvironment,
+  ) => Effect.Effect<HostedOutcome, HostedError>;
+  readonly upgradeState: (stored: string) => Effect.Effect<Option.Option<string>, StateUnreadableError>;
+}
+
+export type {
+  Actor,
+  ActorDefinition,
+  AddressedCommand,
+  AddressedCommands,
+  CommandAddress,
+  ActorHandlers,
+  ActorOptions,
+  CallersSchemas,
+  CommandEnvironment,
+  CommandHandler,
+  CommandScope,
+  CreateHandler,
+  Decoded,
+  DefinitionOf,
+  FileAuthorizer,
+  FileRules,
+  FinishedJob,
+  HostedActor,
+  HostedRequest,
+  HostedResult,
+  Implementation,
+  ImplementationOf,
+  KeySchema,
+  Migration,
+  Migrations,
+  OptionsCheck,
+  PrincipalOf,
+  PrincipalSchema,
+  QueryHandler,
+  ReservedMember,
+  ResultHandler,
+  StateFields,
+  StateMigration,
+  StateOf,
+  StateSchema,
+};
+
+export type { HostedError, HostedOutcome } from "#src/contract/hosted/hosted-error.contract";