@cratis/pi 2.24.1 → 2.26.0

package/package/corpus/prompts/ship-changes.prompt.md

@@ -22,6 +22,13 @@ requested-label, merge, and branch-cleanup effects. Do not pause to ask for sepa
 each step. Follow the repository's Git commit and pull-request rules, use a true merge commit,
 and verify required checks before merging.
 
+**Exception: a `major` label does not carry merge authority.** Prepare the branch, commits, push,
+and PR labeled `major` as usual, then stop before merging. Ask a human to confirm the breaking
+change(s), who is affected, and the resulting version number, and merge only on an explicit
+affirmative answer to that specific question — see
+[`pull-requests.md`](../rules/pull-requests.md#a-major-release-needs-a-humans-explicit-go-ahead).
+Every other label proceeds through merge under this prompt's ordinary authority.
+
 This prompt is for an explicit request to ship or land. If the user asked only to commit, only to
 push, or only to open a PR, stop after that step: the narrower request does not become authority
 for the rest of the chain because this prompt happens to be loaded.

package/package/corpus/rules/java.md

@@ -0,0 +1,134 @@
+---
+applyTo: "**/*.java"
+paths:
+  - "**/*.java"
+---
+
+# Java Conventions
+
+Java is a supported, first-class Cratis application language alongside Kotlin
+— an Arc.Kotlin-based application can be entirely Java source, with Kotlin and
+KSP present only in the build (Arc generates Kotlin adapters for Java
+declarations under the hood). Write idiomatic modern Java; do not import
+Kotlin idioms into Java source, and do not treat Java as a second-class
+citizen of a Kotlin codebase. Arc/Chronicle-specific shapes (`@Command`,
+`@ReadModel`, `@EventType`, and the rest) live in the matching skill, not
+here.
+
+## Building
+
+- Use `./gradlew build` (or the repository's Maven equivalent) from the
+  command line; it is the definition of "the build is clean" — zero warnings,
+  zero errors.
+- Treat compiler warnings as errors (`-Xlint:all -Werror`); do not suppress a
+  warning to get to green.
+
+## Formatting
+
+- Four-space indentation, no tabs.
+- One public top-level type per file, named after that type.
+- Sort imports alphabetically; no wildcard imports.
+- Braces on the same line as the declaration (`if (...) {`), closing brace on
+  its own line.
+
+## Language — American English Only
+
+All identifiers, Javadoc, and string literals use **American English**
+spelling (initialize, serialize, behavior, color, organization, center,
+modeling, dialog, license, judgment, gray). See [general.md](./general.md).
+
+## Naming
+
+- 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.
+- 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.
+
+## Records and Immutable Data
+
+- Prefer a `record` for an immutable value holder (DTOs, command payloads,
+  query results, read models) over a hand-written class with a constructor,
+  getters, `equals`, `hashCode`, and `toString` — the record gives all of that
+  for free and keeps the file short.
+- Give a record component a validating compact constructor when the type must
+  never hold an invalid value, rather than validating at every call site that
+  constructs one.
+- Favor `sealed` interfaces with a closed set of `permits` implementations
+  over a discriminator field, when a value can genuinely only be one of a
+  known set of shapes — pattern matching over the sealed hierarchy replaces
+  the `instanceof` chain.
+
+## Nullability
+
+- Prefer `Optional<T>` for a method's **return type** when absence is a normal
+  outcome the caller must handle; never use `Optional` as a field type, a
+  constructor parameter, or a method parameter — that is not what it is for.
+- Prefer a non-null default and an explicit `Objects.requireNonNull(...)` at a
+  constructor boundary over accepting `null` and checking for it throughout a
+  class.
+- On a surface consumed from Kotlin (an Arc/Chronicle read model, event, or
+  command reached from Kotlin code), be deliberate about which fields are
+  genuinely optional — a Java field with no null-safety annotation reads as
+  non-null to Kotlin-facing generated code by default.
+
+## Classes
+
+- Favor composition over inheritance; an `interface` plus one or more
+  implementing classes is the house shape for an overridable collaborator, not
+  a base class meant to be extended.
+- Make a class `final` unless it is deliberately designed for extension.
+- Prefer constructor injection over field injection for a Spring-managed
+  bean — a `final` field set in the constructor over an `@Autowired` field.
+
+## Asynchronous Code
+
+- `CompletionStage<T>` (or its `CompletableFuture` implementation) is the
+  house shape for an asynchronous Java API, mirroring how Kotlin exposes
+  `suspend` — Arc's generated adapters await a returned `CompletionStage`
+  without reflection.
+- Never block on a `CompletionStage` inside a method that itself returns
+  one — compose with `.thenApply`/`.thenCompose` or `.thenAccept` instead of
+  calling `.get()`/`.join()` inside the async chain.
+- Give a Java caller its own explicit scope (an `ExecutorService`, or the
+  scope type the host library provides) rather than reaching for a shared
+  global one.
+
+## Javadoc
+
+- Every public type and method meant for consumption outside its package gets
+  a Javadoc comment (`/** ... */`) — what it does and why, not a restatement
+  of its name.
+- Use `@param`, `@return`, and `@throws` for parameters, return values, and
+  checked exceptions.
+
+## Exceptions
+
+- Use exceptions for genuinely exceptional, unrecoverable conditions — not for
+  control flow a caller is expected to handle. A command or query rejection a
+  user can act on is a validation result, not a thrown exception; see the Arc
+  validation skills.
+- Prefer an unchecked exception with a clear name over a checked exception
+  that forces every caller to catch or declare it; reserve checked exceptions
+  for conditions a caller genuinely has a recovery path for.
+
+## Dependency Injection
+
+- Constructor injection is the default for a Spring-managed bean; avoid field
+  injection (`@Autowired` on a field) even though Spring supports it.
+
+## Logging
+
+- Log through the host's structured logging facility (SLF4J via Spring Boot),
+  not `System.out`/`System.err`.
+- Log at the boundary where a decision is made or an error is handled, not at
+  every intermediate call.
+
+## Testing
+
+- JUnit 5 is the house test runner.
+- 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
+  compatibility for a mixed-language library.

package/package/corpus/rules/kotlin.md

@@ -0,0 +1,172 @@
+---
+applyTo: "**/*.kt,**/*.kts"
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+
+# Kotlin Conventions
+
+Kotlin is a JVM-first, coroutine-first language. Use its own idioms — data
+classes, `null`-aware types, coroutines, sealed hierarchies — instead of
+carrying Java or C# patterns across unchanged. A Cratis Arc or Chronicle
+application on Kotlin follows Spring Boot conventions for wiring and this
+file's conventions for everything else; Arc/Chronicle-specific shapes
+(`@Command`, `@ReadModel`, `@EventType`, and the rest) live in the matching
+skill, not here.
+
+## Building
+
+- Use `./gradlew build` from the command line; it is the definition of "the
+  build is clean" — zero warnings, zero errors.
+- Use `./gradlew test` to run tests.
+- Treat compiler warnings as errors. `allWarningsAsErrors` is the house
+  default for Kotlin compilation; do not add a suppression to get to green.
+
+## Formatting
+
+- Four-space indentation, no tabs.
+- One top-level public declaration per file, named after that declaration.
+- Sort imports alphabetically; no wildcard imports.
+- Trailing commas in multi-line parameter lists and call sites — they keep
+  diffs to one line when a member is added or removed.
+- Insert a blank line before the opening `{` of a multi-line `if`/`when`/`for`
+  block; keep single-expression bodies on one line.
+
+## Language — American English Only
+
+All identifiers, KDoc, and string literals use **American English** spelling
+(initialize, serialize, behavior, color, organization, center, modeling,
+dialog, license, judgment, gray). See [general.md](./general.md).
+
+## Naming
+
+- 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.
+- Never suffix a class with `Impl`, `Service`, or `Async` purely to
+  disambiguate — name it for its role.
+
+## Visibility
+
+- Kotlin's implicit-public default is what most declarations should use;
+  spelling `public` is a style choice, not a requirement — decide once per
+  file or module and stay consistent within it.
+- Mark a declaration `internal` when it must not cross a module boundary, and
+  `private` for anything a class does not need to expose. Do not default
+  everything to `public` "to be safe" — a wider surface than necessary is a
+  bigger contract to keep stable.
+- Compile-time discovery (KSP, reflection-based scanning) generally requires
+  **public** top-level types and members. A declaration silently excluded from
+  discovery because it is `internal` or `private` is a visibility bug, not a
+  framework limitation — check the matching skill's discovery rules before
+  assuming a narrower visibility is safe.
+
+## Nullability
+
+Kotlin's type system is the first line of defense against null-related bugs —
+trust it the same way C# nullable reference types are trusted.
+
+- Prefer a non-nullable type and a real default over a nullable one with a
+  defensive check.
+- Use `?.`, `?:`, and `requireNotNull()`/`checkNotNull()` instead of manual
+  `if (x != null)` guards.
+- A nullable outer collection (`List<T>?`) is supported; a nullable *element*
+  inside a collection (`List<T?>`) is a narrower, often-unsupported shape in
+  generated/serialized contracts — do not reach for it without checking
+  whether the surface you are writing actually allows it.
+- Data classes model state, not behavior — keep validation and invariants in
+  the type that owns them (a concept, a validator), not scattered across every
+  call site that happens to touch a nullable field.
+
+## Classes and Data
+
+- Prefer `data class` for immutable value holders (DTOs, events, command
+  payloads, read models) — value equality, `copy()`, and `componentN()`
+  destructuring come for free.
+- Prefer a primary constructor with `val` properties over a body full of
+  assignment statements.
+- Reach for a `sealed class`/`sealed interface` hierarchy instead of an enum
+  with a payload bolted on, whenever the variants carry different data.
+- Favor composition over inheritance; an `interface` plus a `Default*`
+  implementation is the house shape for an overridable collaborator, not a
+  base class meant to be extended.
+
+## Coroutines
+
+- An asynchronous API is `suspend`, not a returned `Future`/`CompletableFuture`
+  — Kotlin callers compose `suspend` functions directly, and a JVM-facing
+  bridge (`CompletionStage`) is layered on top for Java callers, never the
+  other way around.
+- Per-call state travels in a `CoroutineContext` element; never a
+  `ThreadLocal`. A coroutine can move between threads, and thread-local state
+  silently goes stale when it does.
+- Never launch on `GlobalScope`. Use the scope the host (Spring Boot's bounded
+  application coroutine scope, a test's `runBlocking`/`runTest`) already
+  provides.
+- Cleanup that must run even after cancellation goes in
+  `withContext(NonCancellable) { ... }`; everything else should stay
+  cancellable rather than swallow the cancellation.
+- Bridge a genuinely thread-bound third-party API with a
+  `ThreadContextElement`; do not leak a raw `ThreadLocal` into coroutine-facing
+  state as a shortcut.
+
+## Java Interop
+
+Kotlin/Java interop is a first-class concern whenever a library or an
+application may be consumed from Java — which every Arc/Chronicle application
+should assume by default:
+
+- Add `@JvmStatic` to companion-object factories a Java caller needs to call
+  without `Companion.`.
+- Add `@JvmOverloads` to a function with default parameter values so Java
+  gets the shorter overloads too.
+- Give a function returning a value class or an inline class a `@JvmName`
+  when Java needs to call it — the mangled synthetic name is not meant to be
+  called directly.
+- Prefer a `List<T>`/`Map<K, V>` parameter type over a Kotlin-only collection
+  interface on any Java-facing surface.
+
+## KDoc
+
+- Every public type, function, and property meant for consumption outside its
+  module gets a KDoc comment (`/** ... */`) — what it does and why, not a
+  restatement of its name.
+- Keep the summary to one or two sentences; use `@param`, `@return`, and
+  `@throws` for the rest.
+
+## Exceptions
+
+- Use exceptions for genuinely exceptional, unrecoverable conditions — not for
+  control flow a caller is expected to handle. A command or query rejection a
+  user can act on is a validation result, not a thrown exception; see the
+  Arc validation skills.
+- Define a custom exception type when a caller needs to distinguish it from
+  other failures; do not throw a bare `RuntimeException`/`IllegalStateException`
+  for something callers are expected to catch specifically.
+
+## Dependency Injection
+
+- Constructor injection through the primary constructor is the default; avoid
+  field/property injection.
+- Give a collaborator an interface and a `Default*` implementation when an
+  application might reasonably override it, bound with Spring's
+  `@ConditionalOnMissingBean` so a consumer can replace it without forking.
+
+## Logging
+
+- Log through the host's structured logging facility (SLF4J via Spring Boot),
+  not `println`.
+- Log at the boundary where a decision is made or an error is handled, not at
+  every intermediate call.
+
+## Testing
+
+- JUnit 5 is the house test runner for Kotlin and Java alike.
+- 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
+  not prove Java call-site compatibility.

package/package/corpus/rules/profiles.md

@@ -59,14 +59,15 @@ The complete list of available profiles is defined in [profile-catalog.json](../
 | `cratis/application/arc-only` | Arc without Chronicle | `cratis/arc/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
 | `cratis/application/chronicle-dotnet` | Chronicle .NET client | `cratis/chronicle/client-dotnet`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
 | `cratis/application/elixir` | Elixir Chronicle client | `cratis/chronicle/client-elixir`, `cratis/language/elixir` |
-| `cratis/application/kotlin` | Kotlin Chronicle client | `cratis/arc/client-kotlin`, `cratis/chronicle/client-kotlin`, `cratis/language/kotlin` |
+| `cratis/application/kotlin` | Kotlin Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-kotlin`, `cratis/language/kotlin` |
+| `cratis/application/java` | Java Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-java`, `cratis/language/java` |
 
 ### Framework Profiles
 
 | Profile ID | Description | Automatically Includes |
 |---|---|---|
-| `cratis/arc` | Arc CQRS framework | `cratis/arc/csharp`, `cratis/arc/kotlin` |
-| `cratis/chronicle` | Chronicle event sourcing engine | `cratis/chronicle/compliance`, `cratis/chronicle/csharp`, `cratis/chronicle/elixir`, `cratis/chronicle/kotlin`, `cratis/chronicle/multi-tenancy`, `cratis/chronicle/typescript`, `cratis/chronicle/web-workbench` |
+| `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/components` | React component library | (no child profiles) |
 | `cratis/fundamentals` | Core primitives (`ConceptAs<T>`, `EventSourceId<T>`) | (no child profiles) |
 | `cratis/specifications` | Specification framework | (no child profiles) |
@@ -88,6 +89,26 @@ The complete list of available profiles is defined in [profile-catalog.json](../
 | `cratis/language/typescript` | TypeScript language conventions |
 | `cratis/language/elixir` | Elixir language conventions |
 | `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
+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,
+since Arc generates Kotlin adapters for Java declarations.
+
+| Skill | Covers |
+| --- | --- |
+| `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 |
+
+Standalone Chronicle client usage (no Arc) for Kotlin and Java is
+`cratis-chronicle-client-kotlin`, reused by `cratis/chronicle/client-java`.
+JVM language conventions are `kotlin.md` and `java.md`.
 
 ### Specialized Profiles
 

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

@@ -37,6 +37,31 @@ Confirm the current repository workflow contract before selecting release intent
   - **minor** — new features, new slices, non-breaking additions
   - **patch** — bug fixes, refactoring with identical behavior
 
+### A major release needs a human's explicit go-ahead
+
+A `major` label is the one release-intent label a ship request does not, by
+itself, authorize through to merge. Breaking a public API is the most
+consequential and hardest-to-reverse thing a release does — every downstream
+consumer eventually has to act on it — so it gets a checkpoint the other two
+intents do not.
+
+- Prepare the branch, commits, push, and PR carrying the `major` label exactly
+  as any other ship request would.
+- Before merging, stop and ask a human to confirm the major bump specifically:
+  name the exact breaking change(s), who is affected and how, and the
+  resulting version number. A generic "ready to ship?" is not this checkpoint —
+  say plainly that this release breaks compatibility and needs a yes.
+- Proceed to merge only on an explicit, affirmative answer to that question.
+  A prior general instruction to "ship" or "land this" does not answer it,
+  even when it named `major` as the intended label.
+- This checkpoint is per release, not per conversation — a human confirming
+  one major release does not pre-authorize the next one.
+
+This narrows the general ship-changes authorization in
+[`ship-changes.prompt.md`](../prompts/ship-changes.prompt.md) for exactly this
+label; every other step of that workflow proceeds under its existing
+authority.
+
 ### A pull request that changes nothing outward-facing carries `no-release`
 
 **If nothing in the PR can change what a consumer compiles against, runs, or observes, propose repository-supported non-release intent, ordinarily `no-release`** — not `patch`. Confirm that the current workflow supports the label, requires exactly one release-intent label, and suppresses publication as intended before applying it with authorization.