@cratis/pi 7.34.1 → 7.35.0

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

@@ -10,7 +10,7 @@
 - What is not here
 - The security boundary, stated plainly
 
-Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.41.1`. Types are in
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.75.0`. Types are in
 `Cratis.Arc.Authentication` and `Cratis.Arc.Identity`.
 
 ## The contract
@@ -61,7 +61,9 @@ It reads three headers, all constants on
 | `IdentityIdHeader` | `x-ms-client-principal-id` |
 | `IdentityNameHeader` | `x-ms-client-principal-name` |
 
-All three must be present or the result is `Anonymous`. The principal header is
+The host-wide `ArcOptions.TrustForwardedIdentityHeaders` must be true first;
+otherwise headers are ignored and the result is `Anonymous`. All three must be
+present or the result is `Anonymous`. The principal header is
 base64-decoded and deserialized into `ClientPrincipal`:
 
 ```csharp
@@ -134,11 +136,13 @@ whose `SchemeName` is `"MicrosoftIdentityPlatform"`. `builder.AddCratis()` (the
 `Cratis` package) calls this for you and makes it the **default** authentication
 scheme; `AddCratisArc()` from `Cratis.Arc` does not register it.
 
-⚠️ At `22.41.1` the default is that a plain `builder.AddCratis()` host trusts the unsigned
-`x-ms-client-principal*` headers from **any caller that can reach it** — it is safe
-only behind the ingress described below (tracked as open Arc#2946). If the host is
-not behind such an ingress, do not use this scheme: configure a credential-validating
-ASP.NET Core scheme yourself.
+At **v22.75.0**, `AddCratis()` registers the scheme but forwarded headers do not
+authenticate anybody until `Cratis:Arc:TrustForwardedIdentityHeaders=true`.
+`AddMicrosoftIdentityPlatformIdentityAuthentication()` warns at startup without
+that opt-in; built-in handlers warn on the first header-bearing request.
+The three-argument `MicrosoftIDentityPlatformAuthHandler` constructor is obsolete;
+use the constructor receiving `IOptions<ArcOptions>`.
+Source: [secure defaults](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/upgrading/secure-defaults.mdx).
 
 ## Forwarded headers, ingress requirements and protected introspection
 
@@ -148,44 +152,36 @@ prevents direct access to the backend**. The same applies to any custom header
 such as `X-User-ID`. Adding a bearer validator does not make a separately accepted
 forwarded-header mechanism safe.
 
-Arc applies that rule to one place itself: the protected introspection catalogs
-(`/.cratis/commands`, `/.cratis/queries`). By default those are enabled and
-**anonymous**. Configure `Cratis:Arc:Introspection`:
+Configure discovery through `Cratis:Arc:Introspection` at **v22.75.0**:
 
 | Option | Default | Effect |
 | --- | --- | --- |
-| `Enabled` | `true` | `false` leaves both catalog routes unmapped |
-| `RequireAuthentication` | `false` | `true` requires an authenticated caller, regardless of the host's default authorization policy |
-| `Roles` | `null` | Comma-separated, any one grants access; needs `RequireAuthentication: true` and no empty entries |
-| `TrustForwardedIdentityHeaders` | `false` | Accepts identity from the unsigned forwarded headers for the protected catalog; needs `Enabled` and `RequireAuthentication` |
-
-At `22.41.1` the default is that the catalogs are public, and with
-`RequireAuthentication: true` the forwarded headers are **ignored** for them until
-you set `TrustForwardedIdentityHeaders: true`: the built-in
-`MicrosoftIdentityPlatformAuthenticationHandler` returns
-`AuthenticationResult.Anonymous` for a protected catalog endpoint, so the request
-gets 401. **Only set the opt-in behind the trusted ingress above.**
-
-- Startup fails closed for unsafe combinations: `Roles` or the trust option
-  without the requirements above; on Arc.Core, `RequireAuthentication` with no
-  handler, or with only the built-in header handler and no trust opt-in; on
-  ASP.NET Core, a header-trusting scheme reachable from the default scheme or the
-  catalog's policy schemes without the opt-in, and a reachable scheme with
-  `ForwardDefaultSelector` when a header handler is registered.
-- **Custom handlers.** Arc cannot tell whether your own `IAuthenticationHandler`
-  reads forwarded headers, and startup accepts any custom handler as
-  credential-validating. If yours builds an identity from ingress headers, read
-  `IOptions<ArcOptions>` and return `AuthenticationResult.Anonymous` when
-  `TrustForwardedIdentityHeaders` is `false` and
-  `context.GetEndpointMetadata()?.RequireAuthentication == true`. A subclass of the
-  ASP.NET Core header handler that overrides `HandleAuthenticateAsync` without
-  calling the base is your own handler and carries the same obligation.
-- These options do **not** change `/.cratis/identity-details/schema`, command and
-  query invocation, or the user and tenant discovery endpoints. Restrict those at
-  the ingress. On ASP.NET Core a protected catalog's 401/403 is the configured
-  scheme's challenge, which a cookie scheme may turn into a redirect.
-
-Discovery exposure as a whole is tracked in open Arc#2834.
+| `Enabled` | `true` | `false` leaves command/query catalogs unmapped |
+| `IdentityDiscovery` | `true` | `false` removes users, tenants and details schema |
+| `RequireAuthentication` | unset | Environment default: anonymous in Development, authenticated elsewhere |
+| `Roles` | `null` | Comma-separated, any one grants access; implies authentication |
+| `TrustForwardedIdentityHeaders` | `false` | Obsolete compatibility setting; turns on the host-wide trust flag |
+
+The `RequireAuthentication` getter remains `bool` and reads false when unset,
+but **assigning** false is an explicit anonymous-everywhere opt-in, with a warning
+outside Development. Explicit true requires authentication everywhere and fails
+startup if the host cannot enforce it. Roles cannot combine with explicit false.
+Under the environment default a host unable to authenticate omits discovery
+routes (404) and logs a warning. Disabling both discovery switches removes all
+discovery without enforcement checks; `/.cratis/me` remains.
+
+Custom forwarded-header handlers must read `IOptions<ArcOptions>` and refuse
+headers whenever the host-wide flag is false, **on every endpoint**, not only
+protected catalogs. Startup no longer rejects the built-in header scheme for
+protected catalogs: it authenticates nobody without the opt-in. A subclass that
+bypasses `HandleAuthenticateAsync` in the base owns the same obligation.
+On ASP.NET Core, a scheme's challenge may redirect instead of returning 401.
+
+`[ExcludeFromDiscovery]` suppresses catalogs/OpenAPI, not endpoint invocation;
+it is not authorization. These .NET options do not establish a JVM equivalent.
+Sources: [IntrospectionOptions.cs](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Arc.Core/Introspection/IntrospectionOptions.cs),
+[DiscoveryExposure.cs](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Arc.Core/Introspection/DiscoveryExposure.cs),
+[secure defaults](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/upgrading/secure-defaults.mdx).
 
 ## What is not here
 

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

@@ -15,7 +15,7 @@
 - The principal and system actors
 - Protected decisions and validators
 
-Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.41.1`. Everything below
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.75.0`. Everything below
 describes that version and is in `Cratis.Arc.Authorization` unless stated.
 
 ## Versions differ — check the one you run
@@ -32,12 +32,18 @@ another.
 | `22.26.0` | `Cratis:Arc:Introspection` options. |
 | `22.30.0` | `IFallbackAuthorizationEvaluator` and `AuthorizationPolicyContext.ReceivedAt`. |
 | `22.31.0` | Opt-in policy evaluation for unauthenticated callers. |
+| `22.31.2` | Identity/declaration continuity rechecked around policy evaluation. |
+| `22.43.0` | Forwarded identity headers require host-wide trust opt-in. |
+| `22.44.2` | Guest-policy endpoints reachable over HTTP, including with authenticated fallback. |
+| `22.45.0` | Discovery anonymous only in Development by default. |
+| `22.46.0` | Identity cookie no longer read or written by the backend. |
+| `22.51.0` | `IdentityDiscovery` controls users/tenants/details schema separately. |
 | `22.39.0` | Protected decisions arrive; the validator boundary at the end of this page is verified at `22.41.1`. |
 
 If you are on a version before `22.21.0`, either upgrade, or use only Arc's
 attributes with roles and treat everything else as unenforced. Do not write a
 policy-protected endpoint on a version before `22.23.0`. The rest of this page
-is `22.41.1` behavior.
+is `22.75.0` behavior.
 
 ## Attributes
 
@@ -142,10 +148,11 @@ opt-in:
 - Only a declaration made **entirely** of opted-in policies, with no roles and no
   schemes, can evaluate guests. Roles and schemes always require authentication.
 
-⚠️ The opt-in governs Arc's pipeline verdict only. At `22.41.1` the HTTP layer can reject
-a guest before the policy runs: a Core host with any authentication handler, or an
-ASP.NET Core `FallbackPolicy` that requires authentication, returns 401 first
-(tracked in Cratis/Arc#2948). Test guest endpoints through the real HTTP host.
+Since 22.44.2, guest-policy endpoints accept unauthenticated callers on both HTTP
+hosts, even with an authenticated fallback policy, when every declared policy
+opts in. Test through the real HTTP host, not only the in-process verdict.
+Source at v22.75.0: `Documentation/backend/csharp/introspection/index.md` and the
+host authorization specs under `Source/DotNET`.
 
 ⚠️ Because a method replaces its type, a method-level guest policy on a read model
 with a type-level `[Roles("Admin")]` is reachable by guests when the policy
@@ -316,4 +323,8 @@ service). So an authorization or ownership rule put in such a validator — or i
 `[Unprotected]` command's validator — is **not decision-safe**. Put
 state-dependent permission and ownership rules in `Provide()` or `Handle()` using
 `DecisionRead<T>` or `IDecisionReads`, and route to the validation and Chronicle
-guidance. Validators that read decision state are tracked in Arc#2831.
+guidance. Arc constructs/certifies discoverable parameterless validators;
+factory-supplied or altered rules fail closed. Keep static/service-locator state
+out of them too: certification is not proof of input purity. Validators that
+read decision state are tracked in Arc#2831.
+Source: [Arc v22.75.0 protected validator boundary](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/chronicle/read-models/injecting-into-commands.md).

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

@@ -0,0 +1,30 @@
+# Cratis AuthProxy as the trusted ingress
+
+Verified against Cratis AuthProxy `v2.30.5` (container image `cratis/authproxy`) and its documentation. AuthProxy is a reverse proxy that authenticates callers (OpenID Connect, JWT) and forwards the result to a backend in exactly the header contract Arc reads. It is the ingress the rest of this skill asks for. Other ingresses (Azure Container Apps or App Service EasyAuth, your own gateway) work if they meet the same four obligations; this page is specific to AuthProxy.
+
+## What it does to the headers
+
+Before forwarding any request, AuthProxy removes every inbound header whose name begins `x-ms-client-principal` (whatever the suffix) and both tenant headers, `x-cratis-tenant-id` and the legacy `Tenant-ID`. For an authenticated caller it then writes its own:
+
+| Header | Carries |
+| --- | --- |
+| `x-ms-client-principal` | The client principal, base64 JSON |
+| `x-ms-client-principal-id` | The provider-local subject |
+| `x-ms-client-principal-name` | The display name; `x-ms-client-principal-name*` holds the RFC 8187 form when the plain value cannot travel verbatim |
+| `x-cratis-tenant-id` | The tenant AuthProxy resolved (absent when none resolved) |
+
+An unauthenticated caller cannot smuggle identity headers downstream, and a client cannot choose the tenant a backend sees. AuthProxy also calls the backend's `GET /.cratis/me` with the same headers to enrich the identity, so a backend behind it must serve that endpoint (Arc does by default).
+
+## The one decision that cannot be fixed afterwards
+
+The headers are **not signed**. A backend cannot tell a request that came through AuthProxy from one that did not, except by the network it arrived on. Only AuthProxy may be able to open a connection to the backend (private network, internal ingress, network policy); otherwise anyone can impersonate any user by sending the header, and everything still appears to work. This is the same trust boundary this skill describes for any ingress. Platform isolation recipes are in the AuthProxy documentation (`Documentation/azure`, `Documentation/aspire`).
+
+## `/.cratis/me` is an authorization decision
+
+`IdentityVerification` on an AuthProxy service defaults to `Required` (fail closed). Only a `2xx` with `"isAuthorized": true` admits the caller. A `404`, an unreachable backend, a timeout (default ten seconds), any other non-`2xx`, an empty or unparseable body, a missing verdict, or `isAuthorized: false` all deny. The earlier `BestEffort` mode denied only on `403`. Consequently your `IProvideIdentityDetails` result is the admission verdict at the proxy, not only display data: return `IsUserAuthorized = false` deliberately, and keep the endpoint reachable and fast. A service can opt back into `BestEffort` explicitly; do not do that to hide a broken identity endpoint.
+
+## Tenants and services
+
+AuthProxy resolves the tenant through ordered strategies under `Cratis:AuthProxy:TenantResolutions` (`Host`, `Claim`, `Route`, `Specified`, `Default`, `SubHost`, `Selection`). The result reaches the backend as `x-cratis-tenant-id`, which is Arc's default tenant header, so an Arc application behind AuthProxy needs no tenancy configuration and the `UseHeaderTenancy("Tenant-ID")` workaround seen in older applications can be removed.
+
+AuthProxy still forwards the legacy `Tenant-ID` and `Service-ID` alongside `x-cratis-tenant-id` and `x-cratis-microservice` during a transition. That forwarding is deprecated and will be removed in a future major release: read the `x-cratis-*` names. Tenant resolution says which tenant the request is for; it is not an authorization decision and does not isolate storage (see [tenancy](tenancy.md)).

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

@@ -7,7 +7,7 @@
 - `RequireRole`
 - MVVM
 
-Verified against `@cratis/arc` and `@cratis/arc.react` `22.41.1`.
+Verified against `@cratis/arc` and `@cratis/arc.react` `22.75.0`.
 
 ## `@cratis/arc/identity`
 
@@ -27,12 +27,13 @@ interface IIdentity<TDetails = object> {
 
 | Member | Notes |
 | --- | --- |
-| `static readonly CookieName = '.cratis-identity'` | The cookie `/.cratis/me` writes |
+| `static readonly CookieName = '.cratis-identity'` | Deprecated legacy cookie name; current backend neither reads nor writes identity there |
 | `static setHttpHeadersCallback(callback)` | Headers to send on the refresh call |
 | `static setApiBasePath(path)` / `static setOrigin(origin)` | Where `/.cratis/me` lives |
-| `static getCurrent<TDetails>(type?)` | Reads the **cookie**, no network call |
+| `static getCurrent<TDetails>(type?)` | Fetches `/.cratis/me`, caches a resolved identity in memory |
 | `static refresh<TDetails>(type?)` | Fetches `<apiBasePath>/.cratis/me` |
-| `static clearIdentityCookie()` | Expires the cookie |
+| `static clearCache()` | Forgets memory cache and expires a legacy cookie; use on logout |
+| `static clearIdentityCookie()` | Deprecated alias for `clearCache()` |
 
 `IIdentityProvider` is an abstract class with a single
 `getCurrent<TDetails>(type?)`, which is what a view model injects.
@@ -40,9 +41,11 @@ interface IIdentity<TDetails = object> {
 `IdentityProviderResult` on the wire is
 `{ id: string; name: string; roles: string[]; details: object }`.
 
-`getCurrent` reads the cookie and never touches the network. That is what makes
-it cheap, and also why nothing it returns is a security decision — the cookie is
-deliberately not `HttpOnly`, so the browser can read *and write* it.
+`getCurrent` fetches once for a resolved identity; `refresh` always asks again.
+Only a 404 enables the warned legacy-cookie fallback; a cookie never overrides
+401/403. Stop reading `.cratis-identity` in application code. Neither the memory
+cache nor the legacy fallback is an authorization boundary.
+Source: [Arc v22.75.0 IdentityProvider.ts](https://github.com/Cratis/Arc/blob/v22.75.0/Source/JavaScript/Arc/identity/IdentityProvider.ts).
 
 ## `@cratis/arc.react/identity`
 
@@ -102,8 +105,8 @@ Everything that is not an unambiguous yes renders `forbidden`:
 - the predicate throws;
 - an `allow` predicate with absent or `null` details.
 
-⚠️ **This hides UI; it does not protect data.** The identity comes from a cookie
-the browser can edit, so anyone can render these children at will. Every query
+⚠️ **This hides UI; it does not protect data.** Identity comes from the endpoint,
+but anyone can edit browser state and render these children at will. Every query
 and command behind the gate must carry its own `[Authorize]`/`[Roles]` on the
 server, where the decision cannot be edited.
 

package/package/corpus/skills/cratis-arc-authentication-authorization-and-identity/references/local-development.md

@@ -1,6 +1,6 @@
 # Running with an identity locally
 
-Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.41.1`.
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.75.0`.
 
 ## What Arc does not give you
 
@@ -28,18 +28,18 @@ public record User(ClientPrincipal MicrosoftIdentity, object Details);
 public interface ICanProvideUsers { Task<IEnumerable<User>> Provide(); }
 ```
 
