effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/eventlog/EventLogServer.ts

@@ -1,19 +1,33 @@
 /**
- * Server-side RPC handlers for accepting remote event-log writes and streaming
- * changes back to authenticated clients.
- *
- * This module is the protocol glue used by concrete event-log servers: it
- * performs the hello / authenticate challenge flow, attaches the authenticated
- * `EventLog.Identity` to subsequent RPC requests, reassembles chunked writes,
- * and chunks large change payloads before they are sent to clients. It is useful
- * when exposing an event-log replica over HTTP-backed RPC, for example to sync
- * browser, edge, or service replicas with a central journal.
- *
- * The authentication state is tied to the RPC client session annotations, so the
- * transport must preserve a stable client session between `Hello`,
- * `Authenticate`, writes, and change streams. Deployments should run the endpoint
- * over TLS, avoid exposing unauthenticated write or changes routes, and persist
- * session-auth key bindings with the same trust boundary as the event-log data.
+ * Builds server-side RPC handlers for the event-log remote protocol.
+ *
+ * Concrete transports use this module when exposing a journal to remote replicas.
+ * The handlers run the hello / authenticate challenge flow, attach the
+ * authenticated `EventLog.Identity` to later requests, accept single or chunked
+ * writes, and stream changes back as single or chunked messages.
+ *
+ * **Mental model**
+ *
+ * A client first calls `Hello` to obtain a challenge tied to the RPC client
+ * session, then calls `Authenticate` to bind its public key to that session.
+ * Subsequent writes and change streams rely on the client annotations populated
+ * during authentication, and `layerAuthMiddleware` enforces that an identity is
+ * present.
+ *
+ * **Common tasks**
+ *
+ * Use `layerRpcHandlers` with callbacks for session-auth key binding, applying
+ * incoming write bytes, and streaming encoded changes. Merge the resulting layer
+ * with an RPC server transport that preserves client session annotations across
+ * calls.
+ *
+ * **Gotchas**
+ *
+ * Session annotations are transport state, so `Hello`, `Authenticate`,
+ * `WriteSingle`, `WriteChunked`, and `Changes` must share a stable client
+ * session. Run the endpoint over TLS and store auth bindings with the same trust
+ * boundary as the event-log data. Chunking is only framing; the supplied
+ * callbacks still work with complete encoded payload bytes.
  *
  * @since 4.0.0
  */
