@klok-integration/cli 0.7.302 → 0.7.309

package/assets/agents/knowledge/glossary.md

@@ -15,7 +15,10 @@ it as the source does.
 | Tenant | An organisation on the platform, and its security boundary; every topic, ODL object and GitLab group belongs to one tenant |
 | Domain | A business area inside a tenant. `common` is shared by the tenant's domains, `public` is open to anyone |
 | Route, route id | One Camel route per Java class (except a `KlokRestApi`, one per operation, and a `KlokRuntimeInstanceRoute`, one per instance `<RouteId>#<instanceKey>`). Its id is `<TENANTSHORT><NNN><LEG><seq>_<Description>`, for example `KLK007T1_PublishKlokStandard`; the class name is the id |
-| Leg | The letter in a route id: I ingress (onramp, brings data in), P processing, E egress (offramp, delivers data out), A API, S sub route, T timer |
+| Leg | The letter in a route id: I ingress, P processing, E egress, A API, S sub route, T timer |
+| Ingress, egress | An ingress is a route that takes a message from outside the platform onto the broker; an egress takes a message off the broker to the outside. An ingress is an onramp or a channel adapter, an egress an offramp or a channel adapter. As a word for a service (`klok-postmark-ingress`) it says what the service is, never a permission |
+| Onramp, offramp | An onramp is an ingress with mapping: the system's own format (class X) becomes a platform model (class A, B or C) before it reaches the broker. An offramp is an egress that maps a platform model to the receiving system's format at the last moment |
+| Channel adapter | An ingress or egress that only converts the protocol (HTTP to the broker, the broker to SFTP); the payload stays as it was received. Good design when it is motivated, for example receiving with minimal handling so that no call is lost while a later leg maps; a system's format put on the broker without such a reason is an anti-pattern |
 | Tenant short name | `TENANTSHORT`, three upper case letters that start every solution and route id of a tenant: the first three consonants of the tenant's name (`KLK` for klok, `DGR` for degerfors), decided by the platform |
 | Solution | The business flow a set of routes implements; its id is the route id's prefix, for example `KLK007`. The id is allocated once, by a merge request in the tenant's `integration-solutions` registry, and never reused; a solution is reserved, active or retired |
 | Solution document | The `README.md` of a solution in the tenant's `integration-solutions` registry: its services, legs and flows, kept true to what is built |

package/assets/agents/knowledge/platform-rules.md

@@ -12,9 +12,20 @@ documentation or the dependency catalog can give you.
   possible by hand in GitLab.
 * Systems talk to the broker, never to each other. Point-to-point calls, a shared database or a shared file system
   between systems are not a Klok design.
-* Transform at the edge. When data from one system is to reach other systems or domains, the ingress transforms
-  it from the system's format to a class C or B model, and the egress transforms it to the receiving system's
+* Ingress and egress are the routes that take messages from outside onto the broker and off the broker to the
+  outside. An ingress is an **onramp** (with mapping: system format X to a platform model A, B or C) or a
+  **channel adapter** (protocol conversion only, the payload stays as received); an egress is an offramp or a sink
+  channel adapter.
+* Transform at the edge. When data from one system is to reach other systems or domains, the onramp transforms
+  it from the system's format to a class C or B model, and the offramp transforms it to the receiving system's
   format at the last moment. Replacing a system then changes only its own ingress and egress.
+* A channel adapter that puts a system's format on the broker is good design when it is motivated: you receive
+  with as little handling as possible so that no call from the system is lost, the message waits safely on the
+  topic (it can be processed again, or wait for a receiving system that is down), and a later processing leg or
+  egress maps it. The solution document says why, which leg maps, and that no other system or domain reads the X
+  topic. Example: Postmark inbound mail in KLK006, received by a channel adapter in `klok-postmark-ingress` so that a support mail never bounces while a product is redeployed. Letting class X onto the broker carelessly and without such a
+  reason is an anti-pattern and breaks Klok best practice; ask of every ingress "onramp or channel adapter, and
+  why?" (https://docs.klok.dev/klok-integration-strategy-and-tactics/platform-2-0/ingress-and-egress/).
 * Prefer fact events (the whole object) over notifications (an id only).
 * Hierarchy: tenant (the security boundary; every topic, ODL object and GitLab group belongs to one), then domain
   (a business area inside the tenant). Domain `common` is shared by the tenant's domains, `public` is open to
