notarius/docs/adr/0008-ordered-pipeline-steps.md

ADR-0008: Bounded ordered pipeline steps and explicit artifact references

Status: Accepted Date: 2026-07-21

Context

Notarius currently models one pipeline-wide input, chunking plan, artifact lanes, and output boundary. Some workflows need a deterministic handoff from one set of normalized artifacts to a later set of artifacts, such as using extracted NPC records while grounding later combat events. The workflow needs an explicit topology without turning the pipeline into a general-purpose workflow engine.

Decision

Add an ordered collection of pipeline steps. Each step owns one or more artifact lanes, and lanes within a step retain the existing independent execution model. The pipeline continues to have one input, chunk plan, output, and failure boundary. Steps are barriers: a later step may consume only normalized artifacts from an earlier step.

Generated references use an explicit step-and-lane selector. Reference slots declare the generated artifact kinds and media types they accept. The resolver validates the topology, ordering, lane identity, artifact kind, schema, and codec compatibility before execution. External references remain supported as path sources, and the legacy top-level artifact map is interpreted as an implicit default step.

Pipeline-level references may not select generated artifacts. General DAGs, branches, loops, conditional execution, joins, and inferred dependencies are not part of this model.

Alternatives considered

• A general DAG would provide more flexibility but would also require a new scheduler, lifecycle model, failure semantics, and provenance model.
• Separate pipeline runs connected through filesystem paths would lose the static topology and typed compatibility checks.
• Inferring dependencies from module or lane names would make ordering and configuration errors difficult to detect reliably.

Consequences

The resolved pipeline has a deterministic, inspectable topology and can include it in its identity digest. Configuration validation can reject invalid generated bindings before any work begins. Existing single-step profiles keep their behavior through the implicit default step. Execution handoff and multi-step scheduling require follow-up work in the runner and checkpoint layers.