Merge branch '15.3.0' into copilot/support-migration-of-events

Author: einari

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: 'kind/bug'
+assignees: ''
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## Steps to reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Actual behavior
+
+A clear and concise description of what actually happens.
+
+## Environment
+
+- OS: [e.g. Windows 11, Ubuntu 22.04, macOS 14]
+- .NET version: [e.g. 8.0.x]
+- Chronicle version: [e.g. 9.x.x]
+
+## Additional context
+
+Add any other context, logs, or screenshots about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea or improvement for Chronicle
+title: ''
+labels: 'kind/feature'
+assignees: ''
+---
+
+## Problem / motivation
+
+A clear and concise description of the problem this feature would solve, or the motivation behind the request.
+For example: "I often run into a situation where..."
+
+## Proposed solution
+
+A clear and concise description of what you would like to happen.
+
+## Alternatives considered
+
+A description of any alternative solutions or features you have considered, and why the proposed solution is preferred.
+
+## Additional context
+
+Add any other context, mockups, or examples about the feature request here.

.github/copilot-instructions.md

@@ -19,58 +19,21 @@ When these instructions don't explicitly cover a situation, apply these values t
 - Always use American English spelling in all code, comments, and documentation (e.g. "color" not "colour", "behavior" not "behaviour").
 - Write clear and concise comments for each function.
 - Make only high confidence suggestions when reviewing code changes.
-- Always use the latest version C#, currently C# 13 features.
 - Never change global.json unless explicitly asked to.
 - Never change package.json or package-lock.json files unless explicitly asked to.
 - Never change NuGet.config files unless explicitly asked to.
-- Never leave unused using statements in the code.
 - Always ensure that the code compiles without warnings.
 - Always ensure that the code passes all tests.
 - Always ensure that the code adheres to the project's coding standards.
 - Always ensure that the code is maintainable.
-- Review Directory.Build.props and .editorconfig for all warnings configured as errors.
-- Never generate code that would violate these warning settings.
-- Always respect the project's nullable reference type settings.
 - Always reuse the active terminal for commands.
 - Do not create new terminals unless current one is busy or fails.
 