@@ -45,7 +56,8 @@ documentation or the dependency catalog can give you.
   * out of the platform: `KlokOfframpRoute`, `KlokOfframpRouteSync` (serves requests from the broker),
     `KlokOfframpRouteWithResult`;
   * on the broker: `KlokProcessingRoute`, `KlokSchemaUpgradeBridge` / `KlokSchemaDowngradeBridge`;
-  * protocol only, same payload: `KlokChannelAdapterSourceRoute` / `KlokChannelAdapterSinkRoute`;
+  * protocol only, the payload as received (a channel adapter, see the principles): `KlokChannelAdapterSourceRoute`
+    / `KlokChannelAdapterSinkRoute`;
   * APIs: `KlokRestApi` with one `KlokRestApiHandlerRoute` per operation; a SOAP API is a `KlokCustomRoute` with
     camel-cxf; long-running work is a `KlokAsyncTaskWorkerRoute` behind a 202 with a task reference;
   * everything else: `KlokCustomRoute`; reusable pieces: `KlokSubRoute`, `KlokEnrichSubRoute`.

package/assets/agents/knowledge/roles/integration-architect.md

@@ -86,7 +86,10 @@ Into the platform:
 * A webhook sender: `KlokWebhookOnrampRoute`.
 * The caller needs a full business reply now: `KlokOnrampRouteSync`. Call it coupling and debt, with an aggressive
   timeout.
-* Same payload, protocol only: `KlokChannelAdapterSourceRoute`.
+* Same payload, protocol only: `KlokChannelAdapterSourceRoute`. Either the payload already is the model its readers
+  need, or receiving with minimal handling is the point (no call may be lost, the message must wait on the topic
+  for a receiver that is down) and a later leg maps. Write the reason in the solution document; a system's format
+  let onto the broker without one is the anti-pattern.
 
 Out of the platform:
 
@@ -176,6 +179,13 @@ synchronous bridge, a timeout of about ten seconds, `[TACTICAL]` on the solution
 the target is down. The strategy-aligned alternative: `KlokOnrampRoute` answering 202 with a task reference, and the
 front end polling or listening on a websocket. If they keep the bridge, write down the debt and the unwind condition.
 
+**Postmark inbound mail for five products.** A support mail must not bounce because QuickRace is redeployed or
+down for a day of planned upgrade. Ingress: a channel adapter per account in
+`klok-postmark-ingress` (KLK006): receive the webhook, put the payload on a topic unchanged, answer Postmark once
+the broker has it. An egress per product delivers each message to the right inbox and maps there. The solution
+document names the reason and the mapping leg; no other domain reads the Postmark topic. That is a motivated
+channel adapter, not `[TACTICAL]`.
+
 **"The offramp can just read the CRM database for the e-mail field."** Reject: that couples the offramp to CRM's
 schema. CRM publishes customer facts; if the e-mail is missing, extend the fact event or add an enricher in
 processing against a master data API on the platform. No SQL credential crosses a domain boundary.

package/assets/agents/knowledge/roles/integration-developer.md

@@ -30,7 +30,9 @@ Walk it from the top; do not pick a base class from habit.
        (the egress then owns retries, dead letters and alerts);
      * a webhook: `KlokWebhookOnrampRoute`;
      * the caller needs a full business reply now: `KlokOnrampRouteSync`, hard coupling, use rarely;
-     * the payload already is the model the readers need, protocol only: `KlokChannelAdapterSourceRoute`.
+     * protocol only, the payload as received: `KlokChannelAdapterSourceRoute`, when the payload already is the
+       model the readers need, or when receiving with minimal handling is the motivated design and a later leg
+       maps (see *Channel adapters and APIs*).
    * Out of the platform:
      * transform into the target's format: `KlokOfframpRoute`;
      * same format: `KlokChannelAdapterSinkRoute`;
