@akterjs/effect 0.0.0-stage → 0.1.0

package/src/contract/history/history-entry.pure.ts

@@ -0,0 +1,282 @@
+import { Effect, Exit, HashMap, Option, Record as Rec, Schema, String as Str } from "effect";
+
+import type { JournalEntry } from "./actor-journal.service.js";
+import { ActorAlreadyExistsError } from "#src/contract/actor/actor-already-exists.errors";
+import type { ActorDefinition, Decoded, PrincipalOf } from "#src/contract/actor/actor.contract";
+import { Caller } from "#src/contract/caller/caller.schema";
+import { jobResult } from "#src/contract/command/command.contract";
+import type { NoJobs } from "#src/contract/command/command.contract";
+import { HandlerFailedError } from "#src/contract/hosted/handler-failed.errors";
+import { exitCodec, jsonCodec } from "#src/contract/json-codec.pure";
+
+interface RecordedCommand<Definition extends ActorDefinition, Name extends keyof Definition["commands"]> {
+  readonly at: number;
+  readonly command: Name;
+  readonly commandId: string;
+  readonly exit: Exit.Exit<
+    Definition["commands"][Name]["success"]["Type"],
+    Definition["commands"][Name]["error"]["Type"] | HandlerFailedError
+  >;
+  readonly kind: "recorded";
+  readonly payload: Definition["commands"][Name]["payload"]["Type"];
+  readonly principal: PrincipalOf<Definition>;
+  readonly seq: number;
+}
+
+type CreationMode = "create" | "ensure";
+
+interface CreatedEntry<Definition extends ActorDefinition> {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly exit: Exit.Exit<void, ActorAlreadyExistsError | HandlerFailedError>;
+  readonly kind: "created";
+  readonly mode: CreationMode;
+  readonly payload: Definition["create"]["Type"];
+  readonly principal: PrincipalOf<Definition>;
+  readonly seq: number;
+}
+
+interface JobResultEntry<Definition extends ActorDefinition, Name extends keyof Definition["jobs"]> {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly exit: Exit.Exit<void, HandlerFailedError>;
+  readonly job: Name;
+  readonly kind: "result";
+  readonly result: Exit.Exit<Definition["jobs"][Name]["success"]["Type"], Definition["jobs"][Name]["error"]["Type"]>;
+  readonly seq: number;
+}
+
+interface UnreadableCommand {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly kind: "unreadable";
+  readonly reason: string;
+  readonly seq: number;
+}
+
+type HistoryEntry<Definition extends ActorDefinition> =
+  | { readonly [Name in keyof Definition["commands"]]: RecordedCommand<Definition, Name> }[keyof Definition["commands"]]
+  | (Definition["create"] extends Schema.Never ? never : CreatedEntry<Definition>)
+  | (Definition["jobs"] extends NoJobs
+      ? never
+      : { readonly [Name in keyof Definition["jobs"]]: JobResultEntry<Definition, Name> }[keyof Definition["jobs"]])
+  | UnreadableCommand;
+
+interface EntryPlace {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly seq: number;
+}
+
+interface ErasedRecorded extends EntryPlace {
+  readonly exit: Exit.Exit<Decoded, Decoded>;
+  readonly kind: "recorded";
+  readonly payload: Decoded;
+  readonly principal: Decoded;
+}
+
+interface ErasedCreated extends EntryPlace {
+  readonly exit: Exit.Exit<Decoded, Decoded>;
+  readonly kind: "created";
+  readonly mode: CreationMode;
+  readonly payload: Decoded;
+  readonly principal: Decoded;
+}
+
+interface ErasedResult extends EntryPlace {
+  readonly exit: Exit.Exit<Decoded, Decoded>;
+  readonly job: string;
+  readonly kind: "result";
+  readonly result: Exit.Exit<Decoded, Decoded>;
+}
+
+type ErasedEntry = ErasedCreated | ErasedRecorded | ErasedResult | UnreadableCommand;
+
+interface NamedDefinition {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+}
+
+type ExitDecoder = (text: string) => Effect.Effect<Exit.Exit<Decoded, Decoded>, Schema.SchemaError>;
+
+type TextDecoder = (text: string) => Effect.Effect<Decoded, Schema.SchemaError>;
+
+type FailureDecoder = (text: string) => Option.Option<Decoded>;
+
+const creationModes = HashMap.make(["akter.create", "create" as const], ["akter.ensure", "ensure" as const]);
+
+const resultPrefix = "akter.result.";
+
+const handlerFailure: FailureDecoder = Schema.decodeOption(Schema.fromJsonString(HandlerFailedError));
+
+const creationFailure: FailureDecoder = Schema.decodeOption(
+  Schema.fromJsonString(Schema.Union([ActorAlreadyExistsError, HandlerFailedError])),
+);
+
+const VoidExit = Schema.Exit(Schema.Void, Schema.Never, Schema.Defect());
+
+const voidExit: ExitDecoder = Schema.decodeEffect(jsonCodec(VoidExit));
+
+const callerOf = Schema.decodeEffect(jsonCodec(Caller));
+
+const placeOf = (entry: JournalEntry): EntryPlace => ({
+  at: entry.at,
+  command: entry.command,
+  commandId: entry.commandId,
+  seq: entry.seq,
+});
+
+const unreadable = (entry: JournalEntry, reason: string): UnreadableCommand => ({
+  ...placeOf(entry),
+  kind: "unreadable",
+  reason,
+});
+
+interface CommandDecoders {
+  readonly exit: ExitDecoder;
+  readonly payload: TextDecoder;
+}
+
+interface Decoders {
+  readonly commands: Readonly<Record<string, CommandDecoders>>;
+  readonly create: TextDecoder;
+  readonly jobs: Readonly<Record<string, ExitDecoder>>;
+  readonly name: string;
+  readonly principals: Readonly<
+    Record<string, (principal: Caller["principal"]) => Effect.Effect<Decoded, Schema.SchemaError>>
+  >;
+}
+
+const decodersOf = ({ definition, name }: NamedDefinition): Decoders => ({
+  commands: Rec.map(definition.commands, (declaration) => ({
+    exit: Schema.decodeEffect(exitCodec(declaration)),
+    payload: Schema.decodeEffect(jsonCodec(declaration.payload)),
+  })),
+  create: Schema.decodeEffect(jsonCodec(definition.create)),
+  jobs: Rec.map(definition.jobs, (job) => Schema.decodeEffect(jsonCodec(jobResult(job)))),
+  name,
+  principals: Rec.map(definition.callers, (schema) => Schema.decodeUnknownEffect(Schema.toCodecJson(schema))),
+});
+
+const exitOf = (
+  failure: FailureDecoder,
+  decode: ExitDecoder,
+  text: string,
+): Effect.Effect<Exit.Exit<Decoded, Decoded>, Schema.SchemaError> =>
+  Option.match(failure(text), {
+    onNone: () => decode(text),
+    onSome: (failed): Effect.Effect<Exit.Exit<Decoded, Decoded>> => Effect.succeed(Exit.fail(failed)),
+  });
+
+const principalOf = Effect.fnUntraced(function* principalOf({ principals }: Decoders, entry: JournalEntry) {
+  const caller = yield* callerOf(entry.principal);
+  const decode = Rec.get(principals, caller.kind);
+
+  return {
+    kind: caller.kind,
+    principal: yield* Effect.transposeOption(Option.map(decode, (decoding) => decoding(caller.principal))),
+  };
+});
+
+const commandOf = Effect.fnUntraced(function* commandOf(
+  decoders: Decoders,
+  entry: JournalEntry,
+): Effect.fn.Return<ErasedEntry, Schema.SchemaError> {
+  const command = Rec.get(decoders.commands, entry.command);
+
+  if (Option.isNone(command)) {
+    return unreadable(entry, `${entry.command} is not a command of ${decoders.name}`);
+  }
+
+  const { kind, principal } = yield* principalOf(decoders, entry);
+
+  if (Option.isNone(principal)) {
+    return unreadable(entry, `${kind} is not a caller of ${decoders.name}`);
+  }
+
+  return {
+    ...placeOf(entry),
+    exit: yield* exitOf(handlerFailure, command.value.exit, entry.exit),
+    kind: "recorded",
+    payload: yield* command.value.payload(entry.payload),
+    principal: principal.value,
+  };
+});
+
+const createdOf = Effect.fnUntraced(function* createdOf(
+  decoders: Decoders,
+  entry: JournalEntry,
+  mode: CreationMode,
+): Effect.fn.Return<ErasedEntry, Schema.SchemaError> {
+  const { kind, principal } = yield* principalOf(decoders, entry);
+
+  if (Option.isNone(principal)) {
+    return unreadable(entry, `${kind} is not a caller of ${decoders.name}`);
+  }
+
+  return {
+    ...placeOf(entry),
+    exit: yield* exitOf(creationFailure, voidExit, entry.exit),
+    kind: "created",
+    mode,
+    payload: yield* decoders.create(entry.payload),
+    principal: principal.value,
+  };
+});
+
+const resultOf = Effect.fnUntraced(function* resultOf(
+  { jobs, name }: Decoders,
+  entry: JournalEntry,
+  job: string,
+): Effect.fn.Return<ErasedEntry, Schema.SchemaError> {
+  const result = Rec.get(jobs, job);
+
+  if (Option.isNone(result)) {
+    return unreadable(entry, `${job} is not a job of ${name}`);
+  }
+
+  return {
+    ...placeOf(entry),
+    exit: yield* exitOf(handlerFailure, voidExit, entry.exit),
+    job,
+    kind: "result",
+    result: yield* result.value(entry.payload),
+  };
+});
+
+const decodedOf = (decoders: Decoders, entry: JournalEntry): Effect.Effect<ErasedEntry, Schema.SchemaError> => {
+  const mode = HashMap.get(creationModes, entry.command);
+
+  if (Option.isSome(mode)) {
+    return createdOf(decoders, entry, mode.value);
+  }
+
+  if (Str.startsWith(resultPrefix)(entry.command)) {
+    return resultOf(decoders, entry, Str.slice(resultPrefix.length)(entry.command));
+  }
+
+  return commandOf(decoders, entry);
+};
+
+const entryOf =
+  (decoders: Decoders) =>
+  (entry: JournalEntry): Effect.Effect<ErasedEntry> =>
+    Effect.catchTag(decodedOf(decoders, entry), "SchemaError", (failure) =>
+      Effect.succeed(unreadable(entry, failure.message)),
+    );
+
+const decodeEntries = (
+  source: NamedDefinition,
+): ((entries: readonly JournalEntry[]) => Effect.Effect<readonly ErasedEntry[]>) => {
+  const decode = entryOf(decodersOf(source));
+
+  return (entries) => Effect.forEach(entries, decode);
+};
+
+export { decodeEntries };
+
+export type { CreatedEntry, ErasedEntry, HistoryEntry, JobResultEntry, RecordedCommand, UnreadableCommand };