-⚠️ Both are mapped `AllowAnonymous` and **unconditionally** — there is no
-environment check in the mapper, so they are anonymous in Production too, and an
-ASP.NET `FallbackPolicy` does not protect them. Without providers they return
-empty arrays. Whatever your implementations return is public to anyone who can
-reach the application. The `Cratis:Arc:Introspection` options do not affect them;
-restrict them at the ingress (see the discovery note in the skill). Register them only for a development
-environment, and return fixtures rather than production users or tenants.
+At **v22.75.0**, both follow `Introspection.IdentityDiscovery` and discovery
+access settings: anonymous by default only in Development, authenticated elsewhere,
+or unmapped (404) if the host cannot authenticate. Return development fixtures,
+not production users or tenants.
+Source: [secure defaults](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/upgrading/secure-defaults.mdx).
 
 ## Supplying an identity locally
 
 Because the shipped handler reads forwarded headers, the way to run with an
-identity locally is to send those headers yourself. All three are required:
+identity locally is to send those headers yourself **after explicitly enabling**
+`Cratis:Arc:TrustForwardedIdentityHeaders=true` in the isolated development host.
+Without it they are ignored. All three are required:
 
 - `x-ms-client-principal-id`
 - `x-ms-client-principal-name`

package/package/corpus/skills/cratis-arc-authentication-authorization-and-identity/references/observable-emission-guards.md

