gnomonlearn

RFC-0022 · Multi-Agent Workflow Orchestration

Versioned draft snapshot

RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.

Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →


Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.


1. Scope

This RFC defines the workflow declaration kind: a named composition of Gnomon agents with explicit coordination semantics, data flow contracts, and error handling.

This RFC covers:

  • The workflow declaration — syntax and semantics
  • Sequential, parallel, conditional, and loop coordination patterns in the .gnm DSL
  • Typed data flow between agents: outputs of one agent as inputs to the next
  • Error handling and compensation: what happens when a sub-agent step fails
  • Human-in-the-loop gates: workflow pause pending human approval
  • Observability: how workflow execution appears in the RFC-0010 event log
  • Diagnostic codes in the M22xxx range

This RFC does not cover:

  • Individual agent declarations — those are defined in RFC-0009
  • Agent runtime binding (endpoint, model, health check) — those are defined in RFC-0015
  • Workflow scheduling or cron-triggered invocation (deferred to a future RFC)
  • Cross-module workflow composition: a workflow may only reference agents declared within its own module or its imported modules
  • Long-running human workflows lasting more than a configurable platform timeout (implementation-defined ceiling; this RFC defines the pause/resume semantics but not timeout policy)

2. Goals

  1. A workflow declaration MUST be fully static: all coordination structure, data flow types, and error policies are known at compile time.
  2. Sequential and parallel composition MUST be expressible without boilerplate. The compiler MUST verify that data flow types are consistent between steps.
  3. Human-in-the-loop gates MUST be first-class: a workflow that requires human approval before proceeding is not a special case but a standard coordination pattern.
  4. Workflow execution MUST be fully observable via the RFC-0010 event log. Every step start, step outcome, gate open/close, and workflow terminal state MUST produce a structured event.
  5. A failed sub-agent step MUST NOT produce silent data corruption. The workflow MUST define an explicit error policy for each step; absence of a policy is a compile error.
  6. The workflow declaration MUST NOT introduce new agent capabilities. Each step invokes an existing agent declaration with its existing permission set (RFC-0009). Workflows are orchestrators, not capability escalators.

Linked References

The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.

3. The workflow Declaration

3.1 Syntax

workflow-decl   ::= { decl-modifier } "workflow" IDENT "{" workflow-body "}"

workflow-body   ::= "description:" STRING NEWLINE
                    "trigger:"    trigger-decl NEWLINE
                    "steps:"      step-list
                  [ "onError:"    error-policy NEWLINE ]
                  [ "timeout:"    DURATION NEWLINE ]

trigger-decl    ::= "procedure" IDENT               (* fired via a declared procedure *)
                  | "event" IDENT                   (* fired by an event log event *)
                  | "manual"                         (* invoked programmatically *)

step-list       ::= step-decl+

step-decl       ::= sequential-step
                  | parallel-step
                  | conditional-step
                  | loop-step
                  | gate-step

sequential-step ::= "step" IDENT "{" step-body "}"

parallel-step   ::= "parallel" "{" sequential-step+ "}"

conditional-step ::= "if" condition-expr
                     "then" "{" step-list "}"
                   [ "else" "{" step-list "}" ]

condition-expr   ::= condition-expr "and" condition-expr
                   | condition-expr "or" condition-expr
                   | "not" condition-expr
                   | "(" condition-expr ")"
                   | field-path ( "==" | "!=" | "<" | ">" | "<=" | ">=" ) literal

field-path       ::= IDENT ( "." IDENT )*
literal          ::= STRING | NUMBER | "true" | "false"

loop-step       ::= "repeat" int-literal "{" step-list "}"

gate-step       ::= "gate" IDENT "{" gate-body "}"

step-body       ::= "agent:"   IDENT NEWLINE
                    "inputs:"  input-map NEWLINE
                    "outputs:" output-bind NEWLINE
                  [ "onError:" error-policy NEWLINE ]
                  [ "timeout:" DURATION NEWLINE ]

gate-body       ::= "description:" STRING NEWLINE
                    "approvedBy:"  IDENT            (* actor declaration *)

input-map       ::= "{" { IDENT ":" value-ref } "}"
output-bind     ::= "{" { IDENT ":" IDENT } "}"     (* bind output field to workflow variable *)

value-ref       ::= "trigger." IDENT                (* field from trigger input *)
                  | IDENT "." IDENT                 (* output field from a previous step *)
                  | literal

error-policy    ::= "fail"                          (* halt workflow, mark failed *)
                  | "continue"                      (* log and continue to next step *)
                  | "retry" int-literal             (* retry step N times before failing *)
                  | "compensate" IDENT              (* invoke a named compensation step *)

3.2 Canonical Example

