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

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
@@ -187,11 +195,11 @@ const makeProto = <
 }
 
 /**
- * Empty event group used as the starting point for defining a group.
+ * Creates an empty event group used as the starting point for defining a group.
  *
  * **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
@@ -139,7 +156,7 @@ export class EventJournalError extends Data.TaggedError("EventJournalError")<{
 /**
  * Brand identifier used for `RemoteId` values.
  *
- * @category remote
+ * @category type IDs
  * @since 4.0.0
  */
 export type RemoteIdTypeId = "effect/eventlog/EventJournal/RemoteId"
@@ -147,7 +164,7 @@ export type RemoteIdTypeId = "effect/eventlog/EventJournal/RemoteId"
 /**
  * Runtime brand identifier used for `RemoteId` values.
  *
- * @category remote
+ * @category type IDs
  * @since 4.0.0
  */
 export const RemoteIdTypeId: RemoteIdTypeId = "effect/eventlog/EventJournal/RemoteId"
@@ -184,7 +201,7 @@ export const makeRemoteIdUnsafe = (): RemoteId => Uuid.v4({}, new globalThis.Uin
 /**
  * Runtime brand identifier used for `EntryId` values.
  *
- * @category entry
+ * @category type IDs
  * @since 4.0.0
  */
 export const EntryIdTypeId: EntryIdTypeId = "effect/eventlog/EventJournal/EntryId"
@@ -192,7 +209,7 @@ export const EntryIdTypeId: EntryIdTypeId = "effect/eventlog/EventJournal/EntryI
 /**
  * Brand identifier used for `EntryId` values.
  *
- * @category entry
+ * @category type IDs
  * @since 4.0.0
  */
 export type EntryIdTypeId = "effect/eventlog/EventJournal/EntryId"
@@ -216,7 +233,7 @@ export const EntryId = (Schema.Uint8Array as Schema.instanceOf<Uint8Array<ArrayB
 )
 
 /**
- * Ordering for `EntryId` values based on their raw UUID bytes.
+ * Provides an Ordering instance for entry identifiers based on their raw UUID bytes.
  *
  * @category entry
  * @since 4.0.0
@@ -258,7 +275,7 @@ export const entryIdMillis = (entryId: EntryId): number => {
 }
 
 /**
- * Schema model for a committed event journal entry.
+ * Schema for a committed event journal entry.
  *
  * **Details**
  *
@@ -331,7 +348,7 @@ export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Ent
 }
 
 /**
- * Schema model for an event journal entry received from a remote source.
+ * Schema for an event journal entry received from a remote source.
  *
  * **Details**
  *

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
  */
@@ -69,10 +83,10 @@ export class EventLog extends Context.Service<EventLog, {
 }>()("effect/eventlog/EventLog") {}
 
 /**
- * Scoped registry used by `EventLog` to collect event handlers, compaction
- * handlers, remote replicas, and reactivity invalidation keys.
+ * Service that collects event handlers, compaction handlers, remote replicas,
+ * and reactivity invalidation keys.
  *
- * @category Registry
+ * @category services
  * @since 4.0.0
  */
 export class Registry extends Context.Service<Registry, {
@@ -111,7 +125,7 @@ export class Registry extends Context.Service<Registry, {
  * Provides an in-memory `Registry` for event handlers, compactors, remote
  * replicas, and reactivity keys.
  *
- * @category Registry
+ * @category layers
  * @since 4.0.0
  */
 export const layerRegistry = Layer.effect(
@@ -175,14 +189,15 @@ export const layerRegistry = Layer.effect(
 )
 
 /**
- * Event-log identity containing a public key and redacted private key material.
+ * Context service for an event-log identity containing a public key and redacted
+ * private key material.
  *
  * **Details**
  *
  * The identity is used by remote replication for authentication and by the
  * encryption service to derive signing and encryption keys.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export class Identity extends Context.Service<Identity, {
@@ -193,7 +208,7 @@ export class Identity extends Context.Service<Identity, {
 /**
  * Type-level identifier used to brand `EventLogSchema` values.
  *
- * @category schemas
+ * @category type IDs
  * @since 4.0.0
  */
 export type SchemaTypeId = "~effect/eventlog/EventLog/Schema"
@@ -201,7 +216,7 @@ export type SchemaTypeId = "~effect/eventlog/EventLog/Schema"
 /**
  * Runtime property key used to identify `EventLogSchema` values.
  *
- * @category schemas
+ * @category type IDs
  * @since 4.0.0
  */
 export const SchemaTypeId: SchemaTypeId = "~effect/eventlog/EventLog/Schema"
@@ -245,7 +260,7 @@ export const schema = <Groups extends ReadonlyArray<EventGroup.Any>>(
 /**
  * Type-level identifier used to brand `Handlers` values.
  *
- * @category handlers
+ * @category type IDs
  * @since 4.0.0
  */
 export type HandlersTypeId = "~effect/eventlog/EventLog/Handlers"
@@ -253,7 +268,7 @@ export type HandlersTypeId = "~effect/eventlog/EventLog/Handlers"
 /**
  * Runtime property key used to identify `Handlers` values.
  *
- * @category handlers
+ * @category type IDs
  * @since 4.0.0
  */
 export const HandlersTypeId: HandlersTypeId = "~effect/eventlog/EventLog/Handlers"
@@ -961,6 +976,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/EventLogEncryption.ts

@@ -74,10 +74,15 @@ const toArrayBuffer = (data: Uint8Array): ArrayBuffer => {
 const toBufferSource = (data: Uint8Array): ArrayBufferView<ArrayBuffer> => new Uint8Array(toArrayBuffer(data))
 
 /**
- * Service used by event-log replication for identity generation, entry
- * encryption and decryption, and SHA-256 hashing.
+ * Service that provides identity generation, entry
+ * encryption and decryption, and SHA-256 hashing for event-log replication.
  *
- * @category services
+ * **When to use**
+ *
+ * Use to provide cryptographic operations required by encrypted event-log
+ * replication.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class EventLogEncryption extends Context.Service<EventLogEncryption, {

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
  */
@@ -30,7 +39,7 @@ import { EncryptedEntry, EncryptedRemoteEntry } from "./EventLogEncryption.ts"
 /**
  * Type-level identifier used to brand event-log store ids.
  *
- * @category StoreId
+ * @category type IDs
  * @since 4.0.0
  */
 export type StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
@@ -38,7 +47,7 @@ export type StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
 /**
  * Runtime brand identifier for event-log store ids.
  *
- * @category StoreId
+ * @category type IDs
  * @since 4.0.0
  */
 export const StoreIdTypeId: StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
@@ -60,14 +69,14 @@ export type StoreId = string & Brand<StoreIdTypeId>
 export const StoreId = Schema.String.pipe(Schema.brand(StoreIdTypeId))
 
 /**
- * Structured error returned by event-log remote RPCs.
+ * Error returned by event-log remote RPCs.
  *
  * **Details**
  *
  * It records the request tag, optional identity and store information, a protocol
  * error code, and a human-readable message.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class EventLogProtocolError extends Schema.TaggedErrorClass<EventLogProtocolError>(
@@ -84,7 +93,7 @@ export class EventLogProtocolError extends Schema.TaggedErrorClass<EventLogProto
  * RPC middleware that authenticates event-log requests and provides the client
  * `Identity` to authenticated handlers.
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export class EventLogAuthentication extends RpcMiddleware.Service<EventLogAuthentication, {
@@ -101,7 +110,7 @@ export class EventLogAuthentication extends RpcMiddleware.Service<EventLogAuthen
  * It contains the server remote id and a challenge that must be signed by the
  * client.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class HelloResponse extends Schema.Class<HelloResponse>("effect/eventlog/EventLogRemote/HelloResponse")({
@@ -112,7 +121,7 @@ export class HelloResponse extends Schema.Class<HelloResponse>("effect/eventlog/
 /**
  * RPC used to start an event-log remote session and receive a `HelloResponse`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class HelloRpc extends Rpc.make("EventLog.Hello", {
@@ -120,10 +129,11 @@ export class HelloRpc extends Rpc.make("EventLog.Hello", {
 }) {}
 
 /**
- * Authentication request containing the client public key, Ed25519 signing public
- * key, signature over the session challenge payload, and algorithm name.
+ * Schema for an authentication request containing the client public key,
+ * Ed25519 signing public key, signature over the session challenge payload, and
+ * algorithm name.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class Authenticate extends Schema.Class<Authenticate>("effect/eventlog/EventLogRemote/Authenticate")({
@@ -136,7 +146,7 @@ export class Authenticate extends Schema.Class<Authenticate>("effect/eventlog/Ev
 /**
  * RPC used to authenticate a remote event-log session after `HelloRpc`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class AuthenticateRpc extends Rpc.make("EventLog.Authenticate", {
@@ -145,9 +155,9 @@ export class AuthenticateRpc extends Rpc.make("EventLog.Authenticate", {
 }) {}
 
 /**
- * Transport message containing an entire encoded event-log payload in one frame.
+ * Represents an entire encoded event-log payload in one transport frame.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class SingleMessage
@@ -157,14 +167,14 @@ export class SingleMessage
 {}
 
 /**
- * Transport message for one part of a large encoded event-log payload.
+ * Represents one part of a large encoded event-log payload.
  *
  * **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
+ * @category protocols
  * @since 4.0.0
  */
 export class ChunkedMessage
@@ -245,9 +255,9 @@ export class ChunkedMessage
 }
 
 /**
- * Authenticated RPC for sending one chunk of a large encoded write payload.
+ * RPC used to send one chunk of a large encoded write payload.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class WriteChunkedRpc extends Rpc.make("EventLog.WriteChunked", {
@@ -256,14 +266,14 @@ export class WriteChunkedRpc extends Rpc.make("EventLog.WriteChunked", {
 }).middleware(EventLogAuthentication) {}
 
 /**
- * Msgpack-encodable payload for writing encrypted entries to a remote store.
+ * Schema for encrypted event-log write payloads sent to a remote store.
  *
  * **Details**
  *
  * It includes the client public key, target store id, AES-GCM initialization
  * vector, and encrypted entries.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class WriteEntries extends Schema.Class<WriteEntries>("effect/eventlog/EventLogRemote/WriteEntries")({
@@ -281,9 +291,9 @@ export class WriteEntries extends Schema.Class<WriteEntries>("effect/eventlog/Ev
 }
 
 /**
- * Msgpack-encodable payload for writing plaintext entries to a remote store.
+ * Schema for plaintext event-log write payloads sent to a remote store.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class WriteEntriesUnencrypted
@@ -302,10 +312,9 @@ export class WriteEntriesUnencrypted
 }
 
 /**
- * Authenticated RPC for sending an encoded write payload that fits in one
- * message.
+ * RPC used to send an encoded write payload that fits in one message.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class WriteSingleRpc extends Rpc.make("EventLog.WriteSingle", {
@@ -316,15 +325,15 @@ export class WriteSingleRpc extends Rpc.make("EventLog.WriteSingle", {
 }).middleware(EventLogAuthentication) {}
 
 /**
- * Authenticated streaming RPC for reading remote event-log changes for a public
- * key and store id starting at a sequence number.
+ * RPC used to stream remote event-log changes for a public key and store id
+ * starting at a sequence number.
  *
  * **Details**
  *
  * Responses are encoded as either `SingleMessage` values or `ChunkedMessage`
  * parts.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ChangesRpc extends Rpc.make("EventLog.Changes", {
@@ -349,7 +358,7 @@ export class ChangesRpc extends Rpc.make("EventLog.Changes", {
  * RPC group containing the event-log remote handshake, authentication, write, and
  * changes endpoints.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class EventLogRemoteRpcs extends RpcGroup.make(

package/src/unstable/eventlog/EventLogRemote.ts

@@ -51,14 +51,19 @@ import { encodeSessionAuthPayload, signSessionAuthPayloadBytes } from "./EventLo
 import { makeGetIdentityRootSecretMaterial } from "./internal/identityRootSecretDerivation.ts"
 
 /**
- * Service representing a remote event-log replica.
+ * Service that represents a remote event-log replica.
+ *
+ * **When to use**
+ *
+ * Use to access or provide a remote event-log replica that can write local
+ * entries and stream remote changes.
  *
  * **Details**
  *
  * It can write local entries to the remote, stream remote changes from a sequence
  * number, and run effects only after the supplied identity has authenticated.
  *
- * @category models
+ * @category tags
  * @since 4.0.0
  */
 export class EventLogRemote extends Context.Service<EventLogRemote, {
@@ -117,9 +122,14 @@ const makeAuthenticate = Effect.fnUntraced(function*(options: {
 })
 
 /**
- * Typed RPC client service for the `EventLogRemoteRpcs` protocol.
+ * Service that provides a typed RPC client for the `EventLogRemoteRpcs` protocol.
+ *
+ * **When to use**
+ *
+ * Use to provide the RPC client used by remote event-log replicas to
+ * authenticate, write entries, and subscribe to changes.
  *
- * @category RpcClient
+ * @category RPC client
  * @since 4.0.0
  */
 export class EventLogRemoteClient extends Context.Service<