@cratis/pi 0.0.1 → 2.0.2

package/package/corpus/rules/typescript.md

@@ -0,0 +1,149 @@
+---
+applyTo: "**/*.ts,**/*.tsx"
+paths:
+  - "**/*.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.
+
+## 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.
+
+```ts
+// ✅ Correct — refactorable, discoverable, exhaustive
+export enum SliceType {
+    StateChange = 'stateChange',
+    StateView   = 'stateView',
+    Automation  = 'automation',
+    Translator  = 'translator',
+}
+
+// ❌ Wrong — no refactoring support, invisible to tooling
+export type SliceType = 'stateChange' | 'stateView' | 'automation' | 'translator';
+```
+
+- Use enum members everywhere — `switch` cases, comparisons, defaults.
+- Do **not** import enums as `type`; they are values.
+- Export enums from `index.ts` without the `type` keyword.
+
+## One Type or Enum per File
+
+Each type gets its own file because it makes the codebase navigable — finding `SliceType` means opening `SliceType.ts`, not hunting through `types.ts`. It also keeps diffs clean and makes imports explicit.
+
+- Every interface, type alias, and enum lives in **its own file**, named after the type (e.g. `SliceType.ts`).
+- **Never create** `types.ts`, `models.ts`, `interfaces.ts` grab-bag files — they become dumping grounds that grow without limit.
+- Exception: component props interfaces (`*Props`) may live alongside their component `.tsx` file since they are tightly coupled to that component.
+- Aggregate exports through the folder's `index.ts`.
+
+## Type Safety
+
+`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.
+- Prefer `value as unknown as TargetType` over `value as any`.
+- 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.
+- **`int64`/`uint64` Chronicle fields generate as `bigint`** in the TypeScript proxies (not `number`, which silently truncated past `Number.MAX_SAFE_INTEGER`). Sequence numbers, large counters, and 64-bit ids surface as `bigint` — use `bigint` arithmetic, never `Number()`.
+
+## User-facing strings (localization)
+
+How user-visible text is handled is **product policy, not a Cratis framework rule** (see [general.md](./general.md) — locales belong in a downstream app's own `.cratis/ai/`). Cratis itself has no mandatory i18n layer or `Strings` alias.
+
+- If the app has a localization convention (e.g. a translation object behind a `strings`/`Strings` import, or any i18n library), follow it consistently and keep raw string literals to constant, non-user-facing values (CSS class names, `key` props, internal identifiers).
+- If the app ships literal text, literal labels in JSX are fine.
+
+Either way, the Cratis-generic rule is only that strings are handled consistently within the app — not a specific file layout or import alias.
+
+## 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`.
+
+### Commands
+
+Auto-generated from C# `[Command]` records. The `.use()` hook returns a tuple: the command instance (with change tracking) and a setter for property values.
+
+```tsx
+const [command, setValues] = OpenAccount.use({ name: '', owner: '' });
+await command.execute();       // Sends command to backend, returns CommandResult
+await command.validate();      // Pre-flight validation only, no side effects
+command.hasChanges;            // True when any property differs from initial values
+command.revertChanges();       // Reset all properties to initial values
+```
+
+### Queries
+
+Auto-generated from C# `[ReadModel]` static query methods. Observable queries (returning `ISubject<T>` on the backend) auto-subscribe via WebSocket — the component re-renders when data changes on the server.
+
+```tsx
+const [result, perform] = AllProjects.use();
+// result.data — the query result
+// result.isPerforming — true while loading
+// result.hasData — true when data has arrived
+// result.isSuccess — true when query completed without errors
+```
+
+Paginated queries:
+```tsx
+const [result, , setPage] = AllProjects.useWithPaging(10);
+```
+
+### CommandScope
+
+Wraps multiple command-using components, aggregating their `hasChanges` state and enabling bulk `execute()` and `revertChanges()`. Useful for forms that span multiple components.
+
+### CommandForm
+
+Declarative form component with built-in field types, validation timing (`validateOn: blur|change|both`), and automatic server-side validation feedback.
+
+## Language — American English Only
+
+All identifiers, comments, JSDoc, and string literals must use **American English** spelling (initialize, serialize, behavior, color, organization, center, modeling, dialog, license, judgment, gray). See [general.md](./general.md) for the full guidance.
+
+## 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.
+- **Never modify any file inside `node_modules/` or any build cache (e.g. `.vite/deps/`).** These are managed by the package manager and will be overwritten on the next install. If something appears broken in a library, look harder at the application code — especially when other usages of the same library work fine. Fixes belong in application code or upstream in the library's own repo.
+
+## 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)`.

package/package/corpus/rules/verification-discipline.md

@@ -0,0 +1,21 @@
+---
+applyTo: "**/*"
+paths:
+  - "**/*"
+---
+
+# Verification Discipline
+
+Verification answers whether changed behavior works. It does not establish who
+authored a file or preserve a chain of evidence about how it arrived.
+
+- Run the narrowest relevant build, type check, lint, and specifications.
+- Add a focused specification for every behavior or rejection rule you change.
+- Keep each check deterministic and runnable locally and in CI.
+- Never replace a real behavior check with a checksum, inventory, generated
+  receipt, or provenance record.
+- Report failures and skipped checks honestly.
+
+For this repository, `Source/Verification` validates corpus structure, profile
+composition, skill scenarios, and native package behavior. `Source/Harness.Setup`
+verifies that repository harness adapters still point to `.cratis/ai`.

package/package/corpus/rules/vertical-slices.md

