actor-ts 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -7,7 +7,327 @@ This is a pre-1.0 hobby project — every minor version is potentially
 breaking.  See `ROADMAP.md` for what's coming, and `README.md` →
 "What's in here / What isn't" for current scope honesty.
 
-## [Unreleased]
+## [0.11.0] — 2026-07-15
+
+### Changed — Naming conventions: no abbreviations, unified vocabulary
+
+Repo-wide naming sweep for consistency.  Pre-1.0, so these are hard
+renames with no deprecation shims.  All are mechanical — same behavior,
+new names.
+
+- **BREAKING — WebSocket → `Websocket` (single-cap), no `Ws` abbreviation.**
+  Every identifier and file/dir uses the `Websocket` spelling:
+  `WebSocketServerActor`/`WebSocketClientActor` → `WebsocketServerActor`/
+  `WebsocketClientActor`; the `Ws*` supporting types (`WsConnection`,
+  `WsCodec`, `WsFrame`, `WsServerMessage`, …) → `Websocket*`; `wsSend()` →
+  `websocketSend()`; `DEFAULT_WS_MAX_FRAME_BYTES` →
+  `DEFAULT_WEBSOCKET_MAX_FRAME_BYTES`; the module moved
+  `src/http/ws/` → `src/http/websocket/`.  The `websocket()` routing
+  directive, the global `WebSocket`, the `ws` package's `WebSocketServer`,
+  and the `Sec-WebSocket-Protocol` header are unchanged.
+  *Migration:* replace `Ws`/`WebSocket` identifier prefixes with
+  `Websocket`; `wsSend` → `websocketSend`.
+- **BREAKING — abbreviations spelled out** in type/member names: `*Cmd` →
+  `*Command`, `*Msg` → `*Message`, `*Ack` → `*Acknowledgment`, `ByPid*` →
+  `ByPersistenceId*`, `*Impl` → `*Implementation`, `*Ctor` → `*Constructor`.
+  Wire/discriminator string literals are unchanged.
+  *Migration:* e.g. `MqttCmd` → `MqttCommand`, `EnvelopeMsg` →
+  `EnvelopeMessage`, `SubscribeAck` → `SubscribeAcknowledgment`.
+- **BREAKING — testkit assertions spelled out too:** `TestProbe.expectMsg()`
+  → `expectMessage()`, `TestProbe.expectMsgType()` → `expectMessageType()` —
+  the last `Msg` holdouts, now consistent with `expectNoMessage()`.
+  *Migration:* rename the calls; signatures and behavior are unchanged.
+- **BREAKING — one config vocabulary: `Options`, never `Settings`.**
+  Remaining `*Settings` types → `*OptionsType` (`CircuitBreakerSettings`,
+  `TlsTransportSettings`, `Bounded/PriorityMailboxSettings`,
+  `ManagementRoutesSettings`, `ConsumerControllerSettings`,
+  `KeepMajoritySettings`, the testkit specs); `BrokerSettings.ts` folded
+  into `BrokerOptions.ts` (`BrokerSettingsError` → `BrokerOptionsError`);
+  the `BrokerActor` glue `readSettingsFromConfig`/`requiredSettings`/
+  `builtInDefaults`/`settings` → `readOptionsFromConfig`/`requiredOptions`/
+  `builtInDefaultOptions`/`options`; `default{FailureDetector,PhiAccrual}Settings`
+  → `default*Options`.  New dedicated `ConsumerControllerOptions` +
+  `KeepMajorityOptions` files with builders.
+- **BREAKING — Command vs Signal unified on `kind`.**  MQTT and WebSocket
+  internal mailbox signals are now `kind`-tagged plain objects (dispatched
+  by `kind`, like the typed-actor `Signal`), not `instanceof`-dispatched
+  classes; the bad-payload hook is `onInvalidMessage` everywhere (MQTT's
+  `onDecodeError` is gone); `WebSocketAcceptSignal` → `WebsocketAcceptCommand`
+  and `WebsocketClientSend` is a command, both lifted out of the `*Signal`
+  unions.
+  *Migration:* override `onInvalidMessage` instead of `onDecodeError`;
+  construct outbound sends via `websocketSend(msg)` (unchanged).
+### Added — Options validation
+
+- **`OptionsValidator` + `OptionsError`** (#274) — a declarative-but-code
+  validator layer for the `XOptions` pattern.  Each options file with
+  constrained fields exports an `XOptionsValidator` (`extends
+  OptionsValidator<XOptionsType>`, brokers via `BrokerOptionsValidator`) whose
+  `rules(s)` uses typo-checked, no-op-on-`undefined` helpers (`port`,
+  `positiveNumber`, `positiveInt`, `nonNegativeInt`, `oneOf`, `nonEmptyString`,
+  `url`, …) plus `fail(field, reason, value)` for cross-field rules.  Validation
+  runs **once at consume time on the merged settings**, so builder, plain-object,
+  and HOCON inputs are all checked and cross-field rules see the final values —
+  broker actors via the `optionsValidator()` hook (in `preStart`, after the
+  required-field check), non-broker consumers via one
+  `new XOptionsValidator().validate(settings)` call in their constructor.
+- **Validators shipped for**: every broker (MQTT, Kafka, AMQP, Redis Streams,
+  NATS, JetStream, SSE, TCP, UDP, gRPC client) and the WebSocket client; the
+  cluster core (`Cluster`, `ClusterBootstrap`, `FailureDetector`, `PhiAccrual`,
+  `ClusterClient`, `ClusterClientReceptionist`, `StaticQuorum`, `KeepReferee`,
+  `LeaseMajority`, `ClusterRouter`), sharding (`Sharding`, `StartSharding`,
+  `ShardedDaemonProcess`) and singleton (`StartSingleton`); discovery
+  (`AutoDiscovery`, `ConfigSeedProvider`, `DnsSeedProvider`,
+  `KubernetesApiSeedProvider`, `Receptionist`) and gossip intervals
+  (`DistributedPubSub`, `DistributedData`); leases (`Lease`, `KubernetesLease`);
+  caches (`RedisCache`, `MemcachedCache`, `CachedSnapshotStore`); the
+  `CassandraJournal` and S3 / filesystem object-storage backends; the
+  Express/Hono HTTP backends; `WorkerCluster`; delivery `ProducerController`;
+  and `TestProbe`.  Options whose fields carry no real constraint
+  (all-boolean/string/callback, or degrade-gracefully knobs like snapshot
+  `keepN` where `<= 0` means "keep all") intentionally get no validator.
+
+### Changed — Options validation
+
+- **BREAKING** (#274) — invalid **option values** now throw `OptionsError` at
+  construction / actor start instead of a bare `Error` (or, previously, going
+  unchecked on the builder/plain-object path).  Notably MQTT `protocolVersion`
+  outside `{4, 5}` now throws `OptionsError` on **all** input paths (previously
+  only the HOCON path threw, as a bare `Error`).  *Migration:* catch
+  `OptionsError` (exported from the package root) where you previously matched
+  the ad-hoc `Error` message.  Missing **required** broker settings still throw
+  `BrokerOptionsError`; malformed HOCON still throws `ConfigError`.
+- **BREAKING — `InMemoryCache` joins the `XOptions` family.** It now takes an
+  `InMemoryCacheOptions` builder (or plain object) with `withMaxEntries` /
+  `withCleanupMs`, validates via `InMemoryCacheOptionsValidator` (out-of-range
+  values throw `OptionsError` instead of a bare `Error`, and `cleanupMs` — a
+  negative / `NaN` sweep interval — is now checked too), and reads its defaults
+  from HOCON `actor-ts.cache.in-memory.{maxEntries, cleanupMs}` via the
+  `CacheExtension` (previously the bounds were unreachable through the
+  extension).  The internal `InMemoryCacheSettings` interface is **removed** —
+  use `InMemoryCacheOptionsType` (both `InMemoryCacheOptions` and the type are
+  now exported from the package root).  *Migration:* a plain
+  `{ maxEntries, cleanupMs }` object still works unchanged; only the type name
+  changed.
+- **WebSocket route / policy options are now validated.** The resolved
+  per-connection policy (`maxFrameBytes`, `maxBufferedBytes`, `maxConnections`,
+  and the `onOversizeFrame` / `onInvalidMessage` / `onBackpressure` enums) is
+  checked on every path — route options, HOCON `actor-ts.http.websocket`, and
+  defaults — via `WebsocketPolicyOptionsValidator`, and `allowedOrigins` via
+  `WebsocketRouteOptionsValidator`.  Bad values throw `OptionsError` (the enum
+  guard previously threw a bare `Error`, and only on the HOCON path; the
+  numeric knobs — e.g. `maxConnections: 0`, which silently admitted nobody —
+  were unchecked).  The reference config now ships an `actor-ts.http.websocket`
+  section documenting the defaults.
+- **The object-storage decompression cap is now a store option.** The 512 MiB
+  decompression-bomb guard (#3) was pinned to its default because the stores
+  called `decodeBody` without a cap.  `withMaxDecompressedBytes` is now on
+  `ObjectStorageSnapshotStoreOptions`, `ObjectStorageDurableStateStoreOptions`,
+  and `ObjectStoragePluginOptions` (validated at construction — a non-positive
+  / non-integer cap throws `OptionsError`, `Infinity` opts out), and both
+  stores forward it into `decodeBody`.  Raise it to restore a legitimately
+  large snapshot / state blob, or lower it for a tighter bound.
+- **HTTP middleware + directives now validate their options.** Added
+  `OptionsValidator`s for `TimeoutOptions` (`ms`), `HstsOptions` (`maxAge` plus
+  the preload cross-field), `CorsOptions` (`maxAge` plus credentials-vs-`*`),
+  `CsrfOptions` (present-secret length, cookie `sameSite` / `maxAgeSeconds`),
+  and `StaticFilesOptions` (`maxFileSize`, `dotfiles` / `symlinks` enums); the
+  ad-hoc bare-`Error` validity checks in the consumers now throw `OptionsError`
+  (required-field guards stay as-is).  `rateLimit` and `idempotent` also gained
+  the real `RateLimitOptions` / `IdempotencyOptions` fluent builders they were
+  already documented to have, each with a validator (`windowMs`/`max`,
+  `ttlMs`/`missingHeader`); the plain-object call form is unchanged.
+- **`CircuitBreaker` and `BoundedMailbox` now validate their options too** —
+  the last exported options types with real numeric constraints join the
+  validator family.  `CircuitBreakerOptionsValidator` checks `maxFailures`
+  (integer >= 1), `resetTimeoutMs` (finite >= 0), and the previously-unchecked
+  `callTimeoutMs` (> 0 — omit it to disable the per-call timeout; `0`, which
+  previously meant "no timeout" silently, now throws), and requires
+  `maxFailures`/`resetTimeoutMs` at runtime (a builder without them previously
+  produced a breaker that silently never opened).
+  `BoundedMailboxOptionsValidator` checks `capacity` (integer >= 1, and now
+  required — previously a missing `capacity` made the "bounded" mailbox
+  silently unbounded) and the previously-unchecked `overflow` enum.  The old
+  ad-hoc bare-`Error` guards now throw `OptionsError`.
+
+### Added — HTTP hardening
+
+- **Scoped error handling + fallback routes** (#352) — `handleErrors(handler,
+  child)` catches exceptions from a subtree (akka-http `ExceptionHandler`
+  style; sees the original error, returns a response or `null` to decline);
+  `fallback(handler)` answers any unmatched request via each backend's
+  not-found hook; `ServerBuilder.withErrorHandler(...)` is the server-wide
+  last resort.  Precedence, uniform across Fastify/Express/Hono: innermost
+  `handleErrors` → `withErrorHandler` → framework default.
+- **HTML response utilities** (#352) — `escapeHtml`, an auto-escaping `html`
+  tagged template with a `SafeHtml` brand, `rawHtml` escape hatch, and
+  `completeHtml` (`text/html` + `nosniff`).
+- **Security-middleware suite** (#353) — `cors` (a route directive that the
+  compiler expands into per-pattern preflight `OPTIONS` routes),
+  `strictTransportSecurity` / `hsts`, `contentSecurityPolicy`,
+  `csrfProtection` + `requireSameOrigin`, `securityHeaders`, `requestId`,
+  `BasicAuth`, and `requestTimeout` — each with an `XOptions` builder.  Plus
+  public `parseCookies` / `serializeCookie` helpers.
+- **Static file serving** (#354) — `getFromFile`, `getFromDirectory`, and
+  `getFromBrowseableDirectory`: MIME detection, index resolution, conditional
+  requests (weak ETag + `Last-Modified` → 304), single `Range` (206/416),
+  HEAD, trailing-slash redirects, and XSS-safe directory listings.
+- **MIME-type registry** (#354) — `contentTypeFor(pathOrExt, overrides?)` and
+  `DEFAULT_MIME_TYPES`.
+- **Streaming response bodies** (#354) — `HttpResponse.body` now accepts a web
+  `ReadableStream<Uint8Array>`, written natively by all three backends.
+
+### Changed — HTTP hardening
+
+- **`Middleware` `next()` accepts an optional request override** (#353) —
+  `next(req?)` lets a middleware enrich what the handler sees (request-id,
+  CSRF token).  Backward compatible.
+- **HonoBackend now answers `HEAD` on `GET` routes** (#354), matching
+  Fastify/Express; a route pattern ending in `/*` exposes the remainder as
+  `req.params['*']` on every backend.
+- **BREAKING:** the `Route` / `CompiledEndpoint` unions gain `fallback` and
+  `cors` variants — an exhaustive `match` over `Route` must handle them
+  (#352, #353).
+- **BREAKING:** `ServerBuilder` gains a required `withErrorHandler` method —
+  structural third-party implementers must add it (#352).
+- **BREAKING:** `HttpError`'s constructor gains an optional 4th `headers`
+  parameter (after `extra`); `BearerTokenAuth` 401s now expose the challenge
+  on `err.headers['www-authenticate']`, no longer `err.extra.wwwAuthenticate`
+  (#352).
+
+### Security
+
+- **CORS, CSRF, and security-header middleware** (#353) — origin allowlisting
+  with correct preflight handling, an HMAC-signed double-submit CSRF token
+  (plus an Origin/Referer check), and HSTS / CSP / COOP / CORP / nosniff /
+  frame-options; secret comparisons are constant-time.
+- **`WWW-Authenticate` reaches the wire** (#353) — `BearerTokenAuth` (and the
+  new `BasicAuth`) 401s emit a real challenge header instead of burying it in
+  the body.
+- **Hardened path-traversal defence for static files** (#354) — the URL
+  remainder is fully decoded before validation, every segment is rejected if
+  it is `..`, empty, NUL, a backslash, or a `:` (drive/ADS) segment, absolute
+  forms are refused, the joined path is confined to the root, symlink escapes
+  are refused, and dotfiles are denied — every rejection a uniform 404.
+
+- **WS-1 (HIGH) — WebSocket upgrade crash hardened**.
+  A malformed percent-escape in the upgrade path (e.g. `GET /room/%ZZ` against a
+  `websocket('/room/:id', …)` route) made `decodeURIComponent` throw inside the
+  Express backend's fire-and-forget upgrade handler, surfacing as an *unhandled
+  rejection* — process-fatal under Node's default and reachable **pre-auth** by
+  an unauthenticated client.  `matchWebsocketPattern` now treats a malformed escape as
+  a non-match (→ 404), and the Express upgrade handler attaches its socket
+  error-guard before any async work and wraps the handler in a last-resort
+  `.catch` that closes the socket.  Fastify/Hono were not affected.
+- **WS-2 (HIGH) — Cross-Site WebSocket Hijacking (CSWSH) defence**.  No upgrade handler validated the `Origin` header, so a
+  malicious web page could open an authenticated WebSocket riding a victim
+  browser's ambient cookie/IP auth.  New **`allowedOrigins`** option on
+  `websocket()` routes (`.withAllowedOrigins([...])` on the builder): an upgrade
+  whose `Origin` is present but not listed is rejected with 403 before the
+  handshake on all three backends; a missing `Origin` (non-browser client) is
+  allowed.  Bearer-token auth was already resistant (browsers can't set
+  `Authorization` on a WS handshake).
+- **HTTP-1 (MEDIUM-HIGH) — Hono body-size cap enforced before buffering**.  The Hono backend read the whole request body via
+  `arrayBuffer()` and only then compared it against `maxBodyBytes`, so the cap
+  was cosmetic — the real ceiling was the runtime's native default (128 MiB on
+  Bun, effectively unbounded on Node via `@hono/node-server`).  It now rejects
+  an oversized `Content-Length` with 413 *before* buffering; the post-buffer
+  check remains a backstop for chunked bodies that omit Content-Length.
+  Express (streaming cap) and Fastify (framework default) were unaffected.
+- **HTTP-2 (MEDIUM-HIGH) — `InMemoryCache` is now bounded (LRU)**.  The default in-process cache was an unbounded `Map`
+  with lazy expiry only, so a flood of distinct attacker-chosen keys
+  (`Idempotency-Key`; rate-limit keys — idempotency additionally stores the
+  full response body for 24 h) grew it without limit → RAM exhaustion.  It now
+  accepts `{ maxEntries?, cleanupMs? }` (defaults `10_000` / `60_000`): a new
+  key beyond the cap evicts the least-recently-used entry, and a background
+  sweep reclaims expired entries.  *Behaviour change:* the default
+  is now bounded — pass `maxEntries: Infinity` for the previous unbounded
+  behaviour (documented OOM risk).  Options / validation / HOCON plumbing for
+  these fields landed as the `InMemoryCacheOptions` follow-up (see *Changed —
+  Options validation*).
+- **WS-6 (LOW) — CRLF stripped from raw upgrade-reject headers**.  `writeRawHttpResponse` (the Express pre-handshake
+  reject path) wrote app-supplied header names/values verbatim onto the raw
+  socket, so an `authorize` guard echoing attacker-influenced data into a
+  header could split the response.  CR/LF are now stripped from header names
+  and values.
+- **#9 (hardening) — JSON deserialization ignores the `__proto__` setter**
+ .  `JsonSerializer` and the cluster ref decoder
+  now define a decoded `"__proto__"` key as an own data property instead of
+  assigning through the prototype setter, so a hostile payload can't change
+  the decoded object's prototype.
+- **BRK-1 / BRK-2 (MEDIUM) — inbound buffer caps for TCP `lines` + SSE**.  A hostile / MITM'd upstream could stream bytes with no
+  frame delimiter, growing the inbound buffer without bound.  The TCP `lines`
+  framer now rejects an un-terminated remainder that already exceeds
+  `maxLineLen` (matching the existing terminated-line check), and the SSE
+  client caps its pending event buffer at 1 MiB — both drop the connection
+  instead of buffering forever.  (`length-prefixed` TCP framing was already
+  bounded.)
+- **#6 (LOW) — consistent SQL/CQL identifier validation**.  Postgres/MariaDB already validated table identifiers,
+  but SQLite (journal + snapshot store) and Cassandra (keyspace + table names,
+  interpolated into CQL) did not.  A shared `assertSafeIdentifier`
+  (`/^[A-Za-z_][A-Za-z0-9_]*$/`) is now applied across all four, so a
+  config-sourced identifier can't inject SQL/CQL.  Data values were, and
+  remain, bound parameters.
+- **HTTP-3 (docs) — rate-limit examples key on the socket peer, not
+  `x-forwarded-for`**.  The shipped `rateLimit`
+  examples taught keying on the client-settable `x-forwarded-for` header, which
+  an attacker rotates per request to bypass the limit (and which collapses all
+  header-less clients into one shared bucket).  The JSDoc and the bilingual
+  docs now use `req.remoteAddress` and state the trusted-proxy caveat.  No
+  behaviour change — `key` was always caller-supplied.
+- **#3 (MEDIUM) — decompression-bomb cap on stored bodies**.  Reading a snapshot / durable-state / object body
+  decompressed it with no output bound, so a tampered or hostile compressed
+  blob (a few KB expanding to many GB) could OOM the process on recovery.
+  `decodeBody` now caps the decompressed size at **512 MiB** by default
+  (`DecodeOptions.maxOutputBytes`; `Infinity` opts out): gzip enforces it at
+  allocation time via zlib's `maxOutputLength`, and every path asserts the
+  decoded size as a portable backstop.
+- **HTTP-4 (MEDIUM) — idempotency responses can be scoped per caller**.  The idempotency cache keyed only on the
+  `Idempotency-Key` header plus a method/path/body fingerprint, so two callers
+  reusing the same key for the same request shape shared one cached response —
+  a cross-user disclosure when the response is identity-specific (e.g. carries
+  `Set-Cookie` or the first caller's data).  New opt-in `identity: (req) =>
+  string` folds the authenticated principal into the cache key so responses are
+  partitioned per caller.  (Same-key-different-body poisoning was already
+  rejected with 422.)
+- **WS-4 (MEDIUM) — WebSocket backpressure works on the Hono backend**.  The Hono socket adapter didn't implement
+  `bufferedAmount`, so the connection actor's `maxBufferedBytes` /
+  `onBackpressure` guard was a no-op on Hono — a slow / idle-reading client
+  could grow the outbound send buffer without bound (OOM).  The adapter now
+  surfaces the send-buffer depth from the native socket (Bun
+  `getBufferedAmount()`, Node/Deno numeric `.bufferedAmount`).
+- **WS-3 (MEDIUM) — cap the WebSocket transport frame size (Express + Fastify)**
+ .  The `ws`-backed backends left the transport at the
+  `ws` default `maxPayload` (100 MiB), so an oversized frame was buffered in
+  full before the app-level `maxFrameBytes` (1 MiB default) rejected it —
+  allocation-amplification DoS.  Both now pass `maxPayload:
+  DEFAULT_WEBSOCKET_MAX_FRAME_BYTES` (1 MiB), so an oversized frame is rejected at the
+  protocol level.  *Caveat:* on these backends a route that raises
+  `maxFrameBytes` above the default is currently still capped at the default by
+  the transport; a per-route / configurable transport cap and the Hono
+  runner-level cap are tracked follow-ups.
+- **WS-5 (MEDIUM, partial) — per-route WebSocket connection admission cap**
+ .  New opt-in `maxConnections` on `websocket()`
+  routes (`.withMaxConnections(n)`, or `actor-ts.http.websocket.maxConnections`
+  in HOCON): a new upgrade beyond the cap is closed with 1013 in the shared
+  wiring layer before an actor is wired for it, and the live count decrements
+  when a connection closes.  Default: unlimited (behaviour unchanged).  The
+  other WS-5 sub-parts — a handshake/idle timeout and hub-mailbox bounding —
+  remain tracked follow-ups.
+
+### Documentation
+
+- Moved the Server-WebSocket page from the IO section into the HTTP section
+  (#351).
+- Reconciled stale API-reference pages with the shipped code (#360): rewrote the
+  persistence adapter & migration pages and the OTel **tracing** adapter page to
+  the function-based APIs, rewrote the management & health-check and cache &
+  durable-data pages to their real APIs, and removed the page for the
+  never-shipped OTel *metrics* adapter.
+- Repointed stale `*Settings` type names in prose to the `*OptionsType`
+  vocabulary (#349).
+- Fixed broken code samples that declared a `const` inside a call's object
+  literal (#359).
 
 ## [0.10.0] — 2026-07-08
 

package/README.md

@@ -5,8 +5,8 @@
 <p align="center">
   <a href="https://github.com/pathosDev/actor-ts/actions/workflows/build.yml"><img alt="build workflow" src="https://github.com/pathosDev/actor-ts/actions/workflows/build.yml/badge.svg?branch=main"/></a>
   <a href="https://github.com/pathosDev/actor-ts/actions/workflows/test.yml"><img alt="tests workflow" src="https://github.com/pathosDev/actor-ts/actions/workflows/test.yml/badge.svg?branch=main"/></a>
-  <a href="#"><img alt="tests" src="https://img.shields.io/badge/tests-2215%20of%202215-22c55e?style=flat-square&logo=bun"/></a>
-  <a href="#"><img alt="coverage" src="https://img.shields.io/badge/coverage-~81%25-22c55e?style=flat-square"/></a>
+  <a href="#"><img alt="tests" src="https://img.shields.io/badge/tests-2657%20of%202657-22c55e?style=flat-square&logo=bun"/></a>
+  <a href="#"><img alt="coverage" src="https://img.shields.io/badge/coverage-~90%25-22c55e?style=flat-square"/></a>
 </p>
 
 <p align="center">
@@ -28,7 +28,7 @@
 > the actor-model stack (actors, supervision, cluster, sharding, persistence,
 > HTTP) to TypeScript, running on Bun, Node.js, and Deno.  Large parts were
 > written with AI pair-programming and **have not been battle-tested in
-> production**.  Test coverage is good (~2215 tests, ~81 % line) but the
+> production**.  Test coverage is good (~2657 tests, ~90 % line) but the
 > surface area is enormous.  **Do not deploy this to anything that matters
 > yet.**  Use it to learn, to prototype, to benchmark ideas — not to handle
 > real money, users, or data.
@@ -61,14 +61,23 @@ A short tour of what's in the box:
 - **HTTP** — directive-style routing DSL with Fastify default, Express + Hono
   backends, response caching, rate-limiting, idempotency-key dedup.  Typed
   **WebSocket** routes: `websocket(path, actorRef)` binds a
-  `WebSocketServerActor` (typed messages, `reply` / `broadcast`,
-  connect/disconnect hooks); `WebSocketClientActor` is the reconnecting
-  client half.
+  `WebsocketServerActor` (typed messages, `reply` / `broadcast`,
+  connect/disconnect hooks); `WebsocketClientActor` is the reconnecting
+  client half.  Scoped error handling (`handleErrors`) + `fallback` routes;
+  a security-middleware suite (CORS, CSRF, HSTS, CSP, security headers,
+  Basic auth, request-id, timeout); HTML-escaping helpers; and
+  backend-agnostic **static file serving** (`getFromFile` /
+  `getFromDirectory` — MIME detection, conditional requests, Range,
+  directory browsing).
 - **Message brokers** — single `BrokerActor` base with Kafka, MQTT, AMQP,
   NATS, Redis-Streams, gRPC, SSE, raw TCP/UDP integrations.
   Reconnect-with-backoff, outbound buffer, subscriber fan-out are baked in.
 - **Caching** — pluggable Cache with in-memory, Redis, Memcached backends.
-- **Observability** — Prometheus exporter, OTel tracing + metrics, management
+- **Typed options + fail-fast validation** — one fluent `XOptions` builder per
+  configurable thing (or a plain object), with values validated once on the
+  merged settings (builder / object / HOCON alike) — a bad port, timeout, or
+  URL throws an `OptionsError` at startup, not deep in a later code path.
+- **Observability** — Prometheus exporter, OTel tracing, management
   HTTP endpoints (`/health`, `/ready`, `/cluster/members`, `/sharding/regions`),
   out-of-the-box stock metrics.
 - **TestKit** — `TestProbe`, `ManualScheduler`, `MultiNodeSpec` for
@@ -120,21 +129,21 @@ snippet that matches what you're reaching for.
 Discriminated-union messages plus `match().exhaustive()` from
 [`ts-pattern`](https://github.com/gvergnaud/ts-pattern) give you a
 compile-time check that every variant is handled. Add a new variant
-to `Cmd` without a matching `with(...)` arm and TypeScript fails the
+to `Command` without a matching `with(...)` arm and TypeScript fails the
 build.
 
 ```ts
 import { Actor, ActorSystem, Props, type ActorRef } from 'actor-ts';
 import { match } from 'ts-pattern';
 
-type Cmd =
+type Command =
   | { kind: 'inc' }
   | { kind: 'dec' }
   | { kind: 'get'; replyTo: ActorRef<number> };
 
-class Counter extends Actor<Cmd> {
+class Counter extends Actor<Command> {
   private count = 0;
-  override onReceive(cmd: Cmd): void {
+  override onReceive(cmd: Command): void {
     match(cmd)
       .with({ kind: 'inc' }, () => { this.count++; })
       .with({ kind: 'dec' }, () => { this.count--; })
@@ -173,11 +182,11 @@ the rest of the app sees, every mutation durable.
 ```ts
 import { PersistentActor, ActorSystem, Props } from 'actor-ts';
 
-type Cmd   = { kind: 'inc' } | { kind: 'dec' };
+type Command   = { kind: 'inc' } | { kind: 'dec' };
 type Event = { kind: 'incremented' } | { kind: 'decremented' };
 interface State { count: number }
 
-class Counter extends PersistentActor<Cmd, Event, State> {
+class Counter extends PersistentActor<Command, Event, State> {
   readonly persistenceId = 'counter-1';
   initialState(): State { return { count: 0 }; }
   onEvent(s: State, e: Event): State {
@@ -185,7 +194,7 @@ class Counter extends PersistentActor<Cmd, Event, State> {
       ? { count: s.count + 1 }
       : { count: s.count - 1 };
   }
-  onCommand(_state: State, cmd: Cmd): void {
+  onCommand(_state: State, cmd: Command): void {
     this.persist({
       kind: cmd.kind === 'inc' ? 'incremented' : 'decremented',
     });
@@ -210,7 +219,7 @@ import { Cluster } from 'actor-ts';
 const { system, cluster } = await Cluster.bootstrap({ name: 'app' });
 
 const cartRegion = cluster.sharding.start('cart', CartActor, {
-  extractEntityId: (msg: CartCmd) => msg.entityId,
+  extractEntityId: (msg: CartCommand) => msg.entityId,
 });
 
 cartRegion.tell({ entityId: 'user-42', kind: 'add', sku: 'book-1' });
@@ -272,9 +281,9 @@ Issues and feature requests live on
 
 <a href="https://www.star-history.com/?repos=pathosDev%2Factor-ts&type=date&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=pathosDev/actor-ts&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=pathosDev/actor-ts&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=pathosDev/actor-ts&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=pathosDev/actor-ts&type=date&theme=dark&legend=top-left&sealed_token=iyC35jF1VENIymplLwZ8Cn2oNYPgr_OxQBWJfsv8Zl0v59Pkk9eKbLf1Gy2VWG_U3xuXb_xL0AAo5KD6Zz9p3izijymg6rD60G6pDZhdGrWgybY6vbLayqijq5n-qYdEyva0SkJ1TCWfrl0uSXCU5LyUa0I_Hz4wbgyrFObbeBFFxzRDMxrNVlNH6f_6" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=pathosDev/actor-ts&type=date&legend=top-left&sealed_token=iyC35jF1VENIymplLwZ8Cn2oNYPgr_OxQBWJfsv8Zl0v59Pkk9eKbLf1Gy2VWG_U3xuXb_xL0AAo5KD6Zz9p3izijymg6rD60G6pDZhdGrWgybY6vbLayqijq5n-qYdEyva0SkJ1TCWfrl0uSXCU5LyUa0I_Hz4wbgyrFObbeBFFxzRDMxrNVlNH6f_6" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=pathosDev/actor-ts&type=date&legend=top-left&sealed_token=iyC35jF1VENIymplLwZ8Cn2oNYPgr_OxQBWJfsv8Zl0v59Pkk9eKbLf1Gy2VWG_U3xuXb_xL0AAo5KD6Zz9p3izijymg6rD60G6pDZhdGrWgybY6vbLayqijq5n-qYdEyva0SkJ1TCWfrl0uSXCU5LyUa0I_Hz4wbgyrFObbeBFFxzRDMxrNVlNH6f_6" />
  </picture>
 </a>
 

package/dist/Actor.d.ts

@@ -13,14 +13,14 @@ import type { Option } from './util/Option.js';
  * onReceive is never invoked concurrently for the same actor.  If onReceive
  * returns a Promise, the runtime awaits it before starting the next message.
  */
-export declare abstract class Actor<TMsg = unknown> {
+export declare abstract class Actor<TMessage = unknown> {
     /** @internal — injected by ActorCell at construction time. */
     private _context;
     /** @internal */
-    _attach(context: ActorContext<TMsg>): void;
+    _attach(context: ActorContext<TMessage>): void;
     /** Runtime context. Only valid after the actor has been started. */
-    protected get context(): ActorContext<TMsg>;
-    protected get self(): ActorRef<TMsg>;
+    protected get context(): ActorContext<TMessage>;
+    protected get self(): ActorRef<TMessage>;
     protected get sender(): Option<ActorRef>;
     protected get system(): ActorSystem;
     protected get log(): Logger;
@@ -28,7 +28,7 @@ export declare abstract class Actor<TMsg = unknown> {
      * Main message handler.  Receives each envelope dequeued from the mailbox.
      * A thrown error (sync or async) is caught by the supervisor.
      */
-    abstract onReceive(message: TMsg): void | Promise<void>;
+    abstract onReceive(message: TMessage): void | Promise<void>;
     /** Called after construction and before the first message is processed. */
     preStart(): void | Promise<void>;
     /** Called after the actor has been terminated. Children are already stopped. */
@@ -37,7 +37,7 @@ export declare abstract class Actor<TMsg = unknown> {
      * Called before a restart, on the instance about to be thrown away.
      * The default stops children and then calls postStop().
      */
-    preRestart(_reason: Error, _message?: TMsg): void | Promise<void>;
+    preRestart(_reason: Error, _message?: TMessage): void | Promise<void>;
     /** Called on the fresh instance after a restart.  Default: call preStart(). */
     postRestart(_reason: Error): void | Promise<void>;
     /**

package/dist/Actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Actor.d.ts","sourceRoot":"","sources":["../src/Actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAmB,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;;;;;GAQG;AACH,8BAAsB,KAAK,CAAC,IAAI,GAAG,OAAO;IACxC,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAsB;IAEtC,gBAAgB;IAChB,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,IAAI;IAI1C,oEAAoE;IACpE,SAAS,KAAK,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,CAA0B;IAErE,SAAS,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,CAA+B;IACnE,SAAS,KAAK,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAiC;IACzE,SAAS,KAAK,MAAM,IAAI,WAAW,CAAiC;IACpE,SAAS,KAAK,GAAG,IAAI,MAAM,CAA8B;IAEzD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvD,2EAA2E;IAC3E,QAAQ,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhC,gFAAgF;IAChF,QAAQ,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhC;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,+EAA+E;IAC/E,WAAW,CAAC,OAAO,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;;OAGG;IACH,kBAAkB,IAAI,kBAAkB;CACzC"}
+{"version":3,"file":"Actor.d.ts","sourceRoot":"","sources":["../src/Actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAmB,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;;;;;GAQG;AACH,8BAAsB,KAAK,CAAC,QAAQ,GAAG,OAAO;IAC5C,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAA0B;IAE1C,gBAAgB;IAChB,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI;IAI9C,oEAAoE;IACpE,SAAS,KAAK,OAAO,IAAI,YAAY,CAAC,QAAQ,CAAC,CAA0B;IAEzE,SAAS,KAAK,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAA+B;IACvE,SAAS,KAAK,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAiC;IACzE,SAAS,KAAK,MAAM,IAAI,WAAW,CAAiC;IACpE,SAAS,KAAK,GAAG,IAAI,MAAM,CAA8B;IAEzD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3D,2EAA2E;IAC3E,QAAQ,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhC,gFAAgF;IAChF,QAAQ,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhC;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE,+EAA+E;IAC/E,WAAW,CAAC,OAAO,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;;OAGG;IACH,kBAAkB,IAAI,kBAAkB;CACzC"}

package/dist/Actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"Actor.js","sourceRoot":"","sources":["../src/Actor.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAsB,MAAM,kBAAkB,CAAC;AAGvE;;;;;;;;GAQG;AACH,MAAM,OAAgB,KAAK;IACzB,8DAA8D;IACtD,QAAQ,CAAsB;IAEtC,gBAAgB;IAChB,OAAO,CAAC,OAA2B;QACjC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,oEAAoE;IACpE,IAAc,OAAO,KAAyB,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAErE,IAAc,IAAI,KAAqB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACnE,IAAc,MAAM,KAAuB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,IAAc,MAAM,KAAkB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACpE,IAAc,GAAG,KAAa,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAQzD,2EAA2E;IAC3E,QAAQ,KAA0B,CAAC;IAEnC,gFAAgF;IAChF,QAAQ,KAA0B,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,OAAc,EAAE,QAAe;QACxC,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzB,CAAC;IAED,+EAA+E;IAC/E,WAAW,CAAC,OAAc;QACxB,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,kBAAkB,KAAyB,OAAO,eAAe,CAAC,CAAC,CAAC;CACrE"}
+{"version":3,"file":"Actor.js","sourceRoot":"","sources":["../src/Actor.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAsB,MAAM,kBAAkB,CAAC;AAGvE;;;;;;;;GAQG;AACH,MAAM,OAAgB,KAAK;IACzB,8DAA8D;IACtD,QAAQ,CAA0B;IAE1C,gBAAgB;IAChB,OAAO,CAAC,OAA+B;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,oEAAoE;IACpE,IAAc,OAAO,KAA6B,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEzE,IAAc,IAAI,KAAyB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACvE,IAAc,MAAM,KAAuB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,IAAc,MAAM,KAAkB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACpE,IAAc,GAAG,KAAa,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAQzD,2EAA2E;IAC3E,QAAQ,KAA0B,CAAC;IAEnC,gFAAgF;IAChF,QAAQ,KAA0B,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,OAAc,EAAE,QAAmB;QAC5C,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzB,CAAC;IAED,+EAA+E;IAC/E,WAAW,CAAC,OAAc;QACxB,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,kBAAkB,KAAyB,OAAO,eAAe,CAAC,CAAC,CAAC;CACrE"}

package/dist/ActorContext.d.ts

@@ -10,9 +10,9 @@ export type Receive<T> = (message: T) => void | Promise<void>;
  * Runtime API given to every Actor.  Access through `this.context` inside
  * an Actor subclass.
  */
-export interface ActorContext<TMsg = unknown> {
+export interface ActorContext<TMessage = unknown> {
     /** A reference to this actor. */
-    readonly self: ActorRef<TMsg>;
+    readonly self: ActorRef<TMessage>;
     /** The ActorPath of this actor. */
     readonly path: ActorPath;
     /** The sender of the message currently being processed, or `None`. */
@@ -70,7 +70,7 @@ export interface ActorContext<TMsg = unknown> {
      * Replace the current behaviour.  When `discardOld` is false, the previous
      * behaviour is pushed onto a stack and can be restored via unbecome().
      */
-    become(behavior: Receive<TMsg>, discardOld?: boolean): void;
+    become(behavior: Receive<TMessage>, discardOld?: boolean): void;
     /** Pop the behaviour stack, restoring the previous behaviour. */
     unbecome(): void;
     /**
@@ -97,7 +97,7 @@ export interface ActorContext<TMsg = unknown> {
      * Per-actor scheduling facade.  Timers are identified by user-supplied
      * string keys and are automatically cancelled when the actor stops.
      */
-    readonly timers: TimerScheduler<TMsg>;
+    readonly timers: TimerScheduler<TMessage>;
     /**
      * Throttle this actor's user-message processing to a token-bucket
      * rate (#83).  Every dequeue from the user mailbox consumes one
@@ -148,11 +148,11 @@ export interface ThrottleOptions {
  * Actor-scoped scheduler.  A fresh `startSingleTimer`/`startTimerWithFixedDelay`
  * call with the same key replaces any existing timer under that key.
  */
-export interface TimerScheduler<TMsg = unknown> {
+export interface TimerScheduler<TMessage = unknown> {
     /** Fire `message` once after `delayMs`. */
-    startSingleTimer(key: string, message: TMsg, delayMs: number): void;
+    startSingleTimer(key: string, message: TMessage, delayMs: number): void;
     /** Fire `message` every `intervalMs`, optionally preceded by `initialDelayMs`. */
-    startTimerWithFixedDelay(key: string, message: TMsg, intervalMs: number, initialDelayMs?: number): void;
+    startTimerWithFixedDelay(key: string, message: TMessage, intervalMs: number, initialDelayMs?: number): void;
     /** Cancel a specific timer.  Returns true if a timer was actually running. */
     cancel(key: string): boolean;
     /** Cancel every timer this actor has started. */

package/dist/ActorContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActorContext.d.ts","sourceRoot":"","sources":["../src/ActorContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ActorContext.d.ts","sourceRoot":"","sources":["../src/ActorContext.ts"],"names":[],"mappings":"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"}

package/dist/ActorPath.js

@@ -20,10 +20,10 @@ export class ActorPath {
     /** All path segments from root to this path (including root). */
     elements() {
         const out = [];
-        let p = this;
-        while (p) {
-            out.unshift(p.name);
-            p = p.parent;
+        let current = this;
+        while (current) {
+            out.unshift(current.name);
+            current = current.parent;
         }
         return out;
     }
@@ -33,11 +33,11 @@ export class ActorPath {
     }
     /** True if this path is an ancestor of other. */
     isAncestorOf(other) {
-        let p = other.parent;
-        while (p) {
-            if (p.equals(this))
+        let ancestor = other.parent;
+        while (ancestor) {
+            if (ancestor.equals(this))
                 return true;
-            p = p.parent;
+            ancestor = ancestor.parent;
         }
         return false;
     }

package/dist/ActorPath.js.map

@@ -1 +1 @@
-{"version":3,"file":"ActorPath.js","sourceRoot":"","sources":["../src/ActorPath.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,SAAS;IAEF;IACA;IACA;IACA;IAJlB,YACkB,IAAY,EACZ,SAA2B,IAAI,EAC/B,aAAqB,SAAS,EAC9B,MAAc,CAAC;QAHf,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAyB;QAC/B,eAAU,GAAV,UAAU,CAAoB;QAC9B,QAAG,GAAH,GAAG,CAAY;IAC9B,CAAC;IAEJ,0CAA0C;IAC1C,KAAK,CAAC,IAAY,EAAE,MAAc,CAAC;QACjC,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACzD,CAAC;IAED,iEAAiE;IACjE,QAAQ;QACN,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,IAAI,CAAC,GAAqB,IAAI,CAAC;QAC/B,OAAO,CAAC,EAAE,CAAC;YACT,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACpB,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;QACf,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,iDAAiD;IACjD,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,iDAAiD;IACjD,YAAY,CAAC,KAAgB;QAC3B,IAAI,CAAC,GAAqB,KAAK,CAAC,MAAM,CAAC;QACvC,OAAO,CAAC,EAAE,CAAC;YACT,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YAChC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;QACf,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,CAAC,KAAgB;QACrB,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC9C,CAAC;IAED,yDAAyD;IACzD,QAAQ;QACN,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjC,8EAA8E;QAC9E,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,cAAc,IAAI,CAAC,UAAU,GAAG,CAAC;QAClE,OAAO,cAAc,IAAI,CAAC,UAAU,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACxE,CAAC;CACF"}
+{"version":3,"file":"ActorPath.js","sourceRoot":"","sources":["../src/ActorPath.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,SAAS;IAEF;IACA;IACA;IACA;IAJlB,YACkB,IAAY,EACZ,SAA2B,IAAI,EAC/B,aAAqB,SAAS,EAC9B,MAAc,CAAC;QAHf,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAyB;QAC/B,eAAU,GAAV,UAAU,CAAoB;QAC9B,QAAG,GAAH,GAAG,CAAY;IAC9B,CAAC;IAEJ,0CAA0C;IAC1C,KAAK,CAAC,IAAY,EAAE,MAAc,CAAC;QACjC,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACzD,CAAC;IAED,iEAAiE;IACjE,QAAQ;QACN,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,IAAI,OAAO,GAAqB,IAAI,CAAC;QACrC,OAAO,OAAO,EAAE,CAAC;YACf,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1B,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC3B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,iDAAiD;IACjD,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,iDAAiD;IACjD,YAAY,CAAC,KAAgB;QAC3B,IAAI,QAAQ,GAAqB,KAAK,CAAC,MAAM,CAAC;QAC9C,OAAO,QAAQ,EAAE,CAAC;YAChB,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YACvC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC7B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,CAAC,KAAgB;QACrB,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC9C,CAAC;IAED,yDAAyD;IACzD,QAAQ;QACN,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjC,8EAA8E;QAC9E,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,cAAc,IAAI,CAAC,UAAU,GAAG,CAAC;QAClE,OAAO,cAAc,IAAI,CAAC,UAAU,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACxE,CAAC;CACF"}