@cratis/pi 7.34.0 → 7.35.0

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

@@ -0,0 +1,114 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Inline command operations and aggregate decisions
+
+## Contents
+
+- Several business outcomes
+- Declare work, do not execute it twice
+- Recovery follows commit facts
+- Chronicle aggregates (experimental)
+
+Verified at `Cratis/Arc.TypeScript` **v0.57.2** (source preview, not on npm):
+`Source/Core/commands/CommandOperation.ts`, operation execution/recovery code,
+`Source/Chronicle/ChronicleCommandScope.ts`, `commandAggregate.ts`,
+`Documentation/commands/operations/reference.md`, and
+`Documentation/chronicle/aggregates/**`.
+
+## Several business outcomes
+
+Proxy generation accepts alternatives resolving to the same client type:
+literal unions retain their type; distinct concepts may fall back to their shared
+primitive. Different client types, even identical-shaped DTO classes, fail
+generation: use one response DTO with a status field. A .NET-style arbitrary
+Result error DTO is ordinary response data, not rejection; use `response(...)`
+for data and `rejected(...)`/`denied(...)` for failures.
+
+## Declare work, do not execute it twice
+
+Extend `CommandOperation` from `@cratis/arc.core`. Return an instance from
+`handle()`; a direct call only returns the declaration. Arc executes it in the
+pipeline, never sends it to the client. Use `operations(first, second)` for an
+explicit sequential batch — a plain array is not a batch. Combine with one
+client response using `tuple(response(value), operation)`.
+
+```typescript
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandOperation, command, response, tuple } from '@cratis/arc.core';
+
+// In-memory demonstration, not a durable external-effect implementation.
+const calls: string[] = [];
+class Notify extends CommandOperation {
+    execute(signal: AbortSignal): void {
+        signal.throwIfAborted();
+        calls.push('notify');
+    }
+    compensate(_failure: unknown, signal: AbortSignal): void {
+        signal.throwIfAborted();
+        calls.push('undo notification');
+    }
+}
+
+@command()
+export class SendNotification {
+    handle() { return tuple(response('declared'), new Notify()); }
+}
+```
+
+`executeDependencies` / `compensateDependencies` are service-token arrays;
+Arc resolves dependencies before starting any operation and passes them after
+the signal (after `failure, signal` for compensation). Do not call the same write
+in `handle()` as well as returning the operation.
+
+## Recovery follows commit facts
+
+Arc records entry **before** calling execute, completes scopes before deciding
+recovery, and compensates entered operations in reverse order, including one
+that threw. The separate cooperative `commandCompensationTimeoutMs` budget
+(default 30,000 ms) is shared by compensations, not the cancelled request signal.
+A callback ignoring its signal cannot be forcibly stopped; late completion is
+`BudgetExpired`.
+
+| `CommandCommitDisposition` | Compensation after failure |
+| --- | --- |
+| `NoCommit`, `NotCommitted` | Attempt |
+| `Committed` | Suppress |
+| `Unknown`, `Mixed` | Do not guess: indeterminate recovery, not success |
+
+Direct-call `result.recovery` / `operationOutcomes` describe execution and
+recovery; they are not serialized to HTTP. `CommandScenario` results offer
+`shouldHaveExecutedOperation(Type)`, `shouldHaveCompensatedOperation(Type)`,
+`shouldHaveNoOperationInvocations()`, and `shouldHaveIndeterminateRecovery()`.
+Specify success, throwing/partially-entered operations, cancellation, compensation
+failure/budget expiry, and unknown commit facts.
+
+With Chronicle, `tuple(event, operation)` stages the event, executes the operation,
+then completes the append scope before deciding compensation. Known append
+rejection compensates; unknown/partial acknowledgment does not claim rollback.
+The tagged `Documentation/commands/operations/index.md` still says events and
+operations cannot combine; `ChronicleCommandScope.ts` and the live integration
+specs establish the supported combination at this tag.
+
+There is no distributed transaction, automatic retry, durable recovery journal
+or crash recovery. Compensation success is not proof an external effect was
+undone. After-commit durable work belongs in an idempotent reactor/outbox/workflow.
+
+## Chronicle aggregates (experimental)
+
+`AggregateRoot` and `commandAggregate` come from `@cratis/arc.chronicle`.
+Bind `@inject(commandAggregate(Order))` to an `Order` extending AggregateRoot.
+Arc rehydrates the command's **explicit key**, in the tenant namespace and the
+command's source/stream route. No key fails before handle; loading another id is
+not supported. Each aggregate type loads once per command.
+
+`apply(event)` stages events in the command's batch; a successful command appends
+them even when handle returns nothing. `return order.commit()` is optional;
+never return the same event again. Rejection discards staged events. The route's
+tail is captured at load and appended as an exact concurrency scope; another
+append to the route rejects the entire batch. Projection reads may lag this
+rehydrated state. Use ChronicleKernelScenario for aggregate/concurrency specs,
+not the in-memory scenario. Registered event-source-definition routing for Arc
+commands/aggregates is **not** part of v0.57.2.

