examples: where the 42k lines of application code go, and the four building blocks that would remove most of it

[Yaraslaut]

What the seven ladder rungs actually write, measured, so that the framework can
be given the building blocks that remove most of it. Tests are excluded —
this is only the code needed to run an application.

Where the 42,473 lines go

rung         src+include   gui_lib      qml     total
pastebin            1806       608      274      2688
polls               2479      1075      730      4284
bookmarks           4037      1280      680      5997
kanban              5492      2664     1607      9763
ledger              6103      1810      553      8466
lims                4283      1059      599      5941
crm                 5334         0        0      5334
TOTAL              29534      8496     4443     42473

Repeated shapes, counted across all seven:

   140  execute() overloads             185  BRIDGE_REGISTER_* sites
   153  validate() definitions          160  journal / log calls
   130  action.validate() call sites    117  transaction sites
   105  role and permission checks       17  error-class definitions
   276  throw sites of those errors      22  *_qml_bridge files
    26  presenter files

---

1. Validation — 153 written, 1 derived

Classifying the 103 validate() bodies short enough to capture as one
expression:

	count
vacuous — return true	29	validates nothing
pure required-ness — !x.empty(), id.hasValue(), n > 0	63	restates the schema
genuine business rules	11	4 of which are !name.empty() && name.size() <= kMax…

89% either do nothing or restate something already computed.
schemaJson<A>() derives required from the action type — a member is
required unless it is std::optional — so those 63 bodies re-state by hand
what the framework computes from the same type in the same process. Four of the
remaining eleven are length bounds, i.e. minLength/maxLength, so the
irreducible set is nearer seven.

The helper already exists and is documented. include/morph/forms/forms.hpp:114
gives it in its own example:

[[nodiscard]] bool validate() const { return morph::forms::allRequiredEngaged(*this); }

Across 153 definitions, one action calls it. So this is not a missing
primitive — it is an undiscoverable one, and that has a far cheaper fix than a
new API. Rule that in or out first.

2. The QML bridge — 8,496 lines of hand-written type erasure

22 *_qml_bridge files and 26 presenters across six rungs. kanban's board
bridge alone is 1,389 lines. What they do is mechanical: turn typed model
results into QVariantMap / QVariantList properties, and typed calls into
Q_INVOKABLEs.

The clearest evidence that it is mechanical — this exact signature is
hand-written seven times, once per rung:

Q_INVOKABLE void submitIfValid(const QString& actionType, const QString& bodyJson);

An action name and a JSON body. That is precisely the erased form the wire
layer already speaks, and schemaJson<A>() already describes the payload. Six
rungs then hand-convert results back into QVariant containers — 189 mentions
across the six.

This is the largest single block in the corpus, and the least
application-specific.

3. Error hierarchies — the same 2–4 types, seven times

pastebin    PastebinError : runtime_error     ValidationError : PastebinError
polls       PollsError : runtime_error        ValidationError : PollsError
bookmarks   BookmarksError : runtime_error    ValidationError : BookmarksError
kanban      KanbanError : runtime_error       ValidationError : KanbanError
ledger      LedgerError : runtime_error       ValidationError, VersionConflict, EmptyPrincipalError
lims        LimsError : runtime_error         ValidationError, EmptyPrincipalError
crm         CrmError : runtime_error          ValidationError, EmptyPrincipalError

17 definitions, 276 throw sites. Every rung reinvents "validation failed",
"not found", "forbidden", "conflict" — the same four outcomes a framework
mediating GUI and backend has to transport anyway. EmptyPrincipalError
appears independently in three.

Note the constraint this must respect: invariant 3 — the value type reports
the fact, the layer decides the policy. A shared error vocabulary is a
transport concern; what a rung does about a conflict stays the rung's.

4. The handler frame — ~1,000 lines of identical opening and closing

Nearly every one of the 140 execute() overloads is: principal check →
validate() with a hand-written throw → DataMapper → transaction → mutate →
commit → journal → return. At roughly seven lines of frame that is ~1,000
lines whose shape is identical across seven independently written rungs.

Two parts of it are already tracked and must not be re-litigated here:

• the post-commit half — a throw after the commit reporting a durable
  success as a failure — is morph#789, confirmed in three rungs;
• IReplayLedger was already promoted for exactly this reason, after five
  rungs hand-wrote the same idempotency table.

What is untracked is the opening: auth, validate, throw. That is where the
29 vacuous validate() bodies live, and it is narrower than "a handler seam".

---

A measured negative, worth recording

Field-by-field copying is not the problem. The row.x = action.x and
.x = y shuttling between DTOs, records and results is 514 lines of 29,534 —
about 1.7%. I expected it to dominate. An auto-mapping or auto-DTO primitive
would solve a problem this corpus does not have, and building one would be
effort spent against a measurement nobody took.

