effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/unstable/encoding/Msgpack.ts

@@ -1,34 +1,11 @@
 /**
- * Encode and decode MessagePack frames in Effect channels.
+ * Encodes and decodes MessagePack frames in Effect channels.
  *
  * MessagePack is a compact binary serialization format for protocols and
- * storage layers that expect bytes rather than JSON text, such as RPC
- * transports, socket streams, caches, or database columns. This module provides
- * raw channel helpers for already-agreed value shapes and schema helpers for
- * validating, transforming, or decoding domain values at the boundary.
- *
- * **Mental model**
- *
- * - Each input value passed to {@link encode} becomes one MessagePack byte array
- * - {@link decode} can receive arbitrary byte chunks; incomplete frames are
- *   buffered until enough bytes arrive
- * - Schema helpers run Effect schema encoding before packing and schema decoding
- *   after unpacking
- *
- * **Common tasks**
- *
- * - Pack values into bytes: {@link encode}
- * - Unpack byte chunks into values: {@link decode}
- * - Encode or decode domain values with schemas: {@link encodeSchema}, {@link decodeSchema}
- *
- * **Gotchas**
- *
- * - MessagePack preserves binary data better than JSON, but it is not a schema;
- *   use schema helpers when runtime validation matters
- * - Packing failures surface as {@link MsgPackError}; schema failures surface as
- *   `SchemaError` before or after the binary boundary
- * - Decoding expects complete MessagePack documents over time, not arbitrary
- *   byte payloads with out-of-band framing
+ * storage layers that expect bytes instead of JSON text, such as RPC
+ * transports, socket streams, caches, or database columns. This module includes
+ * raw channel helpers for values whose shape is already agreed on, and
+ * schema-based helpers for validating and transforming values at the boundary.
  *
  * @since 4.0.0
  */

package/src/unstable/encoding/Ndjson.ts

@@ -1,33 +1,9 @@
 /**
- * Encode and decode newline-delimited JSON streams in Effect channels.
+ * Encodes and decodes newline-delimited JSON streams in Effect channels.
  *
- * NDJSON represents a stream as one complete JSON value per line. This module
- * keeps that framing explicit for streaming boundaries: byte helpers handle
- * UTF-8 transport chunks, string helpers handle already-decoded text, and
- * schema helpers validate or transform each record at the edge of the pipeline.
- *
- * **Mental model**
- *
- * - Encoders receive non-empty chunks of values and emit one NDJSON chunk ending
- *   with a newline
- * - Decoders accumulate partial lines across input chunks and emit parsed JSON
- *   records as soon as complete lines are available
- * - Schema helpers compose channel encoding and decoding with the plain NDJSON
- *   framing helpers
- *
- * **Common tasks**
- *
- * - Encode values to UTF-8 bytes: {@link encode}
- * - Encode values to strings: {@link encodeString}
- * - Decode UTF-8 bytes or strings: {@link decode}, {@link decodeString}
- * - Add schema validation at the boundary: {@link encodeSchema}, {@link decodeSchema}
- *
- * **Gotchas**
- *
- * - Records must be valid JSON values, not JavaScript expressions
- * - Empty lines are ignored only when `ignoreEmptyLines` is enabled
- * - Encoders append a trailing newline, so downstream consumers should treat it
- *   as record framing rather than as an extra record
+ * NDJSON stores one complete JSON value on each line. This module has helpers
+ * for byte streams, string streams, and schema-checked records, so streaming
+ * code can read or write one JSON record at a time.
  *
  * @since 4.0.0
  */

package/src/unstable/encoding/Sse.ts