package/package/corpus/skills/cratis-arc-command-typescript/references/hosting-and-storage.md

@@ -10,8 +10,7 @@
 - Observable-query WebSockets from a dev server
 - Storage integrations
 
-Verified against `Cratis/Arc.TypeScript` `main` at commit `94d398d` (tag
-`v0.33.0` plus three commits): `Documentation/overview.md`, `hosts/**`,
+Verified against `Cratis/Arc.TypeScript` tag **v0.57.2** (GitHub pre-release): `Documentation/overview.md`, `hosts/**`,
 `mongodb/getting-started.md`, `sql/getting-started.md`,
 `chronicle/registration-options.md`, and the `Express`, `Fastify`, `Hono`,
 `MongoDB`, `Drizzle` and `Chronicle` package exports. None of these packages is
@@ -48,7 +47,14 @@ export const arc = await builder.build();
 Every adapter dispatches only exact raw-path matches on a fixed internal origin
 (a crafted `Host` header cannot select an operation), hands Arc the unparsed
 body, and passes a cancellation signal that becomes `context.signal`. The
-framework owns its listener: close it, then `await arc.dispose()`.
+framework owns its listener. With shutdown participants, coordinate listener and
+service shutdown instead of closing first: `host.shutdown({ timeoutMs, registry? })`
+for the standalone host, `middleware.shutdown(listener, registry?)` for Express,
+or `shutdownArcHost(server, closeListener, registry?)` from
+`@cratis/arc.core/hosting`. `close()` remains listener-only. Register participants
+with `server.services.addShutdownParticipant({ stop, drain })`; `app.stop()` /
+`dispose()` coordinate the same order when Arc owns the registry. Repeated
+`server.dispose()` preserves the first outcome.
 
 ## Express
 
@@ -65,10 +71,7 @@ const listener = app.listen(3000, '127.0.0.1');
 middleware.injectWebSocket(listener);
 
 process.once('SIGTERM', () => {
-    void (async () => {
-        try { await middleware.close(listener); }
-        finally { await arc.dispose(); }
-    })();
+    void middleware.shutdown(listener);
 });
 ```
 
@@ -86,12 +89,13 @@ process.once('SIGTERM', () => {
 ```typescript
 import Fastify from 'fastify';
 import cratisArc from '@cratis/arc.fastify';
+import { shutdownArcHost } from '@cratis/arc.core/hosting';
 import { arc } from './arc.js';
 
 const app = Fastify();
 await app.register(cratisArc, { arc });
 await app.listen({ port: 3000, host: '127.0.0.1' });
-process.once('SIGTERM', () => { void app.close().then(() => arc.dispose()); });
+process.once('SIGTERM', () => { void shutdownArcHost(arc.server, () => app.close()); });
 ```
 
 - The plugin is encapsulated, with its own catch-all raw-body parser; your
@@ -107,13 +111,14 @@ process.once('SIGTERM', () => { void app.close().then(() => arc.dispose()); });
 ```typescript
 import { Hono } from 'hono';
 import { cratisArc, serveCratisArc } from '@cratis/arc.hono';
+import { shutdownArcHost } from '@cratis/arc.core/hosting';
 import { arc } from './arc.js';
 
 const app = new Hono();
 app.use(cratisArc(arc));
 app.get('/health', context => context.text('ok'));
 const hosted = await serveCratisArc(app, arc, { port: 3000, hostname: '127.0.0.1' });