Priority, by size and by how application-specific the work is

1. The QML bridge (8,496 lines) — largest, least application-specific,
   and the erased form already exists in the wire layer.
2. Validation (153 sites) — smallest change, possibly just discoverability.
3. Error vocabulary (17 definitions, 276 throws) — mechanical, but
   constrained by invariant 3.
4. The handler opening (~1,000 lines) — after morph#789 settles, since
   they touch the same function.

Verification status

Measured on f0176034, over
examples/{pastebin,polls,bookmarks,kanban,ledger,lims,crm}, excluding every
tests/ directory. Every count above is a grep over that corpus and is
reproducible.

Not verified:

• The 50 validate() bodies too long to capture as one expression were not
  classified. If they skew toward genuine rules the 89% falls; if vacuous, it
  rises. The figure is of single-expression bodies and is not projected onto
  all 153.
• That a generic QML bridge is feasible. The rungs' bridges also carry
  offline queue depth, dead-letter counts, sync status and per-rung
  Q_PROPERTY sets. How much survives generalisation is unmeasured, and the
  8,496 figure is the whole layer, not the removable part.
• That the error hierarchies can be shared without violating invariant 3.
• Whether any rung depends on validate() being called for a side effect.

What must not happen

• Do not delete validate(). Seven bodies carry real rules. The target is
  that an action with no rules of its own writes nothing — not that the hook
  disappears.
• Do not build the DTO mapper. See the measured negative.
• Do not fold morph#789 into this. Same function, different defect.

What would change the verdict

Close as fixed when a new rung of comparable scope can be written in materially
fewer lines, measured the same way — that is the only number that settles
whether the building blocks landed.

Re-open, or re-scope, if classifying the 50 long validate() bodies moves the
89% enough to change the priority order above.

[Yaraslaut]

Triage: valid, area: core + area: forms — and the one caveat that could have weakened it is now closed

Disclosure: I filed this. Triaging it meant testing the weakest thing in it —
"the 50 validate() bodies too long to capture as one expression were not
classified. If they skew toward genuine rules the 89% falls."

Measured: only 12 of the 153 bodies span more than one line. So the
unclassified remainder cannot carry the weight that caveat allowed for. The
rest were single-expression bodies my capture regex missed on signature
variation alone — it required noexcept, and bodies declared const without
it (return accountId > 0 && amountMinor > 0) fell out.

The frequency distribution, which is the clearest statement of the finding:

  28  return true;
   8  return id.hasValue();
   4  return !name.empty();
   4  return accountId.hasValue();
   3  return quoteId.hasValue();
   3  return projectId.hasValue();
   3  return opportunityId.hasValue();
   2  return versionId.hasValue();
   2  return savedViewId.hasValue();
   2  return !reason.empty();
   2  return accountId > 0 && amountMinor > 0;
   2  return !participantName.empty() && participantName.size() <= kMax…
   2  return !bound.has_value() || bound->validate();

The single most common body in the entire corpus is return true, 28
times. The next nine are single-predicate required-ness. That is the issue's
thesis, visible without interpretation.

One line in that table is a finding the issue missed

return !bound.has_value() || bound->validate();

Two actions hand-write recursive delegation into a nested aggregate's own
validation. That is not a business rule — it is the traversal a schema-driven
validator would do for free, written by hand because nothing does it. Worth
carrying into whatever lands, because it is the case that proves required-ness
alone is not the whole job: the framework would need to recurse, and two
authors already discovered that.

On priority order

The issue ranks the QML bridge first by size (8,496 lines) and validation
second. I would keep that order but note the asymmetry it does not state:
validation may cost nothing to fix. If allRequiredEngaged is merely
undiscoverable, the fix is documentation plus possibly a default, against 8,496
lines of bridge whose removable fraction is explicitly unmeasured.

So: settle the discoverability question first because it is cheap, not because
it is biggest. The issue's own step 1 already says this; I am agreeing with it
against its own priority list.

What stays unverified, and should not be quietly dropped

• Whether a generic QML bridge is feasible. The bridges also carry offline
  queue depth, dead-letter counts, sync status and per-rung Q_PROPERTY sets.
  8,496 is the whole layer, not the removable part, and nobody has separated
  them.
• Whether the error hierarchies can be shared without violating invariant
  3 — the value type reports the fact, the layer decides the policy.
• Whether any rung relies on validate() being called for a side effect.

The close condition is the right one and should not be softened

"A new rung of comparable scope written in materially fewer lines, measured
the same way." Every other measure here — lines removed, sites collapsed — can
be satisfied by moving code around. That one cannot.

