@akterjs/effect 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @akterjs/effect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Effect SDK. One package with five entry points, by who loads them:
+
+The Effect SDK for Akter: durable actors with their state in their own SQLite database, their files, jobs and computers.
+
+```sh
+npm install @akterjs/effect @akterjs/client effect
+npm install -D akter
+```
+
+Docs: https://docs.akter.dev. Pricing: https://docs.akter.dev/pricing.
+
+- the root, `@akterjs/effect`: the runtime `Akter`, which is the contract `Akter` plus `Akter.serve`, `Akter.local`, `Akter.environments` and `Akter.migrate`, and `Verify.replay`.
+
+- `contract`: `Akter.make`, commands, queries and errors. Imports only `effect`, so hosts, Workers, browsers and clients can all load it (ADR 0006).
+- `host`: the runtime that runs actor handlers, one SQLite transaction per command.
+- `local`: the local engine behind `akter dev`, on a folder with the production layout.
+- `testing`: `Story`, actor tests on a temporary folder with real SQLite.
+
+Status: Phase 1 in progress. `contract` exports `Akter`: `Akter.make`, `Akter.command`, `Akter.query`, `Room.update`, `Akter.schedule(delay, Room.commands.close, payload)` and `Akter.cancel(timerId)`, where a timer id is a branded `TimerId`, and `Akter.send(Workspace.commands.addMember, workspaceId, payload)` (these need `ActorState`, provided to commands only, so a query that calls them fails to typecheck), and the handler context (`yield* Akter`, `Akter.actorKey`, `Akter.id`, `Akter.now`, `Akter.principal`, `Akter.sql`). `Akter.Principal` is `{ id: PrincipalId }`, where `Akter.PrincipalId` is a branded string that stays a plain string on the wire; a contract's `callers` schema types its `id` as `Akter.PrincipalId`. A contract's `callers` names each kind of principal it accepts and that kind's schema, and defaults to `{ user: Principal }`; a command or query may narrow it with `callers: ["user"]`. A caller of a kind the member does not allow fails with `CallerNotAllowedError` before the handler runs, and nothing is journaled. The gate logs each refusal as a warning, `caller refused`, annotated with the actor, member, caller kind, principal id and the refusal (`CallerNotAllowedError` or `InvalidRequestError`), and never the payload; a refusal stays out of the journal so a retried command id is never answered with a stale refusal and a probing caller costs the actor no durable write. Each actor's `principal` (`Room.principal`) is typed as the kinds its contract declares, while `Akter.principal` is `{ id }`. The `Authentication` RPC middleware (`contract/authentication.api`) provides the `CurrentCaller`; the development authentication in `serve` reads it from the `akter-principal` header and falls back to the development principal, and refuses a header that claims the `actor` caller, which only the engine's deliveries use. A command or query may not be named `callers`, `client`, `commands`, `computer`, `create`, `ensure`, `files`, `fork`, `handlers`, `history`, `historyStream`, `initial`, `jobs`, `key`, `name`, `principal`, `queries`, `rpcs`, `state`, `then`, `toLayer`, `update` or `warm`: those names belong to the actor object and the clients (`then` so a Promise client handle is never thenable), and `Akter.make` rejects them at the type level and throws `ReservedMemberError` for an untyped caller. Each actor's `toLayer` registers its handlers in `ActorRegistry` (`contract/actor-registry`), `rpcs` is its `RpcGroup`, and `client(key)` is a typed client for one actor (see `@akterjs/client`). `contract/room` and `host/room` are the reference room. In `host`, `ActorDatabase.open` opens an actor's `actor.db`: it creates Akter's reserved `akter_` tables (state, command journal, timers, outbox, failed deliveries, workflow, migrations, layout version), applies the actor's numbered migrations in one transaction after checking the stored hashes of applied ones (a migration that fails rolls them all back with `MigrationFailedError`, whose message names the migration and SQLite's reason and code, also kept as `sqliteMessage` and `sqliteCode`), and upgrades state written under an older schema through `Akter.migrateState`. `SqliteDriver.layerNode` runs it on `node:sqlite`, which both Bun and Node provide, and every `SqlError` it raises keeps SQLite's message and code in its message (`Failed to execute statement: file is not a database (SQLite error 26)`), so `ActorUnavailableError` and `HandlerFailedError` carry them too; only `.adapter` files may import a SQLite driver. `pnpm test` runs the suites on Node and `pnpm test:bun` runs them on Bun, and every result is labelled `|node|` or `|bun|`. `pnpm test:browser` and `pnpm test:workerd` run the contract tests in headless Chromium and in workerd. `CommandRunner.run` runs one command in one transaction: a command id already in the journal returns its recorded exit without running anything; otherwise the handler runs in a savepoint that rolls back on a typed error or a defect, the new state is saved on success, and a journal row records the command, payload, principal, exit, the values of `Akter.id` and `Akter.now`, and the time. `Room.history(key, { since })` returns `{ coveredSince, entries }`: the journal read back as entries typed by the contract: `kind: "recorded"` with the decoded payload, principal and `Exit`; `kind: "created"` for `akter.create` and `akter.ensure`, with the `mode`, the payload decoded by the contract's `create` schema, the principal and an `Exit` that can fail with `ActorAlreadyExistsError` or `HandlerFailedError`; and `kind: "result"` for a job's result, with the `job`, its `result` typed by the job's `success` and `error` schemas, and the result handler's `exit`. It marks an entry that an older contract wrote as `kind: "unreadable"` with the reason, instead of failing the read. It needs `ActorJournal`, which `Akter.local` provides: it reads through a second, query-only connection, so a read never waits for a running command, and with `Akter.historyRetention("7 days")` provided a background job deletes older entries every hour and an actor's first call after it opens deletes them first (by default nothing is deleted). `coveredSince` is the time from which the entries are complete: the requested `since`, or later if a prune deleted entries after it. A prune that deletes entries records its cutoff in `akter_meta`, so an actor whose history was never pruned reports `since` even with a retention. `Room.historyStream(key, { since })` reads the same journal 500 commands at a time and emits each page as `{ coveredSince, entries }`, and `Room.historyCoveredSince(key, { since })` returns only that time, without reading entries. With a retention, a command id must be a UUIDv7, which clients mint, so the host can tell its age: a retry whose row was pruned fails with `CommandIdExpiredError` instead of running again, and an id that is not a UUIDv7 or was minted more than 5 minutes ahead of the host's clock fails with `InvalidRequestError`. Outbox message ids are age-checked the same way. Timer commands (`timer:<id>`) and job-result commands (`result:<job id>`) are not, because the actor's own engine claims each one in the transaction that journals it, so it can't arrive twice. A failed SQL statement in a handler rolls the command back and fails it with `HandlerFailedError`, which is journaled and replayed for the same command id. The reply is returned only after `COMMIT`. `CommandRunner.create` runs an actor's `create` handler (`mode: "create"`) or attaches to an existing actor (`mode: "ensure"`) in the same kind of transaction, journaled as `akter.create` or `akter.ensure`; `create` on an existing actor fails with `ActorAlreadyExistsError`, and a command to an actor with `create` that does not exist yet fails with `ActorNotCreatedError`. `QueryRunner.run` runs a query on a second, read-only connection (`query_only`) inside one deferred read transaction, so it sees the last committed state and tables, never waits for a running command, adds no journal rows, and fails with `HandlerFailedError` if it tries to write. A command's `Akter.schedule` and `Akter.cancel` write and delete `akter_timers` rows in the command's transaction, and only if the command succeeds; a timer runs as the principal that scheduled it. `TimerRunner.fireDue` runs each due timer as a journaled command with the id `timer:<id>`, deleting its row in the same transaction, so a timer fires at most once, a timer a neighboring command cancelled never fires, and a crash before the commit leaves it pending. `TimerRunner.nextDue` returns the earliest pending due time, for the engine's next wake. Each entry of an actor's `commands` carries its `address` (`actor`, the `key` schema and `member`), so `Akter.send` encodes the target key and payload and writes an `akter_outbox` row in the command's transaction, only if the command succeeds, with the command id `outbox:<id>`, where the id is a UUIDv7 minted like `Akter.id`, so it is recorded with the command and its age is the time the message was sent. Only the engine's `actor` caller may send an `outbox:` id, so a client that learns a message's id can't take it first and make the delivery fail. `OutboxRunner.deliver` sends each pending row as a command with that id, so the target's journal runs it once however often it arrives, and deletes the row only after the send succeeds. With a retention on the target, a message whose age passes it is refused with `CommandIdExpiredError` and kept as a failed delivery, so a redelivery after the target pruned its journal row never runs twice. A delivered command runs as the sending actor, the `actor` caller `{ actor, id, key }` (`Akter.ActorPrincipal`, whose `id` is `<actor>/<key>`). A target declares that caller in `callers` and lists `"actor"` on each member that accepts messages; a member that does not list it refuses the message with `CallerNotAllowedError`, even when it names no callers.
+
+An actor declares jobs with `jobs: { charge: Akter.job({ payload: { amount: Schema.Int }, success: ChargeId, error: CardDeclinedError }) }`. `Order.jobs.charge` is an Effect `Workflow` named `Order/charge`, and its handler is a layer written the Effect way, `Order.jobs.charge.toLayer(({ amount }) => ...)`, in a `.job.ts` file, where the `workflow-determinism` rule checks that the body does I/O, time and randomness only inside an `Activity`. A command starts a job with `Akter.start(Order.jobs.charge, { amount })`, which needs `ActorState` like `Akter.send` and returns the job's id, `<actor>/<encoded key>/<recorded id>`. The job is written in the command's transaction, so a command that rolls back never starts its job, and a command that names another actor's job dies. After the commit the actor's upkeep starts the job. A `WorkflowEngine` journals each job in the actor's `akter_workflow` table, under the actor's command lock: the job and its payload, each activity attempt's result, each `DurableDeferred` result, each `DurableClock` wake time and the final result. When an actor opens, its upkeep resumes every job with no final result, so finished activities return their journaled results instead of running again, and a clock wakes at the time it journaled. `Akter.local` also provides that `WorkflowEngine`, which job handler layers, `Order.jobs.charge.poll(id)` and `DurableDeferred.succeed` need. When a job ends, its result comes back to the actor as a command: `toLayer` takes `results: { charge: (order, result, job) => ... }`, one handler per job, where `result` is an `Exit` typed by the job's `success` and `error` schemas and `job.id` is the id `Akter.start` returned. A result handler can do whatever a command handler can. `JobResults.deliver` runs it with the command id `result:<job id>`, journaled as `akter.result.charge`, as the actor itself (`Akter.ActorPrincipal`, with no caller gate and no command id age check), and stores the job's final result in the same transaction. So a result lands once, and a crash before that commit leaves the job open: the reopened actor replays it from its journaled activities and delivers the result then. `Room.history` shows a result command as `kind: "result"`. A job can't start another job.
+
+`Akter.serve({ actors: [Room] })` serves every listed actor as one RPC group at `/rpc` over HTTP with NDJSON, through `RpcServer` on `HttpRouter`. The HTTP server is a platform layer picked at startup: `BunHttpServer` on Bun and `NodeHttpServer` on Node (`runtime/http-server.layer`). It needs an engine, an `ActorHost`, rather than the handlers: `Akter.serve({ actors: [Room] }).pipe(Layer.provide(Akter.local(".akter").pipe(Layer.provide(RoomLive))))`. `Akter.local(directory)` is the local engine on a folder, the open counterpart of the private production engine in akter-cloud. It hosts the actors whose handler layers (`Room.toLayer`) are provided to it, and needs no server, network, Archil or Cloudflare. When serve and `Akter.local` run in one process, building the server fails with `ActorsNotHostedError`, naming each listed actor the engine has no handlers for. An engine in another process can't be checked that way, so a call to an actor it doesn't host fails with `InvalidRequestError`. Calls go to `ActorHost` (`serve/actor-host`), which opens an actor's database on its first call under `ActorLocation` in the production layout (`<directory>/shards/<NNN>/<Type>/<key>/` holding `actor.db` and `files/`, `.akter` by default). The shard is Effect Cluster's `Math.abs(hashString(key) % 300) + 1`, written with three digits, and the key is URI-encoded, with an all-dot key's dots written as `%2E` and the empty key as `%`, keeps it open, runs one command at a time per actor and runs queries through `QueryRunner`, so a query never waits for a command and a write in a query fails with `HandlerFailedError`. A query's `/subscribe` RPC and the actor's `state/subscribe` RPC stream the current result and then one `{ value, version }` per commit that changed it, where `version` is the newest journal `seq`. After each commit, the host reads which tables the commit touched (temporary triggers on its own connection; `akter_state` counts only when the value changed) and reruns only the subscribed queries that read one of them, found by `EXPLAIN`ing the statements the query ran. Updates go out after `COMMIT`, a rolled-back command sends none, and closing the stream stops the reruns. An actor declared with `create` also gets `<Actor>/create` and `<Actor>/ensure` RPCs, which take a command id and route to `CommandRunner.create` in that mode, so a retry with the same id replays the journaled result, `ActorAlreadyExistsError` included. Every actor also gets a `<Actor>/warm` RPC, which takes only the key and opens the actor's database through `ActorHost.warm` without running a command, so it journals nothing and leaves the version as it was. A key that was never created opens nothing, so a warm never creates an actor. Reads of such a key open nothing either: a query, `history`, `coveredSince` or the first answer of a `state` or query subscription reads one in-memory, query-only copy of the actor type's migrated schema, so an actor declared with `initial` answers its initial state at version 0 and one declared with `create` answers `ActorNotCreatedError`. Those reads, `files` included, run one at a time, and a query that writes to the copy (by turning `query_only` off, say) fails with `ActorUnavailableError` and the copy is rebuilt. A subscription then attaches to the actor when a command first opens it and sends what that command committed (`tests/serve/engine/actor-host.service.test.ts`). After each command, and for every actor it finds under `shards/` when it starts, the engine delivers the actor's outbox and fires its due timers. A message the target refuses (`CallerNotAllowedError`, `ActorNotCreatedError`, `InvalidRequestError`) leaves the outbox and is recorded in the sender's `akter_failed_deliveries` with a warning, and a target that can't be reached is retried up to 10 times with backoff capped at 30 seconds, after which the message stays in the outbox, an error is logged, and it goes out with the sender's next command or the sweep at the next start. A refusal (`CallerNotAllowedError`, `ActorNotCreatedError`, `InvalidRequestError`), a failed handler statement (`HandlerFailedError`), a database the host can't open or write (`ActorUnavailableError`) and the member's declared error reach the client as their own classes. Until verified principals arrive (Phase 2), the server uses the development authentication, where any caller picks its principal, so it listens on `127.0.0.1` unless given a `hostname`, and building it on a listener that isn't loopback fails with `ListenerNotLoopbackError`, whose message names the address it got, unless `unsafeExposeDevelopmentAuth` is set. Loopback is 127.0.0.0/8, `::1` (a bracketed `[::1]` hostname works too) and the IPv4-mapped `::ffff:127.0.0.1`. It also answers 421 to a request whose `Host` isn't `localhost`, a 127.0.0.0/8 address or `[::1]`, before routing or reading `akter-principal`, so a page that rebinds its own name to the listener's address gets nothing, and 403 to a request whose `Origin` isn't a loopback page. `allowedHosts: ["app.test"]` adds names the Host check accepts, and `allowedHosts: true` accepts any. `unsafeExposeDevelopmentAuth` turns the Origin check off but keeps the Host check, so an exposed listener still needs its names in `allowedHosts`. `Akter.inspector` takes the same `allowedHosts`. A POST whose body isn't `application/ndjson` (or `application/x-ndjson`) gets 415 in every case, so another site can't send one without a CORS preflight the server never answers.
+
+`Akter.migrate({ directory, dryRun })` applies pending migrations to every actor in a local folder now instead of on each actor's next open (`akter migrate --all`). It needs the same handler layers as `Akter.local` and returns a `Stream` of `{ actor, key, from, to }`, one per actor in actor-then-key order, where `from` and `to` are the migration versions before and after. Each actor migrates in its own transaction, as `ActorDatabase.open` would. The first actor that fails ends the stream with `ActorNotMigratedError`, naming its type and key: the actors before it stay migrated, its own transaction rolls back, and the actors after it are not opened. With `dryRun: true` it opens each database with `PRAGMA query_only` and reports the versions it would reach without running a migration or writing to `actor.db` or its WAL. Like any SQLite reader it still updates the read marks in `actor.db-shm`, the WAL's shared-memory index, which holds no data; Bun's `node:sqlite` leaves that file and the WAL in place after a close, where Node removes them. A folder it can't list fails with `StoreUnreadableError`.
+
+A data directory holds environments, each a store of its own, and `LocalEnvironments` (`serve/environment/`) snapshots, branches and promotes them under Akter Cloud's names, shapes and errors (`NotFoundError`, `AlreadyExistsError`, `InUseError`). The record is `<directory>/environments.db`; the first environment, `dev`, is the directory itself, so an existing folder keeps working. `Akter.local(directory)` serves the environment promoted to serve, and `Akter.local({ directory, environment })` pins one, such as a quiet branch to call before promoting it. The engine reads the record every second and applies it: on a promote it closes the old environment's engine, opens the new one and opens its `UpkeepGate`, so held timers fire, held outbox messages go out and jobs resume from the snapshot's journal. While an environment is quiet its upkeep waits at that gate: nothing is dropped. The engine also takes each Pending snapshot of the environment it serves: each actor's database is copied with `VACUUM INTO` under that actor's command lock, under the file home's hold so the blobs and catalog match, into `<directory>/snapshots/<snapshot-n>` beside the store, never as a link to a live file. `branch` copies a Ready snapshot into `<directory>/environments/<name>`, quiet. `promote` switches the serving environment in one transaction and answers a `Promotion` whose `notice` names what the switch leaves out; promoting the one that serves answers the same `Promotion` again. `Akter.environments(directory)` provides `LocalEnvironments` without an engine, as `akter dev snapshots` and `akter dev environments` use it; what it changes, the running engine applies on its next look, and a snapshot it asks for is waited on for up to 30 seconds while that engine takes it. `Akter.inspector` and `Akter.migrate` still read the directory itself, the `dev` environment.
+
+With `AKTER_LOCAL_COMPUTERS=true`, `Akter.local` runs each environment's computers on the machine, under `<store>/computers/<Actor>/<key>/<name>/` (`host/computer/`): a computer is a directory whose `disk` is each step's working directory and `HOME`, so its files last across pause, resume, stop and restarts, and removing it deletes them. A step runs its command in `sh -c` with a fixed `PATH` and no other environment, once by its key (a step sent again reads back the recorded outcome, or `Unknown` when it never recorded one), returns at most 4 MiB of each stream with `truncated`, and is killed with its process group at its timeout. A store holds at most 4 computers, a held computer stays paused (a stopped one stays stopped) until its hold resumes it, and a fork copies the disk. Egress, ingress and secrets are recorded but not enforced, and a computer keeps no process past its step. Job activities reach them through `Actor.computer(key)`, because `Akter.jobs` and `Akter.local` share one `JobComputers`, which the engine binds to the store it serves; on any other engine they fail with `ComputersUnavailableError` until one binds. The `<Actor>/computer/*` RPCs that `akter dev` serves reach the same computers. The variable is off by default, because a local step runs unsandboxed on this machine: then `Akter.jobs` gives the app no computers, so ones another layer provides stay visible, and every computer call answers `ComputersUnavailableError` as before.
+
+`testing` exports `Story`. `Story.run(Handlers, function* (story) { ... })` runs the given handlers on the local engine in a new temporary folder, with real SQLite, and removes the folder afterwards. `story.actor(Room, RoomId.make("lobby"))` returns a client typed from the contract: each command and query is a method that fails with the member's declared error or the host's own failure (`CallerNotAllowedError`, `ActorNotCreatedError`, `HandlerFailedError` and the rest), and a handler's defect dies the call. Calls go in as the user `story` unless `{ as: { kind, principal } }` names another caller the contract declares. `story.create(Agent, key, { input })` creates an actor declared with `create`. A command returns only after the outbox messages it sent, and any they sent in turn, are delivered, and `story.advance(duration)` moves `TestClock` and fires every timer and job clock that falls due, delivering what those timers send. `Story` provides the `WorkflowEngine` too, so a job runs as far as it can before the command that started it returns, and `Order.jobs.charge.poll(id)` reads its result. `Story.run` advances the `TestClock` that `it.effect` provides, and provides its own when none is present.
+
+`Verify.replay(RoomLive, { actor: Room, directory, key })` reruns an actor's command journal against the given handlers and reports the first command whose outcome differs. It opens the actor's `actor.db` query-only and reads the journal 500 commands at a time inside one read transaction, so it never writes to the actor. It replays into a new in-memory database built from the handlers' own migrations, starting from the actor's first command. Each command gets the ids and times it recorded through `Akter.id` and `Akter.now`, plus fresh ones if the new code asks for more, and runs with its recorded principal, through the same `CommandRunner` as a live command. The `ReplayReport` names the window it replayed (how many commands, and the first and last seq and time), and its `difference` is `Option.none()` or the first differing command with the journaled outcome it `expected` and the `actual` one. The actual outcome is either the new journaled exit or a refusal, such as `CallerNotAllowedError`, that was never journaled. Replay stops at the first difference, because later commands ran on state that no longer matches. It compares outcomes only: a change that alters state, timers or sent messages without changing a reply shows up at the first later command whose outcome it changes. An actor with no `actor.db` replays as an empty window. A layer that doesn't host the actor fails with `ActorNotRegisteredError`, and an unreadable file fails with `ActorUnavailableError`. When a history retention has pruned the start of the journal, replay can't rebuild the state the first kept command ran on, so it fails with `HistoryPrunedError`, whose `coveredSince` is the time from which the history is complete, the same time `Room.historyCoveredSince(key)` returns. Inside `Story.run`, `story.replay(Room, key)` replays against the story's own handlers. `akter history <Actor>/<key> --verify` runs it from the command line.
+
+Every error class the package defines is exported from the root, `@akterjs/effect`, so a caller can write `instanceof` or `Effect.catchTag` against a typed import instead of matching on a tag string. That covers each member of the hosted error union a command, query or create can fail with (`ActorAlreadyExistsError`, `ActorNotCreatedError`, `CallerNotAllowedError`, `CommandIdExpiredError`, `HandlerFailedError`, `InvalidRequestError`), and the errors of the engine, migrations and serving, such as `ActorUnavailableError`, `UnauthenticatedError`, `MigrationFailedError` and `ActorsNotHostedError`. `contract/errors` exports the ones a client call can fail with, so a browser or Worker bundle can name them without the engine.
+
+`@akterjs/effect/hosted` exports `HostedRuntime` and its layer `hostedRuntime` for a host that keeps its own SQLite connection, such as Akter Cloud's engine. `HostedRuntime.declare(name)` finds the actor among the handlers provided to `hostedRuntime` and hashes its migrations, which can wait. `HostedRuntime.open({ actor, filename, sql })` then applies any pending migrations on the `SqlClient` it is handed, and it never waits, so a host can open the actor inside a synchronous batch. After that, `run`, `create`, `history` and `coveredSince` are `CommandRunner`'s and `QueryRunner`'s, and they read and write through that same client. `HostedRuntime` opens no database of its own. A host whose client nests `withTransaction` as a savepoint can run each command inside its own batch, and the journal the command writes is the one `Room.history` reads. `HostedRuntime.historyRetention` is `CommandRunner`'s retention. `HostedRuntime.upkeep({ exclusive, key, opened, send })` starts the upkeep `Akter.local` runs for an opened actor: it runs the actor's committed jobs, fires its due timers and hands each outbox message to `send`. Every read and write it makes goes through `exclusive`, which a host makes the actor's next batch, so a write is durable before the upkeep moves on. It returns the actor's `jobs` store and `kick`, which the host calls after each commit that wrote. `send` gets the target's `actor`, `key`, `member` and `payload`, the sender's `principal`, and a `commandId` that stays the same on every attempt, so a host can deliver the message once. A failed `send` leaves the message in the outbox, and the upkeep retries it with backoff. `HostedRuntime.locateJobs` tells the job engine how to find an actor's `jobs` store from a job id. `HostedRuntime.nextDue(opened)` returns the earliest instant the actor has work: its next timer, or now while a job is open or a message waits. A host can wake the actor then. `HostedRuntime.version({ commandId, opened })` returns the version a command committed at: its position in the journal, which a later command never changes, the same for a retried command id, and none for an id the actor never journaled (a refused call). Send it with the reply so a client can wait for a read at that version or later. `HostedRuntime.live({ exclusive, opened })` opens the same live reads `Akter.local` serves: `state` is the internal raw-row stream; `stateFor(principal)` and `subscribe(request)` are caller-gated streams of `{ value, version }`. `stateFor` uses the same admission and initial-state fill as RPC, then encodes the actor's state schema as JSON text. `stateReads` from `@akterjs/effect/hosted/state` exposes that same adapter for a host's never-created-actor stream. Their `version` is the actor's committed version at the read. `refresh` re-runs only the reads whose tables a command touched since the last refresh. Call `refresh` only after the batch is durable, after `fdatasync`, and only while no other batch is open on the actor's connection, so no reader sees a version that a crash could take back. `exclusive` gives that only to a host that runs one command at a time. A host that groups commands into batches would put the refresh in the next batch, behind commands already queued, and it would read their writes before they are durable. Akter Cloud's engine runs `refresh` on the actor's serve fiber instead, after the batch ships and before the next batch is taken, so no later batch can commit while it reads. Its test `a push never carries a write whose batch has not shipped yet` holds a commit's `fdatasync` and checks that no reading carries that commit's write until the batch ships. `hostedRuntime` also provides the `WorkflowEngine` that `Order.jobs.charge.toLayer` registers job handlers on. `hostedFileHome({ catalog, root })` opens a file home for such a host: blobs go under `root`, sealed by the `BlobSealing` the host provides (Cloud seals them under each actor's key), and their claims and reference counts go on `catalog`, a connection only the home writes. `hostedActorFiles({ exclusive, home, identity, opened, snapshot })` then gives an opened actor its files on that home: `identity` names the actor to the keyring and the catalog, every read and write of the actor's own file tables goes through `exclusive`, so it never interleaves with a command batch, and the returned actor's commands reach the files through `Akter.files`. It recovers unfinished uploads, settles references and keeps them settled until its scope closes (`tests/serve/hosted/hosted-files.layer.test.ts`).
+
+`hostedApp(app.layer)` composes a loaded bundle with its runtime, providing one journaled job engine before either job registration or actor upkeep starts. It shares that engine provider with `Akter.local`. A bundled job carries the app's strict payload and result codecs; the host does not reconstruct them with its own Schema instance. A bundle without those codecs fails at load with `HostedAppBuildError`, asking for an SDK rebuild.
+
+- Depends on: `effect` (peer), `@effect/platform-bun` and `@effect/platform-node` (the HTTP servers).
+- Must not depend on: any private package.

package/dist/contract/actor/actor-already-exists.errors.d.mts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+declare const ActorAlreadyExistsError_base: Schema.Class<ActorAlreadyExistsError, Schema.TaggedStruct<"ActorAlreadyExistsError", {
+  readonly actor: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class ActorAlreadyExistsError extends ActorAlreadyExistsError_base {}
+export {};

package/dist/contract/actor/actor-already-exists.errors.mjs

@@ -0,0 +1,4 @@
+import { Schema } from "effect";
+// src/contract/actor/actor-already-exists.errors.ts
+var ActorAlreadyExistsError = class extends Schema.TaggedError()("ActorAlreadyExistsError", { actor: Schema.String }) {};
+export { ActorAlreadyExistsError };

package/dist/contract/actor/actor-definition.pure.d.mts

@@ -0,0 +1,21 @@
+import { ActorDefinition, ActorHandlers, ActorOptions, AddressedCommands, DefinitionOf, HostedActor, PrincipalOf } from "./actor.contract.mjs";
+import { ActorRpcs } from "../client/actor-rpc.contract.mjs";
+import { Principal } from "../caller/principal.schema.mjs";
+import { Declaring, reservedMembers } from "./actor-names.pure.mjs";
+import { fileAccess } from "../file/access/file-access.contract.mjs";
+import { Context, Effect, Option } from "effect";
+declare function definitionOf<Options extends ActorOptions>(declaring: Declaring<Options>): DefinitionOf<Options>;
+interface Naming<Name extends string, Definition extends ActorDefinition> {
+  readonly definition: Definition;
+  readonly name: Name;
+}
+declare function commandsOf<Name extends string, Definition extends ActorDefinition>(naming: Naming<Name, Definition>): AddressedCommands<Name, Definition>;
+declare function initialOf<Options extends ActorOptions>(options: Options): Option.Option<() => Options["state"]["Type"]>;
+declare function principalOf<Definition extends ActorDefinition, Needs>(principal: Effect.Effect<Principal, never, Needs>): Effect.Effect<PrincipalOf<Definition>, never, Needs>;
+declare const handlersKey: <Name extends string>(name: Name) => Context.Key<ActorHandlers<Name>, HostedActor>;
+interface NamedDefinition {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+}
+declare const rpcsOf: ({ definition, name }: NamedDefinition) => ActorRpcs;
+export { commandsOf, definitionOf, fileAccess, handlersKey, initialOf, principalOf, reservedMembers, rpcsOf };

package/dist/contract/actor/actor-definition.pure.mjs

@@ -0,0 +1,106 @@
+import { creationErrors, creationModesOf } from "../client/actor-rpc.contract.mjs";
+import { fileRpcsOf } from "../file/rpc/file-rpc.contract.mjs";
+import { Authentication } from "../caller/authentication.api.mjs";
+import { forkRpcOf } from "../fork/fork-rpc.contract.mjs";
+import { computerRpcsOf } from "../computer/rpc/computer-rpc.contract.mjs";
+import { CommandId } from "../command/command-id.schema.mjs";
+import { declaredSchema } from "../command/command.contract.mjs";
+import { HostedFailure } from "../hosted/hosted-failure.schema.mjs";
+import { Principal } from "../caller/principal.schema.mjs";
+import { rejectInvalidSecrets, rejectReserved, reservedMembers } from "./actor-names.pure.mjs";
+import { fileAccess } from "../file/access/file-access.contract.mjs";
+import { Array, Context, Option, Record, Schema, pipe } from "effect";
+import { Rpc, RpcGroup } from "effect/rpc";
+// src/contract/actor/actor-definition.pure.ts
+function definitionOf(declaring) {
+	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: () => Schema.Never,
+			onSome: (input) => declaredSchema(input)
+		})),
+		fileAccess: Option.filter(Option.fromNullishOr(options.files), (declared) => Option.exists(declared.callers, Array.isReadonlyArrayNonEmpty)),
+		jobs: options.jobs ?? {},
+		key: options.key,
+		queries: options.queries ?? {},
+		secrets: Array.dedupe(options.secrets ?? []),
+		state: options.state
+	};
+}
+function commandsOf({ definition, name }) {
+	return Record.map(definition.commands, (declaration, member) => ({
+		...declaration,
+		address: {
+			actor: name,
+			key: definition.key,
+			member
+		}
+	}));
+}
+function initialOf(options) {
+	return Option.fromNullishOr(options.initial);
+}
+function principalOf(principal) {
+	return principal;
+}
+const handlersKey = (name) => Context.Service(`@akterjs/effect/contract/actor-handlers/${name}`);
+const failureOf = (declared) => Schema.Union([declared, HostedFailure]);
+const updateOf = (value) => Schema.Struct({
+	value,
+	version: Schema.Int
+});
+const subscriptionTag = (name, member) => `${name}/${member}/subscribe`;
+const creationTag = (name, mode) => `${name}/${mode}`;
+const created = Schema.Void;
+const warmTag = (name) => `${name}/warm`;
+const rpcsOf = ({ definition, name }) => RpcGroup.make(...Array.map(Record.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
+})), ...Array.map(Record.toEntries(definition.queries), ([member, declaration]) => Rpc.make(`${name}/${member}`, {
+	error: failureOf(declaration.error),
+	payload: {
+		key: definition.key,
+		payload: declaration.payload
+	},
+	success: declaration.success
+})), ...Array.map(Record.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)
+})), ...Array.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 { commandsOf, definitionOf, fileAccess, handlersKey, initialOf, principalOf, reservedMembers, rpcsOf };