workflow CustomerOnboarding {
  description: "Runs document verification, risk scoring, and advisor assignment in sequence."
  trigger: procedure SubmitApplication

  steps:
    step VerifyDocuments {
      agent:   DocumentVerificationAgent
      inputs:  { applicationId: trigger.applicationId }
      outputs: { verificationResult: verifyResult }
      onError: retry 2
    }

    if verifyResult.status == "approved"
    then {
      step ScoreRisk {
        agent:   RiskScoringAgent
        inputs:  { applicationId: trigger.applicationId, verifyData: verifyResult.data }
        outputs: { riskScore: riskScore }
        onError: fail
      }

      gate ManagerApproval {
        description: "Senior manager must approve high-risk applications."
        approvedBy:  Manager
      }

      step AssignAdvisor {
        agent:   AdvisorAssignmentAgent
        inputs:  { applicationId: trigger.applicationId, riskScore: riskScore }
        outputs: {}
        onError: fail
      }
    }
    else {
      step NotifyRejection {
        agent:   NotificationAgent
        inputs:  { applicationId: trigger.applicationId, reason: "documents-failed" }
        outputs: {}
        onError: continue
      }
    }
}

4. Coordination Patterns

4.1 Sequential Steps

Steps listed in sequence are executed in declaration order. Each step MUST complete before the next begins. The outputs of step N are available as inputs to step N+1 and any subsequent step.

4.2 Parallel Steps

Steps inside a parallel {} block are dispatched concurrently. The workflow waits for all parallel steps to complete before proceeding to the next declaration. If any parallel step fails and its error policy is fail, the workflow halts after all in-flight parallel steps settle (no cancellation mid-flight; this may be revisited in a future RFC).

Output bindings from parallel steps MUST use distinct variable names. A naming collision in parallel output bindings is a compile error M22202.

4.3 Conditional Steps

if … then … else … evaluates a boolean condition over a workflow variable or step output. The condition expression uses a restricted subset of the Transform Expression Language (RFC-0021). Workflow conditionals support the following RFC-0021 TEL subset: field access paths (e.g., step.output.status), equality and comparison operators (==, !=, <, >, <=, >=), logical connectives (and, or, not), and string/number/boolean literals. Arithmetic operators and string manipulation functions are NOT permitted in workflow conditionals.

The then branch is required; the else branch is optional. A conditional without else has an implicit no-op else. The compiler emits M22203 (warning) for a conditional whose then branch can produce outputs that subsequent steps depend on, but whose else branch produces no such outputs. This is a likely author mistake.

4.4 Loop Steps

repeat N { … } executes the enclosed step list exactly N times. N MUST be a positive integer literal; it cannot be a workflow variable. This restriction ensures the loop bound is statically known and the workflow is provably finite.

4.5 Human-in-the-Loop Gates

A gate step pauses the workflow until a human actor (identified by their actor declaration from RFC-0008) approves or rejects the continuation.

  • While a gate is open, the workflow is in the waiting state. No further steps are executed.
  • The approvedBy field identifies the actor declaration whose principals may approve or reject the gate.
  • Approval transitions the workflow to the running state and proceeds to the next step.
  • Rejection transitions the workflow to the rejected terminal state.
  • Gate events MUST appear in the RFC-0010 event log with full actor identity and timestamp.

5. Typed Data Flow

Every step declares its inputs and outputs. The compiler resolves all data flow at compile time:

  1. Each inputs binding references either trigger.<field> or <step>.<field>.
  2. The compiler looks up the type of the referenced field from the triggering action or from the agent’s outputs declaration (RFC-0009).
  3. The type is matched against the agent step’s expected input type.
  4. Any type mismatch produces compile error M22204.

Workflow variables (the values bound in outputs) are immutable once written. A step cannot overwrite a workflow variable produced by a prior step. Attempting to bind to an already-bound variable produces M22205.


6. Error Handling

Each step declares an onError policy. A missing onError at step level, combined with no workflow-level onError default, is compile error M22206.

6.1 Error Policies

PolicyBehavior
failHalt the workflow, mark it failed. No subsequent steps execute. Emit a workflow failure event.
continueLog the step failure, mark the step failed, and proceed to the next step.
retry NRe-invoke the agent step up to N additional times. If all retries fail, apply the next policy level (workflow onError, or fail).
compensate <step>On failure, invoke the named compensation step before halting. The compensation step MUST be a sequential-step declared in the same workflow.

6.2 Compensation Steps

A compensation step is a regular step declaration, but it is invoked by the error policy, not as part of normal sequential flow. Compensation steps SHOULD be idempotent. The compiler verifies that a compensate <step> reference resolves to a declared step within the workflow; an unresolved reference is M22207.


7. Observability

Every workflow state transition MUST be recorded as a structured event in the RFC-0010 event log. The following events are normative:

