docs: Add initial Krescent documentation

This commit introduces the initial set of documentation for the Krescent framework,
generated based on existing KDoc comments in the codebase.

It includes:

- **Conceptual Documentation (`/docs/concepts/`):**
  - events.md
  - event-catalog.md
  - event-models.md
  - event-sourcing-strategies.md
  - event-sources.md
  - event-stream-processing.md
  - checkpointing.md

- **User Guides (`/docs/guide/`):**
  - installation.md (overhauled)
  - getting-started.md
  - creating-event-models.md
  - working-with-event-sources.md

- **VitePress Configuration (`/docs/.vitepress/config.mts`):**
  - Updated sidebar to include all new documentation pages.
  - Updated top navigation to link to the main guide.

The documentation aims to explain key concepts of the Krescent framework
and provide guidance on its usage.

Author: google-labs-jules[bot]

docs/.vitepress/config.mts

@@ -14,7 +14,7 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Examples', link: '/markdown-examples' }
+      { text: 'Guide', link: '/guide/installation' }
     ],
     search: {
       provider: "local"
@@ -25,10 +25,25 @@ export default defineConfig({
     },
 
     sidebar: [
+      {
+        text: 'Concepts',
+        items: [
+          { text: 'Events', link: '/concepts/events' },
+          { text: 'Event Catalog', link: '/concepts/event-catalog' },
+          { text: 'Event Stream Processing', link: '/concepts/event-stream-processing' },
+          { text: 'Event Sources', link: '/concepts/event-sources' },
+          { text: 'Event Sourcing Strategies', link: '/concepts/event-sourcing-strategies' },
+          { text: 'Event Models', link: '/concepts/event-models' },
+          { text: 'Checkpointing', link: '/concepts/checkpointing' }
+        ]
+      },
       {
         text: 'Guide',
         items: [
-          { text: 'Installation', link: '/guide/installation' }
+          { text: 'Installation', link: '/guide/installation' },
+          { text: 'Getting Started', link: '/guide/getting-started' },
+          { text: 'Creating Event Models', link: '/guide/creating-event-models' },
+          { text: 'Working with Event Sources', link: '/guide/working-with-event-sources' }
         ]
       }
     ],

docs/concepts/checkpointing.md

@@ -0,0 +1,36 @@
+---
+title: Checkpointing
+---
+
+Checkpointing in Krescent is a crucial optimization mechanism for event models. Its primary purpose is to periodically save the current state of an event model, along with the position (e.g., `StreamingToken`) of the last event processed to reach that state. This avoids the need to reprocess the entire event stream from the beginning every time the model is initialized or restarted.
+
+## `CheckpointStrategy`
+
+A `CheckpointStrategy` determines *when* a checkpoint should be taken. Krescent offers several built-in strategies:
+
+-   **`FixedEventRateCheckpointStrategy`**: Triggers a checkpoint after a fixed number of events have been processed. For example, checkpoint every 1000 events.
+-   **`FixedTimeRateCheckpointStrategy`**: Triggers a checkpoint after a fixed amount of time has elapsed since the last checkpoint. For example, checkpoint every 5 minutes.
+-   **`ManualCheckpointStrategy`**: Allows the application to trigger checkpoints programmatically based on custom logic or external signals. This provides the most flexibility but requires explicit management.
+
+## `CheckpointStorage`
+
+The `CheckpointStorage` interface defines *how* and *where* checkpoints are saved and loaded. Implementations of this interface are responsible for serializing the model's state and the associated `StreamingToken`, persisting them to a durable store (like a file system, database, or cloud storage), and retrieving them when needed.
+
+## `CheckpointSupport`
+
+`CheckpointSupport` is an interface that must be implemented by components (typically event models or parts of them) that can be checkpointed. It defines methods for:
+
+-   **`captureCheckpoint()`**: Returns the current state of the component to be saved.
+-   **`restoreCheckpoint(state: Any)`**: Restores the component's state from a previously saved checkpoint.
+
+## `CheckpointingEventSourceConsumer`
+
+The `CheckpointingEventSourceConsumer` is the component that orchestrates the checkpointing process for an event model. It works in conjunction with a `CheckpointStrategy` and `CheckpointStorage`. As it consumes events for the model, it monitors the chosen strategy. When the strategy indicates that a checkpoint is due, the consumer:
+
+1.  Pauses event processing temporarily.
+2.  Instructs the event model (which implements `CheckpointSupport`) to capture its current state.
+3.  Retrieves the `StreamingToken` of the last processed event.
+4.  Uses the `CheckpointStorage` to save the model's state and the token.
+5.  Resumes event processing.
+
+When the model is restarted, the `CheckpointingEventSourceConsumer` first attempts to load the latest checkpoint from `CheckpointStorage`. If successful, the model's state is restored, and event processing resumes from the token stored in the checkpoint, significantly reducing startup time.

docs/concepts/event-catalog.md

@@ -0,0 +1,23 @@
+---
+title: Event Catalog
+---
+
+The `EventCatalog` in Krescent is responsible for defining and managing all known event types within the system, as well as their serialization and deserialization.
+
+## `EventCatalogBuilder`
+
+Event types are registered with the `EventCatalog` using the `EventCatalogBuilder`. When registering an event, you provide:
+
+- **Name**: A unique string identifier for the event type.
+- **Serializer**: The serializer responsible for converting the event object to and from a persistent format.
+
+Krescent leverages Kotlinx Serialization for its robust and efficient serialization capabilities.
+
+## Encoding and Decoding
+
+The `EventCatalog` plays a crucial role in the event processing pipeline:
+
+- **Encoding**: It transforms typed `Event` objects into `EventMessage` objects. An `EventMessage` is a generic container that typically includes the event's type name and its serialized payload.
+- **Decoding**: Conversely, it takes an `EventMessage` and, using the registered event type name and serializer, decodes the payload back into the specific, typed `Event` object.
+
+This mechanism allows Krescent to handle diverse event types in a flexible and type-safe manner.

docs/concepts/event-models.md

@@ -0,0 +1,35 @@
+---
+title: Event Models
+---
+
+An `EventModel` in Krescent represents a state that is derived from a stream of events. It is a core concept for building applications that react to and are driven by events. Each `EventModel` consumes events through an `EventSourceConsumer`, which is responsible for feeding events from an `StreamingEventSource` to the model according to a chosen `EventSourcingStrategy`.
+
+## `EventModelBuilder` DSL
+
+Krescent provides a powerful Domain-Specific Language (DSL) through the `EventModelBuilder` for constructing and configuring event models. This builder allows you to declaratively define:
+
+-   **Event Handlers**: Functions that specify how the model's state changes in response to different types of events.
+-   **Extensions**: Custom functionalities that can be added to the model.
+-   **Checkpointing**: Strategies and storage mechanisms for saving and restoring the model's state.
+-   **Initial State**: The starting state of the model before any events are processed.
+
+## Types of Event Models
+
+Krescent distinguishes between two primary types of event models based on their purpose:
+
+### `ReadModelBase`
+
+`ReadModelBase` is designed for creating projections, queries, and read-only views of data. These models consume events to build up their state, which can then be queried by other parts of the application. They are optimized for efficient read access and do not publish new events.
+
+### `WriteModelBase`
+
+`WriteModelBase` is used for command handling and business logic that can result in the creation of new events. Like read models, they consume events to build their internal state. However, they also expose methods to:
+
+-   **`emitEvent(event: Event)`**: Tentatively stages a new event to be published. This event is not yet persisted or made available to other consumers.
+-   **`commitEvents()`**: Persists all staged events (those added via `emitEvent`) to the `EventPublisher`, making them part of the event stream and available for other models and consumers.
+
+`WriteModelBase` instances are central to implementing the command side of a CQRS (Command Query Responsibility Segregation) architecture.
+
+## `ModelExtension`
+
+`ModelExtension` provides a way to add custom, reusable functionality to event models. Extensions can hook into the model's lifecycle, access its state, and provide additional methods or behaviors. This allows for a clean separation of concerns and promotes modularity in model design. Examples could include logging, metrics collection, or specialized state management utilities.

docs/concepts/event-sources.md

@@ -0,0 +1,29 @@
+---
+title: Event Sources
+---
+
+Event Sources in Krescent are responsible for providing a replayable stream of events. They are fundamental to how event models reconstruct their state and how new events are introduced into the system.
+
+## `StreamingEventSource` Interface
+
+The primary interface for consuming events is `StreamingEventSource`. It defines the following key methods:
+
+- **`getHeadToken()`**: Returns a `StreamingToken` representing the beginning of the event stream.
+- **`getTailToken()`**: Returns a `StreamingToken` representing the current end (latest event) of the event stream.
+- **`fetchEventsAfter(token: StreamingToken, limit: Int)`**: Fetches a batch of events that occurred after the given `StreamingToken`, up to a specified `limit`.
+- **`streamEvents(token: StreamingToken, scope: CoroutineScope)`**: Returns a `Flow` of events that occur after the given `StreamingToken`. This allows for continuous consumption of new events as they arrive.
+
+A `StreamingToken` is an opaque marker that represents a specific position within the event stream, enabling consumers to resume event processing from a known point.
+
+## `ExtendedQueryableStreamingEventSource` Interface
+
+For more advanced querying capabilities, Krescent provides the `ExtendedQueryableStreamingEventSource` interface. It extends `StreamingEventSource` and adds methods such as:
+
+- Querying events by a specific time range.
+- Fetching a specific event by its unique ID.
+
+These capabilities are useful for scenarios requiring more targeted event retrieval beyond simple sequential streaming.
+
+## `EventPublisher` Interface
+
+Complementary to sourcing events, the `EventPublisher` interface is responsible for publishing new events into an event source. It typically provides methods to publish one or more events, which are then persisted and become available for consumption by `StreamingEventSource` implementations.

docs/concepts/event-sourcing-strategies.md

@@ -0,0 +1,17 @@
+---
+title: Event Sourcing Strategies
+---
+
+An `EventSourcingStrategy` in Krescent defines the specific approach for how events are fetched from a `StreamingEventSource` and subsequently processed by an `EventModel`. It dictates the lifecycle of event consumption for a model.
+
+Krescent provides several common strategies to suit different use cases:
+
+-   **`CatchupSourcingStrategy`**: This strategy is designed to process all available historical events from the `StreamingEventSource` up to the current tail of the stream. Once all historical events have been fetched and processed, the strategy stops. This is typically used for building projections or read models that only need a snapshot of the current state based on past events.
+
+-   **`StreamingSourcingStrategy`**: This strategy first fetches all historical events, similar to `CatchupSourcingStrategy`. However, after processing the historical events, it continues to listen for and process new events as they arrive in the `StreamingEventSource`. This is suitable for live, continuously updating models that need to react to new information in real-time.
+
+-   **`NoSourcingStrategy`**: This strategy is used when an `EventModel` should not process any events from the source. Instead, it's typically used to restore a model to its initial empty state or to a previously saved checkpointed state without replaying events. This can be useful for initializing models or for scenarios where state is managed externally.
+
+## `WriteCompatibleEventSourcingStrategy`
+
+A `WriteCompatibleEventSourcingStrategy` is a marker interface indicating that the strategy is compatible with `WriteModelBase` instances. These strategies are suitable for models that not only consume events but also produce new events as a result of command processing. Both `CatchupSourcingStrategy` and `StreamingSourcingStrategy` can be write-compatible, allowing write models to build their state and then process commands that generate further events.

docs/concepts/event-stream-processing.md

@@ -0,0 +1,26 @@
+---
+title: Event Stream Processing
+---
+
+Event stream processing in Krescent involves the continuous handling and transformation of sequences of events.
+
+## `EventStreamProcessor` Interface
+
+The core of event stream processing in Krescent is the `EventStreamProcessor` interface. This interface defines the fundamental contract for components that consume and process streams of events. Implementations of this interface are responsible for handling events as they arrive, performing computations, and potentially generating new events.
+
+## `EventMessageStreamProcessor`
+
+For processing raw event messages before they are deserialized into typed events, Krescent provides the `EventMessageStreamProcessor`. This processor operates on `EventMessage` objects, allowing for early-stage filtering, routing, or transformation based on message metadata or payload structure before the full deserialization cost is incurred.
+
+## `TransformingModelEventProcessor`
+
+The `TransformingModelEventProcessor` is a key component that leverages the `EventCatalog`. Its primary function is to:
+
+1.  **Deserialize**: Take an incoming `EventMessage` and use the `EventCatalog` to deserialize its payload into a specific, typed `Event` object.
+2.  **Broadcast**: After successful deserialization, it broadcasts the typed `Event` to other interested downstream processors.
+
+This processor acts as a bridge, converting raw event data into meaningful, domain-specific event objects.
+
+## `BroadcastEventStreamProcessor`
+
+The `BroadcastEventStreamProcessor` serves to distribute events to multiple downstream `EventStreamProcessor` instances. When an event is received by the `BroadcastEventStreamProcessor`, it forwards the event to all registered downstream processors, enabling parallel processing or fan-out scenarios. This is useful when multiple independent components need to react to the same event.

docs/concepts/events.md

@@ -0,0 +1,35 @@
+---
+title: Events
+---
+
+Events in Krescent are immutable facts that represent something that has happened in the system. They are the primary building blocks of Krescent's event-driven architecture.
+
+## Base `Event` Class
+
+All events in Krescent inherit from a base `Event` class. This class provides common functionality and a consistent structure for all events.
+
+## `EventMetadata`
+
+Every event carries metadata, which is encapsulated in the `EventMetadata` class. This metadata includes:
+
+- **id**: A unique identifier for the event.
+- **type**: The type of the event.
+- **timestamp**: The time at which the event occurred.
+- **position**: The position of the event in the event stream.
+
+## Physical vs. Virtual Events
+
+Krescent distinguishes between two main types of events:
+
+- **Physical Events**: These represent actual occurrences in the system, such as a user action or a sensor reading.
+- **`VirtualEvent`**: These are events that are derived or generated by the system itself, often as a result of processing physical events.
+
+## `SystemEvent`
+
+`SystemEvent`s are a special category of events used by Krescent for internal purposes. Some examples include:
+
+- **`SystemStreamHeadEvent`**: Indicates the beginning of an event stream.
+- **`SystemStreamTailEvent`**: Indicates the end of an event stream.
+- **`SystemHintCommitTransactionEvent`**: Provides a hint to commit a transaction, often used in scenarios involving transactional event processing.
+
+These system events help manage and coordinate the flow of events within Krescent.