proposal: mapping on arrival - a business key becomes a relation, and a gate ignores what is not understood

[iliyan-velichkov]

Adds proposals/0021-arrival-mapping.md. Touches nothing under versions/, per the proposal-first rule.

This is the half #30 named and left for its own proposal: the same problem 0017 solved for messages leaving, read in the other direction.

The gap

An inbound entry ingests the arriving JSON as the entity, which is only expressible when the sender's payload already is the entity, field for field. A real arrival contract is an envelope:

{ "messageId": "9f9d1c9e-...", "type": "user.assignment.requested", "version": 1,
  "tenantId": "acme", "email": "new.user@example.com", "role": "User" }

So an application can declare its entity, its deduplication, its process trigger and its arrival, and still need custom code purely because a relation arrives as a name instead of a reference. That is the outcome worth avoiding: the construct looks like it covers the case, and the hand-off is discovered when the first payload lands.

What it proposes

Two optional keys, valid on every arrival, because they describe the payload rather than the transport:

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

Omitting them keeps today's meaning exactly, so no existing file changes.

The three rules worth arguing about

Each is in the proposal with its reasoning, because each is a refusal:

• by: must identify at most one record (a field declared unique, or the entity's key). A lookup that could match several would have to pick one, and picking silently is a worse outcome than failing — so it is refused when the file is read, not when two rows first collide.
• A lookup matching nothing rejects the arrival. A record stored with an unresolved reference cannot be traced back to the party that asked for it, and is indistinguishable from one that never named a party.
• A gate miss is acknowledged and ignored, not failed. Redelivery cannot change the outcome of a message this receiver structurally does not understand, and failing it fills the sender's retry path with something identical every time.

The proposal also states what stays out: a general transformation language. Three value forms and one lookup shape cover the contracts people actually have; more than that moves the arrival out of the model into a second program written in a worse language, and the honest answer there is a hand-written handler over the same write path.

Implementation

Proven in the reference implementation before proposing: eclipse-dirigible/dirigible#6769 (PR), including the runtime evidence that a business key really becomes the stored reference, that a non-matching envelope is ignored with a warning, and that an unresolvable one is rejected rather than stored half-resolved.