effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/eventlog/EventGroup.ts

@@ -1,18 +1,26 @@
 /**
- * Defines typed groups of event-log event definitions.
+ * Describes typed event groups for the unstable event-log system.
  *
- * Event groups describe the events that belong to one event-log domain, such as
- * commands for an aggregate, application workflow, or synced local store. Start
- * from `empty`, add event tags with their payload, success, and error schemas,
- * then use the group with `EventLog.group` to provide the handlers that execute
- * and commit those events.
+ * An `EventGroup` is an immutable catalog of event definitions that belong to one
+ * domain, such as an aggregate, workflow, or synced store. Start with `empty`,
+ * add tags with their payload, success, and error schemas, and then pass the
+ * resulting group to `EventLog.schema` for clients and `EventLog.group` for
+ * server-side handlers. The group itself does not execute writes; it preserves
+ * the event tags and schema services that the event-log runtime uses later.
  *
- * Each event tag becomes the key in the group's events record, so tags should be
- * unique within a group. The `primaryKey` function is part of the event
- * definition and should derive the stable partition key from the decoded
- * payload. Omitted schemas default to `Schema.Void` for payload and success, and
- * `Schema.Never` for errors; use `addError` when every event in the group shares
- * an additional error schema.
+ * **Mental model**
+ *
+ * Each tag in a group is the durable name of an event. Its `primaryKey` function
+ * derives the entity or aggregate partition from the decoded payload, while its
+ * schemas describe the bytes written to the journal and the typed result returned
+ * by the handler.
+ *
+ * **Gotchas**
+ *
+ * Keep tags unique within a group and stable once entries have been persisted.
+ * Omitted schemas default to `Schema.Void` for payload and success and
+ * `Schema.Never` for errors. Use `addError` only for errors shared by every
+ * event in the group.
  *
  * @since 4.0.0
  */
