@cratis/pi 7.34.1 → 7.36.0

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

@@ -9,9 +9,11 @@
 - Cross-stream appends
 - Failure shapes
 
-Verified against `Cratis.Arc.Core` and `Cratis.Arc.Chronicle` `22.16.0` with
-`Cratis.Chronicle` `18.3.0`. Operation dispatch additions are verified against
-Arc **v22.48.1**, `CommandPipeline` and `CommandOperationExecution`.
+Verified against `Cratis.Arc.Core` and `Cratis.Arc.Chronicle` **v22.75.0**
+(Chronicle dependency 19.39.1). Sources: `Source/DotNET/Arc.Core/Commands/CommandPipeline.cs`,
+`CommandOperationExecution.cs` and `Source/DotNET/Chronicle/Commands/CommandContextExtensions.cs`.
+Read [decisions and routing](decisions-and-routing.md) for guarded reads,
+stream templates, tags and post-commit completion.
 
 ## The pipeline around `Handle`
 
@@ -113,11 +115,8 @@ 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>));
-}
+public (<ThingId>, <ThingRegistered>) Handle([GeneratedValue("thing")] <ThingId> id) =>
+    (id, new(<Name>));
 ```
 
 Returning two ids, or an id and another plain value, is the failure case.
@@ -136,6 +135,7 @@ public IEnumerable<object> Handle() =>
 
 `EventForEventSourceId` also carries optional `Subject`, `EventStreamType` and
 `EventStreamId` init members when the target stream is not the default.
+Explicit wrapper routing wins over command-context routing in every return shape.
 
 A command that always appends through a Chronicle event source definition (Arc 22.49.0
 and later, definitions from Chronicle 19.30.0) declares it with

package/package/corpus/skills/cratis-arc-command/references/proxy-generation.md

@@ -1,6 +1,13 @@
 # Proxy generation
 
-Verified against `Cratis.Arc.ProxyGenerator.Build` `22.16.0`.
+## Contents
+
+- Wiring
+- MSBuild properties
+- What the generator extracts for client-side validation
+- Failure modes
+
+Verified against `Cratis.Arc.ProxyGenerator.Build` `22.75.0`.
 
 ## Wiring
 
@@ -8,7 +15,7 @@ Reference the build package from the project that contains the commands,
 queries and read models, and set an output path:
 
 ```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>
@@ -27,7 +34,8 @@ Output folders mirror the C# **namespace**, not the file path. A command in
 
 ## MSBuild properties
 
-The first nine properties below are declared with the default shown in the package's `.props`; the last three are read by the `.targets` only when set to `true` (absent means off).
+Properties below are forwarded by the package's `.props`/`.targets`; boolean
+switches without a declared default are off when absent.
 
 | Property | Default | Effect |
 | --- | --- | --- |
@@ -42,12 +50,20 @@ The first nine properties below are declared with the default shown in the packa
 | `CratisProxiesSkipFileIndexTracking` | `false` | Disables tracking which files the generator owns |
 | `CratisProxiesSkipIndexGeneration` | `false` | Does not write the per-folder `index.ts` barrels |
 | `CratisProxiesUseSourceFileAsOutputFile` | `false` | Names the generated file after the C# source file rather than the type |
+| `CratisProxiesUseProxyFileSuffix` | off | Emits `Name.proxy.ts` and matching barrels; avoids `.ts`/`.tsx` basename collisions |
 | `CratisProxiesEmitInterfaces` | off | **Arc ≥ 22.15.0** (the underlying `--emit-interfaces` flag exists from 22.14.0; the MSBuild property from 22.15.0). Emits plain TypeScript `interface`s instead of `@field`-decorated classes — no `@cratis/fundamentals` import in the output. Only for consumers that never reconstruct instances from JSON; command and query proxies need the classes |
 
 ⚠️ `CratisProxiesSkipOutputDeletion` defaults to `true`. Guidance that tells you
 to set it to `true` "so the generator does not delete your hand-written files"
 is describing the default, not a fix.
 
+The generator preserves hand-written `index.ts` exports, and generated files
+follow the Cratis ESLint configuration. Named concepts live only in the backend
+model: generated TypeScript erases them to primitives; nullable concept properties
+are optional. Source at Arc v22.75.0: `Tools/ProxyGenerator/ConceptMap.cs` and
+`Tools/ProxyGenerator.Build/build/Cratis.Arc.ProxyGenerator.Build.targets` under
+`Source/DotNET`.
+
 Item groups the target also forwards: `AssemblyToPackageMapping`,
 `ExcludeType`, `ExcludeNamespace`, `NamespaceRoot`, and `TypeToTsType`.
 
