Repository navigation
feat: report sums over value-object members and derived measures - #563
Merged
Merged
Conversation
…ixing its units (FR-044 R12) A dimension's or aggregate measure's @Of may name Entity.field.member, a member of a value object stored with @storage: flattened. The report reads the member's own column (amount_amount, amount_currency). A report that sums, averages or takes the min or max of a numeric member must group by every non-numeric member of the same value object, so amounts in different currencies are never combined. jsonb members, unknown members and deeper paths are refused at load. The Cube exporter refuses member references. Loader rules and report-shape derivation in TypeScript, C#, Java and Python, with shared conformance fixtures for the positive case and each refusal.
…uped dimensions (FR-044 R13, TypeScript)
…es (FR-044 R13) Ports measure.derived (M11 @expr validation, R13 dimension operands, the nullable-decimal column type) to the C#, Java and Python loaders, so all four loader ports pass the shared derived and value-object fixtures. Also: - docs: reporting.md, the authoring skill references, the FR-044 spec (R11 amendment) and an FR-037 R5 note; CHANGELOG under Unreleased. - a measureDerived requirement, with the requirement harness regenerated. - fixture counts (490) in AGENTS.md and CONFORMANCE.md, the site payload and the site reference regenerated. - cube-members.ts: imports moved above valueObjectMemberError, so the eject scanner sees every import and the ejected cube template compiles. - Java: a measure whose @agg is outside the closed set no longer throws an NPE in the value-object unit check. - test typecheck fixes for the derived and value-object Cube tests.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Changed
@of(FR-044 R12). A dimension or measure@ofcan nameEntity.field.memberfor a value object stored with@storage: flattened, and the report reads that member's own column. Asum/avg/min/maxover a numeric member loads only when the report also groups by each non-numeric member of the same value object (its currency). Refused at load: jsonb value-object members, unknown members, and deeper paths. The Cube exporter refuses member paths. Loader and report-shape rules are implemented in TypeScript, C#, Java and Python, with conformance fixtures.measure.derivedwith@expr(FR-044 R13). A new measure subtype computesadd,subtract,multiplyordivideover two operands. Each operand is a numericmeasure.aggregateormeasure.ratioon the entity, a numeric attribute dimension the report lists, or a numeric literal.dividereturns null on a zero divisor.meta migratelowers it on Postgres, SQLite, MySQL and D1, and the Cube exporter writes it as anumbermember. Loader rule M11 and report rule R13 apply in every loader port, with a conformance fixture per refusal.meta initagent guide and themetaobjects-authoringskill now route grouped totals and dashboard reports toobject.reportbefore the@sqlescape. The reference docs, the metamodel docs fixtures and the CHANGELOG cover the new vocabulary.Vocabulary changes are additive.
metamodelVersionandexpected-registry.jsonare updated for the newmeasure.derivedsubtype.Validation
Reports this covers
A large-application smoke test wrote its dashboard reports in the reporting vocabulary and
fell back to a hand-written
@sqlview for five of them. This PR moves two onto the vocabulary,and a scratch copy of that app returns the same rows as the original
@sqlon Postgres and SQLite:Payment.amount.amount(a flattened Money) grouped byits currency member and by client, through the R12 member path.
through
measure.derived.Budget burn stays
@sqlin that app, because its budget is a jsonb value object and its cost ishours x rate (a product measure). Both are out of scope here. The other remaining
@sqlcases(a calendar-month spine with no facts, product measures, a member read out of a jsonb value
object) are unchanged.
Risk Assessment
✅ Low: The C#, Java and Python ports match the TypeScript reference: loader rules M10/M11, R12 and R13,
@ofmember resolution, andmeasure.derivedtyping. The fixtures and docs match the code. The only issue found is a misplaced doc comment.Testing
I drove the built
metaCLI against disposable projects outside the worktree.meta migratecreated the report views on SQLite and on a throwaway Postgres 16 container, and I seeded rows and queried the views. A third container, MySQL 8.4, ran the view SQL for the divide-parentheses fix. Sums over the flattened Money member, utilization, non-billable hours, billable share and budget burn all matched hand-calculated values. Four adversarial variants were refused by the loader. The fullscripts/ci-local.shrun (all ports, Testcontainers lanes, the gates lane, the cube live check and the mutation gate) exited 0. The configuredts-fast/ts-unitbaseline had already passed. I also ran the two targeted codegen test files, 16 tests, all passing. The change has no UI, so there are no screenshots. I stopped the Postgres and MySQL containers I started.ERR_INVALID_REPORT … would be combined. List an attribute dimension … Payment.amount.currencyERR_INVALID_MEASUREwith an actionable message(CAST(SUM…) - CAST(SUM…)) / NULLIF(…).scripts/ci-local.shacross all ports and gatesEXIT 0; 52 steps passed, none failedEvidence: SQLite view results, checked against the hand-computed oracle
Evidence: Postgres view results
Evidence: MySQL result for (170-100)/10, expected 7.0000
project_id all_hours billed_hours hours_gap_per_budget 1 170 100 7.0000Evidence: Full ci-local.sh run (exit 0)
Evidence: MySQL view SQL emitted for the fixed divide case
Pipeline
Updates from git push no-mistakes
✅ **Intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
server/typescript/packages/codegen-ts/src/projection/report-ddl-emit.ts:138- On MySQL, a deriveddivideloses its dividend's parentheses and returns a wrong value without any error.realOf()is a no-op on MySQL, so the code decides whether to parenthesise by testingreal.startsWith("CAST("). On MySQL an aggregate isCAST(SUM(x) AS SIGNED)when x is an int, long or currency field (castFor/INTEGRAL_SUM). So fordivide(subtract(revenue, refunds), budget), with revenue and refunds as sums of int, long or currency fields, the emitter writesCAST(SUM(a) AS SIGNED) - CAST(SUM(b) AS SIGNED) / NULLIF(c, 0). That computes a - b/c, not (a - b)/c.addfails the same way. So does a left operand that starts with a ratio whose numerator is cast, e.g.divide(add(ratio, x), y). Postgres and SQLite are not affected, because realOf always wraps the dividend in CAST there. The MySQL test (report-derived-measures.test.ts:79) covers only a dividend that is not cast,(m.weekly_capacity_hours * 52) / 12. Fix: decide by dialect, not by text prefix, e.g.const dividend = d === "mysql" ? derived(t.left, d, factRef, false) : realOf(derived(t.left, d, factRef), d);. Then add a MySQL test that divides a difference of two integral sums.CHANGELOG.md:14- The change registers new vocabulary:measure.derived, its@expr, and new descriptions inexpected-registry.json. ButmetamodelVersionstays at1.3, the value that 1.3.0 shipped with (released 2026-11-11, commit c75c30a; METAMODEL_VERSION = "1.3" in registry-manifest.ts:124). CHANGELOG.md says "If this ships after 1.3.0, the release movesmetamodelVersion", but 1.3.0 has already shipped, so the condition is already true. CLAUDE.md says "any change to the registered vocabulary is also a version edit".scripts/check-metamodel-version.mjscompares against the last release tag, so it should require a move to 1.4 once the v1.3.0 tag is present. This worktree has no v1.3.0 tag, which may be why the gate passes here. Choose one: bump now withnode scripts/check-metamodel-version.mjs --set 1.4and state the move in the [Unreleased] entry, or confirm that the bump is deliberately left for the release cut and reword the sentence.server/typescript/packages/metadata/src/core/reporting/report-describe.ts:123- AddingdescribeExprhad left the existing JSDoc ofdescribeMeasurestacked abovedescribeExpr's own one-line doc comment, so it documented the wrong function. I moved that JSDoc back abovedescribeMeasureand extended it to cover the derived-measure branch. Only comments changed.🔧 Fix applied.
📝 2 wording or comment-placement notes left for the author (no fix round spent):
server/typescript/packages/metadata/src/core/reporting/report-describe.ts:123- AddingdescribeExprhad left the existing JSDoc ofdescribeMeasurestacked abovedescribeExpr's own one-line doc comment, so it documented the wrong function. I moved that JSDoc back abovedescribeMeasureand extended it to cover the derived-measure branch. Only comments changed.server/csharp/MetaObjects/Loader/ValidationPasses.Reporting.cs:1107- The new XML-doc / Javadoc block for the R12 value-object-units check was inserted in the middle of the existing doc block ofCheckReportMeasure/checkReportMeasure. The R3 description ("R3 for one @measures item ... returns null") now sits stacked directly above the R12 doc and documents the wrong method, andCheckReportMeasure/checkReportMeasureitself is left with no doc. The TypeScript and Python ports placed the new helpers before the doc block correctly. Fix: move the R3 doc block down to sit directly aboveCheckReportMeasure/checkReportMeasure. Sites: server/csharp/MetaObjects/Loader/ValidationPasses.Reporting.cs:1107 (stacked above the R12 summary; method at :1202), server/java/metadata/src/main/java/com/metaobjects/loader/ReportingValidation.java:1192 (stacked above the R12 Javadoc; method at :1300). Comments only, no behavior change.✅ **Test** - passed
✅ No issues found.
ERR_INVALID_REPORT … would be combined. List an attribute dimension … Payment.amount.currencyERR_INVALID_MEASUREwith an actionable message(CAST(SUM…) - CAST(SUM…)) / NULLIF(…).scripts/ci-local.shacross all ports and gatesEXIT 0; 52 steps passed, none failedscripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchainsmeta migrate --from-db --db file:./t.db --dialect sqlite --slug init --applyon a disposable project built from thereporting-value-object-membersandreporting-derived-measuresfixtures, then queried the four views against hand-computed valuesmeta migrate --from-db --dialect postgres --applyagainst a throwaway postgres:16-alpine container, then queriedv_revenuebymonth,v_memberutilizationandv_projectburnFour adversarial metadata variants throughmeta migrate --dry-run: no currency dimension, unknown operand, derived-of-derived and a non-numeric literalMySQL: generated thev_hoursgapview SQL (deriveddivideover a difference of two integral sums) and ran it in a throwaway mysql:8.4 containerbun testonreport-derived-measures.test.tsandreport-value-object-members.test.tsin codegen-ts (16 pass)scripts/ci-local.sh(the full run, exit 0)Baseline already run:scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchains✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.
Validated in one no-mistakes run.