@cratis/pi 7.34.1 → 7.36.0

package/package/corpus/rules/go.md

@@ -0,0 +1,115 @@
+---
+applyTo: "**/*.go,go.mod,go.sum,**/go.mod,**/go.sum"
+paths:
+  - "**/*.go"
+  - "go.mod"
+  - "go.sum"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Go conventions
+
+Use Go's own packages, constructors, explicit registration and standard `testing`.
+Do not import C# namespace layouts, one-type-per-file rules, `I` interface prefixes,
+`Async` suffixes or .NET specification mechanics. Product APIs belong in the
+matching Go skill; repository-owned context supplies module paths, layout and
+exact commands.
+
+## Minimum version and dependencies
+
+- Read the `go` directive, build constraints and CI before choosing a feature.
+  The minimum is not the newest locally installed compiler; a `toolchain`
+  preference does not replace minimum-version testing. Do not raise it incidentally.
+- Iterators require Go 1.23; `T.Context` and `B.Loop` require 1.24;
+  stable `testing/synctest` and `WaitGroup.Go` require 1.25.
+- Prefer the standard library when it meets the contract. Review dependency
+  capability, license and compatibility before adding one.
+- Change module files only for authorized dependency work. Review tidy changes,
+  including indirect minimum-version changes; keep sums consistent. A consumer
+  must not need a developer's workspace or local replacement.
+- Never edit generated code; change its authoritative inputs and pinned generator.
+
+## Names, public APIs and values
+
+- Format handwritten Go with `gofmt`; use its tabs and the repository's import grouping.
+- Use MixedCaps and preserve `ID`, `HTTP`, `URL`, `JSON` and `RPC` initialisms.
+  Avoid package stuttering and catch-all packages. Use American English.
+- Keep public surfaces small and caller-oriented. Define interfaces at consuming
+  boundaries or where public substitution is a supported contract, not for every type.
+- Document exported declarations with comments beginning with their names.
+  Explain nil/zero semantics, concurrency, ownership, cancellation, error identities
+  and cleanup. Add executable examples for important public workflows.
+- Make zero values useful where possible; reject invalid construction early.
+  Document option defaults, validation, ordering and duplicates.
+- Use named domain values instead of interchangeable primitives. Defined types
+  do not inherit codec methods; explicitly forward text/JSON codecs and test wire
+  formats. See `cratis-fundamentals-concept-go` when using Fundamentals.Go.
+- Document whether slices, maps, config and results are owned, copied or borrowed.
+  Copying a slice/map header is not a detached copy. Do not copy a used mutex,
+  wait group or atomic value, or expose pooled bytes after returning their buffer.
+
+## Errors, context and diagnostics
+
+- Return ordinary failures as the final `error`; inspect errors, including cleanup.
+  Libraries must not exit the process or panic for expected failures.
+- Preserve documented error identity with `errors.Is`/`errors.As`, not strings.
+  Wrapping with `%w` exposes that identity as API; do it deliberately. Do not
+  return an `error` interface containing a typed nil.
+- Add useful operation context. Handle/log an error at one boundary rather than
+  repeatedly logging and returning it. A partial or ambiguous write is not success
+  and must not trigger a blind retry.
+- Put `context.Context` first for blocking/cancelable work and propagate it through
+  RPCs, HTTP, storage and callbacks. Never escape caller cancellation by replacing
+  it with `Background`. Do not retain request contexts in long-lived clients.
+- Call acquired cancel functions. Context values carry request metadata, not
+  dependencies or configuration; use private keys with typed accessors.
+- Prefer injectable `log/slog` at a supported minimum. Do not mutate global logging
+  from a library. Redact credentials and sensitive payloads.
+
+## Goroutines, streams and iterators
+
+- Each goroutine needs an owner, termination condition and observable join path.
+  Cancellation requests termination; it does not join workers.
+- Bound workers, queues, subscriptions, buffers and retries; define backpressure.
+  Make blocking operations cancellation-aware. Close channels only after senders stop.
+- Do not hold locks while calling user code or performing slow I/O. Call
+  `WaitGroup.Add` before launching work when not using version-supported `Go`.
+- Stop immediately when iterator `yield` returns false. Release resources on
+  exhaustion, early exit, failure and cancellation; call `iter.Pull`'s stop function.
+  Specify ordering, errors and whether a stream can be consumed more than once.
+- Preserve protocol metadata, tenancy, checkpoints and duplicate-delivery semantics.
+  No generic retry or stream helper may promise exactly-once effects.
+- Validate remote TLS identities. Development exceptions must be explicit.
+  Use cryptographic randomness for secrets, never `math/rand`.
+
+## Specifications and checks
+
+- Use standard `testing`, meaningful subtests, useful got/want diagnostics and
+  table-driven cases where setup/assertions actually match. Use external `_test`
+  packages to exercise public contracts where practical.
+- Use `t.Helper`, `t.Cleanup` and `t.TempDir`. Isolate state before `t.Parallel`.
+  Synchronize with channels/joins, not guessed sleeps. Fake-time tests do not
+  establish real-network behavior.
+- Cover error identity, nil/zero input, cancellation/deadlines, partial outcomes,
+  early stream exit and resource ownership. Bound fuzz duration and preserve
+  failing seeds. Use race checks where supported; race-free does not mean leak-free.
+- Run the repository's build, tests, formatting, vet and pinned golangci-lint gates,
+  with race and vulnerability scanning as separate checks. Respect the declared
+  minimum without silent toolchain upgrades. Report absent tools honestly.
+
+## Adaptation and attribution
+
+This condensed rule adapts the repository-owned Go baseline at
+[Chronicle.Go v0.9.1](https://github.com/Cratis/Chronicle.Go/blob/v0.9.1/.cratis/ai/rules/go.md)
+and [Arc.Go v0.1.1](https://github.com/Cratis/Arc.Go/blob/v0.1.1/.cratis/ai/rules/go.md),
+not their project paths or commands. The baseline's adapted readability,
+error-boundary, public-option and goroutine recommendations retain attribution:
+[Google Go style](https://google.github.io/styleguide/go/guide.html), Google,
+[CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/); and
+[Uber Go style](https://github.com/uber-go/guide/blob/master/style.md), Uber
+Technologies, Inc., [Apache-2.0](https://github.com/uber-go/guide/blob/master/LICENSE).
+No community code snippets are reproduced here.

package/package/corpus/rules/java.md

@@ -41,7 +41,9 @@ modeling, dialog, license, judgment, gray). See [general.md](./general.md).
 
 - PascalCase for class and interface names.
 - camelCase for methods, fields, and local variables.
-- No `I` prefix on interfaces — name the interface for what it does.
+- New application and Arc-style interfaces have no `I` prefix — name them
+  for what they do. Chronicle.Kotlin's published interfaces retain their names
+  (`IEventStore`, `IChronicleClient`, `IProjectionFor`, `IReactorMiddleware`).
 - Never suffix a class with `Impl`, `Manager`, or `Helper` purely to
   disambiguate — name it for its role; reserve `Default<Name>` for the
   concrete counterpart of an interface meant to be overridden.
@@ -127,7 +129,8 @@ modeling, dialog, license, judgment, gray). See [general.md](./general.md).
 
 ## Testing
 
-- JUnit 5 is the house test runner.
+- JUnit Jupiter is the house test runner (the Cratis JVM repositories use
+  Jupiter 6.1.x).
 - A test for a Java-facing surface belongs beside the Java production code
   (`src/test/java/.../<Thing>Test.java`) and must actually compile and run
   against that surface — a Kotlin-only test does not prove Java call-site

package/package/corpus/rules/kotlin.md

@@ -43,10 +43,11 @@ dialog, license, judgment, gray). See [general.md](./general.md).
 
 - PascalCase for class, interface, and object names.
 - camelCase for functions, properties, and local variables.
-- No `I` prefix on interfaces — Kotlin does not carry that convention; name
-  the interface for what it does (`CommandPipeline`, not `ICommandPipeline`)
-  unless a concrete/interface pair genuinely needs `Default<Name>` for the
-  implementation.
+- New application and Arc-style interfaces have no `I` prefix; name them for
+  what they do (`CommandPipeline`, not `ICommandPipeline`). Reserve
+  `Default<Name>` for a concrete/interface pair when needed. Chronicle.Kotlin's
+  published types retain their names (`IEventStore`, `IChronicleClient`,
+  `IProjectionFor`, `IReactorMiddleware`); do not rename framework APIs.
 - Never suffix a class with `Impl`, `Service`, or `Async` purely to
   disambiguate — name it for its role.
 
@@ -165,7 +166,8 @@ should assume by default:
 
 ## Testing
 
-- JUnit 5 is the house test runner for Kotlin and Java alike.
+- JUnit Jupiter is the house test runner for Kotlin and Java alike (the
+  Cratis JVM repositories use Jupiter 6.1.x).
 - A Kotlin test lives beside its Kotlin production code
   (`src/test/kotlin/.../<Thing>Test.kt`); a Java-facing surface also gets a
   Java test that compiles and runs against it, because Kotlin-only tests do

package/package/corpus/rules/orleans.md

@@ -10,27 +10,83 @@ paths:
 > **⚠️ APPLIES ONLY TO PROJECTS USING MICROSOFT ORLEANS**
 > If your project does not reference `Microsoft.Orleans` or any Orleans packages, **ignore this entire file**. These rules are irrelevant outside of Orleans contexts.
 
-In the Cratis organization, Orleans is the Chronicle kernel's actor runtime (`Source/Kernel/`). These conventions describe how that kernel is shaped, verified against `Cratis/Chronicle` **v18.3.0**; follow them in any Cratis repository that hosts Orleans grains.
+In the Cratis organization, Orleans is the Chronicle kernel's actor runtime (`Source/Kernel/`). The kernel conventions below are verified against `Cratis/Chronicle` **v19.50.0**. Shared hosting and jobs come from `Cratis/Orleans` **v1.16.3**; use its setup for other services that co-host a silo.
 
 ## General
 
 - Do **not** split grain interfaces into a separate project. Grain interfaces and their implementations live together in `Kernel/Core`; the `Contracts` project holds the gRPC contracts, not grain interfaces.
 - Clustering is chosen by the host, not the grain code: the server uses `UseLocalhostClustering(siloPort, gatewayPort, serviceId, clusterId)` for local development and the MongoDB storage integration switches on `UseMongoDBClustering` (`MongoDBMembershipStrategy.Multiple`) when clustering is enabled. A silo pointed at non-local shared storage while still on localhost clustering is logged as a **warning** at startup (each such node forms its own single-node cluster over the same data); `Cratis__Chronicle__Clustering__Type=MongoDB` on every node is what joins them.
-- Do **not** add `[Alias]` to grain interfaces or grain methods — rely on the default alias Orleans generates. `[Alias(nameof(Type))]` is used only on `[GenerateSerializer]` **state and definition records** in `Kernel/Concepts` (`ReadModelDefinition`, `IndexDefinition`, `ReadModelChangeContext`, `ProjectionFuture`), where a stable serialization alias must survive a rename.
+- Do **not** add `[Alias]` to grain interfaces or grain methods — rely on the default alias Orleans generates. `[Alias(nameof(Type))]` is used only on `[GenerateSerializer]` **state and definition records** in `Kernel/Concepts` (`ReadModelDefinition`, `IndexDefinition`, `ReadModelChangeContext`, `ProjectionFuture`, `ClearPartitionQuarantineResult`), where a stable serialization alias must survive a rename.
 
 ## Grain storage providers
 
-- Storage provider names are constants in `WellKnownGrainStorageProviders` (`Kernel/Core`), **one name per concern** — 25 of them at v18.3.0 (`Namespaces`, `EventSequences`, `ObserverDefinitions`, `ObserverState`, `FailedPartitions`, `Jobs`, `JobSteps`, `Recommendations`, `Projections`, `ProjectionsManager`, `ProjectionFutures`, `Reactors`, `Reducers`, `ReducersManager`, `ReadModels`, `ReadModelsManager`, `ReadModelReplayManager`, `Constraints`, `EventStoreSubscriptionsManager`, `EventSeeding`, `Webhooks`, `WebhooksManager`, `DataProtectionKeys`, `PatchManager`, `System`). Reference a provider only through its constant — never a magic string, and there is no "default" provider.
-- Each concern has its own `IGrainStorage` implementation (`JobGrainStorageProvider`, `EventSequencesStorageProvider`, `NamespacesStateStorageProvider`, …) taking the kernel's `IStorage` abstraction — **not** a MongoDB collection. The storage backend (MongoDB, SQL, in-memory) is selected behind `IStorage`, so a grain storage provider never references a database driver.
+- Storage provider names are constants in `WellKnownGrainStorageProviders` (`Kernel/Core`), **one name per concern** — 23 of them at v19.50.0 (`Namespaces`, `EventSequences`, `ObserverDefinitions`, `ObserverState`, `FailedPartitions`, `Recommendations`, `Projections`, `ProjectionsManager`, `ProjectionFutures`, `Reactors`, `Reducers`, `ReducersManager`, `ReadModels`, `ReadModelsManager`, `ReadModelReplayManager`, `Constraints`, `EventStoreSubscriptionsManager`, `EventSeeding`, `Webhooks`, `WebhooksManager`, `DataProtectionKeys`, `PatchManager`, `System`). Reference a provider only through its constant — never a magic string, and there is no "default" provider.
+- Each concern has its own `IGrainStorage` implementation (`EventSequencesStorageProvider`, `NamespacesStateStorageProvider`, …) taking the kernel's `IStorage` abstraction — **not** a MongoDB collection. The storage backend (MongoDB, SQL, in-memory) is selected behind `IStorage`, so a grain storage provider never references a database driver.
 - Every provider is registered once, in `StorageProviderExtensions.AddStorageProviders(this ISiloBuilder)`, as a keyed singleton wrapped in `ResilientGrainStorage` (a Polly resilience pipeline configured from `Chronicle:ResilientStorage`). A new concern adds a constant, an `IGrainStorage` over `IStorage`, and one `AddKeyedSingleton(WellKnownGrainStorageProviders.<Name>, CreateResilientStorageFor<…>)` line there — nothing else.
 - Grains declare their state with `[PersistentState(nameof(<StateType>), WellKnownGrainStorageProviders.<Name>)]`.
 
+Registration excerpt inside Chronicle's `StorageProviderExtensions`; the provider
+is `Cratis.Chronicle.EventSequences.EventSequencesStorageProvider(IStorage)`:
+
 ```csharp
-public class JobGrainStorageProvider(IStorage storage) : IGrainStorage
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+services.AddKeyedSingleton(WellKnownGrainStorageProviders.EventSequences, CreateResilientStorageFor<Cratis.Chronicle.EventSequences.EventSequencesStorageProvider>);
+```
+
+Jobs are the exception to the kernel's `IStorage` shape: `JobGrainStorageProvider`
+and `JobStepGrainStorageProvider` live in `Cratis.Orleans.Jobs` and take
+`Cratis.Orleans.Storage.IJobsStorage`. Chronicle registers them under
+`Cratis.Orleans.WellKnownGrainStorageProviders.Jobs` and `.JobSteps`, still wrapped
+in its resilient storage pipeline.
+
+## Co-host a silo with Cratis.Orleans
+
+For service authors, `Cratis.Orleans` supplies hosting, grain serializers, and the
+shared job system without requiring Chronicle. With `Cratis.Orleans` and
+`Cratis.Orleans.Storage.MongoDB` 1.16.3, this host uses durable MongoDB membership
+and jobs storage (a local MongoDB server is required):
+
+```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.Orleans.Hosting;
+using Cratis.Orleans.Setup;
+using Microsoft.AspNetCore.Builder;
+using MongoDB.Driver;
+
+var builder = WebApplication.CreateBuilder(args);
+const string connectionString = "mongodb://localhost:27017";
+builder.AddCratisOrleans(new CratisOrleansOptions
 {
-    // ReadStateAsync / WriteStateAsync / ClearStateAsync over
-    // storage.GetEventStore(key.EventStore).GetNamespace(key.Namespace).Jobs
-}
+    ClusterId = "my-service",
+    ServiceId = "my-service",
+    Clustering = ClusteringMode.MongoDB,
+    DatabaseName = "my-service-orleans",
+    ConnectionString = connectionString
+});
+builder.Services.AddCratisOrleansMongoDBJobsStorage(new MongoClient(connectionString));
 
-services.AddKeyedSingleton(WellKnownGrainStorageProviders.Jobs, CreateResilientStorageFor<JobGrainStorageProvider>);
+var app = builder.Build();
+app.Run();
 ```
+
+- Register jobs storage separately: `AddCratisOrleansMongoDBJobsStorage`,
+  `AddCratisOrleansSqlJobsStorage` (`Cratis.Orleans.Setup`), or
+  `AddCratisOrleansInMemoryJobsStorage` (`Cratis.Orleans.Storage`).
+- Give grain implementations a unique `[GrainType("unique-name")]`. Orleans'
+  default type name derives from the class name alone; a collision across
+  assemblies prevents silo startup.
+- Reminders deliberately use Orleans' in-memory service in both clustering
+  modes; they do not survive a full restart. Jobs rehydrate from durable jobs
+  storage and do not use reminders. Do not switch to the incompatible MongoDB
+  reminder table merely because clustering uses MongoDB.
+- `AddCratisOrleans` enables activity propagation itself. If a host keeps an
+  explicit `AddActivityPropagation()` call, it must be **before**, never after,
+  `AddCratisOrleans`, to avoid duplicate Orleans propagation filters/spans.
+- Keep Orleans package versions aligned: the Release-build guard rejects a
+  `Microsoft.Orleans.Reminders`/`Microsoft.Orleans.Server` version mismatch.
+- `Enabled = false` makes `AddCratisOrleans` a no-op for specification hosts;
+  it does not register the silo or its collaborators.

package/package/corpus/rules/profiles.md

@@ -72,9 +72,12 @@ profile includes neither Screenplay nor Stage.
 | Profile ID | Description | Automatically Includes |
 |---|---|---|
 | `cratis/arc` | Arc CQRS framework | `cratis/arc/csharp`, `cratis/arc/java`, `cratis/arc/kotlin` |
-| `cratis/chronicle` | Chronicle event sourcing engine | `cratis/chronicle/compliance`, `cratis/chronicle/csharp`, `cratis/chronicle/elixir`, `cratis/chronicle/java`, `cratis/chronicle/kotlin`, `cratis/chronicle/multi-tenancy`, `cratis/chronicle/typescript`, `cratis/chronicle/web-workbench` |
+| `cratis/chronicle` | Chronicle event sourcing engine (does not compose `cratis/chronicle/mcp`) | `cratis/chronicle/compliance`, `cratis/chronicle/csharp`, `cratis/chronicle/elixir`, `cratis/chronicle/java`, `cratis/chronicle/kotlin`, `cratis/chronicle/multi-tenancy`, `cratis/chronicle/typescript`, `cratis/chronicle/web-workbench` |
 | `cratis/components` | React component library | (no child profiles) |
 | `cratis/fundamentals` | Core primitives (`ConceptAs<T>`, `EventSourceId<T>`) | (no child profiles) |
+| `cratis/arc/go` | Experimental Arc.Go HTTP CQRS (root module) | `cratis/language/go`, `cratis/fundamentals/go` |
+| `cratis/chronicle/client-go` | Experimental standalone Chronicle.Go client | `cratis/language/go`, `cratis/fundamentals/go` |
+| `cratis/fundamentals/go` | Fundamentals.Go named scalar concepts and codecs | `cratis/language/go` |
 | `cratis/specifications` | Specification framework | (no child profiles) |
 | `cratis/specifications/dotnet` | C# specifications and application slice conformance (`cratis-application-slice-conformance`), alongside slice specifications | `cratis/specifications` |
 
@@ -82,8 +85,9 @@ profile includes neither Screenplay nor Stage.
 
 | Profile ID | Description | Automatically Includes |
 |---|---|---|
-| `cratis/engineering` | Engineering conventions and workflows | `cratis/engineering/core`, `cratis/engineering/csharp`, `cratis/engineering/elixir`, `cratis/engineering/kotlin`, `cratis/engineering/react`, `cratis/engineering/typescript` |
+| `cratis/engineering` | Engineering conventions and workflows | `cratis/engineering/core`, `cratis/engineering/csharp`, `cratis/engineering/elixir`, `cratis/engineering/go`, `cratis/engineering/kotlin`, `cratis/engineering/react`, `cratis/engineering/typescript` |
 | `cratis/engineering/csharp` | C# engineering conventions | `cratis/engineering/core` |
+| `cratis/engineering/go` | Go framework parity and immutable module releases | `cratis/engineering/core`, `cratis/language/go` |
 | `cratis/engineering/typescript` | TypeScript engineering conventions | `cratis/engineering/core` |
 | `cratis/engineering/react` | React engineering conventions | `cratis/engineering/core` |
 
@@ -94,13 +98,15 @@ profile includes neither Screenplay nor Stage.
 | `cratis/language/csharp` | C# language conventions |
 | `cratis/language/typescript` | TypeScript language conventions |
 | `cratis/language/elixir` | Elixir language conventions |
+| `cratis/language/go` | Go conventions for source, go.mod and go.sum |
 | `cratis/language/kotlin` | Kotlin language conventions |
 | `cratis/language/java` | Java language conventions |
 
 ### Arc and Chronicle on the JVM (Kotlin and Java)
 
 Arc.Kotlin (`io.cratis:arc`) and its optional Chronicle integration
-(`io.cratis:arc-chronicle-spring-boot-starter`) bring the same command/query
+(`io.cratis:cratis`, the all-in-one event-sourced application artifact, or
+`io.cratis:arc-chronicle-spring-boot-starter`) bring the same command/query
 model-bound shape to the JVM that Arc .NET brings to C#, for both Kotlin and
 Java application code. `cratis/arc/client-kotlin` carries the skills for both
 languages — Java application code still needs Kotlin and KSP on the build,
@@ -111,6 +117,9 @@ since Arc generates Kotlin adapters for Java declarations.
 | `cratis-arc-command-kotlin` | `@Command`, `handle()`/`provide()`, Chronicle event responses, command authorization, TypeScript proxy generation |
 | `cratis-arc-query-kotlin` | `@ReadModel` queries, GET vs RFC QUERY, observable queries (`Flow`, `Flow.Publisher`, RxJava 3) over SSE/WebSocket |
 | `cratis-arc-validation-kotlin` | `FluentModelValidator` shared rules, `CommandValidator`/`QueryValidator`/`ConceptValidator`/`ModelValidator`, Jakarta constraints |
+| `cratis-arc-testing-kotlin` | Real in-process command/query scenarios, bounded observable collection, read-model pins and Chronicle append assertions |
+| `cratis-arc-identity-and-tenancy-kotlin` | Authentication handlers, identity details, tenant resolution and propagation, opt-in trusted platform headers |
+| `cratis-arc-spring-data-kotlin` | JPA/Mongo repositories, paging, observations, concept converters, tenant storage and transaction boundaries |
 
 Standalone Chronicle client usage (no Arc) for Kotlin and Java is
 `cratis-chronicle-client-kotlin`, reused by `cratis/chronicle/client-java`.
@@ -119,8 +128,10 @@ JVM language conventions are `kotlin.md` and `java.md`.
 ### Arc for TypeScript on Node.js
 
 Arc for TypeScript (`@cratis/arc.core` with the Express, Fastify, Hono,
-MongoDB, Drizzle, testing and experimental Chronicle packages) brings the same
-model-bound command/query shape to a Node.js server. Its packages are a source
+MongoDB, Drizzle, testing and experimental Chronicle packages, plus
+`@cratis/arc.proxygenerator`, `@cratis/eslint-plugin-arc-core` and experimental
+`@cratis/cratis`) brings the same model-bound command/query shape to a Node.js
+server. Verified at GitHub pre-release **v0.57.2**: its packages are a source
 preview and are not published to npm. It is separate from `@cratis/arc`, the
 published client runtime that generated proxies import in a frontend.
 `cratis/arc/server-typescript` carries the skills; `cratis/arc/typescript` adds
@@ -139,6 +150,30 @@ Node.js server and a C# or React-frontend project has no use for them. Select
 Standalone Chronicle client usage (no Arc) in TypeScript is
 `cratis-chronicle-client-typescript`.
 
+### Experimental Go modules
+
+Select `cratis/language/go` for a Go repository without importing any HTTP or
+Chronicle guidance. `cratis/engineering/go` adds contributor parity and release
+policy through [go-engineering.md](./go-engineering.md), composing rather than
+duplicating [go.md](./go.md). Set `languages: ["go"]` in `.cratis/ai.json` so
+language-filtered composition selects the Go children. The catalog/manifest
+register `go`; there is no separate extension-based detection registry in the
+corpus's harness setup or Pi package.
+
+| Profile | Skill | Verified experimental version |
+| --- | --- | --- |
+| `cratis/chronicle/client-go` | `cratis-chronicle-client-go` | Chronicle.Go v0.9.1 (Chronicle kernel 19.32.3 profile) |
+| `cratis/arc/go` | `cratis-arc-go` | Arc.Go v0.1.1 |
+| `cratis/fundamentals/go` | `cratis-fundamentals-concept-go` | Fundamentals.Go v0.3.2 |
+
+Arc and Chronicle profiles compose language and Go concepts, **not each other**
+or C# client/HTTP skills. These profiles are explicit opt-ins; existing aggregate
+Arc/Chronicle and application profiles are unchanged. Only the Arc.Go root module
+is released; Chronicle/MongoDB integrations and Go generator tools remain source
+previews. `cratis/application/go` and Go scaffolding are deferred; do not prescribe
+`dotnet new` as a Go template. Each module currently requires Go 1.26, but generic
+language policy always follows the consuming repository's `go.mod` minimum.
+
 ### Specialized Profiles
 
 | Profile ID | Description |
@@ -149,6 +184,8 @@ Standalone Chronicle client usage (no Arc) in TypeScript is
 | `cratis/codescene` | Opt-in CodeScene Code Health change gates, refactoring, debt prioritization and risk-based testing; requires an account and available MCP tools; each user registers the MCP server (see below) |
 | `cratis/studio` | Studio MCP safety guidance |
 | `cratis/cli` | CLI operations |
+| `cratis/cli/terminal-workbench` | Human-operated terminal Workbench |
+| `cratis/chronicle/mcp` | Chronicle MCP inspection and exact tool-effect guidance |
 | `cratis/lens` | Lens browser extension |
 | `cratis/screenplay` | Model-first event modeling: lifecycle, phase skills, toolchain, review, render and gap-fill, plus the whole `.play` language |
 | `cratis/stage` | Stage rendering and sandbox |
@@ -355,7 +392,7 @@ profile: application
 - **Full catalog:** [profile-catalog.json](../profile-catalog.json)
 - **Application rules:** [general.md](./general.md) (Application profile section)
 - **Framework rules:** [framework.md](./framework.md)
-- **Engineering conventions:** [csharp.md](./csharp.md), [typescript.md](./typescript.md)
+- **Engineering conventions:** [csharp.md](./csharp.md), [typescript.md](./typescript.md), [go.md](./go.md), [go-engineering.md](./go-engineering.md)
 
 ## See Also
 

package/package/corpus/rules/pull-requests.md

@@ -6,7 +6,7 @@ applyTo: "**/*"
 
 ## The description is the release note
 
-**The PR description is published verbatim as the GitHub release. In repositories released by `cratis/release-action`, it also closes every issue written as `(#n)`; elsewhere, follow the repository's own release and issue-closing process.** Write the note the person upgrading should read, not a development write-up. The same contract applies to release notes typed into a manual workflow run or written straight into a release. Where it is installed, the `verify-release-notes` check enforces it on release-bound PRs into the default branch carrying `major`/`minor`/`patch` (it re-runs when the label is added); it warns on `no-release` and unlabelled PRs, which must still be written this way because any of them may become releasable. `release-action` does not run for a `no-release` PR, so `(#n)` closes nothing there. Editing the description re-runs the check. HTML comments are not shown on the release page and the check ignores them for headings, keywords and placeholders, but a `(#n)` inside a comment still closes the issue (`release-action` skips only fenced and inline code) and the check fails it, so never put an issue reference in a comment. The template's own comment can stay: its `(#123)` examples are inline code.
+**The PR description is published verbatim as the GitHub release. In repositories released by `cratis/release-action`, it also closes every issue written as `(#n)`; elsewhere, follow the repository's own release and issue-closing process.** Write the note the person upgrading should read, not a development write-up. The same contract applies to release notes typed into a manual workflow run or written straight into a release. Where it is installed, the `verify-release-notes` check enforces it on release-bound PRs into the default branch carrying `major`/`minor`/`patch` (it re-runs when the label is added); it warns on `no-release` and unlabelled PRs, which must still be written this way because any of them may become releasable. `release-action` does not run for a `no-release` PR, so `(#n)` closes nothing there. Editing the description re-runs the check. HTML comments are not shown on the release page and the check ignores them for headings, keywords and placeholders, and `release-action` removes them before publishing, so a `(#n)` only inside a comment closes nothing; the check fails it, so never put an issue reference in a comment. The template's own comment can stay: its `(#123)` examples are inline code, and the comment is not published.
 
 ### Allowed shape
 
@@ -102,7 +102,7 @@ Quick reminders:
 
 Confirm the current repository workflow contract before selecting release intent because release-intent labels can trigger publication. A direct request to ship with a named label authorizes applying that label and completing the repository's standard pull-request workflow, including the release it normally triggers. Do not ask for separate authorization at each step. If the user did not request shipping or publication, a proposed semantic label describes impact but does not grant authority.
 
-- Exactly one of `major`/`minor`/`patch`/`no-release`, set in the creating command (`gh pr create --label patch`), in every repository, including samples, docs and tooling repositories (`no-release` when nothing is shipped). To change intent, swap labels in one command: `gh pr edit <n> --remove-label minor --add-label patch`. Never add a second.
+- Exactly one of `major`/`minor`/`patch`/`no-release`, set in the creating command (`gh pr create --label patch`), in every repository, including samples, docs and tooling repositories (`no-release` when nothing is shipped). To change intent, swap labels in one command: `gh pr edit <n> --remove-label minor --add-label patch`. Never add a second: with more than one of them, release-action releases nothing and reports `reason=error`. Re-running a `pull_request` workflow replays the original label payload, so fix a label mistake by editing the PR or pushing; a `workflow_dispatch` run needs an explicit `version` and the PR description as `release-notes`, and without notes it closes no issues.
 - Dependabot PRs carry only `no-release`. release-action never releases them, and the `major`/`minor`/`patch` Dependabot adds describe the dependency's version, not this product's.
 - Label the PR according to semantic versioning impact:
   - **major** — breaking changes to public APIs
@@ -172,4 +172,4 @@ Before marking code/automation work ready, select the affected-project gates tha
 - `yarn lint` — zero errors
 - `npx tsc -b` — zero TypeScript errors
 - Code follows all project coding standards and conventions
-- **Required CI checks pass.** After an authorized push, inspect checks and failure logs. Diagnose within a bounded attempt, fix in-scope causes, and re-run relevant gates after each fix. Report unrelated/environmental failures and missing authority as blockers rather than retrying indefinitely or silently waiving required checks.
+- **Required CI checks pass.** After an authorized push, inspect checks and failure logs. Diagnose within a bounded attempt, fix in-scope causes, and re-run relevant gates after each fix. Report unrelated/environmental failures and missing authority as blockers rather than retrying indefinitely or silently waiving required checks. If a release job fails after a concurrent merge (the release for the tag exists for another commit), re-run it: it releases under the next version (release-action v1.4.2 fails the job rather than reporting success).

package/package/corpus/rules/react.md

@@ -149,7 +149,7 @@ Out-of-dialog execution branches in this order:
 const result = await command.execute();
 if (!result.isAuthorized) { redirectToLogin(); return; }
 if (!result.isValid)      { /* validationResults → inline field errors */ return; }
-if (result.hasExceptions) { toast.error('Something went wrong'); console.error(result.exceptionMessages); return; }
+if (result.hasExceptions) { toast.error({ title: 'Something went wrong' }); console.error(result.exceptionMessages); return; }
 // happy path — refresh queries, close, etc.
 ```
 
@@ -163,12 +163,19 @@ if (result.hasExceptions) { toast.error('Something went wrong'); console.error(r
 - **`asCommandFormField<P>(Component, opts)`** — wrap a custom input (rich text, address picker) so it participates in `CommandForm` with validation/error wiring.
 - **`CommandScope`** + `useCommandScope()` (`@cratis/arc.react/commands`) — aggregate state across multiple commands (and queries) on one screen; commands and queries rendered inside the scope register themselves (the `ICommandScope` API also exposes `addCommand`/`addQuery`/`addChildScope` for manual registration); scopes nest (a child reports up to its parent); injectable as `ICommandScope` (nearest enclosing scope). Props: `setHasChanges`, `setIsPerforming`, `onBeforeExecute`, `onSuccess(cmd, result)`, `onFailed`, `onException`, `onUnauthorized`. `ICommandScope` members: `hasChanges`, `isPerforming`, `hasValidationFailures`, `hasExceptions`, `validationFailures`/`exceptions` (this scope), `aggregatedValidationFailures`/`aggregatedExceptions` (scope + children), `execute()` (runs only commands with changes), `revertChanges()`, `parent`.
 
+At Arc v22.75.0 `CommandForm` defaults to safe exception text rather than raw
+server messages; customize with `exceptionMessage` or `exceptionDisplayComponent`
+(`ExceptionDisplayProps`). `showErrors={false}` hides built-in display. Dynamic
+accessors need explicit `fieldName`; custom field validation failures block submit.
+
 ### `<Arc>` global configuration
 
 Top-level provider for microservice name and API base path. Config props (with defaults):
 
 | Prop | Default | Notes |
 |---|---|---|
+| `apiBasePath` | — | Backend API prefix; `<Arc basePath>` is deprecated, not router configuration |
+| `detailsType` | — | Constructor for typed identity details |
 | `httpHeadersCallback` | — | returns `HeadersInit` merged into every request (bearer/tenant headers) |
 | `queryTransportMethod` | `ServerSentEvents` | SSE is capped at 4 connections on HTTP/1.1 |
 | `observableQueryTransferMode` | `Delta` | `Delta` = server ChangeSet/client diff; `Full` = all items as `added` |

package/package/corpus/rules/reactors.md

@@ -56,7 +56,9 @@ public class OrderNotifications(INotificationService notifications) : IReactor
 - With a `[Replay]` handler, **only** it runs during replay — the regular handler does not also run.
 - Without one, the regular handler runs during replay exactly as before, so this changes nothing for existing reactors.
 - An event type handled *only* by a `[Replay]` handler is still subscribed to.
-- Reach for **`[OnceOnly]`** instead when the side effect should simply not happen again; use `[Replay]` when replay needs to do something *different* rather than nothing.
+- Reach for **`[OnceOnly]`** when the side effect must not repeat **during replay**;
+  use `[Replay]` when replay needs different work. Neither suppresses ordinary
+  catch-up or recovery redelivery, nor limits runs per event source.
 
 ## Taking Dependencies
 
@@ -188,16 +190,38 @@ Cross-service events route through Chronicle's outbox/inbox rather than a shared
 - Chronicle creates/reuses the outbox→inbox subscription from the observer's `[EventStore]` metadata, or from `[EventStore]` on the event type/assembly. Put `[assembly: EventStore("<source-store>")]` in the contracts project when every event there originates from one service; use observer-level `[EventStore("<source-store>")]` to override.
 - An observer-level `[EventStore]` **cannot** be combined with `[EventSequence]`, `[EventLog]`, or `Reactor(eventSequence: ...)`.
 
+## Storage lookup failures are not absence
+
+At **Chronicle v19.50.1**, a failed next-event lookup leaves the observer's
+position unchanged. Routing defers delivery and the watchdog retries; only
+`NotFound` proves absence and permits fast-forward. The watchdog likewise does
+not advance on storage error. This fixes #4770, not every legacy delivery or
+completion limitation. Quarantined observers do not resume from this retry.
+Sources: `Source/Kernel/Core/Observation/States/Routing.cs` and
+`Observation/Observer.Watchdog.cs` at v19.50.1.
+
 ## Confirming downstream completion — `WaitForCompletion`
 
-The default is fire-and-forget. When a caller's correctness depends on all observers (projections, reducers, reactors) having processed an appended event before returning — integration tests, synchronous webhook surfaces — call `WaitForCompletion` (from `Cratis.Chronicle.Observation`) on the `AppendResult`/`AppendManyResult`. It returns an `AppendResultWaitForCompletionResult` carrying `IsSuccess` and `FailedPartitions` (the full set across all affected observers, not just the first to fail). Reach for it deliberately — not as a default.
+The default is fire-and-forget. When a caller's correctness depends on all observers (projections, reducers, reactors) having processed an appended event before returning — integration tests, synchronous webhook surfaces — call `WaitForCompletion` (from `Cratis.Chronicle.Observation`) on the `AppendResult`/`AppendManyResult`. At Chronicle **v19.50.0**, it returns `AppendResultWaitForCompletionResult` with
+`IsSuccess`, `FailedPartitions`, `TimedOut` and `OutstandingObservers`. Inspect
+all of these: timeout returns `TimedOut = true`, not a successful completion.
+The optional `TimeSpan?` defaults to a 5-second server wait plus 200 ms client
+grace; `Timeout.InfiniteTimeSpan` disables both deadlines. Filtering excludes
+observers that do not consume the appended events when the client supplies the
+first sequence number. Source: `Source/Clients/DotNET/Observation/AppendResultWaitForCompletionExtensions.cs`.
+Reach for it deliberately, not as a default.
 
 ## Critical Rules
 
 1. **Idempotent** — Reactors may be called more than once for the same event (e.g. during replay or recovery). Design accordingly. For a side effect that must **not** repeat on replay (emails, payments, external writes), mark the handler method `[OnceOnly]` — Chronicle then skips that handler for every event arriving as part of a **replay** (observer rewind, redaction, revision). That is the whole of it: `[OnceOnly]` is replay-exclusion, **not** exactly-once and **not** a per-event-source counter. Recovering a failed partition re-delivers the event as an ordinary observation, so the handler runs again — which is the point of a retry. When the side effect must survive that retry too, take a `ReactorDelivery` parameter alongside the attribute and keep a receipt under its identity, which is stable across the failure and the recovery.
 2. **Use event data directly** — Never query the read model back inside a reactor. The event contains all the information you need.
 3. **Return events and commands instead of injecting the plumbing** — If the reactor needs to produce new events, return them directly as `Task<TEvent>`, `Task<EventForEventSourceId>`, or a collection thereof. For intent in another slice, return the `[Command]` (Arc executes it; a denied or invalid result fails the partition) — or inject `ICommandPipeline` and inspect the result. Either way the handler is `[OnceOnly]`. Avoid injecting `IEventLog` directly into a reactor.
-4. **Single responsibility** — Each reactor class should have a focused purpose. Multiple handler methods in one reactor are fine if they serve the same automation concern.
+4. **Stable identity and single responsibility** — Give side-effecting reactors
+an explicit `[Reactor("stable-id")]`: full-type-name identity changes on a rename
+or move and catches up from the start, repeating side effects even with `[OnceOnly]`.
+Chronicle v19.50.0 discovery warns on likely drift; `ArtifactIdentityDrift = Fail`
+rejects Warning-level reactor/event-type drift (not Information-level read-model
+findings). Each reactor class should have a focused purpose. Multiple handler methods in one reactor are fine if they serve the same automation concern.
 5. **Failure behavior** — If a reactor throws, *or* a returned side-effect event fails to append (constraint violation, concurrency violation, or error), the failing event-source partition pauses until the issue is resolved. Repeated failures can **quarantine** the observer: once `QuarantineOnFailedPartitionCount`/`QuarantineOnFailedPartitionPercentage` (under `Observers`) is crossed, the observer enters the `Quarantined` state — reminders cancelled, retries stopped, automatic recovery suppressed. **A quarantine ends when an operator clears it (`ClearObserverQuarantine()`), or when the observer is subscribed again** — for an application observer that is when the client connects again, for example after a redeploy; Kernel-owned observers are subscribed again when the Kernel starts. A periodic watchdog (default 60s, `WatchdogInterval`) re-routes stuck/dead observers but does not rescue quarantined ones. Design for resilience.
 6. **Don't throw to validate malformed inbound events** — reactors are not data-quality validators; invalid payloads must be rejected at the command/append site. When a malformed cross-service fact reaches a consumer, throwing just to reject it pauses the partition and can quarantine the whole observer. Instead append a clear failure/dead-letter event (e.g. `ProvisioningFailed`) or surface it via the operational failure path, and skip partial side effects.
 7. **No state** — Reactors should be stateless. Inject dependencies via primary constructor, but do not store mutable state on the class.

package/package/corpus/rules/specs.csharp.md

@@ -17,8 +17,9 @@ Extends the base [specs.md](./specs.md) (folder structure, naming, philosophy) w
 
 ## Frameworks
 
-- [xUnit](https://xunit.net/) for execution.
-- [Cratis.Specifications](https://github.com/Cratis/Specifications) for BDD specification by example — the `Specification` base class discovers `Establish`/`Because`/`Destroy` by convention (no attributes).
+- [xUnit](https://xunit.net/) **2.x** for execution (not v3).
+- Reference `Cratis.Specifications.XUnit` **4.1.1** for the `Specification` base, convention lifecycle and `ShouldXxx` assertions; the namespace remains `Cratis.Specifications`. Its `Cratis.Specifications` dependency supplies `Catch` and `SpecificationMethods`, not the base or assertions.
+- 4.x targets net8.0/net9.0/net10.0; net48 requires 3.x. `Cratis.Specifications.NUnit` is an alternative with `[Test]` and public test methods; xUnit remains the house default.
 - [NSubstitute](https://nsubstitute.github.io/) for mocking collaborators.
 - Spec projects are named `<Source>.Specs`.
 
@@ -44,7 +45,11 @@ public class when_combining_parts : Specification
 | `void Establish()` | setup, before `Because()` | each class in the chain has its own, run base-first — never call `base.Establish()` |
 | `void Because()` | the single action under test | only in concrete spec files, never in a reusable context |
 | `[Fact] void should_*()` | one assertion per fact | use the `ShouldXxx()` extension methods |
-| `void Destroy()` | teardown after each test | |
+| `void Destroy()` | teardown after each fact by default | once per eligible class with shared lifecycle opt-in |
+
+Shared lifecycle is optional (4.1.0+): add `[assembly: Xunit.TestFramework("Cratis.Specifications.SpecificationTestFramework", "Cratis.Specifications.XUnit")]`. Eligible classes derive from `Specification`, have one public parameterless constructor, do not implement `IDisposable`, and contain only plain facts. Construction, Establish/Because and Destroy run once; all facts share the instance and must not mutate it. Initialization failure fails every fact. Other classes keep per-fact execution. Keep the stock lifecycle by default; details are in the **cratis-specifications-csharp** skill's shared-lifecycle reference.
+
+CRSPEC0001–CRSPEC0007 are warnings bundled in `.Specifications`, `.XUnit`, and `.NUnit` 4.0.0+. With warnings as errors, a non-`should_` fact, multiple specs per file (given contexts exempt), a fact on a given context, a `should_` without a test attribute, explicit base lifecycle calls, non-public specs with facts, or `Because` on a given context fail the build. Follow **cratis-specification-by-example**; do not suppress these diagnostics.
 
 ## Reusable layered contexts
 
@@ -87,7 +92,9 @@ async Task Because() => _error = await Catch.Exception(_sut.DoSomething);
 
 ## Assertion extension methods
 
-From `Cratis.Specifications`: `.ShouldEqual(expected)`, `.ShouldBeTrue()`, `.ShouldBeFalse()`, `.ShouldBeNull()`, `.ShouldNotBeNull()`, `.ShouldBeEmpty()`, `.ShouldNotBeEmpty()`, `.ShouldContain(item)`, `.ShouldNotContain(item)`, `.ShouldContainOnly(items)`, `.ShouldBeOfExactType<T>()`, `.ShouldBeGreaterThan(n)`, `.ShouldBeLessThan(n)`.
+From the `Cratis.Specifications.XUnit` package (namespace `Cratis.Specifications`): `.ShouldEqual(expected)`, `.ShouldBeTrue()`, `.ShouldBeFalse()`, `.ShouldBeNull()`, `.ShouldNotBeNull()`, `.ShouldBeEmpty()`, `.ShouldNotBeEmpty()`, `.ShouldContain(item)`, `.ShouldNotContain(item)`, `.ShouldContainOnly(items)`, `.ShouldBeOfExactType<T>()`, `.ShouldBeGreaterThan(n)`, `.ShouldBeLessThan(n)`.
+
+Additional helpers include `ShouldNotEqual`, `ShouldBeSame`/`ShouldNotBeSame`, `ShouldMatch(Func<T, bool>)`, `ShouldBeInRange`, inclusive comparisons `ShouldBeGreaterThanOrEqual`/`ShouldBeLessThanOrEqual`, `ShouldContainSingleItem`, `ShouldEachConformTo`, ordered collection `ShouldEqual(IEnumerable<T>)`, collection `ShouldContain(Predicate<T>)`, `ShouldBeAssignableFrom<T>`, and string `ShouldContain(substring, StringComparison)`. `Catch.Exception` accepts `Action` or `Func<Task>`; `Catch.Exception<T>(Action)` catches only T.
 
 ## Conventions