Read models without a declarative projection: reducers and computed views are undeclarable

[woksin]

Summary

The projection sub-language (PDL) is the only way a document can define a read model, and it is declarative-only. Two read-model shapes that Arc supports as first-class citizens therefore cannot be described:

1. Reducers — read models folded from events by code (IReducerFor<T>). The fold logic legitimately lives in code; but the document cannot even say "this read model is reduced from these events by this file", the way reactor, constraint, and command handler already pair a declarative header with a file reference.
2. Computed read models — models with no event feed at all, composed by querying over other read models. They surface in the document only as query return types, with no definition anywhere.

Evidence (real application)

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

• 9 × SP0020 [Warning] '<X>Reducer' folds events into '<X>' with code, which Screenplay has no counterpart for, so only the events it observes are stated (e.g. CustomerCandidateReportReducer, CustomerRequestWorkspaceReducer). The emission masquerades as a mapping-less projection — a reader cannot tell a reducer from an underspecified projection.
• 13 read models in the source are computed/query-only (compose over other read models) — they have no definition in the document at all.

Suggested direction

1. A reducer construct symmetric with the existing code-carrying constructs:

reducer CustomerCandidateReport => CustomerCandidateReport
  on RequestCandidatePresented
  on RequestCandidateWon
  file CustomerPortal/Report/Report.cs

(observed events are declarative and validator-checkable; the fold stays in code, exactly like a reactor's handler.)

2. For computed read models, at minimum a declaration that names the model and the read models it composes over (readmodel X from Y, Z + file), so the document introduces every type its queries return.

Context

Found while validating a generated 5,348-line document from a production Arc application against its source. Related: #29 (complex value types), #30 (one projection per slice).

[woksin]

Alignment note: per the declarative-first principle (#40), the constructs proposed here should not require a file reference — the declarative parts (observed events, composed-over read models) must stand alone as a valid pre-code description, with file/inline code as optional realization metadata attached once the fold logic exists.

[woksin]

Verified

Re-verified against main. SliceParser dispatches event, command, query, projection, capture, reactor, screen, constraint and specification — there is no reducer construct and no read-model declaration. A read model exists in a document only as the right-hand side of projection X => Y and as the return type of a query; both are bare strings that nothing resolves.

The word readmodel is already a token, but only as a reference inside the specification sub-language — SpecificationParser matches ^given\s+readmodel\s+([A-Z]\w*)$ and ^then\s+readmodel\s+…. So the language can already assert about a read model in a scenario while having no way to declare one. That asymmetry is the shape of this issue.

Your alignment note is right and, as of #40, now binding: neither construct may require a file.

Design alternatives

1. Two constructs — reducer and readmodel.

reducer CustomerCandidateReport => CustomerCandidateReport
  on RequestCandidatePresented
  on RequestCandidateWon
  file CustomerPortal/Report/Report.cs

readmodel CustomerWorkSurface from CustomerCandidateReport, RequestWorkspace

reducer is symmetric with reactor as it now stands after #34/#40: a header, a list of on triggers, and an optional realization. Same parser shape, same printer shape, same event resolution, and the events it observes are checkable immediately. readmodel names a computed model and what it composes over.

Cost: three constructs (projection, reducer, readmodel) that all ultimately answer "where does this read model come from", and a reader has to know which is which.

2. One construct — readmodel as the declarable entity, with the build strategy inside it.

readmodel CustomerCandidateReport
  reduced from
    on RequestCandidatePresented
    on RequestCandidateWon
    file CustomerPortal/Report/Report.cs

readmodel CustomerWorkSurface
  composed from CustomerCandidateReport, RequestWorkspace

readmodel InvoiceList
  projection
    from InvoiceRegistered
      ...

One declaration for "a read model exists and is called this", with how it is built as a body. This is the shape I would push hardest on, because of what it fixes beyond this issue: it gives the document one declarable entity that every other construct resolves against — projection X => Y, a query's return type, data <ReadModel> via query … on a screen, given readmodel X in a specification, and reads <ReadModel> if #35 lands. Today every one of those is an unresolvable bare string.

Cost: it is a real migration. Existing projection X => Y declarations would either become sugar for readmodel Y / projection … or stay as-is with the read model implicitly declared by the => — and "implicitly declared" is the kind of rule that is easy to write down and hard to reason about later.

3. reducer only; leave computed read models alone.

Cheapest, and it fixes the case with hard evidence (9 reducers emitted as mapping-less projections, indistinguishable from underspecified ones). Computed models stay undeclarable, so a document still returns types it never introduces.

Recommendation

Land alternative 1 now, shaped so it can become alternative 2 later:

• reducer <Name> => <ReadModel> with on <Event> triggers and an optional file/inline block. It is the same body shape reactor now has, so it costs almost nothing to build and nothing to learn.
• readmodel <Name> from <A>, <B> for computed models, file optional.

That closes the evidence in this issue and introduces readmodel as a word that declares rather than only references — which is the foot in the door for alternative 2.

Then, separately, the bigger question, and it is the one I would actually like decided: should readmodel become the general declarable entity that projections, queries, reads (#35) and screens all resolve against? Right now the document has no answer to "what read models exist", which is why #28 cannot resolve a screen's data target, #35 has nothing to key a reads against, and a query's return type is unverifiable. Every one of those issues is paying for the same missing declaration.

If the answer is yes, I would not migrate projection X => Y — I would let it keep declaring its read model implicitly, and have readmodel be the explicit form for the models nothing projects into. One rule: a read model is declared by whatever builds it, or by a bare readmodel declaration when nothing does.

Sequencing

This is the keystone of the declarable-name group. Suggested order:

1. No way to declare complex value types (child records) - generated documents reference shapes they cannot define #29 (type for child records) and this issue's declarations — both add things that can be declared.
2. One symbol table in ScreenplayValidator replacing the two flat hash sets, resolving every declared name kind.
3. Define reference scoping and qualified references for screen data/action/navigate targets #28 (scoping and qualified references) on top of it.
4. command: declare read-model dependencies (DCB reads) and state-fed produces mappings #35 (reads), which needs read models to be resolvable.

@einari — the question worth your time is not reducer's syntax, which is straightforward, but whether readmodel becomes the general declarable entity. Four open issues are currently blocked on the document having no answer to "what read models exist"; deciding that once would unblock all of them.