@powerhousedao/academy 5.0.0-staging.8 → 5.0.1-staging.2

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/03-SpecifyDocumentOperations.md

@@ -8,9 +8,9 @@ In Powerhouse, document models adhere to event sourcing principles. This means t
 
 For example, in our `To-do List` document model, operations might include:
 
-*   `ADD_TODO_ITEM`: To add a new task.
-*   `UPDATE_TODO_ITEM`: To modify an existing task (e.g., change its text or mark it as completed).
-*   `DELETE_TODO_ITEM`: To remove a task.
+- `ADD_TODO_ITEM`: To add a new task.
+- `UPDATE_TODO_ITEM`: To modify an existing task (e.g., change its text or mark it as completed).
+- `DELETE_TODO_ITEM`: To remove a task.
 
 Each operation acts as a command that, when applied, transitions the document from one state to the next. The complete history of these operations defines the document's journey to its current state.
 
@@ -40,9 +40,9 @@ input DeleteTodoItemInput {
 
 These `input` types are not just abstract definitions; they are the **specifications for our document operations**.
 
-*   **`AddTodoItemInput`** specifies that to execute an `ADD_TODO_ITEM` operation, we need an `id` and `text` for the new item.
-*   **`UpdateTodoItemInput`** specifies that for an `UPDATE_TODO_ITEM` operation, we need the `id` of the item to update, and optionally new `text` or a `checked` status.
-*   **`DeleteTodoItemInput`** specifies that a `DELETE_TODO_ITEM` operation requires the `id` of the item to be removed.
+- **`AddTodoItemInput`** specifies that to execute an `ADD_TODO_ITEM` operation, we need an `id` and `text` for the new item.
+- **`UpdateTodoItemInput`** specifies that for an `UPDATE_TODO_ITEM` operation, we need the `id` of the item to update, and optionally new `text` or a `checked` status.
+- **`DeleteTodoItemInput`** specifies that a `DELETE_TODO_ITEM` operation requires the `id` of the item to be removed.
 
 The Powerhouse Connect application uses these GraphQL input types when you define operations within a module (e.g., the `to_do_list` module with operations `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`).
 
@@ -51,36 +51,40 @@ The Powerhouse Connect application uses these GraphQL input types when you defin
 Careful design of your document operations is crucial for a robust and maintainable document model. Here are some key considerations:
 
 ### 1. Granularity
+
 Operations should be granular enough to represent distinct user intentions or logical changes.
 
-*   **Too coarse:** An operation like `MODIFY_TODOLIST` that takes a whole new list of items would be too broad. It would be hard to track specific changes and could lead to complex reducer logic.
-*   **Too fine:** While possible, having separate operations like `SET_TODO_ITEM_TEXT` and `SET_TODO_ITEM_CHECKED_STATUS` might be overly verbose if these are often updated together. `UPDATE_TODO_ITEM` with optional fields offers a good balance.
-*   **Just right:** The `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, and `DELETE_TODO_ITEM` operations for our `ToDoList` are good examples. They represent clear, atomic changes.
+- **Too coarse:** An operation like `MODIFY_TODOLIST` that takes a whole new list of items would be too broad. It would be hard to track specific changes and could lead to complex reducer logic.
+- **Too fine:** While possible, having separate operations like `SET_TODO_ITEM_TEXT` and `SET_TODO_ITEM_CHECKED_STATUS` might be overly verbose if these are often updated together. `UPDATE_TODO_ITEM` with optional fields offers a good balance.
+- **Just right:** The `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, and `DELETE_TODO_ITEM` operations for our `ToDoList` are good examples. They represent clear, atomic changes.
 
 ### 2. Naming conventions
+
 Clear and consistent naming makes your operations understandable. A common convention is `VERB_NOUN` or `VERB_NOUN_SUBJECT`.
 
-*   Examples: `ADD_ITEM`, `UPDATE_USER_PROFILE`, `ASSIGN_TASK_TO_USER`.
-*   In our case: `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`.
+- Examples: `ADD_ITEM`, `UPDATE_USER_PROFILE`, `ASSIGN_TASK_TO_USER`.
+- In our case: `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`.
 
 The name you provide in the Connect UI (e.g., `ADD_TODO_ITEM`) directly corresponds to the operation type that will be recorded and that your reducers will handle.
 
 ### 3. Input types (payloads)
+
 The input type for an operation (its payload) should contain all the necessary information to perform that operation, and nothing more.
 
-*   **Completeness:** If an operation needs a user ID to authorize a change, include it in the input.
-*   **Conciseness:** Avoid including data that isn't directly used by the operation.
-*   **Clarity:** Use descriptive field names within your input types. `action.input.text` is clearer than `action.input.t`.
+- **Completeness:** If an operation needs a user ID to authorize a change, include it in the input.
+- **Conciseness:** Avoid including data that isn't directly used by the operation.
+- **Clarity:** Use descriptive field names within your input types. `action.input.text` is clearer than `action.input.t`.
 
 The GraphQL `input` types we defined earlier (`AddTodoItemInput`, `UpdateTodoItemInput`, `DeleteTodoItemInput`) serve precisely this purpose. They ensure that whoever triggers an operation provides the correct data in the correct format.
 
 ### 4. Immutability and pure functions
-While not specified in the operation definition itself, remember that the *implementation* of these operations (the reducers) should treat state as immutable and behave as pure functions. The operation specification (input type) provides the data for these pure functions.
+
+While not specified in the operation definition itself, remember that the _implementation_ of these operations (the reducers) should treat state as immutable and behave as pure functions. The operation specification (input type) provides the data for these pure functions.
 
 ## Role in event sourcing and CQRS
 
-*   **Events:** Each successfully executed operation is recorded as an event in the document's history. This history provides an audit trail and allows for replaying events to reconstruct state, which is invaluable for debugging and understanding how a document evolved.
-*   **Commands:** Document operations are essentially "commands" in a Command Query Responsibility Segregation (CQRS) pattern. They represent an intent to change the state. The processing of this command (by the reducer) leads to one or more events being stored and the state being updated.
+- **Events:** Each successfully executed operation is recorded as an event in the document's history. This history provides an audit trail and allows for replaying events to reconstruct state, which is invaluable for debugging and understanding how a document evolved.
+- **Commands:** Document operations are essentially "commands" in a Command Query Responsibility Segregation (CQRS) pattern. They represent an intent to change the state. The processing of this command (by the reducer) leads to one or more events being stored and the state being updated.
 
 ## From specification to implementation
 
@@ -95,7 +99,7 @@ The generated code from `ph generate` (as seen in `03-ImplementOperationReducers
 For example, the `ToDoListToDoListOperations` type generated by Powerhouse will expect methods corresponding to `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`.
 
 ```typescript
-import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
+import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js";
 
 export const reducer: ToDoListToDoListOperations = {
   addTodoItemOperation(state, action, dispatch) {
@@ -121,12 +125,12 @@ Assuming you have already defined the state schema for the `To-do List` as cover
 
 1.  **Create a Module for Operations:**
     Below the schema editor in Connect, find the input field labeled `Add module`. Modules help organize your operations.
-    *   Type `to_do_list` into the field and press Enter.
+    - Type `to_do_list` into the field and press Enter.
 
 2.  **Add the `ADD_TODO_ITEM` Operation:**
     A new field, `Add operation`, will appear under your new module.
-    *   Type `ADD_TODO_ITEM` into this field and press Enter.
-    *   An editor will appear for the operation's input type. You need to define the data required for this operation. Paste the following GraphQL `input` definition into the editor:
+    - Type `ADD_TODO_ITEM` into this field and press Enter.
+    - An editor will appear for the operation's input type. You need to define the data required for this operation. Paste the following GraphQL `input` definition into the editor:
 
     ```graphql
     # Defines a GraphQL input type for adding a new to-do item
@@ -137,8 +141,8 @@ Assuming you have already defined the state schema for the `To-do List` as cover
     ```
 
 3.  **Add the `UPDATE_TODO_ITEM` Operation:**
-    *   In the `Add operation` field again, type `UPDATE_TODO_ITEM` and press Enter.
-    *   Paste the corresponding `input` definition into its editor:
+    - In the `Add operation` field again, type `UPDATE_TODO_ITEM` and press Enter.
+    - Paste the corresponding `input` definition into its editor:
 
     ```graphql
     # Defines a GraphQL input type for updating a to-do item
@@ -150,8 +154,8 @@ Assuming you have already defined the state schema for the `To-do List` as cover
     ```
 
 4.  **Add the `DELETE_TODO_ITEM` Operation:**
-    *   Finally, type `DELETE_TODO_ITEM` in the `Add operation` field and press Enter.
-    *   Paste its `input` definition:
+    - Finally, type `DELETE_TODO_ITEM` in the `Add operation` field and press Enter.
+    - Paste its `input` definition:
 
     ```graphql
     # Defines a GraphQL input type for deleting a to-do item

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/04-UseTheDocumentModelGenerator.md

@@ -39,45 +39,43 @@ The generator creates a new directory specific to your document model, usually l
 For example, using `Invoice.phdm.zip` would result in a directory structure under `document-models/invoice/`. Inside this directory, you will find:
 
 1.  **`spec.json` (or similar JSON representation):**
-    *   **Purpose:** This file is a JSON representation of your document model specification, derived directly from the `.phdm.zip` file. It contains the parsed schema, operation definitions, document type, and other metadata.
-    *   **Significance:** It serves as the canonical, machine-readable definition of your model within the project, which other tools or processes might reference.
+    - **Purpose:** This file is a JSON representation of your document model specification, derived directly from the `.phdm.zip` file. It contains the parsed schema, operation definitions, document type, and other metadata.
+    - **Significance:** It serves as the canonical, machine-readable definition of your model within the project, which other tools or processes might reference.
 
 2.  **`schema.graphql`:**
-    *   **Purpose:** This file contains the raw GraphQL Schema Definition Language (SDL) for both the state and operations of your document model, exactly as you defined it in Connect.
-    *   **Significance:** Provides a human-readable reference of the schema and can be useful for quick checks or for tools that might directly consume GraphQL SDL.
+    - **Purpose:** This file contains the raw GraphQL Schema Definition Language (SDL) for both the state and operations of your document model, exactly as you defined it in Connect.
+    - **Significance:** Provides a human-readable reference of the schema and can be useful for quick checks or for tools that might directly consume GraphQL SDL.
 
 3.  **The `gen/` Directory (Generated Code):**
     This directory is pivotal as it houses all the code automatically generated by the tool. **You should generally avoid manually editing files within the `gen/` directory**, as they will be overwritten if you regenerate the model.
     Key files within `gen/` include:
+    - **`types.ts`:**
+      - **Purpose:** Contains TypeScript interfaces and type definitions derived from your GraphQL schema. This includes types for your document's state (e.g., `InvoiceState`), any complex types used within the state (e.g., `LineItem`), and types for the inputs of each defined operation (e.g., `AddLineItemInput`).
+      - **Significance:** This is the cornerstone of type safety in your document model implementation. By using these generated types, you ensure that your reducer logic and any client-side interactions adhere to the defined data structures, catching errors at compile-time rather than runtime.
 
-    *   **`types.ts`:**
-        *   **Purpose:** Contains TypeScript interfaces and type definitions derived from your GraphQL schema. This includes types for your document's state (e.g., `InvoiceState`), any complex types used within the state (e.g., `LineItem`), and types for the inputs of each defined operation (e.g., `AddLineItemInput`).
-        *   **Significance:** This is the cornerstone of type safety in your document model implementation. By using these generated types, you ensure that your reducer logic and any client-side interactions adhere to the defined data structures, catching errors at compile-time rather than runtime.
+    - **`operations.ts` (or `creators.ts`, `actions.ts`):**
+      - **Purpose:** This file exports "action creator" functions for each operation defined in your schema. These functions take the input parameters for an operation and return a correctly structured action object that can be processed by the reducer system.
+      - **Significance:** Action creators simplify the process of creating and dispatching operations, reduce the likelihood of errors in action formatting, and improve code readability. For example, instead of manually constructing an action object like `{ type: "ADD_LINE_ITEM", input: { ... } }`, you'd use a function like `creators.addLineItem({ ... })`.
 
-    *   **`operations.ts` (or `creators.ts`, `actions.ts`):**
-        *   **Purpose:** This file exports "action creator" functions for each operation defined in your schema. These functions take the input parameters for an operation and return a correctly structured action object that can be processed by the reducer system.
-        *   **Significance:** Action creators simplify the process of creating and dispatching operations, reduce the likelihood of errors in action formatting, and improve code readability. For example, instead of manually constructing an action object like `{ type: "ADD_LINE_ITEM", input: { ... } }`, you'd use a function like `creators.addLineItem({ ... })`.
+    - **`utils.ts`:**
+      - **Purpose:** Often includes utility functions related to your document model. A common utility is a function to create an empty or initial instance of your document (e.g., `utils.createDocument()`). This is based on the default values and structure defined in your state schema.
+      - **Significance:** Provides convenient helpers for common tasks, particularly for initializing new documents in tests or application code.
 
-    *   **`utils.ts`:**
-        *   **Purpose:** Often includes utility functions related to your document model. A common utility is a function to create an empty or initial instance of your document (e.g., `utils.createDocument()`). This is based on the default values and structure defined in your state schema.
-        *   **Significance:** Provides convenient helpers for common tasks, particularly for initializing new documents in tests or application code.
-
-    *   **`reducer.ts` (or similar, defining the reducer interface/skeleton):**
-        *   **Purpose:** This file might contain a TypeScript interface or a skeleton object that your actual reducer implementation (in the `src/` directory) will need to conform to. It outlines the expected shape of the reducer map, ensuring that you provide an implementation for every defined operation.
-        *   **Significance:** Guides the implementation of your reducers and helps maintain consistency, ensuring that all defined operations are accounted for.
+    - **`reducer.ts` (or similar, defining the reducer interface/skeleton):**
+      - **Purpose:** This file might contain a TypeScript interface or a skeleton object that your actual reducer implementation (in the `src/` directory) will need to conform to. It outlines the expected shape of the reducer map, ensuring that you provide an implementation for every defined operation.
+      - **Significance:** Guides the implementation of your reducers and helps maintain consistency, ensuring that all defined operations are accounted for.
 
 4.  **The `src/` Directory (Source Code for Your Implementation):**
     This directory is where you, the developer, will write the custom logic for your document model. Unlike the `gen/` directory, files here are meant to be manually edited.
-
-    *   **`reducers/`:**
-        *   **`your-model-name.ts` (e.g., `invoice.ts`):** This is the most important file you'll work with after generation. It's where you implement the **reducer functions** for each operation. The generator usually creates a skeleton file with function stubs for each operation, which you then fill in with the actual state transition logic.
-        *   **Significance:** This is the heart of your document model's behavior, defining how the state changes in response to each operation. The next step in the Mastery Track will typically focus on implementing these reducers.
-    *   **`reducers/tests/`:**
-        *   **`your-model-name.test.ts` (e.g., `invoice.test.ts`):** A placeholder or basic test file is often generated here, encouraging you to write unit tests for your reducer logic.
-        *   **Significance:** Emphasizes the importance of testing your document model's core logic to ensure correctness and reliability.
-    *   **`utils/` (optional):**
-        *   **Purpose:** You can create this directory for any custom utility functions specific to your document model's implementation that don't fit directly into the reducers.
-        *   **Significance:** Helps in organizing shared logic or complex computations that might be used across multiple reducers or other parts of your model's ecosystem.
+    - **`reducers/`:**
+      - **`your-model-name.ts` (e.g., `invoice.ts`):** This is the most important file you'll work with after generation. It's where you implement the **reducer functions** for each operation. The generator usually creates a skeleton file with function stubs for each operation, which you then fill in with the actual state transition logic.
+      - **Significance:** This is the heart of your document model's behavior, defining how the state changes in response to each operation. The next step in the Mastery Track will typically focus on implementing these reducers.
+    - **`reducers/tests/`:**
+      - **`your-model-name.test.ts` (e.g., `invoice.test.ts`):** A placeholder or basic test file is often generated here, encouraging you to write unit tests for your reducer logic.
+      - **Significance:** Emphasizes the importance of testing your document model's core logic to ensure correctness and reliability.
+    - **`utils/` (optional):**
+      - **Purpose:** You can create this directory for any custom utility functions specific to your document model's implementation that don't fit directly into the reducers.
+      - **Significance:** Helps in organizing shared logic or complex computations that might be used across multiple reducers or other parts of your model's ecosystem.
 
 ## Benefits of using the document model generator
 
@@ -101,27 +99,28 @@ This tutorial assumes you have completed the previous steps in this Mastery Trac
 
 ### Prerequisites
 
-*   **`ToDoList.phdm.zip` file**: You must have the document model specification file exported from Connect. If you do not have this file, please revisit the previous sections on specifying the state schema and operations.
+- **`ToDoList.phdm.zip` file**: You must have the document model specification file exported from Connect. If you do not have this file, please revisit the previous sections on specifying the state schema and operations.
 
 ### Steps
 
 1.  **Place the Specification File in Your Project**:
-    *   Navigate to the root directory of your Powerhouse project.
-    *   Move or copy your `ToDoList.phdm.zip` file into this directory.
+    - Navigate to the root directory of your Powerhouse project.
+    - Move or copy your `ToDoList.phdm.zip` file into this directory.
 
 2.  **Run the Generator Command**:
-    *   Open your terminal in the root directory of your Powerhouse project.
-    *   Execute the `ph generate` command, pointing to your specification file:
+    - Open your terminal in the root directory of your Powerhouse project.
+    - Execute the `ph generate` command, pointing to your specification file:
+
     ```bash
     ph generate ToDoList.phdm.zip
     ```
 
 3.  **Explore the Generated Files**:
-    *   After the command completes successfully, you will find a new directory: `document-models/to-do-list/`.
-    *   Take a moment to explore its contents, which will match the structure described earlier in this document:
-        *   `spec.json` and `schema.graphql`: The definition of your model.
-        *   `gen/`: Type-safe, generated code including `types.ts`, `operations.ts`, etc.
-        *   `src/`: The skeleton for your implementation, most importantly `src/reducers/to-do-list.ts`, which will contain empty functions for `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`, ready for you to implement.
+    - After the command completes successfully, you will find a new directory: `document-models/to-do-list/`.
+    - Take a moment to explore its contents, which will match the structure described earlier in this document:
+      - `spec.json` and `schema.graphql`: The definition of your model.
+      - `gen/`: Type-safe, generated code including `types.ts`, `operations.ts`, etc.
+      - `src/`: The skeleton for your implementation, most importantly `src/reducers/to-do-list.ts`, which will contain empty functions for `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`, ready for you to implement.
 
 With these files generated, you have successfully scaffolded your document model. The project is now set up for you to implement the core business logic.
 

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/05-ImplementDocumentReducers.md

@@ -4,7 +4,7 @@
 
 In our journey through Powerhouse Document Model creation, we've defined the "what" – the structure of our data ([State Schema](02-SpecifyTheStateSchema.md)) and the ways it can be changed ([Document Operations](03-SpecifyDocumentOperations.md)). We've also seen how the [Document Model Generator](04-UseTheDocumentModelGenerator.md) translates these specifications into a coded scaffold. Now, we arrive at the "how": implementing **Document Reducers**.
 
-Reducers are the core logic units of your document model. They are the functions that take the current state of your document and an operation (an "action"), and then determine the *new* state of the document. They are the embodiment of your business rules and the engine that drives state transitions in a predictable, auditable, and immutable way.
+Reducers are the core logic units of your document model. They are the functions that take the current state of your document and an operation (an "action"), and then determine the _new_ state of the document. They are the embodiment of your business rules and the engine that drives state transitions in a predictable, auditable, and immutable way.
 
 ## Recap: The journey to reducer implementation
 
@@ -24,22 +24,22 @@ In the context of Powerhouse and inspired by patterns like Redux, a reducer is a
 
 Let's break down its components and principles:
 
-*   **`currentState`**: This is the complete, current state of your document model instance before the operation is applied. It's crucial to treat this as **immutable**.
-*   **`action`**: This is an object describing the operation to be performed. It typically has:
-    *   A `type` property: A string identifying the operation (e.g., `'ADD_TODO_ITEM'`).
-    *   An `input` property (or similar, like `payload`): An object containing the data necessary for the operation, matching the GraphQL `input` type you defined (e.g., `{ id: '1', text: 'Buy groceries' }` for `AddTodoItemInput`).
-*   **`newState`**: The reducer must return a *new* state object representing the state after the operation has been applied. If the operation does not result in a state change, the reducer should return the `currentState` object itself.
+- **`currentState`**: This is the complete, current state of your document model instance before the operation is applied. It's crucial to treat this as **immutable**.
+- **`action`**: This is an object describing the operation to be performed. It typically has:
+  - A `type` property: A string identifying the operation (e.g., `'ADD_TODO_ITEM'`).
+  - An `input` property (or similar, like `payload`): An object containing the data necessary for the operation, matching the GraphQL `input` type you defined (e.g., `{ id: '1', text: 'Buy groceries' }` for `AddTodoItemInput`).
+- **`newState`**: The reducer must return a _new_ state object representing the state after the operation has been applied. If the operation does not result in a state change, the reducer should return the `currentState` object itself.
 
 ### Key principles guiding reducer implementation:
 
 1.  **Purity**:
-    *   **Deterministic**: Given the same `currentState` and `action`, a reducer must *always* produce the same `newState`.
-    *   **No Side Effects**: Reducers must not perform any side effects. This means no API calls, no direct DOM manipulation, no `Math.random()` (unless seeded deterministically for specific testing scenarios), and no modification of variables outside their own scope. Their sole job is to compute the next state.
+    - **Deterministic**: Given the same `currentState` and `action`, a reducer must _always_ produce the same `newState`.
+    - **No Side Effects**: Reducers must not perform any side effects. This means no API calls, no direct DOM manipulation, no `Math.random()` (unless seeded deterministically for specific testing scenarios), and no modification of variables outside their own scope. Their sole job is to compute the next state.
 
 2.  **Immutability**:
-    *   **Never Mutate `currentState`**: You must never directly modify the `currentState` object or any of its nested properties.
-    *   **Always Return a New Object for Changes**: If the state changes, you must create and return a brand new object. If the state does not change, you return the original `currentState` object.
-    *   This is fundamental to Powerhouse's event sourcing architecture, enabling time travel, efficient change detection, and a clear audit trail. We'll explore techniques for immutability shortly.
+    - **Never Mutate `currentState`**: You must never directly modify the `currentState` object or any of its nested properties.
+    - **Always Return a New Object for Changes**: If the state changes, you must create and return a brand new object. If the state does not change, you return the original `currentState` object.
+    - This is fundamental to Powerhouse's event sourcing architecture, enabling time travel, efficient change detection, and a clear audit trail. We'll explore techniques for immutability shortly.
 
 3.  **Single Source of Truth**: The document state managed by reducers is the single source of truth for that document instance. All UI rendering and data queries are derived from this state.
 
@@ -47,8 +47,8 @@ Let's break down its components and principles:
     While you can write one large reducer that uses a `switch` statement or `if/else if` blocks based on `action.type`, Powerhouse's generated code typically encourages a more modular approach. You'll often implement a separate function for each operation, which are then combined into a main reducer object or map. The `ph generate` command usually sets up this structure for you. For example, in your `document-models/to-do-list/src/reducers/to-do-list.ts`, you'll find an object structure like this:
 
     ```typescript
-    import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js'; // Generated type for operations
-    import { ToDoListState } from '../../gen/types.js'; // Generated type for state
+    import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js"; // Generated type for operations
+    import { ToDoListState } from "../../gen/types.js"; // Generated type for state
 
     export const reducer: ToDoListToDoListOperations = {
       addTodoItemOperation(state: ToDoListState, action, dispatch) {
@@ -69,6 +69,7 @@ Let's break down its components and principles:
       // ... other operations
     };
     ```
+
     The `ToDoListToDoListOperations` type (or similar, depending on your model name) is generated by Powerhouse and ensures your reducer object correctly implements all defined operations. The `state` and `action` parameters within these methods will also be strongly typed based on your schema.
 
     The `dispatch` parameter is an advanced feature allowing a reducer to trigger subsequent operations. While powerful for complex workflows, it's often not needed for basic operations and can be ignored if unused.
@@ -78,6 +79,7 @@ Let's break down its components and principles:
 Let's use our familiar `ToDoList` example to illustrate common patterns. For this example, we'll assume our state schema has been updated to include a `stats` object to track the number of total, checked, and unchecked items.
 
 Our `ToDoListState` now looks like this:
+
 ```typescript
 interface ToDoItem {
   id: string;
@@ -98,9 +100,10 @@ interface ToDoListState {
 ```
 
 And our action creators (from `../../gen/creators` or `../../gen/operations.js`) provide actions like:
-*   `actions.addTodoItem({ id: 'some-id', text: 'New Task' })`
-*   `actions.updateTodoItem({ id: 'item-id', text: 'Updated Task Text', checked: true })`
-*   `actions.deleteTodoItem({ id: 'item-id' })`
+
+- `actions.addTodoItem({ id: 'some-id', text: 'New Task' })`
+- `actions.updateTodoItem({ id: 'item-id', text: 'Updated Task Text', checked: true })`
+- `actions.deleteTodoItem({ id: 'item-id' })`
 
 ### 1. Adding an item (e.g., `addTodoItemOperation`)
 
@@ -121,9 +124,11 @@ addTodoItemOperation(state: ToDoListState, action: /* AddTodoItemActionType */ a
   };
 }
 ```
+
 **Explanation**:
-*   We use the spread operator (`...state`) to copy top-level properties from the old state into the new state object.
-*   For the `items` array, we create a *new* array by spreading the existing `state.items` and then appending the `newItem`.
+
+- We use the spread operator (`...state`) to copy top-level properties from the old state into the new state object.
+- For the `items` array, we create a _new_ array by spreading the existing `state.items` and then appending the `newItem`.
 
 ### 2. Updating an item (e.g., `updateTodoItemOperation`)
 
@@ -152,16 +157,19 @@ updateTodoItemOperation(state: ToDoListState, action: /* UpdateTodoItemActionTyp
   };
 }
 ```
+
 **Explanation**:
-*   We use the `map` array method, which always returns a *new* array.
-*   For the item that matches `action.input.id`, we create a new item object using the spread operator (`...item`) and then overwrite the properties (`text`, `checked`) that are present in `action.input`.
-*   The conditional spread (`...(condition && { property: value })`) is a concise way to only include a property in the new object if its corresponding input value is provided. This elegantly handles partial updates.
-*   If an item doesn't match the ID, it's returned as is.
+
+- We use the `map` array method, which always returns a _new_ array.
+- For the item that matches `action.input.id`, we create a new item object using the spread operator (`...item`) and then overwrite the properties (`text`, `checked`) that are present in `action.input`.
+- The conditional spread (`...(condition && { property: value })`) is a concise way to only include a property in the new object if its corresponding input value is provided. This elegantly handles partial updates.
+- If an item doesn't match the ID, it's returned as is.
 
 **Error Handling Note**: In a real application, you might want to add a check to see if an item with `action.input.id` actually exists. If not, you could throw an error or handle it according to your application's requirements:
+
 ```typescript
 // Inside updateTodoItemOperation, before returning:
-const itemToUpdate = state.items.find(item => item.id === action.input.id);
+const itemToUpdate = state.items.find((item) => item.id === action.input.id);
 if (!itemToUpdate) {
   // Option 1: Throw an error (Powerhouse runtime might catch this)
   throw new Error(`Item with id ${action.input.id} not found.`);
@@ -186,8 +194,10 @@ deleteTodoItemOperation(state: ToDoListState, action: /* DeleteTodoItemActionTyp
   };
 }
 ```
+
 **Explanation**:
-*   We use the `filter` array method, which returns a *new* array containing only the elements for which the callback function returns `true`.
+
+- We use the `filter` array method, which returns a _new_ array containing only the elements for which the callback function returns `true`.
 
 ## Leveraging generated types
 
@@ -200,8 +210,8 @@ import {
   ToDoListState,
   AddTodoItemInput, // Generated input type
   // ... other types
-} from '../../gen/types.js';
-import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js'; // Generated operations type
+} from "../../gen/types.js";
+import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js"; // Generated operations type
 
 // Define the type for the action more explicitly if needed, or rely on inferred types
 // from ToDoListToDoListOperations. For complex actions, defining specific action types can be beneficial.
@@ -212,7 +222,11 @@ import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
 // }
 
 export const reducer: ToDoListToDoListOperations = {
-  addTodoItemOperation(state: ToDoListState, action: { input: AddTodoItemInput /* plus type property */ }, dispatch) {
+  addTodoItemOperation(
+    state: ToDoListState,
+    action: { input: AddTodoItemInput /* plus type property */ },
+    dispatch,
+  ) {
     // Now 'action.input.text' and 'action.input.id' are type-checked
     const newItem = {
       id: action.input.id,
@@ -227,10 +241,12 @@ export const reducer: ToDoListToDoListOperations = {
   // ... other reducers
 };
 ```
+
 Using these types provides:
-*   **Compile-time safety**: Catch errors related to incorrect property names or data types before runtime.
-*   **Autocompletion and IntelliSense**: Improved developer experience in your IDE.
-*   **Clearer code**: Types serve as documentation for the expected data structures.
+
+- **Compile-time safety**: Catch errors related to incorrect property names or data types before runtime.
+- **Autocompletion and IntelliSense**: Improved developer experience in your IDE.
+- **Clearer code**: Types serve as documentation for the expected data structures.
 
 ## Practical implementation: Writing the `ToDoList` reducers
 
@@ -246,87 +262,89 @@ This tutorial assumes you have followed the steps in the previous chapters, espe
 Navigate to `document-models/to-do-list/src/reducers/to-do-list.ts`. The generator will have created a skeleton file. Replace its contents with the following logic.
 
 ```typescript
-import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
-import { ToDoListState } from '../../gen/types.js'; // Assuming this now includes the 'stats' object
+import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js";
+import { ToDoListState } from "../../gen/types.js"; // Assuming this now includes the 'stats' object
 
 // REMARKS: This is our main reducer object. It implements all operations defined in the schema.
 // The ToDoListToDoListOperations type is auto-generated from our GraphQL specification and ensures type safety.
 export const reducer: ToDoListToDoListOperations = {
-    // REMARKS: The addTodoItemOperation adds a new item and updates our tracking statistics.
-    // - state: The current document state. Powerhouse uses a library like Immer.js,
-    //   so you can write code that looks like it's mutating the state directly.
-    //   Behind the scenes, Powerhouse ensures this results in an immutable update.
-    // - action: Contains the operation's 'type' and 'input' data from the client.
-    // - dispatch: A function to trigger subsequent operations (advanced, not used here).
-    addTodoItemOperation(state, action, dispatch) {
-        // REMARKS: We update our statistics for total and unchecked items.
-        state.stats.total += 1;
-        state.stats.unchecked += 1;
-
-        // REMARKS: We push the new to-do item into the items array.
-        // The data for the new item comes from the operation's input.
-        state.items.push({
-            id: action.input.id,
-            text: action.input.text,
-            checked: false, // New items always start as unchecked.
-        });
-    },
-
-    // REMARKS: The updateTodoItemOperation modifies an existing to-do item.
-    // It handles partial updates for text and checked status.
-    updateTodoItemOperation(state, action, dispatch) {
-        // REMARKS: First, we find the specific item we want to update using its ID.
-        const item = state.items.find(item => item.id === action.input.id);
-        
-        // REMARKS: It's good practice to handle cases where the item might not be found.
-        if (!item) {
-            throw new Error(`Item with id ${action.input.id} not found`);
-        }
-        
-        // REMARKS: We only update the text if it was provided in the input.
-        // This allows for partial updates (e.g., just checking an item without changing its text).
-        if (action.input.text) {
-            item.text = action.input.text;
-        }
-
-        // REMARKS: When the checked status changes, we also update our statistics.
-        // We check for `true` and `false` explicitly.
-        if (action.input.checked) { // This is true only if action.input.checked is true
-            // Note: This assumes the item was previously unchecked. For a more robust implementation,
-            // you could check `if (item.checked === false)` before updating stats to prevent inconsistencies.
-            state.stats.unchecked -= 1;
-            state.stats.checked += 1;
-            item.checked = action.input.checked;
-        }
-        if (action.input.checked === false) {
-            // Note: This assumes the item was previously checked.
-            state.stats.unchecked += 1;
-            state.stats.checked -= 1;
-            item.checked = action.input.checked;
-        }
-    },
-
-    // REMARKS: The deleteTodoItemOperation removes an item from the list.
-    deleteTodoItemOperation(state, action, dispatch) {
-        // REMARKS: Before removing the item, we find it to determine its checked status.
-        // This is necessary to correctly decrement our statistics.
-        const item = state.items.find(item => item.id === action.input.id);
-
-        // REMARKS: We always decrement the total count.
-        state.stats.total -= 1;
-
-        // REMARKS: We then decrement the 'checked' or 'unchecked' count based on the item's status.
-        if (item?.checked) { // This is shorthand for item?.checked === true
-            state.stats.checked -= 1;
-        }
-        if (item?.checked === false) {
-            state.stats.unchecked -= 1;
-        }
-
-        // REMARKS: Finally, we create a new 'items' array that excludes the deleted item.
-        // Assigning to 'state.items' is handled by Powerhouse to produce a new immutable state.
-        state.items = state.items.filter(item => item.id !== action.input.id);
-    },
+  // REMARKS: The addTodoItemOperation adds a new item and updates our tracking statistics.
+  // - state: The current document state. Powerhouse uses a library like Immer.js,
+  //   so you can write code that looks like it's mutating the state directly.
+  //   Behind the scenes, Powerhouse ensures this results in an immutable update.
+  // - action: Contains the operation's 'type' and 'input' data from the client.
+  // - dispatch: A function to trigger subsequent operations (advanced, not used here).
+  addTodoItemOperation(state, action, dispatch) {
+    // REMARKS: We update our statistics for total and unchecked items.
+    state.stats.total += 1;
+    state.stats.unchecked += 1;
+
+    // REMARKS: We push the new to-do item into the items array.
+    // The data for the new item comes from the operation's input.
+    state.items.push({
+      id: action.input.id,
+      text: action.input.text,
+      checked: false, // New items always start as unchecked.
+    });
+  },
+
+  // REMARKS: The updateTodoItemOperation modifies an existing to-do item.
+  // It handles partial updates for text and checked status.
+  updateTodoItemOperation(state, action, dispatch) {
+    // REMARKS: First, we find the specific item we want to update using its ID.
+    const item = state.items.find((item) => item.id === action.input.id);
+
+    // REMARKS: It's good practice to handle cases where the item might not be found.
+    if (!item) {
+      throw new Error(`Item with id ${action.input.id} not found`);
+    }
+
+    // REMARKS: We only update the text if it was provided in the input.
+    // This allows for partial updates (e.g., just checking an item without changing its text).
+    if (action.input.text) {
+      item.text = action.input.text;
+    }
+
+    // REMARKS: When the checked status changes, we also update our statistics.
+    // We check for `true` and `false` explicitly.
+    if (action.input.checked) {
+      // This is true only if action.input.checked is true
+      // Note: This assumes the item was previously unchecked. For a more robust implementation,
+      // you could check `if (item.checked === false)` before updating stats to prevent inconsistencies.
+      state.stats.unchecked -= 1;
+      state.stats.checked += 1;
+      item.checked = action.input.checked;
+    }
+    if (action.input.checked === false) {
+      // Note: This assumes the item was previously checked.
+      state.stats.unchecked += 1;
+      state.stats.checked -= 1;
+      item.checked = action.input.checked;
+    }
+  },
+
+  // REMARKS: The deleteTodoItemOperation removes an item from the list.
+  deleteTodoItemOperation(state, action, dispatch) {
+    // REMARKS: Before removing the item, we find it to determine its checked status.
+    // This is necessary to correctly decrement our statistics.
+    const item = state.items.find((item) => item.id === action.input.id);
+
+    // REMARKS: We always decrement the total count.
+    state.stats.total -= 1;
+
+    // REMARKS: We then decrement the 'checked' or 'unchecked' count based on the item's status.
+    if (item?.checked) {
+      // This is shorthand for item?.checked === true
+      state.stats.checked -= 1;
+    }
+    if (item?.checked === false) {
+      state.stats.unchecked -= 1;
+    }
+
+    // REMARKS: Finally, we create a new 'items' array that excludes the deleted item.
+    // Assigning to 'state.items' is handled by Powerhouse to produce a new immutable state.
+    state.items = state.items.filter((item) => item.id !== action.input.id);
+  },
 };
 ```
 
@@ -337,8 +355,9 @@ export const reducer: ToDoListToDoListOperations = {
 Every time a reducer processes an operation and returns a new state, Powerhouse records the original operation (the "event") in an append-only log associated with the document instance. The current state of the document is effectively a "fold" or "reduction" of all past events, applied sequentially by the reducers.
 
 This is why purity and immutability are so critical:
-*   **Purity** ensures that replaying the same sequence of events will always yield the exact same final state.
-*   **Immutability** ensures that each event clearly defines a discrete state transition, making it easy to audit changes and understand the document's history.
+
+- **Purity** ensures that replaying the same sequence of events will always yield the exact same final state.
+- **Immutability** ensures that each event clearly defines a discrete state transition, making it easy to audit changes and understand the document's history.
 
 ## Conclusion