docs: mapping on arrival - accept, map and business-key lookups

[iliyan-velichkov]

Mirrors IntentFile/intent-specification#42 (proposal 0021-arrival-mapping) onto the site: docs/spec/glue.md under the inbound chapter, plus its docs/reference.md row.

Hold this until the proposal is released into a version — it describes pending meaning. Opened alongside so the two do not drift, which is the same order the outbound and relative-moment pages followed.

What it documents

An arrival may declare how its payload is read. Ingesting the arriving JSON as the entity is only expressible when the sender's payload already is the entity, field for field, and a real arrival contract is an envelope:

inbound:
  - name: userAssignments
    source: { queue: "user-assignment-requests" }
    accept: { type: user.assignment.requested, version: 1 }
    create: TenantUserAssignment
    map:
      messageId: messageId
      tenant:    { lookup: Tenant, by: tenantId, from: tenantId }

Both keys are optional and valid on any of the three arrivals, because they describe the payload rather than the transport; declaring neither behaves exactly as the chapter already specifies.

Editorial choices worth checking

• Each rule carries its reason, because each one is a refusal rather than a feature: a non-unique by is refused (a lookup that could match several records would have to pick one, and picking silently is worse than failing); a lookup matching nothing rejects the arrival (a record with an unresolved reference cannot be traced back to the party that asked for it); a gate miss is acknowledged and ignored rather than failed (redelivery cannot change the outcome).
• The by rule and the reject rule share one ::: warning rather than getting a container each — they are one decision read from two ends.
• The normative text sits in a single ::: info Normative container, matching the chapter's existing style, and is the proposal's specification text verbatim so a release can fold in both without rewriting either.
• What stays out is stated — a general transformation language — so the cap reads as deliberate rather than unfinished.
• Site style followed: one heading level shallower than the specification, containers instead of blockquotes. npm run docs:build is clean and the reference.md link resolves to the generated anchor (#accept-and-map-when-the-payload-is-an-envelope), which I checked against the built HTML rather than assuming.

Proven in the reference implementation first: eclipse-dirigible/dirigible#6769 (PR).

[iliyan-velichkov]

Closing as premature — this documents pending meaning, and the site tracks the released specification.

The construct is proposed in IntentFile/intent-specification#42 (proposals/0021-arrival-mapping.md), which is still a draft: accept / map / lookup are not in 1.5, so a site page for them would describe something no version specifies yet.

Nothing is lost by closing this. Proposal 0021 already carries the exact specification prose and its Appendix A row inline, under its ## Specification text and ## DSL index headings — by design, so that "a release copies this in; it does not rewrite it". Whoever cuts the next version has the text to hand.

For the record, the ordering this PR got wrong: the site pages for the 1.5 constructs were merged after the version cut, as part of the release sweep (spec 1.5 released 11:10, the outbound site page merged 11:21, the catch-up merged 11:28 — all on 2026-08-18), not ahead of it.

Reference implementation, for when the release does come: eclipse-dirigible/dirigible#6769 (PR).