orbit-code-ai 0.1.20 → 0.1.23

package/_agent_reference/components/error-handling.md

@@ -1,117 +1,178 @@
 # Error Handling
 
-Central error handling is provided by `ErrorHandler.subflow` + `ErrorHandler.esql`. Every flow MUST wire its exception terminal to the error handler.
+Central error handling is provided by `ErrorHandler.subflow` (+ `ErrorHandler.esql`, ~43 KB). Every flow wires its node **failure/catch terminals** to the matching `ErrorHandler` input terminal. The handler classifies the error, logs it for audit, and builds a standardized ESB response.
 
 ---
 
-## ErrorHandler.subflow
+## Two error channels
+
+There are two distinct mechanisms — don't confuse them:
+
+1. **Business errors** (validation, expected error codes) — set the code yourself and let the
+   business-error path build the response:
+   ```esql
+   SET Environment.Variables.MWResponse.status = '<error_code>';   -- e.g. an ESB_ERROR_CODES value
+   ```
+   `ESBBusinessErrorResponse` reads `Environment.Variables.MWResponse.status` (defaulting to
+   `'99999999'`) and calls `CreateEsbXMLResponseHeaderFromRoot(...)` to emit the response header.
+   Do **not** `THROW USER EXCEPTION` for business validation.
+
+2. **Technical exceptions** — wire the node's **failure** terminal to `ErrorHandler`. The exception
+   list is parsed, logged, and turned into a fault/response. The handler distinguishes the error
+   class via `Environment.Variables.esb.errorType`, set by the small `ErrorHandler_Handle*` compute
+   modules (one per input terminal):
+
+   | Input terminal | Handler module | `esb.errorType` set |
+   |---|---|---|
+   | `Failure` (`WSFailure`) | `ErrorHandler_HandleFailure` | `Failure` |
+   | `Fault` (`WSFault`) | `ErrorHandler_HandleFault` | `Fault` |
+   | `ValidationFailure` | `ErrorHandler_HandleValidationFailure` | `ValidationFailure` |
+   | `FileFailure` | `ErrorHandler_HandleFileFailure` | `FileFailure` |
+   | `MQInputFailure` | `ErrorHandler_HandleMQInputFailure` | `MQInputFailure` |
+   | `MQInputCatch` | `ErrorHandler_HandleMQInputCatch` | `MQInputCatch` (sets `EXCEPTION_CAUGHT`) |
+   | `FileInputCatch` | `ErrorHandler_HandleFileInputCatch` | `FileInputCatch` (sets `EXCEPTION_CAUGHT`) |
+
+   `ErrorHandler_CreateGeniricRs` then builds the response from `esb.errorType` + the active backend
+   adapter flag (below).
 
-**Purpose**: Catches all exceptions, builds a standardized error response, logs it, and routes to dead-letter or returns a business error.
+---
+
+## ErrorHandler.subflow terminals
+
+Wire to the input terminal that matches the failing node:
 
-**Internal flow**:
 ```
-Exception caught
-    ↓
-ErrorHandler.esql (build error structure)
-    ↓
-ErrorHandler_IsExceptionCaught.esql (filter: already handled?)
-    ↓
-LogError subflow (audit the error)
-    ↓
-[Route based on adapter type]
-    ├── MQ_Dead_Output_Node (async flows)
-    └── MWBusinessErrorResponse (sync/HTTP flows)
+InTerminal.Input              -- generic
+InTerminal.ValidationFailure  / InTerminal.FileValidationFailure
+InTerminal.WSFailure          / InTerminal.WSFault
+InTerminal.MQInputFailure     / InTerminal.MQInputCatch
+InTerminal.FileFailure        / InTerminal.FileInputCatch
+InTerminal.SystemDown
+InTerminal.httphandlefail     / InTerminal.httphandlefault
+        ↓
+OutTerminal.Output
 ```
 
-**ESQL modules**:
-| Module | Purpose |
-|---|---|
-| `ErrorHandler.esql` | Main: 43KB — builds error structure, maps error codes per backend |
-| `ErrorPoint.esql` | Create error message structure from exception |
-| `ErrorHandler_IsExceptionCaught.esql` | Filter: prevent double-handling |
-| `ErrorHandler_SetExceptionCaught.esql` | Mark exception as handled |
-| `ErrorHandler_IsFileSchemaValidationOccured.esql` | Detect file schema validation errors |
-| `ErrorHandler_PrepareFileDataForAudit.esql` | Prepare file error data for audit |
-| `ESBBusinessErrorResponse.esql` | Build ESB-standard business error response |
+Internally it routes through:
+- `LogError.subflow` — audit-logs the error (uses `ErrorPoint` to build the error/audit record).
+- `MWBusinessErrorResponse.subflow` — emits the synchronous ESB error response to the caller.
+- `MQ_Dynamic_Output_Node.subflow` — async/dead routing.
+- `ErrorHandler_IsAtomicService` (FILTER, gated by `IsAtomic EXTERNAL BOOLEAN`).
 
 ---
 
