@cratis/pi 0.0.1

package/skills/cratis-arc-authentication-authorization-and-identity/references/tenancy.md

@@ -0,0 +1,87 @@
+# Tenancy
+
+Verified against `Cratis.Arc.Core` `22.10.4`. Types are in `Cratis.Arc.Tenancy`.
+
+Arc tenancy is **request-scoped tenant resolution**. It answers "which tenant is
+this request for". It is not Chronicle's tenant namespace isolation, and it does
+not by itself scope any storage.
+
+## Constants
+
+```csharp
+public const string DefaultTenantIdHeader = "x-cratis-tenant-id";
+public const string TenantIdItemKey       = "TenantId";
+public const string DefaultFixedTenantId  = "development";
+```
+
+## Options and defaults
+
+`ArcOptions.Tenancy` is a `TenancyOptions`:
+
+| Property | Default |
+| --- | --- |
+| `ResolverType` | `TenantResolverType.Header` |
+| `HttpHeader` | `x-cratis-tenant-id` |
+| `BaseDomain` | empty |
+| `QueryParameter` | `tenantId` |
+| `ClaimType` | `tenant_id` |
+| `FixedTenantId` | `development` |
+| `DevelopmentTenantId` | an alias property over `FixedTenantId` |
+
+`TenantResolverType` is `Header = 0`, `Query = 1`, `Claim = 2`,
+`Development = 3`, `Subdomain = 4`, `Fixed = 5`. **Header is the default.**
+
+Configure through the extension methods on `ArcOptions`: `UseHeaderTenancy`,
+`UseQueryTenancy`, `UseClaimTenancy`, `UseDevelopmentTenancy`, `UseFixedTenancy`,
+and `UseSubdomainTenancy(baseDomain, fallbackHeaderName?)`. Options are validated
+by `TenancyOptionsValidator`.
+
+## The resolvers
+
+| Resolver | Reads |
+| --- | --- |
+| `HeaderTenantIdResolver` | `Tenancy.HttpHeader` |
+| `QueryTenantIdResolver` | `Tenancy.QueryParameter` |
+| `ClaimTenantIdResolver` | the first claim of `Tenancy.ClaimType` |
+| `SubdomainTenantIdResolver` | the host label in front of `BaseDomain` |
+| `FixedTenantIdResolver` | `Tenancy.FixedTenantId` |
+| `DevelopmentTenantIdResolver` | deprecated alias over `FixedTenantIdResolver` |
+
+⚠️ `SubdomainTenantIdResolver` **falls back to the configured HTTP header** when
+the host does not match. A request that misses the subdomain can therefore still
+name its own tenant through a header it controls. Clear `Tenancy.HttpHeader` if
+that fallback is not wanted.
+
+Its suffix is built once from the base domain at construction and never rebuilt.
+Writing `BaseDomain` after construction does not take effect — and would silently
+send every request down the header fallback. `BaseDomainIsNotADomainName` guards
+the configured value.
+
+## Reading the tenant
+
+`ITenantIdAccessor.Current` gives the current `TenantId`, cached into an
+`AsyncLocal`. An empty resolution is `TenantId.NotSet`, whose value is the
+literal string `"[NotSet]"`. `TenantId.Default` is `"Default"` and `IsDefault`
+tests for it. `CurrentTenantIdIsNotSet.ThrowIfNotSet(...)` is the guard for code
+that requires a tenant.
+
+⚠️ `NotSet` is a real string, not `null`. A check like
+`string.IsNullOrEmpty(tenantId)` never fires for an unresolved tenant. Compare
+against `TenantId.NotSet`.
+
+## Development listing
+
+`ICanProvideTenants` (`Task<IEnumerable<Tenant>> Provide()`) feeds
+`GET /.cratis/tenants`, where `Tenant` is `record (TenantId Id, TenantName Name)`.
+The endpoint is `AllowAnonymous` and mapped unconditionally, so an implementation
+that returns real tenants publishes them. Return development fixtures only.
+
+## Where the boundary is
+
+Tenant resolution reads a value the **caller** supplied — a header, a query
+parameter, a claim, or a host. Only the claim resolver reads something the
+authentication step produced. The other four are caller-controlled input.
+
+Anything that must be isolated per tenant has to enforce that isolation itself,
+downstream of resolution. Never treat a resolved tenant id as an authorization
+decision.