package/src/contract/hosted/handler-failed.errors.ts

@@ -0,0 +1,16 @@
+import { Schema } from "effect";
+
+/**
+ * A handler failed outside its declared error contract. `platform` is true when the failure was Akter's, not the
+ * handler's: a platform error such as `FilesUnavailableError` escaped it. Akter Cloud doesn't bill a call that ends
+ * with one. A handler's own failure, such as a statement its SQL got wrong, carries no `platform`.
+ */
+export class HandlerFailedError extends Schema.TaggedError<HandlerFailedError, { readonly brand: unique symbol }>()(
+  "HandlerFailedError",
+  {
+    actor: Schema.String,
+    member: Schema.String,
+    message: Schema.String,
+    platform: Schema.optionalKey(Schema.Literal(true)),
+  },
+) {}

package/src/contract/hosted/handler-failure.pure.ts

@@ -0,0 +1,161 @@
+import {
+  Array as Arr,
+  Cause,
+  Context,
+  Effect,
+  Exit,
+  Option,
+  Predicate,
+  Record as Rec,
+  Schema,
+  String as Str,
+} from "effect";
+import { dual } from "effect/Function";
+import { SqlError } from "effect/sql";
+
+import { FilesUnavailableError } from "#src/contract/file/files-unavailable.errors";
+import { HandlerFailedError } from "./handler-failed.errors.js";
+
+interface Failing {
+  readonly actor: string;
+  readonly member: string;
+  /** A query runs on a read-only connection, so a write in it fails as the plain SQLITE_READONLY: the handler's own. */
+  readonly query?: true;
+}
+
+const dataFirstArity = 2;
+
+const isHostFailure = Predicate.or(SqlError.isSqlError, Schema.is(FilesUnavailableError));
+
+/**
+ * Whether a failed SQL statement's own message reaches the caller. akter dev shows it. Akter Cloud's hosted runtime sets
+ * `logged`: the message names the app's tables, columns and constraints, so the host logs it under the command's id and
+ * the caller gets a generic message.
+ */
+const StatementDetail = Context.Reference<"logged" | "shown">(
+  "@akterjs/effect/contract/hosted/handler-failure/StatementDetail",
+  { defaultValue: () => "shown" },
+);
+
+/** The message every engine gives a handler that writes an engine-owned `akter_*` table. */
+const engineOwnedRefusal = (table: string): string =>
+  `${table} is engine-owned: a handler may read akter_* tables but never write them`;
+
+/** The engine's own refusal names only its own table, never the app's schema, so it reaches the caller as it is. */
+const isEngineRefusal = (failure: SqlError.SqlError): boolean => Str.includes(engineOwnedRefusal(""))(failure.message);
+
+const loggedStatement = "a SQL statement failed; its message is in the host's log under this command's id";
+
+/**
+ * SQLite's primary result codes that mean the platform failed under the handler, not the handler's SQL: the disk or
+ * the database file failed (IOERR, CORRUPT, NOTADB, CANTOPEN, READONLY, FULL; a store past its disk ceiling is refused
+ * as StorageLimitError before this, so FULL here is the platform's sizing), the database was held elsewhere (BUSY,
+ * LOCKED, PROTOCOL) or the host ran out of memory (NOMEM). Every other code, such as a constraint, a syntax error, a
+ * mismatch or a misuse, is the handler's own failure. node:sqlite gives the extended code as `errcode`, whose low byte
+ * is the primary code; Akter Cloud's native driver and Bun give its name as `code`, such as `SQLITE_IOERR_WRITE`. In a
+ * query, the plain READONLY is the handler's: both engines run a query read-only, and SQLite refuses its write with
+ * that code. An extended READONLY, such as READONLY_CANTLOCK or READONLY_DBMOVED, names the storage and stays the
+ * platform's.
+ */
+const platformCodes = {
+  SQLITE_BUSY: 5,
+  SQLITE_CANTOPEN: 14,
+  SQLITE_CORRUPT: 11,
+  SQLITE_FULL: 13,
+  SQLITE_IOERR: 10,
+  SQLITE_LOCKED: 6,
+  SQLITE_NOMEM: 7,
+  SQLITE_NOTADB: 26,
+  SQLITE_PROTOCOL: 15,
+  SQLITE_READONLY: 8,
+} as const;
+
+/** An extended result code's primary code is its low byte. */
+const primaryCodes = 256;
+
+const NumberedCause = Schema.Struct({ errcode: Schema.Int });
+
+const NamedCause = Schema.Struct({ code: Schema.String });
+
+const platformNumbered = (cause: unknown): boolean =>
+  Option.exists(Schema.decodeUnknownOption(NumberedCause)(cause), ({ errcode }) =>
+    Arr.contains(Rec.values(platformCodes), errcode % primaryCodes),
+  );
+
+const platformNamed = (cause: unknown): boolean =>
+  Option.exists(Schema.decodeUnknownOption(NamedCause)(cause), ({ code }) =>
+    Arr.some(Rec.keys(platformCodes), (name) => code === name || Str.startsWith(`${name}_`)(code)),
+  );
+
+/** The plain SQLITE_READONLY, with no extended code: what SQLite answers a write on a read-only connection. */
+const isPlainReadOnly = (cause: unknown): boolean =>
+  Option.exists(
+    Schema.decodeUnknownOption(NumberedCause)(cause),
+    ({ errcode }) => errcode === platformCodes.SQLITE_READONLY,
+  ) || Option.exists(Schema.decodeUnknownOption(NamedCause)(cause), ({ code }) => code === "SQLITE_READONLY");
+
+const isPlatformStatement = (failure: SqlError.SqlError, { query }: Failing): boolean => {
+  const { cause } = failure.reason;
+
+  if (query === true && isPlainReadOnly(cause)) {
+    return false;
+  }
+
+  return platformNumbered(cause) || platformNamed(cause);
+};
+
+type PlatformMark = Pick<HandlerFailedError, "platform">;
+
+/** `platform: true` when the platform failed under the handler: its files were unavailable, or SQLite's storage failed. */
+const platformMark = (failure: Error, failing: Failing): PlatformMark => {
+  if (
+    Schema.is(FilesUnavailableError)(failure) ||
+    (SqlError.isSqlError(failure) && isPlatformStatement(failure, failing))
+  ) {
+    return { platform: true };
+  }
+
+  return {};
+};
+
+const failedWith = Effect.fnUntraced(function* failedWith(failure: Error, failing: Failing) {
+  const { actor, member } = failing;
+  const detail = yield* StatementDetail;
+  const mark = platformMark(failure, failing);
+
+  if (detail === "shown" || !SqlError.isSqlError(failure) || isEngineRefusal(failure)) {
+    return yield* HandlerFailedError.make({ actor, member, message: failure.message, ...mark });
+  }
+
+  yield* Effect.logError(`${actor}.${member}: ${failure.message}`).pipe(Effect.annotateLogs({ member }));
+
+  return yield* HandlerFailedError.make({ actor, member, message: loggedStatement, ...mark });
+});
+
+const rejectFailedStatement: {
+  (
+    failing: Failing,
+  ): <Success, Failure>(
+    exit: Exit.Exit<Success, Failure>,
+  ) => Effect.Effect<Exit.Exit<Success, Failure>, HandlerFailedError>;
+  <Success, Failure>(
+    exit: Exit.Exit<Success, Failure>,
+    failing: Failing,
+  ): Effect.Effect<Exit.Exit<Success, Failure>, HandlerFailedError>;
+} = dual(
+  dataFirstArity,
+  <Success, Failure>(
+    exit: Exit.Exit<Success, Failure>,
+    failing: Failing,
+  ): Effect.Effect<Exit.Exit<Success, Failure>, HandlerFailedError> =>
+    Exit.match(exit, {
+      onFailure: (cause) =>
+        Option.match(Option.filter(Cause.findErrorOption(cause), isHostFailure), {
+          onNone: () => Effect.succeed(exit),
+          onSome: (error) => failedWith(error, failing),
+        }),
+      onSuccess: () => Effect.succeed(exit),
+    }),
+);
+
+export { engineOwnedRefusal, StatementDetail, rejectFailedStatement };

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