EventEmitted when
workflow.startedWorkflow is triggered and begins execution
workflow.step.startedA step begins dispatch
workflow.step.completedA step completes successfully
workflow.step.failedA step fails (includes error policy applied)
workflow.step.retryingA step retry is initiated
workflow.gate.openedA gate is reached and the workflow enters waiting
workflow.gate.approvedA gate is approved by a human actor
workflow.gate.rejectedA gate is rejected; workflow transitions to rejected
workflow.completedWorkflow completes all steps successfully
workflow.failedWorkflow halts due to a fail error policy
workflow.rejectedWorkflow halts due to gate rejection

Each event MUST include: workflow ID, workflow name, step name (if applicable), actor identity (for gate events), timestamp, and any diagnostic codes raised.


8. Security

  1. No capability escalation. A workflow declaration MUST NOT grant any step agent capabilities beyond those declared in the agent’s own permissions block (RFC-0009). The orchestrator has no permission surface of its own.
  2. Gate actor verification. The approvedBy actor in a gate MUST be validated at runtime against the authenticated identity of the approving principal. Unauthenticated or impersonated approvals MUST be rejected and logged as M22208.
  3. Data flow isolation. Workflow variables are scoped to the workflow execution instance. They MUST NOT be readable by other workflow instances or by code outside the workflow execution context.
  4. Trigger authorization. The principal that fires the workflow trigger MUST be authorized to invoke the trigger’s underlying action (RFC-0008 §6.25). An unauthorized trigger attempt is rejected before the workflow begins.

9. Failure Modes

ScenarioOutcomeDiagnostic
Step agent has no resolved binding in active environmentWorkflow fails at that stepM22200
Parallel step outputs bind to same variable nameCompile errorM22202
Conditional output referenced by subsequent step but missing from one branchCompile warningM22203
Data flow type mismatch between step output and next step inputCompile errorM22204
Step attempts to rebind an already-bound workflow variableCompile errorM22205
Step missing onError and no workflow-level defaultCompile errorM22206
compensate references an undeclared stepCompile errorM22207
Gate approval attempted by unauthenticated or wrong-actor principalRuntime rejection, loggedM22208
Loop count is zero or negativeCompile errorM22209
Workflow trigger references an undeclared actionCompile errorM22210
Workflow trigger references an action directly; MUST reference a procedureCompile errorM22214
Unresolved actor reference in gate approvedBy declarationCompile errorM22215
draft agent referenced in workflow step in a ciState: ready bundleCompile errorM01502 (RFC-0015)

10. Invariants

  1. Static data flow. All input/output bindings in a workflow are resolved and type-checked at compile time. No runtime type errors can occur in data flow for a statically validated workflow.
  2. Bounded step count. All loop bounds are static integer literals. Combined with the absence of unbounded recursion in the DSL, every workflow execution has a finite bound on dispatched steps. This does not guarantee wall-clock termination: a human gate can remain open until a decision or a platform timeout outside this RFC.
  3. Complete error policy coverage. Every step MUST have an error policy — either at the step level or via a workflow-level default. A workflow with an uncovered step cannot compile.
  4. Full event log coverage. Every workflow state transition produces an event in the RFC-0010 event log. There are no silent transitions.
  5. No cross-instance variable sharing. Workflow variables are isolated to the instance. Two concurrent executions of the same workflow cannot observe each other’s variables.
  6. Gate actor binding. The approvedBy actor reference in a gate MUST resolve to a declared actor (RFC-0008). An unresolved actor reference is a compile error (M22215).
  7. No permissions beyond declared agents. A workflow can only invoke agents it references by name. It cannot dynamically select agents at runtime, nor can it grant an agent temporary escalated permissions.

11. Diagnostic Codes (M22xxx)

All diagnostics introduced by this RFC occupy the M22200–M22299 range.

CodeSeveritySummary
M22200ErrorWorkflow step references an agent with no resolved binding in the active environment.
M22201—Reserved.
M22202ErrorParallel step output bindings use the same variable name (naming collision).
M22203WarningConditional step: subsequent step depends on a variable only bound in one branch.
M22204ErrorData flow type mismatch: step output type is not assignable to next step input type.
M22205ErrorStep output attempts to rebind an already-bound workflow variable.
M22206ErrorStep has no onError policy and no workflow-level default is declared.
M22207Errorcompensate error policy references an undeclared workflow step.
M22208ErrorGate approval rejected: actor identity does not match the approvedBy declaration.
M22209ErrorLoop step has a zero or negative repeat count.
M22210ErrorWorkflow trigger references an action that is not declared.
M22211—Reserved.
M22212—Reserved.
M22213—Reserved.
M22214ErrorWorkflow trigger references an action directly; MUST reference a procedure.
M22215ErrorUnresolved actor reference in gate approvedBy declaration (compile error).