@cratis/pi 7.2.1 → 7.3.0

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

@@ -0,0 +1,495 @@
+---
+name: cratis-arc-command-typescript
+description: Define a Cratis Arc command in a Node.js TypeScript server with Arc for TypeScript — project setup from the source preview, ArcApplication.createBuilder() and discovery, the @command() class with @field inputs, handle() and provide(), outcome helpers, service injection, authorization, returning Chronicle events through withChronicle, generated artifact metadata and proxies, hosting on the standalone host, Express, Fastify, Hono or the Fetch entry, and CommandScenario specs. Use when adding or changing a command in an Arc for TypeScript server, or bootstrapping such a server. Do not use for the .NET or Kotlin/Java Arc command shapes, for a React frontend that calls generated proxies, for validation-only changes, or for query/read-model definition.
+license: MIT
+---
+
+# Define an Arc command in TypeScript (Node.js server)
+
+Arc for TypeScript (`Cratis/Arc.TypeScript`) is the Node.js server implementation
+of Arc. A command is a decorated class that carries the input and handles itself;
+Arc supplies the route, body binding, validation, authorization, and the
+`CommandResult` envelope. There is no controller and no route to write.
+
+## Source preview — read this first
+
+- **None of the server packages is published to npm.** `@cratis/arc.core`,
+  `@cratis/arc.express`, `@cratis/arc.fastify`, `@cratis/arc.hono`,
+  `@cratis/arc.testing`, `@cratis/arc.mongodb`, `@cratis/arc.drizzle`,
+  `@cratis/arc.chronicle`, `@cratis/cratis`, `@cratis/arc.proxygenerator` and
+  `@cratis/eslint-plugin-arc-core` are an unpublished source preview (0.x
+  manifests; versions appear only as source-only GitHub pre-releases). The API may still change. `npm install @cratis/arc.core` fails.
+- **`@cratis/arc` is a different package.** `@cratis/arc`, `@cratis/arc.react` and
+  `@cratis/arc.react.mvvm` are the published **client** runtime, built from
+  `Cratis/Arc`. Generated proxies import them in the frontend. The server packages
+  never depend on them. Never tell a user to install `@cratis/arc` to get a
+  server.
+- `@cratis/arc.chronicle` and `@cratis/cratis` are additionally marked
+  **experimental**.
+
+## Verified product sources
+
+Verified against `Cratis/Arc.TypeScript` `main` at commit `94d398d` (tag
+`v0.33.0` plus three commits), reading `Source/Core/index.ts` and the package
+`index.ts` exports, `Documentation/**`, and the `Samples/Tasks` and
+`Samples/Library` applications. Every API named here exists at that commit.
+Chronicle SDK: `@cratis/chronicle` peer `^6.7.0`; the Library sample pins
+`6.14.0`. Fundamentals: `@cratis/fundamentals` `^7.19.6`.
+
+Host setup, the Fetch entry, and the storage integrations are in
+[references/hosting-and-storage.md](references/hosting-and-storage.md). Returned
+Chronicle events and their specs are in
+[references/chronicle-events.md](references/chronicle-events.md).
+
+## Set up a project
+
+Consume the preview in one of two ways:
+
+| Path | How | Use when |
+| --- | --- | --- |
+| Inside a clone | Put the application under `Samples/<Name>` in a clone of `Cratis/Arc.TypeScript`; reference packages as `workspace:^` | Experimenting, or changing Arc while building on it |
+| Packed tarballs | In the clone: `yarn install`, `yarn build`, then `yarn workspace @cratis/arc.core pack --out <file>` per package; `npm install <file>.tgz` in your project | A separate repository |
+
+Use `yarn pack`, not `npm pack` — Yarn rewrites `workspace:^` dependencies to
+version ranges; npm does not, and the tarball then fails to install. A
+`workspace:^` dependency outside the clone fails at install.
+
+- Node.js 22.19 or later (the core runs on 22; the workspace build needs 22.19;
+  24 LTS is recommended).
+- ES modules only: `"type": "module"` in `package.json`.
+- Peer dependencies of `@cratis/arc.core`: `@cratis/fundamentals` `^7.19.6`,
+  `@opentelemetry/api` `^1.9.0`; `rxjs` `^7.8.2` is an optional peer, needed for
+  RxJS observable queries.
+- TypeScript: the repository and proxy generator use TypeScript 6
+  (`typescript@npm:@typescript/typescript6@^6.0.2`, command `tsc6`).
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "ESNext.Decorators"],
+    "types": ["node"],
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "rootDir": ".",
+    "outDir": "dist"
+  },
+  "include": ["main.ts", "Features/**/*.ts"]
+}
+```
+
+- **No `experimentalDecorators`.** Arc's decorators compile as standard TC39
+  decorators, as the samples do; `ESNext.Decorators` declares `Symbol.metadata`.
+  Legacy `experimentalDecorators` also work. The Library sample compiles its
+  `@cratis/chronicle` 6.14 event types and projections under the same
+  standard-decorator settings. Generated frontend proxies are the exception:
+  they compile with `experimentalDecorators: true`.
+- With `NodeNext`, relative imports carry a `.js` extension. `ESNext` +
+  `Bundler` (the samples' choice) also works.
+- Node's own type stripping does not transform decorators — `node main.ts`
+  fails at the first `@`. Run source with `tsx watch main.ts` during
+  development and compile with `tsc6` for production.
+- A Vitest/Vite transform must lower standard decorators with
+  `useDefineForClassFields: true` (`target: 'es2022'`,
+  `experimentalDecorators: false`), or decorators silently do nothing in specs.
+
+## Bootstrap the application
+
+`Samples/Tasks/main.ts`:
+
+```typescript
+import { ArcApplication } from '@cratis/arc.core';
+import { Tasks } from './Features/Tasks/Tasks.js';
+import { metadata } from './Features/generatedMetadata.js';
+
+const builder = ArcApplication.createBuilder();
+builder.useGeneratedMetadata(metadata);
+builder.services.addSingleton(Tasks);
+await builder.discover(new URL('./Features/', import.meta.url));
+export const app = await builder.build();
+await app.run({ port: Number(process.env.PORT ?? 3000) });
+```
+
+| Call | Effect |
+| --- | --- |
+| `ArcApplication.createBuilder(options?)` | Starts the application; the Node builder reads `appsettings.json` (`Cratis:Arc`) and `Cratis__...` environment variables |
+| `useGeneratedMetadata(metadata)` | Installs parameter and return-type metadata extracted from source. Call it **before** `discover()`/`add()` |
+| `services.addSingleton(Token)` | Registers a service; `addScoped`/`addTransient` take factories. Classes can also carry `@singleton()`, `@scoped()`, `@transient()` |
+| `discover(folderUrl)` | Imports every module under the folder and registers **exported**, decorated artifacts. Skips `dist`, `node_modules`, `given`, `for_*`, `index.*`, declaration files |
+| `add(...types)` | Registers artifacts explicitly — required on the Fetch entry, which cannot discover |
+| `build()` | Validates the whole graph (missing services, lifetime mismatches, misplaced decorators, stale metadata) and throws before any listener opens |
+| `app.run()` / `app.start()` | Standalone Node host. `app.dispose()` stops it and disposes services |
+
+`discover()` refuses a folder that contains the entry point; keep artifacts in a
+dedicated folder such as `Features/`. `Cratis:Arc:Development: true` is for a
+local machine only.
+
+## Lay out the slice
+
+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.
+Specs sit beside the slice in `for_<Subject>/when_<action>/<case>.ts`, which
+`discover()` skips.
+
+```text
+Features/Tasks/
+├── TaskId.ts
+├── TaskTitle.ts
+├── Tasks.ts
+├── Registration/
+│   ├── Registration.ts
+│   └── for_RegisterTask/when_registering/with_valid_title.ts
+└── Listing/
+    └── Listing.ts
+```
+
+## Declare the command
+
+`Samples/Tasks/Features/Tasks/Registration/Registration.ts`:
+
+```typescript
+import { field } from '@cratis/fundamentals';
+import { command, CommandValidator, validator } from '@cratis/arc.core';
+import { TaskId } from '../TaskId.js';
+import { TaskTitle } from '../TaskTitle.js';
+import { Tasks } from '../Tasks.js';
+
+/** Register a task. */
+@command()
+export class RegisterTask {
+    @field(TaskId) id!: TaskId;
+    @field(TaskTitle) title!: TaskTitle;
+
+    handle(tasks: Tasks): TaskId {
+        tasks.register(this.id, this.title);
+        return this.id;
+    }
+}
+
+@validator(RegisterTask)
+export class RegisterTaskValidator extends CommandValidator<RegisterTask> {
+    constructor() {
+        super();
+        this.ruleFor(command => command.title).notEmpty().withMessage('A title is required');
+    }
+}
+```
+
+Rules Arc enforces:
+
+- `@command()` from `@cratis/arc.core` marks the class; it needs a public
+  instance `handle()` (which may be inherited). Name it as the action —
+  `RegisterTask`, not `RegisterTaskCommand`.
+- `@field(Type)` comes from **`@cratis/fundamentals`**, not Arc. Every field is
+  required unless marked `@optional()`, `@nullable()`, or `@defaultValue(value)`
+  (from `@cratis/arc.core`). `@enumeration(EnumObject)` restricts a scalar field.
+  Arrays: `@field(Array, { genericArguments: [Item] })`.
+- Domain values are `ConceptAs<T>` classes with a static `valueType`
+  (`static readonly valueType = Guid;`) because generics are erased at runtime.
+  A concept travels as its primitive on the wire.
+- The artifact must be **exported** from a module under the discovery root, or
+  it is never registered.
+- `handle()` returns a value or a promise; the value becomes `response`.
+  Returning nothing is success without a `response`.
+
+### The command key
+
+The key identifies what the command is about. It is resolved from, in order: a
+registered `CommandKeyResolver`, a `getKey()` method, then the `@key()` field
+(a concept unwraps to its primitive). **No key is inferred from an unmarked `id`
+field.** With Chronicle, the key is the default event source.
+
+### Route
+
+`POST /api/<discovery-namespace>/<command-name>` in kebab case —
+`Tasks.Registration.RegisterTask` serves `POST /api/tasks/registration/register-task`.
+`POST <route>/validate` runs authorization and validation only, never
+`provide()` or `handle()`. Pin a route across folder moves with
+`@command({ namespace: 'Tasks.Registration' })` or `@path('/api/...')`, and keep
+class names in bundled builds (`keepNames` in esbuild).
+
+## Bind parameters
+
+TypeScript erases parameter types, so Arc learns them one of two ways:
+
+- **Generated artifact metadata** (the samples): `arc-proxygenerator --metadata`
+  writes a module from source; `handle(tasks: Tasks)` then needs no decorator.
+- **Explicit tokens**: `@inject(Tasks)` on `handle()` or `provide()`, one token
+  or marker per parameter, in order.
+
+Built-in markers for `@inject(...)`:
+
+| Marker | Binds |
+| --- | --- |
+| `abortSignal()` | The request's `AbortSignal` — pass it to cancelable I/O |
+| `commandContext()` | The `CommandContext`: `key`, `values`, `correlationId`, `principal`, `tenantId`, `signal` |
+| `provided(Type)` | A value from `provide()`, matched by runtime type |
+| `commandReadModel(Type, { optional? })` | The read model for the command key, from a registered resolver (MongoDB, Drizzle, Chronicle) |
+| `mongoCollection(Model)` / `drizzleDatabase()` | Storage handles from the optional integrations |
+
+`build()` fails with `Unbound handle parameters on <Type>.handle` when neither
+metadata nor tokens cover a parameter. Default and rest parameters always need
+explicit tokens.
+
+## Prepare data with `provide()`
+
+`provide()` is optional. It runs after authorization and validation, before
+`handle()`, on the same instance; its value becomes the **first** `handle()`
+argument, before injected services.
+
+```typescript
+import { field } from '@cratis/fundamentals';
+import { command, inject, rejected, validation } from '@cratis/arc.core';
+
+@command()
+export class RenameTask {
+    @field(TaskId) id!: TaskId;
+    @field(TaskTitle) title!: TaskTitle;
+
+    @inject(Tasks)
+    provide(tasks: Tasks) {
+        const task = tasks.byId(this.id);
+        return task ?? rejected(validation('The task does not exist', ['id'], 'notFound'));
+    }
+
+    handle(task: TaskItem): void {
+        task.title = this.title;
+    }
+}
+```
+
+For several prepared values, return `tuple(...)` and mark each `handle()`
+parameter with `@inject(provided(A), commandContext(), provided(B))`.
+`@inject` is accepted only on a command's `handle()` or `provide()`;
+authorization decorators on `provide()` fail at build.
+
+## Return an outcome
+
+| Return from `provide()` or `handle()` | Result |
+| --- | --- |
+| A plain value, or `response(value)` | Success; the value is `response` |
+| Nothing | Success without `response` |
+| `rejected(...results)` | 400 with the validation results; later steps do not run |
+| `denied(reason?)` | 403 with `authorizationFailureReason`; later steps do not run |
+| `tuple(a, b, ...)` | At most one client response; every other value must be consumed by a response value handler (Chronicle events, command operations) or the command fails |
+
+Outcomes are recognized by origin (a private brand), not shape — an object with
+a `kind` property is ordinary data. `rejected()` with no results throws. A
+thrown error is a 500 whose message is redacted unless `exposeExceptionDetails`
+is enabled; do not throw for a rejection the user can act on. Rules that can
+run before `handle()` belong in validators: see
+`cratis-arc-validation-typescript`.
+
+## Protect the command
+
+```typescript
+import { authorize, command, roles } from '@cratis/arc.core';
+
+@command()
+@roles('Librarian')
+export class RegisterAuthor { /* ... */ }
+
+@command()
+@authorize({ policy: 'Finance' })
+export class ApproveBudget { /* ... */ }
+```
+
+- No decorator allows everyone, including anonymous callers.
+- `@authorize()` requires an authenticated caller; `@authorize({ policy?, roles?, schemes? })`
+  a policy, a role, or a scheme; `@roles('A', 'B')` any listed role;
+  `@allowAnonymous()` states anonymous access explicitly.
+- Stacked decorators must **all** pass. `@allowAnonymous()` with an authenticated
+  requirement on the same class fails at startup.
+- Authorization belongs on the **class**. Decorators on `handle()`, `provide()`
+  or any other command method fail the build (a deliberate difference from Arc
+  on .NET, which ignores them).
+- A decision that needs loaded data returns `denied(reason)` from `provide()`.
+
+## Return Chronicle events
+
+With `@cratis/arc.chronicle` registered (`withChronicle`), `handle()` returns the
+event and Arc appends it after authorization, validation and `provide()` pass,
+in the namespace of the resolved tenant. Arc does not require event sourcing: a
+command without Chronicle calls a service, as `RegisterTask` does.
+
+`Samples/Library/Features/Authors/Registration/Registration.ts`:
+
+```typescript
+import { field } from '@cratis/fundamentals';
+import { eventType } from '@cratis/chronicle/events';
+import { command, key, roles } from '@cratis/arc.core';
+import { AuthorId } from '../AuthorId.js';
+import { AuthorName } from '../AuthorName.js';
+
+@eventType()
+export class AuthorRegistered {
+    @field(AuthorName) name: AuthorName;
+    constructor(name: AuthorName = new AuthorName('')) { this.name = name; }
+}
+
+@command()
+@roles('Librarian')
+export class RegisterAuthor {
+    @key() @field(AuthorId) id!: AuthorId;
+    @field(AuthorName) name!: AuthorName;
+
+    handle(): AuthorRegistered { return new AuthorRegistered(this.name); }
+}
+```
+
+- The event class lives in the slice file beside the command, carries
+  `@eventType()` from `@cratis/chronicle/events` and `@field` declarations, and
+  is created through its **constructor** in `handle()` — the house pattern in
+  both samples.
+- `@key()` names the event source; without a key or `getEventSourceId()`, each
+  execution gets a new UUID.
+- A returned event is consumed on the server, so the result carries no
+  `response`.
+- Never append through the SDK inside `handle()` — that append is outside the
+  command's batch.
+
+Returning several events, events beside a response, cross-stream targets,
+routing decorators, concurrency, and the in-memory `ChronicleCommandScenario`
+are in [references/chronicle-events.md](references/chronicle-events.md).
+
+## Generate metadata and proxies
+
+`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
+rejects relative paths, and the output folder must exist:
+
+```javascript
+import { spawnSync } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const path = relative => fileURLToPath(new URL(relative, import.meta.url));
+const cli = fileURLToPath(new URL('./cli.js', import.meta.resolve('@cratis/arc.proxygenerator')));
+mkdirSync(path('./generated'), { recursive: true });
+const result = spawnSync(process.execPath, [cli,
+    '--project', path('./tsconfig.json'),
+    '--artifacts', path('./Features'),
+    '--output', path('./generated'),
+    '--metadata', path('./Features/generatedMetadata.ts'),
+    ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exitCode = result.status ?? 1;
+```
+
+- Commit the metadata module; never edit it. Regenerate after **every** change
+  to a command, read model or validator — `useGeneratedMetadata` throws
+  `Stale generated artifact metadata for <Type>` otherwise. Reordering
+  parameters without changing their count goes undetected, so gate CI with
+  `--check-metadata` and keep `--watch` running beside `tsx` while developing.
+- `--artifacts` must be the folder passed to `discover()`. Match route options
+  (`--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`.
+
+## Host the application
+
+`app.run()` is the standalone Node host. To mount the same built application in
+Express 5, Fastify 5, Hono 4, or a Fetch API runtime, keep the builder and swap
+the host — see
+[references/hosting-and-storage.md](references/hosting-and-storage.md). Mount
+Express's `cratisArc(arc)` **before** any body parser, or every command answers
+400 `malformedRequest`.
+
+## Specify the command
+
+`@cratis/arc.testing` runs a command through the real pipeline in-process —
+binding, authorization, validators, services, `provide()`, `handle()` — without
+a listener. From `Samples/Tasks`:
+
+```typescript
+import { CommandScenario } from '@cratis/arc.testing';
+import { Tasks } from '../../../Tasks.js';
+import { RegisterTask, RegisterTaskValidator } from '../../Registration.js';
+import { metadata } from '../../../../generatedMetadata.js';
+
+export class a_task_registration {
+    tasks = new Tasks();
+    scenario = CommandScenario.for(RegisterTask, RegisterTaskValidator);
+
+    constructor() {
+        this.scenario.extend(builder => builder.useGeneratedMetadata(metadata));
+        this.scenario.services.addSingleton(Tasks, this.tasks);
+    }
+}
+```
+
+```typescript
+import { given, type ScenarioCommandResult } from '@cratis/arc.testing';
+import { TaskId } from '../../../TaskId.js';
+import { TaskTitle } from '../../../TaskTitle.js';
+import { a_task_registration } from '../given/a_task_registration.js';
+
+describe('when registering a task with a valid title', given(a_task_registration, context => {
+    const id = TaskId.create();
+    let result: ScenarioCommandResult;
+
+    beforeAll(async () => {
+        result = await context.scenario.execute({ id, title: new TaskTitle('Plan release') });
+    });
+    afterAll(async () => { await context.scenario.dispose(); });
+
+    it('should succeed through the command pipeline', () => { result.shouldBeSuccessful(); });
+}));
+```
+
+- `CommandScenario.for(Command, ...artifacts)` — pass the validators and other
+  artifacts the command needs; it cannot discover classes that were never
+  imported.
+- Register fakes on `scenario.services` **before** the first call.
+  `extend(builder => ...)` installs builder setup such as generated metadata.
+- `execute(values)` runs everything; `validate(values)` stops before
+  `provide()`/`handle()`. `withContext({ principal, tenantId, correlationId })`
+  sets a trusted caller.
+- `given(Context, ...)` creates **one** context per `describe`: act in
+  `beforeAll`, dispose in `afterAll`. A disposed scenario cannot run again.
+- Assertions on the result: `shouldBeSuccessful()`, `shouldNotBeSuccessful()`,
+  `shouldBeValid()`, `shouldHaveValidationErrors()`,
+  `shouldHaveValidationErrorForMember(member)`, `shouldHaveValidationErrorFor(text)`,
+  `shouldHaveValidationErrorBecauseOf(reason)`, `shouldBeAuthorized()`,
+  `shouldNotBeAuthorized()`, `shouldHaveExceptions()`, `shouldNotHaveExceptions()`.
+- Specify authorization for three callers — anonymous, without the role, with
+  it — and on `validate()` too.
+
+Folder and naming conventions for specs are `cratis-specifications-typescript`.
+
+## Route near misses
+
+- A rejection rule on an existing command: `cratis-arc-validation-typescript`.
+- A `@readModel()` query or observable query: `cratis-arc-query-typescript`.
+- A React page that calls the generated proxies: `cratis-arc-react-page`.
+- Talking to Chronicle outside Arc (a worker, direct append, reactors,
+  projections): `cratis-chronicle-client-typescript`.
+- The .NET command shape: `cratis-arc-command`; Kotlin/Java:
+  `cratis-arc-command-kotlin`.
+
+## Verify
+
+- The command class is exported under the discovery root, carries `@command()`,
+  has a public instance `handle()`, and carries authorization only on the class
+  — never on `handle()`, `provide()` or another method.
+- Every input field has `@field(Type)` from `@cratis/fundamentals`; domain values
+  are concepts with a static `valueType`.
+- The key is explicit (`@key()`, `getKey()`, or a resolver) wherever something
+  depends on it — never an assumed `id`.
+- Rejections the user can act on are `rejected(...)`/`denied(...)` or validator
+  results, never thrown errors.
+- Generated metadata is regenerated and `--check-metadata` passes; `build()`
+  succeeds at startup.
+- The command's `CommandScenario` specs pass, including the unauthorized and
+  `/validate` cases.
+- Guidance never claims the server packages are on npm, and never substitutes
+  `@cratis/arc` (the client) for `@cratis/arc.core` (the server).

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

@@ -0,0 +1,141 @@
+# Returning Chronicle events from an Arc for TypeScript command
+
+Verified against `Cratis/Arc.TypeScript` `main` at commit `94d398d` (tag
+`v0.33.0` plus three commits): `Documentation/chronicle/**`,
+`Documentation/testing/chronicle.md`, `Source/Chronicle/index.ts`, and
+`Samples/Library`. `@cratis/arc.chronicle` is **experimental** and, like every
+package in the repository, not published to npm. `@cratis/chronicle` (the SDK)
+is published; the integration peers `^6.7.0`.
+
+## Register the integration
+
+```typescript
+import { ArcApplication } from '@cratis/arc.core';
+import '@cratis/arc.chronicle';
+import { metadata } from './Features/generatedMetadata.js';
+
+const builder = ArcApplication.createBuilder();
+builder.useGeneratedMetadata(metadata);
+builder.withChronicle({ connectionString: 'chronicle://localhost:35000', eventStore: 'MyArcApp' });
+await builder.discover(new URL('./Features/', import.meta.url));
+const app = await builder.build();
+await app.run({ port: 3000 });
+```
+
+The Library sample uses the equivalent function form,
+`withChronicle(builder, options)`. Discovery hands every discovered event type,
+projection, reducer, reactor and constraint to the Arc-owned client; they must be
+**exported** beneath the discovery root. You do not import `reflect-metadata` for
+the SDK — it imports it itself.
+
+## What `handle()` may return
+
+| `handle()` returns | Result |
+| --- | --- |
+| A registered event instance | Appended to the command's event source |
+| An array of registered events | Appended in one batch |
+| An array of ordinary objects | An ordinary response, not events |
+| `tuple(event, 'message')` | The event is appended to the command key; `'message'` is the response |
+| `tuple(eventSourceIdResponse(id), event)` | The event is appended to `id`, and `id` is the response |
+| `eventForEventSourceId({ eventSourceId, event, eventSourceType?, subject?, tags? })` | Appended to that event source with explicit routing |
+| `eventsWithConcurrencyScopes(events, scopes)` | Appended with exact per-source concurrency scopes |
+| `tuple(event, operation)` | The command operation runs first; the event batch then decides compensation (compensated on a known append rejection, not on an unknown outcome) |
+
+`tuple` comes from `@cratis/arc.core`; `eventSourceIdResponse`,
+`eventForEventSourceId`, and `eventsWithConcurrencyScopes` from
+`@cratis/arc.chronicle`. The wrappers are branded, so a DTO that happens to have
+`event` and `eventSourceId` fields is never mistaken for one.
+
+## The event source
+
+| The command declares | Event source ID |
+| --- | --- |
+| `getEventSourceId()` | Its result (string, `Guid`, or a concept over either); takes precedence |
+| A `@key()` field | That field's value |
+| Neither | A new UUID per execution |
+
+## Routing defaults and concurrency
+
+Class decorators from `@cratis/arc.chronicle` set defaults for every returned
+event:
+
+| Decorator | Sets |
+| --- | --- |
+| `@eventSourceType('Book', { concurrency? })` | Event source type |
+| `@eventStreamType('Lending', { concurrency? })` | Event stream type |
+| `@eventStreamId('main', { concurrency? })` | Event stream ID |
+| `@eventSubject('subject')` | Compliance subject |
+| `@notAudited()` (on a command **field**) | Keeps the value out of the permanent causation chain |
+
+`{ concurrency: true }` reads that dimension's tail **after** `handle()` and
+before the append. It does not protect a decision made from state read earlier.
+For "create once", return `eventsWithConcurrencyScopes([event], { [this.id]:
+{ eventSourceId: true, sequenceNumber: EventSequenceNumber.beforeFirst.value } })`
+(`EventSequenceNumber` from `@cratis/chronicle/eventSequences`). For a decision
+from the source's full history, use a command aggregate (`commandAggregate`).
+For a rule across sources, such as a unique name, use a Chronicle constraint in
+the slice file (`@constraint()` from `@cratis/chronicle/events`, as the Library
+sample's `UniqueAuthorName` does).
+
+## Rejections and the batch
+
+- A constraint or concurrency rejection answers 400 with a validation result
+  (`reason` `constraintViolation` or `concurrencyViolation`) and appends nothing.
+- Events returned by nested Arc commands that share tenant, correlation ID and
+  event store join the outer command's batch, sent once after the outer command
+  succeeds. Any failure discards every staged event.
+- An unknown, partial or incomplete acknowledgment fails the command with an
+  exception, because Arc cannot tell what was stored.
+- An SDK `eventLog.append(...)` inside `handle()` is outside the batch. Return
+  events instead.
+- Appending and projecting are separate: a query sent right after the command
+  may not see the event yet. Prefer an observable query on the client.
+  `completionTimeoutMs` makes the command wait for observers, but Chronicle waits
+  for **every** observer on the log (Cratis/Chronicle#4132), so a projection or
+  reactor that does not handle the event makes every command time out with 500.
+
+## Read current state in the command
+
+`@inject(commandReadModel(Book))` hands `handle()` the Chronicle read model
+projected for the command key; a missing model rejects the command unless
+`{ optional: true }`, which passes `null`. `ChronicleReadModels` (via
+`service(ChronicleReadModels)` or `@inject`) reads other instances. The
+validation-side equivalent is `readModelForValidation(Type)`.
+
+## Reactors that return commands
+
+A Chronicle reactor (from `@cratis/chronicle/reactors`) may return an Arc
+`@command()` instance, or a non-empty array of only commands; Arc runs each
+through the full command pipeline. Handlers are matched by camelCase event-class
+method name, receive parsed JSON content (not a class instance), and run on
+replay by default since SDK 6.9.0 — mark effects `@onceOnly()`, and keep returned
+commands safe to repeat after a failed-partition re-delivery. Reactor authoring
+itself is `cratis-chronicle-client-typescript`.
+
+## Specify it without a kernel
+
+`ChronicleCommandScenario` from `@cratis/arc.chronicle/testing` runs the real
+pipeline with an in-memory event log:
+
+```typescript
+import { ChronicleCommandScenario } from '@cratis/arc.chronicle/testing';
+
+const scenario = ChronicleCommandScenario.for(LendBook, BookLent, ReturnDateSet, LendBookValidator, Book);
+scenario.givenReadModel(Book, bookId.toString(), book);
+const result = await scenario.execute({ bookId, member: 'member-1', days: 14 });
+result.shouldBeSuccessful();
+result.appendedEvents.should.have.lengthOf(2);
+result.shouldHaveAppendedEvent(BookLent, bookId.toString(), event => event.member === 'member-1');
+await scenario.dispose();
+```
+
+- Pass the command, its event types, validators and read-model types to
+  `for(...)`; the in-memory log refuses an unregistered event type.
+- `givenReadModel(Type, id, instance, tenant?)` pins state;
+  `scenario.given.forEventSource(id).events(...)` seeds reducer history (SDK
+  6.14.0 or later).
+- `shouldHaveAppendedEvent` does not check count or order — assert
+  `appendedEvents` when either matters.
+- The in-memory scenario does **not** run projections, aggregates, constraints
+  or concurrency checks. `ChronicleKernelScenario` runs against a live kernel at
+  `ARC_CHRONICLE_TEST_URL` for those.