Documentation
¶
Overview ¶
Package graph implements stage 5 of the manifest's fixed seven-stage validation pipeline (design.md D-H): dependency-graph construction from each step's needs[], cycle detection via Kahn's algorithm (design.md D-J), rejection of an undeclared data reference (a steps.<id>.output interpolation reference to a step not present in the consuming step's own needs[]), and the output-kind/input-kind checks that are statically knowable without a resolved provider.
Build is directly callable with a raw []manifest.Step slice — it does not assume manifest.ValidateStructure (stage 3) already ran, and re-validates duplicate ids and unknown needs[] references defensively for its own independent testability (tasks.md 6.6, 6.7), mirroring every other stage package in this pipeline (internal/workflow/interp is likewise independently testable without manifest.Parse).
Kind checking (tasks.md 6.9) is deliberately PARTIAL, following the same honesty standard internal/workflow/interp's Reference.StaticKind set (tasks.md 5.3): a step's declared Input is a Directory-typed field (design.md D-H, workflow-manifest spec), and a secrets.* reference — unconditionally KindSecret by construction (interp.StaticKind) — can never satisfy that, so it is rejected here. That is the ONLY kind mismatch this package can prove without a provider schema. Two classes of check are explicitly NOT implemented here and deferred to internal/workflow/providers (Phase 7, design.md D-I):
- A steps.<id>.output reference's Kind is fixed by whichever capability produced that step, which is not knowable until stage 6 provider resolution — StaticKind reports ok=false for exactly this case, and this package accepts it rather than guessing.
- Kind compatibility for `with` field values against a provider's declared WithSchema (stage 7, forbidPlaintext and general type mismatch) requires the provider's field-kind declaration, which does not exist until Phase 7 — this package has no schema to compare a with-field's resolved kind against, so it does not attempt that comparison.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CycleError ¶
type CycleError struct{ StepIDs []string }
CycleError reports the set of step ids that remain unresolved after Kahn's algorithm drains every zero-in-degree node (tasks.md 6.10, design.md D-J): "after Kahn drains, any node with residual in-degree > 0 is in or downstream of a cycle." StepIDs is ordered by manifest declaration order for a deterministic, reproducible error message.
func (*CycleError) Error ¶
func (e *CycleError) Error() string
type DuplicateStepIDError ¶
type DuplicateStepIDError struct{ StepID string }
DuplicateStepIDError reports a step id used more than once (tasks.md 6.7).
func (*DuplicateStepIDError) Error ¶
func (e *DuplicateStepIDError) Error() string
type Graph ¶
Graph is the engine's compiled DAG artifact (design.md D-G: "the engine's compiled artifact is a Graph, never a 'plan'"). Waves is the topological schedule Kahn's algorithm produces: Waves[i] is the set of step ids that can run in round i, ordered within each wave by manifest declaration order (design.md D-K: sequential execution within a wave, in manifest-declaration order — the exact seam a worker pool drops into later).
type KindMismatchError ¶
KindMismatchError reports an interpolation reference whose statically known Kind cannot satisfy the structural expectation of the field it is used in (tasks.md 6.9). See this file's package doc comment for exactly what IS and is NOT checked.
func (*KindMismatchError) Error ¶
func (e *KindMismatchError) Error() string
type Node ¶
Node is one step in the graph as this package's stage-5 validation sees it: just the id and the resolved, deduplicated set of upstream dependency ids (needs[]). Everything else about the step (capability, uses, with) belongs to a later phase's concern.
type UndeclaredDataReferenceError ¶
type UndeclaredDataReferenceError struct{ StepID, ReferencedStepID, Field string }
UndeclaredDataReferenceError reports a steps.<id>.output interpolation reference used in a step's input/with fields where <id> is not also present in that step's own declared needs[] (tasks.md 6.8) — reading another step's output without a declared ordering dependency would be an unordered/racy read once execution ever widens within a wave (design.md D-K).
func (*UndeclaredDataReferenceError) Error ¶
func (e *UndeclaredDataReferenceError) Error() string
type UnknownNeedsError ¶
type UnknownNeedsError struct{ StepID, UnknownID string }
UnknownNeedsError reports a needs[] entry naming a step id that does not exist among the manifest's steps (tasks.md 6.6). Deliberately a distinct Go type from CycleError so a caller can tell "you referenced a step that doesn't exist" apart from "the steps you referenced form a cycle" with errors.As, not string matching.
func (*UnknownNeedsError) Error ¶
func (e *UnknownNeedsError) Error() string
Source Files