[Yaraslaut]

Correction: two of this issue's numbers were wrong, and the priority order changes

Both errors are mine and both inflated the case. Measured on f0176034, all of
examples/ excluding every tests/ directory.

1. Everything was counted raw, including comments

area        raw     code   comment+blank
src       16650    11031        33%
include   19011     7783        59%
gui_lib    8496     3611        57%
qml        5546     3856        30%
          -----    -----
total     49703    26281        47%

Application code is ~26,000 lines, not the 42,473 this issue opens with.
Forty-seven per cent of the raw count is comments and blank lines, and
include/ — the DTO and action headers — is 59% non-code. The framework's
own comment cleanup is landing across these trees now, so even this will move.

2. The QML bridge is 3,611 code lines, not 8,496

That was the headline claim — "the largest single block" — and it was 57%
comments. Classifying the 8,496 raw lines:

comments                           3808   44%
blank                              1077   12%
includes and guards                 553    6%
lone braces and semicolons          428    5%
QVariant / QString conversion       343    4%
Qt macros (PROPERTY/INVOKABLE/…)    185    2%
emit …Changed                       107    1%
everything else                    1995   23%

The mechanically generable part — the Qt macros, the QVariant
conversion, the change signals — is about 635 lines, plus an unknown share
of the 1,995. So the bridge remains the largest single target, but the prize is
hundreds of lines, not thousands, and the issue's framing of it as
eight-and-a-half thousand was wrong.

3. The handler frame was an estimate, and it was nearly double

This issue said "roughly seven lines of frame … ~1,000 lines". That was
arithmetic, not a measurement. Measured across 136 execute() overloads by
counting the lines that match the frame shape — principal check, validate(),
the throw, DataMapper, transaction, commit, journal call:

handlers measured   136
total body lines   5280
frame lines         568   (10%)
mean body          38.8 lines
mean frame          4.2 lines

568 lines, not ~1,000. Mean frame is 4.2 lines per handler, not 7. Ninety
per cent of a handler body is its own work.

Revised priority

The order in the issue body was set by the inflated numbers. On code-only
counts:

1. The QML bridge — still largest, ~635 clearly mechanical lines of 3,611.
   The removable share of the remaining 1,995 is the open question, and it is
   the one measurement that would settle whether this is worth a seam.
2. Validation — 153 sites, but possibly zero cost to fix if
   allRequiredEngaged is merely undiscoverable. Cheapest first regardless of
   size.
3. Error vocabulary — 17 definitions, 276 throw sites. Unchanged.
4. The handler frame — 568 lines, demoted. At 4.2 lines per handler
   this is the smallest of the four, and it is not worth a public-contract
   change on its own. Its post-commit half stays where it belongs.

What this does not change

The shape findings all survive: return true is still the most common
validate() body in the corpus at 28 occurrences; submitIfValid(const QString&, const QString&) is still hand-written seven times; seven rungs still
define the same error hierarchy; and field-copying is still a measured negative
at 514 lines.

What changed is the size of the prize, and I should have measured code rather
than lines before ranking by it.

[Yaraslaut]

Step 1 answered: allRequiredEngaged is neither missing nor undiscoverable — it answers a narrower question than 64 of the 103 bodies ask

The issue's hypothesis was "this is not a missing primitive — it is an
undiscoverable one, and that has a far cheaper fix than a new API. Rule that
in or out first." Ruled out. Discoverability is not what is stopping the
rungs. Capability is.

Verification status

Measured and reproduced on f0176034. Linux, clang 22.1.8, glaze v7.4.0
(the pinned FetchContent version). Two artefacts: a script that parses every
single-expression validate() body out of the seven rungs and classifies it
against what the helper can see, and a probe program compiled and run against
the real include/morph/forms/forms.hpp.

Not verified: the 50 long bodies the issue already flags as unclassified —
I classified the same 103 single-expression bodies it did, and my total
matches its 103 exactly, which is the cross-check that the two parsers agree.
Nothing here says anything about the other 50.

1. Why nobody uses it — the four candidates, tested