package/dist/contract/actor/actor-erased.errors.d.mts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+declare const ActorErasedError_base: Schema.Class<ActorErasedError, Schema.TaggedStruct<"ActorErasedError", {
+  readonly actor: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class ActorErasedError extends ActorErasedError_base {}
+export {};

package/dist/contract/actor/actor-erased.errors.mjs

@@ -0,0 +1,4 @@
+import { Schema } from "effect";
+// src/contract/actor/actor-erased.errors.ts
+var ActorErasedError = class extends Schema.TaggedError()("ActorErasedError", { actor: Schema.String }) {};
+export { ActorErasedError };

package/dist/contract/actor/actor-names.pure.d.mts

@@ -0,0 +1,11 @@
+import { ActorOptions, ReservedMember } from "./actor.contract.mjs";
+/** Every name the actor object and its clients use, so no command or query may take one. */
+declare const reservedMembers: readonly ReservedMember[];
+interface Declaring<Options extends ActorOptions> {
+  readonly name: string;
+  readonly options: Options;
+}
+declare const rejectReserved: ({ name, options }: Declaring<ActorOptions>) => void;
+/** A secret name no environment could set is a mistake in the declaration, refused where the actor is made. */
+declare const rejectInvalidSecrets: ({ name, options }: Declaring<ActorOptions>) => void;
+export { type Declaring, rejectInvalidSecrets, rejectReserved, reservedMembers };

package/dist/contract/actor/actor-names.pure.mjs

@@ -0,0 +1,51 @@
+import { ReservedMemberError } from "./reserved-member.errors.mjs";
+import { InvalidSecretNameError } from "../secret/invalid-secret-name.errors.mjs";
+import { SecretName } from "../secret/secret.schema.mjs";
+import { Array, Option, Record, Schema } from "effect";
+// src/contract/actor/actor-names.pure.ts
+const isSecretName = Schema.is(SecretName);
+/** Every name the actor object and its clients use, so no command or query may take one. */
+const reservedMembers = [
+	"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"
+];
+const rejectReserved = ({ name, options }) => {
+	const members = [...Record.keys(options.commands), ...Record.keys(options.queries ?? {})];
+	const reserved = Array.findFirst(members, (member) => Array.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 }) => {
+	const invalid = Array.findFirst(options.secrets ?? [], (secret) => !isSecretName(secret));
+	if (Option.isSome(invalid)) throw InvalidSecretNameError.make({
+		actor: name,
+		secret: invalid.value
+	});
+};
+export { rejectInvalidSecrets, rejectReserved, reservedMembers };

package/dist/contract/actor/actor-not-created.errors.d.mts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+declare const ActorNotCreatedError_base: Schema.Class<ActorNotCreatedError, Schema.TaggedStruct<"ActorNotCreatedError", {
+  readonly actor: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class ActorNotCreatedError extends ActorNotCreatedError_base {}
+export {};

package/dist/contract/actor/actor-not-created.errors.mjs

@@ -0,0 +1,4 @@
+import { Schema } from "effect";
+// src/contract/actor/actor-not-created.errors.ts
+var ActorNotCreatedError = class extends Schema.TaggedError()("ActorNotCreatedError", { actor: Schema.String }) {};
+export { ActorNotCreatedError };

package/dist/contract/actor/actor-not-registered.errors.d.mts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+declare const ActorNotRegisteredError_base: Schema.Class<ActorNotRegisteredError, Schema.TaggedStruct<"ActorNotRegisteredError", {
+  readonly actor: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class ActorNotRegisteredError extends ActorNotRegisteredError_base {}
+export {};

package/dist/contract/actor/actor-not-registered.errors.mjs

@@ -0,0 +1,4 @@
+import { Schema } from "effect";
+// src/contract/actor/actor-not-registered.errors.ts
+var ActorNotRegisteredError = class extends Schema.TaggedError()("ActorNotRegisteredError", { actor: Schema.String }) {};
+export { ActorNotRegisteredError };

package/dist/contract/actor/actor-registry.service.d.mts

@@ -0,0 +1,16 @@
+import { HostedActor } from "./actor.contract.mjs";
+import { ActorNotRegisteredError } from "./actor-not-registered.errors.mjs";
+import { Context, Effect, Layer } from "effect";
+declare const ActorRegistry_base: Context.ServiceClass<ActorRegistry, "@akterjs/effect/contract/actor/actor-registry.service/ActorRegistry", {
+  readonly lookup: (name: string) => Effect.Effect<HostedActor, ActorNotRegisteredError>;
+  readonly register: (actor: HostedActor) => Effect.Effect<void>;
+}> & {
+  readonly make: Effect.Effect<{
+    readonly lookup: (name: string) => Effect.Effect<HostedActor, ActorNotRegisteredError>;
+    readonly register: (actor: HostedActor) => Effect.Effect<void>;
+  }, never, never>;
+};
+export declare class ActorRegistry extends ActorRegistry_base {
+  static readonly layer: Layer.Layer<ActorRegistry, never, never>;
+}
+export {};

package/dist/contract/actor/actor-registry.service.mjs

@@ -0,0 +1,21 @@
+import { ActorNotRegisteredError } from "./actor-not-registered.errors.mjs";
+import { Context, Effect, HashMap, Layer, Option, Ref } from "effect";
+// src/contract/actor/actor-registry.service.ts
+var ActorRegistry = class extends Context.Service()("@akterjs/effect/contract/actor/actor-registry.service/ActorRegistry", { make: Effect.gen(function* makeActorRegistry() {
+	const actors = yield* Ref.make(HashMap.empty());
+	const register = Effect.fn("ActorRegistry.register")(function* register(actor) {
+		yield* Ref.update(actors, HashMap.set(actor.name, actor));
+	});
+	return {
+		lookup: Effect.fn("ActorRegistry.lookup")(function* lookup(name) {
+			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;
+		}),
+		register
+	};
+}) }) {
+	static layer = Layer.effect(this, this.make);
+};
+export { ActorRegistry };