package/skills/cratis-arc-command/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-arc-command/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: cratis-arc-command
+description: Define a Cratis Arc command — the [Command] record, its Handle() method and return shape, the optional Provide() step, and the generated TypeScript proxy. Use when adding a command, choosing what Handle() should return, deciding which values may reach the causation chain, or wiring a form or button to an Arc backend. Do not use for a validation-only change or merely to execute an existing command.
+license: MIT
+---
+
+# Define an Arc command
+
+A command is a record that carries the user's intent and owns its own handler.
+Arc discovers it, runs authorization and validation, calls `Handle()`, and turns
+whatever `Handle()` returns into appended events, a response, or both.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Arc.Core` | `22.10.4` | `Cratis.Arc.Commands.ModelBound.CommandAttribute`, `CommandResult`, `CommandValidator<T>` |
+| `Cratis.Arc.Chronicle` | `22.10.4` | event append handling, `Cratis.Arc.Chronicle.Commands.NotAuditedAttribute` |
+| `Cratis.Arc.ProxyGenerator.Build` | `22.10.4` | `CratisProxiesOutputPath` MSBuild integration |
+| `Cratis.Fundamentals` | `7.18.2` | `Cratis.Monads.Result<TResult, TError>` |
+| `Cratis.Chronicle` | `16.39.1` | `EventTypeAttribute`, `EventForEventSourceId`, `ICanProvideEventSourceId` |
+| `@cratis/arc` | `22.10.4` | `ICommand`, `CommandResult`, `ValidationResult` |
+
+Reverify before claiming support for another version. Arc without Chronicle is a
+supported setup; everything on this page that appends events needs Chronicle.
+
+## Declare the command
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Arc.Commands.ModelBound;
+using Cratis.Chronicle.Events;
+
+namespace <NamespaceRoot>.<Feature>;
+
+[Command]
+public record <ImperativeName>(<ConceptType> <Name>, <ConceptType> <Name>)
+{
+    public <EventType> Handle() => new(<Name>);
+}
+
+[EventType]
+public record <EventType>(<ConceptType> <Name>);
+```
+
+Rules the framework actually enforces:
+
+- `[Command]` is `Cratis.Arc.Commands.ModelBound.CommandAttribute` and applies to
+  a class declaration only. A type counts as a command when it carries
+  `[Command]` **and** declares a `Handle` method; either one alone is not enough.
+- `Handle` is found by name on the command type itself. `ARC0003` is an error
+  when another class defines `Handle` for a command, and `ARC0004` is an error
+  when a `[Command]` type has no public instance `Handle`.
+- `ARC0002` warns when a type has `Handle` but no `[Command]`; `ARC0007` warns
+  when a command is a `class` rather than a `record`.
+- Name the command as the action — `OpenDebitAccount`, not
+  `OpenDebitAccountCommand`.
+- `Handle` parameters are resolved from DI, so ask for services there rather
+  than through a constructor.
+- Never inject `IEventLog` into `Handle` to append the command's own events —
+  `ARCCHR0007` warns, and it bypasses Arc's append pipeline. Express the append
+  through the return type.
+
+Use concept types rather than raw primitives for the command's values, and give
+Chronicle-backed identities the `EventSourceId<T>` base — see the
+`cratis-fundamentals-concept` skill for the exact shapes.
+
+## Choose the return shape
+
+`Handle()`'s return value is dispatched by its runtime type. The shape decides
+what is appended and what the caller gets back.
+
+| Return | What Arc does |
+| --- | --- |
+| A registered event record | Appends it to the command's event source id |
+| `IEnumerable<object>` of registered events | Appends each to the command's event source id |
+| `EventForEventSourceId(id, @event)` | Appends that one event to `id` |
+| A collection mixing events and `EventForEventSourceId` | Appends each to its own target, wrappers to their id and plain events to the command's |
+| A tuple | Each element is dispatched on its own; the one element nothing can handle becomes the response |
+| Anything else | Becomes the response payload |
+| `Result<TEvent, ValidationResult>` | Success appends the event; failure becomes a validation failure |
+| `Task<T>` / `ValueTask<T>` of any of the above | Awaited first, then dispatched |
+
+See [handler shapes](references/handler-shapes.md) for the dispatch order, the
+tuple rule, and the exact failure modes.
+
+Two consequences worth knowing before writing the first command:
+
+- **The tuple is how a create command returns its new id.** An
+  `EventSourceId`-derived value in the tuple is not appendable, so it becomes the
+  response — and the response, when it is an event-source id value, is also what
+  the events in that same tuple are appended to. Returning more than one
+  unhandleable element throws `MultipleUnhandledTupleValues`.
+- **Events never carry their own event source.** Cross-stream writes use
+  `EventForEventSourceId`; they are not expressed by a property on the event.
+
+```csharp
+[Command]
+public record Register<Thing>(<ConceptType> <Name>)
+{
+    public (<ThingId>, <ThingRegistered>) Handle()
+    {
+        var id = <ThingId>.New();
+        return (id, new(<Name>));
+    }
+}
+```
+
+```csharp
+[Command]
+public record Transfer(<AccountId> From, <AccountId> To, <Money> Amount)
+{
+    public IEnumerable<object> Handle() =>
+    [
+        new EventForEventSourceId(From, new <Withdrawn>(Amount)),
+        new EventForEventSourceId(To, new <Deposited>(Amount)),
+    ];
+}
+```
+
+## Where the event source id comes from
+
+Chronicle resolves the command's event source id in this order:
+
+1. `commandContext.Response`, when the response is an event-source-id value —
+   the tuple case above;
+2. `ICanProvideEventSourceId.GetEventSourceId()` on the command;
+3. a single `EventSourceId`/`EventSourceId<T>`-derived or `[Key]`-marked
+   property on the command;
+4. otherwise a freshly generated id.
+
+A command with more than one candidate property is ambiguous and `ARCCHR0002`
+warns; implement `ICanProvideEventSourceId` to say which value wins. Do not rely
+on property order.
+
+Two attributes are spelled `[Key]`. Chronicle reads `Cratis.Chronicle.Keys.KeyAttribute`.
+Marking `System.ComponentModel.DataAnnotations.KeyAttribute` in an application
+that uses Chronicle compiles, resolves nothing, and silently invents a new event
+source id for every command — `ARCCHR0008` reports it.
+
+## Fetch what the handler needs with `Provide()`
+
+`Provide` is an optional instance method that runs before `Handle`. Its purpose
+is to keep IO out of `Handle`: it fetches or computes values, and Arc binds them
+to `Handle`'s parameters by type.
+
+```csharp
+[Command]
+public record Open<Thing>(<ThingId> Id, <OwnerId> OwnerId)
+{
+    public async Task<Result<<Owner>, ValidationResult>> Provide(IReadModels readModels)
+    {
+        var owner = await readModels.GetInstanceById<<Owner>>((EventSourceId)OwnerId);
+        return owner is null
+            ? ValidationResult.Error("Owner must exist.")
+            : owner;
+    }
+
+    public <ThingOpened> Handle(<Owner> owner) => new(owner.Id);
+}
+```
+
+- Short-circuit with `ValidationResult.Error(...)`; do not throw for a rejection
+  the user can act on. A thrown exception surfaces as `HasExceptions` and HTTP
+  500, not as a validation failure.
+- Every value `Provide` returns must be consumed by a `Handle` parameter.
+  `ARC0005` warns otherwise. `ValidationResult`, `AuthorizationResult` and
+  `CommandResult` are exempt because they short-circuit rather than feed `Handle`.
+- `Provide` runs after authorization and validation.
+
+An Arc read model can also be injected directly into `Provide`, `Handle`, or a
+`CommandValidator<T>` — but only by **the command's own resolved key**. Reading a
+read model keyed by anything else needs an explicit by-id read, and an absent
+instance does not always arrive as `null`. Read
+[read-model injection](references/read-model-injection.md) before relying on a
+directly injected read model.
+
+## Decide what the causation chain may record
+
+Every property value of the command is written to the causation of every event
+the command appends, and the event log is immutable. Decide this when the
+property is added.
+
+| Marking | Use for | Effect |
+| --- | --- | --- |
+| `[PII]` (Chronicle) | personal data | encrypted in the event and enrolled in erasure; already withheld from causation |
+| `[NotAudited]` (Arc Chronicle) | a secret that is not personal data — password, token, API key | withheld from causation, nothing else |
+
+```csharp
+[Command]
+public record Change<Secret>(
+    <UserId> User,
+    [property: NotAudited] string Old<Secret>,
+    [property: NotAudited] string New<Secret>)
+{
+    public <SecretChanged> Handle(I<Hasher> hasher) => new(hasher.Hash(New<Secret>));
+}
+```
+
+`[NotAudited]` applies to a class, struct, property, or parameter. On the type it
+withholds every property at once. Marking the concept type instead makes it
+travel to every command that takes that value. The command is still named on the
+chain either way; only the values are withheld.
+
+`ARCCHR0009` warns when a property's *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". When the name only
+reads like a secret and the value is safe to record, the framework's own guidance
+is to mark it `[NotAudited]` anyway or rename the property — the value is written
+either way, so the reading is all a reviewer has to go on.
+
+## Generate the TypeScript proxy
+
+```xml
+<PackageReference Include="Cratis.Arc.ProxyGenerator.Build" Version="22.10.4" />
+
+<PropertyGroup>
+  <CratisProxiesOutputPath>$(MSBuildThisFileDirectory)../<Web>/src/api</CratisProxiesOutputPath>
+</PropertyGroup>
+```
+
+`dotnet build` runs the generator after the build, and only when
+`CratisProxiesOutputPath` is set. Output folders mirror the C# namespace, not the
+file path. See [proxy generation](references/proxy-generation.md) for the full
+set of MSBuild knobs and the common failures.
+
+## The generated client contract
+
+The generated proxy is a `Command` from `@cratis/arc`. Its members are the same
+whatever renders it:
+
+| Member | What it does |
+| --- | --- |
+| `route` | The generated route, including the configured API prefix |
+| `roles` | The roles the command declares; empty when it declares none |
+| `<property>` | Get or set one value; setting raises `propertyChanged` |
+| `hasChanges` | True when any value differs from the initial values |
+| `execute(allowedSeverity?, ignoreWarnings?)` | Sends the command; resolves to `CommandResult` |
+| `validate()` | Runs authorization and validation on the server without the handler |
+| `validateClientSide()` | Runs only the extracted rules locally; never touches the network |
+| `setInitialValues(values)` | Sets the change-tracking baseline |
+| `setInitialValuesFromCurrentValues()` | Rebaselines onto the current values |
+| `revertChanges()` / `clear()` | Restore the baseline / reset everything |
+
+Branch on the specific flag, not only on `isSuccess`. The exact `CommandResult`
+and `ValidationResult` shapes are in
+[command result](references/command-result.md) — in particular, a validation
+failure carries `members: string[]` (camelCased) and a numeric `severity`, not a
+`propertyName` string.
+
+`validateClientSide()` runs only the rules the generator could extract, so it can
+pass where `execute()` still fails validation — see
+[proxy generation](references/proxy-generation.md) for the exact extractable set.
+
+Binding this proxy into a React component — the generated `use()` hook and the
+Cratis Components command dialog and form fields — belongs to the Arc React and
+Components guidance, not to this skill.
+
+## Route near misses
+
+- Adding or changing a rule on an existing command: the Arc command validation
+  guidance.
+- Executing an existing command from backend code: `cratis-arc-command-execution`.
+- Append-time uniqueness or concurrency constraints: the Chronicle event
+  constraints guidance.
+- Choosing the concept or identity type for a value: `cratis-fundamentals-concept`.
+
+## Verify
+
+- The command is a `record`, carries `[Command]`, and declares a public instance
+  `Handle`.
+- The return shape matches what the command is supposed to do, and any
+  cross-stream event is wrapped in `EventForEventSourceId`.
+- At most one tuple element is unhandleable.
+- The event source id resolves from exactly one place; `ARCCHR0002` is silent.
+- `[Key]`, where used, is `Cratis.Chronicle.Keys.KeyAttribute`.
+- No `IEventLog` is injected into `Handle`.
+- Every value `Provide` returns is consumed by `Handle`.
+- Rejections are validation results, never thrown exceptions.
+- Every secret or personal value is marked before it can reach the event log.
+- `dotnet build` is clean in Debug and Release, with no suppressed `ARC*` or
+  `ARCCHR*` diagnostic left unjustified.
+- The generated proxy exists at the configured output path and the frontend
+  compiles against it.