@@ -0,0 +1,338 @@
+---
+applyTo: "**/*.cs, **/*.tsx"
+profile: application
+paths:
+  - "**/*.cs"
+  - "**/*.tsx"
+---
+
+# Vertical Slice Architecture
+
+> **Application profile.** This is the architecture for *applications built on Cratis*. It does **not** apply inside a Cratis framework repo (Arc/Chronicle/Fundamentals/Components) — those are libraries; see [framework.md](./framework.md).
+
+A vertical slice owns a single behavior: the command or query, the events it produces, the projections that build read models, the React component that renders the UI, and the specs that verify it all works. Everything lives together because everything changes together. **The slice is the invariant unit** (command + events + projection + component + specs), created, renamed, and deleted as one.
+
+This file is the reference for *what* goes in each part of a slice. Layout, slice types, workflow, and quality gates are in [general.md](./general.md).
+
+## Technical stack
+
+- .NET / C# (ASP.NET Core) — **Cratis Arc** for CQRS / model-bound commands and queries, **Cratis Chronicle** for event sourcing, MongoDB or EF Core for read models.
+- React + TypeScript (Vite) — Cratis Components (PrimeReact-based) + Arc-generated proxies, MVVM. Vitest + Mocha/Chai/Sinon for frontend specs.
+- xUnit + Cratis.Specifications + NSubstitute for C# specs (the `*Scenario` family — see [specs.md](./specs.md)).
+
+## Proxy generation — the build dependency
+
+A Debug `dotnet build` generates a typed TypeScript proxy per command and query next to the slice's `.cs` — Debug is the canonical trigger because it carries the fullest, most reliably-emitted PDB debug information the generator uses to place generated files. Until the backend compiles, **no proxy files exist** and frontend code cannot reference them. **Backend → build → frontend, always** — backend and frontend for the same slice cannot be done in parallel. When a subsequent Release build is only there to verify the app compiles in that configuration, skip proxy regeneration with `dotnet build -c Release -p:CratisProxiesOutputPath=` rather than letting it re-run the generator against a different compilation. Never edit a generated proxy (`// @generated by Cratis` header); fix the C# source and rebuild.
+
+## Model-bound — no controllers **[contract]**
+
+Commands are `[Command]` records with a public instance `Handle()` (Arc analyzers enforce this); queries are `static` methods on `[ReadModel]` records; projections, constraints, and authorization use attributes. Arc generates the HTTP surface — never write an MVC/API controller. Drop to fluent (`IProjectionFor<T>`, `IConstraint`) only when model-bound cannot express the rule.
+
+> **[convention]** A single `.cs` per slice and a fixed declaration order are house style for readability — Arc/Chronicle discover by attributes and static methods, not by file or source order. Split the file when a slice grows large or shared concepts move upward.
+
+Declaration order (house style): concepts → command + validator (paired) → business rules → constraints → events → read models + queries → projections → reactors. StyleCop SA1201/SA1210 enforce that each `[EventType]` appears **after** the command/validator that constructs it (a [convention] surfaced as a compile warning, not a Chronicle [contract]).
+
+A single `<Slice>.cs` therefore contains ALL of: `[Command]` records with `Handle()`, validators, constraints, `[EventType]` records, `[ReadModel]` records with static query methods, projections/reducers, reactors, and slice-specific concepts.
+
+```
+<Slice>/
+├── <Slice>.cs          ← ALL backend artifacts in one file
+├── <Component>.tsx     ← React component(s) for the slice
+└── when_<behavior>/    ← specs
+    └── and_<scenario>.cs
+```
+
+**❌ Never split by artifact type** (`Commands/`, `Handlers/`, `Events/` folders) — that is the layered structure the slice replaces.
+
+## Concepts
+
+Every domain identifier or named value is a typed record — raw `string`/`Guid`/`int` should not appear on commands, events, or read models for domain values. Primitives stay primitive only when the meaning *is* the base type (`bool`, a plain count, `DateOnly`).
+
+- **[contract] Value concepts** derive from `ConceptAs<T>`. The base provides value equality and an implicit **concept → `T`** conversion. **Add your own `T` → concept operator** when call-site ergonomics need it — the base does *not* provide that direction.
+- **[contract] Chronicle stream identities** derive from `EventSourceId<T>` with an `IComparable` underlying primitive. Add `NotSet`, `New()`, or a `T` → derived-id operator only when the domain API justifies it; typed empty/zero values are real specified stream IDs. The base conversion surface does not construct every derived domain record automatically.
+
+```csharp
+public record AuthorId(Guid Value) : EventSourceId<Guid>(Value)
+{
+    public static readonly AuthorId NotSet = new(Guid.Empty);
+    public static AuthorId New() => new(Guid.NewGuid());
+    public static implicit operator AuthorId(Guid value) => new(value);
+}
+
+public record AuthorName(string Value) : ConceptAs<string>(Value)
+{
+    public static implicit operator AuthorName(string value) => new(value);
+}
+```
+
+**[convention] Placement:** slice-specific concept → in the slice file; feature-shared → feature folder; module-shared → module folder; app-wide → `Common/`. Scan `Common/` and the feature folder before creating a new concept. See [concepts.md](./concepts.md) for full patterns, or invoke the **add-concept** skill.
+
+## Commands
+
+The command carries input from the caller. `Handle()` is defined directly on the record — never a separate handler class. For step-by-step creation, invoke the **cratis-command** skill.
+
+> This application is event-sourced, so the guidance below assumes a command's `Handle()` returns event(s) that Arc+Chronicle appends. Arc itself is a standalone CQRS framework (see [general.md](./general.md)) — a command may legitimately return a response or `void` and do its work through injected services when a slice isn't event-sourced; the return-shape and "never inject `IEventLog`" rules are the event-sourced default, not universal Arc laws.
+
+### The decision matrix — where each rule lives **[contract]**
+
+`Handle()` assumes the command is valid and constructs the event(s). Pick the mechanism by what the decision *is*:
+
+| Decision | Use |
+| --- | --- |
+| Reusable value invariant (length, format, range) | `ConceptValidator<T>` on the concept type |
+| Command-input / cross-field / pre-handler rule (incl. injected read-model/service/identity checks) | `CommandValidator<TCommand>` with `RuleFor(...)` |
+| Handler needs fetched/computed data before it can build the event | `Provide()` — fetches the data; may validate it and short-circuit |
+| State-dependent rule that must hold **under concurrency** | inject the read model into `Handle()`, return `Result<TEvent, ValidationResult>` |
+| Uniqueness | Chronicle `[Unique]` / `IConstraint` (race-safe) — not a read-model pre-check |
+| Genuinely exceptional failure (bug, missing infra) | `throw` a domain exception |
+
+**Do not throw for normal business rejection.** A thrown exception (from `Provide()` or `Handle()`) surfaces as an exception/HTTP 500, *not* a validation result. Recoverable, user-facing rejections are validation: `ValidationResult.Error(...)` via a validator or `Result<,>`. (For step-by-step business-rule placement, invoke the **add-business-rule** skill.)
+
+### Causation — what a command records **[contract]**
+
+A command's **property values** are recorded on the causation of every event it appends, alongside the command's name, so an event says not only which command produced it but what that command was asked to do. The causation is written into the event log and stays there for as long as the events do — a value recorded there cannot be taken back out by changing code.
+
+Two markings keep a value off the chain, and both are honored on the property, the declaring type, the positional record parameter, **and the property's type**:
+
+| Marking | For | Also does |
+| --- | --- | --- |
+| `[PII]` | personal data | encrypts it in the event, enrolls it in erasure |
+| `[NotAudited]` | a secret that is not personal data — password, token, API key, card number | nothing else; it only withholds |
+
+They are **not interchangeable**: `[PII]` on a password would encrypt it and enroll it in GDPR erasure, which is wrong; `[NotAudited]` on a name does nothing for an erasure request, which is also wrong.
+
+**Prefer marking the concept**, exactly as with `[PII]` — mark `ApiKey` once and every command taking one is covered:
+
+```csharp
+[NotAudited]
+public record ApiKey(string Value) : ConceptAs<string>(Value);
+```
+
+`[NotAudited]` on the command type excludes every property at once, which is right when a command exists only to carry secrets. The command is still **named** on the chain either way — what is withheld is the values, never the fact that it ran.
+
+`ARCCHR0009` warns on a command property whose *name* reads like a secret and is unmarked. It cannot see a secret whose name does not say so, so a clean build means "nothing obvious was missed", not "no secrets are recorded". For a false positive, **suppress the diagnostic** — marking it `[NotAudited]` would silence the warning by withholding a value you wanted recorded.
+
+Values render camel-cased; concepts unwrap to the value they hold; a value that is not set is omitted; a long one is truncated (the causation rides on *every* event the command appends).
+
+### `Provide()` — data for `Handle()` **[contract]**
+
+`Provide()` runs after authorization and validation, before `Handle()`. Its parameters resolve from DI (like `Handle()`'s); the command instance is `this`. Return one value, or a tuple (Arc binds tuple values to `Handle(...)` parameters by type). Each provided value must be consumed by a `Handle` parameter — an unused one is the **`ARC0005`** analyzer error. Use a **named record** when the provided values form a real domain/snapshot concept; a **tuple** when they are just separate inputs to event construction. It may be sync or async.
+
+```csharp
+[Command]
+public record PlaceOrder(OrderId OrderId, CustomerId CustomerId) : ICanProvideEventSourceId
+{
+    public EventSourceId GetEventSourceId() => OrderId;
+
+    public async Task<Result<Customer, ValidationResult>> Provide(IReadModels readModels)
+    {
+        var customer = await readModels.GetInstanceById<Customer>((EventSourceId)CustomerId);
+        return customer is null ? ValidationResult.Error("Customer must exist.") : customer;
+    }
+
+    public OrderPlaced Handle(Customer customer) => new(customer.Name);
+}
+```
+
+Use `Provide()` for IO/fetched/computed data a valid command needs (explicit-key read-model lookups, external services, snapshots). It may short-circuit with `ValidationResult` / `AuthorizationResult` / `Result<TProvided, ValidationResult>` when the supplied data is missing or unusable. Keep IO in `Provide()` and the decision in `Handle()`. Do **not** write a pass-through `Provide()` that only wraps a read model `Handle(...)` could take directly, and do **not** duplicate the same rejection in both the validator and `Provide()` — pick one owner.
+
+### `Handle()` return shapes **[contract]**
+
+Return the event(s) directly — Arc appends them; never inject `IEventLog` to append the primary event. If there is no `await`, return the value directly (no `Task<T>`/`Task.FromResult`).
+
+| Return | When |
+| --- | --- |
+| `TEvent` | one event on the implicit stream |
+| `(EventSourceId, TEvent)` | command decides the event source id (tuple order doesn't matter) |
+| `(TResponse, TEvent)` | a response value plus an event |
+| `IEnumerable<object>` | multiple events; `EventForEventSourceId(id, @event)` wrappers for cross-stream |
+| `Result<TEvent, ValidationResult>` | success event or a typed validation error (concurrency-sensitive rule) |
+| `void` | no event |
+
+**How Arc picks the response vs. metadata:** for an `(A, B)` tuple, each element is checked — exactly one element *without* a registered event handler becomes the `CommandResult<...>` response; if all are events, there is no response; **more than one un-handled element throws**. A `Result<TSuccess, TError>` has its inner value unwrapped and processed by these same rules (so `Result<(TId, TEvent), ValidationResult>` is processed as a tuple). A `(TEvent, Subject)` tuple's `Subject` is treated as **append metadata** (not a response) and overrides the resolved compliance subject. A `(TIdConcept, TEvent)` tuple opens a new stream — the id concept is the event source for that event.
+
+### Stream metadata & DCB concurrency **[contract]**
+
+Three attributes scope an append broad→narrow, and each one *also* (only with `concurrency: true`) contributes its dimension to the server-side concurrency check:
+
+| Attribute | Meaning |
+| --- | --- |
+| `[EventSourceType("...")]` | the overarching concept the event source *is* (`Account`, `Order`) |
+| `[EventStreamType("...")]` | a concrete process **within** that source type (`Onboarding`, `Transactions`) |
+| `[EventStreamId("...")]` | a marker separating **independent streams** within one stream type (`Monthly`, `2026-06`) |
+
+Each attribute always tags the appended events (visible in `EventContext`). **Only when the command also carries `concurrency: true`** does each dimension join the server-side `ConcurrencyScope` (plus the event source id), with the optimistic strategy supplying the expected tail sequence number. A command **without** `concurrency: true` contributes no scope of its own, and the append falls to whatever concurrency strategy the event sequence is configured with — by default the optimistic one, scoped to the event source. So the attribute chooses *which dimensions* bound the check, not whether a check happens at all. Reach for it on high-contention state transitions where a stale read would let two commands both "win" — it narrows the boundary so appends that are genuinely independent stop colliding (concurrency failures surface on `CommandResult`/`AppendResult`). Adopt it deliberately per behavior, not as a blanket default.
+
+When the stream id is known only at runtime, implement `ICanProvideEventStreamId.GetEventStreamId()` instead of `[EventStreamId]`. ⚠️ Combining `ICanProvideEventStreamId` with a non-null `[EventStreamId]` attribute on the same command throws `AmbiguousEventStreamId` at startup — pick one (or set the attribute value to `null` to defer to the interface).
+
+### Event-source id resolution order **[contract]**
+
+`ICanProvideEventSourceId.GetEventSourceId()` → a single `EventSourceId`/`EventSourceId<T>`-derived property → a `[Key]` property → else Arc/Chronicle generates one.
+
+⚠️ **Injected read models resolve ONLY by the command's resolved event-source id** — not by the read-model type, and not by "the property that looks like its key." If the read model you need is keyed by a **different** value, direct injection silently hands you the **wrong** instance — or, when nothing exists for the command's id, `null` (or for a `[Passive]` projection a **default-valued** instance; see *Existence checks* below) — a correctness bug, not a compile error. The three failure shapes: (1) you need a *referenced other* entity (act on A, check B); (2) the command has **multiple** `EventSourceId<T>`-typed properties → ambiguous resolution (never rely on property order); (3) a create command whose id is generated inside `Handle()`. In all three, read by explicit key: `IReadModels.GetInstanceById<T>((EventSourceId)key)`.
+
+### Validators **[contract]**
+
+`CommandValidator<TCommand>` (FluentValidation) sits directly below the `[Command]` it validates. **Omit it entirely when there are no rules** — delete an empty subclass. Single-property intrinsic rules belong on `ConceptValidator<T>`, not here. Constructor dependencies (read models, services, identity accessor) are injected and resolved per the command's event-source id.
+
+### Authorization **[contract]/[convention]**
+
+Apply authorization attributes on the `[Command]` record or query method. **[convention]** never check roles inside `Handle()` with an `if` — express it as an attribute/policy/command-filter at the boundary; command-specific scope rejection belongs in the validator.
+
+## Events
+
+`[EventType]` records are the schema-bound truth of the system.
+
+- **[contract] No arguments for new events** — the type name is the identifier. Use `generation:`/id only when evolving an existing contract (invoke the **event-type-migrations** skill).
+- **[contract] Past-tense, one-purpose names** (`AuthorRegistered`, not `Updated`/`FormSubmitted`) — Chronicle requires past-tense, single-purpose facts. Self-describing without slice context.
+- **[contract] Avoid nullable properties** — Chronicle's analyzer warns on nullable event members; model optional facts as a separate event, or resolve a nullable command input to a non-null sentinel before constructing the event.
+- **[contract] Never carry the event-source id** — it's implicit in the event context.
+- **[convention] No `DateTimeOffset`/`DateTime` properties** that duplicate `EventContext.Occurred` — Chronicle records the wall-clock timestamp of every event there. Read it in projections/reducers via `[SetFromContext<T>]` or fluent `.Set(m => m.X).ToEventContextProperty(c => c.Occurred)`. Use `DateOnly` only for a business date the user explicitly supplies.
+- **[convention] Every `[EventType]` has an XML `<summary>`** (Cratis C# doc convention) recording why the event exists and what each value means.
+- **[contract] `[EventType]` lives in its owning slice file** — referenced from other slices via `using`.
+
+**Event-design rules (what is and isn't a fact):**
+
+- **Events are not read models** — never append events for totals, counts, statuses, search indexes, or dashboards. Project those from source events into read models.
+- **Never duplicate one fact as an aggregate event *plus* a per-item fanout.** If a command fans out per item (one `RequestSentToPartner` per partner), don't also emit an aggregate event carrying the whole list. Keep the fanout as the single source of truth and project any aggregate from it; pick per-item vs. single-with-list event from how consumers read it — never both.
+- **Command rejection normally appends no event.** Validation and business-rule rejections are command results, not facts. Add a rejection/failed event only when the business must audit or react to that failure later.
+- **One event name = one meaning.** Don't reuse a vague event for several domain facts; if facts can occur, be absent, or have consumers independently, split them into separate event types.
+
+```csharp
+/// <summary>Emitted when an author is registered.</summary>
+/// <param name="Name">The author's display name.</param>
+[EventType]
+public record AuthorRegistered(AuthorName Name);
+```
+
+## Read Models and Queries
+
+**[contract]** `[ReadModel]` records expose queries as `public static` methods; dependencies are plain method parameters (no `[FromServices]`). Default to model-bound projection shape; drop to fluent only when needed. For step-by-step creation, invoke the **cratis-readmodel** skill.
+
+### Query return shapes **[contract]**
+
+Stay within analyzer-supported shapes: the read model, `T?`, a collection/array/`IQueryable<T>` of it, `Task<...>` of those, `IAsyncEnumerable<T>`, or `ISubject<...>` of read model/collection.
+
+- **`IQueryable<TReadModel>`** → automatic server-side paging/sorting (frontend `useWithPaging` — see the **query-paging** skill). Use it whenever a list can grow.
+- **`ISubject<...>`** → live/observable queries. Return it directly — **never** `Task<ISubject<...>>`.
+- **[contract] Custom paths use `[Path("...")]`** (`PathAttribute`), not ASP.NET `[Route]`. Reserve `[Route]` for controller endpoints (which this convention avoids).
+
+```csharp
+[ReadModel]
+[FromEvent<AuthorRegistered>]
+public record Author(AuthorId Id, AuthorName Name)
+{
+    public static IQueryable<Author> AllAuthors(IMongoCollection<Author> collection) => collection.AsQueryable();
+    public static Task<Author?> AuthorById(IReadModels readModels, AuthorId id) =>
+        readModels.GetInstanceById<Author>((EventSourceId)id);
+}
+```
+
+**[convention] No default values on `[ReadModel]` constructor parameters** — omit `= null`, `= default`, `= default!`, `= 0`, `= false`, `= ""`, `= []`. Chronicle writes the projected value on the first event, so a sentinel default is never correct and hides missing projection wiring. The only permitted defaults are enum variants that represent an explicit initial state and `[SetValue<T>]`-driven `bool` flags. Use `T?` for data genuinely absent before the relevant event fires.
+
+**[convention] Read-model boundaries & naming.** Read models are shaped for consumers and command policies, not CRUD-style aggregate DTOs. Split one when it starts mixing unrelated lifecycles — the test is coupling (state that changes for different reasons), not size. The event log is already the canonical history/audit trail, so name a model `AuditLog`/`ActivityLog` only when it genuinely is an audit surface; for curated UI projections prefer names like `Timeline`, `WorkSurface`, `Summary`, `Detail`, or `Policy`. (This is "specialization over reuse" applied to read models.)
+
+### Choosing read-model access in command-side code **[convention]**
+
+Ladder, first that fits: (1) direct read-model (DCB) injection — only when keyed by the command's own event-source id; (2) a `[Passive]` projection; (3) `IReadModels.GetInstanceById<T>((EventSourceId)key)` for a different/derived key; (4) a materialized projection. A lookup *interface* is justified **only** for a genuine non-key search (e.g. find-by-email) — never to wrap a keyed `GetInstanceById`.
+
+### Existence checks — what an absent read model actually resolves to **[contract]**
+
+`IReadModels.GetInstanceById<T>` is declared `Task<TReadModel>` (non-nullable) yet hands back `default!` when nothing exists, so the compiler gives callers no signal. What "nothing exists" resolves to depends on the **backing** — *not* on whether the model carries `[RemovedWith<T>]`:
+
+| Backing | Never created — no matching event for the key | Removed by a `[RemovedWith<T>]` event |
+| --- | --- | --- |
+| Materialized projection or reducer (**the default**) | `null` | `null` — the sink document is deleted |
+| `[Passive]` **projection** | ⚠️ a **default-valued instance**, never `null` | `null` — the computed state is blanked |
+| `[Passive]` **reducer** | `null` | `null` |
+
+`[RemovedWith<T>]` is therefore not the axis: a removed instance is `null` on **every** backing. The single non-`null` case is a **`[Passive]` projection that was never created** — Chronicle computes it on demand and seeds the initial state from the read model's schema, which fills every non-nullable, non-`string` property with its type default. (It answers `null` only when *no* property yields a schema default — all of them nullable, `string`/`object`, or an enum whose `0` is not a declared member — which is why the behavior looks inconsistent between models, not an escape hatch to design for.)
+
+⚠️ **This is invisible when a status enum's `0` is a real state** ("the state every stream starts in"): absent becomes byte-identical to freshly-created, so a command reads never-invited as already-invited. **Renumbering the enum from `1` is not the fix** — the value is then dropped from the payload and deserializes back to CLR `0` on the client anyway. Carry an explicit existence flag instead: `[SetValue<FirstEvent>(true)] bool Exists`, one `[SetValue<T>]` per event that can be the first for the stream. That is exactly the `[SetValue<T>]`-driven `bool` exception the no-defaults convention above allows for. An explicit `NotSet`/`Unknown` zero member also works, but only because the property stays present and readable; the flag is the robust form. ⚠️ **A spec suite will not catch this** — `CommandScenario`'s read-model harness answers `null` for an unseeded event-source id, which matches production for every row above *except* the passive projection. Cover the absent case by seeding a default-valued instance explicitly, not only `null`.
+
+**Injected-parameter nullability is the required/optional switch:** a nullable `TReadModel?` parameter (on a validator, `Provide()`, or `Handle()`) gets `null` injected for a never-created/removed instance — check `is null`. A **non-nullable** `TReadModel` whose instance does not exist throws **`CannotResolveValidatorDependency`** (non-nullable = "required, must exist"). ⚠️ Both switches ride on the same resolution, so on a **`[Passive]` projection** neither fires for a never-created instance: the nullable parameter receives a default-valued object and the `is null` guard never runs, and the non-nullable one resolves happily. Check the existence flag there, not nullability. Type by-id accessors you write yourself as `Task<T?>` so callers get the compiler signal Chronicle's own signature withholds.
+
+## Projections **[contract]**
+
+Projections build read models from **events** (never from other read models). Use the ladder — for adding one to an existing model, invoke the **add-projection** skill:
+
+1. **Model-bound attributes** on the `[ReadModel]`: `[FromEvent<T>]`, `[SetFrom<T>]`, `[SetFromContext<T>]`, `[ChildrenFrom<T>]`, `[RemovedWith<T>]`, `[Nested]`, `[ClearWith<T>]`, counters, `[FromAll]`.
+2. **Fluent `IProjectionFor<T>`** for joins, composite/constant keys, parent-key extraction, context mapping, `.NotRewindable()`, or supported conditional setters. Declarative metadata only — no DI side effects, no imperative `Define()` body, builder lambdas are member access only.
+3. **Reducer `IReducerFor<T>`** when the model is "current state + event → next state" — branching on prior state, loops, calculations. A valid style, **not** a failure mode; carry an inline justification comment naming the limitation that ruled out a projection.
+
+- **[contract] AutoMap is on by default — never call `.AutoMap()`.** Match property names so AutoMap wires them; diverge with `[SetFrom<T>]` / `.Set().To()` only for genuine name differences. Re-enable `.AutoMap()` only inside a scope disabled with `.NoAutoMap()`.
+  - ⚠️ **AutoMap runs per *event* across every event the projection references — it does not defer to your explicit setters.** A property sourced with `[SetFrom<A>]` can still be silently overwritten when some *other* referenced event `B` happens to carry an identically named property (AutoMap wires `B`'s value on top). Fence the property with property-level **`[NoAutoMap]`** (which pairs with the `[SetFrom]`, not replaces it) so only your explicit setter writes it. `[SetFrom]` does **not** imply this — leaving AutoMap on is what allows the common create-then-rename pattern (a later event updating a property by name-match). No colliding event property name means no `[NoAutoMap]` needed. (An event subscribed only via an aggregate like `[Count]` doesn't auto-map its other properties, so it can't collide.) The analyzer **`CHR0025`** surfaces this collision as an *informational* heads-up (not a warning, because either resolution — add `[NoAutoMap]`, or accept the update — can be correct).
+- **[contract] `[Nested]`** projects a single nullable child object; place `[FromEvent<T>]` on the nested type (or property-level `[SetFrom<T>]` when the parent shares the event — declaring class-level `[FromEvent<T>]` on both parent and nested type for the same event is a duplicate-registration startup crash).
+- **[contract] Event-sequence source attributes:** class-level `[EventSequence("name")]`, `[EventLog]`, or `[EventStore("name")]` select where the projection reads from (a named sequence, the explicit default log, or another Chronicle event store / inbox). ⚠️ `[FromEventSequence]` is **removed** — use `[EventSequence("name")]`.
+
+## Constraints **[contract]**
+
+Append-time invariants enforced by the Chronicle Kernel; Arc converts violations to validation errors on command appends.
+
+- **`[Unique]`** on an event property (across event sources) or event class (one per source) — the default.
+- **`[RemoveConstraint("name")]`** on a removal event to release a claimed value.
+- **`IConstraint`** for multi-event, differing property names, case-insensitive (`.IgnoreCasing()`), or custom messages. Declarative metadata only — no DI side effects, member-access lambdas.
+
+Group multi-event constraints under a shared name constant (`<Module>ConstraintNames`). Treat violations as validation results — never as thrown exceptions.
+
+## Reactors **[contract]**
+
+`IReactor` is a marker interface; dispatch is by the first parameter type. Reactors live only in Automation/Translation slices. See [reactors.md](./reactors.md) for full rules, or invoke the **add-reactor** skill.
+
+```csharp
+public Task AuthorRegistered(AuthorRegistered @event, EventContext context) => ...
+```
+
+- **Signatures:** the first parameter is the event and drives dispatch; every parameter after it is resolved as a dependency — `EventContext`, a read model, a service, a `ReactorDelivery` — with no limit on how many. Return `Task`, `void`, or a synchronous side-effect return type. Prefer `Task`/async for real side effects, but sync returns are supported.
+- **[convention] `[OnceOnly]`** on any non-idempotent side effect (emails, payments, external writes) — replay re-fires otherwise. It covers **replay only**; a recovered failed partition still re-delivers, so guard that with a `ReactorDelivery` receipt.
+- **Side-effect events:** return them directly as event objects (single `TEvent`, `IEnumerable<object>`, or `Task<...>` thereof) — Chronicle appends them to the triggering event source. To target a different event source/stream, return `EventForEventSourceId(id, @event)` wrappers (the same cross-stream mechanism as a command — see [reactors.md](./reactors.md)); the wrapper is self-describing, so set the stream type, source type or `Subject` on it when you need full metadata control. Don't inject `IEventLog` for the normal path; reserve it for explicit append-result/wait/options/mixed-target workflows.
+- **Commands from a reactor:** inject `ICommandPipeline` and `Execute(command)` (scopeless overload) — runs the full validation/authorization/handler pipeline. Don't reach for `IEventLog` to change state in another slice.
+- **[convention] Stateless, idempotent, read state via Chronicle read models** (`GetInstanceById`), not `IMongoCollection<T>`. Don't throw to "validate" malformed inbound events — that pauses the partition and can quarantine the observer; record an explicit failure/dead-letter event instead.
+
+## Compliance (PII)
+
+**[contract]** Chronicle encrypts `[PII]`-marked values per subject; decryption is transparent to observers and queries (read models injected into a `CommandValidator<T>` or `Handle()` decrypt transparently under the command's resolved subject before validation/handler logic runs).
+
+- Prefer **concept-level `[PII]`** (on the `ConceptAs<T>` type) so the marker travels everywhere automatically; use property-level `[PII]` only when a value is personal in one event context but not everywhere.
+- `[PII]` also keeps the value **off the causation chain** when it is a command property — see [Causation](#causation--what-a-command-records-contract). A secret that is not personal data needs `[NotAudited]` instead; `[PII]` is the wrong tool for a password.
+- **`[PII]` is found at any nesting depth, and may mark a whole value object.** A `[PII]` concept inside a value object is encrypted where it sits (siblings stay readable). Marking the **value object type** (or a property typed as one) with `[PII]` classifies every value it holds — Chronicle pushes the marker down to the individual values, so the document keeps its shape and each value is separately encrypted rather than fused into one blob.
+- Projection-backed read models inherit PII lineage automatically — don't add `[PII]` to their properties. Reducer-backed models: a `[PII]`-concept-typed property is detected automatically; add property-level `[PII]` only for a primitive/non-PII-concept property populated from PII source data.
+- ⚠️ **`[PII]` cannot be applied to `EventSourceId`/`EventSourceId<T>`** — Chronicle throws `PIINotSupportedOnEventSourceId` at runtime because the identifier is the encryption-key lookup. If the identifier itself is sensitive, use a random `Guid`-backed surrogate as the event source id and store the sensitive value in a `[PII]` property.
+- **PII inside a list/array element IS encrypted.** The compliance walk descends into nested objects *and* into array elements, so a `[PII]` concept in an `IReadOnlyList<T>` and a `[PII]` member of an element object are both encrypted per element. `[PII]` on the *list property itself* is different: it blob-encrypts the whole collection as one value, protecting it but making per-element values unqueryable — reach for that only when you never need to query inside the collection. For list-valued PII that must stay queryable, prefer a **person-scoped** read model joined at the query edge.
+- ⚠️ **Do not declare a read-model property named `_subject`** — Chronicle reserves that field in MongoDB for internal key tracking. After right-to-erasure key deletion, `[PII]` properties return an **empty** value (no exception is thrown).
+
+### Subject resolution **[contract]**
+
+The compliance **subject** is the encryption-key identity. It is resolved first-match-wins:
+
+| Priority | Mechanism |
+| --- | --- |
+| 1 | `Subject` as the second tuple element returned from `Handle()` (computed in the handler) |
+| 2 | `ICanProvideSubject.GetSubject()` on the command |
+| 3 | a `Subject`-typed property on the command |
+| 4 | an `EventSourceId<T>` property (the typed identity is the subject — no attribute) |
+| 5 | `[Subject]` on a **non-`EventSourceId<T>`** property (Arc converts via `ToString()`) |
+
+`ICanProvideSubject` lives in `Cratis.Chronicle.Events` (alongside `ICanProvideEventSourceId`/`ICanProvideEventStreamId`). `[Subject]` is *not* aggregate identity. A managed read-model document has **one** subject — never mix multiple people's PII in one document; split into person-scoped models.
+
+### Redaction **[contract]**
+
+Redaction is a system-event request that removes payload availability from the event log: it replaces the selected event payload in place, preserves the original sequence slot and event context, and records an **`EventRedacted`** marker. It is **not domain undo** — if business state must change, emit a domain event before/alongside the compliance operation. Rewind/rebuild replayable observers after redaction, and make reactor/projection code that consumes broad streams tolerate (filter or no-op on) `EventRedacted`.
+
+## Cross-slice patterns **[convention]**
+
+Cross-slice access is **read-only and goes through Chronicle** — inject another slice's read model (validator/`Provide()`/`Handle()`), read by explicit key with `IReadModels.GetInstanceById`, mark a `[Passive]` projection for command-side decisions, or react to its events. **Never** instantiate or DI another slice's command/handler/service.
+
+**DCB (Dynamic Consistency Boundary):** a command's consistency boundary is exactly the state its validator/`Provide()`/`Handle()` reads — determined at runtime, not pre-declared. Pair with `concurrency: true` stream metadata when a stale read could let two commands both "win."
+
+## Dialogs
+
+Frontend commands run through Cratis dialog wrappers — **never** import `Dialog` from `primereact/dialog`. Use `CommandDialog` (executes a command) or `Dialog` (data collection) from `@cratis/components`. See [dialogs.md](./dialogs.md).
+
+## See also
+
+- [general.md](./general.md) — layout, slice types, workflow, quality gates.
+- [concepts.md](./concepts.md) — `ConceptAs<T>` / `EventSourceId<T>` full patterns.
+- [reactors.md](./reactors.md) — reactor signatures and side-effect rules.
+- [specs.md](./specs.md) — `CommandScenario` / `EventScenario` / `ReadModelScenario` / `ReactorScenario`.
+- skills: **event-modeling**, **new-vertical-slice**, **scaffold-feature**, **cratis-command**, **cratis-readmodel**, **add-concept**, **add-projection**, **add-reactor**, **add-business-rule**, **event-type-migrations**, **call-command-from-code**, **query-paging**, **cross-cutting-properties**, **multi-tenancy**.

package/package/corpus/rules/web-fetching.md

@@ -0,0 +1,11 @@
+---
+applyTo: "**/*"
+description: "Use when fetching data from the web, CI logs, artifact URLs, signed URLs, Azure Blob URLs, or simple API/text responses. Prefer curl in the terminal over webpage fetch tools for raw data retrieval."
+---
+
+# Web Fetching
+
+- Prefer `curl` in the terminal for raw remote content such as CI logs, artifact downloads, signed URLs, plain-text endpoints, and JSON APIs.
+- Use webpage/content fetch tools only when the goal is to summarize or inspect rendered page content rather than retrieve the exact response body.
+- For expiring, authenticated, or redirecting URLs, default to `curl -L -s` and then pipe to `head`, `grep`, `sed`, or `jq` as needed.
+- When debugging remote responses, keep the raw output in the terminal path and filter locally instead of depending on fetch tools.

package/package/corpus/rules/writing-correct-examples.md

@@ -0,0 +1,35 @@
+---
+applyTo: "**/Documentation/**/*.{md,mdx}"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+---
+
+# Writing Correct Code Examples (Technical Docs)
+
+Documentation code examples are **copied verbatim** by evaluators. A snippet that uses an API that doesn't exist is worse than no snippet — it breaks on first paste and loses trust. An audit of these docs found **~12 fabricated-API bugs** that had passed review and shipped. The discipline below is how you avoid adding the thirteenth.
+
+## The rule: verify every framework API against real source — before you write it
+
+For each framework type, attribute, method, prop, hook, or import in an example, confirm it exists and has that exact shape in **source**, not in another doc page (the docs themselves had the bugs):
+
+- **C# / backend** — grep real usage in a reference application (e.g. Cratis **Studio**) and the product `Source/` trees of the Cratis repos checked out alongside this one (`Arc/Source`, `Chronicle/Source`). For extension methods, find the `public static … (this <Type> …)` signature and note **which type it extends**.
+- **React / Components** — the authoritative prop names are in the compiled type defs of the installed package (`node_modules/@cratis/components/dist/esm/**/*.d.ts`) or the `Components` source `dist`. Real usage: a reference app's `*.tsx`.
+- **Invented *domain* names are fine** (event/concept/command names like `AuthorRegistered`, `BookId`). Only **framework APIs** must be real. Never invent a framework interface, attribute, prop, method, or import path.
+
+## Complete and correct
+
+- No pseudo-code, no `// ...` elisions that leave the reader guessing, no props/members that don't exist.
+- A snippet a reader pastes should compile (modulo the invented domain types they'd supply).
+
+## Verified gotchas (the real APIs — these are the ones docs kept getting wrong)
+
+- Commands/queries are **model-bound**: a `[Command]` record with `Handle()` **on the record**, and `[ReadModel]` records with **static** query methods. The marker/handler interfaces `ICommand`, `ICommandHandler<T>`, `IQuery<T>`, `IQueryHandler<T,R>` **do not exist** — never use them.
+- Bootstrap: `ArcApplication.CreateBuilder(args)` (not `ArcApplicationBuilder.CreateBuilder`). `builder.AddCratisArc()` on the builder (`WebApplicationBuilder`/`IHostBuilder`); `app.UseCratisArc()` on the built app and it takes **no args** (the listen URL comes from `ArcOptions.Hosting.ApplicationUrl`).
+- Read the current user inside `Handle()` by injecting **`IHttpContextAccessor`** and reading `HttpContext?.User` (`ClaimsPrincipal`). There is no `CommandContext.User` and no `IUserAccessor` Arc type. In-`Handle` guards return **`Result<TEvent, ValidationResult>`** (success type first, error type second) + `ValidationResult.Error(...)` — there is no `CommandResult.Forbidden`/`Unauthorized` to return.
+- Components: `DataPage` uses the **compound** `DataPage.Columns` / `DataPage.MenuItems`; the detail prop is **`detailsComponent`** (lowercase) — `detailsTitle`/`initialSizes` are **not** props. Import `DataTableForObservableQuery` from `@cratis/components/DataTables` (the root barrel only re-exports namespaces); `DataPage`/`MenuItem` from `@cratis/components/DataPage`. Required props like `emptyMessage`/`title` must be present.
+- Chronicle model-bound projections use property attributes **`[SetFrom<T>]`** / **`[SetValue<T>]`** (and `[FromEvent<T>]` AutoMap) — **not** `static On(event)` methods (that shape does not exist). Retrieve a read model with `eventStore.ReadModels.GetInstanceById<T>(id)`. Assertion signatures depend on the extension receiver: the out-of-process `IChronicleSetupFixture` extension is `ShouldHaveAppendedEvent<TEvent>(sequenceNumber, eventSourceId, validator)`, while Arc's in-process `CommandScenario<TCommand>` extensions use `<TCommand, TEvent>` with the event-source id and optional predicate. Verify the receiver type and its exact extension signature before copying either shape.
+
+## Auditing at scale
+
+Re-run a snippet-correctness audit periodically — it keeps finding bugs (the list above came from three rounds). Delegate the cross-checking to subagents that compare each snippet to source and report only confirmed discrepancies; **verify each finding against source yourself before fixing**. Consider adopting an automated example tester (**Doc Detective**, **Squidler** — from awesome-docs) that actually runs the snippets, so correctness is enforced by CI rather than by hand. The principle, from jvns's "write good examples by starting with real code": derive examples from working source, don't compose them from memory.