Skip to content

ADR 0003 — Workflow scope as a compositional unit (concept)

Status: Proposed (conceptual contract; partial alignment with today’s engine)
Date: 2026-05-02
Related: ADR 0001, ADR 0002, ADR 0004 — scoped_context per scope, Workflow YAML — Scoped context, Context variables

Context

Operators and designers need a stable mental model for units of work inside a workflow: something smaller than a full workflow but larger than a single step—close to a sub-workflow, without necessarily being a separate deployed workflow.

This ADR names that unit scope and fixes boundaries for connections, variables, and visibility so documentation and future engine features stay aligned.

Decision

1. What is a “scope”?

A scope is a logical grouping of steps with three conceptual surfaces:

Surface Meaning
Input What enters the scope from its caller (parent step or parent scope)—typically the XML/string pipeline and any explicitly passed bindings.
Output What leaves the scope to the parent—usually the last step’s output in that scope, or an aggregated result (e.g. parallel outputs_map).
Context Key/value state carried while steps inside the scope run—may be derived from workflow-level context but, by design intent, may eventually be isolated so inner names do not leak outward.

From outside the scope, authors reason about the scope as a black box: they care about declared inputs/outputs (and declared exposed context if any), not about inner step IDs unless they intentionally wire them (e.g. advanced parallel mapping).

2. Connections live only at workflow level

Connection references (connection, embedded workflow connections, templates) are defined at workflow document scope. Scopes reuse those connections by name; they do not define new connection stores.

Rationale: credentials and endpoints are centralized; nested scopes stay composable without duplicating connection YAML.

3. Variables and scopes (intent vs today)

Design intent

  • A scope may introduce local variables that are not meaningful outside that scope (lexical or prefix isolation).
  • Workflow-level declarative slots remain under scoped_context (Workflow YAML)—that is workflow scope, not step-block scope.

Current orchestrator behaviour (important)

  • scoped_context merges into the single workflow run context for the invocation (after trigger/initial_context).
  • type: parallel named scopes run substeps concurrently but today execute against the same shared context and outputs maps as the rest of the workflow (_exec_substeps inside parallel lanes shares the enclosing closure). So true variable isolation per parallel scope is not implemented yet; steps in two lanes can observe each other’s context writes.
  • Treat scope-local variables as a target architecture; migrating to copy-on-enter, prefixed keys, or shadow contexts would be follow-on work.

4. Visibility rule

Outside → in: A parent may pass input/prev XML and shared workflow context into a scope.
Inside → out: Only declared outputs (and chosen extracted fields) leave the scope; inner step structure is an implementation detail unless explicitly referenced (e.g. outputs_map targets).

Consequences

  • Documentation and designer UX can speak of scope input / output / context consistently.
  • Connections documentation stays workflow-centric; nested UI must not imply per-scope connection registries.
  • Features that promise isolated scope variables must be paired with explicit orchestrator/runtime changes and tests; until then, docs should not claim isolation for parallel lanes.

Mapping to existing mechanics (today)

Mechanism Role relative to this ADR
scoped_context in workflow YAML Declarative workflow-level variable slots + provider hint—not automatic isolation per inner scope.
type: parallel / scopes[] Structural scopes with named lanes and outputs_map; concurrency boundary, not yet a context firewall.
workflow_call Separate workflow invocation—stronger isolation boundary than inner scopes; shares patterns with “sub-workflow”.

Open points (for future ADRs)

  • Concrete context isolation strategy for parallel scopes (snapshot, prefix scope:<name>:, or shadow dict).
  • Whether designer shows scopes as collapsible “sub-workflow” panels with explicit input/output ports.
  • Alignment with scoped_context naming (“scoped” workflow vs “scope” block)—keep both terms but define glossary entries.

Glossary (short)

Term Definition
Workflow scope The whole document run: steps, connections resolution, scoped_context, single run id.
Inner scope A nested block (e.g. parallel lane) treated as a compositional unit; may gain variable isolation in a future release.