@cratis/pi 7.34.1 → 7.35.0

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

@@ -0,0 +1,148 @@
+---
+name: cratis-arc-go
+description: Build a Go HTTP CQRS application with Arc.Go commands, read-model queries, validation, identity and explicit hosting lifecycle. Use for the tagged root module and handwritten typed adapters. Do not use for Chronicle-only clients, C# or JVM Arc, or unpublished Go integration and generator modules.
+license: MIT
+compatibility: Go 1.26 or later for Arc.Go v0.1.1; root module only.
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Arc HTTP CQRS in Go
+
+> **Experimental v0:** Arc.Go **v0.1.1**. Companion guidance targets
+> Chronicle.Go **v0.9.1** and Fundamentals.Go **v0.3.2**. Minor releases may break APIs.
+
+**Only `github.com/cratis/arc.go`, the root module, is tagged.** Chronicle and
+MongoDB integrations, `arc-gen`, `arc-vet` and framework-host recipes are separate
+**source previews**, not installable released modules at v0.1.1. Do not prescribe
+those tools, promise generated proxies, or claim returned events append to
+Chronicle in this root-module setup. Arc commands can return ordinary responses
+without an event store.
+
+## Verified product sources
+
+| Product | Tag | Source checked |
+| --- | --- | --- |
+| Arc.Go (`github.com/cratis/arc.go`) | `v0.1.1` | `builder.go`, `application.go`, `server.go`, `lifecycle.go`, `commands/registration.go`, `commands/result.go`, `queries/registration.go`, `queries/example_test.go`, `authentication/microsoft_identity.go`, `example_test.go`, `arctest/example_test.go` |
+
+[Source at v0.1.1](https://github.com/Cratis/Arc.Go/tree/v0.1.1)
+is authoritative. The README's “no tagged Go release yet” wording is stale.
+The [parity ledger](https://github.com/Cratis/Arc.Go/blob/v0.1.1/Documentation/parity.md)
+reports bounded **Partial** conformance; a paired snapshot HTTP checkpoint with
+34/36 strict matches does not establish command, authentication, HEAD or whole-product parity.
+
+## Declare, register and host a command
+
+Install `github.com/cratis/arc.go@v0.1.1` in a consumer module. This complete
+package exposes a greeting with explicit handwritten registration:
+
+```go
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+package greeting
+
+import (
+	"context"
+
+	arc "github.com/cratis/arc.go"
+	"github.com/cratis/arc.go/commands"
+)
+
+// Greet requests a greeting for a name.
+type Greet struct {
+	Name string `json:"name" validate:"required"`
+}
+
+// Handle produces the response without transport concerns.
+func (c Greet) Handle(_ context.Context) (string, error) {
+	return "Hello, " + c.Name, nil
+}
+
+// Build registers Greet and seals application composition without starting it.
+func Build() (*arc.Application, error) {
+	builder, err := arc.NewBuilder(arc.Options{})
+	if err != nil {
+		return nil, err
+	}
+	if err := commands.Register[Greet](builder, commands.Handle(Greet.Handle)); err != nil {
+		return nil, err
+	}
+	return builder.Build()
+}
+
+// Run serves loopback HTTP until the caller cancels its context.
+func Run(ctx context.Context) error {
+	app, err := Build()
+	if err != nil {
+		return err
+	}
+	return app.Run(ctx, "127.0.0.1:8080")
+}
+```
+
+The caller owns signals and error reporting. After calling `Run`, post
+`{"name":"Ada"}` as JSON to `/api/greet`; the Arc envelope contains
+`"response":"Hello, Ada"`. An empty name returns 400. `/api/greet/validate`
+runs authorization/validation without the handler. This sample is public, not
+an authorization baseline for private business operations.
+
+`NewBuilder` and `Build` perform no listener or business-callback activation.
+Build seals composition; do not mutate registries afterward or independently
+build registries borrowed from the root builder. For an externally owned HTTP
+server, explicitly `Start(ctx)` before `ServeHTTP` and `Shutdown(ctx)` with a
+bounded cleanup context. `Run` owns the server path instead.
+
+Use explicit `json` names and named concepts. A typed `commands.Handle` adapter
+supports the result above; do not assume reflective C# discovery. `Provide`
+preparation uses an explicit typed adapter, not an automatically found method.
+Ordinary `(value, error)` results become Arc outcomes. Inspect the returned error
+**and** `IsSuccess`/authorization/validation/exception flags. `Response()` carries
+presence separately from legitimate zero values; `StatusCode()` preserves Arc's
+200/403/400/500 precedence. Failed outcomes discard responses.
+
+## Query a read model
+
+Read [typed query registration](references/queries.md) when defining snapshot
+queries, paging or observable sources. A value-receiver namespace method can
+represent a static-equivalent query, but must still be explicitly registered.
+A comment directive alone does not activate discovery or publish an endpoint.
+
+Root-module observable queries support SSE and WebSocket with emission guards.
+Use a lifecycle-bearing `observable.Source` with `queries.RegisterObservable`,
+not an arbitrary channel returned from a snapshot registration. Preserve query
+identity, authorization/validation on emissions, backpressure and joined cleanup;
+SSE and WebSocket framing are not interchangeable. Consult the tagged
+[observable query guide](https://github.com/Cratis/Arc.Go/blob/v0.1.1/Documentation/backend/go/queries/observable-queries.md)
+before choosing transport or delta behavior. Do not generalize its supported
+profile to an unpublished MongoDB/Chronicle provider.
+
+## Identity and tenancy are security boundaries
+
+`authentication.MicrosoftIdentityPlatform` is an explicitly registered,
+borrowed handler, not a JWT validator. With zero options it ignores forwarded
+identity headers. Enable `MicrosoftIdentityOptions.TrustForwardedIdentityHeaders`
+only behind a credential-validating ingress that strips caller-supplied
+`x-ms-client-principal*` headers, writes verified replacements and prevents direct
+backend access. Base64 and headers are not authentication proof.
+
+Keep identity enrichment (`/.cratis/me`), endpoint authorization and tenant
+membership distinct. Resolve the tenant from trusted request context; never
+interpret a caller's tenant selection as permission to access it. Wire explicit
+policies for private operations and verify both denial and cross-tenant isolation
+before exposing the server. Do not copy .NET identity-provider or attribute APIs
+into Go code.
+
+## Verify and route
+
+- Use `arctest.NewScenario`, `NewCommand` and `NewQuery` for in-process pipeline
+  contracts; close the scenario with a bounded cleanup context. Validation-only
+  assertions must prove no handler invocation/response.
+- Test HTTP routes/envelopes, invalid input, authorization, presence/zero/null,
+  observable cancellation and lifecycle ownership in addition to compilation.
+- Inline operations have commit-aware recovery, not a generic rollback promise;
+  consult tagged operation sources before implementing effects or compensation.
+- A Chronicle-only client belongs in `cratis-chronicle-client-go`, not this skill.
+- Arc.Go v0.1.1 requires Fundamentals.Go v0.1.0; the separate concepts skill's
+  v0.3.2 pin is not a required dependency upgrade.

package/package/corpus/skills/cratis-arc-go/references/queries.md

@@ -0,0 +1,80 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Explicit Go query adapters
+
+Verified at Arc.Go **v0.1.1**, `queries/registration.go`, `queries/example_test.go`
+and `queries/paging.go`. This complete package builds and executes a snapshot
+pipeline; it does not start an HTTP host:
+
+```go
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+package authors
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/cratis/arc.go/metadata"
+	"github.com/cratis/arc.go/queries"
+)
+
+// Author is the owning read model.
+//arc:readmodel
+type Author struct {
+	Name string `json:"name"`
+}
+
+// All is a static-equivalent query; it uses no receiver state.
+func (Author) All(context.Context, queries.NoArguments) ([]Author, error) {
+	return []Author{{Name: "Ada"}}, nil
+}
+
+// ReadAuthors explicitly authorizes a public example query and checks its outcome.
+func ReadAuthors(ctx context.Context) ([]Author, error) {
+	var registry queries.Registry
+	if err := queries.Register[Author](&registry, "All",
+		queries.Function(Author{}.All),
+		queries.WithAuthorization[queries.NoArguments](
+			metadata.Authorization{AllowAnonymous: true})); err != nil {
+		return nil, err
+	}
+	pipeline, err := registry.Build(queries.PipelineOptions{})
+	if err != nil {
+		return nil, err
+	}
+	result, err := queries.Perform[[]Author](ctx, pipeline,
+		"Author.All", queries.Request{})
+	if err != nil {
+		return nil, err
+	}
+	if !result.IsSuccess() {
+		return nil, fmt.Errorf("author query failed with status %d", result.StatusCode())
+	}
+	data, present := result.Data()
+	if !present {
+		return nil, fmt.Errorf("author query returned no data")
+	}
+	return data, nil
+}
+```
+
+The expected result is one `Author{Name: "Ada"}`. This public example opts into
+anonymous access deliberately; use an explicit authorization policy for private
+queries. `//arc:readmodel` documents the model, but handwritten registration is
+what activates this package. The same `queries.Register` accepts a root builder
+when composing HTTP endpoints.
+
+For server-side paging, adapt with `queries.WithParameters` and return a
+`queries.Page[Author]` containing items plus total count; do not fetch an unbounded
+collection just to slice it in memory. The tagged `queries/example_test.go`
+demonstrates parameter binding and paged results.
+
+For observables, `queries.RegisterObservable` records the emission type separately
+from `observable.Source` ownership and rendered client data. Preserve authorization
+and validation guards on every emission, cancellation, terminal errors and cleanup.
+Read the [source and examples](https://github.com/Cratis/Arc.Go/tree/v0.1.1/queries)
+for the exact source/renderer profile instead of assuming channels, providers or
+unpublished generators share one registration contract.

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

@@ -0,0 +1,96 @@
+---
+name: cratis-arc-hosting
+description: Bootstrap and configure a Cratis Arc .NET host — choose AddCratis versus AddCratisArc or ArcApplication, activate Chronicle and storage integrations, disable controllers for trimming/NativeAOT, supply JSON metadata, and check identity/discovery and embedded viewer exposure. Use when creating a host, diagnosing missing endpoints, or preparing a trimmed publish. Do not use for command/query design, running a Chronicle server, or Kotlin/TypeScript hosting.
+license: MIT
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Host Arc for .NET
+
+Choose the host and integrations before copying a bootstrap. Arc is standalone
+CQRS; Chronicle is optional and its client connects to a separate event store.
+Nothing in `AddCratis()` runs the Chronicle engine in your application.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis`, `Cratis.Arc`, `Cratis.Arc.Core` | `22.75.0` | Composition, ASP.NET hosting and standalone host |
+| `Cratis.Arc.Chronicle`, `Cratis.Arc.MongoDB`, `Cratis.Arc.EntityFrameworkCore` | `22.75.0` | Optional client/storage integrations |
+| `Cratis.Arc.Screenplay.Embedded` | `22.75.0` | Optional embedded event-model explorer |
+
+Source verification at [Arc v22.75.0](https://github.com/Cratis/Arc/tree/v22.75.0/Source/DotNET).
+Reverify signatures at the consumer's tag before claiming another version.
+
+## Choose one bootstrap
+
+| Setup | Configure before Build | Activate after Build |
+| --- | --- | --- |
+| ASP.NET, full event-sourced stack (`Cratis`) | `builder.AddCratis(...)` | `app.UseCratis()` |
+| ASP.NET, Arc only (`Cratis.Arc`) | `builder.AddCratisArc(...)` | `app.UseCratisArc()` |
+| Standalone HTTP host (`Cratis.Arc.Core`) | `ArcApplication.CreateBuilder(args)`, then `builder.AddCratisArc(...)` | `app.UseCratisArc()` |
+
+Full-stack ASP.NET bootstrap (requires the `Cratis` package and configured
+Chronicle connection; it deliberately does not opt into unsigned headers):
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Microsoft.AspNetCore.Builder;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.AddCratis();
+var app = builder.Build();
+app.UseCratis();
+app.Run();
+```
+
+`AddCratis` composes Arc, `WithChronicle` and the Microsoft Identity Platform
+header scheme. For your own authentication use `AddCratisArc` plus
+`WithChronicle`, not `AddCratis`. For Arc without event sourcing use
+`AddCratisArc` and your storage/services. On the standalone host the listen URL
+comes from `ArcOptions.Hosting.ApplicationUrl`, not an argument to `UseCratisArc`.
+Read [integrations and publish boundaries](references/integrations-and-publish.md)
+when selecting storage, disabling MVC, adding generated JSON contracts, or
+configuring the explorer.
+
+## Keep trust and discovery explicit
+
+- Forwarded identity headers are ignored by default. Set
+  `Cratis:Arc:TrustForwardedIdentityHeaders=true` only behind an authenticating,
+  header-stripping ingress that prevents direct backend access. `AddCratis`
+  registering a scheme does not make the headers trusted.
+- Discovery is anonymous only in Development by default. Elsewhere it requires
+  authentication, or is unmapped (404) if the host cannot authenticate.
+  `Introspection.RequireAuthentication` unset chooses that default; assigning
+  false deliberately exposes it everywhere. `Roles` implies authentication and
+  cannot combine with false. Disable both `Introspection.Enabled` and
+  `Introspection.IdentityDiscovery` to remove all discovery; `/.cratis/me` remains.
+- `/.cratis/me` uses the authenticated principal, not a readable identity cookie.
+  Configure a real authentication mechanism before treating protected endpoints
+  as usable. See `cratis-arc-authentication-authorization-and-identity` for the
+  full ingress, identity and authorization contract.
+
+Source: [secure defaults at v22.75.0](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/upgrading/secure-defaults.mdx).
+
+## Verify the host, not just the compilation
+
+1. Build in the actual shipping configuration and publish mode, zero warnings.
+2. Start against the intended Chronicle/storage services. Confirm activation
+   maps one intended command and query; a successful Build alone proves neither.
+3. Exercise anonymous and authenticated requests in Development and Production.
+   Check discovery switches and protected invocation independently.
+4. For trimmed/NativeAOT output, run that published binary and exercise JSON
+   responses (including each `CommandResult<TResponse>`), not only an untrimmed
+   Debug host. Missing metadata or service support is a failed publish check.
+5. Confirm MVC and the embedded explorer are absent wherever they are not intended.
+
+## Route near misses
+
+- Define the command and its proxy: `cratis-arc-command`.
+- EF schema/migrations: `cratis-arc-ef-core-migration`.
+- Authentication and identity: `cratis-arc-authentication-authorization-and-identity`.
+- A standalone Chronicle client or running store: the Chronicle client/CLI skills.

package/package/corpus/skills/cratis-arc-hosting/references/integrations-and-publish.md

@@ -0,0 +1,80 @@
+# Integrations and publish boundaries
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+Verified at **Arc v22.75.0**. These are host configuration fragments, not a claim
+that any arbitrary application is NativeAOT-compatible.
+
+## Storage and Chronicle
+
+`AddCratisArc(configureOptions: ..., configureBuilder: ...)` separates
+`ArcOptions` from the `IArcBuilder`. With the corresponding packages referenced,
+the builder supports `WithChronicle`, `WithMongoDB` and `WithEntityFrameworkCore`.
+`AddCratis` instead names these arguments `configureArcOptions` and
+`configureArcBuilder` and composes Chronicle for you. Do not activate/register the
+same stack twice.
+
+- `WithChronicle` installs the Chronicle client integration, including tenant
+  namespace resolution, command returned-event handling and read-model access.
+  The server and its credentials/connection belong to deployment configuration.
+- `WithMongoDB` configures Arc's MongoDB storage/query integration.
+- `WithEntityFrameworkCore` registers the application's EF integration; use the
+  EF migration skill for the actual context/provider/migration setup.
+
+Source signatures under `Source/DotNET`:
+[Cratis composition](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Cratis/WebApplicationBuilderExtensions.cs),
+[ASP.NET builder](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Arc/WebApplicationBuilderExtensions.cs),
+[Core builder](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Arc.Core/ArcApplicationBuilderExtensions.cs),
+[Chronicle integration](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Chronicle/ArcBuilderExtensions.cs),
+[MongoDB integration](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/MongoDB/ArcBuilderExtensions.cs).
+
+## MVC and NativeAOT
+
+For runtime-only removal of MVC, use this ASP.NET configuration excerpt:
+
+```csharp
+builder.AddCratisArc(configureBuilder: arc => arc.WithoutControllers());
+```
+
+Model-bound command/query endpoints still work. Controller commands/queries and
+`MapControllers` do not. Runtime removal alone cannot tell the trimmer to remove
+MVC. For trimming/NativeAOT set the application MSBuild feature switch:
+
+```xml
+<PropertyGroup>
+  <CratisArcControllersSupport>false</CratisArcControllersSupport>
+</PropertyGroup>
+```
+
+The switch also turns controllers off without `WithoutControllers()`. Arc
+registers the ASP.NET services it previously got through MVC (including CORS,
+endpoint API exploration and authorization). Do not infer that every provider,
+serializer or dependency is trim-safe just because MVC is off.
+[Controller boundary](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Arc/ControllersArcBuilderExtensions.cs).
+
+## Application JSON metadata
+
+`ArcOptions.AddJsonTypeInfoResolver(IJsonTypeInfoResolver)` puts application
+contracts ahead of Arc's defaults. Supply your source-generated
+`JsonSerializerContext.Default` during configuration, before serialization makes
+options read-only. Include the read models, query arguments and responses the
+application serializes, and **each** `CommandResult<TResponse>` used for typed
+command responses. Arc's own context cannot enumerate your generic responses.
+Reflection fallback only exists when reflection-based serialization is enabled.
+[Resolver contract](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Arc.Core/ArcOptions.cs).
+
+## Optional event-model viewer
+
+`Cratis.Arc.Screenplay.Embedded` supplies
+`services.AddCratisEventModelViewer(...)` and
+`endpoints.MapCratisEventModel(params Assembly[] assemblies)` (a
+`RouteGroupBuilder`, allowing explicit host authorization). It exposes
+`/.cratis/event-model`. Automatic exposure defaults to an unoptimized Debug entry
+assembly **and** Development; explicit `Enabled=true` overrides that default.
+Do not enable the explorer in a deployed environment accidentally. Mapping it
+manually needs an intentional host policy, not an assumption of automatic gating.
+The Screenplay family owns generated-model content and compiler capability.
+Sources: [viewer registration](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Screenplay.Embedded/Hosting/EventModelViewerServiceCollectionExtensions.cs),
+[mapping](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Screenplay.Embedded/Hosting/EventModelEndpoints.cs),
+[automatic exposure](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/Screenplay.Embedded/Hosting/EventModelViewerExposure.cs).

package/package/corpus/skills/cratis-arc-identity-and-tenancy-kotlin/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: cratis-arc-identity-and-tenancy-kotlin
+description: Wire Kotlin or Java Arc authentication, application identity details and tenant resolution — AuthenticationHandler, IdentityDetailsProvider, tenancy.required, resolver precedence, ambient coroutine tenancy and the opt-in trusted platform-header bridge. Use for JVM Arc identity endpoints, tenant isolation or security ingress setup. Do not use for C# Arc identity, command input validation, or standalone Chronicle namespace resolution.
+license: MIT
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Resolve identity and tenancy in JVM Arc
+
+Authentication identifies the caller; authorization decides whether they may
+execute an operation; tenant resolution selects their data boundary. Configure
+and verify all three separately. A tenant header alone proves no membership.
+
+## Verified product sources
+
+Verified at `Arc.Kotlin v7.7.0`: `Source` authentication/identity/tenancy contracts,
+`Integrations/SpringBoot/ArcTenancyProperties.java`, platform security classes,
+`Documentation/guides/security.mdx`, `ambient-tenancy.mdx` and
+`reference/configuration.mdx`. Use `io.cratis:arc-spring-boot-starter:7.7.0`
+(or `io.cratis:cratis:7.7.0` for Chronicle integration), with matching plugin/KSP.
+These are JVM contracts; do not infer the same switches exist in Arc .NET.
+
+## Authenticate and expose identity details
+
+Register ordered `AuthenticationHandler` beans. A handler gets immutable
+`AuthenticationRequestContext`: case-insensitive headers, cookies, captured
+principal and selected tenant. Return:
+
+- `AuthenticationResult.ANONYMOUS` when credentials are not recognized, so the
+  next handler can try.
+- `AuthenticationResult.failed(...)` for recognized but rejected credentials.
+- `AuthenticationResult.succeeded(...)` with an `ArcPrincipal` on success.
+
+Success and failure are terminal; a later handler cannot override a rejection.
+Spring interleaves Kotlin handlers and Java `AsyncAuthenticationHandler` beans
+in global `@Order`. Java handlers return `CompletionStage`, which Arc adapts.
+Do not block while verifying credentials. Public authentication errors are
+generic 401 responses, not the handler's private reason.
+
+With Spring Security present, Arc captures its principal before suspending
+work. `ROLE_` authorities become unprefixed Arc roles. Without it, Arc captures
+the servlet principal. Never read thread-local security state after suspension.
+
+Register exactly one `IdentityDetailsProvider<T>` to serve `GET /.cratis/me`.
+Supply `detailsType: Class<T>` and return `IdentityDetails<T>` from
+`provide(IdentityProviderContext)`, including `isUserAuthorized` and the
+application payload. Use a concrete DTO KSP can describe; an unsupported
+identity shape fails `ARCKSP0307`. Java uses `AsyncIdentityDetailsProvider<T>`.
+Multiple providers fail startup. The client-readable identity cache cookie is
+excluded from authentication input and cannot authenticate a later request.
+
+`@Authorize`, `@Roles`, `@AllowAnonymous` declare authorization. An operation's
+own metadata replaces its class default wholesale; contradictions on the same
+declaration fail `ARCKSP0108`. See `cratis-arc-command-kotlin` for precedence.
+
+## Configure inbound tenant resolution
+
+Keys below are under `cratis.arc`:
+
+| Key | Default / contract |
+| --- | --- |
+| `tenancy.resolvers` | `header`; ordered `fixed`, `header`, `query`, `claim`, `subdomain`, `development` |
+| `tenancy.required` | `false`; true rejects unresolved command, query, observable and identity requests with 400 |
+| `tenancy.header-name` | unset uses `tenant-header` (default `x-cratis-tenant-id`); case-insensitive |
+| `tenancy.query-parameter-name` | `tenantId`; case-sensitive |
+| `tenancy.claim-type` | `tenant_id` |
+| `tenancy.base-domain` | empty; subdomain resolution needs a valid multi-label DNS base domain |
+| `tenancy.fixed-tenant-id` | `development` |
+| `tenancy.constrain-to-authenticated-claims` | `true`; when membership claims exist, selection must match one |
+
+Keep claim constraints on. Absence of membership claims is not proof the caller
+belongs to every tenant; add the application authorization policy required by
+your domain. Do not expose development/fixed selection as production isolation.
+`TenantsProvider` lists development tenants for tools; it does not resolve a request.
+
+Resolution is not storage routing. Plain repository injection is ordinary
+Spring DI, not automatic tenant isolation. Use certified tenant-aware store
+resolvers and test two-tenant isolation; `cratis-arc-spring-data-kotlin` covers
+the storage boundary. Chronicle namespace mapping is a separate integration concern.
+
+## Carry an already resolved tenant
+
+`withTenant(TenantId(...))` installs a `TenantCoroutineContext` that survives
+suspension and dispatcher switches. `currentTenant()` returns the nearest
+tenant or `null`; `currentTenantOrNotSet()` returns `TenantId.NOT_SET` when absent.
+Nested scopes shadow the outer tenant for their duration. These functions do
+not resolve HTTP requests or authorize a tenant.
+
+Java on a plain thread uses `TenantContextBridge.withTenant` and
+`TenantContextBridge.currentTenant()`. The bridge blocks through `runBlocking`;
+do not call it inside an active coroutine. Kotlin coroutine code uses the
+suspending APIs, not a `ThreadLocal`. Establish scopes explicitly for background
+work; do not assume an inbound request or command establishes every ambient seam.
+
+## Opt into trusted platform headers only behind secure ingress
+
+`cratis.arc.platform-identity.enabled` defaults to `false`. Base64 is unsigned
+input, not authentication. Enable the bridge only behind authenticated ingress
+that strips caller-supplied `x-ms-client-principal`,
+`x-ms-client-principal-id`, `x-ms-client-principal-name` and rewrites them from
+verified identity. Block direct backend access.
+
+Supply an `ArcPlatformIdentityTrust` bean checking the actual deployment
+boundary on every submission; the default denies all. Do not trust forwarded
+headers or an address a request wrapper rewrote without verified proxy handling.
+Header parsing cannot install firewall, TLS or ingress guarantees.
+
+With Spring Security absent or the bridge disabled, Arc registers no platform
+filter/chain. With no application chain, enabling it creates a conservative
+chain: all routes need authentication and CSRF remains enabled. Arc does not
+rewrite an application `SecurityFilterChain`; add `ArcPlatformAuthenticationFilter`
+after existing authentication and before `AnonymousAuthenticationFilter` only
+in chains intended to accept platform identity. Keep servlet registration
+disabled to prevent double execution outside Spring Security.
+
+Valid submissions never replace an already authenticated non-anonymous identity.
+Invalid/partial/repeated submissions fail generically with 401 (earlier filters
+may reject first). The bridge retains identity in request attributes, not the
+HTTP session. Never log identity headers, raw claims or the cache cookie.
+Consult the tagged security guide for the bounded header schema and limits
+before changing an ingress adapter; do not hand-roll permissive parsing.
+
+## Verify and route
+
+- Test the resolver order, missing tenant, membership mismatch and valid selection
+  with `withTenantResolution` in `cratis-arc-testing-kotlin`.
+- Exercise anonymous, accepted and rejected credentials plus identity-details
+  authorization; do not mistake a successful details response for authentication.
+- Verify tenant propagation across a dispatcher switch and two isolated stores.
+- If enabling platform identity, test spoofed/direct submissions fail, legitimate
+  ingress succeeds, CSRF remains enforced, and the filter runs once.
+- Run the application's `./gradlew build` and real storage/ingress checks.
+
+Command rules: `cratis-arc-validation-kotlin`. Standalone Chronicle namespaces:
+`cratis-chronicle-client-kotlin`, not this resolver configuration.

package/package/corpus/skills/cratis-arc-observable-query-http/SKILL.md

@@ -13,7 +13,7 @@ request is made. Choose the transport first, then the command.
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.Core` | `22.16.0` | `ObservableQueryHttp`, `ObservableQueryHandler`, the demultiplexer routes |
+| `Cratis.Arc.Core` | `22.75.0` | `ObservableQueryHttp`, `ObservableQueryHandler`, the demultiplexer routes |
 
 > 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.
 
@@ -119,6 +119,23 @@ inconvenient — a proxy that buffers, a client with no streaming support.
 authorization and the `Count()` a paged query performs. Long polling a hot query
 is not free.
 
+## Diagnosis and emission protection (Arc v22.75.0)
+
+Plain HTTP snapshots/waits/long polls run read-model interceptors and
+`IGuardObservableQueryEmission`: denied data returns unauthorized; suppressed
+emissions remain 202 until an allowed value (or the wait deadline). Failures
+respect `ExposeExceptionDetails`. `IAsyncEnumerable` plain-query requests still
+return 400; do not assume every streaming return shape works on snapshot HTTP.
+
+For a MongoDB-backed query stuck at Loading with no first result, check database
+connectivity, replica-set change-stream support and permissions first (Arc#2916).
+The collection watch logs failure then completes without `OnError`; frontend
+error UI is not reliable evidence the watch is healthy. A waiting HTTP request
+still has its timeout/completion contract; do not describe it as an infinite wait.
+Sources at v22.75.0: `Arc.Core/Queries/ObservableQueryHttp.cs`,
+`ObservableQueryHandler.cs` and
+[MongoDB observations](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/mongodb/observing-collections.md).
+
 ## What comes back
 
 Every transport carries the same `QueryResult` shape:
@@ -130,7 +147,8 @@ paging { page, size, totalItems, totalPages }, changeSet?
 ```
 
 `data` is the full snapshot. `changeSet` may also be present for collection
-updates, carrying `added`, `replaced` and `removed`.
+updates, carrying `added`, `replaced` and `removed`. Items without `Id` use
+full snapshots; `IHaveKnownChanges` supports known-change collection results.
 
 Paging and sorting keys work here too: `page`, `pageSize`, `sortby`,
 `sortDirection`. `pageSize` is what enables paging at all, and `page` is

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

@@ -12,14 +12,13 @@ static (Java) methods are queries. KSP generates a reflection-free
 
 ## Verified product sources
 
-Verified against `Arc.Kotlin` at tag **`v7.3.0`**, re-verified at commit
-`d0aa6a4` (14 commits past the tag), documented consumer setup: JDK 17,
-Kotlin 2.4.20, KSP 2.3.12, Spring Boot 4.1.x. `io.cratis:arc` supplies
+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. `io.cratis:arc` supplies
 `io.cratis.arc.artifacts.ReadModel`, `io.cratis.arc.queries.Path`,
 `@QueryHttpMethod`, `@QueryTransport`, `ObservableState<T>`. The optional
 `arc-rxjava3` artifact adds RxJava 3 `Observable` support at runtime. The
-re-verification added `ObservableState<T>` (new since the tag) and the
-`observable-queries.allowed-origins` WebSocket setting — both covered below.
+`queries/QueryPage.kt`, `QueryRendererFor.kt` and the observable pipeline
+verify the paging and transport contracts below.
 
 ## Declare a one-shot query
 
@@ -115,7 +114,16 @@ needed for these:
 - RxJava 3 `Observable<T>` / `ObservableSource<T>` / `Subject<T>` — requires
   the optional `arc-rxjava3` artifact at runtime
 
-A one-shot return (`T`, `List<T>`, `Page<T>`) stays request-response.
+A one-shot return (`T`, `List<T>`, `io.cratis.arc.queries.QueryPage<T>`) stays
+request-response. `QueryPage(items, page, pageSize, totalItems)` carries a
+provider-owned page, with zero-based page and `totalItems: Long`.
+
+A matching application `QueryRendererFor<T>` chain owns data and paging:
+Arc does not append implicit in-memory sorting/paging after it. Return
+`QueryPage<T>` or include `QueryableQueryRenderer()` explicitly in that chain.
+`QueryPaging.UNPAGED` and `QuerySorting.UNSORTED` represent no paging/sorting;
+`InterceptReadModel<T>` is the read-model interception seam. The default
+in-memory sorter reads public properties only; sorting is not authorization.
 
 ```kotlin
 @ReadModel
@@ -201,10 +209,20 @@ Leave it empty in a real deployment — the WebSocket handshake is not subject
 to the same-origin policy `fetch` obeys, so this setting is what stops another
 site from opening a socket carrying your visitor's cookies.
 
+## Storage-backed queries
+
+For repository-backed paging, concept converters, tenant-aware storage and
+Mongo/JPA observable snapshots, use `cratis-arc-spring-data-kotlin`.
+Arc `7.7.0` also aligns Chronicle projection collection names with Arc MongoDB;
+read [../cratis-arc-command-kotlin/references/read-model-naming.md](../cratis-arc-command-kotlin/references/read-model-naming.md)
+when upgrading or customizing collection names.
+
 ## Route near misses
 
 - Defining or changing a `@Command`: `cratis-arc-command-kotlin`.
 - Adding a query-argument rejection rule: `cratis-arc-validation-kotlin`.
+- In-process query specifications: `cratis-arc-testing-kotlin`.
+- Identity or tenant resolution: `cratis-arc-identity-and-tenancy-kotlin`.
 - How events populate the read model in the first place (Chronicle projections
   and reducers): `cratis-chronicle-client-kotlin`, `cratis-chronicle-projection`,
   `cratis-chronicle-reducer`.
@@ -223,3 +241,5 @@ site from opening a socket carrying your visitor's cookies.
 - A `delta`-mode observable query has a stable item identity, not incidental
   reliance on serialized-JSON fallback identity.
 - `./gradlew build` is clean with zero warnings and zero errors.
+- Use `QueryScenario` or bounded `ObservableQueryScenario.collect` from
+  `cratis-arc-testing-kotlin`; assert emission count, not only success.