@@ -9,7 +9,7 @@
 - Cost
 - What a guard does not protect
 
-Verified against `Cratis.Arc.Core` `22.41.1` (`Cratis.Arc.Queries`).
+Verified against `Cratis.Arc.Core` `22.75.0` (`Cratis.Arc.Queries`).
 
 Authorization for an observable query runs **once, when the subscription is
 established**. It decides whether the caller may obtain the live stream. It does
@@ -42,7 +42,9 @@ public class SessionMustStillBeActive(ISessions sessions) : IGuardObservableQuer
 Arc API, and never an always-true stub.
 
 It runs on **every emission** of **every subscription**, on **every transport**:
-the multiplexed hub, WebSocket and SSE.
+the multiplexed hub, WebSocket and SSE. Since 22.69.1 it also runs with
+read-model interceptors on plain HTTP snapshots, waits and long polls.
+Source: [Arc v22.75.0 ObservableQueryHttp.cs](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Arc.Core/Queries/ObservableQueryHttp.cs).
 
 ## Verdicts
 
@@ -104,9 +106,10 @@ a failure.
 
 ## What a guard does not protect
 
-- The HTTP **snapshot** path (`ObservableQueryHttp`, including
-  `waitForFirstResult=true`) is not an emission guard path. Apply subscription-time
-  authorization and safe data selection to every query.
+- Plain HTTP **is** guarded at v22.75.0: suppression returns 202 until an allowed
+  emission (or the wait deadline), denial returns unauthorized with no data.
+  Before 22.69.1 that path was unguarded. Keep safe data selection and initial
+  authorization on every query regardless of transport.
 - A guard is not a substitute for the subscription-time declaration: the
   `[Authorize]`/`[Roles]`/policy on the read model still decides who may subscribe.
 - Interceptor masking is not an access control; the producer must never yield

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

