intent: allow a calculated action on a to-one relation (derive an FK server-side)

[delchev]

What

Lets a to-one relation declare calculatedActionOnCreate / calculatedActionOnUpdate, the counterpart of the field-level calculated action, so a relation's FK can be derived server-side instead of only fixed.

Why

init: covers the fixed case — a literal target seed id. Nothing covered "read it off another record", and the adjacent hooks all fall short by design:

hook	why it cannot do this
init:	a literal seed id, and it is the FK's database-level default — applied by the INSERT
dependsOn	a UI-only cascade; never fires on a server-side create
setRelationField	a BPMN step, and its parser requires value to be a literal integer id

The motivating case: a sales document's Currency defaulting from its company's base currency. Auto-settlement matches a payment to an invoice only on an exact currency equality, so a currency-less document can never settle itself — it sits unpaid next to the credit that should have cleared it.

The silent-drop half

Authoring the key on a relation looked like it should work and did nothing. IntentModel is bound by Gson (IntentParser.parse → GSON.fromJson), which ignores unknown properties, so calculatedActionOnCreate on a relations: line was discarded at parse time — no error, no warning, generate 200, code-gen 201, publish 200, and a default that never appears. That is the #6541 family one level up from seed rows; I have commented there arguing the ask generalises to any unknown intent key rather than another per-keyword guard.

How

• RelationIntent gains calculatedActionOnCreate / calculatedActionOnUpdate + isCalculated().
• New shared EdmIntentGenerator.putCalculatedAction emits isCalculatedProperty plus the action names, called from both relation builders — relationProperty (same-model) and crossModelRelationProperty. The motivating case is cross-model, so covering only the first would have passed unit tests and failed on the real model.
• IntentParser rejects the combination where there is no single FK to assign, or where the value is not the author's to set: a collection relation, a composition parent (preset by the layout), and an EntityStatus badge (owned by the workflow transitions — init: is its starting-value hook).

The DAO template needed no change, which is the part worth knowing: a relation is already an ordinary property in the .model — the FK column, typed to the target's key — so the template's shared property loop and its actionAssign macro emit

entity.<Relation> = Beans.get(<Action>.class).calculate(entity);

against the Integer FK with no new branch. The gap was engine-only, so adopting this needs a jar swap and no registry re-seed.

Verification

Unit: EdmIntentGeneratorTest.relationCalculatedActionEmitsTheServerSideCallOutOnBothRelationBuilders asserts the three emitted keys on both builders and that an action-less relation stays unmarked. IntentParserTest asserts the key binds onto the model — deliberately a typed-mapping test, since that binding is the regression guard for the silent drop — and that a collection relation is rejected. Full engine-intent suite: 406 green.

Runtime, against a locally built instance carrying this change, driving a real six-document consumer:

• all six generated repositories emit the Beans.get(...).calculate(entity) assignment;
• client-Java batch 871 units / 902 class files, no failures;
• REST creates omitting the currency returned it derived from the company on all five document types plus payments;
• an explicitly posted currency was respected, not overwritten;
• end to end: an ISSUED invoice and a payment created with no currency at all auto-allocated and flipped the invoice to PAID.

Not included — an IntentEmissionCoverageIT case

engine-intent/CLAUDE.md asks every new keyword to extend that gate, and I have not done so; it is recorded as owed in the commit message and in engine-intent/CLAUDE.md. The reason is concrete rather than an oversight: that fixture carries no calculated action of either kind today, so adding one means introducing the first compilable custom/ class into the emission-test project — and a generated repository referencing a missing class fails the whole client-Java batch, taking every REST assertion in that gate with it. I could not run that gate locally to confirm, and guessing at a smoke gate seemed worse than a documented gap. Happy to add it if you can point me at the intended shape for a custom/ fixture there.

Docs

engine-intent/CLAUDE.md and intent-assistant-guide.md both updated, including when to reach for this over init: / dependsOn / setRelationField, and the rule that the action should return the current value unchanged when one is already set so a user's explicit pick always wins.

🤖 Generated with Claude Code