scientific-method-engine 8.0.0__tar.gz → 8.1.0__tar.gz

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.
Files changed (70) hide show
  1. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/PKG-INFO +9 -1
  2. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/README.md +8 -0
  3. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/cli.py +2 -0
  5. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/memory_scopes.py +18 -1
  6. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/trace.py +91 -29
  7. scientific_method_engine-8.1.0/tests/test_interrupt_models.py +219 -0
  8. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_relational_controls.py +67 -0
  9. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/.gitignore +0 -0
  10. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/LICENSE +0 -0
  11. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/__init__.py +0 -0
  12. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/__main__.py +0 -0
  13. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  14. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  15. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  16. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  17. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  18. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  19. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  20. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  21. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  22. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  23. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  24. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  25. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  26. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  27. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  28. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  29. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  30. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  31. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  32. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  33. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  34. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  35. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  36. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  37. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  38. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  39. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  40. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  41. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  42. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  43. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  44. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  45. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  46. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  47. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  48. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  49. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  50. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/machine.py +0 -0
  51. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  52. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  53. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  54. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/relational.py +0 -0
  55. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/reports.py +0 -0
  56. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  57. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  58. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/oracle.py +0 -0
  59. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_continuation_budget.py +0 -0
  60. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_dispatch.py +0 -0
  61. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_effect_order.py +0 -0
  62. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_entry_frame.py +0 -0
  63. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_loops.py +0 -0
  64. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_memory_scopes.py +0 -0
  65. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_nested_frame_request.py +0 -0
  66. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_oracle.py +0 -0
  67. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_pe.py +0 -0
  68. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_successor_rule.py +0 -0
  69. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_table_continuations.py +0 -0
  70. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.0}/tests/test_x86.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 8.0.0
3
+ Version: 8.1.0
4
4
  Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
5
5
  Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
6
6
  Author: kibertoad
@@ -145,6 +145,14 @@ boundary and continuation limits remain explicit gaps or stops. Partial-table sp
145
145
  partial evidence, never complete dispatch or native-reachability claims. See the