@@ -1,6 +1,15 @@
 # Tenancy
 
-Verified against `Cratis.Arc.Core` `22.41.1`. Types are in `Cratis.Arc.Tenancy`.
+## Contents
+
+- Constants
+- Options and defaults
+- The resolvers
+- Reading the tenant
+- Development listing
+- Where the boundary is
+
+Verified against `Cratis.Arc.Core` `22.75.0`. 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
@@ -64,6 +73,12 @@ the configured value.
 literal string `"[NotSet]"`. `TenantId.Default` is `"Default"`. ⚠️ `IsDefault`
 is `this == NotSet || this == Default` — it is true for an **unresolved** tenant
 as well, so it cannot tell "single-tenant default" from "nothing resolved".
+Arc for .NET has no tenancy-required switch. Empty header/query resolution
+becomes `NotSet`; Chronicle's `TenantNamespaceResolver` maps `IsDefault` (both
+`NotSet` and `Default`) to its default namespace. Refuse unresolved tenants in
+application authorization when required; resolution alone is not isolation.
+Sources at Arc v22.75.0: `Arc.Core/Tenancy/TenancyOptions.cs` and
+`Chronicle/Tenancy/TenantNamespaceResolver.cs` under `Source/DotNET`.
 Compare against `TenantId.NotSet` explicitly, or use
 `CurrentTenantIdIsNotSet.ThrowIfNotSet(...)`, wherever an unresolved tenant must
 be refused.