@@ -0,0 +1,97 @@
+import { Context, Effect, Layer, Option } from "effect";
+
+import { ActorRegistry } from "#src/contract/actor/actor-registry.service";
+import type { ActorDefinition, HostedActor, Implementation, StateOf } from "#src/contract/actor/actor.contract";
+import { HostedCommand } from "./hosted-command.service.js";
+import { HostedCreate } from "./hosted-create.service.js";
+import { HostedQuery } from "./hosted-query.service.js";
+import type { ErasedImplementation, ErasedParts, ErasedSpec, ProvideScope } from "./hosted-request.pure.js";
+import { hostInterface } from "#src/contract/actor/host-interface.pure";
+import { upgradeState } from "#src/contract/state/state-migration.pure";
+import { stateReader } from "#src/contract/state/state-read.pure";
+
+interface HostedSpec<Definition extends ActorDefinition> {
+  readonly definition: Definition;
+  readonly initial: Option.Option<() => StateOf<Definition>>;
+  readonly name: string;
+  readonly provide: ProvideScope;
+}
+
+interface Runners {
+  readonly runCommand: HostedCommand["Service"]["run"];
+  readonly runCreate: HostedCreate["Service"]["run"];
+  readonly runQuery: HostedQuery["Service"]["run"];
+  readonly runResult: HostedCommand["Service"]["runResult"];
+}
+
+function hostedActor<Definition extends ActorDefinition>(
+  runners: Runners,
+  spec: HostedSpec<Definition>,
+): (implementation: Implementation<Definition>) => HostedActor;
+function hostedActor(runners: Runners, spec: ErasedSpec): (implementation: ErasedImplementation) => HostedActor {
+  return (implementation) => {
+    const parts: ErasedParts = { ...spec, implementation };
+
+    return {
+      callers: spec.definition.callers,
+      fileAccess: spec.definition.fileAccess,
+      hostInterface,
+      initial: spec.initial,
+      key: spec.definition.key,
+      migrations: implementation.migrations ?? {},
+      name: spec.name,
+      readState: stateReader({
+        callers: spec.definition.callers,
+        initial: spec.initial,
+        name: spec.name,
+        state: spec.definition.state,
+      }),
+      runCommand: (request, environment) => runners.runCommand(parts, request, environment),
+      runCreate: (request, environment) => runners.runCreate(parts, request, environment),
+      runQuery: (request, environment) => runners.runQuery(parts, request, environment),
+      runResult: (request, environment) => runners.runResult(parts, request, environment),
+      secrets: spec.definition.secrets,
+      state: spec.definition.state,
+      upgradeState: (stored) => upgradeState(parts, stored),
+    };
+  };
+}
+
+export class HostedActors extends Context.Service<
+  HostedActors,
+  {
+    readonly register: <Definition extends ActorDefinition>(
+      spec: HostedSpec<Definition>,
+      implementation: Implementation<Definition>,
+    ) => Effect.Effect<HostedActor>;
+  }
+>()("@akterjs/effect/contract/hosted/hosted-actor.service/HostedActors", {
+  make: Effect.gen(function* makeHostedActors() {
+    const commands = yield* HostedCommand;
+
+    const runners: Runners = {
+      runCommand: commands.run,
+      runCreate: (yield* HostedCreate).run,
+      runQuery: (yield* HostedQuery).run,
+      runResult: commands.runResult,
+    };
+
+    const register = Effect.fnUntraced(function* register<Definition extends ActorDefinition>(
+      spec: HostedSpec<Definition>,
+      implementation: Implementation<Definition>,
+    ) {
+      const hosted = hostedActor(runners, spec)(implementation);
+      const registry = yield* Effect.serviceOption(ActorRegistry);
+
+      yield* Option.match(registry, { onNone: () => Effect.void, onSome: (found) => found.register(hosted) });
+
+      return hosted;
+    });
+
+    return { register } as const;
+  }),
+}) {
+  public static readonly layer = Layer.effect(this, this.make).pipe(
+    Layer.provide([HostedCommand.layer, HostedCreate.layer, HostedQuery.layer]),
+  );
+}

