feat(metamodel): @of is optional on @agg:collect — the whole-object rollup (#335)

[dmealing]

Closes #335.

The gap

A projection could roll related rows up into an array of one column, and had no way to roll them up into an array of objects. origin.aggregate @agg: collect required @of, so "every supplier's {id, name} for this product" was inexpressible — the shape had to be a second round-trip, or a hand-written view, which is unmanaged and invisible to meta verify --db. When origin.collection retired in 0.24.0 this became the one coverage gap the retirement guide had to state rather than close.

What lands

@of becomes OPTIONAL on collect, and omitting it means a whole-object rollup. The carrying field.object @isArray @objectRef collects each related row as its declared value object.

{ "field.object": {
    "name": "supplierBriefs", "isArray": true, "@objectRef": "SupplierBrief",
    "children": [
      { "origin.aggregate": { "@agg": "collect", "@via": "Product.suppliers" } }
    ]
}}

• The declared value object IS the exposure. Members bind to the @via terminal entity's fields by name; a field the entity has but the value object omits is simply not projected. That carries the Prelude to #210: retire redundant payload origin-typing (Kotlin, Python) and close Java's KNOWN_GAPS entry as moot #270 guarantee (a curated value object must not silently become the full entity) down to the DDL tier. Name matching rather than extends is deliberate — it keeps one value object collectable from two different entities. The convention is written into the byte-gated origin.aggregate registry prose so no port has to infer it from TypeScript.
• Eight load errors, in all five ports — carrying field must be a field.object declaring @objectRef; that @objectRef must name an object.value; @via is required; the path must be to-many; @distinct is refused; @orderBy keys must resolve against the @via terminal entity; every value-object member must match a terminal field; and a matched member must agree on both type axes (subtype and array-ness).
• A new error code, ERR_COLLECT_WHOLE_OBJECT, for the five refusals that would otherwise have shared ERR_INVALID_ORIGIN. Not taxonomy for its own sake: the shared corpus compares error code + source and never message text, and ERR_INVALID_ORIGIN is exactly what a loader that still requires @of emits for this same metadata — so five of the eight negative fixtures passed against three ports containing none of the rules. Proven: the unported ports went 4 → 9 failures once the code was distinct.
• View lowering, both dialects. Postgres emits COALESCE(jsonb_agg(jsonb_build_object(...) ORDER BY <pk> ASC) FILTER (WHERE <pk> IS NOT NULL), '[]'::jsonb) — jsonb not json, because PG's json type has neither an equality nor an ordering operator.

Half B — array filter/sort validation

Two commits (9a09724, 1de6601) give @sortable the subtype validation @filterable already had, and stop an array field claiming a filter-operator band.

This makes previously-loading metadata fail to load, so it is breaking on the metadata contract — but it is the previously-wrong-acceptance ruling this release already invokes twice (#342, and before that the 0.19.1 @min clamp and the 0.21.6 like case-sensitivity fix): such a declaration emitted a like/eq rule against a text[] column, i.e. SQL that cannot execute. It was never validly expressible. Bounds, stated rather than hoped:

1. In-repo cost is zero — a structural per-field-node scan of 1321 JSON and 124 YAML files found no field carrying both isArray: true and @filterable/@sortable: true.
2. What breaks was already broken — a runtime failure becomes a load failure.
3. Nothing ever taught adopters to write it — never documented, never exemplified, never emitted by any generator.

Residual exposure is not zero and the changelog says so: an adopter who wrote the form independently auto-adopts a load error, because pre-1.0 ^0.24.x resolves it.

Two findings the real-engine round-trip paid for

Both were invisible to emitted-SQL text, and only the emit → apply → introspect → re-diff gate could see them:

1. The SQLite emitter was wrong and the unit test agreed with it. On SQLite 3.44.0 the in-aggregate ORDER BY destroys the JSON subtype, so the column returned an array of quoted strings while the generated type declared an array of objects. The obvious json(json_object(...)) wrapper does not survive the ORDER BY (seven variants probed). Fix: build the ordered array, then re-wrap element-by-element through json_each, which iterates in array order — ordering survives and json(value) restores the subtype. Dropping ORDER BY was rejected (an author's @orderBy would silently do nothing); a correlated ordered subquery also works but loses multi-hop @via.
2. A field.long member arrives inside the rollup as a JSON number while the same value as a top-level BIGINT arrives from node-postgres as a string. Inherent to JSON, lossy above 2^53. Pinned with a comment rather than normalised away.

Verification

scripts/ci-local.sh on this exact tree (merge-base bcef4d9c8), every lane read from its trailing OK — line, never piped:

Lane	Result
--quick	PASSED — 16/16, incl. leak-scan, #337's shipped-doc-examples gate, metamodel-version bump, peer-range bounds, TS conformance, ts unit suites, completeness-gate (mutation, killed 787), doc-template + embedded-library drift
--only ts-slow	PASSED — migrate-ts real-PG, runtime-ts real-PG dialect matrix, integration-tests (ts): persistence conformance 229 pass / 0 fail
--only java	PASSED — conformance java + kotlin, java-reactor, integration-tests java + kotlin
--only csharp	PASSED — conformance csharp, integration-tests csharp 118/118
--only python	PASSED

• Zero golden churn attributable to this branch: git diff origin/main -- server/typescript/packages/codegen-ts/test/golden/ is empty.
• metamodelVersion moves 0.11 → 0.12. 0.11 is index @expr is unreachable: @fields is required on both index.lookup and identity.secondary, and @fields+@expr silently drops the fields #342's sole claimant per the rule [0.24.1] states; this branch complying with that rule is why it moves.

Coordination

The 0.24.1 release cut owns the merge — landing this is part of that cut, not a separate action.

🤖 Generated with Claude Code

https://claude.ai/code/session_015WgNA6uDN9qxu2nA471rAq