-## MWBusinessErrorResponse.subflow
+## ESQL modules
 
-**Purpose**: Returns a structured business error response to the caller (used in sync/HTTP flows).
+| Module | Type | Purpose |
+|---|---|---|
+| `ErrorHandler.esql` › `ErrorHandler_CreateGeniricRs` | COMPUTE | Builds the error response from `esb.errorType` + backend flag |
+| `ErrorHandler.esql` › `ErrorHandler_Handle*` | COMPUTE | Tag `esb.errorType` per terminal (table above) |
+| `ErrorHandler.esql` › `ErrorHandler_IsAtomicService` | FILTER | Routes atomic vs non-atomic (`IsAtomic`) |
+| `ErrorHandler_IsExceptionCaught.esql` | FILTER | Returns the `EXCEPTION_CAUGHT` SHARED flag (prevent double-handling) |
+| `ErrorHandler_SetExceptionCaught.esql` | COMPUTE | Resets `EXCEPTION_CAUGHT = FALSE` |
+| `ErrorHandler_IsFileSchemaValidationOccured.esql` | — | Detect file schema-validation errors |
+| `ErrorHandler_PrepareFileDataForAudit.esql` | COMPUTE | Prepare file error data for audit |
+| `ErrorPoint.esql` › `ErrorPoint_PrepareErrorMsg` | COMPUTE | Build the error/audit record (see below) |
+| `ESBBusinessErrorResponse.esql` › `ESBBusinessErrorResponse_handleRs` | COMPUTE | Business-error response from `MWResponse.status` |
+
+`EXCEPTION_CAUGHT` is a `SHARED BOOLEAN` set by the `*Catch` handlers; `ErrorHandler_IsExceptionCaught`
+reads it and `ErrorHandler_SetExceptionCaught` clears it, so an MQ/File input catch isn't processed twice.
 
-**When to use**: REST/HTTP flows where the caller expects a JSON error response.
+---
 
-**Response structure**:
-```xml
-<ResponseStatus>
-  <Code>XXXXXXXX</Code>
-  <Status>Error</Status>
-  <EnglishMsg>Human readable message</EnglishMsg>
-</ResponseStatus>
-```
+## Backend adapter flags
 
----
+Which backend produced the error is selected by an `EXTERNAL BOOLEAN` flag, set `TRUE` at the
+node/BAR level for the adapter in use (all default `FALSE`). `ErrorHandler_CreateGeniricRs` branches
+on these:
 
-## Error Codes by Backend System
+```esql
+DECLARE IsFrotEndAdapter        EXTERNAL BOOLEAN FALSE;  -- front-end SOAP fault
+DECLARE IsFrontEndJSONAdapter   EXTERNAL BOOLEAN FALSE;  -- front-end JSON fault
+DECLARE IsT24Adapter            EXTERNAL BOOLEAN FALSE;
+DECLARE IsT24OFENQAdapter       EXTERNAL BOOLEAN FALSE;
+DECLARE IsODMWSAdapter          EXTERNAL BOOLEAN FALSE;
+DECLARE IsNICAdapter            EXTERNAL BOOLEAN FALSE;
+DECLARE IsNIWSAdapter           EXTERNAL BOOLEAN FALSE;
+DECLARE IsMEPSWSAdapter         EXTERNAL BOOLEAN FALSE;
+DECLARE IsICBSWSAdapter         EXTERNAL BOOLEAN FALSE;
+DECLARE IsA2AWSAdapter          EXTERNAL BOOLEAN FALSE;
+DECLARE IsACHWSAdapter          EXTERNAL BOOLEAN FALSE;
+DECLARE IsUnifonicAdapter       EXTERNAL BOOLEAN FALSE;
+DECLARE IsMLSDWSAdapter         EXTERNAL BOOLEAN FALSE;
+DECLARE IsCapptionsWSAdapter    EXTERNAL BOOLEAN FALSE;
+DECLARE IsHyperpayWSAdapter     EXTERNAL BOOLEAN FALSE;
+DECLARE IsAtomic                EXTERNAL BOOLEAN TRUE;
+```
 
-Defined as constants in `CommonUtils.esql`:
+For each backend, the response code is taken from properties with a hardcoded fallback, using four
+severities gated by an availability check:
 