@@ -74,6 +90,9 @@ Rules declared on a `ConceptValidator<T>` are projected onto every property
 typed as that concept, so declaring a value's format once validates it in the
 browser too.
 
+Conditional `When`/`Unless` rules are not projected to the client. Extracted
+rules retain severity (`withSeverity`); command blocking thresholds still apply.
+
 ⚠️ **`Must(...)` is not extracted.** Neither is any rule that needs an injected
 dependency. Those run on the server only, which means
 `validateClientSide()` can pass while `execute()` still fails validation.

package/package/corpus/skills/cratis-arc-command/references/read-model-injection.md

@@ -1,6 +1,18 @@
 # Injecting a read model into a command
 
-Verified against `Cratis.Arc.Core` `22.16.0` and `Cratis.Chronicle` `18.3.0`.
+## Contents
+
+- Nullability is the required/optional switch
+- `null` is not always what absence looks like
+- Which provider owns a read model type
+
+Arc injection verified at **v22.75.0**, with Chronicle dependency 19.39.1;
+separate Chronicle absence behavior below retains its original version context.
+Source: [read models in commands](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/chronicle/read-models/injecting-into-commands.md).
+Plain models and keyed reads are advisory, not concurrency guards. For protected
+reads use [decisions and routing](decisions-and-routing.md): opt into
+`[ProtectedDecision]` before taking `DecisionRead<T>`; constructor-injected
+validators are refused there.
 
 A read model can be injected into a `CommandValidator<T>` constructor, into
 `Provide()`, or into `Handle()`. Arc resolves it through an

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

@@ -16,14 +16,16 @@ recovery; calling `Handle()` directly only returns their declarations.
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.Core` | `22.16.0` | `Cratis.Arc.Commands.ICommandPipeline`, `CommandResult`, `ValidationResultSeverity` |
-| `Cratis.Arc.Chronicle` | `22.16.0` | analyzer `ARCCHR0006` for reactor replay |
+| `Cratis.Arc.Core` | `22.75.0` | `Cratis.Arc.Commands.ICommandPipeline`, `CommandResult`, `ValidationResultSeverity` |
+| `Cratis.Arc.Chronicle` | `22.75.0` | analyzer `ARCCHR0006` for reactor replay |
 
-> 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 execution/severity and returned-reactor effects rechecked at v22.75.0.
+> Arc's Chronicle dependency is 19.39.1; older source-pinned transaction/operation
+> sections below remain explicitly version-qualified.
 
 Reverify before claiming support for another version. Operation execution,
 nesting restrictions, and backend recovery members below are verified at
-**Arc v22.48.1**; see `cratis-arc-command-operation` for sources and limits.
+**Arc v22.75.0**; see `cratis-arc-command-operation` for sources and limits.
 
 ## When this is the wrong tool
 
@@ -43,12 +45,17 @@ it records a failed compensator. Compose operation declarations instead.
 ## Inject and execute
 
 > **Reactors have a declarative alternative.** With the Arc Chronicle integration a
-> reactor handler can **return** the `[Command]` (or a collection of commands) and
-> Arc executes it; a denied or invalid result fails the partition instead of being
+> reactor handler can **return** the `[Command]` or a stable collection mixing
+> commands, registered events and `EventForEventSourceId`. At v22.75.0 events
+> append first; append rejection stops all commands, and the first failed command
+> stops the rest. Earlier effects stay committed, so retries need idempotency.
+> A denied or invalid result fails the partition instead of being
 > discarded, and `[ExecuteCommandsAsSystem]` on the reactor class supplies a
 > principal for those returned commands. That attribute does **not** cover manual
 > `Execute` calls — the form below needs its own execution context. See the
-> **cratis-chronicle-reactor** skill.
+> **cratis-chronicle-reactor** skill. `[ExecuteCommandsAsSystem]` no longer leaks
+> the system actor into the caller (fixed in 22.72.0). A reactor may also return
+> `CompleteStream` directly; it cannot mix completion with events in a collection.
 
 ```csharp
 public class <Name>Reactor(ICommandPipeline pipeline) : IReactor
@@ -138,8 +145,11 @@ Both `Execute` and `Validate` take an optional
 `ValidationResultSeverity? allowedSeverity` from `Cratis.Arc.Validation`. The
 levels are `Unknown = 0`, `Information = 1`, `Warning = 2`, `Error = 3`.
 