@@ -82,9 +97,10 @@ created after beginning it.
 
 `ICanProvideTenants` (`Task<IEnumerable<Tenant>> Provide()`) feeds
 `GET /.cratis/tenants`, where `Tenant` is `record (TenantId Id, TenantName Name)`.
-The endpoint is `AllowAnonymous` and mapped unconditionally — also in Production,
-and an ASP.NET fallback policy does not protect it — so an implementation that
-returns real tenants publishes them. Return development fixtures only.
+The endpoint follows `Introspection.IdentityDiscovery` and discovery access:
+anonymous only in Development by default, authenticated elsewhere, or unmapped
+when the host cannot authenticate. Return development fixtures only.
+Source: [Arc v22.75.0 secure defaults](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/upgrading/secure-defaults.mdx).
 
 ## Where the boundary is
 

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

@@ -26,18 +26,24 @@ or a combination.
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.Core` | `22.16.0` | `Cratis.Arc.Commands.ModelBound.CommandAttribute`, `CommandResult`, `CommandValidator<T>` |
-| `Cratis.Arc.Chronicle` | `22.16.0` | event append handling, `Cratis.Arc.Chronicle.Commands.NotAuditedAttribute` |
-| `Cratis.Arc.ProxyGenerator.Build` | `22.16.0` | `CratisProxiesOutputPath` MSBuild integration |
-| `Cratis.Fundamentals` | `7.19.2` | `Cratis.Monads.Result<TResult, TError>` |
+| `Cratis.Arc.Core` | `22.75.0` | `Cratis.Arc.Commands.ModelBound.CommandAttribute`, `CommandResult`, `CommandValidator<T>` |
+| `Cratis.Arc.Chronicle` | `22.75.0` | event append handling, `Cratis.Arc.Chronicle.Commands.NotAuditedAttribute` |
+| `Cratis.Arc.ProxyGenerator.Build` | `22.75.0` | `CratisProxiesOutputPath` MSBuild integration |
+| `Cratis.Fundamentals` | `7.23.0` | `Cratis.Monads.Result<TResult, TError>` |
 | `Cratis.Chronicle` | `18.3.0` | `EventTypeAttribute`, `EventForEventSourceId`, `ICanProvideEventSourceId` |
-| `@cratis/arc` | `22.16.0` | `ICommand`, `CommandResult`, `ValidationResult` |
+| `@cratis/arc` | `22.75.0` | `ICommand`, `CommandResult`, `ValidationResult` |
 
-> Re-verified at the versions above by **symbol and signature**: every type, attribute and member this skill names exists at that tag, and the public surface it describes is unchanged since the previous verification (Chronicle 16.45.x / Arc 22.10.4 — the Chronicle 16→18 client diff is converters, options and doc comments; no type was removed or renamed). Behavior claims were verified at the earlier tag unless a section says otherwise.
+> Arc surface rechecked at v22.75.0, including the source-pinned references below.
+> Arc's package dependency is Chronicle 19.39.1 / Fundamentals 7.23.0; separately
+> version-qualified Chronicle/Fundamentals claims retain their own verification.
+
+Fundamentals rechecked at v7.23.0 in
+[`Result<TResult, TError>`](https://github.com/Cratis/Fundamentals/blob/v7.23.0/Source/DotNET/Fundamentals/Monads/Result%7BTResult,TError%7D.cs):
+success is first, error second, with implicit conversions from both types.
 
 Reverify before claiming support for another version. Arc without Chronicle is a
 supported setup; everything on this page that appends events needs Chronicle.
-Operation guidance below is verified at **Arc v22.48.1**; see
+Operation guidance below is rechecked at **Arc v22.75.0**; see
 `cratis-arc-command-operation` for its source and recovery contract.
 
 ## Declare the command
@@ -126,7 +132,7 @@ processes a non-null result, so a `null` is success with nothing appended and th
 caller is told a command succeeded that never happened. Missing state or a failed
 rule is a rejection: return `Result<TEvent, ValidationResult>` with
 `ValidationResult.Error(...)`, or reject in a validator or `Provide()`. Optional
-`ICommandOperation` returns are a separate contract and unaffected. A nullable
+`ICommandOperation` returns are a separate contract and unaffected. `ARCCHR0015` warns on nullable event returns. A nullable
 read-model parameter (`ARC0006`) is handled by rejecting, never by returning a
 nullable event.
 
@@ -166,7 +172,7 @@ public record Transfer(<AccountId> From, <AccountId> To, <Money> Amount)
 
 ## Generate a server-owned new identifier
 
-**Arc 22.66.0+**, verified at **v22.68.0**: the create-command example above
+**Arc 22.66.0+**, verified at **v22.75.0**: the create-command example above
 requires `<ThingId>` to implement `IGeneratable<ThingId>` with a static `New()`
 strategy (Fundamentals 7.23.0+; see `cratis-fundamentals-concept`). Replace
 `Guid.NewGuid()` or `<ThingId>.New()` inside `Handle()` with a generated parameter,
@@ -201,6 +207,17 @@ 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.
 
+`[Key]` on a positional record's primary-constructor parameter is recognized
+and counted once. Child-only/nested read-model types are not standalone
+command-scoped models. `[EventSource<TSource>(stream)]` supplies source type and
+stream metadata on commands and aggregate roots.
+
+Read [decisions and routing](references/decisions-and-routing.md) when a command
+needs guarded state, stream-id templates, definition-backed routes, event tags or
+post-commit `CompleteStream`. Plain read-model injection remains advisory;
+`Result<,>` alone is not concurrency protection. Explicit routing on a returned
+`EventForEventSourceId` wins over command context.
+
 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
@@ -283,7 +300,7 @@ 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.16.0" />
+<PackageReference Include="Cratis.Arc.ProxyGenerator.Build" Version="22.75.0" />
 
 <PropertyGroup>
   <CratisProxiesOutputPath>$(MSBuildThisFileDirectory)../<Web>/src/api</CratisProxiesOutputPath>
@@ -295,6 +312,11 @@ either way, so the reading is all a reviewer has to go on.
 file path. When configuring proxy generation or diagnosing missing or stale output, read [proxy generation](references/proxy-generation.md) for the full
 set of MSBuild knobs and the common failures.
 
+`[BlockOnValidationSeverity(ValidationResultSeverity.Warning)]` declares the
+lowest blocking severity for validation, `Provide` and execution. Caller
+`allowedSeverity`/`X-Allowed-Severity` can only make it stricter; `Unknown` blocks.
+The proxy carries `blockOnValidationSeverity` and honors it client-side.
+
 ## The generated client contract
 
 The generated proxy is a `Command` from `@cratis/arc`. Its members are the same

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

@@ -7,7 +7,9 @@
 - Client side
 - Executing with a severity
 
-Verified against `Cratis.Arc.Core` `22.16.0` and `@cratis/arc` `22.16.0`.
+Verified against `Cratis.Arc.Core` and `@cratis/arc` **v22.75.0**.
+Sources: `Source/DotNET/Arc.Core/Commands/CommandResult.cs`,
+`CommandValidationResults.cs` and `Source/JavaScript/Arc/commands/Command.ts`.
 
 ## Server side
 
@@ -43,10 +45,15 @@ value into the error body.
 `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.