package/skills/cratis-arc-command/references/command-result.md

@@ -0,0 +1,111 @@
+# CommandResult and ValidationResult
+
+Verified against `Cratis.Arc.Core` `22.10.4` and `@cratis/arc` `22.10.4`.
+
+## Server side
+
+`Cratis.Arc.Commands.CommandResult`:
+
+| Member | Type | Notes |
+| --- | --- | --- |
+| `CorrelationId` | `CorrelationId` | Defaults to `CorrelationId.NotSet` |
+| `IsSuccess` | `bool` | Computed: `IsAuthorized && IsValid && !HasExceptions` |
+| `IsAuthorized` | `bool` | Settable; defaults to `true` |
+| `IsValid` | `bool` | Computed: `!ValidationResults.Any()` |
+| `HasExceptions` | `bool` | Computed: `ExceptionMessages.Any()` |
+| `ValidationResults` | `IEnumerable<ValidationResult>` | |
+| `ExceptionMessages` | `IEnumerable<string>` | |
+| `ExceptionStackTrace` | `string` | |
+| `AuthorizationFailureReason` | `string` | |
+
+`CommandResult<TResult>` adds a `Response` of `TResult`.
+
+`IsValid` and `HasExceptions` are **derived**, not stored. There is no way to
+set them directly — a result is invalid because it carries validation results.
+
+Factories: `Success`, `Unauthorized`, `MissingHandler`, `Error`, `InvalidBody`,
+`FromException`.
+
+⚠️ **A failed result carries no response.** The pipeline clears the response once
+every execution scope has completed and the result is not successful, so a
+transaction that rolls back after `Handle` returned a value does not leak that
+value into the error body.
+
+## Severity filtering
+
+`ValidationResultSeverity`: `Unknown = 0`, `Information = 1`, `Warning = 2`,
+`Error = 3`.
+
+Only *blocking* results survive onto the result. With no `allowedSeverity`, only
+`Error` blocks — information and warnings are filtered out entirely. With an
+`allowedSeverity`, anything strictly greater than it blocks. So passing
+`Warning` keeps errors blocking and lets warnings through.
+
+## Client side
+
+`@cratis/arc` `ICommandResult<TResponse = object>`:
+
+```ts
+readonly correlationId: Guid;
+readonly isSuccess: boolean;
+readonly isAuthorized: boolean;
+readonly isValid: boolean;
+readonly hasExceptions: boolean;
+readonly validationResults: ValidationResult[];
+readonly exceptionMessages: string[];
+readonly authorizationFailureReason: string;
+readonly exceptionStackTrace: string;
+readonly response?: TResponse;
+```
+
+`ValidationResult` is a class with these readonly members:
+
+```ts
+severity: ValidationResultSeverity   // numeric enum, 0..3
+message: string
+members: string[]
+state: any
+reason: ValidationResultReason       // defaults to Rule
+reasonDetail?: string
+```
+
+⚠️ **There is no `propertyName` and no string severity.** A rule attributes its
+failure to one or more `members`, and `severity` is the numeric
+`ValidationResultSeverity` enum. Code that reads `v.propertyName` or compares
+`v.severity === 'Error'` is reading fields that do not exist.
+
+Match a failure to a field through `members`, and branch on `reasonDetail`
+rather than parsing `message` — the message is prose written for a human and is
+free to change, while `reasonDetail` is the identity of the specific thing that
+rejected the command (a constraint name, for instance).
+
+```tsx
+const result = await command.execute();
+
+if (!result.isAuthorized) { /* the caller is not allowed to do this */ }
+else if (!result.isValid) {
+    const errorFor = (property: string) =>
+        result.validationResults.find(v => v.members.includes(property))?.message;
+}
+else if (result.hasExceptions) { /* server fault */ }
+else { /* result.response */ }
+```
+
+`members` is **camelCased on purpose**, so a form can match a server failure to
+the field that caused it without transforming anything. A nested member is a
+dotted path from the graph root — `address.postalCode`. A failure raised by a
+`ConceptValidator<T>` is attributed to the field holding the concept, not to the
+concept's inner `Value`, because TypeScript erases the concept to its primitive
+and names the field the same way.
+
+`reason` also distinguishes a genuine rejection from a validator that threw
+while validating hostile or partial input: the latter arrives as a single result
+with a `ValidatorFailed` reason and a generic message, replacing every message
+the validator's author wrote. Do not read the message to tell the two apart.
+
+## Executing with a severity
+
+`command.execute(allowedSeverity?, ignoreWarnings?)` mirrors the server-side
+filtering. `command.validate()` runs authorization and validation on the server
+without the handler; `command.validateClientSide()` runs only the extracted
+rules locally and never touches the network.