-process.once('SIGTERM', () => { void hosted.dispose().then(() => arc.dispose()); });
+process.once('SIGTERM', () => { void shutdownArcHost(arc.server, () => hosted.dispose()); });
 ```
 
 - Running on Node needs the optional `@hono/node-server`. There the adapter also
@@ -143,9 +148,11 @@ export const app = await builder.build();
 Import `command`, `query`, `readModel` from `@cratis/arc.core/fetch` in artifacts
 served this way. Arc targets **Node-compatible** servers: Chronicle uses gRPC,
 MongoDB uses TCP, and live queries need long-lived SSE/WebSocket connections.
-Non-Node edge runtimes are not supported hosts for the framework or these
-integrations. Bun has a smoke check only. The host owns ingress limits, trusted
-principal metadata, and cancelling long-lived streams on disconnect.
+The Fetch entry supports Next.js App Router route handlers on the **Node.js**
+runtime; Bun and Deno have smoke checks. Cloudflare Workers and Next.js Edge
+are unsupported. Its only Node import is `node:async_hooks`; that does not make
+TCP/gRPC integrations portable to an edge host. The host owns ingress limits,
+trusted principal metadata, and cancelling long-lived streams on disconnect.
 
 ## Observable-query WebSockets from a dev server
 
@@ -164,18 +171,23 @@ adds a builder method when imported; the exported function form is equivalent.
 | Integration | Register | Inject |
 | --- | --- | --- |
 | MongoDB (`@cratis/arc.mongodb`, peer `mongodb` `^6.21.0`) | `import '@cratis/arc.mongodb'; builder.withMongoDB({ client, databaseNameResolver, readModels: [TaskRecord] })` or `withMongoDB(builder, options)` | `service(mongoCollection(TaskRecord))` in `@query`, or `@inject(mongoCollection(TaskRecord))`; `commandReadModel(TaskRecord)` in commands |
-| SQL through Drizzle (`@cratis/arc.drizzle`, peer `drizzle-orm` `^0.45.0`) | `import '@cratis/arc.drizzle'; builder.withDrizzle({ dialect: DrizzleDialect.SQLite, database, readModels: [{ type: TaskRecord, table: tasks }] })` | `service(drizzleReadModel(TaskRecord))` for read-only query handles; `@inject(drizzleDatabase<SQLJsDatabase>())` for a writable handle in commands; `commandReadModel(TaskRecord)` |
-| Chronicle (`@cratis/arc.chronicle`, experimental, peer `@cratis/chronicle` `^6.7.0`) | `import '@cratis/arc.chronicle'; builder.withChronicle({ connectionString, eventStore })` or `withChronicle(builder, options)` | Commands return events; queries take `service(ChronicleReadModels)`; `commandReadModel(Type)` |
+| SQL through Drizzle (`@cratis/arc.drizzle`, peers `drizzle-orm` `^0.45.0` and `rxjs` `^7.8.2`) | `import '@cratis/arc.drizzle'; builder.withDrizzle({ dialect: DrizzleDialect.SQLite, database, readModels: [{ type: TaskRecord, table: tasks }] })` | `service(drizzleReadModel(TaskRecord))` for read-only query handles; `@inject(drizzleDatabase<SQLJsDatabase>())` for a writable handle in commands; `commandReadModel(TaskRecord)` |
+| Chronicle (`@cratis/arc.chronicle`, experimental, peer `@cratis/chronicle` `^6.29.0`) | `import '@cratis/arc.chronicle'; builder.withChronicle({ connectionString, eventStore })` or `withChronicle(builder, options)` | Commands return events; queries take `service(ChronicleReadModels)`; `commandReadModel(Type)` |
 
 - **MongoDB**: list every injected model in `readModels`; a model left out has
   no collection token. `@key()` marks the field stored as `_id` (otherwise a
   field named `id`). Only `server` and `database` bind from `Cratis:MongoDB`
-  configuration. Change-stream observation needs a replica set.
+  configuration. Change-stream observation needs a replica set. Protected raw
+  documents need typed `MongoReadModels` with a Chronicle-registered `readModel`
+  (optional `subjectFor`); untyped reads remain ciphertext. Read
+  [the observation/compliance reference](../../cratis-arc-query-typescript/references/storage-observation-and-compliance.md)
+  before exposing protected documents.
 - **Drizzle**: `withDrizzle` never creates or changes tables — own the schema
   with migrations. Every SQL access needs a tenant (`A tenant is required for
   Drizzle access` otherwise); a single-database setup resolves one fixed tenant.
   Command read-model injection needs exactly one column-level `.primaryKey()`
-  declared as an Arc `@field`.
+  declared as an Arc `@field`. Observation is opt-in; the query skill's
+  storage reference covers in-process announcements and PostgreSQLNotify.
 - **Chronicle**: `withChronicle` needs `eventStore` and exactly one of
   `connectionString` or `client` (`Chronicle requires eventStore and exactly one
   of connectionString or client`). It reads `Cratis:Chronicle` `connectionString`
@@ -187,6 +199,15 @@ adds a builder method when imported; the exported function form is equivalent.
   reachable makes Chronicle-backed requests wait, not fail.
   `chronicle://localhost:35000` without credentials uses the development client —
   local kernels only.
+- **MongoDB + Chronicle naming**: Arc-owned `withChronicle` stores projected
+  models in the collection `withMongoDB` reads (pluralized by default), in either
+  registration order. The former `collectionName: type => type.name` workaround
+  is no longer needed. A throwing/empty collection-name callback fails
+  registration. Override with `withChronicle({ ..., readModelNamingPolicy })`;
+  with a caller-owned client set it in that client's `ChronicleOptions` instead.
+  Existing deployments must replay projections into the aligned collection;
+  the old collection is left intact. Core exports `readModelCollectionNameResolver`,
+  MongoDB exports `resolveMongoCollectionName`.
 - `@cratis/cratis` (experimental) registers Arc and Chronicle together through
   `CratisApplication.createBuilder()` and `builder.addCratis(...)`. Unlike C#
   `AddCratis`, it installs no authentication handler; protected routes still

