Merge pull request #26 from IntentFile/docs/declared-payload

docs(spec): a declared payload for an outward-facing message

Author: delchev

docs/reference.md

@@ -42,6 +42,7 @@ The quick lookup surface: one line and a minimal snippet per construct. For rule
 | [the notify block / `attach: print`](/spec/glue#the-notify-block-and-attach-print) | send a message about a record - with the record's own document attached - from a process step, a transition or a schedule |
 | [`schedules`](/spec/glue#schedules) | cron: notify or generate records per matching row |
 | [`integrations`](/spec/glue#integrations-outbound-http) | outbound HTTP on a data change |
+| [`integrations.payload`](/spec/glue#payload-the-declared-envelope) | the declared envelope a message carries, instead of the record as stored |
 | [`inbound`](/spec/glue#inbound-webhooks) | a webhook that creates records |
 | [`rollups`](/spec/glue#rollups-denormalised-parent-totals) | counts, sums, balance + status maintenance |
 | [`settlements`](/spec/glue#settlements-payment-allocation) | auto-allocation of payments across open invoices |

docs/spec/glue.md

@@ -206,6 +206,56 @@ integrations:
 
 The `@config:KEY` sugar resolves to a configuration lookup, so endpoints and secrets stay out of the source.
 
+### payload — the declared envelope
+
+Without a `payload`, the request body is the record as stored. That is only right when the receiver accepts the entity, and it has a cost even then: every column becomes part of a public contract, so adding a field silently changes what the outside world receives. A real integration contract is usually an *envelope* — a type, a version, an idempotency key, a timestamp, an identifier of the sender — which no arrangement of entity columns can produce.
+
+`payload` declares that envelope, key by key:
+
+```yaml
+integrations:
+  - name: requestUserAssignment
+    event: { onCreate: UserInvitation }
+    method: POST
+    url: "@config:ASSIGNMENT_URL"
+    payload:
+      type: "user.assignment.requested"     # literal
+      version: 1
+      messageId: "{uuid}"                   # minted per message
+      tenantId: "{tenant}"                  # execution context
+      appId: "@config:APP_ID"               # configuration
+      email: email                          # a field of the record
+      role: role.name                       # one hop off a to-one relation
+      requestedAt: "{now}"
+```
+
+The value forms are the ones [`notify`](#notifications) already resolves, deliberately borrowed rather than invented: a **literal**, a **direct field**, or a **one-hop `relation.field`** of a to-one relation, which the generated sender reads from the related record it loads once. `@config:KEY` reads the configuration, as it does in `url`.
+
+The **context tokens** are a closed set of four:
+
+| token | value |
+|---|---|
+| `{uuid}` | a fresh identifier, minted per message — the idempotency key a receiver deduplicates on |
+| `{now}` | the send time, as an ISO-8601 instant |
+| `{tenant}` | the tenant the send runs for |
+| `{user}` | the user behind the change that raised the event |
+
+::: info Normative
+A `payload` value MUST be one whole value in one of the declared forms. Interpolated text (`"Order {id} placed"`), a nested object and a list are NOT payload values and MUST be reported as authoring errors — a payload is a contract, not a template.
+
+A path MUST resolve at most one hop; `a.b.c` MUST be rejected.
+
+An unknown context token MUST be an authoring error, never an empty value in a sent message.
+
+A `payload` MUST be rejected on a method that carries no request body.
+
+Keys MUST be sent in the order they were declared.
+
+A bare word that names no field and no to-one relation of the record is a **literal** — the only way to carry a one-word constant. A value braced as `"{name}"` is a reference and MUST resolve.
+:::
+
+Three value forms and four tokens is the cap, and the cap is the point: it expresses a frozen contract without the construct becoming a transformation language. A payload that needs more than this is an algorithm, and belongs in a hand-written handler — the honest hand-off.
+
 ## inbound — webhooks
 
 Another system tells us — a webhook that ingests a JSON payload into an entity.