package/skills/cratis-arc-command/references/handler-shapes.md

@@ -0,0 +1,135 @@
+# Handler shapes and how Arc dispatches them
+
+Verified against `Cratis.Arc.Core` and `Cratis.Arc.Chronicle` `22.10.4` with
+`Cratis.Chronicle` `16.39.1`.
+
+## The pipeline around `Handle`
+
+One command execution runs in this order:
+
+1. resolve the handler — no handler produces a `MissingHandler` result;
+2. build the command context, including the resolved event source id;
+3. begin every `ICommandExecutionScope`;
+4. run the command filters — **authorization filters first**, then the rest,
+   stopping at the first blocking verdict;
+5. resolve `Handle`'s arguments, which is where `Provide()` runs;
+6. invoke `Handle`;
+7. dispatch the returned value;
+8. complete the execution scopes in reverse order.
+
+If the final result is not successful, the response is **cleared** before it is
+serialized. A caller never receives both a failure and a payload.
+
+Authorization runs before validation deliberately: sorting authorization filters
+first is what stops a validation failure from short-circuiting the chain and
+leaving the authorization verdict at its permissive default.
+
+## Dispatch
+
+The returned value is dispatched on its **runtime** type, not on the method's
+declared return type.
+
+- `Task<T>` and `ValueTask<T>` are awaited first, then the inner value is
+  dispatched. (`ARC0010` warns when a synchronous result is wrapped in a `Task`
+  for no reason.)
+- A `Result<TValue, TError>` — `Cratis.Monads.Result<,>` from
+  `Cratis.Fundamentals` — is a `OneOf`, so its inner value is unwrapped and
+  dispatched. `Result<TEvent, ValidationResult>` therefore appends on success and
+  becomes a validation failure on error. Both directions have implicit
+  conversions, so `return new SomethingHappened(...)` and
+  `return ValidationResult.Error("...")` both compile in the same method.
+- A tuple has every non-null element dispatched independently.
+- Anything no handler claims becomes the response payload.
+
+## What claims an event
+
+The Chronicle response-value handlers claim a value only when the event type is
+**registered** — that is, the record carries `[EventType]` and Chronicle's event
+type registry knows it.
+
+| Runtime value | Claimed by | Appended to |
+| --- | --- | --- |
+| A registered event record | single-event handler | the command's event source id |
+| `IEnumerable<object>` where every element is a registered event | events handler | the command's event source id |
+| `EventForEventSourceId` | single wrapper handler | the wrapper's own id |
+| A collection containing at least one `EventForEventSourceId`, every other element being a registered event | wrapper-collection handler | each wrapper to its own id, each plain event to the command's |
+
+⚠️ **An unregistered event type is not an error.** No handler claims it, so it
+silently becomes the HTTP response body instead of being appended. A command
+that "runs fine" but appends nothing is almost always a missing `[EventType]`.
+
+An empty collection statically typed as `IEnumerable<EventForEventSourceId>` is
+still recognised and appends nothing, rather than being serialized as the
+response.
+
+`[EventType]` takes an optional id and generation. Pass neither for a new event:
+the identifier defaults to the type name, and `ARCCHR0004` reports an id that
+merely repeats the type name. An id that *differs* from the type name is the
+supported way to rename the record while stored events keep resolving, and is
+left alone.
+
+## The tuple rule
+
+Within a tuple:
+
+1. every element is offered to the handlers;
+2. the elements nothing can handle are candidates for the response;
+3. **more than one unhandleable element throws `MultipleUnhandledTupleValues`** —
+   Arc cannot decide which one is the response;
+4. the single unhandleable element is set as the response *before* the
+   handleable elements are handled, which is what lets the events see it.
+
+That last point is the mechanism behind the create-command idiom: an
+`EventSourceId`/`EventSourceId<T>`-derived value is not appendable, so it becomes
+the response, and `commandContext.GetEventSourceId()` prefers a response that is
+an event-source-id value over the id resolved from the command's properties. The
+events in the same tuple are therefore appended to the id the handler just
+generated, and the client receives it as the response.
+
+```csharp
+public (<ThingId>, <ThingRegistered>) Handle()
+{
+    var id = <ThingId>.New();
+    return (id, new(<Name>));
+}
+```
+
+Returning two ids, or an id and another plain value, is the failure case.
+
+## Cross-stream appends
+
+An event never carries its own event source. To write to another stream, wrap:
+
+```csharp
+public IEnumerable<object> Handle() =>
+[
+    new EventForEventSourceId(From, new <Withdrawn>(Amount)),
+    new EventForEventSourceId(To, new <Deposited>(Amount)),
+];
+```
+
+`EventForEventSourceId` also carries optional `Subject`, `EventStreamType` and
+`EventStreamId` init members when the target stream is not the default.
+
+Concurrency scope is resolved **per target stream** — one expected tail per
+event source id, not one shared across the streams a cross-stream command writes
+to.
+
+Do not reach for `IEventLog` to do this instead. `ARCCHR0007` warns when a
+command's `Handle` injects `IEventLog`, because that bypasses Arc's append
+pipeline along with its correlation and ordering guarantees.
+
+## Failure shapes
+
+| Situation | What the caller sees |
+| --- | --- |
+| No handler for the command type | `ExceptionMessages` names the command type |
+| Authorization filter denies | `IsAuthorized` false, `AuthorizationFailureReason` set |
+| Validator or `Provide()` returns `ValidationResult.Error` | `IsValid` false, `ValidationResults` populated |
+| Append rejected by a Chronicle constraint | a validation failure whose `Reason` says a constraint rejected it and whose `ReasonDetail` names it |
+| `Provide()`/`Handle()` throws | `HasExceptions` true — HTTP 500, not a validation failure |
+| Two unhandleable tuple elements | `MultipleUnhandledTupleValues` becomes an exception outcome |
+
+Branch on `ValidationResult.ReasonDetail` rather than on `Message`. The message
+is prose written for a human and is free to change; the detail is the identity of
+the specific thing that rejected the command.