package/package/corpus/skills/cratis-arc-command-typescript/references/identity-and-introspection.md

@@ -0,0 +1,88 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Identity, authorization and discovery access
+
+Verified at `Cratis/Arc.TypeScript` **v0.57.2** (GitHub pre-release, not on npm):
+`Source/Core/authentication/**`, `identity/**`, `introspection/**`,
+`Documentation/core/authentication.md`, `authorization.md`,
+`Documentation/identity/**`, `hosts/native-principal.md`, and
+`upgrading/secure-defaults.md`. This is the **TypeScript server** contract,
+not the .NET authentication skill.
+
+## Authenticate at one trusted boundary
+
+| Boundary | Builder options | Trust requirement |
+| --- | --- | --- |
+| Arc verifies bearer JWTs | `authentication: [jwtBearer({ jwksUrl, issuer, audience, algorithms })]` | HTTPS JWKS URL; pin issuer, API audience and asymmetric algorithms; validate API tokens, not an ID token |
+| Host middleware already verified identity | `nativePrincipal: true`, plus the adapter's verified native-context callback | Bridge HTTP and WebSocket upgrades explicitly; a raw request/header is not a principal |
+| EasyAuth/AuthProxy ingress | `authentication: [microsoftIdentityPlatform()]` | Strip client `x-ms-client-principal*` headers, set trusted ones and block direct backend access |
+| Application credential check | `authentication: [handler]` | Implement `AuthenticationHandler`; do not trust the display cookie |
+
+`nativePrincipal` and Arc authentication handlers are mutually exclusive.
+Handlers return `AuthenticationStatus.Anonymous` (try next), `Authenticated`
+(with principal), or `Failed` (401 even for an anonymous operation). Principals
+require authenticated status, string `id`, string-array `roles`; name, claims
+and scheme are optional. Arc freezes the principal, roles and own claims.
+With no handler, protected operations answer 403 rather than authenticating.
+
+For Entra bearer tokens, verify against the tenant-specific issuer and API
+audience. App roles and delegated scopes are different; require the one the API
+actually uses. Do not put bearer tokens in query-string URLs. Native identity
+must also be provided on upgrades/SSE; configuring HTTP middleware alone does
+not authenticate a WebSocket upgrade. Named schemes belong in
+`authenticationSchemes: { Verified: handler }` and are selected with
+`@authorize({ schemes: ['Verified'] })`.
+
+## Authorize the operation, not the UI
+
+With no decorator, anonymous callers are permitted. `@authorize()` requires authentication;
+`@authorize({ policy, roles, schemes })` adds requirements, and `@roles('A', 'B')`
+accepts any listed role. Stacked requirements all pass. `@allowAnonymous()` cannot
+coexist with an authenticated requirement on the same declaration. Commands
+carry decorators on the **class**, never `handle`/`provide`; query methods may
+override the read-model class's declaration. Policies and row filters use the
+verified principal, not an input role/tenant or a hidden button.
+Observable authorization runs at subscription opening; changing a role later
+needs an emission guard to stop further disclosure.
+
+## Supply identity details
+
+`@identityDetailsProvider()` on an exported provider lets discovery register it;
+`builder.add(Provider)` is also supported. Implement `IdentityDetailsProvider`
+with `detailsType` (a `@field` model) or `schema` and
+`provide(principal, context)`. Returning undefined denies the authenticated
+caller; output must match the schema.
+
+`GET /.cratis/me` serves principal id/name/roles plus provider `details` and sets
+`.cratis-identity`. This unsigned, JavaScript-readable cookie is **display data,
+never a credential**; provider details never flow into authorization. The
+published React identity hooks can display it, but server protection still
+belongs on every operation. Local users/tenants are development fixtures, not
+production credentials; keep simulated identities on loopback hosts.
+
+## Secure introspection defaults (0.56.0+)
+
+`/.cratis/commands`, `/.cratis/queries`, `/.cratis/identity-details/schema`,
+`/.cratis/users`, `/.cratis/tenants`, and `/openapi.json` are anonymous only in
+Development by default. Elsewhere they require an authenticated principal from
+Arc handlers or the native host. Without authentication, protected discovery is
+unmapped (normally 404) with a startup warning. Explicitly requiring auth with
+none configured fails startup.
+
+- `introspection.requireAuthentication: false` deliberately restores anonymous
+  discovery; outside Development it logs a warning. Prefer authenticating tools.
+- `introspection.roles: 'Admin,Operator'` accepts any listed role, implies auth,
+  and cannot combine with `requireAuthentication: false`; empty roles fail.
+- `introspection.enabled: false` unmaps **catalogs and HTTP OpenAPI**, not identity
+  discovery. Its access policy/diagnostics and in-process metadata remain.
+- Node config: `Cratis:Arc:Introspection:Enabled/RequireAuthentication/Roles` or
+  `Cratis__Arc__Introspection__Enabled/RequireAuthentication/Roles` environment keys.
+- `environmentName` is code-only. Otherwise the first defined
+  `DOTNET_ENVIRONMENT`, `ASPNETCORE_ENVIRONMENT`, `NODE_ENV` decides; no environment
+  is Production. `development: true` enables fixture providers, not this bypass.
+
+`/.cratis/me`, command/query invocation and observable transports are unaffected
+by the discovery policy. Deployed Lens/curl/OpenAPI consumers must authenticate
+or rely on a deliberate anonymous opt-out. Source-based proxy generation needs
+no running host. Verify both anonymous and authenticated access after upgrades.