-| Constant | Value | Backend |
-|---|---|---|
-| `ESB_SUCCESS_RESPONSE_CODE` | `'00000000'` | All |
-| `ESB_RUNTIME_TECHNICAL_ERROR_CODE` | `'99999999'` | All (generic) |
-| `ESB_MIDDLEWARE_DATABASE_ERROR_RESPONSE_CODE` | `'E0199998'` | DB errors |
+```
+Environment.Properties.<Adapter>.<Flow>.Variables.IsSystemAvailable      -- false → SystemDown code
+Environment.Properties.<Adapter>.<Flow>.Variables.<BE>SystemDownErrorCode -- e.g. 'ODM99996'
+Environment.Properties.<Adapter>.<Flow>.Variables.<BE>FailureErrorCode    -- esb.errorType='Failure'
+Environment.Properties.<Adapter>.<Flow>.Variables.<BE>FaultErrorCode      -- esb.errorType='Fault'
+Environment.Properties.<Adapter>.<Flow>.Variables.<BE>TechnicalErrorCode  -- else
+```
 
-Additional backend-specific codes exist for:
-- **T24**: Core banking errors
-- **NIWS**: National Information and Workflow System
-- **ODM**: Operational Decision Manager
-- **Unifonic**: SMS/notification service
-- **MLSD**: Ministry of Labor and Social Development
-- **ICBS**: Core banking system
+Backend code prefixes seen in defaults: T24 (`Create_esbXML_Response_Header_Using_Backend_Code('T24'…)`),
+`ODM999xx`, `UNI999xx`, `NIC999xx`, `MLSD999x`, `CAPP999x`, `HYPP00xx`, `NI9999xx`, `MEPS999x`,
+`ICBS999x`, `A2A999x`, `ACH999x`. SOAP-fault backends map via `..._Using_Backend_Code('<BE>WS', code, …)`
+against `ESB_ERROR_CODES`. When `Header.DebugFlag = '1'`, the raw backend error + parsed exception
+text are surfaced under `Header.BackendError.ErrorCode` / `.ErrorDescription`.
 
-Read `ErrorHandler.esql` directly for the full mapping if you need specific codes.
+The response itself is built with the CommonUtils procedures `Create_esbXML_Response_Header`,
+`Create_esbXML_Response_Header_Using_Backend_Code`, and `CreateEsbXMLResponseHeaderFromRoot`, setting
+`Header.ResponseStatus.{Status='Error', Code, EnglishMsg, ArabicMsg}`. Front-end adapters instead emit
+a SOAP/JSON fault (`GenerateSOAPFault` / `GenerateJSONFault`) with HTTP reply status `500`.
 
 ---
 
-## Wiring the Error Handler in a New Flow
+## Error codes
 
-Every node that can fail must connect its **failure/exception terminal** to `ErrorHandler`:
+ESB codes are `EXTERNAL CHARACTER` constants in `CommonUtils.esql` (see [common-utils](common-utils.md)):
+`ESB_SUCCESS_RESPONSE_CODE` `'00000000'`, `ESB_RUNTIME_TECHNICAL_ERROR_CODE` `'99999999'`,
+`ESB_MIDDLEWARE_RUNTIME_ERROR_RESPONSE_CODE` `'99999999'`, `ESB_MIDDLEWARE_DATABASE_ERROR_RESPONSE_CODE`
+`'E0199998'`, plus channel codes `'E9009999'`/`'55555555'`/`'44444444'` and `'E5500003'`. Localized
+descriptions come from `dbo.ESB_ERROR_CODES` via `getEsbErrorCodeDescriptionFrom` /
+`getEsbChannlsErrorCodeDescriptionFrom` / `getBackendEsb_MapErrorCode`. Per-backend default codes live
+in the adapter's properties (above), not in CommonUtils.
 
-```
-[Any Node]
-    │ failure terminal
-    ↓
-ErrorHandler.subflow
-    │
-    ├──[MQ flow]──→ MQ_Dead_Output_Node
-    └──[HTTP flow]─→ MWBusinessErrorResponse
-```
+---
 
-**ESQL DECLARE for ErrorHandler behavior**:
-```esql
--- Set which backend adapter this flow uses (controls error code mapping)
-DECLARE IsT24Adapter        EXTERNAL BOOLEAN FALSE;
-DECLARE IsODMWSAdapter      EXTERNAL BOOLEAN FALSE;
-DECLARE IsFrontEndJSONAdapter EXTERNAL BOOLEAN FALSE;
-DECLARE IsNIWSAdapter       EXTERNAL BOOLEAN FALSE;
-DECLARE IsUniFonicAdapter   EXTERNAL BOOLEAN FALSE;
-DECLARE IsMLSDAdapter       EXTERNAL BOOLEAN FALSE;
-DECLARE IsICBSAdapter       EXTERNAL BOOLEAN FALSE;
-```
+## ErrorPoint (error/audit record)
 
-Set the appropriate flag to `TRUE` at the node level to get correct error codes for that backend.
+`ErrorPoint_PrepareErrorMsg` is the **internal** module the error/audit path uses — it is not a
+user-set API. It builds `OutputRoot.XMLNSC.Error` with:
+
+- `errorName` = `'Error in Application: ' || ApplicationLabel || ' in Message Flow: ' || MessageFlowLabel`
+- `errorMessage` = parsed exception text (via `PARSEExceptionList`), or the raw bitstream when no exception list
+- `auditHeader` = requestId, timestamp, applicationName, messageFlowName, brokerName, executionGroupName,
+  logType `'Error'`, channelId, userName, serviceCode, sessionId, channelReqTime, requestMessage
+
+It falls back to `Environment.ESB.Framework.ErrorHandler.Header.*` for header fields when the inbound
+message header is absent.
 
 ---
 