package/src/contract/hosted/hosted-command.service.ts

@@ -0,0 +1,114 @@
+import { Context, Effect, Exit, Layer, Option, Ref, Schema } from "effect";
+
+import type {
+  CommandEnvironment,
+  HostedError,
+  HostedOutcome,
+  HostedRequest,
+  HostedResult,
+} from "#src/contract/actor/actor.contract";
+import {
+  commandActorState,
+  noJobs,
+  noMessages,
+  noSignals,
+  noTimers,
+  scopeOf,
+} from "#src/contract/state/actor-state.pure";
+import { rejectFailedStatement } from "./handler-failure.pure.js";
+import { prepare, prepareResult } from "./hosted-request.pure.js";
+import type { ErasedParts, Prepared } from "./hosted-request.pure.js";
+import { exitCodec, jsonCodec } from "#src/contract/json-codec.pure";
+
+interface Handling {
+  readonly environment: CommandEnvironment;
+  readonly member: string;
+  readonly parts: ErasedParts;
+  readonly prepared: Prepared;
+}
+
+const nothingChanged: Omit<HostedOutcome, "exit"> = {
+  jobs: noJobs,
+  messages: noMessages,
+  signals: noSignals,
+  state: Option.none(),
+  timers: noTimers,
+};
+
+const handle = Effect.fnUntraced(function* handle({
+  environment,
+  member,
+  parts,
+  prepared,
+}: Handling): Effect.fn.Return<HostedOutcome, HostedError> {
+  const { changes, service } = yield* commandActorState({
+    actor: parts.name,
+    commands: parts.definition.commands,
+    environment,
+    jobs: parts.definition.jobs,
+    state: prepared.state,
+  });
+
+  const execution = Effect.gen(function* execution() {
+    const value = yield* prepared.handler(prepared.state, prepared.payload);
+    const { cancelled, jobs, messages, scheduled, signals, state } = yield* Ref.get(changes);
+    const text = yield* Effect.orDie(Schema.encodeEffect(jsonCodec(parts.definition.state))(state));
+
+    return { jobs, messages, signals, text, timers: { cancelled, scheduled }, value };
+  });
+
+  const finished = yield* Effect.exit(
+    parts.provide(execution, scopeOf({ environment, principal: prepared.principal }), service),
+  );
+
+  const exit = yield* rejectFailedStatement(finished, { actor: parts.name, member });
+
+  const reply = yield* Effect.orDie(
+    Schema.encodeEffect(exitCodec(prepared.declaration))(Exit.map(exit, (result) => result.value)),
+  );
+
+  return Exit.match(exit, {
+    onFailure: () => ({ ...nothingChanged, exit: reply }),
+    onSuccess: (result) => ({
+      exit: reply,
+      jobs: result.jobs,
+      messages: result.messages,
+      signals: result.signals,
+      state: Option.some(result.text),
+      timers: result.timers,
+    }),
+  });
+});
+
+const runCommand = Effect.fn("HostedActor.runCommand")(function* runCommand(
+  parts: ErasedParts,
+  request: HostedRequest,
+  environment: CommandEnvironment,
+): Effect.fn.Return<HostedOutcome, HostedError> {
+  const prepared = yield* prepare(
+    parts,
+    { declarations: parts.definition.commands, handlers: parts.implementation.commands },
+    request,
+  );
+
+  return yield* handle({ environment, member: request.member, parts, prepared });
+});
+
+const runResult = Effect.fn("HostedActor.runResult")(function* runResult(
+  parts: ErasedParts,
+  request: HostedResult,
+  environment: CommandEnvironment,
+): Effect.fn.Return<HostedOutcome, HostedError> {
+  const prepared = yield* prepareResult(parts, request);
+
+  return yield* handle({ environment, member: request.member, parts, prepared });
+});
+
+export class HostedCommand extends Context.Service<
+  HostedCommand,
+  { readonly run: typeof runCommand; readonly runResult: typeof runResult }
+>()("@akterjs/effect/contract/hosted/hosted-command.service/HostedCommand", {
+  make: Effect.succeed({ run: runCommand, runResult }),
+}) {
+  public static readonly layer = Layer.effect(this, this.make);
+}