package/package/corpus/skills/cratis-arc-command-typescript/references/observability-and-host-scopes.md

@@ -0,0 +1,25 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Observability and trusted host scopes
+
+Verified at `Cratis/Arc.TypeScript` **v0.57.2** (source preview):
+`Source/Core/execution/WellKnownTelemetryNames.ts`, `observability.ts`,
+`runInScope.ts`, `RunInScopeOptions.ts`, and `Documentation/observability.md`.
+
+- `cratis.arc.command.duration` / `cratis.arc.query.duration` measure **seconds**.
+  `cratis.arc.command.outcomes` counts command outcomes; the outcome vocabulary
+  is `success`, `validation`, `authorization`, `append_rejected`, `cancelled`,
+  `error`. `cratis.arc.query.transport` distinguishes query transports.
+- Core exports `WellKnownTelemetryNames`, `OperationOutcome`, `QueryTransport`;
+  `@opentelemetry/api ^1.9.0` is a peer. Instrumentation caps command/query names
+  at 1,000 to bound cardinality. Do not add raw user/tenant keys to metric names.
+- `cratis.arc.operation.duration` and the `query_name` attribute are deprecated;
+  migrate dashboards to command/query-specific names.
+
+`ArcServer.runInScope(scope, callback, options?)` runs trusted host integration
+work in a scope created with `server.services.createScope(context)`.
+Service scopes snapshot the execution context at creation. Per-invocation
+options accept only a correlation id (valid UUID) and extra abort signal.
+This is **not** authentication or authorization: never turn untrusted request
+values into a trusted principal by creating a scope.

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

@@ -1,5 +1,9 @@
 ## Generate metadata and proxies
 
+Verified at `Cratis/Arc.TypeScript` **v0.57.2** (source preview):
+`Source/Tools/ProxyGenerator/parseSourceOptions.ts`,
+`Documentation/proxy-generation/getting-started.md`, and sample generator scripts.
+
 `arc-proxygenerator` (package `@cratis/arc.proxygenerator`, also unpublished)
 reads the TypeScript source with the compiler API — it never queries a running
 server. It writes server metadata and client proxies in one run. The CLI
@@ -32,7 +36,34 @@ process.exitCode = result.status ?? 1;
   (`--api-prefix`, `--segments-to-skip`, `--root-namespace`) to the server's
   `generatedApis` options, or proxies call URLs the server does not serve.
 - Generated proxies import the **published** `@cratis/arc` and
