effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/eventlog/EventLogServerUnencrypted.ts

@@ -1,4 +1,20 @@
 /**
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -33,8 +49,11 @@ import {
 import * as EventLogServer from "./EventLogServer.ts"
 
 /**
- * @since 4.0.0
+ * Server-side service for writing plaintext event-log entries directly to
+ * unencrypted storage through registered event handlers.
+ *
  * @category EventLogServerUnencrypted
+ * @since 4.0.0
  */
 export class EventLogServerUnencrypted extends Context.Service<EventLogServerUnencrypted, {
   readonly makeWrite: <Groups extends EventGroup.Any>(
@@ -53,8 +72,11 @@ export class EventLogServerUnencrypted extends Context.Service<EventLogServerUne
 }>()("effect/eventlog/EventLogServerUnencrypted") {}
 
 /**
- * @since 4.0.0
+ * Creates a typed server-side write function for events in the supplied
+ * `EventLogSchema`.
+ *
  * @category EventLogServerUnencrypted
+ * @since 4.0.0
  */
 export const makeWrite = <Groups extends EventGroup.Any>(
   schema: EventLog.EventLogSchema<Groups>
@@ -75,8 +97,14 @@ export const makeWrite = <Groups extends EventGroup.Any>(
 > => EventLogServerUnencrypted.useSync((_) => _.makeWrite(schema))
 
 /**
- * @since 4.0.0
+ * Provides RPC handlers for the unencrypted event-log server.
+ *
+ * Incoming plaintext entries are authorized, mapped to a server store, checked
+ * for conflicts, run through registered handlers, and persisted; change streams
+ * include compacted backlog entries when compactors are registered.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerRpcHandlers: Layer.Layer<
   Rpc.ToHandler<RpcGroup.Rpcs<typeof EventLogRemoteRpcs>> | EventLogAuthentication,
@@ -198,8 +226,10 @@ export const layerRpcHandlers: Layer.Layer<
 }))
 
 /**
- * @since 4.0.0
+ * Error raised by unencrypted server storage and store mapping operations.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class EventLogServerStoreError extends Data.TaggedError("EventLogServerStoreError")<{
   readonly reason: "NotFound" | "PersistenceFailure"
@@ -209,8 +239,11 @@ export class EventLogServerStoreError extends Data.TaggedError("EventLogServerSt
 }> {}
 
 /**
- * @since 4.0.0
+ * Error raised when unencrypted server authorization rejects an identity or store
+ * operation.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class EventLogServerAuthError extends Data.TaggedError("EventLogServerAuthError")<{
   readonly reason: "Unauthorized" | "Forbidden"
@@ -220,8 +253,11 @@ export class EventLogServerAuthError extends Data.TaggedError("EventLogServerAut
 }> {}
 
 /**
- * @since 4.0.0
+ * Authorization service used by the unencrypted event-log server to validate
+ * write access, read access, and identities.
+ *
  * @category context
+ * @since 4.0.0
  */
 export class EventLogServerAuthorization extends Context.Service<EventLogServerAuthorization, {
   readonly authorizeWrite: (options: {
@@ -239,8 +275,11 @@ export class EventLogServerAuthorization extends Context.Service<EventLogServerA
 }>()("effect/eventlog/EventLogServerUnencrypted/EventLogServerAuthorization") {}
 
 /**
- * @since 4.0.0
+ * Service that resolves client-requested store ids to server store ids and checks
+ * whether a store exists.
+ *
  * @category context
+ * @since 4.0.0
  */
 export class StoreMapping extends Context.Service<StoreMapping, {
   readonly resolve: (
@@ -269,8 +308,11 @@ const toStoreNotFoundError = (options: {
   })
 
 /**
- * @since 4.0.0
+ * Provides a `StoreMapping` that accepts only one configured store id and fails
+ * all other store ids as not found.
+ *
  * @category store
+ * @since 4.0.0
  */
 export const layerStoreMappingStatic = (options: {
   readonly storeId: StoreId
@@ -286,8 +328,14 @@ export const layerStoreMappingStatic = (options: {
   })
 
 /**
- * @since 4.0.0
+ * Storage service used by the unencrypted event-log server.
+ *
+ * It provides the server remote id, stores session authentication bindings,
+ * allocates remote sequence numbers, persists entries, streams changes, and
+ * exposes a transaction boundary.
+ *
  * @category storage
+ * @since 4.0.0
  */
 export class Storage extends Context.Service<Storage, {
   readonly getId: Effect.Effect<RemoteId>
@@ -405,8 +453,14 @@ const toCompactedRemoteEntries = (options: {
 }
 
 /**
- * @since 4.0.0
+ * Compacts a backlog of remote entries using the registered compactors.
+ *
+ * Contiguous entries handled by the same compactor may be replaced with compacted
+ * entries when the replacement count can be mapped back to increasing remote
+ * sequence numbers; otherwise the original entries are kept.
+ *
  * @category compaction
+ * @since 4.0.0
  */
 export const compactBacklog = Effect.fnUntraced(function*(options: {
   readonly remoteEntries: ReadonlyArray<RemoteEntry>
@@ -469,8 +523,14 @@ export const compactBacklog = Effect.fnUntraced(function*(options: {
 })
 
 /**
- * @since 4.0.0
+ * Creates an in-memory unencrypted server `Storage`.
+ *
+ * The implementation keeps per-store journals and session authentication bindings
+ * in memory, publishes live changes, and serializes transactions with a
+ * semaphore.
+ *
  * @category storage
+ * @since 4.0.0
  */
 export const makeStorageMemory: Effect.Effect<Storage["Service"], never, Scope.Scope> = Effect.gen(function*() {
   const knownIds = new Map<string, Map<string, number>>()
@@ -574,14 +634,19 @@ export const makeStorageMemory: Effect.Effect<Storage["Service"], never, Scope.S
 })
 
 /**
- * @since 4.0.0
+ * Provides unencrypted server `Storage` using the in-memory implementation.
+ *
  * @category storage
+ * @since 4.0.0
  */
 export const layerStorageMemory: Layer.Layer<Storage> = Layer.effect(Storage)(makeStorageMemory)
 
 /**
- * @since 4.0.0
+ * Creates the `EventLogServerUnencrypted` service from the configured storage and
+ * registered event handlers.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.gen(function*() {
   const storage = yield* Storage
@@ -640,8 +705,11 @@ export const make = Effect.gen(function*() {
 })
 
 /**
- * @since 4.0.0
+ * Provides `EventLogServerUnencrypted` and an event-log `Registry` using the
+ * configured unencrypted server `Storage`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerServer: Layer.Layer<
   EventLogServerUnencrypted | EventLog.Registry,
@@ -652,8 +720,11 @@ export const layerServer: Layer.Layer<
 )
 
 /**
- * @since 4.0.0
+ * Builds a full unencrypted event-log RPC server for the supplied schema and
+ * event-group handler layer.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = <Groups extends EventGroup.Any, E, R>(
   _schema: EventLog.EventLogSchema<Groups>,
@@ -674,8 +745,11 @@ export const layer = <Groups extends EventGroup.Any, E, R>(
   )
 
 /**
- * @since 4.0.0
+ * Builds the unencrypted event-log server handlers without installing an
+ * `RpcServer.Protocol` implementation.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerNoRpcServer = <Groups extends EventGroup.Any, E, R>(
   _schema: EventLog.EventLogSchema<Groups>,

package/src/unstable/eventlog/EventLogSessionAuth.ts

@@ -1,4 +1,22 @@
 /**
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Data from "../../Data.ts"
@@ -10,38 +28,52 @@ const textDecoder = new TextDecoder("utf-8", { fatal: true })
 const constLengthPrefixBytes = 4
 
 /**
- * @since 4.0.0
+ * Domain-separation string embedded in canonical session authentication payloads.
+ *
  * @category constants
+ * @since 4.0.0
  */
 export const AuthPayloadContext = "eventlog-auth-v1"
 
 /**
- * @since 4.0.0
+ * Required byte length for raw Ed25519 public keys used in session
+ * authentication.
+ *
  * @category constants
+ * @since 4.0.0
  */
 export const Ed25519PublicKeyLength = 32
 
 /**
- * @since 4.0.0
+ * Required byte length for Ed25519 signatures used in session authentication.
+ *
  * @category constants
+ * @since 4.0.0
  */
 export const Ed25519SignatureLength = 64
 
 /**
- * @since 4.0.0
+ * Number of random bytes generated for a session authentication challenge.
+ *
  * @category constants
+ * @since 4.0.0
  */
 export const SessionAuthChallengeLength = 32
 
 /**
- * @since 4.0.0
+ * Time-to-live, in milliseconds, for a pending session authentication challenge.
+ *
  * @category constants
+ * @since 4.0.0
  */
 export const SessionAuthChallengeTimeToLiveMillis = 30_000
 
 /**
- * @since 4.0.0
+ * Payload fields that are canonicalized and signed during session
+ * authentication.
+ *
  * @category model
+ * @since 4.0.0
  */
 export interface SessionAuthPayload {
   readonly remoteId: string | Uint8Array
@@ -51,8 +83,11 @@ export interface SessionAuthPayload {
 }
 
 /**
- * @since 4.0.0
+ * Error raised while encoding, decoding, signing, verifying, or generating
+ * session authentication challenges.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class EventLogSessionAuthError extends Data.TaggedError("EventLogSessionAuthError")<{
   readonly reason:
@@ -214,8 +249,8 @@ const encodeRemoteIdField = (remoteId: string | Uint8Array): Uint8Array =>
  * 4. publicKey
  * 5. signingPublicKey bytes
  *
- * @since 4.0.0
  * @category encoding
+ * @since 4.0.0
  */
 export const encodeSessionAuthPayload = Effect.fnUntraced(function*(payload: SessionAuthPayload) {
   yield* assertSigningPublicKeyLength(payload.signingPublicKey)
@@ -245,8 +280,13 @@ export const encodeSessionAuthPayload = Effect.fnUntraced(function*(payload: Ses
 })
 
 /**
- * @since 4.0.0
+ * Decodes a canonical session authentication payload.
+ *
+ * The decoder validates the context field, UTF-8 fields, signing public key
+ * length, and rejects truncated or trailing bytes.
+ *
  * @category encoding
+ * @since 4.0.0
  */
 export const decodeSessionAuthPayload = Effect.fnUntraced(
   function*(payload: Uint8Array): Effect.fn.Return<SessionAuthPayload, EventLogSessionAuthError> {
@@ -283,8 +323,13 @@ export const decodeSessionAuthPayload = Effect.fnUntraced(
 )
 
 /**
- * @since 4.0.0
+ * Signs canonical session authentication payload bytes with an Ed25519 private
+ * key.
+ *
+ * The private key must be PKCS#8-encoded bytes importable by `SubtleCrypto`.
+ *
  * @category signing
+ * @since 4.0.0
  */
 export const signSessionAuthPayloadBytes = Effect.fnUntraced(function*(options: {
   readonly payload: Uint8Array
@@ -323,8 +368,14 @@ export const signSessionAuthPayloadBytes = Effect.fnUntraced(function*(options:
 })
 
 /**
- * @since 4.0.0
+ * Verifies an Ed25519 signature for canonical session authentication payload
+ * bytes.
+ *
+ * The payload, signing public key, and signature lengths are validated before
+ * calling `SubtleCrypto.verify`.
+ *
  * @category verification
+ * @since 4.0.0
  */
 export const verifySessionAuthPayloadBytes = Effect.fnUntraced(function*(options: {
   readonly payload: Uint8Array
@@ -358,8 +409,11 @@ export const verifySessionAuthPayloadBytes = Effect.fnUntraced(function*(options
 })
 
 /**
- * @since 4.0.0
+ * Encodes a session authentication payload in canonical form and signs it with an
+ * Ed25519 private key.
+ *
  * @category signing
+ * @since 4.0.0
  */
 export const signSessionAuthPayload = (
   options: SessionAuthPayload & {
@@ -376,8 +430,11 @@ export const signSessionAuthPayload = (
   )
 
 /**
- * @since 4.0.0
+ * Encodes a session authentication payload in canonical form and verifies its
+ * Ed25519 signature.
+ *
  * @category verification
+ * @since 4.0.0
  */
 export const verifySessionAuthPayload = (
   options: SessionAuthPayload & {
@@ -395,8 +452,10 @@ export const verifySessionAuthPayload = (
   )
 
 /**
- * @since 4.0.0
+ * Generates a random session authentication challenge using `globalThis.crypto`.
+ *
  * @category challenge
+ * @since 4.0.0
  */
 export const makeSessionAuthChallenge: Effect.Effect<
   Uint8Array<ArrayBuffer>,
@@ -409,8 +468,11 @@ export const makeSessionAuthChallenge: Effect.Effect<
 })
 
 /**
- * @since 4.0.0
+ * Verifies an authentication request by requiring the `Ed25519` algorithm and
+ * checking the signature over the canonical session authentication payload.
+ *
  * @category verification
+ * @since 4.0.0
  */
 export const verifySessionAuthenticateRequest = Effect.fnUntraced(function*(options: {
   readonly remoteId: string | Uint8Array

package/src/unstable/eventlog/SqlEventJournal.ts

@@ -1,4 +1,22 @@
 /**
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Uuid from "uuid"
@@ -14,8 +32,13 @@ import * as EventJournal from "./EventJournal.ts"
 type WriteFromRemoteOptions = Parameters<EventJournal.EventJournal["Service"]["writeFromRemote"]>[0]
 
 /**
- * @since 4.0.0
+ * Creates an `EventJournal` backed by a SQL database.
+ *
+ * The constructor creates the entry and remote metadata tables when needed,
+ * persists local and remote entries, and uses the configured `SqlClient`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (options?: {
   readonly entryTable?: string
@@ -267,8 +290,11 @@ export const make = (options?: {
   })
 
 /**
- * @since 4.0.0
+ * Provides `EventJournal` using the SQL-backed implementation created by
+ * `make`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options?: {
   readonly entryTable?: string

package/src/unstable/eventlog/SqlEventLogServerEncrypted.ts

@@ -1,4 +1,22 @@
 /**
+ * SQL-backed storage for encrypted event-log servers.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -15,8 +33,14 @@ import * as EventLogEncryption from "./EventLogEncryption.ts"
 import * as EventLogServerEncrypted from "./EventLogServerEncrypted.ts"
 
 /**
- * @since 4.0.0
+ * Creates encrypted event-log server `Storage` backed by SQL.
+ *
+ * It persists the server remote id, session authentication bindings, and encrypted
+ * entries in dialect-specific tables, creating per-identity/store entry tables as
+ * needed.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeStorage = (options?: {
   readonly entryTablePrefix?: string
@@ -287,8 +311,10 @@ const decodeSessionAuthBindings = (
 ): Effect.Effect<ReadonlyArray<SessionAuthBindingSql>, Schema.SchemaError> => decodeSessionAuthBindingRows(rows)
 
 /**
- * @since 4.0.0
+ * Provides encrypted server `Storage` using the SQL-backed implementation.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerStorage = (options?: {
   readonly entryTablePrefix?: string
@@ -301,8 +327,11 @@ export const layerStorage = (options?: {
 > => Layer.effect(EventLogServerEncrypted.Storage)(makeStorage(options))
 
 /**
- * @since 4.0.0
+ * Provides SQL-backed encrypted server `Storage` and supplies the default Web
+ * Crypto `EventLogEncryption` layer.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerStorageSubtle = (options?: {
   readonly entryTablePrefix?: string

package/src/unstable/eventlog/SqlEventLogServerUnencrypted.ts

@@ -1,4 +1,22 @@
 /**
+ * SQL-backed storage for an unencrypted event-log server.
+ *
+ * This module provides the persistence layer 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
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -15,8 +33,14 @@ import { Entry, EntryId, makeRemoteIdUnsafe, RemoteEntry, type RemoteId } from "
 import * as EventLogServerUnencrypted from "./EventLogServerUnencrypted.ts"
 
 /**
- * @since 4.0.0
+ * Creates unencrypted event-log server `Storage` backed by SQL.
+ *
+ * The implementation creates tables for the server remote id, store sequences,
+ * entries, and session authentication bindings, then persists and streams
+ * plaintext remote entries.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeStorage = (options?: {
   readonly entryTablePrefix?: string
@@ -424,8 +448,10 @@ export const makeStorage = (options?: {
   }).pipe(withTracerDisabled)
 
 /**
- * @since 4.0.0
+ * Provides unencrypted server `Storage` using the SQL-backed implementation.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerStorage = (options?: {
   readonly entryTablePrefix?: string