-## ErrorPoint Usage
+## Wiring a new flow
+
+```
+[Any processing node]
+   │ failure terminal
+   ↓
+ErrorHandler.subflow  (InTerminal matching the node/error class)
+   ├─ LogError.subflow                → audit
+   ├─ MWBusinessErrorResponse.subflow → sync ESB response to caller
+   └─ MQ_Dynamic_Output_Node.subflow  → async/dead routing
+```
 
-Use `ErrorPoint.esql` when you need to manually create an error structure (e.g., business validation failure before calling a backend):
+For an expected business/validation error, prefer the business channel:
 
 ```esql
--- Set error details on the Environment before routing to ErrorHandler
-SET Environment.ErrorDetails.Code = 'XXXXXXXX';
-SET Environment.ErrorDetails.EnglishMsg = 'Validation failed: ...';
--- Then propagate to ErrorHandler via failure terminal
+-- validation failed: set the ESB code and let the business-error path respond
+SET Environment.Variables.MWResponse.status = 'E5500003';
+PROPAGATE TO TERMINAL 'out2';   -- route to the business-error branch
+RETURN FALSE;
 ```

package/_agent_reference/components/http-adapters.md

@@ -10,26 +10,15 @@ Used for outbound HTTP calls (to backends or internal services) and for chaining
 
 **Supported backends**: T24, NIWS, ODM, Unifonic, MLSD, ICBS, and any REST/SOAP service.
 
-**ESQL helpers**:
-| Module | Purpose |
-|---|---|
-| `HTTPResponseAdapter_CheckCallType.esql` | Determine INTERNAL vs EXTERNAL call |
-| `InternalHTTPRequestAdapter_Remove_MQRFH2.esql` | Strip MQRFH2 headers before HTTP call |
-
-**ESQL DECLARE flags** (set at node level):
-```esql
-DECLARE IsT24Adapter          EXTERNAL BOOLEAN FALSE;
-DECLARE IsODMWSAdapter        EXTERNAL BOOLEAN FALSE;
-DECLARE IsFrontEndJSONAdapter EXTERNAL BOOLEAN FALSE;
-DECLARE IsNIWSAdapter         EXTERNAL BOOLEAN FALSE;
-DECLARE IsUniFonicAdapter     EXTERNAL BOOLEAN FALSE;
-DECLARE IsMLSDAdapter         EXTERNAL BOOLEAN FALSE;
-DECLARE IsICBSAdapter         EXTERNAL BOOLEAN FALSE;
-```
+**Node properties** (EXTERNAL): `ServiceURL`, `TimeoutInSec`.
 
-Set exactly ONE of these to `TRUE` to get correct request formatting and error code mapping for that backend.
+**URL/endpoint**: set the node `ServiceURL`, or read the target from the
+`BankIdForRoutingService` properties group (see below).
 
-**URL/endpoint**: Set in `Environment.Destination.HTTP.RequestURL` before calling this subflow, or configure in `BankIdForRoutingService` properties group.
+> The per-backend `Is<Backend>Adapter` flags (`IsT24Adapter`, `IsODMWSAdapter`, `IsUnifonicAdapter`,
+> `IsMLSDWSAdapter`, `IsICBSWSAdapter`, …) are **not** declared on `HTTPRequestAdapter`. They live on
+> the error path (`ErrorHandler_CreateGeniricRs`) where they select backend-specific error-code mapping.
+> See [error-handling](error-handling.md) for the full, correctly-named list.
 
 ---
 
@@ -37,8 +26,10 @@ Set exactly ONE of these to `TRUE` to get correct request formatting and error c
 
 **Purpose**: Processes the HTTP response from a backend call, normalizes it to the standard ESB response structure.
 
-**ESQL helper**: `HTTPResponseAdapter_CheckCallType.esql`
-- Routes differently based on whether it was an `INTERNAL` or `EXTERNAL` call
+**ESQL helper**: `HTTPResponseAdapter_CheckCallType.esql` (FILTER)
+- Reads `Root.MQRFH2.usr.http.reply.callType`: returns FALSE for `'EXTERNAL'`, TRUE otherwise.
+- The call type is stamped upstream by `InternalHTTPRequestAdapter_SetCallType.esql`, which sets
+  `MQRFH2.usr.http.reply.callType = 'INTERNAL'` (and the reply id) for internal calls.
 
 **Always pair with** `HTTPRequestAdapter` — use both or neither.
 

package/_agent_reference/components/input-adapters.md