+Only *blocking* results survive onto the result. For an unannotated command,
+with no `allowedSeverity`, only `Error` blocks; with a caller threshold, anything
+strictly greater blocks. `[BlockOnValidationSeverity(ValidationResultSeverity.Warning)]`
+(`Cratis.Arc.Commands.ModelBound`) declares an inclusive blocking floor across
+HTTP, Validate, Provide and in-process execution. Caller `X-Allowed-Severity` or
+`allowedSeverity` can tighten, never loosen, that floor; attributed commands
+also block `Unknown`. The generated proxy carries `blockOnValidationSeverity`
+and applies it client-side. This attribute does not change an unannotated
+command's legacy filtering.
 
 ## Client side
 

package/package/corpus/skills/cratis-arc-command/references/decisions-and-routing.md

@@ -0,0 +1,95 @@
+# Protected decisions and routed streams
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+Verified at **Arc v22.75.0**. These features require `Cratis.Arc.Chronicle`.
+
+## Pick the guarded read
+
+Plain injected read models and `IReadModels.GetInstanceById` are advisory. A
+`Result<TEvent, ValidationResult>` rejects a request but does not enroll a guard.
+
+- For one stream, inject `IStreamReads` into `Provide`, call `ForCommand()`, and
+  return `StreamDecision.Append(...)` from `Handle`. It returns
+  `EventsWithConcurrencyScopes`, retaining the read route and exact tail. A
+  competing append conflicts, including two competing first appends.
+- For projected state, opt in with `[ProtectedDecision]` in
+  `Cratis.Arc.Chronicle.ReadModels`, then inject `DecisionRead<T>` into
+  `Provide`/`Handle` (`Exists`/`Instance`). Command-aware `IDecisionReads.Get<T>`
+  enrolls reads of other keys. Only Chronicle-admitted direct event-source-keyed
+  projections with a known event-type set qualify; reducers, joins, children,
+  passive and incomplete definitions are refused. Arc certifies parameterless
+  validators it constructs; constructor dependencies and uncertified instances
+  are refused. Keep all decision state out of validators, including static
+  members and service locators. `[Unprotected]` on the command opts out; never
+  combine it with `[ProtectedDecision]`. A parameter-level marker acknowledges
+  tooling, not a runtime opt-out. `Validate` is advisory, not a commit promise.
+- Automatic `concurrency: true` on the routing attributes supplies stream-level
+  scopes. Exact returned scopes replace automatic capture; remove the flags
+  when returning `EventsWithConcurrencyScopes` (ARCCHR0016).
+
+Do not manually append or commit to bypass the owner-capable unit of work.
+Protection does not guard foreign writers, external state, revisions, redactions,
+migrations or changes to projection definitions. A successful empty protected
+command still validates enrolled reads. In contrast, `StreamDecision.Append([])`
+returns no scopes: use it only for an identical retry, not a rejected request.
+
+## Definition-backed routes and templates
+
+`[EventSource<TSource>(stream)]` supplies source type and stream metadata on
+commands and aggregate roots from a discovered definition. ARCCHR0013 recommends
+it; ARCCHR0014 flags observer streams absent from that definition.
+
+`[EventStreamId("{ReportingScopeId}:{Period}")]` resolves a command template after
+validation. Concept properties contribute underlying values.
+`EventStreamIdTemplate.ResolveFor(command)` exposes the same resolution.
+ARCCHR0017/0018 check invalid templates/properties. On reactors the value is
+literal, not a command template. `AmbiguousEventStreamId` rejects a non-NotSet
+attribute value combined with `ICanProvideEventStreamId`, **including templates**.
+Choose the attribute or the interface, not both. Source:
+[EventStreamIdTemplate.cs](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Chronicle/Commands/EventStreamIdTemplate.cs).
+
+`IEventRoutes.For<TSource>(stream).WithStreamId(value)` resolves an `EventRoute`;
+`IStreamReads.Stream(id, route)` guards that route, while `StreamType(id, route)`
+guards every stream id of its type. Both require a specific source, stream type
+and append stream id. There is only one exact scope per source id: do not combine
+two independent stream decisions for the same source and assume both are guarded.
+`route.Route(id, fact)` produces a routing wrapper. Explicit routing on a returned
+`EventForEventSourceId` wins over command context in every return shape.
+
+## Tags and completion
+
+In `Cratis.Arc.Chronicle.Commands`, `[EventTag("projectId", nameof(ProjectId))]`
+takes a property and `[EventTag("origin", Value = "import")]` a constant. Each
+attribute must have exactly one source. `ICanProvideEventTags` computes command
+tags; returned `EventTags` supplies handler-known tags; discovered scoped/transient
+`ICanProvideCommandEventTags` providers add application conventions. All sources
+form a union distinct by name/value pair; wrapper tags are preserved. Tags apply
+to returned events, not manual appends or aggregate commits.
+
+Return `CompleteStream` (`Cratis.Arc.Chronicle.Streams`) alone or with events in
+a command tuple. It completes **after commit**, not atomically with append.
+Completion is keyed by stream type/id across the entire event log, not source id.
+A failure leaves earlier events committed; retry completion rather than blindly
+duplicating events. Reactors may return it directly, using the observed route;
+reactor tuples/collections cannot mix it with events.
+
+## Decision specifications
+
+Call `new CommandScenario<T>().UseDecisionReads()` before seeding events.
+`Given.ForEventSource(id).OnRoute(route).Events(...)` and
+`AppendConcurrently(id, route, ...)` share one real in-process log. Pinned models
+cannot supply guards. Assert a real nonempty decision conflicts on the intended
+route, and that an independent route is not over-guarded.
+`ShouldHaveCompletedStream(type, id)` asserts completion;
+`DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly)` checks projection
+admission in assembly-level specs.
+
+## Sources at v22.75.0
+
+- [Stream decisions](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/chronicle/commands/stream-decisions.md)
+- [Protected read-model decisions and limitations](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/chronicle/read-models/injecting-into-commands.md)
+- [Concurrency and templates](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/chronicle/commands/concurrency.md)
+- [Event tags](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/chronicle/commands/event-tags.md)
+- [Completing streams](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/chronicle/commands/completing-streams.md)