-- With no `allowedSeverity`, **only `Error` blocks**, and information and
-  warnings are filtered off the result entirely — they never reach the caller.
+- With no `allowedSeverity`, **only `Error` blocks** for an unannotated command,
+  and information/warnings are filtered off. An attributed command uses
+  `[BlockOnValidationSeverity(...)]` as its inclusive blocking floor; `Unknown`
+  also blocks. Caller thresholds can tighten, never loosen, that floor.
+  Source at Arc v22.75.0: `Arc.Core/Commands/CommandValidationResults.cs`.
 - With an `allowedSeverity`, anything **strictly greater** blocks. Passing
   `Warning` lets warnings through onto the result while errors still block.
 

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

@@ -13,29 +13,33 @@ there is no controller or handler class to write by hand.
 
 ## Verified product sources
 
-Verified against `Arc.Kotlin` at tag **`v7.3.0`**, re-verified at commit
-`d0aa6a4` (14 commits past the tag), against the documented consumer setup:
-JDK 17, Gradle 8.14.4, Kotlin 2.4.20, KSP 2.3.12, Spring Boot 4.1.x. The
-re-verification picked up a real behavior correction to authorization
-override — see "Protect the command" below — confirmed against
-`ArcSymbolProcessorAuthorizationPrecedenceCompilationTest` and
-`buildAuthorization` in `ArcSymbolProcessor.kt`, not documentation prose alone:
-two of Arc.Kotlin's own reference pages (`reference/annotations.md`,
-`troubleshooting.md`) are currently stale on this point relative to
-`guides/security.md`, `reference/parity.md`, and the compiler source. The local workspace version is `0.0.0-SNAPSHOT`; use a released version
-from Maven Central for a real application.
+Verified against `Arc.Kotlin` at tag **`v7.7.0`**: JDK 17, Gradle 8.14.4,
+Kotlin 2.4.20, KSP 2.3.12, Spring Boot 4.1.1, JUnit Jupiter 6.1.3.
+Sources include `ArcSymbolProcessor.kt`, `GradlePlugin/ArcExtension.kt` and
+`Integrations/Cratis`/`Integrations/Chronicle` publishing blocks. Use a released
+version from Maven Central, not the local `0.0.0-SNAPSHOT`.
 
 | Artifact | Purpose |
 | --- | --- |
 | `io.cratis:arc` | `io.cratis.arc.artifacts.Command`, `CommandKey`, `FromServices` |
 | `io.cratis:arc-ksp` | the KSP processor that generates the command handler |
 | `io.cratis:arc-spring-boot-starter` | Spring Boot auto-configuration, the command pipeline host |
-| `io.cratis:arc-chronicle-spring-boot-starter` | optional — Chronicle event append from a returned event |
+| `io.cratis:cratis` | recommended single dependency for an event-sourced app: Arc, Spring Boot wiring and Chronicle integration (`7.5.0+`) |
+| `io.cratis:arc-chronicle-spring-boot-starter` | explicit alternative to `cratis`, same Arc version |
+| `io.cratis:arc-testing` | in-process command and query scenarios (test scope) |
+| `io.cratis:arc-spring-data-jpa`, `io.cratis:arc-spring-data-mongodb` | Spring Data read-model integrations |
+| `io.cratis:arc-rxjava3` | RxJava 3 observable queries |
+| `io.cratis:arc-observability-spring-boot-starter`, `io.cratis:arc-openapi-spring-boot-starter` | optional observability and OpenAPI |
 | `io.cratis.arc` Gradle plugin | applies Kotlin/JVM + KSP, adds the dependencies, configures the module name and proxy output |
 
 Arc.Kotlin has no Chronicle dependency by default. Add the optional Chronicle
-starter only when a command should append a returned event or read a Chronicle
-read model; without it, `handle()` returns an ordinary response value.
+integration only when a command should append a returned event or read a
+Chronicle read model; without it, `handle()` returns an ordinary response value.
+For that setup prefer `implementation("io.cratis:cratis:<version>")` over the
+Arc-only starter in the example below. Arc `7.7.0` brings Chronicle.Kotlin
+`6.10.0` transitively; its compatibility gate uses kernel `19.21.1` (19.x).
+The standalone Chronicle `6.13.0` client needs `19.30.0`; do not assume that
+latest/latest is a verified Arc integration pair.
 
 Java applications still need Kotlin and KSP on the build — Arc generates Kotlin
 adapters for Java declarations even in an all-Java application. A Java project