@@ -1,41 +1,10 @@
 /**
- * Utilities for parsing and rendering Server-Sent Events text streams.
- *
- * SSE is the EventSource wire format used by live updates, notifications,
- * progress feeds, and other unidirectional server-to-client HTTP streams. This
- * module provides low-level parser and encoder primitives, channel combinators
- * for streaming text chunks through Effect pipelines, and schema-aware helpers
- * for validating or transforming the `id`, `event`, and string `data` fields
- * at the edge of an application.
- *
- * **Mental model**
- *
- * - SSE is line-oriented text, not a framed binary protocol.
- * - Incoming chunks may split fields across arbitrary boundaries, so decoders
- *   buffer incomplete lines until a full event is available.
- * - A blank line dispatches an event; repeated `data:` lines are joined with
- *   newlines.
- * - `retry:` directives are control messages. Decoders surface them as
- *   {@link Retry} failures so callers can reconnect with the requested delay.
- *
- * **Common tasks**
- *
- * - Parse string chunks into {@link Event} values: {@link decode}
- * - Decode events with a schema: {@link decodeSchema}
- * - JSON-decode each event `data` field with a schema:
- *   {@link decodeDataSchema}
- * - Feed a stateful parser manually: {@link makeParser}
- * - Encode {@link Event} values as SSE text: {@link encode}, {@link encoder}
- * - Schema-encode domain values before writing SSE text: {@link encodeSchema}
- *
- * **Gotchas**
- *
- * - Event `data` is text. Use {@link decodeDataSchema} when the data field
- *   contains JSON that should be decoded into a domain value.
- * - The default event name is `message`; the encoder omits the `event:` line
- *   for that default.
- * - The decoder handles UTF-8 byte order marks, CRLF and LF line endings, and
- *   retry directives while preserving the last event ID when available.
+ * Parses and renders Server-Sent Events text streams.
+ *
+ * Server-Sent Events, or SSE, are the text format used by `EventSource` for
+ * one-way server-to-client updates. This module includes parsers, encoders,
+ * channel helpers, and schema-based helpers for the `id`, `event`, and `data`
+ * fields of each event.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/Event.ts

@@ -4,31 +4,9 @@
  * An `Event` is the durable contract shared by writers, handlers, journals, and
  * replicas. It gives an event a stable tag, derives the aggregate or entity
  * primary key from the decoded payload, and records the schemas used for the
- * payload and handler result. The payload schema also derives the MessagePack
- * schema used when entries are written to an event journal or sent to a remote
- * replica.
- *
- * **Mental model**
- *
- * The tag names the event kind, the primary key chooses the partition or entity
- * affected by the event, the payload schema describes the persisted fact, and
- * the success and error schemas describe the handler boundary. Type helpers in
- * this module derive payload, success, error, and service types from either a
- * single event definition or a union selected by tag.
- *
- * **Common tasks**
- *
- * Use `make` to define a single event, `addError` to add a shared handler error
- * to an existing definition, and the tag-based helper types when a client or
- * server API needs the payload, success, or error type for one event in a group.
- *
- * **Gotchas**
- *
- * Persisted tags and payload schemas should remain stable. Prefer a new tag or a
- * backward-compatible schema when an event shape changes, and keep
- * `primaryKey` deterministic so related entries group consistently across
- * local journals and remote replicas. Omitted payload and success schemas
- * default to `Schema.Void`; omitted error schemas default to `Schema.Never`.
+ * payload, handler result, and handler errors. The payload schema is also used
+ * to derive the MessagePack encoding for journal entries and remote
+ * replication.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventGroup.ts

@@ -1,26 +1,11 @@
 /**
- * Describes typed event groups for the unstable event-log system.
+ * Defines groups of typed events for the unstable event-log system.
  *
- * 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.
- *
- * **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.
+ * An `EventGroup` collects event definitions that belong together. Start with
+ * `empty`, add events with their payload, success, and error schemas, then use
+ * the group to build clients with `EventLog.schema` and server handlers with
+ * `EventLog.group`. The group only describes events; it does not write or run
+ * them.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventJournal.ts

@@ -1,36 +1,13 @@
 /**
- * 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.
+ * Stores event-log entries and replication state.
+ *
+ * `EventJournal` records committed entries, exposes them for replay, publishes
+ * local changes, and tracks the remote metadata needed to exchange entries with
+ * other journals. Higher-level event-log schemas and handlers use this service
+ * to rebuild projections, sync offline clients, import remote changes, and
+ * coordinate writes per store. This module also defines journal errors, entry
+ * and remote identifiers, schemas, and in-memory or IndexedDB-backed journal
+ * layers.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLog.ts

@@ -1,33 +1,11 @@
 /**
- * High-level runtime for writing typed event-log events and replaying replicated
- * journal entries.
+ * Runtime for writing typed events to an event journal.
  *
- * 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.
+ * `EventLog` combines event groups, handlers, a journal, local identity,
+ * optional remote replicas, and reactivity hooks. Writers send typed payloads
+ * through a client; the matching handler runs first, and the journal entry is
+ * committed only after the handler succeeds. This module also contains the
+ * layers and helpers needed to assemble that runtime.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogEncryption.ts

@@ -1,23 +1,10 @@
 /**
- * Event-log encryption primitives for encrypted remote replication.
+ * Cryptographic service for encrypted event-log replication.
  *
- * This module defines the `EventLogEncryption` service used by encrypted
- * `EventLogRemote` clients to turn local journal entries into encrypted remote
- * payloads, decrypt encrypted changes received from a server, hash byte data,
- * and create event-log identities. It is useful when events need to be
- * replicated through infrastructure that stores or transports only ciphertext,
- * such as an encrypted event-log server, offline-first synchronization backend,
- * or multi-device replicated store.
- *
- * Encryption keys are deterministically derived from the identity private key
- * material, so the same stable identity is required to decrypt entries across
- * sessions and devices. The public key identifies the replicated log, while the
- * private key material must remain secret and must not be rotated without a
- * migration plan for existing encrypted entries. The default implementation
- * uses Web Crypto AES-GCM with generated initialization vectors that are stored
- * alongside encrypted entries; persisted ciphertext, IVs, entry schemas, and
- * identity key derivation labels are part of the compatibility surface for
- * future event-log encryption versions.
+ * `EventLogEncryption` turns local journal entries into encrypted remote
+ * payloads and decrypts encrypted changes received from a server. It also
+ * hashes byte data and creates event-log identities, so remote replication can
+ * use storage or transport that should not see plaintext event data.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogMessage.ts

@@ -1,26 +1,10 @@
 /**
- * Defines the remote event-log protocol messages and RPC group.
+ * Defines protocol messages for event-log remote clients and servers.
  *
  * 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.
- *
- * **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.
+ * event-log servers. It defines store ids, protocol errors, the
+ * hello/authenticate session handshake, remote calls for writes and changes,
+ * and message formats for encrypted or plaintext journal entries.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogRemote.ts

@@ -1,22 +1,12 @@
 /**
- * Client-side remote replica support for writing event-log entries and
- * receiving change streams over the event-log RPC protocol.
+ * Connects a local event log to a remote replica.
  *
- * This module builds `EventLogRemote` services backed by `EventLogRemoteRpcs`.
- * It is used by local event logs that need to replicate entries to another
- * journal, subscribe to remote changes from a sequence number, or run effects
- * only after the current event-log identity has completed the remote
- * authentication handshake. The encrypted constructor is the default choice for
- * synchronizing browser, edge, or service replicas across an untrusted network,
- * while the unencrypted constructor is intended for trusted transports or tests.
- *
- * Remote sessions begin with `Hello` and `Authenticate`, cache authentication by
- * identity public key, and retry forbidden responses by refreshing the handshake.
- * The RPC transport must preserve a stable client session across hello,
- * authentication, writes, and change streams. Entries and change batches may be
- * split into protocol chunks, so callers should treat `changes` as a scoped
- * streaming queue and rely on the remote `Registry` registration instead of
- * manually sharing partially assembled payloads between sessions.
+ * `EventLogRemote` writes local entries to another journal, receives remote
+ * change streams from a sequence number, and can wait until the current
+ * event-log identity has completed remote authentication. The encrypted
+ * constructor is the default for browser, edge, or service replicas crossing an
+ * untrusted network. The unencrypted constructor is intended for trusted
+ * transports or tests.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogServer.ts

@@ -1,34 +1,11 @@
 /**
- * Builds server-side RPC handlers for the event-log remote protocol.
+ * Builds server-side 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
+ * Transport modules use these handlers to expose an event 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
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"

package/src/unstable/eventlog/EventLogServerEncrypted.ts

@@ -1,23 +1,12 @@
 /**
- * Server-side RPC layers and storage contracts for encrypted event-log
- * replication.
+ * Serves encrypted event-log replication.
  *
- * This module is used by encrypted `EventLogRemote` clients that need a remote
- * synchronization endpoint without exposing plaintext events to the server. The
- * server stores ciphertext, initialization vectors, entry ids, and remote
- * sequence numbers keyed by the client's public key and store id, then streams
- * encrypted changes back to clients so they can decrypt locally with their
- * identity private key material. This makes it suitable for offline-first
- * synchronization, multi-device replication, and hosted backends where the
- * transport or storage layer should not inspect event payloads.
- *
- * The server does not derive or hold encryption keys. It treats public keys as
- * log identities, persists one session authentication binding per public key,
- * and reuses the initialization vector supplied with each encrypted write
- * request for the entries in that batch. Persisted remote ids, session signing
- * key bindings, ciphertext, IVs, and sequence numbers are therefore part of the
- * encrypted replication protocol and should be kept stable by durable storage
- * implementations.
+ * Encrypted `EventLogRemote` clients use this module when they need a remote
+ * synchronization endpoint that never sees plaintext events. The server stores
+ * encrypted entries and replication metadata keyed by client public key and
+ * store id, then streams encrypted changes back to clients for local
+ * decryption. This module defines the RPC handlers, server layer, storage
+ * contract, and in-memory storage layer for that encrypted server path.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogServerUnencrypted.ts

@@ -1,41 +1,13 @@
 /**
  * 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.
+ * This module accepts unencrypted event batches from remote clients, runs the
+ * registered event handlers, stores journal entries, and streams backlog plus
+ * live changes through the shared `EventLogServer` RPC protocol. It is intended
+ * for trusted deployments, local development, and tests where event data does
+ * not need a server-side encryption layer. The module also provides the
+ * services and layers needed to authorize requests, map stores, persist entries,
+ * and install the plaintext server.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogSessionAuth.ts

@@ -1,39 +1,10 @@
 /**
- * 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
+ * Signs and verifies event-log session authentication payloads.
+ *
+ * Remote peers use this challenge-response flow to prove that they control a
+ * session signing key before sending session traffic. The signed payload
+ * includes the remote id, a short-lived challenge, the event-log public key, and
+ * the signing public key in a stable byte format.
  *
  * @since 4.0.0
  */

package/src/unstable/eventlog/SqlEventJournal.ts

@@ -6,32 +6,6 @@
  * tables, giving event-log programs a durable journal that can be replayed after
  * restart and synchronized with remote journals.
  *
- * **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
  */
 import * as Uuid from "uuid"

package/src/unstable/eventlog/SqlEventLogServerEncrypted.ts

@@ -1,45 +1,12 @@
 /**
- * SQL storage for encrypted event-log server state.
+ * Stores encrypted event-log server state in SQL.
  *
  * 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.
- *
- * **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.
+ * `EventLogServerEncrypted` when entries should be stored without exposing
+ * plaintext event data to the database. It persists the server remote id,
+ * session authentication bindings, and encrypted entry tables, assigns stable
+ * sequence numbers, and streams changes. Clients remain responsible for
+ * encrypting writes and decrypting reads.
  *
  * @since 4.0.0
  */