@@ -215,10 +229,15 @@ export const layerRpcHandlers = (options: {
   )
 
 /**
- * Client annotation storing partial `ChunkedMessage` data while chunked writes are
+ * Annotation that stores partial `ChunkedMessage` data while chunked writes are
  * being reassembled.
  *
- * @category ChunkedMessage state
+ * **When to use**
+ *
+ * Use to keep per-client chunk assembly state while handling chunked event-log
+ * writes.
+ *
+ * @category chunked message state
  * @since 4.0.0
  */
 export class ChunkedMessageState extends Context.Reference<

package/src/unstable/eventlog/EventLogServerEncrypted.ts

@@ -101,6 +101,23 @@ export const layerRpcHandlers = Layer.unwrap(Effect.gen(function*() {
  * Provides an encrypted event-log RPC server using `EventLogRemoteRpcs` and the
  * encrypted server RPC handlers.
  *
+ * **When to use**
+ *
+ * Use to expose the encrypted event-log RPC server when you already have an
+ * `RpcServer.Protocol` and want clients using encrypted `EventLogRemote`
+ * replication to synchronize through server-side `Storage`.
+ *
+ * **Details**
+ *
+ * This layer installs `EventLogRemoteRpcs` on the provided RPC server protocol
+ * and wires those RPCs to `layerRpcHandlers`. Encrypted entries, session
+ * authentication bindings, remote ids, and change streams are delegated to
+ * `Storage`.
+ *
+ * @see {@link layerRpcHandlers} for the encrypted handler layer without installing an RPC server protocol
+ * @see {@link Storage} for the storage service required by this layer
+ * @see {@link layerStorageMemory} for the process-local in-memory storage layer
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -109,7 +126,7 @@ export const layer: Layer.Layer<never, never, RpcServer.Protocol | Storage> = Rp
 )
 
 /**
- * Encrypted entry representation persisted by the encrypted event-log server.
+ * Schema for encrypted entries persisted by the encrypted event-log server.
  *
  * @category storage
  * @since 4.0.0
@@ -132,7 +149,12 @@ export class PersistedEntry extends Schema.Class<PersistedEntry>(
 }
 
 /**
- * Storage service used by the encrypted event-log server.
+ * Defines the backing store service used by the encrypted event-log server.
+ *
+ * **When to use**
+ *
+ * Use to provide durable encrypted event-log persistence for an encrypted
+ * event-log server layer.
  *
  * **Details**
  *

package/src/unstable/eventlog/EventLogServerUnencrypted.ts

@@ -1,19 +1,41 @@
 /**
- * Server implementation for event logs whose entries are persisted and streamed
- * in plaintext.
- *
- * This module is useful for trusted deployments, local development, tests, and
- * server-side event sources that need typed event handlers, conflict detection,
- * compaction, and RPC change streams without an encryption layer. It includes
- * services for mapping client store ids to server stores, authorizing reads and
- * writes, storing remote entries, and binding session authentication keys.
- *
- * Because payloads and journals are unencrypted, storage must be protected by
- * the surrounding infrastructure. Session authentication bindings are part of
- * the storage contract and must be persisted by durable implementations so a
- * public key cannot silently bind to a different signing key after a restart.
- * The provided memory storage is process-local and intended for ephemeral
- * servers, tests, or examples rather than durable multi-process use.
+ * Plaintext server implementation for the event-log remote protocol.
+ *
+ * The module accepts unencrypted event batches from remote clients, runs the
+ * registered event handlers, persists journal entries through `Storage`, and
+ * streams compacted backlog entries plus live changes through the shared
+ * `EventLogServer` RPC protocol. It is intended for trusted deployments, local
+ * development, tests, and server-side producers that want typed event handling
+ * and conflict detection without an encryption layer.
+ *
+ * **Mental model**
+ *
+ * `StoreMapping` resolves the client-requested store id to the server store,
+ * `EventLogServerAuthorization` gates reads, writes, and identities, and
+ * `Storage` is the durable boundary for remote entries and session
+ * authentication bindings. Remote writes are sorted, checked for duplicates and
+ * conflicts, passed to event handlers inside the storage transaction, and then
+ * committed as remote entries. Change streams replay the requested backlog,
+ * apply registered compactors when possible, and then continue with live
+ * entries.
+ *
+ * **Common tasks**
+ *
+ * Use `layer` for a complete RPC server, `layerNoRpcServer` when an
+ * `RpcServer.Protocol` is installed elsewhere, and `layerServer` plus
+ * `makeWrite` for server-side plaintext writes that do not enter through RPC.
+ * `layerStoreMappingStatic` and `layerStorageMemory` are small local defaults;
+ * production systems usually provide their own mapping, authorization, and
+ * durable storage services.
+ *
+ * **Gotchas**
+ *
+ * Payloads, journals, and change streams are plaintext, so protect the backing
+ * store and transport with the surrounding infrastructure. Durable storage must
+ * preserve session authentication bindings across restarts so a public key
+ * cannot silently bind to a different signing key. The memory storage is
+ * process-local and volatile; it is useful for tests and examples, not for
+ * multi-process or restart-safe servers.
  *
  * @since 4.0.0
  */
@@ -49,10 +71,15 @@ import {
 import * as EventLogServer from "./EventLogServer.ts"
 
 /**
- * Server-side service for writing plaintext event-log entries directly to
+ * Service that writes plaintext event-log entries directly to
  * unencrypted storage through registered event handlers.
  *
- * @category EventLogServerUnencrypted
+ * **When to use**
+ *
+ * Use to access or provide the server service that handles plaintext
+ * event-log writes.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class EventLogServerUnencrypted extends Context.Service<EventLogServerUnencrypted, {
@@ -255,10 +282,15 @@ export class EventLogServerAuthError extends Data.TaggedError("EventLogServerAut
 }> {}
 
 /**
- * Authorization service used by the unencrypted event-log server to validate
+ * Service that validates unencrypted event-log server
  * write access, read access, and identities.
  *
- * @category context
+ * **When to use**
+ *
+ * Use to provide authorization checks for plaintext event-log writes, reads,
+ * and identity authentication.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class EventLogServerAuthorization extends Context.Service<EventLogServerAuthorization, {
@@ -280,7 +312,12 @@ export class EventLogServerAuthorization extends Context.Service<EventLogServerA
  * Service that resolves client-requested store ids to server store ids and checks
  * whether a store exists.
  *
- * @category context
+ * **When to use**
+ *
+ * Use to map client-visible store identifiers to server storage identifiers
+ * before authorizing or serving unencrypted event-log requests.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class StoreMapping extends Context.Service<StoreMapping, {
@@ -330,7 +367,12 @@ export const layerStoreMappingStatic = (options: {
   })
 
 /**
- * Storage service used by the unencrypted event-log server.
+ * Defines the backing store service used by the unencrypted event-log server.
+ *
+ * **When to use**
+ *
+ * Use to provide durable event-log persistence for an unencrypted event-log
+ * server layer.
  *
  * **Details**
  *
@@ -457,7 +499,12 @@ const toCompactedRemoteEntries = (options: {
 }
 
 /**
- * Compacts a backlog of remote entries using the registered compactors.
+ * Runs the registered compactors over a backlog of remote entries.
+ *
+ * **When to use**
+ *
+ * Use to reduce stored remote entries before replaying them to an unencrypted
+ * event-log client.
  *
  * **Details**
  *
@@ -653,6 +700,27 @@ export const layerStorageMemory: Layer.Layer<Storage> = Layer.effect(Storage)(ma
  * Creates the `EventLogServerUnencrypted` service from the configured storage and
  * registered event handlers.
  *
+ * **When to use**
+ *
+ * Use to construct the unencrypted event-log server service directly when you
+ * already provide `Storage` and an event-log `Registry` and want to supply the
+ * service yourself.
+ *
+ * **Details**
+ *
+ * The constructed service exposes `makeWrite`, which builds a typed server-side
+ * write function from an `EventLogSchema`. Each write encodes the payload with
+ * the event schema, runs the registered handler, and persists the generated
+ * entry inside `Storage.withTransaction`.
+ *
+ * **Gotchas**
+ *
+ * The write function dies if the requested event tag is not present in the
+ * schema passed to `makeWrite`; it does not report that case as a typed failure.
+ *
+ * @see {@link makeWrite} for the accessor that retrieves the typed server-side write function from the service environment
+ * @see {@link layerServer} for the layer form that provides this service together with an event-log `Registry`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -716,6 +784,11 @@ export const make = Effect.gen(function*() {
  * Provides `EventLogServerUnencrypted` and an event-log `Registry` using the
  * configured unencrypted server `Storage`.
  *
+ * **When to use**
+ *
+ * Use to provide the unencrypted event-log server service together with the
+ * registry needed by event handlers.
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -731,6 +804,30 @@ export const layerServer: Layer.Layer<
  * Builds a full unencrypted event-log RPC server for the supplied schema and
  * event-group handler layer.
  *
+ * **When to use**
+ *
+ * Use when you need a complete unencrypted event-log RPC endpoint for a trusted
+ * deployment, local development, tests, or a server-side event source, and you
+ * can provide storage, store mapping, authorization, an RPC protocol, and the
+ * event-group handler layer.
+ *
+ * **Details**
+ *
+ * The layer installs `EventLogRemoteRpcs`, wires `layerRpcHandlers`, registers
+ * the supplied event-group handler layer, and provides `layerServer`, leaving
+ * only the required infrastructure services in the environment.
+ *
+ * **Gotchas**
+ *
+ * Entries are persisted and streamed in plaintext. Protect the backing
+ * `Storage` with the surrounding infrastructure, and use durable storage that
+ * preserves session authentication bindings when the server must survive
+ * restarts.
+ *
+ * @see {@link layerNoRpcServer} for installing the same unencrypted handlers when an `RpcServer.Protocol` is provided elsewhere
+ * @see {@link layerRpcHandlers} for wiring the unencrypted RPC handlers directly
+ * @see {@link layerServer} for constructing the server service and event-log registry without RPC handlers
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogSessionAuth.ts

@@ -1,21 +1,39 @@
 /**
- * Utilities for authenticating event log sessions with short-lived challenges
- * and Ed25519 signatures.
- *
- * This module builds and verifies the canonical payload that a remote peer signs
- * when proving control of a session signing key. It is used by event log
- * transports that need to bind a connection attempt to a remote identifier,
- * session challenge, advertised event log public key, and signing public key
- * before accepting session traffic.
- *
- * Callers are responsible for issuing fresh challenges, enforcing the challenge
- * time-to-live, and tracking whether a challenge has already been consumed. The
- * helpers here provide deterministic payload encoding, algorithm checks,
- * signature validation, and Web Crypto integration; they do not establish peer
- * trust by themselves. Trust decisions still need to compare the supplied keys
- * and remote identity against the application's authorization policy, and
- * signed payloads should be treated as bearer authentication material until the
- * challenge expires.
+ * Challenge-response helpers for authenticating event log sessions with Ed25519
+ * signatures.
+ *
+ * Event log transports use this module when a remote peer must prove control of
+ * a session signing key before sending session traffic. The signed payload binds
+ * the remote identifier, a short-lived challenge, the advertised event log public
+ * key, and the signing public key into one canonical byte sequence.
+ *
+ * **Mental model**
+ *
+ * Authentication is split into canonicalization and cryptographic proof.
+ * {@link encodeSessionAuthPayload} produces a deterministic, length-prefixed
+ * payload that includes {@link AuthPayloadContext} for domain separation.
+ * Signing proves possession of the Ed25519 private key for exactly those fields;
+ * authorization still belongs to the caller's event log policy.
+ *
+ * **Common tasks**
+ *
+ * - Generate a fresh challenge with {@link makeSessionAuthChallenge}
+ * - Sign a payload with {@link signSessionAuthPayload} or pre-encoded bytes with
+ *   {@link signSessionAuthPayloadBytes}
+ * - Verify an incoming authentication message with
+ *   {@link verifySessionAuthenticateRequest}
+ * - Encode or decode canonical bytes with {@link encodeSessionAuthPayload} and
+ *   {@link decodeSessionAuthPayload}
+ *
+ * **Gotchas**
+ *
+ * - Callers must enforce {@link SessionAuthChallengeTimeToLiveMillis} and track
+ *   whether a challenge has already been consumed
+ * - Raw Ed25519 public keys must be {@link Ed25519PublicKeyLength} bytes and
+ *   signatures must be {@link Ed25519SignatureLength} bytes
+ * - Signing private keys must be PKCS#8 bytes importable by Web Crypto
+ * - Verified signatures prove key possession, not peer trust; compare the keys
+ *   and remote identity against your authorization policy
  *
  * @since 4.0.0
  */
@@ -28,7 +46,13 @@ const textDecoder = new TextDecoder("utf-8", { fatal: true })
 const constLengthPrefixBytes = 4
 
 /**
- * Domain-separation string embedded in canonical session authentication payloads.
+ * Defines the domain-separation string embedded in canonical session
+ * authentication payloads.
+ *
+ * **When to use**
+ *
+ * Use when you need the domain-separation string used to build canonical
+ * event-log session authentication payloads.
  *
  * @category constants
  * @since 4.0.0
@@ -36,16 +60,26 @@ const constLengthPrefixBytes = 4
 export const AuthPayloadContext = "eventlog-auth-v1"
 
 /**
- * Required byte length for raw Ed25519 public keys used in session
+ * Defines the required byte length for raw Ed25519 public keys used in session
  * authentication.
  *
+ * **When to use**
+ *
+ * Use when you need to validate the byte length of raw Ed25519 public keys for
+ * session authentication.
+ *
  * @category constants
  * @since 4.0.0
  */
 export const Ed25519PublicKeyLength = 32
 
 /**
- * Required byte length for Ed25519 signatures used in session authentication.
+ * Defines the required byte length for Ed25519 signatures used in session authentication.
+ *
+ * **When to use**
+ *
+ * Use when you need to validate the byte length of Ed25519 signatures for
+ * session authentication.
  *
  * @category constants
  * @since 4.0.0
@@ -53,7 +87,12 @@ export const Ed25519PublicKeyLength = 32
 export const Ed25519SignatureLength = 64
 
 /**
- * Number of random bytes generated for a session authentication challenge.
+ * Defines the number of random bytes generated for a session authentication
+ * challenge.
+ *
+ * **When to use**
+ *
+ * Use when you need the challenge size for event-log session authentication.
  *
  * @category constants
  * @since 4.0.0
@@ -61,7 +100,13 @@ export const Ed25519SignatureLength = 64
 export const SessionAuthChallengeLength = 32
 
 /**
- * Time-to-live, in milliseconds, for a pending session authentication challenge.
+ * Defines the time-to-live, in milliseconds, for a pending session
+ * authentication challenge.
+ *
+ * **When to use**
+ *
+ * Use when you need the timeout for pending event-log session authentication
+ * challenges.
  *
  * @category constants
  * @since 4.0.0
@@ -329,8 +374,7 @@ export const decodeSessionAuthPayload = Effect.fnUntraced(
 )
 
 /**
- * Signs canonical session authentication payload bytes with an Ed25519 private
- * key.
+ * Creates a canonical session authentication signature with an Ed25519 private key.
  *
  * **Details**
  *

package/src/unstable/eventlog/SqlEventJournal.ts

@@ -1,21 +1,36 @@
 /**
  * SQL-backed persistence for the unstable event-log journal.
  *
- * This module provides an `EventJournal` implementation that stores local
- * entries and remote replication metadata in a `SqlClient` database. It is
- * useful when event-log data needs to survive process restarts, be replayed to
- * rebuild projections, or be synchronized with other journals such as remote
- * servers, peer replicas, or offline clients that later reconnect.
+ * This module implements `EventJournal` on top of a `SqlClient`. It stores event
+ * entries as encoded bytes and stores per-remote sequence metadata in separate
+ * tables, giving event-log programs a durable journal that can be replayed after
+ * restart and synchronized with remote journals.
  *
- * The adapter creates the entry and remotes tables with dialect-specific UUID,
- * binary payload, and timestamp column types, but it only performs the minimal
- * `CREATE TABLE IF NOT EXISTS` setup needed by the journal. Applications that
- * customize table names, add indexes, or evolve storage should manage those
- * migrations explicitly and keep encoded payloads compatible with the schemas
- * that will decode historical entries. Remote sequence rows are persisted
- * separately from entries, duplicate imports are ignored by primary key, and
- * conflict checks rely on event name, primary key, and the timestamp derived
- * from the entry id.
+ * **Mental model**
+ *
+ * The entry table is the append-only history used by `entries`, local writes,
+ * and remote imports. The remotes table records which entries are associated
+ * with a remote id and sequence number, so the journal can compute the next
+ * sequence to read from a remote and the local entries a remote has not yet
+ * seen. `changes` is a process-local stream of entries written by this service.
+ *
+ * **Common tasks**
+ *
+ * - Provide a persistent `EventJournal` with `layer`.
+ * - Customize entry and remotes table names when sharing a database.
+ * - Replay `entries` to rebuild projections after process restart.
+ * - Import remote entries and detect duplicates or conflicts during
+ *   synchronization.
+ *
+ * **Gotchas**
+ *
+ * Construction runs only minimal `CREATE TABLE IF NOT EXISTS` statements with
+ * dialect-specific UUID, binary, and timestamp column types; indexes,
+ * migrations, retention, and table-name changes remain application
+ * responsibilities. Payloads must stay compatible with the schemas that decode
+ * historical entries. Duplicate remote imports are ignored by primary key, and
+ * conflict lookup compares event name, primary key, and the timestamp derived
+ * from the UUID v7 entry id.
  *
  * @since 4.0.0
  */
@@ -295,6 +310,27 @@ export const make = (options?: {
  * Provides `EventJournal` using the SQL-backed implementation created by
  * `make`.
  *
+ * **When to use**
+ *
+ * Use when composing a Layer graph that should provide a persistent SQL-backed
+ * `EventJournal` from an existing `SqlClient` service.
+ *
+ * **Details**
+ *
+ * The layer delegates to `make(options)`, so the same optional `entryTable` and
+ * `remotesTable` settings are used and construction requires `SqlClient` and
+ * may fail with `SqlError`.
+ *
+ * **Gotchas**
+ *
+ * Layer construction performs the same minimal `CREATE TABLE IF NOT EXISTS`
+ * setup as `make`; manage indexes and schema migrations outside this layer when
+ * your SQL schema needs more than the built-in tables.
+ *
+ * @see {@link make} for constructing the SQL-backed service directly
+ * @see {@link EventJournal.layerMemory} for an in-memory `EventJournal` layer
+ * @see {@link EventJournal.layerIndexedDb} for an IndexedDB-backed `EventJournal` layer
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/eventlog/SqlEventLogServerEncrypted.ts

@@ -1,21 +1,45 @@
 /**
- * SQL-backed storage for encrypted event-log servers.
+ * SQL storage for encrypted event-log server state.
  *
- * This module provides the encrypted server-side storage implementation used
- * when event-log entries should be durable in a SQL database without exposing
- * plaintext event data to that database. It is intended for remote event-log
- * servers, sync services, and multi-client deployments where the server assigns
- * stable sequence numbers and broadcasts changes while clients retain control of
- * event encryption and decryption.
+ * This module provides the durable `Storage` implementation used by
+ * `EventLogServerEncrypted` when remote entries should be stored in SQL without
+ * exposing plaintext event data to the database. The server assigns stable
+ * sequence numbers and streams changes, while clients remain responsible for
+ * encrypting writes and decrypting reads with their identity key material.
  *
- * The storage creates dialect-specific tables for the server remote id and
- * session authentication bindings, then creates per-identity/store entry tables
- * using a SHA-256-derived table suffix. Those entry tables store IVs, entry ids,
- * encrypted entry bytes, and the SQL sequence used for ordering. Operators
- * should account for these dynamically created tables in migrations, backups,
- * retention policies, and table-prefix changes. Encryption key material is not
- * stored here, so rotating encryption schemes or moving data between databases
- * requires compatibility with the clients that produced the encrypted entries.
+ * **Mental model**
+ *
+ * The storage keeps a durable server remote id, one session authentication
+ * binding per public key, and one append-only entry table per public-key/store
+ * pair. Entry table names are derived from `entryTablePrefix` plus a truncated
+ * SHA-256 hash of the public key and store id. Each encrypted entry row stores
+ * the SQL sequence, initialization vector, entry id, and ciphertext bytes. A
+ * write inserts new entry ids in batches, ignores duplicates, reads back the
+ * ordered rows that are present, and publishes those rows to in-process change
+ * subscribers. A change stream first reads the SQL backlog from the requested
+ * sequence and then continues with entries published by this process.
+ *
+ * **Common tasks**
+ *
+ * - Persist an encrypted event-log server across process restarts.
+ * - Use SQL backup, replication, and transactional ordering while keeping event
+ *   payloads encrypted at rest.
+ * - Choose table names with `entryTablePrefix` and `remoteIdTable`, or tune
+ *   insert batching with `insertBatchSize`.
+ *
+ * **Gotchas**
+ *
+ * The database still contains protocol-sensitive ciphertext, IVs, entry ids,
+ * sequence numbers, public keys, and signing public key bindings, so backups and
+ * retention policies remain part of the security boundary. Live notifications
+ * are process-local after the initial SQL backlog read, so multi-process
+ * deployments need routing, reconnect/backfill behavior, or an external
+ * notification channel for writes made elsewhere. Entry tables are created
+ * dynamically, so migrations, monitoring, grants, table-prefix changes, and
+ * cleanup jobs must account for tables whose names are derived from identities
+ * and store ids. Encryption key material is not stored here; changing identity
+ * keys, encryption schemes, or data portability rules requires compatibility
+ * with the clients that produced the encrypted entries.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/SqlEventLogServerUnencrypted.ts

@@ -1,21 +1,40 @@
 /**
- * SQL-backed storage for an unencrypted event-log server.
+ * SQL-backed storage for unencrypted event-log servers.
  *
- * This module provides the persistence layer used by
+ * This module provides the durable `Storage` implementation used by
  * `EventLogServerUnencrypted` when remote entries should be stored in a SQL
- * database and streamed back to clients by store sequence. It creates and uses
+ * database and streamed back to clients by store sequence. It creates
  * dialect-specific tables for the server remote id, per-store sequence state,
- * plaintext entries, and session authentication bindings, which makes it useful
- * for durable local or service-side event-log deployments where database
- * backup, replication, and transactional ordering are desired.
+ * plaintext entries, and session authentication bindings.
+ *
+ * **Mental model**
+ *
+ * Each server store is an append-only SQL sequence. A write transaction ensures
+ * the store row exists, locks its next sequence, inserts the plaintext entry
+ * rows, advances the sequence, and publishes the committed remote entries to
+ * in-process subscribers. A change stream first reads the SQL backlog from the
+ * requested sequence, applies compaction, and then continues with entries
+ * published by this process.
+ *
+ * **Common tasks**
+ *
+ * - Persist an unencrypted event-log server across process restarts.
+ * - Use database backup, replication, and transactional ordering for remote
+ *   event-log entries.
+ * - Choose table names with `entryTablePrefix` and `remoteIdTable`, or tune
+ *   insert batching with `insertBatchSize`.
+ *
+ * **Gotchas**
  *
  * Entry payloads are intentionally written as plaintext bytes. Use this storage
  * only when the database, transport, backups, logs, and operators are trusted,
- * or when encryption is handled outside this module. Table names are derived
- * from the provided prefixes, and writes rely on SQL transactions plus
- * store-level sequence rows, so deployments should provision compatible
- * isolation/locking behavior and account for dialect-specific binary and text
- * column limits.
+ * or when encryption is handled outside this module. Live notifications are
+ * process-local after the initial SQL backlog read, so multi-process
+ * deployments need routing, reconnect/backfill behavior, or an external
+ * notification channel for writes made elsewhere. Writes also rely on SQL
+ * transactions and store-level locking, so deployments should provision
+ * compatible isolation behavior and account for dialect-specific binary and
+ * text column limits.
  *
  * @since 4.0.0
  */