-## Chronicle & Arc Key Conventions
-
-These conventions exist because the frameworks rely on convention-based discovery. Breaking them doesn't just violate style — it breaks runtime behavior.
-
-- `[EventType]` takes **no arguments** — the type name is used automatically. Adding a GUID or string argument is a common mistake from other frameworks; Chronicle does not use it.
-- `[Command]` records define `Handle()` directly on the record — never create separate handler classes. The framework discovers `Handle()` by convention; a separate class breaks that discovery.
-- `[ReadModel]` records define static query methods directly on the record. The proxy generator creates TypeScript hooks from these methods automatically.
-- Prefer `ConceptAs<T>` over raw primitives in all domain models, commands, events, and queries. This prevents accidental mix-ups (passing a `UserId` where an `AuthorId` was expected) and makes APIs self-documenting.
-- Use model-bound projection attributes (`[FromEvent<T>]`, `[SetFrom<T>]`, etc.) when possible; fall back to `IProjectionFor<T>` for complex cases.
-- For fluent projections, AutoMap is on by default — just call `.From<>()` directly.
-- Projections join **events**, never read models. This is fundamental to event sourcing: projections rebuild state from the event stream, not from other projections.
-- `IReactor` is a marker interface — method dispatch is by first-parameter event type, method name is descriptive.
-- All backend artifacts for a vertical slice go in a **single `.cs` file**. This keeps cohesion high and makes the scope of a slice immediately visible.
-
-## Proxy Generation — Build Dependency
-
-Commands and Queries generate TypeScript proxies at build time via `dotnet build`. This creates `.ts` files that the frontend imports (hooks, execute methods, change tracking). Until the backend compiles, **no proxy files exist** and frontend code cannot reference them.
-
-**This is a hard sequencing constraint:**
-1. Backend C# code must be written and compile successfully first.
-2. `dotnet build` must complete — this generates the TypeScript proxy files.
-3. Only then can frontend React components import and use the generated proxies.
-
-**When running parallel agents or sub-agents:** backend and frontend work for the same slice **cannot** run in parallel. The backend agent must finish and `dotnet build` must succeed before the frontend agent starts. Independent slices (no shared events) can have their backends worked on in parallel, but each slice's frontend still depends on its own backend build completing first.
-
 ## Development Workflow
 
 - After creating each new file, run `dotnet build` (C#) or `yarn compile` (TypeScript) immediately before proceeding to the next file. Fix all errors as they appear — never accumulate technical debt.
 - Before adding parameters to interfaces or function signatures, review all usages to ensure the new parameter is needed at every call site.
 - When modifying imports, audit all occurrences — verify additions are used and removals don't break other files.
-- Never use placeholder or temporary types — use proper types from the start.
-- Review each file for lint compliance before moving on.
-- The user may keep Storybook running — do not try to stop it, suggest stopping it, or start your own instance.
-
-## TypeScript Type Safety
-
-- Never use `any` — use `unknown`, `Record<string, unknown>`, or proper generic constraints instead. See [TypeScript Conventions](./instructions/typescript.instructions.md) for detailed patterns.
 
 ## Detailed Guides
 
@@ -90,3 +53,12 @@ These guides contain the full rules, examples, and rationale for each topic. The
    - [Dialogs](./instructions/dialogs.instructions.md)
    - [Reactors](./instructions/reactors.instructions.md)
    - [Orleans](./instructions/orleans.instructions.md)
+
+## Header
+
+All files should start with the following header:
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+```

.github/instructions/csharp.instructions.md

@@ -131,21 +131,6 @@ The framework discovers and wires dependencies by convention. Explicit registrat
 - Use `async`/`await` for asynchronous programming.
 - Use `Task` and `Task<T>` for asynchronous methods.
 
-## File Header
-
-Every C# file must start with:
-
-```csharp
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-```
-
-## Generated Files
-
-**Never edit generated files.** Files produced by code generators, scaffolding tools, or any other automated tool must not be modified by hand — in any language. Generated files are overwritten on the next build, so hand-edits are silently lost and create false confidence that a fix is in place.
-
-- If the generated output is wrong, fix the **source** (the template, the generator configuration, or the source type) and rebuild.
-
 ## Chronicle & Arc — Key API Types
 
 These are the building blocks. Each type has a specific role in the vertical slice architecture — using the right type in the right place means the framework handles discovery, wiring, and proxy generation automatically.
@@ -167,3 +152,9 @@ These are the building blocks. Each type has a specific role in the vertical sli
 | `EventContext` | Event metadata: `Occurred`, `SequenceNumber`, `CorrelationId`, `EventSourceId`, etc. |
 | `ISubject<T>` | Observable query return type — enables real-time WebSocket push |
 | `IMongoCollection<T>` | MongoDB collection — use `.Observe()` for reactive queries |
+
+**Key conventions:**
+- Prefer `ConceptAs<T>` over raw primitives in all domain models, commands, events, and queries — prevents accidental mix-ups and makes APIs self-documenting. See [concepts.instructions.md](./concepts.instructions.md) for details.
+- Projections join **events**, never read models — projections rebuild state from the event stream, not from other projections.
+- For fluent projections, AutoMap is on by default — just call `.From<EventType>()` without manually mapping every property.
+- Use model-bound projection attributes (`[FromEvent<T>]`, `[SetFrom<T>]`, etc.) when possible; fall back to `IProjectionFor<T>` for complex cases.

.github/instructions/dialogs.instructions.md

@@ -18,7 +18,10 @@ The Cratis dialog wrappers handle command execution, validation timing, loading
 - Pass the command constructor to `command={}`. `CommandDialog` handles instantiation, execution, and confirm/cancel buttons.
 - Use command form fields (`InputTextField`, `TextAreaField`, etc. from `@cratis/components/CommandForm`) for user-input values.
 - `CommandDialog` automatically disables confirm while the command executes.
-- Use `onBeforeExecute` only for values that cannot come from form fields (for example generated IDs).
+- Any value that must be present for the form to be considered valid (i.e. passes `validateRequiredProperties`) must be supplied via `initialValues`, **not** via `onBeforeExecute`.
+  - `onBeforeExecute` fires only at execution time — the command is already validated before it runs, so values set there never influence `isValid` and the OK/Submit button will remain permanently disabled.
+  - Use `initialValues` for injected context values (e.g. a parent entity id passed as a prop).
+  - Use `onBeforeExecute` only for transformations that should not affect form validity (e.g. generated IDs).
 
 ```tsx
 import { DialogProps, DialogResult } from '@cratis/arc.react/dialogs';

.github/instructions/efcore.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "**/*Context*.cs, **/Database/**/*.cs, **/Migrations/**/*.cs"
+applyTo: "**/*.cs"
 ---
 
 # Entity Framework Core Instructions

.github/instructions/pull-requests.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: ".github/**"
+applyTo: "**/*"
 ---
 
 # How to Do Pull Requests

.github/instructions/specs.csharp.instructions.md

@@ -239,4 +239,11 @@ public class and_name_already_exists(context context) : Given<context>(context)
 
 - Don't break long `should_` method lines — prefer one-line lambda assertions.
 - Don't add blank lines between multiple `should_` methods.
+
+## Entity Framework Core Specs
+
+- Use SQLite in-memory database for specs involving `DbContext`.
+- `SaveChanges` / `SaveChangesAsync` are virtual and can be mocked with NSubstitute.
+- `DbSet` methods are virtual — mock as needed.
+- Pass options when substituting: `Substitute.For<YourDbContext>(options)`.
 - Simulate failures by mocking `SaveChanges` to throw exceptions.

.github/instructions/typescript.instructions.md

@@ -1,27 +1,11 @@
 ---
-applyTo: "**/*.ts, **/*.tsx"
+applyTo: "**/*.ts,**/*.tsx"
 ---
 
 # TypeScript Conventions
 
 TypeScript's type system is the primary tool for catching bugs before they reach production. Every rule here pushes toward maximum compiler coverage and self-documenting code. If the types are right, the code almost writes itself.
 
-## Variables and Naming
-
-- Prefer `const` over `let` over `var`.
-- Never use shortened or abbreviated names for variables, parameters, or properties.
-  - Use full descriptive names: `deltaX` not `dx`, `index` not `idx`, `event` not `e`, `previous` not `prev`, `direction` not `dir`, `position` not `pos`, `contextMenu` not `ctx`/`ctxMenu`.
-  - The only acceptable short names are well-established domain terms (e.g. `id`, `url`, `min`, `max`).
-- Never leave unused import statements in the code.
-- Always ensure the code compiles without warnings — run `yarn compile` to verify (no output means success).
-
-## Folder Structure and Naming
-
-- Do not prefix a file, component, type, or symbol with the name of its containing folder or concept — use folder structure to provide that context instead.
-- Favor functional folder structure over technical folder structure.
-  - Group files by the feature or concept they belong to, not by their technical role.
-  - Avoid folders like `components/`, `hooks/`, `utils/`, `types/` at the feature level.
-
 ## Enums over Magic Strings
 
 String literal unions look concise but provide no refactoring support, no namespace, and no discoverability. Enums give you all three — plus `switch` exhaustiveness checking.
@@ -57,37 +41,9 @@ Each type gets its own file because it makes the codebase navigable — finding
 `any` disables the compiler — the one tool that catches bugs for free. Every `any` is a hole in the safety net. Use `unknown` and narrow with type guards instead.
 
 - Never use `any` — use `unknown`, `Record<string, unknown>`, or proper generic constraints.
-- Use proper generic constraints: `<TCommand extends object = object>` not `= any`.
-- Use `unknown` as the default generic parameter: `<T = unknown>` not `<T = any>`.
 - Prefer `value as unknown as TargetType` over `value as any`.
-- For objects with dynamic properties: `(obj as unknown as { prop: Type }).prop`.
-
-### Event Handlers
-
+- Use `unknown` as default generic parameter instead of `any`.
 - React synthetic events (`React.MouseEvent<Element, MouseEvent>`) and DOM events (`MouseEvent`) are different types — don't mix them.
-- Convert between them: `nativeEvent as unknown as React.MouseEvent`.
-- Use `e.preventDefault?.()` instead of `(e as any).preventDefault?.()`.
-
-### Generic React Components
-
-- Use `React.ComponentType<Props>` for React component types.
-- For Storybook components with no props: `React.ComponentType<Record<string, never>>`.
-- When converting component imports in Storybook: always `as unknown as` to avoid type mismatch errors.
-- Properly type story args — never use `any`.
-
-### External Libraries
-
-- Use proper library types when available (e.g. PIXI types, not `any`).
-- Use specific property types: `{ canvas?: HTMLCanvasElement }` instead of `any`.
-- When library generics have strict constraints, thread types through `unknown`: `props.command as unknown as Constructor<Command<...>>`.
-- Extract tuple results explicitly rather than destructuring when type assertions are needed.
-
-### Unknown Values
-
-- Add type guards before using function parameters of unknown type: `if (typeof accessor !== 'function') return ''`.
-- Type parameters with fallbacks: `function<T = unknown>(accessor: ((obj: T) => unknown) | unknown)`.
-- Cast unknown objects to record before property access: `(obj as Record<string, unknown>).items`.
-- Use `String(value)` for string conversions; `new Date(value as string | number | Date)` for dates.
 
 ## Localised Strings
 
@@ -146,22 +102,6 @@ For attribute strings (e.g. `title`, `placeholder`, `aria-label`):
 - **Never** use plain string literals for user-visible text in JSX or attribute props. This includes `label`, `header`, `placeholder`, `title`, `aria-label`, `emptyMessage`, and any visible text nodes.
 - Only constant, non-localised values are allowed as raw strings (CSS class names, `key` props, internal identifiers).
 
-## File Header
-
-Every TypeScript file must start with:
-
-```typescript
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-```
-
-## Generated Files
-
-**Never edit generated files.** Files produced by the proxy generator (`dotnet build`), code scaffolding tools, or any other automated tool must not be modified by hand — in any language. Generated files are overwritten on the next build, so hand-edits are silently lost and create false confidence that a fix is in place.
-
-- If the generated output is wrong, fix the **source** (the C# record, the template, or the generator configuration) and rebuild.
-- Generated TypeScript proxy files (commands, queries, observable queries) are always regenerated from C# sources. Never edit them directly.
-
 ## Arc Frontend Patterns
 
 Arc's proxy generator bridges C# and TypeScript automatically — every `[Command]` and `[ReadModel]` becomes a TypeScript class with `.use()` hooks, `.execute()` methods, and change tracking. This is the foundation of full-stack type safety: change a C# record and the TypeScript proxy updates on the next `dotnet build`.
@@ -202,3 +142,46 @@ Wraps multiple command-using components, aggregating their `hasChanges` state an
 ### CommandForm
 
 Declarative form component with built-in field types, validation timing (`validateOn: blur|change|both`), and automatic server-side validation feedback.
+
+## Variables and Naming
+
+- Prefer `const` over `let` over `var` when declaring variables.
+- Never use shortened or abbreviated names for variables, parameters, or properties.
+  - Use full descriptive names: `deltaX` not `dx`, `index` not `idx`, `event` not `e`, `previous` not `prev`, `direction` not `dir`, `position` not `pos`, `contextMenu` not `ctx`/`ctxMenu`.
+  - The only acceptable short names are well-established domain terms (e.g. `id`, `url`, `min`, `max`).
+
+## Imports and Compilation
+
+- Never leave unused import statements in the code.
+- Always ensure that the code compiles without warnings — use `yarn compile` to verify (successful runs produce no output).
+- Review each file for lint compliance before finalizing.
+- Never use placeholder or temporary types — use proper types from the start.
+
+## Folder Structure
+
+- Do not prefix a file, component, type, or symbol with the name of its containing folder or the concept it belongs to. Instead, use folder structure to provide that context.
+- Favor functional folder structure over technical folder structure.
+  - Group files by the feature or concept they belong to, not by their technical role.
+  - Avoid folders like `components/`, `hooks/`, `utils/`, `types/` at the feature level.
+
+## Advanced Type Safety
+
+Additional patterns for common tricky scenarios:
+
+**Storybook:**
+- Use `React.ComponentType<Record<string, never>>` for components with no props.
+- Always use `as unknown as` when converting component imports to avoid type mismatch errors.
+- Properly type story args — never use `any`.
+
+**External libraries with strict generic constraints:**
+- Import necessary types (e.g. `Command` from `@cratis/arc/commands`) rather than asserting to `any`.
+- Use type assertions through `unknown`: `props.command as unknown as Constructor<Command<...>>`.
+- Extract tuple results explicitly rather than destructuring when type assertions are needed.
+- Use proper library types when available; use specific property types (e.g. `{ canvas?: HTMLCanvasElement }`) over `any`.
+
+**Dynamic and generic types:**
+- Add type guards for unknown function parameters: `if (typeof accessor !== 'function') return ''`.
+- Type parameters with fallbacks: `function<T = unknown>(accessor: ((obj: T) => unknown) | unknown)`.
+- Cast arrays from `unknown` explicitly: `((obj as Record<string, unknown>).items || []) as string[]`.
+- Use `String(value)` for string conversions in generic contexts.
+- Use explicit Date parameter types: `new Date(value as string | number | Date)`.