stacklatch 0.1.0a1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,338 @@
1
+ """Static, bounded Python package graph for pinned V2.4 source trees.
2
+
3
+ This parser never imports repository modules on the host. Unsupported syntax
4
+ fails closed for a selected closure; unrelated modules remain unselected.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import ast
9
+ import hashlib
10
+ import re
11
+ from pathlib import Path
12
+
13
+ from .core import Analysis, InspectionError, _copy_checked
14
+ from .v22 import (DENIED, IDENT, STDLIB, _constant_value, _literal,
15
+ _metadata_v22, _read_ast, _return_shape, _score)
16
+
17
+ MAX_MODULES = 32
18
+ MAX_GRAPH_DEPTH = 6
19
+ MAX_FUNCTIONS = 128
20
+ AUDITED_MODULES = STDLIB | {"unicodedata", "string", "collections", "dataclasses"}
21
+ AUDITED_FROM = {"collections": {"Counter"}, "dataclasses": {"dataclass"},
22
+ "typing": {"Final", "Dict", "List", "Tuple", "Optional", "Any"},
23
+ "pathlib": {"Path"}}
24
+
25
+
26
+ def _annotation(node):
27
+ if node is None or isinstance(node, ast.Name):
28
+ return True
29
+ if isinstance(node, ast.Constant) and node.value is None:
30
+ return True
31
+ if isinstance(node, ast.Subscript):
32
+ return _annotation(node.value) and _annotation(node.slice)
33
+ if isinstance(node, ast.Tuple):
34
+ return all(_annotation(x) for x in node.elts)
35
+ if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
36
+ return _annotation(node.left) and _annotation(node.right)
37
+ return False
38
+
39
+
40
+ def _safe_constant(node, names):
41
+ if _constant_value(node, names):
42
+ return True
43
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "frozenset" and len(node.args) == 1 and not node.keywords and _literal(node.args[0]):
44
+ return True
45
+ return (isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
46
+ and isinstance(node.func.value, ast.Name) and node.func.value.id == "re"
47
+ and node.func.attr == "compile" and len(node.args) == 2 and not node.keywords
48
+ and _literal(node.args[0]) and isinstance(node.args[1], ast.Attribute)
49
+ and isinstance(node.args[1].value, ast.Name) and node.args[1].value.id == "re"
50
+ and node.args[1].attr in {"UNICODE", "IGNORECASE", "MULTILINE", "DOTALL"})
51
+
52
+
53
+ def _modules(analysis: Analysis) -> dict[str, str]:
54
+ result = {}
55
+ for path in analysis.files:
56
+ if not path.endswith(".py") or Path(path).name == "setup.py" or any(
57
+ p in {"tests", "test", ".github"} for p in Path(path).parts):
58
+ continue
59
+ parts = list(Path(path).parts)
60
+ if parts[0] == "src":
61
+ parts.pop(0)
62
+ # Implicit namespace packages are valid Python and have no initializer
63
+ # to execute. Any present initializer is audited before staging.
64
+ if parts[-1] == "__init__.py":
65
+ parts.pop()
66
+ else:
67
+ parts[-1] = parts[-1][:-3]
68
+ if parts and all(IDENT.fullmatch(p) for p in parts):
69
+ name = ".".join(parts)
70
+ if name in result:
71
+ raise InspectionError("Ambiguous source module path")
72
+ result[name] = path
73
+ return result
74
+
75
+
76
+ def _project_import(node: ast.ImportFrom, module: str, initializer: bool,
77
+ modules: dict[str, str]) -> tuple[str, dict[str, tuple[str, str]]]:
78
+ if node.level:
79
+ package = module if initializer else module.rpartition(".")[0]
80
+ parts = package.split(".") if package else []
81
+ if node.level > len(parts):
82
+ raise InspectionError("Relative import escapes package")
83
+ base = parts[:len(parts) - node.level + 1]
84
+ requested = ".".join([*base, *(node.module.split(".") if node.module else [])])
85
+ else:
86
+ requested = node.module or ""
87
+ if requested not in modules:
88
+ raise InspectionError("Unresolved in-repository import")
89
+ aliases = {}
90
+ for name in node.names:
91
+ if name.name == "*" or not IDENT.fullmatch(name.name):
92
+ raise InspectionError("Wildcard or invalid import name")
93
+ target = f"{requested}.{name.name}"
94
+ if target in modules: # from . import helper_module
95
+ aliases[name.asname or name.name] = (target, "")
96
+ else:
97
+ aliases[name.asname or name.name] = (requested, name.name)
98
+ return requested, aliases
99
+
100
+
101
+ def _scan(root: Path, analysis: Analysis, module: str, modules: dict[str, str]):
102
+ path = modules[module]
103
+ tree = _read_ast(root, analysis, path)
104
+ imports = {}
105
+ edges = set()
106
+ constants = set()
107
+ for node in tree.body:
108
+ if isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant) and isinstance(node.value.value, str):
109
+ continue
110
+ if isinstance(node, ast.Import):
111
+ for alias in node.names:
112
+ if alias.name in AUDITED_MODULES and not alias.asname:
113
+ continue
114
+ if alias.name not in modules or alias.asname:
115
+ raise InspectionError("Unaudited or aliased module import")
116
+ edges.add(alias.name)
117
+ elif isinstance(node, ast.ImportFrom):
118
+ if node.level == 0 and node.module == "__future__" and [a.name for a in node.names] == ["annotations"]:
119
+ continue
120
+ if node.level == 0 and node.module in AUDITED_FROM and all(
121
+ a.name in AUDITED_FROM[node.module] and not a.asname for a in node.names):
122
+ continue
123
+ target, aliases = _project_import(node, module, path.endswith("/__init__.py"), modules)
124
+ if imports.keys() & aliases.keys():
125
+ raise InspectionError("Ambiguous imported alias")
126
+ imports.update(aliases)
127
+ edges.add(target)
128
+ edges.update(m for m, name in aliases.values() if not name)
129
+ elif isinstance(node, (ast.Assign, ast.AnnAssign)):
130
+ targets = node.targets if isinstance(node, ast.Assign) else [node.target]
131
+ if len(targets) != 1 or not isinstance(targets[0], ast.Name) or node.value is None or not _safe_constant(node.value, constants):
132
+ raise InspectionError("Dynamic import-time constant")
133
+ constants.add(targets[0].id)
134
+ elif isinstance(node, ast.FunctionDef):
135
+ if node.decorator_list or node.args.vararg or node.args.kwarg or node.args.kwonlyargs:
136
+ raise InspectionError("Unsupported function definition")
137
+ if any(not _literal(default) for default in node.args.defaults):
138
+ raise InspectionError("Evaluated function default")
139
+ if not any(isinstance(n, ast.ImportFrom) and n.module == "__future__" for n in tree.body):
140
+ anns = [a.annotation for a in node.args.posonlyargs + node.args.args] + [node.returns]
141
+ if any(not _annotation(a) for a in anns):
142
+ raise InspectionError("Evaluated annotation")
143
+ elif isinstance(node, ast.ClassDef):
144
+ decorator = node.decorator_list[0] if len(node.decorator_list) == 1 else None
145
+ safe_decorator = (isinstance(decorator, ast.Name) and decorator.id == "dataclass") or (
146
+ isinstance(decorator, ast.Call) and isinstance(decorator.func, ast.Name)
147
+ and decorator.func.id == "dataclass" and not decorator.args
148
+ and all(k.arg in {"frozen", "slots"} and isinstance(k.value, ast.Constant)
149
+ and type(k.value.value) is bool for k in decorator.keywords))
150
+ if (not safe_decorator or node.bases or node.keywords
151
+ or not any(isinstance(n, ast.ImportFrom) and n.module == "dataclasses"
152
+ and [a.name for a in n.names] == ["dataclass"] for n in tree.body)):
153
+ raise InspectionError("Unsupported class initialization")
154
+ if any(not (isinstance(n, ast.AnnAssign) and isinstance(n.target, ast.Name)
155
+ and _annotation(n.annotation) and (n.value is None or _literal(n.value)))
156
+ and not (isinstance(n, ast.FunctionDef) and not n.decorator_list
157
+ and not n.args.vararg and not n.args.kwarg
158
+ and all(_literal(d) for d in n.args.defaults))
159
+ and not (isinstance(n, ast.Expr) and isinstance(n.value, ast.Constant)
160
+ and isinstance(n.value.value, str)) for n in node.body):
161
+ raise InspectionError("Unsupported dataclass body")
162
+ elif (isinstance(node, ast.If) and isinstance(node.test, ast.Compare)
163
+ and isinstance(node.test.left, ast.Name) and node.test.left.id == "__name__"
164
+ and len(node.test.ops) == 1 and isinstance(node.test.ops[0], ast.Eq)
165
+ and len(node.test.comparators) == 1 and isinstance(node.test.comparators[0], ast.Constant)
166
+ and node.test.comparators[0].value == "__main__" and not node.orelse):
167
+ continue
168
+ else:
169
+ raise InspectionError("Unsupported import-time statement")
170
+ return tree, imports, edges
171
+
172
+
173
+ def _closure(root, analysis, module, function, modules, checked, active, functions):
174
+ key = (module, function)
175
+ if key in active:
176
+ raise InspectionError("Cyclic helper closure")
177
+ if key in functions:
178
+ return
179
+ if len(functions) >= MAX_FUNCTIONS:
180
+ raise InspectionError("Helper closure exceeds limit")
181
+ tree, imports, _ = checked[module]
182
+ defs = {n.name: n for n in tree.body if isinstance(n, ast.FunctionDef)}
183
+ if function not in defs:
184
+ raise InspectionError("Unresolved helper function")
185
+ active.add(key)
186
+ for node in ast.walk(defs[function]):
187
+ if isinstance(node, (ast.Import, ast.ImportFrom)):
188
+ raise InspectionError("Dynamic function import")
189
+ if isinstance(node, ast.Name) and node.id in DENIED:
190
+ raise InspectionError("Unsafe function name")
191
+ if isinstance(node, ast.Attribute) and node.attr.startswith("__"):
192
+ raise InspectionError("Unsafe function attribute")
193
+ if isinstance(node, ast.Call):
194
+ if isinstance(node.func, ast.Name):
195
+ name = node.func.id
196
+ if name in DENIED:
197
+ raise InspectionError("Unsafe function call")
198
+ if name in defs:
199
+ _closure(root, analysis, module, name, modules, checked, active, functions)
200
+ elif name in imports:
201
+ other, called = imports[name]
202
+ if not called:
203
+ raise InspectionError("Module used as callable")
204
+ _closure(root, analysis, other, called, modules, checked, active, functions)
205
+ elif isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
206
+ alias = node.func.value.id
207
+ if alias in imports and not imports[alias][1]:
208
+ other = imports[alias][0]
209
+ _closure(root, analysis, other, node.func.attr, modules, checked, active, functions)
210
+ active.remove(key)
211
+ functions.add(key)
212
+
213
+
214
+ def index_graph(root: Path, analysis: Analysis):
215
+ if analysis.language != "python" or analysis.license != "MIT-like (heuristic)" or analysis.dependencies:
216
+ raise InspectionError("Only MIT-like dependency-free Python is supported")
217
+ _metadata_v22(root, analysis)
218
+ modules = _modules(analysis)
219
+ if len(modules) > MAX_MODULES:
220
+ raise InspectionError("Module graph exceeds limit")
221
+ checked = {}
222
+ rejected = {}
223
+
224
+ def visit(module, active, depth):
225
+ if module in checked:
226
+ return
227
+ if module in active or depth > MAX_GRAPH_DEPTH:
228
+ raise InspectionError("Cyclic or deep package imports")
229
+ tree, imports, edges = _scan(root, analysis, module, modules)
230
+ for edge in sorted(edges):
231
+ # A package initializer may re-export the child currently being
232
+ # audited. This is the only allowed back edge; all other cycles
233
+ # fail closed.
234
+ if edge in active and modules[module].endswith("/__init__.py") and edge.startswith(module + "."):
235
+ continue
236
+ visit(edge, active | {module}, depth + 1)
237
+ # Python imports parent initializers before submodules.
238
+ parts = module.split(".")
239
+ for n in range(1, len(parts)):
240
+ parent = ".".join(parts[:n])
241
+ if parent in modules and parent not in active:
242
+ visit(parent, active | {module}, depth + 1)
243
+ checked[module] = (tree, imports, edges)
244
+
245
+ for name in sorted(modules):
246
+ try:
247
+ visit(name, set(), 1)
248
+ except InspectionError as exc:
249
+ rejected[name] = str(exc)
250
+ indexed = []
251
+ for module in sorted(checked):
252
+ tree, _, _ = checked[module]
253
+ for fn in (n for n in tree.body if isinstance(n, ast.FunctionDef) and not n.name.startswith("_")):
254
+ params = fn.args.posonlyargs + fn.args.args
255
+ shape, keys, evidence = _return_shape(fn)
256
+ item = {"module": module, "path": modules[module], "name": fn.name,
257
+ "line": fn.lineno, "file_sha256": analysis.file_sha256[modules[module]],
258
+ "parameters": [{"name": p.arg, "annotation": ast.unparse(p.annotation) if p.annotation else "unknown",
259
+ "required": i < len(params) - len(fn.args.defaults)}
260
+ for i, p in enumerate(params)],
261
+ "return_shape": shape, "return_keys": keys, "shape_evidence": evidence,
262
+ "docstring": ast.get_docstring(fn) or "", "supported": True}
263
+ try:
264
+ closure = set()
265
+ _closure(root, analysis, module, fn.name, modules, checked, set(), closure)
266
+ staged = {m for m, _ in closure} | {module}
267
+ pending = list(staged)
268
+ while pending:
269
+ current = pending.pop()
270
+ parents = [".".join(current.split(".")[:n])
271
+ for n in range(1, len(current.split(".")))]
272
+ for dependency in checked[current][2] | set(parents):
273
+ if dependency in modules and dependency not in staged:
274
+ if dependency not in checked:
275
+ raise InspectionError("Unresolved package initializer")
276
+ staged.add(dependency)
277
+ pending.append(dependency)
278
+ item["closure"] = sorted(staged)
279
+ except InspectionError as exc:
280
+ item["supported"], item["reason"] = False, str(exc)
281
+ indexed.append(item)
282
+ return indexed, rejected
283
+
284
+
285
+ def propose_graph(left: Analysis, right: Analysis, left_root: Path, right_root: Path, goal: str):
286
+ if not isinstance(goal, str) or not goal.strip() or any(
287
+ a.provenance != "fetched_git_commit" for a in (left, right)):
288
+ raise InspectionError("Pinned fetched commits and goal required")
289
+ indexes = [index_graph(root, analysis) for root, analysis in
290
+ zip((left_root, right_root), (left, right), strict=True)]
291
+ candidates = []
292
+ for source in indexes[0][0]:
293
+ if (not source["supported"] or not source["parameters"]
294
+ or not source["parameters"][0]["required"]
295
+ or any(p["required"] for p in source["parameters"][1:])):
296
+ continue
297
+ for target in indexes[1][0]:
298
+ if not target["supported"]:
299
+ continue
300
+ required = [p for p in target["parameters"] if p["required"]]
301
+ pattern = ("direct" if len(required) == 1 else "fields" if len(required) == 2
302
+ and source["return_shape"] == "dict" and source["return_keys"] else None)
303
+ if pattern is None:
304
+ continue
305
+ score, evidence = _score(source, target, pattern)
306
+ candidates.append({"pattern": pattern, "score": score, "score_kind": "ranking_evidence_not_probability",
307
+ "contributions": evidence, "source": {k: source[k] for k in ("module", "path", "name", "closure")},
308
+ "target": {k: target[k] for k in ("module", "path", "name", "closure")},
309
+ "target_required": [p["name"] for p in required], "available_fields": source["return_keys"],
310
+ "mapping_suggestion": ({required[0]["name"]: "$output"} if pattern == "direct" else
311
+ {p["name"]: p["name"] for p in required
312
+ if p["name"] in source["return_keys"]}),
313
+ "requires_confirmation": True, "verified": False})
314
+ candidates.sort(key=lambda c: (-c["score"], c["source"]["path"], c["source"]["name"],
315
+ c["target"]["path"], c["target"]["name"]))
316
+ for i, candidate in enumerate(candidates):
317
+ candidate["id"] = i
318
+ return {"schema_version": 24, "goal": goal, "proposed": True, "verified": False,
319
+ "sources": [{"url": a.source, "commit": a.commit, "content_sha256": a.content_sha256,
320
+ "file_sha256": a.file_sha256, "kind": a.provenance} for a in (left, right)],
321
+ "indexes": [x[0] for x in indexes], "rejected_modules": [x[1] for x in indexes],
322
+ "candidates": candidates, "risk_flags": ["AST cannot establish semantic correctness"]}
323
+
324
+
325
+ def stage_graph(root: Path, analysis: Analysis, selected: dict, target: Path):
326
+ modules = _modules(analysis)
327
+ for name in selected["closure"]:
328
+ path = modules[name]
329
+ parts = list(Path(path).parts)
330
+ if parts[0] == "src":
331
+ parts.pop(0)
332
+ _copy_checked(root, path, target.joinpath(*parts), analysis.file_sha256[path])
333
+ for n in range(1, len(parts)):
334
+ parent = Path("src") if path.startswith("src/") else Path()
335
+ init = (parent / Path(*parts[:n]) / "__init__.py").as_posix()
336
+ if init in analysis.file_sha256:
337
+ _copy_checked(root, init, target / Path(*parts[:n]) / "__init__.py", analysis.file_sha256[init])
338
+ return selected["module"]
stacklatch/v25.py ADDED
@@ -0,0 +1,156 @@
1
+ """Deterministic goal-only ranking on a canonical V2.4 AST package graph.
2
+
3
+ Ordinal evidence is never a probability. The code never imports repository
4
+ source on the host and a proposal is never marked verified by this module.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import hashlib
9
+ import json
10
+ import re
11
+ from typing import Any
12
+
13
+ from .core import InspectionError
14
+ from .v23 import _expanded, _ratio, _stem, _words
15
+
16
+ MAX_RANKED = 50
17
+ MAX_GOAL = 512
18
+ STOP = frozenset("a an the as and into its it then from in of to for with text phrase word words input output result return calculate convert turn make".split())
19
+ ALIASES = {
20
+ "url": {"slug"}, "safe": {"slug"}, "slugify": {"slug"},
21
+ "dashed": {"kebab", "dash"}, "hyphenated": {"kebab", "dash"},
22
+ "pieces": {"list", "piece"}, "join": {"cast", "join"},
23
+ "character": {"char", "character"}, "characters": {"char", "character"},
24
+ "syllable": {"syllable"}, "syllables": {"syllable"},
25
+ "token": {"word", "token"}, "tokens": {"word", "token"},
26
+ "lowercase": {"lower", "lowercase"}, "analyze": {"analyze", "stat"},
27
+ "line": {"line"}, "lines": {"line"},
28
+ }
29
+ UNSUPPORTED = frozenset("translate translation french german sentiment palindrome forecast predict currency fahrenheit celsius".split())
30
+ NEGATION = frozenset("not never without avoid exclude".split())
31
+ VAGUE = frozenset("something anything useful somehow various".split())
32
+
33
+
34
+ def _terms(value: str) -> set[str]:
35
+ return {_stem(x) for x in _words(value)}
36
+
37
+
38
+ def _hits(goal_terms: set[str], reference: str) -> list[str]:
39
+ names = _terms(reference)
40
+ return sorted(t for t in goal_terms if t not in STOP and
41
+ (t in names or bool(ALIASES.get(t, set()) & names)
42
+ or (len(t) >= 4 and any(n.startswith(t) for n in names))))
43
+
44
+
45
+ def _contract(annotation: str, shape: str) -> dict[str, Any]:
46
+ ann = annotation.lower()
47
+ if ann in {"str", "builtins.str"} or shape == "str":
48
+ return {"type": "string", "maxLength": 8192}
49
+ if ann == "int" or shape == "int":
50
+ return {"type": "integer"}
51
+ if ann in {"float", "number"} or shape == "number":
52
+ return {"type": "number"}
53
+ if ann.startswith("list") or shape == "list":
54
+ return {"type": "array", "items": "unknown; explicit schema required"}
55
+ if ann.startswith("dict") or shape == "dict":
56
+ return {"type": "object", "properties": "unknown; explicit schema required"}
57
+ return {"type": "unknown; explicit schema required"}
58
+
59
+
60
+ def _index(proposal, side, candidate):
61
+ return next(x for x in proposal["indexes"][side]
62
+ if x["path"] == candidate["path"] and x["name"] == candidate["name"])
63
+
64
+
65
+ def _canonical_digest(proposal: dict) -> str:
66
+ return hashlib.sha256(json.dumps(proposal, sort_keys=True, separators=(",", ":"),
67
+ ensure_ascii=False).encode("utf-8")).hexdigest()
68
+
69
+
70
+ def select_goal(proposal: dict[str, Any]) -> dict[str, Any]:
71
+ goal = proposal.get("goal")
72
+ if (not isinstance(goal, str) or not 0 < len(goal.strip()) <= MAX_GOAL
73
+ or proposal.get("schema_version") != 24 or not proposal.get("proposed")):
74
+ raise InspectionError("A bounded canonical V2.4 proposal is required")
75
+ tokens = _terms(goal)
76
+ ratio = _ratio(goal)
77
+ before, divider, after = goal.lower().partition("then")
78
+ left_terms = _terms(before) if divider else tokens
79
+ right_terms = _terms(after) if divider else tokens
80
+ results = []
81
+ for candidate in _expanded(proposal):
82
+ source = _index(proposal, 0, candidate["source"])
83
+ target = _index(proposal, 1, candidate["target"])
84
+ src_ref = source["name"] + " " + source["module"].replace(".", " ") + " " + source["docstring"][:256]
85
+ dst_ref = target["name"] + " " + target["module"].replace(".", " ") + " " + target["docstring"][:256]
86
+ src_hits = _hits(left_terms, src_ref)
87
+ dst_hits = _hits(right_terms, dst_ref)
88
+ # Filename evidence is weaker than callable name/docstring evidence.
89
+ src_path_hits = _hits(left_terms, source["path"])
90
+ dst_path_hits = _hits(right_terms, target["path"])
91
+ evidence = [{"kind": "source_interface", "tokens": src_hits, "location": f"{source['path']}:{source['line']}"},
92
+ {"kind": "target_interface", "tokens": dst_hits, "location": f"{target['path']}:{target['line']}"}]
93
+ score = 11 * len(src_hits) + 14 * len(dst_hits) + 2 * (len(src_path_hits) + len(dst_path_hits))
94
+ if divider and dst_hits:
95
+ score += 6
96
+ evidence.append({"kind": "explicit_target_order", "tokens": dst_hits})
97
+ requested_output = re.search(r"\binto\s+(?:a|an|the)?\s*([^,]+?)(?:,|\s+then\b|$)", before)
98
+ if requested_output:
99
+ result_hits = _hits(_terms(requested_output[1]), source["name"])
100
+ if result_hits:
101
+ score += 30
102
+ evidence.append({"kind": "explicit_source_result", "tokens": result_hits,
103
+ "location": f"{source['path']}:{source['line']}"})
104
+ binding = candidate["mapping"]
105
+ mapping_valid = True
106
+ if candidate["pattern"] == "fields":
107
+ ordered = list(binding.values())
108
+ mapping_valid = bool(ratio and len(ordered) == 2
109
+ and ratio[0] in _terms(ordered[0])
110
+ and ratio[1] in _terms(ordered[1])
111
+ and ("div" in target["name"] or "ratio" in target["name"]))
112
+ if mapping_valid:
113
+ score += 55
114
+ evidence.append({"kind": "ordered_field_binding", "numerator": ratio[0],
115
+ "denominator": ratio[1], "mapping": binding,
116
+ "source_location": f"{source['path']}:{source['line']}"})
117
+ input_hint = _contract(source["parameters"][0]["annotation"], "unknown")
118
+ intermediate_hint = _contract("unknown", source["return_shape"])
119
+ output_hint = _contract("unknown", target["return_shape"])
120
+ results.append({**candidate, "rank": 0, "ranking_score": score,
121
+ "score_kind": "ordinal_evidence_not_probability", "evidence": evidence,
122
+ "mapping_evidenced": mapping_valid,
123
+ "contract_hints": {"input": input_hint, "intermediate": intermediate_hint,
124
+ "output": output_hint},
125
+ "uncertainty": "AST and lexical evidence do not establish semantics or concrete schemas",
126
+ "verified": False, "requires_confirmation": True})
127
+ results.sort(key=lambda x: (-x["ranking_score"], -x["structural_score"],
128
+ x["source"]["path"], x["source"]["name"],
129
+ x["target"]["path"], x["target"]["name"],
130
+ tuple(sorted(x["mapping"].items()))))
131
+ for i, item in enumerate(results):
132
+ item["rank"] = i + 1
133
+ reason = None
134
+ if tokens & UNSUPPORTED:
135
+ reason = "Unsupported domain or unit transformation; no conversion is evidenced"
136
+ elif tokens & NEGATION:
137
+ reason = "Negated or contradictory request requires explicit clarification"
138
+ elif tokens & VAGUE:
139
+ reason = "Goal does not specify a testable transformation"
140
+ elif not results or not results[0]["mapping_evidenced"]:
141
+ reason = "No evidenced complete argument binding"
142
+ elif (not results[0]["evidence"][0]["tokens"] or
143
+ not (results[0]["evidence"][1]["tokens"] or
144
+ any(e["kind"] == "ordered_field_binding" for e in results[0]["evidence"]))):
145
+ reason = "Insufficient evidence for both source and target roles"
146
+ elif results[0]["ranking_score"] < 25:
147
+ reason = "Insufficient interface evidence"
148
+ elif len(results) > 1 and results[0]["ranking_score"] == results[1]["ranking_score"]:
149
+ reason = "Equal evidence for multiple complete mappings"
150
+ selected = None if reason else results[0]
151
+ return {"schema_version": 25, "goal": goal, "sources": proposal["sources"],
152
+ "proposal_sha256": _canonical_digest(proposal), "candidate_count": len(results),
153
+ "candidates": results[:MAX_RANKED], "selected": selected,
154
+ "abstained": reason is not None, "abstention_reason": reason,
155
+ "verified": False, "risk_flags": proposal["risk_flags"] +
156
+ ["Schema hints and lexical rankings require confirmation and independent Docker oracles"]}