feat(intent): a declarative fileName pattern names both server-side renders (#6899)

[delchev]

Fixes #6899.

The problem

The two server-side PDF renders named their files with hardcoded, mutually inconsistent expressions:

• snapshot mint — "<Entity> <id> v<n>.pdf", i.e. the numeric primary key, even though the mint runs after the number: stamp, so the document number was right there;
• mail attachment (attach: print) — the first number: field with an id fallback.

So one document reached the archive and the customer's inbox under two different names, and neither was configurable. A real archive wants a self-describing name: ORD0000042_20260822_MyCompany_AcmeLtd.pdf.

The change

A fileName: pattern on the function: Snapshot child and inside a notify block (with attach: only — a plain-text message has no file to name). Literal text plus {token} interpolations; no expression language.

- name: SalesInvoiceCopy
  function: Snapshot
  fileName: "{number}_{date:yyyyMMdd}_{company.shortName|company.name}"

Token	Renders
{field}	a field of the rendered record
{relation.field}	a field of a one-hop to-one relation
{field:pattern}	a date/timestamp through a DateTimeFormatter pattern
{A|B}	the first non-blank operand, left to right
{Version}	the copy's version — a snapshot only

Tokens use the authored field/relation names, exactly as a notify subject does (the issue's PascalCase sketch is illustrative; the contract it names — "the same as notify interpolation" — is what shipped, so an author does not have to learn a second casing rule).

New FileNameSupport translates a pattern once into a Java expression plus the one-hop relation loads it reads. The new SDK helper sdk.print.FileNames sanitizes every interpolated value at run time: trim, whitespace → one _, path/control characters (/ \ : * ? " < > |) stripped, repeats collapsed. Non-ASCII is deliberately kept — a local-language document legitimately carries a non-Latin name, and keeping names Latin is an application data convention, not the platform's guess. The literal separators between tokens are the author's and are emitted verbatim.

Three things worth a reviewer's attention:

1. The pattern's relation loads are merged into the notify block's own, deduped by local. Both name the local after the relation, so declaring it twice would not compile — and this is what lets a name read a relation the message text never mentions (SendBill in the IT does exactly that: a literal recipient, {Person.name} in the file name).
2. attach: recordPrint refuses a relation hop. That document is rendered once, in renderDocument(source) before the per-row loop, where the block's relation locals do not exist. Same one-field rule the record. scope already has, and rejected at parse rather than emitted as a read of an undeclared local.
3. The Snapshot delegate now always loads its master (the name is a property of the document, not of the copy) and returns early when it is gone — previously it only loaded it under languageFrom.

Called-out behaviour change: absent a pattern, the snapshot default changes from the primary-key form to the same number-or-id expression the mail uses, plus the version. That is the point — the two finally agree. Already-stored copies are untouched.

Rejected at parse/generation, never rendered empty: an unknown field/relation, a multi-hop path, unbalanced or nested braces, a format on a non-date field, a format DateTimeFormatter won't accept, a pattern that interpolates nothing, and {Version} on a mailed copy. A silently-dropped token would produce archive names nobody can tell apart, which is the failure being replaced.

Tests

• FileNamesTest (12) — the run-time sanitizer: whitespace, path/control characters, a stripped character not leaving a separator run, non-ASCII kept, both date shapes, a non-date value degrading, and first(...).
• FileNameIntentTest (16) — every rejection above plus the accepted full pattern on both sides.
• GlueFileNameTest (9) — the emitted expressions, the version-suffix rules, the merged/deduped loads, and both defaults asserted as exact strings, agreeing with each other.
• IntentEngineIT (58 green) — OrderCopy gains fileName: "{orderDate:yyyyMMdd}_{customer.name}"; asserts the load off the document, the SDK date call, the hop read, the version suffix, and that the old primary-key name is gone.
• IntentEmissionCoverageIT (green) — SendBill gains fileName: "BILL_{note|Person.name}". That project's client-Java compile is the compile proof for the emitted expression (an undeclared local fails the whole batch and takes every REST assertion with it).

Verified: formatter:validate clean, mvn -P release javadoc clean on api-modules-java + engine-intent, 852 + 28 + 77 unit tests green, both ITs green headless.

Docs

• In-repo: the engine-intent guide bullet, the root CLAUDE.md paragraph, and the intent assistant guide (a new "naming a rendered document" section + the snapshot/notify knob mentions).
• dirigible.io: docs(intent): naming a rendered document with fileName dirigible-io/dirigible-io.github.io#213 (merging).
• Spec: proposal: naming a rendered document (fileName) IntentFile/intent-specification#50 (proposal) + docs: naming a rendered document (fileName) IntentFile/intentfile.github.io#40 (site page), both left open for the maintainer.

🤖 Generated with Claude Code