package/package/corpus/skills/cratis-arc-command/references/generated-values.md

@@ -102,7 +102,7 @@ ordinary response, event and compliance contracts.
 
 ## Analyzer diagnostics
 
-Arc v22.68.0 reports these at compile time; none has a code fix. Runtime
+Arc v22.75.0 reports these at compile time; none has a code fix. Runtime
 handler-construction checks remain for declarations compiled without analyzers.
 
 | Diagnostic | Severity | Fix |
@@ -154,7 +154,8 @@ Published guides:
   [ARC0024](/arc/backend/csharp/code-analysis/arc0024/),
   [ARC0025](/arc/backend/csharp/code-analysis/arc0025/).
 
-Source at **Arc v22.68.0**: `Source/DotNET/Arc.Core/Commands/ModelBound/GeneratedValueAttribute.cs`,
+Source rechecked at **Arc v22.75.0** (generation/pinning APIs unchanged since
+the prior verification): `Source/DotNET/Arc.Core/Commands/ModelBound/GeneratedValueAttribute.cs`,
 `Commands/GeneratedValueParameters.cs`, `GeneratedValueFactories.cs`,
 `CommandHandlerArgumentResolver.cs`, `GeneratedValueResolution.cs`;
 `Source/DotNET/Arc.Core.CodeAnalysis/DiagnosticDescriptors.cs`; and