1- """Construct the Apps side of a generation plan for Harness to seal ."""
1+ """Plan candidate generation and collect the outputs retained by Harness."""
22
33from collections .abc import Callable
44from copy import deepcopy
5+ from hashlib import sha256
56
6- from inferrsi .contracts .json_v1 import encode
7+ from inferrsi .contracts .json_v1 import decode , encode
78from inferrsi .harness .errors import PublicError
89
910from .archive import _logical_path
11+ from .artifact_reader import ArtifactReader
1012from .bridge import (
1113 _ATTEMPT_FIELDS ,
14+ _CANDIDATE_FIELDS ,
1215 _definition ,
16+ _digest ,
1317 _id ,
1418 _input_paths ,
1519 _output_paths ,
1620 _require_disjoint_paths ,
1721)
18- from .result import validate_artifact_ref
22+ from .result import _RECORD_OBSERVATIONS , _check_ref , validate_artifact_ref
1923
2024_CONTEXT_FIELDS = {
2125 "campaign_id" , "generation_id" , "candidate" , "parent" , "task_materials" ,
2428_OUTPUT_CONTRACT_FIELDS = {
2529 "manifest_role" , "candidate_role" , "format_schema" , "required_input_roles" , "parser_revision" ,
2630}
31+ _MANIFEST_FIELDS = {"schema_version" , "provider" , "output_contract" , "context_refs" , "attempt_id" }
32+ _PLAN_ROLE = "generation_plan"
2733
2834
2935class CandidateProvider :
30- """Apps adapter for planning the generation leg of a Harness loop."""
36+ """Apps adapter for the generation leg of a Harness loop.
37+
38+ The configured parser implements the frozen parser revision. Given the worker's
39+ manifest and candidate bytes, it returns candidate metadata (without context refs)
40+ and a mapping from evaluation input roles to declared generation output roles.
41+ """
3142
3243 def __init__ (
3344 self , * , provider : dict , output_contract : dict , steps : list [dict ],
3445 bind_inputs : Callable [[dict ], list [dict ]], output_root_for : Callable [[str ], str ],
3546 required_capabilities : list [str ],
47+ parse_candidate : Callable [[bytes , bytes ], tuple [dict , dict [str , str ]]] | None = None ,
3648 ):
3749 self ._provider = deepcopy (provider )
3850 self ._output_contract = deepcopy (output_contract )
3951 self ._steps = deepcopy (steps )
4052 self ._bind_inputs = bind_inputs
4153 self ._output_root_for = output_root_for
4254 self ._required_capabilities = deepcopy (required_capabilities )
55+ self ._parse_candidate = parse_candidate
4356
4457 def plan_generation (self , context : dict , attempt : dict ) -> dict :
4558 """Bind the authorized context and original attempt to the configured worker."""
@@ -49,6 +62,166 @@ def plan_generation(self, context: dict, attempt: dict) -> dict:
4962 required_capabilities = self ._required_capabilities ,
5063 )
5164
65+ def collect_candidate (self , record : dict , * , artifacts : ArtifactReader ) -> dict :
66+ """Build a proposal from a fixed successful generation record and its outputs."""
67+ if self ._parse_candidate is None :
68+ raise PublicError (
69+ "UnsupportedOperation" , stage = "candidate_collection" ,
70+ message = "No candidate parser is configured for this provider." ,
71+ )
72+ try :
73+ record_ref , payload = _generation_record (record , artifacts )
74+ manifest = _generation_manifest (
75+ payload , artifacts , self ._provider , self ._output_contract ,
76+ )
77+ outputs = _generation_outputs (payload , self ._steps )
78+ contract = manifest ["output_contract" ]
79+ manifest_ref = outputs [contract ["manifest_role" ]]
80+ candidate_ref = outputs [contract ["candidate_role" ]]
81+ worker_manifest = _read_artifact (artifacts , manifest_ref )
82+ candidate_bytes = _read_artifact (artifacts , candidate_ref )
83+ candidate , bindings = self ._parse_candidate (worker_manifest , candidate_bytes )
84+ inputs = _candidate_inputs (candidate , bindings , contract , outputs )
85+ verified = {encode (manifest_ref ), encode (candidate_ref )}
86+ refs = [item ["source_ref" ] for item in inputs ]
87+ refs .extend (outputs [output ["role" ]] for step in self ._steps
88+ for output in step ["outputs" ] if output ["required" ])
89+ for ref in refs :
90+ identity = encode (ref )
91+ if identity not in verified :
92+ with artifacts .open (ref ):
93+ pass
94+ verified .add (identity )
95+ except (AttributeError , KeyError , TypeError , ValueError ) as exc :
96+ raise PublicError (
97+ "InvalidRequest" , stage = "candidate_collection" ,
98+ message = "Expected an accepted generation plan and a valid candidate output." ,
99+ ) from exc
100+ return deepcopy ({
101+ "candidate" : {** candidate , "context_refs" : manifest ["context_refs" ]},
102+ "inputs" : inputs ,
103+ "generation_record_ref" : record_ref ,
104+ })
105+
106+
107+ def _read_artifact (artifacts : ArtifactReader , ref : dict ) -> bytes :
108+ validate_artifact_ref (ref )
109+ _logical_path (ref ["location" ])
110+ with artifacts .open (ref ) as stream :
111+ return stream .read ()
112+
113+
114+ def _generation_record (record : dict , artifacts : ArtifactReader ) -> tuple [dict , dict ]:
115+ ref = record ["record_ref" ]
116+ _check_ref (ref , "attempt_id" , "record_version" )
117+ if ref ["artifact" ]["media_type" ] != "application/json" :
118+ raise ValueError ("expected a JSON record" )
119+ data = _read_artifact (artifacts , ref ["artifact" ])
120+ payload = decode (data )
121+ receipt = {key : value for key , value in record .items () if key not in _RECORD_OBSERVATIONS }
122+ if (
123+ encode (receipt ) != data or payload ["attempt_id" ] != ref ["attempt_id" ]
124+ or payload ["request_id" ] != ref ["attempt_id" ]
125+ or payload ["record_version" ] != ref ["record_version" ]
126+ ):
127+ raise PublicError (
128+ "IdentityMismatch" , stage = "candidate_collection" ,
129+ message = "The generation receipt differs from the committed record." ,
130+ )
131+ if (
132+ payload ["phase" ] != "finished" or payload ["process_outcome" ] != "exited"
133+ or type (payload ["exit_code" ]) is not int or payload ["exit_code" ] != 0
134+ or payload ["side_effect_unknown" ] is not False
135+ or any (payload [field ] is not None for field in (
136+ "candidate" , "prepared_ref" , "protocol_digest" , "operation" , "validation_scope" ,
137+ ))
138+ ):
139+ raise ValueError ("incomplete or unsuccessful generation record" )
140+ return ref , payload
141+
142+
143+ def _generation_manifest (
144+ record : dict , artifacts : ArtifactReader , provider : dict , output_contract : dict ,
145+ ) -> dict :
146+ plans = [item for item in record ["bound_inputs" ] if item ["role" ] == _PLAN_ROLE ]
147+ if len (plans ) != 1 :
148+ raise ValueError ("expected one bound generation plan" )
149+ plan = plans [0 ]
150+ ref = plan ["retained_ref" ]
151+ if (
152+ plan ["attempt_id" ] != record ["attempt_id" ] or plan ["identity_status" ] != "matched"
153+ or plan ["actual_sha256" ] != ref ["sha256" ] or plan ["expected_sha256" ] != ref ["sha256" ]
154+ ):
155+ raise ValueError ("generation plan identity was not verified" )
156+ manifest = decode (_read_artifact (artifacts , ref ))
157+ if (
158+ not isinstance (manifest , dict ) or manifest .keys () != _MANIFEST_FIELDS
159+ or type (manifest ["schema_version" ]) is not int or manifest ["schema_version" ] != 1
160+ or manifest ["provider" ] != provider or manifest ["output_contract" ] != output_contract
161+ or manifest ["attempt_id" ] != record ["attempt_id" ]
162+ or not isinstance (manifest ["context_refs" ], list ) or not manifest ["context_refs" ]
163+ ):
164+ raise ValueError ("generation manifest does not match the attempt and configured parser" )
165+ for context in manifest ["context_refs" ]:
166+ validate_artifact_ref (context )
167+ _logical_path (context ["location" ])
168+ return manifest
169+
170+
171+ def _generation_outputs (record : dict , steps : list [dict ]) -> dict :
172+ declarations = {output ["role" ]: (step ["step_id" ], output )
173+ for step in steps for output in step ["outputs" ]}
174+ outputs = {}
175+ for item in record ["artifacts" ]:
176+ role = item ["role" ]
177+ if role not in declarations :
178+ continue
179+ step_id , declaration = declarations [role ]
180+ if (
181+ role in outputs or item ["attempt_id" ] != record ["attempt_id" ]
182+ or item ["step_id" ] != step_id or item ["format_schema" ] != declaration ["format_schema" ]
183+ ):
184+ raise ValueError ("generation output must match its unique declared producer" )
185+ outputs [role ] = item ["artifact" ] if item ["status" ] == "available" else None
186+ if any (declaration ["required" ] and outputs .get (role ) is None
187+ for role , (_ , declaration ) in declarations .items ()):
188+ raise PublicError (
189+ "ArtifactUnavailable" , stage = "candidate_collection" ,
190+ message = "A required generation output was not retained." ,
191+ )
192+ return outputs
193+
194+
195+ def _candidate_inputs (candidate : dict , bindings : dict , contract : dict , outputs : dict ) -> list :
196+ if (
197+ not isinstance (candidate , dict ) or candidate .keys () != _CANDIDATE_FIELDS - {"context_refs" }
198+ or not all (_id (candidate [field ]) for field in ("candidate_id" , "input_role" , "kind" ))
199+ or (candidate ["parent_id" ] is None ) != (candidate ["parent_digest" ] is None )
200+ or (candidate ["parent_id" ] is not None and (
201+ not _id (candidate ["parent_id" ]) or not _digest (candidate ["parent_digest" ])
202+ ))
203+ or not isinstance (bindings , dict )
204+ or bindings .keys () != {* contract ["required_input_roles" ], candidate ["input_role" ]}
205+ or bindings [candidate ["input_role" ]] != contract ["candidate_role" ]
206+ ):
207+ raise ValueError ("candidate metadata and input roles must match the frozen output contract" )
208+ inputs = []
209+ for role , output_role in sorted (bindings .items ()):
210+ ref = outputs .get (output_role )
211+ if ref is None :
212+ raise PublicError (
213+ "ArtifactUnavailable" , stage = "candidate_collection" ,
214+ message = "A candidate input does not name a retained output." ,
215+ )
216+ validate_artifact_ref (ref )
217+ inputs .append ({
218+ "role" : role , "source" : ref ["location" ], "source_namespace" : "artifact" ,
219+ "source_ref" : ref , "snapshot_format" : "file-v1" , "expected_sha256" : ref ["sha256" ],
220+ "materialized_path" : f"inputs/{ sha256 (role .encode ('ascii' )).hexdigest ()} " ,
221+ })
222+ _input_paths (inputs )
223+ return inputs
224+
52225
53226def _plan_generation (
54227 context : dict , attempt : dict , * , provider : dict , output_contract : dict ,
@@ -92,7 +265,7 @@ def _plan_generation(
92265 if not isinstance (inputs , list ):
93266 raise ValueError ("expected generation inputs" )
94267 by_role = _input_paths (inputs )
95- if "generation_plan" in by_role :
268+ if _PLAN_ROLE in by_role :
96269 raise ValueError ("the generation_plan input role is reserved for Harness sealing" )
97270 used = set ()
98271 for item in by_role .values ():
0 commit comments