Compound Emission Pattern

Some generators emit more than one XAML element. The caller receives a compound structure, not a single activity.

Affected Generators

Generator	Emitted structure
add_queue_item	RetryScope > Sequence > AddQueueItem
get_queue_item	RetryScope > Sequence > GetQueueItem
bulk_add_queue_items	RetryScope > Sequence > BulkAddQueueItems
get_robot_asset	RetryScope > Sequence > GetRobotAsset

Each generator calls gen_retryscope internally and passes the activity XML as the body:

return gen_retryscope(
    display_name=f"Retry - {display_name}",
    id_ref=f"RetryScope_{id_ref}",
    body_content=add_queue_xml,
    body_sequence_idref=f"Sequence_Retry_{id_ref}",
    number_of_retries=number_of_retries,
    indent=indent,
)

Design Rationale

The wrapping implements Rule 13: Orchestrator API calls must always be wrapped in RetryScope to handle transient network failures. Baking this into the generator prevents the most common omission — an LLM generating a bare AddQueueItem without retry protection.

Composability Friction

The wrapping is unconditional. A caller that already handles retry at a higher level (e.g., a RetryScopeWrapper around the entire transaction block) cannot get the bare AddQueueItem without the inner RetryScope. The result is nested RetryScope structures.

This is documented as accepted behaviour: the inner RetryScope retries the API call on transient failures (HTTP 503, timeout); the outer RetryScope retries the business transaction on application failures. They serve different purposes and nesting is intentional in REFramework patterns.

However, for non-REFramework use cases where a single retry strategy is sufficient, the compound emission cannot be bypassed without calling the underlying generator functions directly, bypassing the JSON spec interface.

IdRef Consumption

Compound generators consume multiple IdRef slots in a single call. add_queue_item with id_ref="1" produces:

• AddQueueItem_1
• RetryScope_RetryScope_1
• Sequence_Retry_Sequence_Retry_1

The IdRef counter is shared across the entire workflow, so this has no practical impact — but it means the IdRef numbering in compound-emitting generators does not follow the simple ActivityName_N pattern of leaf generators.