Orchestration

Layer 3 of 12·Slice: Orchestration core·Platform: n8n

Scope of this page. Reference material for the Orchestration layer: what it owns, what it must not own, and how Synedrix OS implements it today. It is descriptive, not normative — where this page and the Layer Taxonomy Table disagree, the taxonomy table wins.

What this layer is link

The Orchestration Layer routes work, decomposes goals, sequences tasks, and manages retries and approvals. It is the layer that decides what happens next, in what order, on what trigger, and with what retry and escalation behavior — without itself performing domain reasoning or holding long-lived memory of its own.

Synedrix OS treats orchestration as the center of gravity of the whole platform: the durable value of the system is the quality of its sequencing, governance, and observability, not any single model or agent. Every workflow — deterministic or agent-driven — passes through this layer’s trigger handling, input validation, execution planning, and outcome persistence before its result is considered final. Since ADR-OS-001, this layer is deliberately narrow: it sequences and gates, but stateful or cyclic agent reasoning is delegated to the Agent Runtime Layer (Layer 4) as a governed step, not absorbed here.

flowchart LR
  n1([Orchestration]):::term
  subgraph What it owns
    n2[The workflow router]:::agent
    n3[The execution planner and task graph]:::agent
    n4[Retry logic timeout management and error/compensation handling]:::agent
    n5[Escalation rules and approval routing]:::agent
    n6[Sub-workflow calls and composition]:::agent
    n7[Outcome persistence]:::agent
  end
  n1 --> n2
  subgraph What it must not own
    n8[Domain-specific heuristics and business decision logic]:::warn
    n9[Domain Pack Layer]:::term
    n8 --> n9
    n10[Long-lived memory management]:::warn
    n11[Memory Data Layer]:::term
    n10 --> n11
    n12[Stateful cyclic multi-agent reasoning]:::warn
    n13[Agent Runtime Layer]:::term
    n12 --> n13
    n14[Policy decisions]:::warn
    n15[Policy Guard Agent]:::term
    n14 --> n15
    n16[Canonical business state]:::warn
    n17[Supabase PG17]:::term
    n16 --> n17
    n18[LLM traces prompts evaluations]:::warn
    n19[Langfuse]:::term
    n18 --> n19
  end
  n1 --> n8
  subgraph Interfaces with
    n20[Agent runtime]:::check
    n21[Governance]:::check
    n22[Observability]:::check
    n23[Event bus]:::check
  end
  n1 --> n20

What it owns link

Per the Layer Taxonomy Table, Orchestration owns the following:

• The workflow router — deciding which workflow or sub-workflow handles a given trigger.
• The execution planner and task graph — the decomposition of a goal into sequenced or parallel steps.
• Retry logic, timeout management, and error/compensation handling.
• Escalation rules and approval routing — inserting policy and HITL gates into the task graph.
• Sub-workflow calls and composition.
• Outcome persistence (append-only) and event emission at the end of every workflow run.

What it must not own link

This layer is deliberately narrow, and the boundary is enforced against two directions: domain reasoning belongs elsewhere, and so does anything requiring evolving state across cycles or agents.

Interfaces with link

Orchestration sits between the layers that produce work for it and the layers that execute, govern, and observe that work.

• Agent runtime — orchestration invokes LangGraph as a governed step whenever a workflow’s execution_pattern is stateful or cyclic, and always owns the trigger and surrounding sequence around that invocation.
• Governance — every approval-gated or high-impact workflow routes through Policy Guard and the HITL Gateway before a side-effecting step is allowed to proceed.
• Observability — every workflow run emits correlation-carrying events and outcomes so execution is traceable end-to-end, satisfying the invariant that every workflow must be observable.
• Event bus — triggers arrive as events, and outcomes are emitted as events, making orchestration a first-class producer and consumer on the event bus rather than a black box between them.

How Synedrix OS implements it link

n8n is the concrete implementation of this layer, and the n8n Implementation Guide fixes the mapping from abstract OS contracts to n8n constructs. Every compliant n8n workflow follows a required structural skeleton — trigger, input validation, correlation-ID initialization, the execution-pattern-specific node topology, invocation start and tool-call persistence, outcome assembly and persistence, and outcome-event emission — in that order. Simple acyclic agents (sequential, conditional, parallel, fan-out-fan-in, pipeline) may still run as n8n AI Agent nodes; the guide gives each of these patterns a concrete node topology (linear chains, IF/Switch nodes, Merge nodes, and so on).

The Workflow Contract Spec is what every workflow at this layer must satisfy. It requires a fixed set of fields — workflow_id, name, domain, purpose, trigger_type, trigger_source, input_contract, validation_rules, execution_pattern, agent_roles, tool_dependencies, side_effects, approval_requirements, output_contract, idempotency_strategy, retry_policy, error_policy, observability_signals, security_scope, and version — so that orchestration, policy, and observability can reason about any workflow consistently rather than relying on implicit assumptions. The spec also defines the execution_pattern field’s nine canonical values (sequential, parallel, conditional, fan-out-fan-in, iterative, consensus, hierarchical, pipeline, reflect-and-revise) and a formal step_type discriminator (deterministic vs. agent-driven) for steps within sequential and pipeline workflows.

The Orchestration & Runtime Strategy defines the boundary between this layer and Layer 4, decided in ADR-OS-001. n8n keeps event triggers, input validation, business-workflow sequencing, policy/HITL routing, sub-workflow composition, outcome persistence, and deterministic glue (Set, Merge, Filter, HTTP, DB read/write). Anything requiring shared, evolving state across cycles or agents — the iterative, consensus, reflect-and-revise, and hierarchical execution patterns — is routed to LangGraph instead, invoked over HTTP, MCP, or A2A as a governed step that carries correlation_id, causation_id, the resolved active_tool_set, and deployment_mode, and that must return the canonical Outcome Envelope. This keeps n8n’s own workflow execution queue (Redis-backed, in queue mode) architecturally distinct from the Layer 7 coordination bus that also happens to run on Redis — the strategy spec is explicit that the two roles must not be collapsed onto one logical database without a deliberate decision.

Platform mapping link

n8n is the sole platform mapped to this layer.

OS agents at this layer link

One OS-owned agent is registered at this layer.

Layer principles that apply link

• Layer Principle 1 — Shared before specific. Orchestration mechanics (routing, retries, escalation) are reusable across every domain pack, which is precisely why they live in the OS layer rather than being reimplemented per pack.
• Layer Principle 2 — Controls before execution. Execution paths at this layer pass through governance (Policy Guard, HITL) rather than bypassing them for convenience — the Workflow Contract Spec makes approval_requirements a mandatory field for exactly this reason.

Related Synedrix OS documents link

• Layer Taxonomy Table — the authoritative row for this layer.
• Orchestration & Runtime Strategy — the n8n↔LangGraph boundary and governance bridge.
• ADR-OS-001 — the decision that split Agent Runtime (Layer 4) out of Orchestration (Layer 3).
• n8n Implementation Guide — agent spec to AI Agent node, invocation start and outcome persistence, correlation ID propagation.
• Workflow Contract Spec — the contract every workflow at this layer must satisfy.
• n8n platform reference — what n8n is, what it is normally used for, and its licence position.

Synedrix OS · Layer reference · Orchestration