intent: a checks kind for two relations of a junction row that must agree on a shared target (#7409)

[delchev]

The gap

A junction/allocation entity links two records that both point at the same third thing - the same Customer, the same Currency, the same Company, the same Employee. No checks: kind could say "these two relations must agree on X": compare relates two values of ONE row, and requiredWhen/forbidWhen relate a child to its OWN parent. Nothing compared two DIFFERENT relations' targets.

So a EUR CustomerPayment was allocated against a USD SalesInvoice (200 OK), and customer B's payment against customer A's invoice (200 OK). The probe found the same shape in 7 more places across 6 modules - PurchaseInvoicePayment, StockTransfer, EmployeeTimesheet, EmployeeProjectAssignment, Payslip, VacationDay - every one closed by a hand-written calculatedActionOnCreate/OnUpdate guard class whose entire content was a rule the intent should be able to state.

The change

checks:
  - { kind: agree, relations: [SalesInvoice, CustomerPayment], onProperty: Customer,
      message: "This payment belongs to a different customer than the invoice" }
  - { kind: agree, relations: [SalesInvoice, CustomerPayment], onProperty: Currency,
      message: "The payment's currency does not match the invoice's" }

• relations: names exactly two distinct to-one relations of the entity; onProperty: the property BOTH their targets declare - one of their to-ones (compared by its foreign key: the same customer, the same currency) or a scalar field an equality is exact on.
• Each side is ONE PATH - <relation>.<onProperty> through the same ResolvePathSupport walker every other path in the DSL uses, sharing ONE walker so each related record is loaded exactly once and a cross-model target resolves through its uses: owner like any other hop.
• Enforced in the generated validate() of all three surfaces' controllers (EntityController, EntityMyController, EntityPartnerController) with 400 and the authored message - the same place exactlyOne and an ungated compare refuse - so it takes no status: gate.
• whenNull: defaults to skip (a row not yet carrying both values has nothing to disagree about, and requiredness is the relation's own declaration); refuse rejects the write instead.
• A check with no authored message still says what disagreed - only the declaration knows.

One deviation from the proposal: the key is onProperty, not on

YAML 1.1 resolves a bare on key to the boolean true, so an on: Customer declaration arrives as the key true, binds to nothing, and would generate a check with no property to agree on - the trap lifecycle: already documents. Since the issue proposes on:, authors and the assistant will write it, so that spelling is refused by name on the raw tree (rejectCheckOn) pointing at onProperty, rather than dropped silently.

Refused at parse

Each because the declaration could not otherwise mean anything: not exactly two relations; the same relation twice (it always agrees with itself); a relation or an onProperty a target does not declare (the walker's own message, so a cross-model target reads); a status: gate; an unknown whenNull; a terminal an equality is not exact on (a decimal, a double, a date - the same line a when condition draws); and two terminals of DIFFERENT declared types, where the boxed comparison is silently always false.

An entity declaring no agree check generates byte-identically.

Verified

• IntentParserTest.agreeChecksParseAndValidate - the shape and every refusal above, incl. the on: spelling.
• EdmIntentGeneratorTest.agreeChecksEmitBothSidesAndTheirLoads - both expressions, both labels, the shared walker loading each side once, and the derived message.
• IntentEmissionCoverageIT - a junction entity added to the fixture carrying BOTH whenNull readings; the generated controller is compiled and asserted to load each side by FK and refuse a disagreement. Run green locally (Tests run: 1, Failures: 0, Errors: 0, 330 s).
• Full unit suites of engine-intent (1317) and ide-template (169) green; mvn formatter:validate green with the cache wiped; -P release javadoc build green on both modules.

Not verified: no browser-level check - an agree refusal surfaces through the same 400 path every other row check already uses, and no UI half is emitted.

Follow-ups outside this PR, per the issue: the intent-assistant guide is updated here, the IntentFile spec proposal follows now that the shape is agreed, and R13 can turn from WAITING-UPSTREAM into a real FINDING.

Fixes #7409

🤖 Generated with Claude Code