@@ -18,25 +18,35 @@ All input adapters live in `Qiwa/Framework/Lib/`. Use them as the entry point of
 **ESQL helper modules used**:
 | Module | Purpose |
 |---|---|
-| `MQ_Input_Node_IsAuditEnabled.esql` | Filter: check if audit is on |
-| `MQ_Input_Node_IsPropertiesEnabled.esql` | Filter: check if properties loaded |
-| `MQ_Input_Node_IsRetryEnabled.esql` | Filter: check if retry is on |
-| `MQ_Input_Node_IsRollBackEnabled.esql` | Filter: check if rollback is on |
-| `MQ_Input_Node_PrepareAuditMessage.esql` | Compute: build audit payload |
+| `MQ_Input_Node.esql` (`MQ_Input_Node_Compute`, `Filter_IS_Audit_Enabled_Input_Node`) | Main compute + input audit gate (`ENABLE_AUDIT_INPUT`) |
+| `MQ_Input_Node_IsAuditEnabled.esql` | Filter: `Logging.LogEnabled OR Logging.AuditEnabled` |
+| `MQ_Input_Node_IsPropertiesEnabled.esql` | Filter: is PropertyReader enabled (`PROPERTIES_ENABLED`) |
+| `MQ_Input_Node_IsRetryEnabled.esql` | Filter: `Retry.RetryEnabled` |
+| `MQ_Input_Node_IsRollBackEnabled.esql` | Filter: `ROLL_BACK_TRANSACTION` |
+| `MQ_Input_Node_SetMsgUIDinEnv.esql` | Compute: stash message UID in Environment |
+| `MQ_Input_Node_PrepareAuditMessage.esql` | Compute: build audit payload → `LogAudit` |
 
-**Configuration flags** (set in Properties XML under `Logging` group):
-```
-AuditEnabled      TRUE/FALSE
-LogEnabled        TRUE/FALSE
-RetryEnabled      TRUE/FALSE   (also under Retry group)
-ValidationEnabled TRUE/FALSE   (under SchemaValidation group)
-```
+(`MQ_Input_Node_IsAuditEnabled.esql` also defines `MQ_Input_Node_IsSchemaValidationEnabled` and `MQ_OutputNode_IsServiceOut`.)
+
+**Configuration (Properties XML)** — each filter reads its property, and if the flow's property group
+is absent it falls back to the node EXTERNAL default:
+
+| Property (group) | EXTERNAL fallback |
+|---|---|
+| `Logging.LogEnabled` / `Logging.AuditEnabled` | `LOG_ENABLED` (also `ENABLE_AUDIT_INPUT`) |
+| `Retry.RetryEnabled` | `RETRY_ENABLED` |
+| `SchemaValidation.ValidationEnabled` | `SCHEMA_VALIDATION_ENABLED` |
+| (rollback — flag only) | `ROLL_BACK_TRANSACTION` |
+| (PropertyReader on/off — flag only) | `PROPERTIES_ENABLED` |
 
-**ESQL DECLARE for this node**:
+**ESQL EXTERNAL flags on this node** (real names — all default as noted):
 ```esql
-DECLARE IsAuditEnabled   EXTERNAL BOOLEAN FALSE;
-DECLARE IsRetryEnabled   EXTERNAL BOOLEAN FALSE;
-DECLARE IsRollBackEnabled EXTERNAL BOOLEAN FALSE;
+DECLARE PROPERTIES_ENABLED        EXTERNAL BOOLEAN FALSE;
+DECLARE LOG_ENABLED               EXTERNAL BOOLEAN FALSE;
+DECLARE SCHEMA_VALIDATION_ENABLED EXTERNAL BOOLEAN FALSE;
+DECLARE RETRY_ENABLED             EXTERNAL BOOLEAN FALSE;
+DECLARE ROLL_BACK_TRANSACTION     EXTERNAL BOOLEAN FALSE;
+DECLARE ENABLE_AUDIT_INPUT        EXTERNAL BOOLEAN TRUE;
 ```
 
 **When to use**: Any flow that reads from an IBM MQ queue asynchronously.

package/_agent_reference/components/output-adapters.md

@@ -8,9 +8,13 @@ All output adapters live in `Qiwa/Framework/Lib/`. Use them as the exit point of
 
 **Purpose**: Standard MQ output. Writes message to a target queue.
 
-**ESQL module**: `MQ_Output_Node.esql`
-- Copies message headers (`CopyMessageHeaders`)
-- Sets MQ destination queue from `Environment.Destination.MQ.DestinationData.queueName`
+**ESQL module**: `MQ_Output_Node.esql` (`MQ_Output_Node_Compute` + `Filter_Is_Audit_Enabled_Output_Node`)
+- Copies headers, then defaults `MQMD.CorrelId` to `MQMD.MsgId` when empty/zero
+- Applies `MQMD.Priority` from `Environment.Properties.{ApplicationLabel}.{flowName}.Priority.Priority` when present
+- Optional output audit gated by EXTERNAL `ENABLE_AUDIT_OUTPUT` (default `TRUE`)
+- It does **not** choose the destination queue — that is set upstream on
+  `LocalEnvironment.Destination.MQ.DestinationData[1].queueName` (by `SetQueues`,
+  `MQ_OutputNode_IsServiceOut`, or `MQ_OutputNode_IsDeadFlow`)
 
 **When to use**: Standard async MQ output for any request or response message.
 