-  `@cratis/arc.react` (the docs pin `22.19.1`) plus `@cratis/fundamentals`.
-  Compile them in `Bundler` resolution with `experimentalDecorators: true`, and
-  import `reflect-metadata` once in the frontend entry. Consuming the proxies in
-  React is `cratis-arc-react-page`.
+  `@cratis/arc.react` (docs/sample pins **22.45.0**) plus `@cratis/fundamentals`;
+  the UI samples pin `@cratis/components` 4.23.0. Compile in strict `Bundler`
+  resolution with `skipLibCheck: false`, `experimentalDecorators: true`, and
+  import `reflect-metadata` once in the frontend entry. These published client
+  declarations do not support NodeNext consumer compilation. Consuming proxies
+  in React is `cratis-arc-react-page`.
+
+### Co-locate proxies with the slice
+
+The separate-output form above remains supported. To put proxies next to backend
+artifacts, set `--output` to `Features` (or its ancestor/nested folder) and add
+**`--use-proxy-file-suffix`**. This is required for overlapping output. The
+samples emit `RegisterAuthor.proxy.ts` beside `Registration.ts` and
+`RegisterAuthorForm.tsx`, without barrels. `discover()` skips `*.proxy.ts/.tsx`;
+server tsconfig excludes `Features/**/*.proxy.ts` and `Features/**/*.tsx`.
+Never give a `.tsx` file the same basename as the backend slice `.ts`.
+
+`--watch` regenerates on backend edits; the generator overwrites/deletes only
+its own output. A web bundler reading slice files outside the web project must
+still lower the proxies' legacy decorators: Vite 8 uses
+`oxc: { decorator: { legacy: true } }`.
+
+| Additional flag | Effect |
+| --- | --- |
+| `--skip-react-hooks` | No React import or generated `use*`/`when` hooks |
+| `--type-mapping <Type>=<package>[#<export>]` | Repeatable external mappings (`typeMappings` in programmatic options) |
+| `--watch-poll-interval <ms>` | Poll fallback; requires `--watch`; 0 disables polling |
+| `--js-import-specifiers` | `.js` specifiers for compiled NodeNext ESM; does not fix client declaration compatibility |
+| `--emit-interfaces` | Emit model interfaces |
+| `--skip-index-generation` | Do not emit barrels |
+| `--skip-output-deletion` | Retain stale generated output; use deliberately, not to hide drift |

package/package/corpus/skills/cratis-arc-command-typescript/references/slice-layout.md

@@ -1,5 +1,8 @@
 ## Lay out the slice
 
+Verified at `Cratis/Arc.TypeScript` **v0.57.2**:
+`Samples/Library/Features/Authors/Registration` and sample generator scripts.
+
 House convention (not a runtime requirement): one folder per behavior, one
 TypeScript file named for the behavior holding the command, its validator and —
 for Chronicle — its events. Concepts shared by several slices live one level up.
@@ -13,7 +16,15 @@ Features/Tasks/
 ├── Tasks.ts
 ├── Registration/
 │   ├── Registration.ts
+│   ├── RegisterTask.proxy.ts
+│   ├── RegisterTaskForm.tsx
 │   └── for_RegisterTask/when_registering/with_valid_title.ts
 └── Listing/
     └── Listing.ts
 ```
+
+Co-location needs `--use-proxy-file-suffix` with the artifacts folder as
+`--output`; no barrels. Exclude proxies and TSX from server compilation and
+lower proxy decorators in the frontend bundler. Read
+[proxy-generation.md](proxy-generation.md) when configuring the overlapping
+output or watch mode. Separate output is still supported.

package/package/corpus/skills/cratis-arc-command-typescript/verification.json

@@ -10,6 +10,13 @@
     { "kind": "skill-contains", "value": "Authorization belongs on the **class**." },
     { "kind": "skill-contains", "value": "is created through its **constructor** in `handle()`" },
     { "kind": "skill-contains", "value": "`--check-metadata`" },
-    { "kind": "skill-contains", "value": "CommandScenario.for(RegisterTask, RegisterTaskValidator)", "file": "references/command-specifications.md" }
+    { "kind": "skill-contains", "value": "CommandScenario.for(RegisterTask, RegisterTaskValidator)", "file": "references/command-specifications.md" },
+    { "kind": "skill-contains", "value": "tag **v0.57.2**" },
+    { "kind": "skill-contains", "value": "peer `^6.29.0`" },
+    { "kind": "skill-contains", "value": "Outside **Development**" },
+    { "kind": "skill-contains", "value": "not identity\n  discovery", "file": "references/identity-and-introspection.md" },
+    { "kind": "skill-contains", "value": "Unknown`, `Mixed", "file": "references/command-operations.md" },
+    { "kind": "skill-contains", "value": "**`--use-proxy-file-suffix`**", "file": "references/proxy-generation.md" },
+    { "kind": "skill-contains", "value": "projections (>=6.19.0)", "file": "references/chronicle-events.md" }
   ]
 }

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

@@ -23,12 +23,18 @@ rejection on it.)
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.Core` | `22.16.0` | `CommandValidator<T>`, `ConceptValidator<T>`, `ValidationResult`, `CommandResult`, the command pipeline, `ARC0004`–`ARC0013` |
-| `Cratis.Fundamentals` | `7.19.2` | `Cratis.Monads.Result<TResult, TError>` |
+| `Cratis.Arc.Core` | `22.75.0` | `CommandValidator<T>`, `ConceptValidator<T>`, `ValidationResult`, `CommandResult`, the command pipeline, `ARC0004`–`ARC0013` |
+| `Cratis.Fundamentals` | `7.23.0` | `Cratis.Monads.Result<TResult, TError>` |
 | `Cratis.Chronicle` | `18.3.0` | Read-model resolution for command-side injection |
 | `FluentValidation` | `12.1.1` | `RuleFor(...)`, `.WithMessage(...)` |
 
