ormuzPARTNER
Design standards/Nodes

Design a node

A node is a durable Process Editor contract. It must represent a business operation worth composing in a graph, not merely the availability of a partner endpoint or function.

When to introduce a node

A new node is justified when all five of the following conditions are met:

  1. a concrete process use case exists;
  2. the extension holds the authority required for the effect or observation;
  3. composing existing elements does not already solve the need cleanly;
  4. the durable value outweighs the contract maintenance cost;
  5. the node does not exist solely to complete CRUD symmetry.

Scalar, Each, or collection

Keep a scalar contract when each item can be processed independently. The Each mechanism then carries repetition.

Expose a collection directly when knowing the other items genuinely changes processing: aggregation, deduplication, provider batch behavior, coordination, rate-limit strategy, or completeness rule.

Use one subprocess per item when each item itself requires routing, waits, or human interactions.

Inputs and outputs

  • prefer a typed business object over a raw identifier when the node needs the full context;
  • ask directly for the precise property when the node only needs a value, for example an email address;
  • an output must add new value or a new guarantee, not re-emit an unchanged input;
  • a platform.* output must be complete and conform to the canonical contract;
  • display projections must not duplicate the output contract merely to enrich the UI card.

Drafts and mutations

Create a draft as late as possible, once the data required for its handoff is known. Do not introduce a node update_*_draft by default solely because a backend allows progressive mutation.

A mutation must remain explicit. Do not mix a read with a hidden effect, and do not hide a business failure in a warning or success output.

Naming and labels

An extension node uses the canonical identity <extension_key>.<snake_case>, for example stripe.ensure_customer. The prefix must be exactly the extension's metadata.name . Core executables use the reserved namespace ormuz in process artifacts; an extension must never borrow that namespace.

The user-facing label describes the operation in sentence case with a clear business verb.

Avoid implementation-oriented names such as “helper”, “handler”, or “API call”. The designer must understand the business outcome without knowing the partner code.