@@ -20,11 +24,14 @@ All output adapters live in `Qiwa/Framework/Lib/`. Use them as the exit point of
 
 **Purpose**: Routes failed/unprocessable messages to a backout/dead-letter queue.
 
-**ESQL module**: `MQ_OutputNode_IsDeadFlow.esql`
+**ESQL module**: `MQ_OutputNode_IsDeadFlow.esql` (FILTER, EXTERNAL `DEAD_FLOW BOOLEAN FALSE`)
+- When `DEAD_FLOW` is TRUE → dead path. Otherwise it sets the destination from
+  `Root.MQRFH2.usr.queue.distinationQueue` (sic) and returns FALSE.
 
 **When to use**: Always wire this as the terminal node on the error path of every MQ flow.
 
-**Queue naming**: `<ORIGINAL_QUEUE_NAME>.BACKOUT`
+**Queue naming**: backout/dead queues follow the `<ORIGINAL_QUEUE_NAME>.BACKOUT` convention (see
+[naming-conventions](../config/naming-conventions.md)).
 
 ---
 
@@ -34,7 +41,7 @@ All output adapters live in `Qiwa/Framework/Lib/`. Use them as the exit point of
 
 **When to use**: Flows where the destination queue varies per message (e.g., routing based on `ServiceCode`).
 
-**How it works**: Reads queue name from `Environment.Destination.MQ.DestinationData.queueName` — set this dynamically in your compute ESQL before calling this subflow.
+**How it works**: Reads the queue name from `LocalEnvironment.Destination.MQ.DestinationData[1].queueName` — set this dynamically in your compute ESQL (via `OutputLocalEnvironment.Destination...`) before this subflow.
 
 ---
 
@@ -66,8 +73,8 @@ All output adapters live in `Qiwa/Framework/Lib/`. Use them as the exit point of
 
 **Purpose**: Makes outbound HTTP/SOAP calls to backend services.
 
-**ESQL helper**: `HTTPResponseAdapter_CheckCallType.esql`
-- Determines `INTERNAL` vs `EXTERNAL` call type
+**Node properties**: EXTERNAL `ServiceURL`, `TimeoutInSec`. (Call-type detection lives in
+`HTTPResponseAdapter`, not here — see [http-adapters](http-adapters.md).)
 
 **When to use**: Any flow that calls an external REST or SOAP service (T24, NIWS, ODM, Unifonic, MLSD, etc.).
 
@@ -109,16 +116,16 @@ All output adapters live in `Qiwa/Framework/Lib/`. Use them as the exit point of
 
 ---
 
-## ESQL Copy Utilities (used in all adapters)
+## ESQL Copy Utilities
 
-Every output adapter uses these standard procedures from `copy_Compute.esql`:
+Every framework module defines its own `CopyMessageHeaders()` and `CopyEntireMessage()` procedures
+inline (they are not imported from a shared module):
 
 ```esql
--- Copy all MQ and transport headers
-CALL CopyMessageHeaders();
-
--- Copy entire message tree
-CALL CopyEntireMessage();
+CALL CopyMessageHeaders();   -- copy header folders 1..N-1 (preserves MQMD, MQRFH2)
+CALL CopyEntireMessage();    -- SET OutputRoot = InputRoot;
 ```
 
-Always call `CopyMessageHeaders()` before modifying output to preserve MQ metadata (MQMD, MQRFH2).
+`copy_Compute.esql` is a ready-made generic copy COMPUTE node — it calls both procedures and also
+copies `LocalEnvironment.Wildcard.WildcardMatch`. Use it when you just need a pass-through copy node.
+Always copy headers before modifying output to preserve MQ metadata.

package/_agent_reference/components/property-reader.md

@@ -26,8 +26,12 @@
 
 Properties are accessed via the path:
 ```
-Environment.Properties.{ApplicationLabel}.{FlowName}.{Group}.{PropertyName}
+Environment.Properties.{ApplicationLabel}.{flowName}.{Group}.{PropertyName}
 ```