@@ -181,7 +185,8 @@ data class CompleteTask(val taskId: TaskId) {
 
 ## Return a Chronicle event
 
-Requires the optional `io.cratis:arc-chronicle-spring-boot-starter`. A plain
+Requires `io.cratis:cratis` or the explicit
+`io.cratis:arc-chronicle-spring-boot-starter`. A plain
 event response needs a stable command key backed by `String`, `UUID`, a
 number, or a concept wrapping one of those — mark it `@CommandKey`.
 
@@ -235,9 +240,10 @@ data class CreateTask(@CommandKey val id: String, val title: String) {
 ```
 
 Each annotation is optional and must be nonblank with no control characters
-when present (`ARCKSP0110` otherwise). Omit one to keep Chronicle's own
-fallback: source/stream type default to `Default`, stream id/subject default
-to the event-source identifier. An explicit `EventForEventSourceId` value keeps
+when present (`ARCKSP0110` otherwise). Omitted routing is forwarded as absent by `ChronicleOperationContext`:
+with Chronicle `6.x`, the kernel resolves source/stream type/stream id to
+`Default`/`All`/`Default`; subject defaults to the event-source identifier.
+Pass all routing fields explicitly to preserve a legacy route. An explicit `EventForEventSourceId` value keeps
 its own metadata; only its missing fields inherit the command's declaration.
 Implement `CommandEventStreamIdProvider` or `CommandEventSubjectProvider`
 instead when a value depends on the command instance — never combine a
@@ -271,6 +277,10 @@ A value from `provide` still takes precedence over this injection. A missing
 model leaves the dependency unresolved rather than silently falling through to
 another store; an invalid key or unavailable store fails the command.
 
+Collection naming is shared with Arc's MongoDB integration in `7.7.0`.
+Read [references/read-model-naming.md](references/read-model-naming.md) when
+upgrading an existing projection or overriding its storage collection name.
+
 ## Protect the command
 
 ```kotlin
@@ -337,6 +347,17 @@ they read almost identically. The generated proxy's runtime contract
 `@cratis/arc` client shape as Arc .NET; see the `cratis-arc-command` skill for
 that contract.
 
+`proxies.enabled` defaults to true; `removeStaleGeneratedFiles` defaults to
+true. Set `proxies.useProxyFileSuffix` for `Name.proxy.ts` instead of `Name.ts`
+(CLI: `--use-proxy-file-suffix`). `proxies.mapType(...)` and `mapPackage(...)`
+map external DTOs to TypeScript types/npm packages. Do not map a command or
+concept directly: command mappings fail, and `ConceptAs` is unwrapped to its
+underlying primitive before mapping, so its named type exists only in the backend.
+`@ExportedType` explicitly exports a DTO; KDoc/Javadoc summaries become JSDoc.
+
+`endpoints.routePrefix`, `includeCommandNames`, `includeQueryNames`, and
+`enableQueryHttpMethod` control endpoint conventions separately from proxy paths.
+
 ## Route near misses
 
 - Adding or changing a rejection rule on an existing command:
@@ -344,6 +365,9 @@ that contract.
 - Defining or changing a `@ReadModel` query: `cratis-arc-query-kotlin`.
 - Talking to Chronicle outside a command (a plain worker, a reactor's own
   event types, direct append): `cratis-chronicle-client-kotlin`.
+- In-process command/query specifications: `cratis-arc-testing-kotlin`.
+- Authentication, identity or tenant resolution: `cratis-arc-identity-and-tenancy-kotlin`.
+- Spring Data storage and observations: `cratis-arc-spring-data-kotlin`.
 - The C# Arc command shape and its causation-chain rules: `cratis-arc-command`.
 
 ## Verify
@@ -365,3 +389,5 @@ that contract.
   `allWarningsAsErrors`, Java `-Xlint:all -Werror`).
 - The generated proxy exists at the configured output directory when one was
   configured, and the frontend compiles against it.
+- Exercise the generated module through `cratis-arc-testing-kotlin`, including
+  rejection, authorization and append-failure paths when they apply.

package/package/corpus/skills/cratis-arc-command-kotlin/references/read-model-naming.md

@@ -0,0 +1,29 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Share Arc and Chronicle collection names
+
+Verified at `Arc.Kotlin v7.7.0`: `ChronicleArcAutoConfiguration.arcReadModelNamingPolicy`,
+its Kotlin/Java conformance tests and `Documentation/guides/read-model-naming.mdx`.
+The integration depends on Chronicle.Kotlin `6.10.0`.
+
+With the MongoDB integration present, one Arc `NamingPolicy` bean is adapted
+into Chronicle's `ReadModelNamingPolicy`. Chronicle's starter passes it to the
+options it builds: a projected `Author` lands in `Authors`, where Arc reads it.
+The adapter is absent when the Arc policy is missing/ambiguous or an application
+already declares a Chronicle `ReadModelNamingPolicy` bean. The application bean
+wins; keep its names consistent with Arc's reader.
+
+The policy changes the storage container, not the read-model identifier or
+observer identity. An explicit `@ReadModel(id = ...)` no longer determines the
+collection name under the adapter. Without Arc's Mongo naming policy,
+Chronicle retains identifier-based naming. An application that constructs its
+own `ChronicleOptions` must call `withReadModelNamingPolicy(policy)` itself.
+
+The old `pluralizeReadModelNames = false` workaround is no longer needed for
+this JVM integration. Remove it only after verifying your affected type names
+and reader/projection pairing. Existing documents do not move with the name:
+replay affected projections into the new collections and verify their data;
+drop the old collections only when no longer needed and deletion is authorized.
+Do not claim a .NET-written collection uses the JVM inflector: Arc's default
+policy uses Evo Inflector, while .NET uses Humanizer. Override measured disagreements.

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

@@ -19,15 +19,16 @@ Chronicle is not required.
 
 | Package / source assembly | Verified version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.Core` | `22.48.1` | `Cratis.Arc.Commands`: operation declarations, pipeline, scopes, recovery observations |
-| `Cratis.Arc.Core.CodeAnalysis` / `Cratis.Arc.Core.Generators` | `22.48.1` | ARC0016–ARC0018 and typed invocation; generator ships inside Core, not as a standalone package |
-| `Cratis.Arc.ProxyGenerator` | `22.48.1` | Excludes operations and batches from the client response |
-| `Cratis.Arc.Testing` | `22.48.1` | `Cratis.Arc.Testing.Commands.CommandScenario<TCommand>` and operation assertions |
-| `Cratis.Arc.Chronicle` / `Cratis.Arc.Chronicle.Testing` | `22.48.1` | Deferred event commitment and real in-process constraint-rejection specs |
-
-Verified at **Arc v22.48.1**, against the
-[operation docs](https://github.com/Cratis/Arc/blob/v22.48.1/Documentation/backend/csharp/commands/operations/index.md),
-[execution reference](https://github.com/Cratis/Arc/blob/v22.48.1/Documentation/backend/csharp/commands/operations/reference.md),
+| `Cratis.Arc.Core` | `22.75.0` | `Cratis.Arc.Commands`: operation declarations, pipeline, scopes, recovery observations |
+| `Cratis.Arc.Core.CodeAnalysis` / `Cratis.Arc.Core.Generators` | `22.75.0` | ARC0016–ARC0018 and typed invocation; generator ships inside Core, not as a standalone package |
+| `Cratis.Arc.ProxyGenerator` | `22.75.0` | Excludes operations and batches from the client response |
+| `Cratis.Arc.Testing` | `22.75.0` | `Cratis.Arc.Testing.Commands.CommandScenario<TCommand>` and operation assertions |
+| `Cratis.Arc.Chronicle` / `Cratis.Arc.Chronicle.Testing` | `22.75.0` | Deferred event commitment and real in-process constraint-rejection specs |
+
+Rechecked at **Arc v22.75.0**; operation/recovery sources and the linked lessons
+are unchanged since the prior 22.48.1 verification.
+[Operation docs](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/commands/operations/index.md),
+[execution reference](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/commands/operations/reference.md),
 `Source/DotNET/Arc.Core/Commands/`, the analyzer/generator, and the testing
 sources. Reverify for other versions. These are C# APIs, not the separate
 Arc for TypeScript server API.

package/package/corpus/skills/cratis-arc-command-operation/references/execution-and-recovery.md

@@ -12,8 +12,8 @@
 - Supported scopes
 - Troubleshooting
 
-Verified at **Arc v22.48.1** against the
-[product reference](https://github.com/Cratis/Arc/blob/v22.48.1/Documentation/backend/csharp/commands/operations/reference.md)
+Rechecked at **Arc v22.75.0** (operation/recovery sources unchanged since 22.48.1), against the
+[product reference](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/commands/operations/reference.md)
 and `Source/DotNET/Arc.Core/Commands/`. Types below are in
 `Cratis.Arc.Commands`. Start with [the skill](../SKILL.md) to choose the boundary.
 

package/package/corpus/skills/cratis-arc-command-operation/references/testing.md

@@ -9,9 +9,10 @@
 - Extend the failure coverage
 - Migrate an existing service-backed Handle
 
-Verified at **Arc v22.48.1**. These class excerpts follow the product's
-[standalone lesson](https://github.com/Cratis/Arc/blob/v22.48.1/Documentation/backend/csharp/testing/command-operations.md)
-and [Chronicle rejection lesson](https://github.com/Cratis/Arc/blob/v22.48.1/Documentation/backend/csharp/testing/command-operations-with-chronicle.md).
+Rechecked at **Arc v22.75.0**; operation assertions and these lessons are unchanged
+since 22.48.1. These class excerpts follow the product's
+[standalone lesson](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/testing/command-operations.md)
+and [Chronicle rejection lesson](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/testing/command-operations-with-chronicle.md).
 See "Observe and test on the backend" in SKILL.md.
 
 The standalone examples reuse `ReservationId`, `SeatId`, `ISeatReservations`,

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

@@ -18,7 +18,7 @@ Arc supplies the route, body binding, validation, authorization, and the
   `@cratis/arc.testing`, `@cratis/arc.mongodb`, `@cratis/arc.drizzle`,
   `@cratis/arc.chronicle`, `@cratis/cratis`, `@cratis/arc.proxygenerator` and
   `@cratis/eslint-plugin-arc-core` are an unpublished source preview (0.x
-  manifests; versions appear only as source-only GitHub pre-releases). The API may still change. `npm install @cratis/arc.core` fails.
+  manifests; GitHub pre-releases v0.1.0–v0.57.2). The API may still change. `npm install @cratis/arc.core` fails.
 - **`@cratis/arc` is a different package.** `@cratis/arc`, `@cratis/arc.react` and
   `@cratis/arc.react.mvvm` are the published **client** runtime, built from
   `Cratis/Arc`. Generated proxies import them in the frontend. The server packages
@@ -29,26 +29,28 @@ Arc supplies the route, body binding, validation, authorization, and the
 
 ## Verified product sources
 
-Verified against `Cratis/Arc.TypeScript` `main` at commit `94d398d` (tag
-`v0.33.0` plus three commits), reading `Source/Core/index.ts` and the package
-`index.ts` exports, `Documentation/**`, and the `Samples/Tasks` and
-`Samples/Library` applications. Every API named here exists at that commit.
-Chronicle SDK: `@cratis/chronicle` peer `^6.7.0`; the Library sample pins
-`6.14.0`. Fundamentals: `@cratis/fundamentals` `^7.19.6`.
+Verified against `Cratis/Arc.TypeScript` tag **v0.57.2** (GitHub pre-release;
+server manifests 0.57.2), reading package exports, `Documentation/**`, and
+`Samples/Tasks` / `Samples/Library`. Unreleased main/0.58.0 behavior is excluded.
+Chronicle SDK: peer `^6.29.0`, built against/sample pin `6.35.0`;
+Fundamentals peer `^7.19.6`, Library pin `7.22.0`. The Chronicle integration
+needs Node 22.19+, `zod ^4.1`, `rxjs ^7.8.2`, and an optional
+`@cratis/arc.testing` peer for scenarios.
 
-Read [references/hosting-and-storage.md](references/hosting-and-storage.md) when setting up a host, using the Fetch entry, or wiring storage integrations. Read [references/chronicle-events.md](references/chronicle-events.md) when returning Chronicle events or specifying those commands.
+Read [references/hosting-and-storage.md](references/hosting-and-storage.md) when
+hosting or wiring storage. Read [references/chronicle-events.md](references/chronicle-events.md)
+when returning or specifying Chronicle events.
 
 ## Chronicle traps
 
-- Appending and projecting are separate: a query sent right after the command
-  may not see the event yet. Prefer an observable query on the client.
-  `completionTimeoutMs` makes the command wait for observers, but Chronicle waits
-  for **every** observer on the log (Cratis/Chronicle#4132), so a projection or
-  reactor that does not handle the event makes every command time out with 500.
+- Appending and projecting are separate; prefer observable reads. See the
+  Chronicle reference before using `completionTimeoutMs` to wait for observers.
 
-- The in-memory scenario does **not** run projections, aggregates, constraints
-  or concurrency checks. `ChronicleKernelScenario` runs against a live kernel at
-  `ARC_CHRONICLE_TEST_URL` for those.
+- In-memory scenarios evaluate reducers and fixture-bounded projections through
+  the SDK's `ReadModelScenario`; unsupported shapes throw
+  `UnsupportedProjectionOperation`. Aggregates, constraints, concurrency,
+  listing/watching and history beyond that boundary need `ChronicleKernelScenario`
+  against `ARC_CHRONICLE_TEST_URL`.
 
 ## Set up a project
 
@@ -86,14 +88,15 @@ version ranges; npm does not, and the tarball then fails to install. A
     "rootDir": ".",
     "outDir": "dist"
   },
-  "include": ["main.ts", "Features/**/*.ts"]
+  "include": ["main.ts", "Features/**/*.ts"],
+  "exclude": ["Features/**/*.proxy.ts", "Features/**/*.tsx"]
 }
 ```
 
 - **No `experimentalDecorators`.** Arc's decorators compile as standard TC39
   decorators, as the samples do; `ESNext.Decorators` declares `Symbol.metadata`.
   Legacy `experimentalDecorators` also work. The Library sample compiles its
-  `@cratis/chronicle` 6.14 event types and projections under the same
+  `@cratis/chronicle` 6.35 event types and projections under the same
   standard-decorator settings. Generated frontend proxies are the exception:
   they compile with `experimentalDecorators: true`.
 - With `NodeNext`, relative imports carry a `.js` extension. `ESNext` +
@@ -127,14 +130,22 @@ await app.run({ port: Number(process.env.PORT ?? 3000) });
 | `ArcApplication.createBuilder(options?)` | Starts the application; the Node builder reads `appsettings.json` (`Cratis:Arc`) and `Cratis__...` environment variables |
 | `useGeneratedMetadata(metadata)` | Installs parameter and return-type metadata extracted from source. Call it **before** `discover()`/`add()` |
 | `services.addSingleton(Token)` | Registers a service; `addScoped`/`addTransient` take factories. Classes can also carry `@singleton()`, `@scoped()`, `@transient()` |
-| `discover(folderUrl)` | Imports every module under the folder and registers **exported**, decorated artifacts. Skips `dist`, `node_modules`, `given`, `for_*`, `index.*`, declaration files |
+| `discover(folderUrl)` | Imports every module under the folder and registers **exported**, decorated artifacts. Skips `dist`, `node_modules`, `given`, `for_*`, `index.*`, declaration files and `*.proxy.ts/.tsx` |
 | `add(...types)` | Registers artifacts explicitly — required on the Fetch entry, which cannot discover |
 | `build()` | Validates the whole graph (missing services, lifetime mismatches, misplaced decorators, stale metadata) and throws before any listener opens |
 | `app.run()` / `app.start()` | Standalone Node host. `app.dispose()` stops it and disposes services |
 
-`discover()` refuses a folder that contains the entry point; keep artifacts in a
-dedicated folder such as `Features/`. `Cratis:Arc:Development: true` is for a
-local machine only.
+`discover()` refuses a folder containing the entry point; use `Features/`.
+`Cratis:Arc:Development: true` is local-only.
+
+### Secure discovery defaults (0.56.0+)
+
+Outside **Development**, catalogs, identity discovery and `/openapi.json` require
+authentication; without it they are unmapped with a warning. Explicitly requiring
+authentication without configuring it fails startup. `development: true` is no bypass.
+Read [references/identity-and-introspection.md](references/identity-and-introspection.md)
+when configuring authentication, native principals, identity providers or
+introspection access for deployed tools. Source proxy generation needs no host.
 
 ## Lay out the slice
 
@@ -279,6 +290,11 @@ is enabled; do not throw for a rejection the user can act on. Rules that can
 run before `handle()` belong in validators: see
 `cratis-arc-validation-typescript`.
 
+Read [references/command-operations.md](references/command-operations.md) when
+returning inline work (`CommandOperation`, `operations(...)`), combining it with
+a response, or choosing several business outcomes. It covers commit-aware
+compensation; durable delivery needs its own workflow.
+
 ## Protect the command
 
 ```typescript