146
146
  [table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
147
147
 
148
+ A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
149
+ still reported as a hardware boundary with its vector, the handler is not executed, and each case
150
+ returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
151
+ the model does not preserve or set are unknown. `leavesFlags: true` describes a service that returns
152
+ with a far return and leaves the interrupt's FLAGS word on the stack. Without a model, and at INT1,
153
+ INT3 (in either encoding), INTO or any PE32 interrupt, the path stops at the interrupt as before. See
154
+ [ADR 0017](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/decisions/0017-call-models-at-interrupt-sites.md).
155
+
148
156
  A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
149
157
  segment register, an address-width base register, an optional displacement, a byte count and the
150
158
  evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
@@ -129,6 +129,14 @@ boundary and continuation limits remain explicit gaps or stops. Partial-table sp
129
129
  partial evidence, never complete dispatch or native-reachability claims. See the
130
130
  [table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
131
131
 
132
+ A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
133
+ still reported as a hardware boundary with its vector, the handler is not executed, and each case
134
+ returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
135
+ the model does not preserve or set are unknown. `leavesFlags: true` describes a service that returns
136
+ with a far return and leaves the interrupt's FLAGS word on the stack. Without a model, and at INT1,
137
+ INT3 (in either encoding), INTO or any PE32 interrupt, the path stops at the interrupt as before. See
138
+ [ADR 0017](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/decisions/0017-call-models-at-interrupt-sites.md).
139
+
132
140
  A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
133
141
  segment register, an address-width base register, an optional displacement, a byte count and the
134
142
  evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  name = "scientific-method-engine"
7
7
  # The release workflow writes the published version from the package's release tag.
8
- version = "8.0.0"
8
+ version = "8.1.0"
9
9
  description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.12"
@@ -27,6 +27,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
27
27
  "Declared table continuations are separate conditional paths that spend continuationBudget\n"
28
28
  "(paths, totalSteps, maxSteps, visitLimit, stringIterations); ordinary computed transfers remain stopped.\n"
29
29
  "Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
30
+ "A callModels entry at an INT n site (real mode) returns past the interrupt under its cases (leavesFlags: true\n"
31
+ "keeps the interrupt's FLAGS word on the stack); other interrupts stop.\n"
30
32
  "callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
31
33
  "A scope needs a concrete segment; its base may be symbolic, such as BP in an entryFrame query.\n"
32
34
  "Each traced path's loops record lists restart edges and what changed between iterations (loopIterationLimit).\n"
@@ -56,7 +56,7 @@ def validate_scopes(model, bits, flat):
56
56
  ranges.append((displacement, displacement + size))
57
57
 
58
58
 
59
- def capture_scopes(state, model):
59
+ def capture_scopes(state, model, frame_bytes=0):
60
60
  """Resolve each scope against the pre-call state and snapshot its bytes.
61
61
 
62
62
  Returns ``(values, unread, descriptions)``: the cached bytes, the unknown term names of bytes
@@ -68,8 +68,23 @@ def capture_scopes(state, model):
68
68
  share a linear byte (segment aliases included). A symbolic base may address any byte of its
69
69
  segment, so it may alias every scope whose segment range overlaps that segment. An uncached
70
70
  byte stays uncached after the call.
71
+
72
+ ``frame_bytes`` is the size of the return frame the processor writes below SS:SP when the modeled
73
+ instruction runs: the return address of a call, or FLAGS, CS and IP of an interrupt. Those bytes
74
+ no longer hold their pre-call values, so a scope that shares a byte with that frame on the same
75
+ segment and base raises ``StopPath``. A scope that only may alias the frame stays the query's
76
+ hypothesis.
71
77
  """
72
78
  values, unread, descriptions, resolved = {}, {}, [], []
79
+ frame = None
80
+ if frame_bytes:
81
+ try:
82
+ frame_seg, frame_base, _, frame_keys = state.keys(
83
+ state.segment("ss"), op("sub", state.reg(state.sp), const(frame_bytes, state.bits)), frame_bytes)
84
+ frame = ((frame_seg, frame_base), set(frame_keys))
85
+ except StopPath:
86
+ # A frame that wraps past offset zero of the stack segment is not checked.
87
+ frame = None
73
88
  for scope in model.get("preservesMemory", []):
74
89
  segment, base = state.segment(scope["segment"]), state.reg(scope["base"])
75
90
  if segment.number is None:
@@ -91,6 +106,8 @@ def capture_scopes(state, model):
91
106
  shared = domains_may_overlap(prior_domain, domain)
92
107
  if shared:
93
108
  raise StopPath("preservesMemory intervals overlap or alias")
109
+ if frame is not None and frame[0] == (seg, group_base) and not frame[1].isdisjoint(keys):
110
+ raise StopPath("preservesMemory scope covers the return frame the processor writes below SP")
94
111
  resolved.append(((seg, group_base), set(keys), domain))
95
112
  linear = seg == ("linear",)
96
113
  cached = 0
@@ -10,6 +10,7 @@ from .values import const, unknown, sources, op, Value
10
10
  from .result_flow import validate_contracts, result_contracts
11
11
  from .loops import LoopTracker
12
12
  from .memory_scopes import validate_scopes, capture_scopes, retain_scopes, scope_history
13
+ from .pcode_backend import interrupt_vector
13
14
 
14
15
  def call_target(image, site, ins):
15
16
  if ins.mnemonic in ("lcall", "ljmp"):
@@ -27,6 +28,19 @@ PORTS = ("in", "out", "insb", "insw", "insd", "outsb", "outsw", "outsd")
27
28
  PORT_INPUTS = ("in", "insb", "insw", "insd")
28
29
 
29
30
 
31
+ def modeled_interrupt(image, ins, site):
32
+ """The vector of the ``INT n`` at ``site`` that a call model there describes, or None.
33
+
34
+ Only an ``INT n`` in the real-mode model takes a model. INT1, INT3 (also when encoded as
35
+ ``INT 1`` or ``INT 3``), INTO and every interrupt in the PE32 flat model keep stopping the path,
36
+ with or without a model at their site (ADR 0017). The vector can be 0, so test it against None.
37
+ """
38
+ if ins is None or ins.mnemonic != "int" or image.flat:
39
+ return None
40
+ vector, _ = interrupt_vector(image.flat, ins, site)
41
+ return None if vector in (1, 3) else vector
42
+
43
+
30
44
  def base_mnemonic(ins):
31
45
  # Capstone names REP/REPNE/BND prefixes in the mnemonic ("repz ret", "rep insb", "bnd jmp").
32
46
  return ins.mnemonic.split()[-1]
@@ -453,6 +467,11 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
453
467
  raise ValueError("A model requires 1..16 return cases")
454
468
  if "returnBytes" in model and (type(model["returnBytes"]) is not int or model["returnBytes"] not in (2, 4)):
455
469
  raise ValueError("Modeled returnBytes must be 2 or 4")
470
+ if "returnBytes" in model and modeled_interrupt(image, image.decode(model["site"]), model["site"]) is not None:
471
+ raise ValueError("An interrupt model takes no returnBytes: the interrupt returns past its own FLAGS, CS and IP")
472
+ if "leavesFlags" in model and (model["leavesFlags"] is not True
473
+ or modeled_interrupt(image, image.decode(model["site"]), model["site"]) is None):
474
+ raise ValueError("leavesFlags must be true and needs an INT n site in the real-mode model")
456
475
  if any(r not in REGISTERS for r in model.get("preserves", [])):
457
476
  raise ValueError("Model preserves must name full registers")
458
477
  validate_scopes(model, image.bits, image.flat)
@@ -460,6 +479,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
460
479
  for r, n in case.get("registers", {}).items():
461
480
  if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
462
481
  raise ValueError("Invalid model register")
482
+ model_at = {model["site"]: model for model in models}
463
483
  explicit_continuation_budget = validate_continuation_budget(config)
464
484
  observed_frame = entry_frame(image, config, entry) if arrive is None else None
465
485
  root = State(entry, image, config)
@@ -515,6 +535,52 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
515
535
  gap["callStack"] = open_calls(s)
516
536
  global_gaps.append(gap)
517
537
 
538
+ def capture_model_scopes(s, model, frame_bytes):
539
+ # Scopes resolve against the state before the modeled instruction runs. frame_bytes is the
540
+ # return frame the processor writes below SP, which no scope may claim to preserve.
541
+ values, unread, scopes = capture_scopes(s, model, frame_bytes)
542
+ return values, unread, scopes, scope_history(s, values, unread)
543
+
544
+ def model_returns(s, model, captured, following, assumption, limit_reason, target, **marks):
545
+ # One child per case, each a conditional return under the query's model. ``marks`` extend
546
+ # the conditionalModels entry and the modeled call-return event (an interrupt's vector).
547
+ nonlocal created
548
+ at = s.at
549
+ kept_values, kept_unread, preserved_scopes, kept_history = captured
550
+ for case in model["cases"]:
551
+ if created >= max_paths:
552
+ path_limit(at, s, limit_reason)
553
+ break
554
+ child = deepcopy(s)
555
+ created += 1
556
+ for r in REGISTERS:
557
+ if r not in model.get("preserves", []) and r not in ("esp", "cs"):
558
+ child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
559
+ child.clear_memory()
560
+ retain_scopes(child, kept_values, kept_unread, kept_history)
561
+ if model.get("leavesFlags"):
562
+ # The handler returned with a far return over the interrupt's FLAGS word, which stays on
563
+ # the stack. Its word is the pre-interrupt FLAGS snapshot, so a later POPF restores them.
564
+ child.save_flags(16)
565
+ child.forget_flags()
566
+ child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
567
+ child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
568
+ for r, n in case.get("registers", {}).items():
569
+ child.setreg(r, const(n, ALIASES[r][2], at), at)
570
+ child.conditional.append({"site": at, "evidence": model["evidence"], **marks,
571
+ "assumption": assumption + "; memory effects unresolved"
572
+ + (" outside explicit scopes" if preserved_scopes else ""),
573
+ "preservedMemoryScopes": preserved_scopes})
574
+ # The scopes are reported once, on the path's conditionalModels entry; the event cites its index.
575
+ child.event("call-return", callSite=at, callerEntry=s.frames[-1]["entry"],
576
+ # A modeled call's result contracts are its target's; an interrupt's target is None,
577
+ # which no contract names.
578
+ resultContracts=result_contracts(child, contracts, target),
579
+ registers=snapshot(child), modeled=True, **marks,
580
+ unknownMemoryEffects=True, conditionalModel=len(child.conditional) - 1)
581
+ child.at = following
582
+ pending.append(child)
583
+
518
584
  def finish(s, reason=None, returned=False):
519
585
  if continuing and reason and reason.startswith(STRING_BUDGET_STOP):
520
586
  # machine.py names no budget; a continuation's string iterations come from continuationBudget.
@@ -712,6 +778,27 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
712
778
  string_step(state, ins, count)
713
779
  state.at = following
714
780
  continue
781
+ interrupt_model = model_at.get(at) if m == "int" else None
782
+ vector = modeled_interrupt(image, ins, at) if interrupt_model else None
783
+ if vector is not None:
784
+ # The handler is not executed. The boundary event is kept, and each case returns to the
785
+ # next instruction under the query's model, with CS as before the interrupt and SP as before it or,
786
+ # under leavesFlags, one FLAGS word below (ADR 0017).
787
+ # Scopes resolve first, so a path that stops on them reports the boundary unmodeled.
788
+ try:
789
+ captured = capture_model_scopes(state, interrupt_model, 6)
790
+ except StopPath:
791
+ state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector,
792
+ interpretation="the interrupt handler and its effects are not modeled")
793
+ raise
794
+ state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector, modeled=True,
795
+ interpretation="the interrupt handler is not executed; a callModels case supplies its return")
796
+ model_returns(state, interrupt_model, captured, following,
797
+ "interrupt returns to the next instruction with its FLAGS word left on the stack and CS unchanged"
798
+ if interrupt_model.get("leavesFlags") else
799
+ "interrupt returns to the next instruction with balanced stack and CS unchanged",
800
+ "path limit at modeled interrupt", None, boundary="interrupt", vector=vector)
801
+ break
715
802
  if m in ("call", "lcall"):