+where `ApplicationLabel` is the broker built-in (application name) and `flowName` is derived from the
+built-in `MessageFlowLabel` via `getFlowNameWithouSchema(Environment.FlowNameSplit)` — both are
+resolved at runtime, not hardcoded. Framework filters guard against the group being absent and fall
+back to the node's EXTERNAL default (e.g. `LOG_ENABLED`, `RETRY_ENABLED`).
 
 Examples:
 ```esql
@@ -66,24 +70,32 @@ These tokens in property values are replaced at runtime:
 
 | Token | Replaced With |
 |---|---|
-| `${broker.name}` | ACE broker/integration node name |
-| `${execution.group}` | Execution group / integration server name |
-| `${flow.name}` | Message flow name |
-| `${application.name}` | Application name |
+| `${broker.name}` | ACE broker/integration node name (`BrokerName`) |
+| `${execution.group}` | Execution group / integration server name (`ExecutionGroupLabel`) |
+| `${flow.name}` | Message flow name (`MessageFlowLabel`) |
+
+(Only these three tokens are substituted by `PropertyReader_LoadProperties`.)
 
 ---
 
-## ESQL Node Properties for PropertyReader
+## PropertyReader node properties
+
+`PropertyReader_LoadProperties.esql` declares these EXTERNAL (user-defined) properties — set them on the PropertyReader subflow node:
 
 ```esql
--- Required EXTERNAL declarations in the module using PropertyReader
-DECLARE ApplicationLabel EXTERNAL CHARACTER '';
-DECLARE PropertiesFileName EXTERNAL CHARACTER '';
+DECLARE PropertyFilename  EXTERNAL CHARACTER '*';            -- the XML config file
+DECLARE PropertiesGroup   EXTERNAL CHARACTER '*';            -- which group(s) to load
+DECLARE LogicalTreePath   EXTERNAL CHARACTER 'Environment';  -- target tree (must start Environment. or OutputLocalEnvironment.)
 ```
 
-Set `ApplicationLabel` and `PropertiesFileName` at the node level in the flow:
-- `ApplicationLabel`: e.g., `BS_Account`
-- `PropertiesFileName`: e.g., `ACCOUNT-PROPERTIES.xml`
+Typical node values (note the `${broker.name}` token):
+- `PropertyFilename`: `${broker.name}/ACCOUNT.xml`
+- `PropertiesGroup`: the property group, e.g. `BS_Account.GetAccountDetails`
+- `LogicalTreePath`: leave as `Environment` (default) → properties land under `Environment.Properties`
+
+It reads the file via the external `readerProperties(configFile, PropertiesGroup)` routine and builds
+the tree under `LogicalTreePath`. `ApplicationLabel` is **not** a PropertyReader external — it is a
+broker built-in correlation name (the application/library name), used when reading properties back.
 
 ---
 

package/_agent_reference/components/retry.md

@@ -8,19 +8,22 @@ The framework provides configurable retry for MQ-based flows using `RetryPoint.s
 
 | Component | Type | Purpose |
 |---|---|---|
-| `RetryPoint.subflow` | subflow | Re-queue message after failure with delay |
-| `SetRetryProperties.esql` | esql | Set retry tracking headers on MQRFH2 |
+| `RetryPoint.subflow` | subflow | Re-queue message after failure with delay (runs `SetRetryProperties`) |
+| `SetRetryProperties.esql` | esql | Seed the `MQRFH2.usr.retry` struct from `Retry` properties (or node externals) |
+| `MQ_Input_Node_IsRetryEnabled.esql` | esql | FILTER: `Retry.RetryEnabled` (fallback EXTERNAL `RETRY_ENABLED`) |
 
 ---
 
 ## How It Works
 
-1. On failure, message is caught by `ErrorHandler`
-2. `ErrorHandler` checks `RetryEnabled` from Properties
-3. If enabled, routes to `RetryPoint`
-4. `SetRetryProperties.esql` increments retry count in `MQRFH2.usr.retry`
-5. Message is re-queued to `MQRFH2.usr.sourceQueue` after `minWaitDurationSec`
-6. When `maxRetryCount` is reached → route to `MQ_Dead_Output_Node`
+1. On failure, the message is caught on the MQ input error path
+2. Retry is gated by `Retry.RetryEnabled` (filter `MQ_Input_Node_IsRetryEnabled`; fallback EXTERNAL `RETRY_ENABLED`)
+3. If enabled, routes to `RetryPoint`, which runs `SetRetryProperties`
+4. `SetRetryProperties` seeds the `MQRFH2.usr.retry` struct **only when not already present**:
+   `maxRetryCount`, `minWaitDurationSec`, and `sourceQueue` (= `InputRoot.MQMD.SourceQueue`).
+   The attempt counter is `MQRFH2.usr.retry.count` (read by `AuditPoint`)
+5. The message is re-queued to `MQRFH2.usr.retry.sourceQueue` after `minWaitDurationSec`
+6. When the attempt count reaches `maxRetryCount` → route to `MQ_Dead_Output_Node`
 
 ---
 