@@ -52,7 +60,7 @@ export const isEventGroup = (u: unknown): u is Any => Predicate.hasProperty(u, T
  *
  * **When to use**
  *
- * Build groups from `empty.add(...)`, then provide implementations for the events
+ * Use when build groups from `empty.add(...)`, then provide implementations for the events
  * with `EventLog.group`.
  *
  * @category models
@@ -191,7 +199,7 @@ const makeProto = <
  *
  * **When to use**
  *
- * Call `.add(...)` to add event definitions and build a typed `EventGroup`.
+ * Use when call `.add(...)` to add event definitions and build a typed `EventGroup`.
  *
  * @category constructors
  * @since 4.0.0

package/src/unstable/eventlog/EventJournal.ts

@@ -1,18 +1,35 @@
 /**
- * Low-level storage and replay primitives for the unstable event-log system.
- *
- * An `EventJournal` records committed event entries, exposes them for replay,
- * and tracks the replication state needed to exchange entries with remote
- * journals. It is the persistence boundary used by higher-level event-log
- * schemas and handlers for workflows such as rebuilding projections, syncing
- * offline clients, importing remote changes, and coordinating per-store writes.
- *
- * Journal entries are ordered by their UUID v7 entry ids, so persistence and
- * replay code should account for clock-derived ordering when detecting
- * conflicts. Payloads are stored as encoded bytes and must remain compatible
- * with the event schemas that will decode them later. Remote writes may include
- * duplicate entries, compaction can rewrite the set of imported entries before
- * effects run, and replay handlers should be prepared for entries that arrive
+ * Persistence boundary for unstable event-log entries and replication state.
+ *
+ * `EventJournal` stores committed entries, exposes them for replay, publishes
+ * local changes, and records the remote metadata needed to exchange entries
+ * with other journals. Higher-level event-log schemas and handlers build on
+ * this service when rebuilding projections, syncing offline clients, importing
+ * remote changes, or coordinating writes per store.
+ *
+ * **Mental model**
+ *
+ * A local write creates a UUID v7 entry id, runs the caller-provided effect,
+ * and commits the entry only when that effect succeeds. Remote writes first
+ * split duplicate entries from new entries, optionally compact the new remote
+ * history, run replay effects with conflict entries, and then persist the
+ * imported entries. Remote metadata tracks the last known sequence number and
+ * which local entries each remote still needs.
+ *
+ * **Common tasks**
+ *
+ * Use `entries` to replay the full journal, `changes` to subscribe to local
+ * writes, `writeFromRemote` to import replicated entries, and
+ * `withRemoteUncommited` to send entries a remote has not yet acknowledged. Use
+ * `withLock` when multiple event-log operations must serialize work for the
+ * same store id.
+ *
+ * **Gotchas**
+ *
+ * Entry ordering comes from UUID v7 timestamps, so conflict detection is tied
+ * to clock-derived ids. Payloads are opaque encoded bytes and must remain
+ * compatible with the schemas that decode historical entries. Remote imports
+ * can include duplicates, and replay handlers should expect entries that arrive
  * after local changes for the same event and primary key.
  *
  * @since 4.0.0

package/src/unstable/eventlog/EventLog.ts

@@ -1,19 +1,33 @@
 /**
- * Typed event-log runtime for appending domain events to an `EventJournal` and
- * replaying entries from remote replicas.
- *
- * This module is used to define event-log schemas, register handlers for event
- * groups, build clients that write typed payloads, and connect local journals to
- * authenticated remote sessions. It is useful for event-sourced state,
- * offline-first synchronization, audit trails, and replicated stores where each
- * event must run its handler before the entry is committed.
- *
- * Local appends encode payloads with the event schema and commit only after the
- * registered handler succeeds. Remote replay decodes entries with the same
- * schema, passes duplicate or conflicting entries to handlers, may run
- * compaction before committing, and invalidates registered reactivity keys.
- * Remote sessions depend on the current `Identity` and `CurrentStoreId`, so use
- * stable values when multiple replicas or stores must share the same log.
+ * High-level runtime for writing typed event-log events and replaying replicated
+ * journal entries.
+ *
+ * This module connects event definitions, handler layers, an `EventJournal`, and
+ * optional remote replicas. Applications define groups with `EventGroup`, build
+ * an `EventLogSchema`, register handlers with `group`, and obtain a typed client
+ * with `makeClient`; the `EventLog` service then encodes payloads, runs the
+ * matching handler, and commits the entry only after the handler succeeds.
+ *
+ * **Mental model**
+ *
+ * Local writes are command-like: encode the payload, derive the primary key, run
+ * the handler, then commit the journal entry. Remote replay is journal-like:
+ * entries are decoded with the same schemas, conflict entries are supplied to
+ * handlers, optional compaction can rewrite imported entries, and reactivity keys
+ * are invalidated after successful handling.
+ *
+ * **Common tasks**
+ *
+ * Use `schema` to combine event groups, `layer` or `layerEventLog` to install
+ * the runtime, `group` to register required handlers, `groupCompaction` to
+ * collapse remote history before replay, and `groupReactivity` to invalidate
+ * projections keyed by event primary key.
+ *
+ * **Gotchas**
+ *
+ * Remote synchronization depends on the current `Identity` and `CurrentStoreId`.
+ * Keep both stable for replicas that should share a log, and provide handlers for
+ * every event tag before writing through a client.
  *
  * @since 4.0.0
  */
@@ -961,6 +975,29 @@ export const layerEventLog: Layer.Layer<EventLog | Registry, never, EventJournal
 /**
  * Combines event-group handler layers with the `EventLog` runtime for a schema.
  *
+ * **When to use**
+ *
+ * Use when an application has an `EventLogSchema` and event-group handler layer
+ * and wants one layer that installs the shared `EventLog` runtime and registers
+ * the handlers for typed writes.
+ *
+ * **Details**
+ *
+ * The supplied handler layer is provided with `layerEventLog`. The returned
+ * layer provides `EventLog | Registry`, preserves the handler layer's error
+ * type, and still requires its remaining services plus `EventJournal` and
+ * `Identity`.
+ *
+ * **Gotchas**
+ *
+ * The schema argument does not register handlers by itself. Handler registration
+ * comes from the supplied layer, and writing an event without a registered
+ * handler dies with `Event handler not found for: "<tag>"`.
+ *
+ * @see {@link schema} for creating the schema argument from event groups
+ * @see {@link group} for building the handler layer consumed by this layer
+ * @see {@link layerEventLog} for installing the runtime and registry without combining a handler layer
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogMessage.ts

@@ -1,17 +1,26 @@
 /**
- * Defines the wire messages used by event-log remotes to authenticate clients,
- * write event batches, and stream changes back to replicas.
+ * Defines the remote event-log protocol messages and RPC group.
  *
- * This module is the protocol boundary between `EventLogRemote` clients and
- * event-log servers: it provides schemas for store identifiers, protocol
- * errors, session handshake payloads, authenticated RPCs, and the msgpack
- * payloads used to carry encrypted or plaintext journal entries.
+ * This module is the shared boundary between `EventLogRemote` clients and
+ * event-log servers. It provides branded store ids, structured protocol errors,
+ * the hello/authenticate session handshake, authenticated write and changes
+ * RPCs, and msgpack payloads for encrypted or plaintext journal entries.
  *
- * Event batches are serialized as binary payloads before transport. Small
- * payloads can be sent as a single frame, while larger payloads are split into
- * `ChunkedMessage` parts and must be reassembled by message id after every part
- * has arrived. Transports should preserve `Uint8Array` bytes exactly and avoid
- * treating msgpack data as text.
+ * **Mental model**
+ *
+ * A remote session starts with `HelloRpc`, then proves control of the client's
+ * signing key with `AuthenticateRpc`. After authentication, writes flow from the
+ * client to the server as encoded entry batches, and `ChangesRpc` streams
+ * encoded remote entries back to replicas from a requested sequence number. The
+ * `EventLogAuthentication` middleware marks the RPCs that require an
+ * authenticated event-log identity.
+ *
+ * **Gotchas**
+ *
+ * Entry batches are binary payloads. Small payloads travel as `SingleMessage`,
+ * while larger payloads are split into `ChunkedMessage` parts and reassembled by
+ * message id after every part arrives. Transports must preserve `Uint8Array`
+ * bytes exactly; do not treat msgpack payloads as text or JSON.
  *
  * @since 4.0.0
  */
@@ -161,7 +170,7 @@ export class SingleMessage
  *
  * **When to use**
  *
- * Use `split` to divide data into chunks and `join` to reassemble all chunks with
+ * Use to divide data into chunks and `join` to reassemble all chunks with
  * the same id once every part has arrived.
  *
  * @category protocol

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.
+ * Builds server-side RPC handlers for the event-log remote protocol.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * **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
  */

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
  */

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
  */
@@ -653,6 +675,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
  */
@@ -731,6 +774,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
  */

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
  */