@@ -175,8 +177,12 @@ its own `retry.*`, `dlq.*` or `failure.*` keys; configure its caller.
 
 ## Channel adapters and APIs
 
-A channel adapter is a dumb pipe: the same payload over another protocol, only `fromUri()` and `toUri()`. As soon as
-a field is mapped it is an onramp or an offramp.
+A channel adapter only converts the protocol: the same payload over another protocol, only `fromUri()` and
+`toUri()`. As soon as a field is mapped it is an onramp or an offramp. Use a source channel adapter for a system's
+own format only for a reason the solution document states: you must accept every call without losing a message, so
+the route does as little as possible, the message waits on the topic, and a processing leg or the egress maps it
+later (Postmark inbound mail in KLK006). A system's format on the broker without that reason, read by other domains,
+is the anti-pattern the refusals below describe.
 
 `KlokRestApi` declares its operations in `get()`, `post()`, `put()` and `delete()`, one `KlokRestApiHandlerRoute`
 per operation; an operation's route id is `<ApiRouteId>.<verb><path>`. Errors are answered as JSON

package/assets/agents/skills/klok-route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: klok-route
-description: Write or change a Camel route on the Klok Quarkus extension 2.0 (onramp, processing, offramp, REST API handler, async task worker, custom route) with the correct naming, topics and topic purpose, configuration, error handling, tests and klok-docs. Use for any change inside a Klok integration project.
+description: Write or change a Camel route on the Klok Quarkus extension 2.0 (onramp, channel adapter, processing, offramp, REST API handler, async task worker, custom route) with the correct naming, topics and topic purpose, configuration, error handling, tests and klok-docs. Use for any change inside a Klok integration project.
 ---
 
 # Writing a Klok route
@@ -13,8 +13,12 @@ motivates.
 
 ## Steps
 
-1. **Pick the pattern.** Ingress from a system: `KlokOnrampRoute<SYS, DOM>`; transformation between datamodels:
-   `KlokProcessingRoute<IN, OUT>`; egress to a system: `KlokOfframpRoute<DOM, SYS>`; synchronous request/reply:
+1. **Pick the pattern.** Ingress from a system: an onramp, `KlokOnrampRoute<SYS, DOM>`, which maps; or a channel
+   adapter, `KlokChannelAdapterSourceRoute<MODEL>`, which only converts the protocol, when receiving with minimal
+   handling is the motivated design and a later leg maps (the solution document says why; a system's own format
+   let onto the broker without a reason is an anti-pattern,
+   https://docs.klok.dev/klok-integration-strategy-and-tactics/platform-2-0/ingress-and-egress/); transformation
+   between datamodels: `KlokProcessingRoute<IN, OUT>`; egress to a system: `KlokOfframpRoute<DOM, SYS>`; synchronous request/reply:
    the `Sync` variants; REST: `KlokRestApi` plus one `KlokRestApiHandlerRoute` per operation; long running work:
    `KlokAsyncTaskWorkerRoute<REQ, RES>`; anything else: `KlokCustomRoute`.
 2. **Name it.** `<TENANTSHORT><NNN><LEG><seq>_<Description>`, one class per route. `<TENANTSHORT><NNN>` is the id of

package/assets/agents/skills/klok-solution/SKILL.md

@@ -45,7 +45,8 @@ shared platform service) in `klok/integration-solutions`.
 6. **Classify every service** the solution needs: *new project*, *new routes in an existing project*, *reused,
    slight change*, *reused as is*, *client change*. Name the repository of each.
 7. **Map the legs.** For every route: id (`<TENANTSHORT><NNN><LEG><seq>_<Description>`, leg and sequence not used
-   before — `klok solutions check` reports duplicates), project, pattern base class, topics with their purpose,
+   before — `klok solutions check` reports duplicates), project, pattern base class (for an ingress: onramp or
+   channel adapter, and why — a channel adapter needs its reason and the leg that maps), topics with their purpose,
    datamodels and their class, task types, configuration keys, and how the legs interact (diagrams in the flows
    section). Route configuration and details stay in the project's `klok-docs/`; the solution links there.
 8. **Choose the technology deliberately.**