@@ -36,39 +39,41 @@ Under the `Retry` group for each flow:
 </group>
 ```
 
-| Property | Default | Description |
-|---|---|---|
-| `RetryEnabled` | `FALSE` | Enable/disable retry |
-| `maxRetryCount` | `5` | Max attempts before dead-lettering |
-| `minWaitDurationSec` | `60` | Seconds to wait before re-queue |
+When the flow's `Retry` property group is present, values come from properties; otherwise
+`SetRetryProperties` falls back to the node EXTERNAL defaults:
+
+| Property (group `Retry`) | EXTERNAL fallback | Default | Description |
+|---|---|---|---|
+| `RetryEnabled` | `RETRY_ENABLED` | `FALSE` | Enable/disable retry |
+| `maxRetryCount` | `MAX_RETRY_COUNT` | `0` | Max attempts before dead-lettering |
+| `minWaitDurationSec` | `MIN_WAIT_TIME_SEC` | `60` | Seconds to wait before re-queue |
 
 ---
 
-## MQRFH2 Headers Used
+## MQRFH2 retry struct
 
-| Header | Purpose |
+`SetRetryProperties` writes a **struct** under `MQRFH2.usr.retry` (not a scalar):
+
+| Field | Purpose |
 |---|---|
-| `MQRFH2.usr.retry` | Current retry attempt count |
-| `MQRFH2.usr.sourceQueue` | Original queue to re-queue to |
+| `MQRFH2.usr.retry.count` | Current attempt count (read by `AuditPoint`) |
+| `MQRFH2.usr.retry.maxRetryCount` | Max attempts for this message |
+| `MQRFH2.usr.retry.minWaitDurationSec` | Delay before re-queue |
+| `MQRFH2.usr.retry.sourceQueue` | Original queue (`MQMD.SourceQueue`) to re-queue to |
 
 ---
 
 ## ESQL for Retry Check
 
 ```esql
--- Check current retry count
-DECLARE retryCount INT;
-SET retryCount = InputRoot.MQRFH2.usr.retry;
-
--- Get max from properties
-DECLARE maxRetry INT;
-SET maxRetry = Environment.Properties.{AppLabel}.{flowName}.Retry.maxRetryCount;
+-- Current attempt count and limit
+DECLARE retryCount INT  CAST(InputRoot.MQRFH2.usr.retry.count AS INT);
+DECLARE maxRetry   INT  CAST(InputRoot.MQRFH2.usr.retry.maxRetryCount AS INT);
 
 IF retryCount >= maxRetry THEN
-    -- route to dead letter
+    -- limit reached → route to MQ_Dead_Output_Node
 ELSE
-    -- increment and re-queue
-    SET OutputRoot.MQRFH2.usr.retry = retryCount + 1;
+    SET OutputRoot.MQRFH2.usr.retry.count = retryCount + 1;   -- re-queue to .sourceQueue
 END IF;
 ```
 

package/_agent_reference/config/naming-conventions.md

@@ -7,13 +7,16 @@ All naming in this framework follows strict conventions. The agent MUST follow t
 ## ESQL Broker Schema
 
 ```esql
-BROKER SCHEMA Qiwa.<ApplicationName>
+BROKER SCHEMA com.qiwa.esb.<msgflowname-lower>
 -- Examples:
-BROKER SCHEMA Qiwa.BS_Account
-BROKER SCHEMA Qiwa.BS_Transfer
-BROKER SCHEMA Qiwa.Framework.Lib   ← shared lib only, never use for app code
+BROKER SCHEMA com.qiwa.esb.getaccountdetails
+BROKER SCHEMA com.qiwa.esb.createtransfer
+BROKER SCHEMA Qiwa.Framework.Lib   ← shared framework library only, never use for app code
 ```
 
+The schema is the message-flow name, lowercased, with no separators. App ESQL must also
+`PATH Qiwa.Framework.Lib;` to resolve the shared framework routines.
+
 ---
 
 ## ESQL Module Naming
@@ -174,7 +177,7 @@ Standard terminal names used in the framework:
 
 | Artifact | Format | Example |
 |---|---|---|
-| ESQL schema | `Qiwa.<AppName>` | `Qiwa.BS_Account` |
+| ESQL schema | `com.qiwa.esb.<msgflowname-lower>` | `com.qiwa.esb.getaccountdetails` |
 | ESQL module | `<Flow>_<Purpose>.esql` | `GetAccountDetails_Compute.esql` |
 | Message flow | `<FlowName>.msgflow` | `GetAccountDetails.msgflow` |
 | Application | `<Tier>_<Domain>` | `BS_Account` |

package/_agent_reference/config/properties-template.md

@@ -27,8 +27,9 @@ Use ALL-CAPS domain name.
 
   <!--
     Group name format: {ApplicationLabel}.{FlowName}
-    ApplicationLabel: set on PropertyReader node, e.g. "BS_MyService"
+    ApplicationLabel: the broker built-in application/library name, e.g. "BS_MyService"
     FlowName:         the message flow name, e.g. "GetMyData"
+    This whole group name is what you pass as PropertiesGroup on the PropertyReader node.
   -->
   <group name="BS_MyService.GetMyData">