• "Newer than most of the rungs." Ruled out. allRequiredEngaged is
  present at f0d54f6f (2026-07-19, the sub-domain folder reorg) and earlier
  through the rename; the first ladder file lands at 2026-08-15 (ladder: shared infrastructure, docs, and framework prerequisites (rung 0) #88). Four
  weeks earlier than rung 0.
• "Documented only inside a long file nobody reads end to end." Ruled
  out. It is named in five places, one of which is the file a rung author is
  actually given: examples/IMPLEMENTATION.md:142 — "Every action declares
  validate() (via allRequiredEngaged + domain checks)". Also
  README.md:306, docs/ARCHITECTURE.md, docs/spec/core/registry.md:304,
  and docs/spec/forms/forms.md's own section. An author following the
  instructions was pointed straight at it.
• "The rungs' authors were following a different example." Partly, but
  downstream of the real cause — see below.
• "It does not handle a case the rungs need." Confirmed, and it is the
  answer.

2. Does it do what the required-ness bodies do?

Not for most of them. allRequiredEngaged inspects a member only when that
member satisfies EmptyCapableField — i.e. exposes a noexcept hasValue().
Measured, compiled against the real header:

EmptyCapableField<std::string>        = 0
EmptyCapableField<std::int64_t>       = 0
EmptyCapableField<std::vector<int>>   = 0
EmptyCapableField<std::optional<int>> = 0
EmptyCapableField<LedgerId>           = 1     // the rungs' strong-id shape

So !name.empty() — the second commonest predicate in the corpus — is
structurally invisible to it. Against a trimmed ledger::OpenAccount:

[empty id, empty name]   handWritten=0   allRequiredEngaged=0
[id set,   empty name]   handWritten=0   allRequiredEngaged=1   <-- disagree
[id set,   name set  ]   handWritten=1   allRequiredEngaged=1

All 103 single-expression bodies, classified by whether the helper can reach
them:

bucket	count	can allRequiredEngaged express it?
return true, and the action has no empty-capable member at all	29	it would also return true — no gain
body tests exactly the action's required empty-capable members	39	yes, exact drop-in
body rests on std::string::empty() (alone, or &&-ed with an id)	26	no
other predicates (name.size() <= kMax…, isValidYearMonth, >= 0, != 0)	8	no
already calls the helper	1	—

Two things fall out of that table that change the issue's framing:

1. The 29 vacuous bodies are not an accident of authorship. Every one of
   them is on an action with zero empty-capable members — GetBoardState,
   ListTags, ExportBookmarks. Writing allRequiredEngaged(*this) there
   produces return true by a longer route. The helper does not shrink the
   "89% do nothing" figure at all; it addresses a different slice.
2. 39 are exact drop-ins, with zero behaviour change. Not one body was
   found checking fewer ids than its action carries (the classifier tests
   set equality, and the hasValue_partial bucket came back empty), so
   swapping them is a pure deletion, not a tightening. ledger::LinkAccountToCategory
   is the clean example: {AccountId, CategoryId} and
   return accountId.hasValue() && categoryId.hasValue();.

So the ceiling on "just use the existing helper" is 39 of 153, not 63.

3. Recursion — it does not, and this understates the gap

allRequiredEngaged calls detail::forEachNamedMember(action, ...) once over
glz::reflect<A>::keys and inspects each member in place. There is no second
level. Measured, not inferred:

[optional<Bound> engaged, its required id empty]
    hand-written `!b.has_value() || b->validate()` = 0
    allRequiredEngaged                             = 1

[Bound by value + vector<Bound>, their required ids empty]
    allRequiredEngaged                             = 1

A std::optional<Sub> member is skipped because std::optional has
has_value(), not hasValue(); a Sub held by value and a
std::vector<Sub> are skipped for the same reason. So the two actions that
hand-write return !bound.has_value() || bound->validate(); are doing
something the helper cannot do at any depth, and no amount of adopting it
would remove them.

This is documented correctly and in detail in
docs/spec/forms/forms.md's "allRequiredEngaged<A>() — readiness check",
which spells out both the mechanism and the non-recursion. Two rungs found it
the hard way and wrote it down locally
(examples/crm/include/crm/dto/quote_dto.hpp:63,
examples/lims/include/lims/dto/result_dto.hpp:246 — the latter says
"Deliberately not allRequiredEngaged").

What changed, and what did not

PR #795 adds the two limits to the @par Readiness helper block in
forms.hpp and to the function's own Doxygen — the place the issue points at,
forms.hpp:114, sits thirty lines below a heading reading "Nested
aggregates (recursive, cycle-safe)", which is about schemaJson<A>() and
reads as though it covered the helper too. Comment-only; the spec was already
right and is untouched.

No API was designed. Whether required-ness should extend to a
"non-empty string" notion (a NonEmpty<std::string> in the palette, or a
requiredNonEmpty field-metadata key) reaches 26 more bodies and is a
public-contract decision, not a lane's.

What would change the verdict

• Close the "undiscoverable" framing as answered. The 39 exact drop-ins are a
  mechanical examples/ change worth roughly 39 lines, and they are the whole
  of what adopting the existing helper buys.
• Re-open the capability question if someone wants the other 64: that needs a
  new declaration, not a new doc.