FcqrsModule

Build a SQLite/etc. Connection from a raw connection string (ShortString hidden).

Create the actor system from plain values (cluster name as a string).

A fresh correlation id (UUID v7).

A correlation id from a string you already have (a request id, a trace id). Rejects '~': the separator FCQRS builds saga entity names and pub-sub topics from, so a CID containing one is parsed back wrong and leaves the saga permanently deaf. `newCid` needs no such check — a UUID has none.

An aggregate id from a string (e.g. a document/user key). Any non-blank id works: the shard names entity actors Uri.EscapeDataString(entityId), so characters Akka actor names would reject directly (spaces, %) are escaped before they reach an actor path.

Register an aggregate and return its typed handle. Calling this IS the registration (it initializes the sharding region).

Register an aggregate immediately and return a reusable application handler. The returned function takes filter, cid, aggregate id, and command, in that order, and sends when its Async is executed. It returns EventDetails from the first matching reply; it does not wait for a projection or wire saga starters. Use aggregate instead when the caller needs the envelope or entity-ref factory.

Send only if the aggregate's persisted version equals expectedVersion (initially zero). A mismatch raises AggregateVersionConflictException before the domain handler or filter runs. The check and handler run in the same actor turn. Deferred replies do not advance the version; a persisted batch advances it once per event. Stashed commands and RunAsync result commands recheck the original expected version. This is not command deduplication or a projection wait. Cancellation or timeout after dispatch does not undo a write. A caller-built PublishEvent reply must retain the incoming command's Id and CorrelationId.

Register an aggregate whose `decide` uses `dispatch` (the RunAsync effect), supplying the runner that turns an effect DESCRIPTION into a command sent back to the aggregate. `decide` stays pure; the oracle or side effect lives only here. The runner MUST be total (wrap it with `total` so an oracle error becomes a command, never an escaping exception). See `EventAction.RunAsync` for the ephemeral contract.

Register a saga and return its handle. The originator-event type is inferred from `def.StartOn`, so there are no type arguments to supply: `Fcqrs.saga api def`.

Wire every registered saga into one saga-starter (or the empty starter if none). Call after the aggregates + sagas are registered.

Register stable journal names for payload types (see JournalTypes): Fcqrs.journalTypes [ journalType<Document.Event> "doc.event"; ... ] Call before the actor system writes anything.

Register a deterministic, one-to-one historical event conversion for this actor system. Call after creating the actor API and before registering any aggregate, saga, or projection. Chains follow the envelope's declared payload type; duplicate sources and cycles are rejected. FCQRS converts journal events during recovery and projection reads, preserving every envelope field except EventDetails. Stored events, live messages, and application-owned snapshot state remain unchanged. Historical payloads must still deserialize before conversion can run. Converters may run concurrently across consumers and must be thread-safe.

Register the read-model projection and return the subscription stream.

Starts a transactional projection with journal-wide CatchUpAsync support. Write the read model through the supplied connection and transaction; FCQRS commits those updates and contiguous per-persistence-ID progress together. Retain unprocessed journal history. Events have per-persistence-ID ordering, with no ordering between different persistence IDs. See TransactionalProjectionOptions.

Read-your-writes in one call: subscribe on the CID BEFORE sending, send, then await the projection ONLY if the delivered ack was journaled. A deferred (rejection-style) ack never reaches the journal, so a naive await would hang until timeout. The subscribe-before-send ordering is what makes the wait race-free; owning it here means callers cannot get it backwards. Awaits exactly ONE projected event: a batch persist (PersistAllEvents) caller should Subscribe with an explicit take instead. Envelopes without the delivery stamp (pre-stamp FCQRS) are treated as journaled. The projection wait is bounded by `akka.fcqrs.command-timeout` (default 30s, bare number = seconds): a projection that suppresses or filters out the matching notification raises TimeoutException instead of hanging the caller forever.