Definitions, revisions, and instances

Process definition

A process_definition is identified by an prd_…ID. Its executable content notably includes the input schema, output schema, graph, hosted-experience configuration, and associated launchers.

• input_schema defines what the instance accepts at startup.
• flow_config describes nodes, their parameters, and graph edges.
• output_schema defines the values produced on completion.
• active allows or prevents creation of new instances from the definition.

Working and immutable revisions

The definition exposes working_revision_id and revision_number. The Working pointer designates the snapshot currently selected by the editor and by new launches of this definition. The snapshot itself is an immutable revision identified by pdr_….

When a save genuinely changes executable content, Ormuz calculates a new content_hash and creates a newly numbered revision. When executable content is identical, the existing snapshot is reused instead of producing an artificial revision.

A revision captures the contract required for reproducible execution: inputs, outputs, graph, environment dependencies, User Journey, and launcher snapshot. Agent and Decision dependencies used by the process are also resolved at revision level.

Releases: explicitly publish a revision

A process_definition_release (prl_…) is a publication milestone referencing one precise revision. It has its own release_number and preserves the hash of published content. Publishing without specifying a revision promotes the current Working snapshot.

The same revision is not published twice as two distinct Releases: another promotion request for the same snapshot resolves the existing Release. A definition also preserves its latest published milestone separately from its Working pointer.

Subprocess revisions

A subprocess or Foreach node chooses how it references the child definition. The current contract exposes two modes: working and pinned.

A child instance always remains attached to the revision actually selected when it was created. Live accounts do not accept a child reference working in a process revision: deployment must freeze dependencies to precise revisions.

See Subworkflow for the complete parent/child contract.

Instances

A process_instance (pci_…) represents a concrete execution. It retains the process_definition_id, the process_definition_revision snapshot used, its input, current state, optional output, and start provenance.

Current public states are:

• running — active execution;
• waiting — waiting for a timer, interaction, event, or child;
• stopping — stop requested while execution still needs to yield;
• completed — output contract produced successfully;
• failed — terminal failure of this attempt;
• retry_exhausted — automatic retry budget exhausted;
• superseded — a corrective continuation replaced this attempt in the lineage;
• stopped — instance explicitly stopped.

The relationships retry_of, fork_of and parent_process_instance_id make lineage observable without mixing states of several instances. See Observability and Errors, retries, and idempotency.

Start source

start_source preserves instance provenance. Its structure depends on the operation that created it; do not treat it as a closed enum limited to a few historical values.

Event provenance may preserve event ID and type; subprocess provenance preserves parent context; retry, rerun, and fork preserve their relationship to the source instance. These values reconstruct why an execution exists, not modify its revision contract.

Instance output

A completed instance resolves its output_schema from authorized process sources. The persisted output belongs to the executed revision, not to a newer definition version.

For a waiting subprocess, this output becomes the parent node output when the child finishes. An empty output schema is valid for a terminal process that performs only business effects.

The sensitive and secret values preserve their protection in input, state, steps, and output. See Data protection.

Duplicate a process

POST /v1/processes/:id/duplicate creates a new definition with its own identity and history. Current executable content is copied; instances and revision history from the source definition are not.

copy_launchers is true by default, and the new definition is inactive by default. Permissions required by nodes must be explicitly granted in the copy context rather than assumed inherited from the source definition.

Activation

active controls creation of new instances from a definition. A direct launch of an inactive definition is rejected, and system-launcher resolution ignores inactive definitions.

Disabling a definition does not rewrite existing instances or their snapshot. Use this option to prevent new starts, not as a mechanism to retroactively stop running instances.