-> Re-verified at the versions above by **symbol and signature**: every type, attribute and member this skill names exists at that tag, and the public surface it describes is unchanged since the previous verification (Chronicle 16.45.x / Arc 22.10.4 — the Chronicle 16→18 client diff is converters, options and doc comments; no type was removed or renamed). Behavior claims were verified at the earlier tag unless a section says otherwise.
+> Arc validation and decision boundaries rechecked at v22.75.0. Arc depends on
+> Chronicle 19.39.1 / Fundamentals 7.23.0; separate product claims retain their
+> version-qualified verification.
+
+Fundamentals rechecked at v7.23.0 in
+[`Result<TResult, TError>`](https://github.com/Cratis/Fundamentals/blob/v7.23.0/Source/DotNET/Fundamentals/Monads/Result%7BTResult,TError%7D.cs):
+success is first, error second, with implicit conversions from both types.
 
 Reverify against the owning product repository before claiming support for
 another version.
@@ -62,7 +68,7 @@ another version.
 | A reusable value invariant — length, format, range | `ConceptValidator<T>` on the concept type |
 | Command input, cross-field, or a pre-handler check | `CommandValidator<TCommand>` with `RuleFor(...)` |
 | A dependency on data the handler must fetch first | `Provide()` — fetch, and short-circuit if unusable |
-| State-dependent and must hold **under concurrency** | Inject the read model into `Handle()`, return `Result<TEvent, ValidationResult>` |
+| State-dependent and must hold **under concurrency** | Guard the read with `IStreamReads`/`StreamDecision`, or `[ProtectedDecision]` + `DecisionRead<T>`; return events through Arc |
 | Uniqueness | A Chronicle constraint, never a command-side read |
 | A genuine defect or missing infrastructure | `throw` a domain exception |
 
@@ -144,27 +150,49 @@ public async Task<Result<Customer, ValidationResult>> Provide(IReadModels readMo
   directly, and do not duplicate one rejection in both the validator and
   `Provide()` — pick one owner.
 
-## Step 5 — Concurrency-sensitive rules: the read model in `Handle()`
-
-Use this when the rule depends on accumulated event-sourced state — a count, a
-running total — and must still hold when two requests arrive at once. Arc
-resolves the read model before `Handle()` runs and the handler returns a
-`Result<TEvent, ValidationResult>`: success carries the event, failure carries a
-typed validation error.
+## Step 5 — Guard a concurrency-sensitive decision
+
+Plain read-model injection or `IReadModels.GetInstanceById` is **advisory**, even
+inside `Handle()` returning `Result<,>`: it enrolls no guard against a competing
+append. Choose the first boundary that fits at Arc v22.75.0:
+
+1. One routed stream: `Provide(IStreamReads reads) => reads.ForCommand()` returns
+   `Task<StreamDecision>`; `Handle(StreamDecision decision)` returns
+   `decision.Append(...)` (`EventsWithConcurrencyScopes`), guarding the read tail.
+2. Projected state: mark the command `[ProtectedDecision]` and take
+   `DecisionRead<T>` (`.Exists`/`.Instance`) or command-aware `IDecisionReads`.
+   Only Chronicle-admitted, direct event-source-keyed projections with known
+   event types qualify; reducers, joins, children and passive shapes are refused.
+   Only parameterless validators constructed/certified by Arc run. Constructor
+   dependencies are refused; static/service-locator decision state is still your
+   responsibility. Command-level `[Unprotected]` opts out, not into safety.
+3. Stream-level automatic scopes: `concurrency: true` on routing attributes
+   (`EventStreamId`, `EventStreamType`, `EventSourceType`). Exact returned scopes
+   take precedence; do not combine automatic capture with exact scopes.
+
+`ARCCHR0011/0012` flag unprotected reads and immediate append bypasses. Return
+events, never append them directly. Read
+[protected and stream decisions](../cratis-arc-command/references/decisions-and-routing.md)
+when choosing the guard. This handler excerpt assumes `CartSummary` is an
+admitted projection; domain types are the slice's existing types.
 
 ```csharp
 using Cratis.Monads;
+using Cratis.Arc.Chronicle.ReadModels;
 
 [Command]
+[ProtectedDecision]
 public record AddItemToCart(CartId CartId, ItemId ItemId)
 {
     /// <summary>Adds the item; rejects when the cart already holds the maximum.</summary>
     /// <param name="cart">The current cart summary, resolved by the command's event-source id.</param>
     /// <returns>The event on success, or a validation error.</returns>
-    public Result<ItemAddedToCart, ValidationResult> Handle(CartSummary cart) =>
-        cart.ItemCount >= 3
-            ? ValidationResult.Error("A cart can hold at most 3 items.")
-            : new ItemAddedToCart(ItemId);
+    public Result<ItemAddedToCart, ValidationResult> Handle(DecisionRead<CartSummary> cart) =>
+        !cart.Exists
+            ? ValidationResult.Error("Cart must exist.")
+            : cart.Instance.ItemCount >= 3
+                ? ValidationResult.Error("A cart can hold at most 3 items.")
+                : new ItemAddedToCart(ItemId);
 }
 ```
 
@@ -205,7 +233,9 @@ where absence is *not* `null`.
 ## Step 6 — Specify the rejection
 
 Every rule gets a specification of its failure case, using
-`CommandScenario<TCommand>`. Assert **both** that the command did not succeed
+`CommandScenario<TCommand>`. For protected reads, call `UseDecisionReads()`
+before seeding actual events; pinned read models cannot supply a guard. Queue a
+competing append on the relevant route and assert the conflict. Assert **both** that the command did not succeed
 and that it failed *as a validation*:
 
 ```csharp
@@ -231,9 +261,9 @@ the fact. See
 - **The rule never fires.** The read-model type has no backing Chronicle
   projection, reducer, `DbSet<T>`, or MongoDB collection, so nothing registered
   it for command-side resolution.
-- **Two requests both win.** The rule is in a validator or a `Provide()` read
-  rather than in `Handle()` with `Result<,>`, or it is a uniqueness rule that
-  belongs in a Chronicle constraint.
+- **Two requests both win.** A plain read was mistaken for a protected decision;
+  moving it to `Handle()` or returning `Result<,>` does not guard it. Enroll a
+  stream/projection decision read, or use an append-time uniqueness constraint.
 - **`ARC0005` on build.** `Provide()` returns a value no `Handle()` parameter
   consumes.
 

package/package/corpus/skills/cratis-arc-ef-core-migration/SKILL.md

@@ -15,11 +15,12 @@ Everything else is ordinary EF Core.
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.EntityFrameworkCore` | `22.16.0` | `BaseDbContext`, `ReadOnlyDbContext`, `WithEntityFrameworkCore`, column helpers, `EntityFrameworkReadModelForCommandResolver` |
-| `Cratis.Arc.Core` | `22.16.0` | `Cratis.Arc.Queries.ModelBound.ReadModelAttribute`, `ICanResolveReadModelForCommand` |
+| `Cratis.Arc.EntityFrameworkCore` | `22.75.0` | `BaseDbContext`, `ReadOnlyDbContext`, `WithEntityFrameworkCore`, column helpers, `EntityFrameworkReadModelForCommandResolver` |
+| `Cratis.Arc.Core` | `22.75.0` | `Cratis.Arc.Queries.ModelBound.ReadModelAttribute`, `ICanResolveReadModelForCommand` |
 | `Microsoft.EntityFrameworkCore` | `10.0.11` | EF Core itself, including all migration tooling |
 
-> Re-verified at the versions above by **symbol and signature**: every type, attribute and member this skill names exists at that tag, and the public surface it describes is unchanged since the previous verification (Chronicle 16.45.x / Arc 22.10.4 — the Chronicle 16→18 client diff is converters, options and doc comments; no type was removed or renamed). Behavior claims were verified at the earlier tag unless a section says otherwise.
+> Arc EF context, builder and observation surface rechecked at v22.75.0.
+> Verify provider-specific migration behavior against the configured provider.
 
 Reverify before claiming support for another version.
 
@@ -189,9 +190,14 @@ and `ObserveById<TEntity, TId>(id, configure?)`, returning
 `AddEntityFrameworkCoreObservation()` and `options.AddObservation(serviceProvider)`
 on the context — `WithEntityFrameworkCore` already does the first for you.
 
-Paging and sorting are applied at the source for these, and an out-of-range page
-size is clamped rather than throwing, and an unknown sort field is ignored rather
-than failing.
+Paging and sorting are applied at the source; the query pipeline validates
+`page >= 0` and `pageSize > 0`. Unknown observation sort fields are ignored.
+Auxiliary observations can pass `ignoreQueryContext: true` so only the primary
+uses client paging/sorting and writes totals. `ObserveSingle`/`ObserveById` emit
+`default` when the row is absent/deleted/outside the filter, remaining subscribed.
+Indexer-property keys (shared-type entities) are supported; composite and
+shadow-only keys are refused at setup. Source at Arc v22.75.0:
+`Source/DotNET/EntityFrameworkCore/Observe/DbSetObserveExtensions.cs`.
 
 ⚠️ Database-level change notification differs by provider: PostgreSQL uses
 LISTEN/NOTIFY, SQL Server uses Service Broker, and **SQLite has none at all** —