produces: express the target event source and multi-stream appends

[woksin]

Summary

A command's produces block can state which event is appended and how its properties map, but not where it is appended: there is no way to express the target event source, and no way to express a handler that appends to several event sources in one decision. Both are first-class Arc shapes, and generators must currently drop them.

Evidence (real application)

Generating from the Ada application (Cratis.Arc.Screenplay 20.65.0):

• 10 × SP0013 [Information] The handler yields the identifier of the event source alongside the event, which Screenplay has no counterpart for — handlers returning (EventSourceId, TEvent) tuples to append somewhere other than the command's own stream.
• Multi-source appends are fully inexpressible: Ada's Activate command returns IEnumerable<EventForEventSourceId> fanning out to four event sources in one decision (ContractPolicy, RequestDetail, RequestContract, CandidateWorkSurface). The generated document shows a plain produces list with no hint that the events land on different streams.
• Derived event-source identity is also unstatable: StartMonth implements ICanProvideEventSourceId with TimesheetId.For(EngagementId, Year, Month) — the fact that the stream identity derives from command input is part of the slice's behavior (it is what makes the unique event constraint work) and the document cannot say it.

Other corners of the language already acknowledge event-source targeting: seeds have for "<event source id>", and projections have key expressions — produces is the gap.

Suggested direction

An optional targeting clause on produces (syntax open):

produces TimesheetStarted for key(engagementId, year, month)
produces ContractPolicyActivated for ContractPolicy

or an indented for <expr> line inside the produces block, reusing the PDL key-expression parser. Multi-source handlers then become several produces entries with different targets — which is exactly what the code does.

Context

Found while validating a generated 5,348-line document from a production Arc application against its source.

[woksin]

Verified

Re-verified against main. produces <EventType> carries the event name and a mapping block and nothing else — CommandParser.ParseProduces has no slot for a target, and ProducesSyntax has no field for one. Every event a command produces goes to the command's implicit event source.

Two neighbouring constructs already say the thing this issue needs, in two different shapes:

• seed names its target with a quoted literal — SeedParser line 87, ^for\s+"(...)"$, used as for "3fa85f64-…" in invoicing.play.

• Projections name theirs with a key expression — ProjectionParser.ParseKey handles both the single-expression form (key invoiceId) and the composite form used at invoicing.play:671:

  key InvoiceLineKey
    invoiceId  = invoiceId
    lineNumber = lineNumber
  

So the language already has a vocabulary for "which stream is this about". produces is the one place that needs it and does not have it.

Design alternatives

1. A trailing for <key-expression> on the produces header, reusing the PDL key parser.

produces MonthlyHoursRegistered for key(engagementId, year, month)
produces InvoiceCancelled for invoiceId

Reuses ParseKey verbatim, so composite keys, $eventSourceId and context expressions all work on day one and print back through the existing key printer. Reads left to right as one statement: produces this event, for that source.

Cost: the header line grows, and the composite form does not fit on one line — key(a, b, c) is a new spelling of something PDL already spells as an indented block, so we would have two syntaxes for a composite key.

2. An indented for <key-expression> line inside the produces body.

produces MonthlyHoursRegistered
  for key MonthlyKey
    engagementId = engagementId
    year         = year
    month        = month
  hours = hours

Consistent with how PDL already writes composite keys, and there is exactly one spelling. The for keyword is already the seed group's word for the same idea, so nothing new is introduced. Printer parity is trivial — one more directive in an already-ordered body.

Cost: the target is now buried among the property mappings rather than visible on the header, and for inside a mapping block is a new reserved first word (which #27's @ escape already covers, but it is one more).

3. Named-stream forms — produces X to stream <name> / to source <id>.

Most explicit about which dimension is being set, and it maps onto the Chronicle metadata a reader may actually need (EventSourceId vs EventStreamType vs EventStreamId). But it invents a vocabulary the rest of the language does not use — concurrency already spells these dimensions eventSource / sourceType / streamType / streamId, and adding a third spelling for the same concepts is the opposite of convention over configuration.

Recommendation

Alternative 2 — the indented for line, reusing the PDL key parser. It keeps one spelling for a composite key, borrows for from seed where it already means exactly this, and leaves the header line alone. Multi-stream appends then fall out with no extra syntax: several produces blocks under one command, each with its own for, which is the shape that matches Arc's IEnumerable<object> with EventForEventSourceId wrappers.

Derived stream identity (ICanProvideEventSourceId) is the case I would explicitly not try to express. A for expression over the command's own properties covers the declarative cases; when the identity is computed by code, that is what the handler escape hatch is for, and per #40 the document still says what is produced even when it cannot say where it lands.

Sequencing

Independent of the declarable-name work in #29/#28/#39 — this touches only ProducesSyntax and the command parser, and it needs no new resolution.

It does interact with #35: if a command can declare reads <ReadModel>, then a for expression should plausibly be allowed to reference the state it read, not just the command's own properties. I would land for over command properties first (self-contained, useful immediately), and revisit whether state-fed keys are needed once #35 has a shape.

It also pairs naturally with #34, which just gave reactors produces. If reactors and commands are going to share the word, they should share the targeting syntax too — worth deciding here rather than discovering later.

@einari — the call I would like your view on is header (produces X for …) versus indented body (for … inside the block). I have argued for the body because it keeps one spelling of a composite key, but the header form reads better for the simple single-property case, which is most of them.