716
803
  target, provenance = call_target(image, at, ins)
717
804
  indirect_value = None
@@ -730,7 +817,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
730
817
  push_cs = (not image.flat and m == "call" and previous is not None and previous.mnemonic == "push"
731
818
  and previous.size + state.path[-2] == at and previous.operands[0].type == X86_OP_REG
732
819
  and previous.reg_name(previous.operands[0].reg) == "cs" and previous.operands[0].size == 2)
733
- model = next((x for x in models if x["site"] == at), None)
820
+ model = model_at.get(at)
734
821
  if model:
735
822
  return_bytes = model.get("returnBytes", 4 if m == "lcall" else image.bits // 8)
736
823
  # The encoding before the call decides validity; a path that reaches the call
@@ -745,38 +832,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
745
832
  raise StopPath("push-CS/near-call model requires an explicit four-byte return contract")
746
833
  # Scopes resolve against the pre-call state: before the modeled frame consumes an
747
834
  # already-pushed CS word and before a case replaces registers.
748
- kept_values, kept_unread, preserved_scopes = capture_scopes(state, model)
749
- kept_history = scope_history(state, kept_values, kept_unread)
835
+ captured = capture_model_scopes(state, model, 4 if m == "lcall" else image.bits // 8)
750
836
  if push_cs:
751
837
  actual_cs = state.pop(2)
752
838
  if actual_cs.term != state.reg("cs").term:
753
839
  raise StopPath("modeled far return segment changed")
754
- for case in model["cases"]:
755
- if created >= max_paths:
756
- path_limit(at, state, "path limit at modeled call")
757
- break
758
- child = deepcopy(state)
759
- created += 1
760
- for r in REGISTERS:
761
- if r not in model.get("preserves", []) and r not in ("esp", "cs"):
762
- child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
763
- child.clear_memory()
764
- retain_scopes(child, kept_values, kept_unread, kept_history)
765
- child.forget_flags()
766
- child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
767
- child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
768
- for r, n in case.get("registers", {}).items():
769
- child.setreg(r, const(n, ALIASES[r][2], at), at)
770
- child.conditional.append({"site": at, "evidence": model["evidence"],
771
- "assumption": "call returns with balanced stack; memory effects unresolved"
772
- + (" outside explicit scopes" if preserved_scopes else ""),
773
- "preservedMemoryScopes": preserved_scopes})
774
- # The scopes are reported once, on the path's conditionalModels entry; the event cites its index.
775
- child.event("call-return", callSite=at, callerEntry=state.frames[-1]["entry"],
776
- resultContracts=result_contracts(child, contracts, target), registers=snapshot(child), modeled=True,
777
- unknownMemoryEffects=True, conditionalModel=len(child.conditional) - 1)
778
- child.at = following
779
- pending.append(child)
840
+ model_returns(state, model, captured, following, "call returns with balanced stack",
841
+ "path limit at modeled call", target)
780
842
  break
781
843
  if target is None:
782
844
  raise StopPath("unresolved call: " + provenance.get("reason", "outside mapped code"))
@@ -0,0 +1,219 @@
1
+ """Call models at INT n sites (ADR 0017), over synthetic real-mode code. No original bytes or claims."""
2
+ import unittest
3
+
4
+ from test_x86 import Code, report
5
+ from test_pe import CODE_RAW, Code as FlatCode, report as flat_report
6
+
7
+ FRAME = {"ds": 0x2000, "ss": 0x3000, "sp": 0xff00}
8
+
9
+
10
+ def model(site, cases=({},), **extra):
11
+ return {"site": site, "evidence": "synthetic interrupt service hypothesis", "cases": list(cases), **extra}
12
+
13
+
14
+ def control(name, kind, **fields):
15
+ return {"name": name, "kind": kind, **fields}
16
+
17
+
18
+ def verdict(result, name):
19
+ return next(c for c in result["relationalControls"]["controls"] if c["name"] == name)
20
+
21
+
22
+ def wrapper_case(test="a8 01"):
23
+ """A caller passes one far scratch pointer twice to a wrapper around INT 33h.
24
+
25
+ The wrapper stores CX then DX through the two pointers and copies BX to AX; the caller reads
26
+ the scratch word into CX and tests bit zero of AL (``test``), or of CL to test the scratch word.
27
+ """
28
+ c = (Code().emit("1e b8 40 00 50 1e 50").branch("e8", "wrapper").emit("83 c4 08")
29
+ .label("scratch").emit("8b 0e 40 00").label("test").emit(test).branch("74", "zero").emit("c3")
30
+ .label("zero").emit("c3")
31
+ .label("wrapper").emit("55 89 e5").label("int").emit("cd 33")
32
+ .emit("c4 7e 04").label("first").emit("26 89 0d").emit("c4 7e 08").label("second").emit("26 89 15")
33
+ .emit("89 d8 5d c3"))
34
+ frame = {"segment": "ss", "base": "bp", "bytes": 12, "evidence": "synthetic saved BP, return word and four argument words"}
35
+ service = model(c.labels["int"], [{"registers": {"cx": 5, "dx": 7}}], preserves=["ds", "ss", "ebp"],
36
+ preservesMemory=[frame])
37
+ return c, service
38
+
39
+
40
+ class InterruptModelTests(unittest.TestCase):
41
+ def test_each_case_returns_past_the_interrupt_with_its_boundary_kept(self):
42
+ r = report("cd 21 c3", "effects", registers=FRAME, callModels=[model(0, [{"registers": {"ax": 0}}, {"registers": {"ax": 1}}])])
43
+ self.assertTrue(r["completeWithinModel"])
44
+ self.assertEqual(sorted(p["registers"]["ax"]["value"] for p in r["paths"]), [0, 1])
45
+ for path in r["paths"]:
46
+ self.assertTrue(path["returned"])
47
+ boundary = next(e for e in path["events"] if e["kind"] == "hardware-boundary")
48
+ self.assertEqual((boundary["boundary"], boundary["vector"], boundary["modeled"]), ("interrupt", 0x21, True))
49
+ returned = next(e for e in path["events"] if e["kind"] == "call-return")
50
+ self.assertEqual((returned["callSite"], returned["boundary"], returned["vector"]), (0, "interrupt", 0x21))
51
+ self.assertTrue(returned["modeled"] and returned["unknownMemoryEffects"])
52
+ self.assertEqual(returned["resultContracts"], [])
53
+ entry = path["conditionalModels"][returned["conditionalModel"]]
54
+ self.assertEqual((entry["site"], entry["boundary"], entry["vector"]), (0, "interrupt", 0x21))
55
+ self.assertTrue(entry["assumption"].startswith("interrupt returns to the next instruction"))
56
+ self.assertEqual(entry["preservedMemoryScopes"], [])
57
+ # Unpreserved registers come back unknown, and SP is as before the interrupt.
58
+ self.assertIsNone(path["registers"]["bx"]["value"])
59
+ self.assertEqual(path["registers"]["sp"]["value"], FRAME["sp"])
60
+ self.assertEqual(r["hardwareBoundaries"][0]["placement"], "everyTracedPath")
61
+ summary = r["effectOrdering"]["paths"][0]
62
+ self.assertEqual(len(summary["hardwareBoundaryOrders"]), 1)
63
+ self.assertEqual(summary["calls"], [])
64
+ self.assertFalse(summary["effectCompleteWithinModel"])
65
+ self.assertEqual(r["effectOrdering"]["nativeReachability"], "unconfirmed")
66
+
67
+ def test_without_a_model_the_interrupt_still_stops_the_path(self):
68
+ c, service = wrapper_case()
69
+ for models in ([], [model(c.labels["first"])]):
70
+ r = report(c, registers=FRAME, callModels=models)
71
+ self.assertEqual(r["paths"][0]["stop"], "interrupt handler is not modeled; later effects are not read")
72
+
73
+ def test_a_model_at_int3_into_or_a_pe32_interrupt_is_not_consumed(self):
74
+ unmodeled = "interrupt handler is not modeled; later effects are not read"
75
+ # INT 1 and INT 3 written as INT n are the same debug traps as INT1 and INT3.
76
+ for code, stop in (("cc c3", unmodeled), ("f1 c3", unmodeled), ("cd 03 c3", unmodeled), ("cd 01 c3", unmodeled),
77
+ ("ce c3", "Unsupported instruction semantics: into")):
78
+ r = report(code, registers=FRAME, callModels=[model(0)])
79
+ self.assertEqual(r["paths"][0]["stop"], stop, code)
80
+ self.assertEqual(r["paths"][0]["conditionalModels"], [])
81
+ r = flat_report(FlatCode().emit("cd 2e c3"), callModels=[model(CODE_RAW)])
82
+ self.assertFalse(r["paths"][0]["returned"])
83
+ self.assertEqual(r["paths"][0]["conditionalModels"], [])
84
+
85
+ def test_an_interrupt_model_rejects_return_bytes(self):
86
+ for width in (2, 4):
87
+ with self.assertRaisesRegex(ValueError, "interrupt model takes no returnBytes"):
88
+ report("cd 21 c3", registers=FRAME, callModels=[model(0, returnBytes=width)])
89
+
90
+ def test_a_scope_that_does_not_resolve_stops_with_the_boundary_unmodeled(self):
91
+ scope = {"segment": "ds", "base": "si", "bytes": 2, "evidence": "synthetic scope"}
92
+ r = report("cd 21 c3", registers={"ss": 0x3000, "sp": 0xff00},
93
+ callModels=[model(0, preserves=["ds", "ss"], preservesMemory=[scope])])
94
+ path = r["paths"][0]
95
+ self.assertTrue(path["stop"].startswith("preservesMemory address unresolved"))
96
+ boundary = next(e for e in path["events"] if e["kind"] == "hardware-boundary")
97
+ self.assertEqual((boundary["vector"], "modeled" in boundary), (0x21, False))
98
+ self.assertEqual(path["conditionalModels"], [])
99
+
100
+ def test_leaves_flags_keeps_the_interrupts_flags_word_for_a_later_popf(self):
101
+ # int 25h; popf; ret. The service returns with a far return and leaves FLAGS on the stack.
102
+ r = report("cd 25 9d c3", registers=FRAME, callModels=[model(0, leavesFlags=True)])
103
+ path = r["paths"][0]
104
+ self.assertTrue(path["returned"])
105
+ # The POPF takes the word the interrupt left, so the RET finds SP as before the interrupt.
106
+ self.assertEqual(path["registers"]["sp"]["value"], FRAME["sp"])
107
+ self.assertTrue(path["conditionalModels"][0]["assumption"].startswith(
108
+ "interrupt returns to the next instruction with its FLAGS word left on the stack"))
109
+ saved = next(e for e in path["events"] if e["kind"] == "flags-save")
110
+ restored = next(e for e in path["events"] if e["kind"] == "flags-restore")
111
+ self.assertEqual(saved["value"], restored["value"])
112
+ self.assertTrue(restored["intactLocalSnapshot"])
113
+ # Without it, the POPF takes the caller's word and the RET reads past the caller's frame.
114
+ r = report("cd 25 9d c3", registers=FRAME, callModels=[model(0)])
115
+ self.assertEqual(r["paths"][0]["registers"]["sp"]["value"], FRAME["sp"] + 2)
116
+ restored = next(e for e in r["paths"][0]["events"] if e["kind"] == "flags-restore")
117
+ self.assertFalse(restored["intactLocalSnapshot"])
118
+
119
+ def test_leaves_flags_needs_true_on_an_interrupt_model(self):
120
+ for code, value in (("cd 25 c3", 1), ("cd 25 c3", False), ("e8 00 00 c3", True), ("cd 03 c3", True)):
121
+ with self.assertRaisesRegex(ValueError, "leavesFlags must be true"):
122
+ report(code, registers=FRAME, callModels=[model(0, leavesFlags=value)])
123
+
124
+ def test_a_scope_over_the_frame_the_processor_writes_stops_the_path(self):
125
+ def scope(displacement, size):
126
+ return {"segment": "ss", "base": "sp", "displacement": displacement, "bytes": size, "evidence": "synthetic stack scope"}
127
+ # FLAGS, CS and IP of an interrupt fill SS:SP-6..SP-1; a near call's return address fills SS:SP-2..SP-1.
128
+ for code, displacement, size in (("cd 21 c3", -6, 1), ("cd 21 c3", -2, 4), ("e8 00 00 c3", -2, 1), ("e8 00 00 c3", -4, 8)):
129
+ r = report(code, registers=FRAME, callModels=[model(0, preserves=["ss"], preservesMemory=[scope(displacement, size)])])
130
+ path = r["paths"][0]
131
+ self.assertEqual(path["stop"], "preservesMemory scope covers the return frame the processor writes below SP", code)
132
+ self.assertEqual(path["conditionalModels"], [])
133
+ r = report("cd 21 c3", registers=FRAME, callModels=[model(0, preserves=["ss"], preservesMemory=[scope(-6, 1)])])
134
+ boundary = next(e for e in r["paths"][0]["events"] if e["kind"] == "hardware-boundary")
135
+ self.assertNotIn("modeled", boundary)
136
+ # Bytes at and above SP, and below the frame, stay the query's hypothesis.
137
+ for code, displacement in (("cd 21 c3", 0), ("cd 21 c3", -8), ("e8 00 00 c3", 0), ("e8 00 00 c3", -4)):
138
+ r = report(code, registers=FRAME, callModels=[model(0, preserves=["ss"], preservesMemory=[scope(displacement, 2)])])
139
+ self.assertTrue(r["paths"][0]["returned"], (code, displacement))
140
+
141
+ def test_the_path_limit_drops_cases_at_the_interrupt_as_a_gap(self):
142
+ r = report("cd 21 c3", registers=FRAME, maxPaths=1, callModels=[model(0, [{"registers": {"ax": 0}}, {"registers": {"ax": 1}}])])
143
+ self.assertFalse(r["completeWithinModel"])
144
+ self.assertEqual(len(r["paths"]), 0)
145
+ self.assertEqual(r["gaps"], [{"site": 0, "reason": "path limit at modeled interrupt"}])
146
+
147
+ def wrapper_controls(self, c, writer="second"):
148
+ return [control("later store", "lastWriter", at={"site": c.labels["scratch"], "event": "read"}, writers=[c.labels[writer]]),
149
+ control("predicate", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
150
+ expect={"inputs": {"include": [{"modeledCall": c.labels["int"], "register": "bx"}]}}),
151
+ control("not scratch", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
152
+ expect={"producers": {"exclude": [c.labels["scratch"]]}})]
153
+
154
+ def test_aliased_outputs_and_the_predicate_source_hold_through_a_modeled_interrupt(self):
155
+ c, service = wrapper_case()
156
+ r = report(c, "effects", registers=FRAME, callModels=[service], relationalControls=self.wrapper_controls(c)[:2])
157
+ self.assertTrue(r["completeWithinModel"])
158
+ self.assertTrue(r["relationalControls"]["allHeld"])
159
+ self.assertEqual(verdict(r, "later store")["verdict"], "held")
160
+ self.assertEqual(verdict(r, "predicate")["verdict"], "held")
161
+ # The service register is an unread input, which may hide any producer, so an exclusion stays open.
162
+ r = report(c, registers=FRAME, callModels=[service], relationalControls=self.wrapper_controls(c)[2:])
163
+ excluded = verdict(r, "not scratch")
164
+ self.assertEqual(excluded["verdict"], "undecided")
165
+ self.assertIn("may be hidden by an unread input", excluded["paths"][0]["occurrences"][0]["reason"])
166
+ # Both stores went through the one far address the caller passed twice.
167
+ stores = [e for e in r["paths"][0]["events"] if e["kind"] == "write" and e["site"] in (c.labels["first"], c.labels["second"])]
168
+ self.assertEqual([(e["segment"]["value"], e["offset"]["value"]) for e in stores], [(0x2000, 0x40)] * 2)
169
+ self.assertEqual(verdict(r, "not scratch")["queryAssumptions"]["callModels"], [c.labels["int"]])
170
+ self.assertEqual(len(r["paths"][0]["conditionalModels"][0]["preservedMemoryScopes"]), 1)
171
+
172
+ def test_supplied_predicate_cases_decide_the_branch_each_way(self):
173
+ c, service = wrapper_case()
174
+ service["cases"] = [{"registers": {"bx": 0, "cx": 5, "dx": 7}}, {"registers": {"bx": 1, "cx": 5, "dx": 7}}]
175
+ r = report(c, registers=FRAME, callModels=[service])
176
+ taken = [next(e["taken"] for e in p["events"] if e["kind"] == "branch") for p in r["paths"]]
177
+ self.assertEqual(sorted(taken), [False, True])
178
+ # A case that supplies BX makes it a constant, so the origin control cannot see the service register.
179
+ r = report(c, registers=FRAME, callModels=[service], relationalControls=self.wrapper_controls(c)[1:2])
180
+ self.assertEqual(verdict(r, "predicate")["verdict"], "undecided")
181
+
182
+ def test_unscoped_wrong_writer_wrong_origin_and_capped_controls_do_not_hold(self):
183
+ c, service = wrapper_case()
184
+ # Without the frame scope the pointers and the return word are lost at the interrupt.
185
+ unscoped = {k: v for k, v in service.items() if k != "preservesMemory"}
186
+ r = report(c, registers=FRAME, callModels=[unscoped], relationalControls=self.wrapper_controls(c)[:2])
187
+ self.assertEqual(r["paths"][0]["stop"], "return target was overwritten or has unknown provenance")
188
+ self.assertEqual(verdict(r, "later store")["verdict"], "undecided")
189
+ self.assertFalse(r["relationalControls"]["allHeld"])
190
+ with self.assertRaisesRegex(ValueError, "later store violated"):
191
+ report(c, registers=FRAME, callModels=[service], relationalControls=self.wrapper_controls(c, "first")[:1])
192
+ # A caller that tests the scratch word instead takes its predicate from the scratch read.
193
+ scratch, service = wrapper_case("f6 c1 01")
194
+ for rule in self.wrapper_controls(scratch)[1:]:
195
+ with self.assertRaisesRegex(ValueError, rule["name"] + " violated"):
196
+ report(scratch, registers=FRAME, callModels=[service], relationalControls=[rule])
197
+ c, service = wrapper_case()
198
+ r = report(c, registers=FRAME, callModels=[service], maxSteps=12, relationalControls=self.wrapper_controls(c)[:2])
199
+ self.assertEqual(r["paths"][0]["stop"], "step limit; loop progress unresolved")
200
+ self.assertEqual(verdict(r, "later store")["verdict"], "undecided")
201
+ self.assertEqual(verdict(r, "predicate")["verdict"], "undecided")
202
+
203
+ def test_an_entry_frame_trace_continues_through_a_modeled_interrupt(self):
204
+ # From the wrapper's entry, the frame trace reaches the code after the interrupt only through the model.
205
+ c, service = wrapper_case()
206
+ regions = [{"name": "synthetic", "start": 0, "end": len(c.bytes()), "ip": 0, "segment": 0x1000, "resident": True,
207
+ "entries": [0, c.labels["wrapper"]], "evidence": "synthetic declared code extent"}]
208
+ after = c.labels["int"] + 2
209
+ regions[0]["entries"].append(after)
210
+ for models, established in (([], False), ([service], True)):
211
+ r = report(c, regions=regions, entry=after, entryFrame={"from": c.labels["wrapper"]},
212
+ registers={"ds": 0x2000, "ss": 0x3000}, callModels=models)
213
+ self.assertEqual(r["entryFrame"]["established"], established)
214
+ if established:
215
+ self.assertEqual((r["entryFrame"]["sp"], r["entryFrame"]["bp"]), (-2, -2))
216
+
217
+
218
+ if __name__ == "__main__":
219
+ unittest.main()
@@ -510,6 +510,73 @@ class OriginTests(unittest.TestCase):
510
510
  # Without the case value the call's BX is an unknown input of the value.
511
511
  self.assertEqual(verdict(run(c, [rule], callModels=[{**model, "cases": [{}]}]), "service")["verdict"], "held")
512
512
 
513
+ def reencoding(self):
514
+ # The helper tests its recursive call's AX against FFFF and on a match writes a fresh FFFF;
515
+ # otherwise it returns zero. The recursive call is modeled with the helper's frame kept.
516
+ c = Code().branch("e8", "helper").label("test").emit("83 f8 ff c3")
517
+ c.label("helper").label("recurse").branch("e8", "helper").label("tested").emit("83 f8 ff").label("branch").branch("75", "zero")
518
+ c.label("reencode").emit("b8 ff ff").label("after").branch("eb", "out").label("zero").emit("31 c0").label("out").emit("c3")
519
+ return c
520
+
521
+ def reencoding_query(self, c, controls, case):
522
+ model = {"site": c.labels["recurse"], "evidence": "synthetic recursive return", "preserves": ["ss"],
523
+ "preservesMemory": [{"segment": "ss", "base": "sp", "bytes": 2, "evidence": "synthetic return address"}],
524
+ "cases": [case]}
525
+ checkpoints = [c.labels["after"]] if "after" in c.labels else []
526
+ return run(c, controls, registers={"ss": 0x3000, "sp": 0xff00}, checkpoints=checkpoints,
527
+ returnContracts=self.contracts(c), callModels=[model])
528
+
529
+ def test_a_reencoded_recursive_result_keeps_the_tested_value_the_branch_and_the_local_producer_apart(self):
530
+ c = self.reencoding()
531
+ after = {"site": c.labels["after"], "event": "checkpoint"}
532
+ tested = control("tested", "origin", at={"site": c.labels["tested"], "event": "compare"}, value={"field": "left"},
533
+ expect={"inputs": {"include": [{"modeledCall": c.labels["recurse"], "register": "ax"}]}})
534
+ guarded = control("guarded", "order", at=after, before={"site": c.labels["branch"], "event": "branch"}, branch={"taken": False})
535
+ output = control("output", "origin", at=after, value={"field": "registers.ax"},
536
+ expect={"producers": {"include": [c.labels["reencode"]]}})
537
+ copied = control("copied", "origin", at=after, value={"field": "registers.ax"},
538
+ expect={"inputs": {"include": [{"modeledCall": c.labels["recurse"], "register": "ax"}]}})
539
+ # With the recursive AX unknown, the tested value is the recursive result.
540
+ open_result = self.reencoding_query(c, [tested, guarded, output], {})
541
+ self.assertEqual(verdict(open_result, "tested")["verdict"], "held")
542
+ # The mismatching path passes the modeled recursion without reaching the checkpoint, so
543
+ # controls anchored there stay undecided in this query.
544
+ for name in ("guarded", "output"):
545
+ self.assertEqual(verdict(open_result, name)["verdict"], "undecided", name)
546
+ # The fresh encoding does not carry the recursive value.
547
+ with self.assertRaisesRegex(ValueError, rf"copied violated .* at site {c.labels['after']} .*not among the value's inputs"):
548
+ self.reencoding_query(c, [copied], {})
549
+ # With the encoding supplied, the re-encoding follows the match and its own write produced the output.
550
+ # sameValue holds as well, since the tested value and the fresh constant are the same number.
551
+ same = control("same", "order", at=after, before={"site": c.labels["tested"], "event": "compare"},
552
+ sameValue={"before": "left", "at": "registers.ax"})
553
+ supplied = self.reencoding_query(c, [tested, guarded, output, copied, same], {"registers": {"ax": 0xffff}})
554
+ for name in ("guarded", "output", "same"):
555
+ self.assertEqual(verdict(supplied, name)["verdict"], "held", name)
556
+ for name in ("tested", "copied"):
557
+ self.assertEqual(verdict(supplied, name)["verdict"], "undecided", name)
558
+ # The caller's test reaches the helper's own return as the originating one; the modeled
559
+ # recursive return is not among the returns the value came through.
560
+ caller = control("caller", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
561
+ expect={"originatingReturns": {"entries": [c.labels["helper"]]}, "producers": {"include": [c.labels["reencode"]]}})
562
+ result = verdict(self.reencoding_query(c, [caller], {"registers": {"ax": 0xffff}}), "caller")
563
+ self.assertEqual(result["verdict"], "held")
564
+ returns = result["paths"][0]["occurrences"][0]["returns"]
565
+ self.assertEqual([(r["site"], r["originating"], r["modeled"]) for r in returns], [(c.labels["out"], True, False)])
566
+
567
+ def test_originating_returns_hold_when_a_modeled_recursive_return_supplies_the_value(self):
568
+ # The helper copies its modeled recursive call's AX up unchanged. The modeled return belongs
569
+ # to the helper too, so only the returns' modeled field tells it from the helper's own return.
570
+ c = Code().branch("e8", "helper").label("test").emit("83 f8 ff c3")
571
+ c.label("helper").label("recurse").branch("e8", "helper").label("out").emit("c3")
572
+ caller = control("caller", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
573
+ expect={"originatingReturns": {"entries": [c.labels["helper"]]}})
574
+ result = verdict(self.reencoding_query(c, [caller], {"registers": {"ax": 0xffff}}), "caller")
575
+ self.assertEqual(result["verdict"], "held")
576
+ returns = result["paths"][0]["occurrences"][0]["returns"]
577
+ self.assertEqual([(r["site"], r["originating"], r["modeled"]) for r in returns],
578
+ [(c.labels["recurse"], True, True), (c.labels["out"], False, False)])
579
+
513
580
  def test_originating_returns_need_a_return_contract(self):
514
581
  c = self.recursion()
515
582
  with self.assertRaisesRegex(ValueError, "needs a returnContracts declaration"):