Define an Arc command
A command is a record that carries the user's intent and owns its own handler.
Arc discovers it, runs authorization and validation, calls Handle(), and turns
whatever Handle() returns into events, server-executed operations, a response,
or a combination.
- An accepted
.playmodel under the model root covers the behavior, or the repository is opted in (pergeneral.md"Model first"; wherecratis-screenplay-modeling-lifecycleis installed, run itsscripts/model-first-status.mjs): change the model first withcratis-screenplay-event-modeling. If the Screenplay skills are not installed, say so and do not author.playfrom memory. Edit code here only for infrastructure, clients, adapters, Screenplay code attachments, or gap-fill scope (cratis-screenplay-render-and-gap-fill); never edit Stage-managed output.
Verified product sources
Read references/product-sources.md for the owning packages and Result.
Arc without Chronicle is a
supported setup; everything on this page that appends events needs Chronicle.
See cratis-arc-command-operation for the operation source and recovery contract.
Declare the command
// Copyright (c) Cratis. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.Events;
namespace <NamespaceRoot>.<Feature>;
[Command]
public record <ImperativeName>(<ConceptType> <Name>, <ConceptType> <Name>)
{
public <EventType> Handle() => new(<Name>);
}
[EventType]
public record <EventType>(<ConceptType> <Name>);
Rules the framework actually enforces:
[Command]isCratis.Arc.Commands.ModelBound.CommandAttributeand applies to a class declaration only. A type counts as a command when it carries[Command]and declares aHandlemethod; either one alone is not enough.Handleis found by name on the command type itself.ARC0003is an error when another class definesHandlefor a command, andARC0004is an error when a[Command]type has no public instanceHandle.ARC0002warns when a type hasHandlebut no[Command];ARC0007warns when a command is aclassrather than arecord.- For returned operations,
ARC0016checks method shapes,ARC0017rejects bare operation collections, andARC0018checks generated-invoker accessibility. - Name the command as the action —
OpenDebitAccount, notOpenDebitAccountCommand. - Unmarked
Handleparameters resolve fromProvide()or DI; ask for services there rather than through a constructor. Server-owned new values use[GeneratedValue]instead (below). - Never inject
IEventLogintoHandleto append the command's own events —ARCCHR0007warns, and it bypasses Arc's append pipeline. Express the append through the return type.
Use concept types rather than raw primitives for the command's values, and give
Chronicle-backed identities the EventSourceId<T> base — see the
cratis-fundamentals-concept skill for the exact shapes.
Choose the return shape
Handle()'s return value is dispatched by its runtime type. The shape decides
what is appended and what the caller gets back. Operations are the exception:
the declared return type must name ICommandOperation/CommandOperations
(directly or in a tuple, Task, Result/OneOf) for Arc to execute them.
| Return | What Arc does |
|---|---|
| A registered event record | Appends it to the command's event source id |
IEnumerable<object> of registered events |
Appends each to the command's event source id |
EventForEventSourceId(id, @event) |
Appends that one event to id |
A collection mixing events and EventForEventSourceId |
Appends each to its own target, wrappers to their id and plain events to the command's |
ICommandOperation (or a concrete operation) |
Executes server-side after returned events are enrolled; never the response |
CommandOperations |
Executes an explicit batch sequentially after event enrollment; never the response |
| A tuple | Each element is dispatched on its own; the one element nothing can handle becomes the response |
| Anything else | Becomes the response payload |
Result<TEvent, ValidationResult> |
Success appends the event; failure becomes a validation failure |
Task<T> / ValueTask<T> of any of the above |
Awaited first, then dispatched |
When choosing a return shape or diagnosing dispatch failures, read handler shapes for the dispatch order, the tuple rule, and the exact failure modes.
⚠️ An unregistered event type is not an error. No handler claims it, so it
silently becomes the HTTP response body instead of being appended. A command
that "runs fine" but appends nothing is almost always a missing [EventType].
For immediate inline side effects chosen by the command, prefer returning an
operation rather than calling the service inside Handle(). Arc executes the
work and selects optional compensation from the commit facts. Direct service
calls remain supported when their result is needed for the decision; durable
after-commit work belongs in reactors/outboxes/workflows. Use
cratis-arc-command-operation rather than a custom response handler or rollback
stack for this application work.
Never return a nullable event or null to mean "nothing to do". Arc only
processes a non-null result, so a null is success with nothing appended and the
caller is told a command succeeded that never happened. Missing state or a failed
rule is a rejection: return Result<TEvent, ValidationResult> with
ValidationResult.Error(...), or reject in a validator or Provide(). Optional
ICommandOperation returns are a separate contract and unaffected. ARCCHR0015 warns on nullable event returns. A nullable
read-model parameter (ARC0006) is handled by rejecting, never by returning a
nullable event.
Two consequences worth knowing before writing the first command:
- The tuple is how a create command returns its new id. An
EventSourceId-derived value in the tuple is not appendable, so it becomes the response — and the response, when it is an event-source id value, is also what the events in that same tuple are appended to. Returning more than one unhandleable element throwsMultipleUnhandledTupleValues. When the command also returns an operation keyed by that id, have the caller supply the id instead of generating a new value, so a retried request reuses the same ownership key. A generated value alone does not provide idempotency. - Events never carry their own event source. Cross-stream writes use
EventForEventSourceId; they are not expressed by a property on the event.
Read references/return-shape-examples.md for create and cross-stream examples.
Generate a server-owned new identifier
Requires Arc 22.66.0 for [GeneratedValue].
Replace local New() with a [GeneratedValue] Handle parameter,
never a request property. Use a non-nullable self-generatable concept and a unique,
case-sensitive generated name. Return the value explicitly if the caller needs it.
Read generated values for Provide/DI boundaries,
validation/captures, ARC0022–ARC0025, migration and named pins; context
factories are covered in the shop reference below.
Choosing a strategy
Use the threaded shop example: CustomerId
(cus_ + ULID), context-aware TypeID OrderId, NanoID InviteCode and secret
Bytes(32) ApiKey. Context factories receive captured
received time/tenant (Requires Arc 22.83.0); Clock/Tenant scenario setup
is shown there.
Read references/fresh-identifiers.md when a generated value is an append target: Requires Arc 22.95.0 for whole-source emptiness protection, collision outcomes, explicit opt-out and decision-mode scenario setup.
When not to generate
Read references/generation-boundaries.md when deciding whether to generate.
Where the event source id comes from
Chronicle resolves the command's event source id in this order:
commandContext.Response, when the response is an event-source-id value — the tuple case above;ICanProvideEventSourceId.GetEventSourceId()on the command;- a single
EventSourceId/EventSourceId<T>-derived or[Key]-marked property on the command; - otherwise a freshly generated id.
Two or more candidates raise ARCCHR0002 ([Key] does not silence it); Arc
silently takes the first declared. Implement ICanProvideEventSourceId.
Read decisions and routing when a command
needs guarded state, stream-id templates, definition-backed routes, event tags or
post-commit CompleteStream. A read-model parameter guards the append only under
read protection On; under Off (the default) it is advisory. Result<,> and
concurrency: true are not protection; see
choosing how a rule holds.
A returned EventForEventSourceId route wins over command context.
Read references/event-source-id-details.md when marking [Key] (two attributes share the name; ARCCHR0008) or using [EventSource<TSource>].
Fetch what the handler needs with Provide()
Provide is an optional instance method that runs before Handle. Its purpose
is to keep IO out of Handle: it fetches or computes values, and Arc binds them
to Handle's parameters by type.
Read references/provide-example.md for a worked Provide() example.
- Short-circuit with
ValidationResult.Error(...); do not throw for a rejection the user can act on. A thrown exception surfaces asHasExceptionsand HTTP 500, not as a validation failure. - Every value
Providereturns must be consumed by aHandleparameter.ARC0005warns otherwise.ValidationResult,AuthorizationResultandCommandResultare exempt because they short-circuit rather than feedHandle. Provideruns after authorization and validation.
An Arc read model can also be injected directly into Provide, Handle, or a
CommandValidator<T> — but only by the command's own resolved key, as a plain
read that guards nothing. Reading a
read model keyed by anything else needs an explicit by-id read, and an absent
instance does not always arrive as null. Read
read-model injection before relying on a
directly injected read model.
Decide what the causation chain may record
Every property value of the command is written to the causation of every event the command appends, and the event log is immutable. Decide this when the property is added.
| Marking | Use for | Effect |
|---|---|---|
[PII] (Chronicle) |
personal data | encrypted in the event and enrolled in erasure; already withheld from causation |
[Encrypted] (Chronicle, Cratis.Chronicle.ProtectedValues) |
an operational secret the system retains — a third-party API key, a company's bank account number | encrypted at rest on the event, no erasure; does not withhold it from causation |
[NotAudited] (Arc Chronicle) |
the same operational secret, and any credential given as a command input | withheld from causation, nothing else |
A retained operational secret needs both [Encrypted] and [NotAudited]; either alone leaves a gap. A credential used for authentication (password, token) is marked [NotAudited] on the command and reaches an event only as a hash or a reference, never encrypted. Never combine [PII] with [Encrypted] (CHR0053).
Read references/causation-details.md when marking an input [NotAudited] or reading ARCCHR0009.
Generate the TypeScript proxy
<PackageReference Include="Cratis.Arc.ProxyGenerator.Build" Version="22.75.0" />
<PropertyGroup>
<CratisProxiesOutputPath>$(MSBuildThisFileDirectory)../<Web>/src/api</CratisProxiesOutputPath>
</PropertyGroup>
dotnet build runs the generator after the build, and only when
CratisProxiesOutputPath is set. Output folders mirror the C# namespace, not the
file path. When configuring proxy generation or diagnosing missing or stale output, read proxy generation for the full
set of MSBuild knobs and the common failures.
Read references/proxy-generation.md when a command declares [BlockOnValidationSeverity].
The generated client contract
The generated proxy is a Command from @cratis/arc. Its members are the same
whatever renders it:
Read references/client-contract.md for the generated proxy members.
Read references/command-result.md when branching on a command result, matching validation failures to fields, or mapping integration exceptions. Branch on the specific flag, not only on isSuccess. The exact CommandResult
and ValidationResult shapes are in
command result — in particular, a validation
failure carries members: string[] (camelCased) and a numeric severity, not a
propertyName string.
validateClientSide() runs only the rules the generator could extract, so it can
pass where execute() still fails validation — read
proxy generation when checking which validation rules are extractable.
Binding this proxy into a React component — the generated use() hook and the
Cratis Components command dialog and form fields — belongs to the Arc React and
Components guidance, not to this skill.
Route near misses
- Adding or changing a rule on an existing command: the Arc command validation guidance.
- Executing an existing command from backend code:
cratis-arc-command-execution. - Declaring inline work, compensation, or operation specs:
cratis-arc-command-operation. - Append-time uniqueness or concurrency constraints: the Chronicle event constraints guidance.
- Choosing the concept or identity type for a value:
cratis-fundamentals-concept.
Verify
Keep Handle a pure function of the command, its read-model parameters and
provided values: that makes it specifiable by a plain call. Start Handle() and
validator decisions with direct calls and supplied read-model state. Add the
pipeline scenario plus a negative proof per authorization policy, validator
rejection and Provide() short-circuit, and a constraint scenario; never
read-protection plumbing or simulated concurrency. Follow the
decision table.
- The command is a
record, carries[Command], and declares a public instanceHandle. - The return shape matches what the command is supposed to do, and any
cross-stream event is wrapped in
EventForEventSourceId. - At most one tuple element is unhandleable.
- Inline work follows
cratis-arc-command-operation: explicit operation return shapes, no duplicate direct write, and tested execution/recovery boundaries. - The event source id resolves from exactly one place;
ARCCHR0002is silent. [Key], where used, isCratis.Chronicle.Keys.KeyAttribute.- No
IEventLogis injected intoHandle. - Every value
Providereturns is consumed by an unmarkedHandleparameter. - Generated parameters follow generated values
and are pinned before scenario execution (
cratis-specifications-csharp). - User-correctable rejections are validation results, never thrown exceptions;
GeneratedValueRejectedinstead signals a defective server generation strategy. - Every secret or personal value is marked before it can reach the event log.
dotnet buildis clean in Debug and Release, with no suppressedARC*orARCCHR*diagnostic left unjustified.- The generated proxy exists at the configured output path and the frontend compiles against it.