@@ -378,6 +394,10 @@ Read [references/command-specifications.md](references/command-specifications.md
 
 Folder and naming conventions for specs are `cratis-specifications-typescript`.
 
+Read [references/observability-and-host-scopes.md](references/observability-and-host-scopes.md)
+when instrumenting commands/queries or using `ArcServer.runInScope` for a trusted
+host integration; a service scope is not an authorization mechanism.
+
 ## Route near misses
 
 - A rejection rule on an existing command: `cratis-arc-validation-typescript`.

package/package/corpus/skills/cratis-arc-command-typescript/references/chronicle-events.md

@@ -11,12 +11,11 @@
 - Reactors that return commands
 - Specify it without a kernel
 
-Verified against `Cratis/Arc.TypeScript` `main` at commit `94d398d` (tag
-`v0.33.0` plus three commits): `Documentation/chronicle/**`,
+Verified against `Cratis/Arc.TypeScript` tag **v0.57.2** (GitHub pre-release): `Documentation/chronicle/**`,
 `Documentation/testing/chronicle.md`, `Source/Chronicle/index.ts`, and
 `Samples/Library`. `@cratis/arc.chronicle` is **experimental** and, like every
 package in the repository, not published to npm. `@cratis/chronicle` (the SDK)
-is published; the integration peers `^6.7.0`.
+is published; the integration peers `^6.29.0` and is built against 6.35.0.
 
 ## Register the integration
 
@@ -90,6 +89,11 @@ sample's `UniqueAuthorName` does).
 
 ## Rejections and the batch
 
+Appending and projecting are separate: immediate queries may be stale. Prefer
+observable reads. `completionTimeoutMs` waits for observers, but Chronicle waits
+for **every** observer on the log (Cratis/Chronicle#4132); an observer that does
+not handle the event can make every command time out with 500.
+
 - A constraint or concurrency rejection answers 400 with a validation result
   (`reason` `constraintViolation` or `concurrencyViolation`) and appends nothing.
 - Events returned by nested Arc commands that share tenant, correlation ID and
@@ -118,6 +122,24 @@ replay by default since SDK 6.9.0 — mark effects `@onceOnly()`, and keep retur
 commands safe to repeat after a failed-partition re-delivery. Reactor authoring
 itself is `cratis-chronicle-client-typescript`.
 
+`ARCCHR0006` in `@cratis/eslint-plugin-arc-core`'s `recommended-type-checked`
+preset flags a command-returning handler without `@onceOnly()` or a replay
+handler. Prefer explicit replay decisions, not lint suppression.
+
+Preview `withChronicle({ ..., activateArtifactsInScopes: true })` on an Arc-owned
+client resolves reactors/reducers through Arc DI, one scope per delivered batch,
+with the Chronicle namespace as tenant and no principal. Existing registrations
+win; otherwise discovered reactors/reducers are registered scoped. The SDK
+activator API arrived in 6.17.0; this integration requires its 6.29.0 peer minimum.
+For a caller-owned client, supply `chronicleArtifactActivator(...)` as
+`artifactActivator` and `reactorCommandResultHandler(...)` as
+`reactorResultHandler`, then opt in to `activateArtifactsInScopes`. Build Arc
+before observing and dispose Arc before that client. See the tagged
+`Documentation/chronicle/reactors/scoped-activation.md`.
+
+Read [command-operations.md](command-operations.md) when combining events with
+inline operations, or rehydrating a `commandAggregate` for a state-based decision.
+
 ## Specify it without a kernel
 
 `ChronicleCommandScenario` from `@cratis/arc.chronicle/testing` runs the real
@@ -138,7 +160,16 @@ await scenario.dispose();
 - Pass the command, its event types, validators and read-model types to
   `for(...)`; the in-memory log refuses an unregistered event type.
 - `givenReadModel(Type, id, instance, tenant?)` pins state;
-  `scenario.given.forEventSource(id).events(...)` seeds reducer history (SDK
-  6.14.0 or later).
+  `scenario.given.forEventSource(id, tenant?).events(...)` seeds reducer history
+  (SDK >=6.14.0) and projections (>=6.19.0) through SDK `ReadModelScenario`.
+  `.readModel(instance)` pins state on the same given builder.
 - `shouldHaveAppendedEvent` does not check count or order — assert
   `appendedEvents` when either matters.
+- `ChronicleQueryScenario.for(Model, 'method', ...artifacts)` runs snapshot
+  queries with the same tenant-scoped given events/read models.
+- Fixture-bounded projections/reducers work in-process. Unsupported definitions
+  throw `UnsupportedProjectionOperation`; give declarative projections an
+  explicit model (`@projection('', ReadModel)`) so lookups of other seeded models
+  can associate them. No aggregate rehydration, constraint/concurrency enforcement,
+  listing/watching, or projection history beyond that boundary: use
+  `ChronicleKernelScenario` at `ARC_CHRONICLE_TEST_URL`.