scientific-method-engine 1.0.1__tar.gz → 2.0.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 (60) hide show
  1. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/PKG-INFO +10 -1
  2. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/README.md +9 -0
  3. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/__init__.py +1 -1
  5. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/cli.py +1 -0
  6. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/effect_order.py +9 -4
  7. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/machine.py +17 -3
  8. scientific_method_engine-2.0.0/src/scientific_method_engine/x86/memory_scopes.py +106 -0
  9. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/reports.py +4 -1
  10. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/trace.py +12 -2
  11. scientific_method_engine-2.0.0/tests/test_memory_scopes.py +293 -0
  12. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/tests/test_x86.py +2 -2
  13. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/.gitignore +0 -0
  14. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/LICENSE +0 -0
  15. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/__main__.py +0 -0
  16. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  17. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  18. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  19. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  20. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  21. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  22. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  23. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  24. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  25. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  26. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  27. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  28. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  29. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  30. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  31. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  32. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  33. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  34. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  35. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  36. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  37. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  38. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  39. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  40. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  41. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  42. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  43. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  44. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  45. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  46. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  47. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  48. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  49. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  50. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  51. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  52. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  53. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  54. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/tests/oracle.py +0 -0
  55. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/tests/test_dispatch.py +0 -0
  56. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/tests/test_effect_order.py +0 -0
  57. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/tests/test_nested_frame_request.py +0 -0
  58. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/tests/test_oracle.py +0 -0
  59. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/tests/test_pe.py +0 -0
  60. {scientific_method_engine-1.0.1 → scientific_method_engine-2.0.0}/tests/test_table_continuations.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 1.0.1
3
+ Version: 2.0.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
@@ -128,3 +128,12 @@ Concrete values/field addresses reject inconsistent rows; overlap and shared
128
128
  path/step/visit/total/boundary limits remain explicit. Partial-table splits are
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
+
132
+ A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
133
+ segment register, an address-width base register, an optional displacement, a byte count and the
134
+ evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
135
+ registers. An unknown, wrapping or overlapping interval stops the path. Only the scoped bytes
136
+ survive the model's memory invalidation, and each scope is reported with the model, the modeled
137
+ return and the effect summary. Everything else the service may do stays unknown. This input needs
138
+ prepared protocol 3, so upgrade the reader and the engine together. See the
139
+ [call model contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#limits-and-assumptions).
@@ -112,3 +112,12 @@ Concrete values/field addresses reject inconsistent rows; overlap and shared
112
112
  path/step/visit/total/boundary limits remain explicit. Partial-table splits are
113
113
  partial evidence, never complete dispatch or native-reachability claims. See the
114
114
  [table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
115
+
116
+ A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
117
+ segment register, an address-width base register, an optional displacement, a byte count and the
118
+ evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
119
+ registers. An unknown, wrapping or overlapping interval stops the path. Only the scoped bytes
120
+ survive the model's memory invalidation, and each scope is reported with the model, the modeled
121
+ return and the effect summary. Everything else the service may do stays unknown. This input needs
122
+ prepared protocol 3, so upgrade the reader and the engine together. See the
123
+ [call model contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#limits-and-assumptions).
@@ -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 = "1.0.1"
8
+ version = "2.0.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"
@@ -2,4 +2,4 @@
2
2
 
3
3
  # The reader passes this number with every prepared config it pipes to the engine. A reader and
4
4
  # engine that disagree on it refuse to run instead of exchanging relocation data in another shape.
5
- PREPARED_PROTOCOL = 2
5
+ PREPARED_PROTOCOL = 3
@@ -18,6 +18,7 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
18
18
  "effects includes ordered path writes/calls and local restoration witnesses; transactionality remains unestablished.\n"
19
19
  "callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges.\n"
20
20
  "Declared table continuations are separate conditional paths; ordinary computed transfers remain stopped.\n"
21
+ "callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
21
22
  " scientific-method-engine ghidra-scripts")
22
23
 
23
24
 
@@ -60,7 +60,8 @@ def effect_ordering(report):
60
60
  call = {"order": event["order"], "site": event["site"], "entry": event["entry"],
61
61
  "depth": event["depth"], "target": event.get("target"),
62
62
  "writesBeforeCount": len(writes), "status": "unresolved-or-stopped",
63
- "unknownEffects": True, "continuation": None, "_unknownStart": len(unknown_orders)}
63
+ "unknownEffects": True, "continuation": None, "preservedMemoryScopes": [],
64
+ "_unknownStart": len(unknown_orders)}
64
65
  calls.append(call)
65
66
  pending.setdefault((event["site"], event["depth"]), []).append(call)
66
67
  elif kind == "call-return":
@@ -68,11 +69,14 @@ def effect_ordering(report):
68
69
  if stack:
69
70
  call = stack.pop()
70
71
  modeled = event.get("modeled", False)
72
+ scopes = event.get("preservedMemoryScopes", []) if modeled else []
71
73
  call.update(status="modeled-return" if modeled else "traced-return",
72
74
  unknownEffects=bool(modeled or event.get("unknownMemoryEffects") or len(unknown_orders) > call.pop("_unknownStart")),
73
- returnOrder=event["order"], writesAfterCount=len(writes),
74
- continuation="assumes balanced returning service; its memory/flag effects are unknown" if modeled
75
- else "local callee return reached within the instruction model")
75
+ returnOrder=event["order"], writesAfterCount=len(writes), preservedMemoryScopes=scopes,
76
+ continuation="local callee return reached within the instruction model" if not modeled
77
+ else "assumes balanced returning service; memory outside its preservedMemoryScopes "
78
+ "hypotheses and its flag effects are unknown" if scopes
79
+ else "assumes balanced returning service; its memory/flag effects are unknown")
76
80
  if event.get("modeled") or event.get("unknownMemoryEffects"):
77
81
  unknown_orders.append(event["order"])
78
82
  for call in calls:
@@ -84,6 +88,7 @@ def effect_ordering(report):
84
88
  destination = conditional_summaries if conditional else summaries
85
89
  destination.append({"path": index, "declaredJumpAssumptions": path.get("declaredJumpAssumptions", []), "returned": path["returned"], "stop": boundary,
86
90
  "guards": path["guards"], "timeline": timeline,
91
+ "conditionalModels": path.get("conditionalModels", []),
87
92
  "writeOrders": [w["order"] for w in writes], "calls": calls,
88
93
  "localRestorationWitnesses": witnesses,
89
94
  "effectCompleteWithinModel": bool(path["returned"] and not unknown_orders and not conditional),
@@ -60,6 +60,9 @@ class State:
60
60
  # Keys grouped by (segment, base) so a write scans only groups that can alias it.
61
61
  self.memory_groups = {}
62
62
  self.memory_epoch = 0
63
+ # Bytes a preservesMemory scope kept without a value (ADR 0009): key -> the unknown term
64
+ # name they had before the modeled call. They stay unread: no value, no producer.
65
+ self.unread_memory = {}
63
66
  self.events = []
64
67
  # Value transfers are recorded only for queries that trace declared return results.
65
68
  self.value_transfers = bool(config.get("returnContracts"))
@@ -148,8 +151,17 @@ class State:
148
151
  def clear_memory(self):
149
152
  self.memory.clear()
150
153
  self.memory_groups.clear()
154
+ self.unread_memory.clear()
151
155
  self.memory_epoch += 1
152
156
 
157
+ def unread_term(self, key):
158
+ """Name the unknown term of a byte with no modeled value: a kept scope term or the epoch's."""
159
+ return self.unread_memory.get(key, f"memory:{self.memory_epoch}:{key}")
160
+
161
+ def byte(self, key):
162
+ """The modeled value of one memory byte, or an unknown term produced by the current site."""
163
+ return self.memory[key] if key in self.memory else unknown(self.unread_term(key), 8, self.at)
164
+
153
165
  def reg(self, name):
154
166
  root, low, bits = alias(name)
155
167
  value = extract(self.regs[root], low, bits)
@@ -194,7 +206,7 @@ class State:
194
206
  def peek(self, segment, offset, width):
195
207
  """Inspect modeled memory without reporting an access the program never performed."""
196
208
  _, _, _, keys = self.keys(segment, offset, width)
197
- return join([self.memory.get(key, unknown(f"memory:{self.memory_epoch}:{key}", 8, self.at)) for key in keys])
209
+ return join([self.byte(key) for key in keys])
198
210
 
199
211
  def access(self, segment, offset, width, write=None, role=None, addressing_register=None):
200
212
  seg, base, delta, keys = self.keys(segment, offset, width)
@@ -221,18 +233,20 @@ class State:
221
233
  disjoint = a is not None and b is not None and (a[1] <= b[0] or b[1] <= a[0])
222
234
  if not disjoint:
223
235
  uncertain.append(key)
224
- del self.memory[key]
236
+ self.memory.pop(key, None)
237
+ self.unread_memory.pop(key, None)
225
238
  members.discard(key)
226
239
  if not members:
227
240
  del self.memory_groups[group]
228
241
  for i, key in enumerate(keys):
229
242
  self.memory[key] = extract(write, i * 8, 8)
243
+ self.unread_memory.pop(key, None)
230
244
  self.memory_groups.setdefault((seg, base), set()).update(keys)
231
245
  value = write
232
246
  missing = []
233
247
  else:
234
248
  missing = [i for i, key in enumerate(keys) if key not in self.memory]
235
- value = join([self.memory.get(key, unknown(f"memory:{self.memory_epoch}:{key}", 8, self.at)) for key in keys])
249
+ value = join([self.byte(key) for key in keys])
236
250
  relevant = []
237
251
  for g in self.guards:
238
252
  left = g.get("left", {}).get("expression")
@@ -0,0 +1,106 @@
1
+ """Explicit, bounded memory hypotheses on modeled calls (ADR 0009).
2
+
3
+ A scope is a query hypothesis that a modeled service leaves a named byte range as it was before the
4
+ call. It is evidence-layer bookkeeping: it reads and writes no memory on the path, adds no read or
5
+ write event and computes no instruction value or flag (ADR 0003).
6
+ """
7
+ from .machine import ALIASES, StopPath
8
+ from .values import const
9
+
10
+
11
+ SEGMENTS = ("cs", "ds", "es", "ss", "fs", "gs")
12
+ FIELDS = {"segment", "base", "displacement", "bytes", "evidence"}
13
+ MAX_SCOPES = 32
14
+ MAX_BYTES = 4096
15
+
16
+
17
+ def validate_scopes(model, bits, flat):
18
+ """Check the shape and budgets of a call model's ``preservesMemory`` before tracing.
19
+
20
+ Every model is checked, including one whose call site no path reaches. Raises ``ValueError``
21
+ on a malformed scope, more than 32 scopes or more than 4,096 bytes in total, two scopes on the
22
+ same segment and base whose ranges overlap, or (segmented images) a scope whose segment register
23
+ the model does not preserve: reads after the call could not address it.
24
+ """
25
+ scopes = model.get("preservesMemory", [])
26
+ if not isinstance(scopes, list):
27
+ raise ValueError("preservesMemory must be a list of scopes")
28
+ if len(scopes) > MAX_SCOPES:
29
+ raise ValueError(f"preservesMemory scope limit is {MAX_SCOPES}")
30
+ total, declared = 0, {}
31
+ for scope in scopes:
32
+ if not isinstance(scope, dict) or set(scope) - FIELDS:
33
+ raise ValueError("preservesMemory scope fields are segment, base, displacement, bytes and evidence")
34
+ if scope.get("segment") not in SEGMENTS:
35
+ raise ValueError("preservesMemory segment must name a segment register")
36
+ base = scope.get("base")
37
+ if not isinstance(base, str) or base not in ALIASES or base in SEGMENTS or ALIASES[base][2] != bits:
38
+ raise ValueError("preservesMemory base must be an address-width general register")
39
+ displacement = scope.get("displacement", 0)
40
+ if type(displacement) is not int or not -(1 << (bits - 1)) <= displacement < 1 << (bits - 1):
41
+ raise ValueError("preservesMemory displacement must be a signed address-width integer")
42
+ size = scope.get("bytes")
43
+ if type(size) is not int or not 1 <= size <= MAX_BYTES:
44
+ raise ValueError(f"preservesMemory bytes must be 1..{MAX_BYTES}")
45
+ total += size
46
+ if total > MAX_BYTES:
47
+ raise ValueError(f"preservesMemory total byte limit is {MAX_BYTES}")
48
+ if not isinstance(scope.get("evidence"), str) or not scope["evidence"].strip():
49
+ raise ValueError("preservesMemory scope requires nonempty evidence")
50
+ # The model replaces every unpreserved segment register except CS with an unknown value.
51
+ if not flat and scope["segment"] != "cs" and scope["segment"] not in model.get("preserves", []):
52
+ raise ValueError(f"preservesMemory segment {scope['segment']} must also be listed in the model's preserves")
53
+ ranges = declared.setdefault((scope["segment"], ALIASES[base][0]), [])
54
+ if any(displacement < end and start < displacement + size for start, end in ranges):
55
+ raise ValueError("preservesMemory scopes on one segment and base overlap")
56
+ ranges.append((displacement, displacement + size))
57
+
58
+
59
+ def capture_scopes(state, model):
60
+ """Resolve each scope against the pre-call state and snapshot its bytes.
61
+
62
+ Returns ``(values, unread, descriptions)``: the cached bytes, the unknown term names of bytes
63
+ the model had no value for, and one report entry per scope. Raises ``StopPath`` when a segment
64
+ or base is not concrete, an interval leaves the address space, or two intervals share a linear
65
+ byte (segment aliases included). An uncached byte stays uncached after the call.
66
+ """
67
+ values, unread, descriptions, intervals = {}, {}, [], []
68
+ for scope in model.get("preservesMemory", []):
69
+ segment, base = state.segment(scope["segment"]), state.reg(scope["base"])
70
+ if segment.number is None or base.number is None:
71
+ raise StopPath("preservesMemory address unresolved: segment and base must be concrete before the call")
72
+ displacement = scope.get("displacement", 0)
73
+ offset = base.number + displacement
74
+ size = scope["bytes"]
75
+ if offset < 0 or offset + size > 1 << state.bits:
76
+ raise StopPath("preservesMemory interval crosses the address boundary")
77
+ _, _, _, keys = state.keys(segment, const(offset, state.bits), size)
78
+ start, end = keys[0][2], keys[-1][2] + 1
79
+ if any(start < prior_end and prior_start < end for prior_start, prior_end in intervals):
80
+ raise StopPath("preservesMemory intervals overlap or alias")
81
+ intervals.append((start, end))
82
+ cached = 0
83
+ for key in keys:
84
+ if key in state.memory:
85
+ cached += 1
86
+ values[key] = state.memory[key]
87
+ else:
88
+ unread[key] = state.unread_term(key)
89
+ descriptions.append({
90
+ "segmentRegister": scope["segment"], "segment": segment.report(),
91
+ "baseRegister": scope["base"], "base": base.report(), "displacement": displacement,
92
+ "offset": offset, "linearStart": start, "linearEnd": end, "bytes": size,
93
+ "cachedBytes": cached, "uncachedBytes": size - cached, "evidence": scope["evidence"],
94
+ "meaning": "explicit pre-call memory-preservation hypothesis; memory outside every scope is unknown"})
95
+ return values, unread, descriptions
96
+
97
+
98
+ def retain_scopes(state, values, unread):
99
+ """Put the captured bytes back after the model invalidated memory. Later writes still apply.
100
+
101
+ All scoped keys are concrete linear bytes, so they share one alias group.
102
+ """
103
+ state.memory.update(values)
104
+ state.unread_memory.update(unread)
105
+ if values or unread:
106
+ state.memory_groups.setdefault((("linear",), ("absolute",)), set()).update(values, unread)
@@ -591,7 +591,10 @@ def allocations(report, config):
591
591
  "orderedWrites": [e for e in path["events"][event["order"]+1:] if e["kind"] == "write"],
592
592
  "arithmetic": [e for e in path["events"] if e["kind"] == "arithmetic"],
593
593
  "guards": path["guards"], "pathStop": path["stop"],
594
- "allocatorEffects": "conditional model; memory unresolved" if returns and returns.get("modeled") else "see path writes and unresolved exits",
594
+ "allocatorEffects": ("see path writes and unresolved exits" if not (returns and returns.get("modeled")) else
595
+ "conditional model; memory unresolved outside its preservedMemoryScopes" if returns.get("preservedMemoryScopes") else
596
+ "conditional model; memory unresolved"),
597
+ "preservedMemoryScopes": returns.get("preservedMemoryScopes", []) if returns else [],
595
598
  "extentObservation": extent, "pointerObservation": pointer, "writeComparisons": comparisons,
596
599
  "observedExtentBytes": capacity,
597
600
  "capacity": "conditional on evidenced extent units and pointer identity" if extent else "unresolved: request units and bounded writes do not establish allocated extent",
@@ -6,6 +6,7 @@ from .machine import (State, StopPath, REGISTERS, ALIASES, BRANCH_CONDITIONS, st
6
6
  string_count, string_effect, check_string_form, compare_string, repeated)
7
7
  from .values import const, unknown, sources, op, Value
8
8
  from .result_flow import validate_contracts, result_contracts
9
+ from .memory_scopes import validate_scopes, capture_scopes, retain_scopes
9
10
 
10
11
  def call_target(image, site, ins):
11
12
  if ins.mnemonic in ("lcall", "ljmp"):
@@ -237,6 +238,8 @@ def trace(image, config, continue_declared_jumps=True):
237
238
  raise ValueError("At most 64 explicit call models")
238
239
  sites = set()
239
240
  for model in models:
241
+ if not isinstance(model, dict):
242
+ raise ValueError("Call model must be an object")
240
243
  integer(model.get("site"), 0, len(image.data) - 1, "model site")
241
244
  if model["site"] in sites or not model.get("evidence"):
242
245
  raise ValueError("Call model requires a unique site and evidence")
@@ -248,6 +251,7 @@ def trace(image, config, continue_declared_jumps=True):
248
251
  raise ValueError("Modeled returnBytes must be 2 or 4")
249
252
  if any(r not in REGISTERS for r in model.get("preserves", [])):
250
253
  raise ValueError("Model preserves must name full registers")
254
+ validate_scopes(model, image.bits, image.flat)
251
255
  for case in cases:
252
256
  for r, n in case.get("registers", {}).items():
253
257
  if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
@@ -463,6 +467,9 @@ def trace(image, config, continue_declared_jumps=True):
463
467
  raise StopPath("four-byte call model reached without an immediately executed push cs")
464
468
  if push_cs and return_bytes != 4:
465
469
  raise StopPath("push-CS/near-call model requires an explicit four-byte return contract")
470
+ # Scopes resolve against the pre-call state: before the modeled frame consumes an
471
+ # already-pushed CS word and before a case replaces registers.
472
+ kept_values, kept_unread, preserved_scopes = capture_scopes(state, model)
466
473
  if push_cs:
467
474
  actual_cs = state.pop(2)
468
475
  if actual_cs.term != state.reg("cs").term:
@@ -477,16 +484,19 @@ def trace(image, config, continue_declared_jumps=True):
477
484
  if r not in model.get("preserves", []) and r not in ("esp", "cs"):
478
485
  child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
479
486
  child.clear_memory()
487
+ retain_scopes(child, kept_values, kept_unread)
480
488
  child.forget_flags()
481
489
  child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
482
490
  child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
483
491
  for r, n in case.get("registers", {}).items():
484
492
  child.setreg(r, const(n, ALIASES[r][2], at), at)
485
493
  child.conditional.append({"site": at, "evidence": model["evidence"],
486
- "assumption": "call returns with balanced stack; memory effects unresolved"})
494
+ "assumption": "call returns with balanced stack; memory effects unresolved"
495
+ + (" outside explicit scopes" if preserved_scopes else ""),
496
+ "preservedMemoryScopes": preserved_scopes})
487
497
  child.event("call-return", callSite=at, callerEntry=state.frames[-1]["entry"],
488
498
  resultContracts=result_contracts(child, contracts, target), registers=snapshot(child), modeled=True,
489
- unknownMemoryEffects=True)
499
+ unknownMemoryEffects=True, preservedMemoryScopes=preserved_scopes)
490
500
  child.at = following
491
501
  pending.append(child)
492
502
  break
@@ -0,0 +1,293 @@
1
+ """Bounded call-memory hypotheses over synthetic near, far and PE32 frames."""
2
+ import unittest
3
+
4
+ from test_x86 import Code, report, events, configuration
5
+ from test_pe import Code as FlatCode, report as flat_report, CODE_RAW
6
+ from scientific_method_engine.x86.image import Image
7
+ from scientific_method_engine.x86.machine import State
8
+ from scientific_method_engine.x86.memory_scopes import validate_scopes, capture_scopes, retain_scopes
9
+ from scientific_method_engine.x86.values import const
10
+
11
+
12
+ def scope(**extra):
13
+ return {"segment": "ss", "base": "sp", "bytes": 4, "evidence": "synthetic saved frame hypothesis", **extra}
14
+
15
+
16
+ def nested(far=False, overwrite=False):
17
+ c = Code().emit("c6 06 30 00 01")
18
+ if far:
19
+ c.emit("0e")
20
+ c.branch("e8", "child").label("after").emit("c6 06 30 00 00 c3")
21
+ c.label("child").emit("55 89 e5").label("service").branch("e8", "external")
22
+ if overwrite:
23
+ c.emit("c7 46 02 00 00")
24
+ c.label("childWrite").emit("c6 06 30 00 03 5d").label("childReturn").emit("cb" if far else "c3")
25
+ c.label("external").emit("c3")
26
+ model = {"site": c.labels["service"], "preserves": ["ds", "ss"],
27
+ "preservesMemory": [scope(bytes=6 if far else 4)],
28
+ "evidence": "synthetic balanced returning service; other memory unknown", "cases": [{}]}
29
+ return c, model
30
+
31
+
32
+ REGISTERS = {"ds": 0x2000, "ss": 0x3000, "sp": 0xff00, "ebp": 0x7777}
33
+
34
+
35
+ class MemoryScopeTests(unittest.TestCase):
36
+ def test_nested_near_and_far_join_with_saved_register_and_explicit_provenance(self):
37
+ for far in (False, True):
38
+ with self.subTest(far=far):
39
+ c, model = nested(far)
40
+ r = report(c, "effects", registers=REGISTERS, callModels=[model])
41
+ self.assertTrue(r["completeWithinModel"])
42
+ self.assertEqual(r["paths"][0]["registers"]["bp"]["value"], REGISTERS["ebp"])
43
+ writes = events(r, "write")
44
+ self.assertTrue(any(e["site"] == c.labels["after"] and e["value"]["value"] == 0 for e in writes))
45
+ p = r["effectOrdering"]["paths"][0]
46
+ self.assertFalse(p["effectCompleteWithinModel"])
47
+ self.assertTrue(all(call["unknownEffects"] for call in p["calls"]))
48
+ # Every call summary has the field; only the modeled call carries scopes.
49
+ self.assertEqual([bool(call["preservedMemoryScopes"]) for call in p["calls"]],
50
+ [call["site"] == model["site"] for call in p["calls"]])
51
+ service = next(call for call in p["calls"] if call["site"] == model["site"])
52
+ declared = service["preservedMemoryScopes"]
53
+ self.assertEqual(declared, r["paths"][0]["conditionalModels"][0]["preservedMemoryScopes"])
54
+ self.assertEqual(declared, p["conditionalModels"][0]["preservedMemoryScopes"])
55
+ returned = next(e for e in events(r, "call-return") if e.get("modeled"))
56
+ self.assertEqual(declared, returned["preservedMemoryScopes"])
57
+ self.assertEqual(declared[0]["segment"]["value"], REGISTERS["ss"])
58
+ self.assertEqual(declared[0]["cachedBytes"], 6 if far else 4)
59
+ self.assertEqual(declared[0]["uncachedBytes"], 0)
60
+ self.assertNotIn("cacheMeaning", declared[0])
61
+ self.assertIn("outside its preservedMemoryScopes", service["continuation"])
62
+ self.assertEqual(declared[0]["linearStart"], REGISTERS["ss"] * 16 + 0xff00 - declared[0]["bytes"])
63
+ self.assertMatchUnknownOutsideScopes(c, model, r)
64
+
65
+ def assertMatchUnknownOutsideScopes(self, c, model, r):
66
+ # A hypothesis is not a write/read event or a native effect proof.
67
+ returned = next(e for e in events(r, "call-return") if e.get("modeled"))
68
+ self.assertTrue(returned["unknownMemoryEffects"])
69
+ self.assertEqual(len([e for e in r["paths"][0]["events"] if e["site"] == model["site"] and e["kind"] == "read" ]), 0)
70
+ self.assertEqual([e["site"] for e in events(r, "write") if e["width"] == 1], [0, c.labels["childWrite"], c.labels["after"]])
71
+
72
+ def test_default_wrong_and_partial_scopes_do_not_preserve_return_control(self):
73
+ # Register preservation alone (BP and SP included) never establishes the saved frame bytes.
74
+ for replacement in (None, [], [scope(segment="ds")], [scope(bytes=3)]):
75
+ c, model = nested()
76
+ model["preserves"] = ["ds", "ss", "ebp", "esp"]
77
+ if replacement is None:
78
+ model.pop("preservesMemory")
79
+ else:
80
+ model["preservesMemory"] = replacement
81
+ r = report(c, "effects", registers=REGISTERS, callModels=[model])
82
+ self.assertFalse(r["completeWithinModel"])
83
+ self.assertFalse(r["paths"][0]["returned"])
84
+ self.assertEqual(r["paths"][0]["stopSite"], c.labels["childReturn"])
85
+ self.assertFalse(any(e["site"] == c.labels["after"] for e in events(r, "write")))
86
+ self.assertTrue(any(e["site"] == c.labels["childWrite"] for e in events(r, "write")))
87
+
88
+ def test_return_control_scope_does_not_imply_saved_register_preservation(self):
89
+ c, model = nested()
90
+ model["preservesMemory"] = [scope(displacement=2, bytes=2)]
91
+ r = report(c, "effects", registers=REGISTERS, callModels=[model])
92
+ self.assertTrue(r["completeWithinModel"])
93
+ self.assertIsNone(r["paths"][0]["registers"]["bp"]["value"])
94
+
95
+ def test_explicit_post_model_overwrite_still_stops_nested_return(self):
96
+ c, model = nested(overwrite=True)
97
+ r = report(c, "effects", registers=REGISTERS, callModels=[model])
98
+ self.assertFalse(r["completeWithinModel"])
99
+ self.assertEqual(r["paths"][0]["stopSite"], c.labels["childReturn"])
100
+ self.assertFalse(any(e["site"] == c.labels["after"] for e in events(r, "write")))
101
+
102
+ def test_pe32_saved_register_and_nested_return_remain_conditional(self):
103
+ c = FlatCode().emit("c6 05 00 20 40 00 01").branch("e8", "child")
104
+ c.label("after").emit("c6 05 00 20 40 00 00 c3")
105
+ c.label("child").emit("55 89 e5").label("service").branch("e8", "external")
106
+ c.emit("c6 05 00 20 40 00 03 5d c3").label("external").emit("c3")
107
+ model = {"site": CODE_RAW + c.labels["service"], "evidence": "synthetic flat service",
108
+ "preservesMemory": [scope(base="esp", bytes=8)], "cases": [{}]}
109
+ r = flat_report(c, "effects", registers={"esp": 0x70000000, "ebp": 0x11223344}, callModels=[model])
110
+ self.assertTrue(r["completeWithinModel"])
111
+ self.assertEqual(r["paths"][0]["registers"]["ebp"]["value"], 0x11223344)
112
+ self.assertTrue(any(e["site"] == CODE_RAW + c.labels["after"] for e in events(r, "write")))
113
+ self.assertFalse(r["effectOrdering"]["paths"][0]["effectCompleteWithinModel"])
114
+ model["preservesMemory"][0]["bytes"] = 7
115
+ capped = flat_report(c, "effects", registers={"esp": 0x70000000}, callModels=[model])
116
+ self.assertFalse(capped["completeWithinModel"])
117
+
118
+ def test_flat_segment_selectors_do_not_create_bases_or_nonalias_proofs(self):
119
+ c = FlatCode().label("service").branch("e8", "external").emit("c3").label("external").emit("c3")
120
+ model = {"site": CODE_RAW, "evidence": "synthetic flat service", "cases": [{}],
121
+ "preservesMemory": [scope(base="esp", bytes=4), scope(segment="ds", base="esp", bytes=4)]}
122
+ r = flat_report(c, "effects", registers={"esp": 0x70000000, "ss": 0x23, "ds": 0x2b}, callModels=[model])
123
+ self.assertFalse(r["completeWithinModel"])
124
+ self.assertIn("overlap or alias", r["paths"][0]["stop"])
125
+ for segment in ("fs", "gs"):
126
+ model["preservesMemory"] = [scope(segment=segment, base="esp", bytes=4)]
127
+ stopped = flat_report(c, "effects", registers={"esp": 0x70000000, segment: 0x23}, callModels=[model])
128
+ self.assertFalse(stopped["completeWithinModel"])
129
+ self.assertIn("address unresolved", stopped["paths"][0]["stop"])
130
+ model["preservesMemory"] = [scope(base="sp")]
131
+ with self.assertRaises(ValueError):
132
+ flat_report(c, "effects", callModels=[model])
133
+ for displacement in (-2147483649, 2147483648):
134
+ model["preservesMemory"] = [scope(base="esp", displacement=displacement)]
135
+ with self.assertRaises(ValueError):
136
+ flat_report(c, "effects", callModels=[model])
137
+
138
+ def test_scopes_use_pre_call_registers_even_when_case_changes_them(self):
139
+ c, model = nested()
140
+ model["cases"] = [{"registers": {"bx": 0x1111}}]
141
+ model["preservesMemory"] = [scope(base="bx")]
142
+ # BX explicitly identifies the frame before the modeled return overwrites it.
143
+ r = report(c, "effects", registers={**REGISTERS, "bx": 0xfefc}, callModels=[model])
144
+ self.assertTrue(r["completeWithinModel"])
145
+ saved = r["paths"][0]["conditionalModels"][0]["preservedMemoryScopes"][0]
146
+ self.assertEqual(saved["base"]["value"], 0xfefc)
147
+ self.assertEqual(r["paths"][0]["registers"]["bx"]["value"], 0x1111)
148
+
149
+ def test_overlap_and_segment_alias_scopes_stop_before_continuation(self):
150
+ # Overlap through another base register is visible only once registers are known.
151
+ for other, registers in ((scope(base="bx"), {**REGISTERS, "bx": 0xff00 - 6}),
152
+ (scope(segment="ds"), {**REGISTERS, "ds": REGISTERS["ss"]}),
153
+ (scope(segment="ds", displacement=16), {**REGISTERS, "ds": REGISTERS["ss"] - 1})):
154
+ c, model = nested()
155
+ model["preservesMemory"].append(other)
156
+ r = report(c, "effects", registers=registers, callModels=[model])
157
+ self.assertFalse(r["completeWithinModel"])
158
+ self.assertIn("overlap or alias", r["paths"][0]["stop"])
159
+ self.assertFalse(any(e["site"] == c.labels["childWrite"] for e in events(r, "write")))
160
+
161
+ def test_unknown_and_wrapping_addresses_stop_without_preservation(self):
162
+ for registers, declared, reason in (({**REGISTERS, "bx": 0xffff}, scope(base="bx"), "boundary"),
163
+ (REGISTERS, scope(base="bx"), "unresolved"),
164
+ ({"sp": 0xff00}, scope(), "unresolved"),
165
+ ({**REGISTERS, "bx": 0}, scope(base="bx", displacement=-1), "boundary")):
166
+ c, model = nested()
167
+ model["preservesMemory"] = [declared]
168
+ r = report(c, "effects", registers=registers, callModels=[model])
169
+ self.assertFalse(r["completeWithinModel"])
170
+ self.assertIn(reason, r["paths"][0]["stop"])
171
+ self.assertEqual(r["paths"][0]["conditionalModels"], [])
172
+
173
+ def test_invalid_unreachable_declarations_and_independent_limits_are_rejected(self):
174
+ c, model = nested()
175
+ invalid = [scope(bytes=0), scope(bytes=True), scope(bytes=4097), scope(displacement=True),
176
+ scope(displacement=-32769), scope(displacement=32768), scope(base="al"), scope(base="esp"),
177
+ scope(base="ss"), scope(base=[]), scope(segment="eax"), scope(segment=[]), scope(evidence=" "), scope(extra="unexpected")]
178
+ invalid_lists = [[s] for s in invalid] + [[scope()] * 33, [scope(bytes=4096), scope(bytes=1)], "not a list",
179
+ # declared overlap on one segment and base, duplicates included
180
+ [scope(), scope(displacement=2)], [scope(), scope()],
181
+ [scope(base="sp"), scope(base="sp", displacement=-1, bytes=2)],
182
+ # a segment register the model replaces cannot address the scope
183
+ [scope(segment="es")]]
184
+ for declarations in invalid_lists:
185
+ with self.subTest(declarations=declarations):
186
+ unused = {**model, "site": c.labels["external"], "preservesMemory": declarations}
187
+ with self.assertRaises(ValueError):
188
+ report(c, "effects", registers=REGISTERS, callModels=[unused])
189
+ validate_scopes({"preserves": ["ss"], "preservesMemory": [scope(bytes=1, displacement=i) for i in range(32)]}, 16, False)
190
+ validate_scopes({"preserves": ["ss"], "preservesMemory": [scope(bytes=4096)]}, 16, False)
191
+ # Adjacent ranges, other bases and CS (never replaced by a model) are accepted; flat images
192
+ # address memory through segment bases that a model does not replace.
193
+ validate_scopes({"preserves": ["ss"], "preservesMemory": [scope(), scope(displacement=4), scope(base="bp")]}, 16, False)
194
+ validate_scopes({"preservesMemory": [scope(segment="cs")]}, 16, False)
195
+ validate_scopes({"preservesMemory": [scope(base="esp")]}, 32, True)
196
+
197
+ def test_step_path_and_total_caps_never_prove_a_later_write_absent(self):
198
+ c, model = nested()
199
+ positive = report(c, "effects", registers=REGISTERS, callModels=[model])
200
+ self.assertTrue(positive["completeWithinModel"])
201
+ for limit in ({"maxSteps": 1}, {"maxSteps": 5}, {"maxPaths": 1}, {"totalSteps": 5}):
202
+ with self.subTest(limit=limit):
203
+ r = report(c, "effects", registers=REGISTERS, callModels=[model], **limit)
204
+ self.assertFalse(r["completeWithinModel"])
205
+ self.assertFalse(r["effectOrdering"]["allPathsRead"])
206
+ self.assertFalse(any(e["site"] == c.labels["after"] for e in events(r, "write")))
207
+
208
+ def test_snapshot_restores_only_scoped_bytes_and_keeps_unknown_terms(self):
209
+ data = bytes.fromhex("c3")
210
+ config = configuration(data, registers={"sp": 0x200, "ss": 0x3000, "ds": 0x4000})
211
+ state = State(0, Image(data, config), config)
212
+ state.access(state.segment("ss"), const(0x200, 16), 2, write=const(0x1234, 16))
213
+ state.access(state.segment("ss"), const(0x204, 16), 2, write=const(0x5678, 16))
214
+ state.access(state.segment("ds"), const(0x200, 16), 2, write=const(0x9999, 16))
215
+ previous = state.peek(state.segment("ss"), const(0x202, 16), 2)
216
+ event_count = len(state.events)
217
+ values, unread, declared = capture_scopes(state, {"preservesMemory": [scope(bytes=4)]})
218
+ self.assertEqual(len(state.events), event_count)
219
+ self.assertEqual((declared[0]["cachedBytes"], declared[0]["uncachedBytes"]), (2, 2))
220
+ state.clear_memory()
221
+ retain_scopes(state, values, unread)
222
+ self.assertEqual(state.peek(state.segment("ss"), const(0x200, 16), 2).number, 0x1234)
223
+ self.assertEqual(state.peek(state.segment("ss"), const(0x202, 16), 2).term, previous.term)
224
+ self.assertIsNone(state.peek(state.segment("ss"), const(0x204, 16), 2).number)
225
+ self.assertIsNone(state.peek(state.segment("ds"), const(0x200, 16), 2).number)
226
+ # A later unknown-address write must still invalidate possible scoped aliases.
227
+ state.access(state.segment("ds"), state.reg("bx"), 1, write=const(1, 8))
228
+ self.assertEqual(state.peek(state.segment("ss"), const(0x200, 16), 2).number, 0x1234)
229
+ state.access(state.segment("ss"), state.reg("bx"), 1, write=const(1, 8))
230
+ self.assertIsNone(state.peek(state.segment("ss"), const(0x200, 16), 2).number)
231
+
232
+ def test_kept_uncached_bytes_stay_uncached_at_later_models_and_reads(self):
233
+ data = bytes.fromhex("c3")
234
+ config = configuration(data, registers={"sp": 0x200, "ss": 0x3000})
235
+ state = State(0, Image(data, config), config)
236
+ state.access(state.segment("ss"), const(0x200, 16), 1, write=const(0x12, 8))
237
+ declarations = {"preservesMemory": [scope(bytes=2)]}
238
+ terms = set()
239
+ for _ in range(2):
240
+ values, unread, declared = capture_scopes(state, declarations)
241
+ self.assertEqual((declared[0]["cachedBytes"], declared[0]["uncachedBytes"]), (1, 1))
242
+ terms.update(unread.values())
243
+ state.clear_memory()
244
+ retain_scopes(state, values, unread)
245
+ self.assertEqual(len(terms), 1)
246
+ # A kept uncached byte reads like any unread byte: produced by the reading site, listed missing.
247
+ state.at = 7
248
+ state.access(state.segment("ss"), const(0x200, 16), 2)
249
+ self.assertEqual(state.events[-1]["missingByteProducers"], [1])
250
+ self.assertIn(7, state.peek(state.segment("ss"), const(0x201, 16), 1).sources)
251
+ # Writing the byte gives it a value; it is no longer unread.
252
+ state.access(state.segment("ss"), const(0x201, 16), 1, write=const(0x34, 8))
253
+ self.assertEqual(state.unread_memory, {})
254
+
255
+ def test_exact_scope_and_byte_limits_execute_and_report_each_scope(self):
256
+ c = Code().label("service").branch("e8", "external").emit("c3").label("external").emit("c3")
257
+ for declarations in ([scope(base="bx", bytes=4096)],
258
+ [scope(base="bx", displacement=i * 128, bytes=128) for i in range(32)]):
259
+ model = {"site": 0, "evidence": "synthetic boundary-sized preservation", "cases": [{}], "preserves": ["ss"],
260
+ "preservesMemory": declarations}
261
+ r = report(c, "effects", registers={"ss": 0x3000, "bx": 0x1000}, callModels=[model])
262
+ self.assertTrue(r["completeWithinModel"])
263
+ scopes = r["paths"][0]["conditionalModels"][0]["preservedMemoryScopes"]
264
+ self.assertEqual(len(scopes), len(declarations))
265
+ self.assertEqual(sum(s["uncachedBytes"] for s in scopes), 4096)
266
+
267
+ def test_allocation_cites_scopes_of_a_modeled_allocator(self):
268
+ c = Code().emit("b8 02 00").label("call").branch("e8", "allocator").emit("c6 06 00 02 01 c3")
269
+ c.label("allocator").emit("c3")
270
+ allocations = [{"site": c.labels["call"], "requestRegister": "ax", "unitBytes": 16, "unitEvidence": "synthetic paragraph API"}]
271
+ for declared, text in (([scope()], "outside its preservedMemoryScopes"), ([], "memory unresolved")):
272
+ model = {"site": c.labels["call"], "preserves": ["ds", "ss"], "evidence": "synthetic allocator model",
273
+ "cases": [{}], "preservesMemory": declared}
274
+ r = report(c, "allocation", registers=REGISTERS, allocations=allocations, callModels=[model])
275
+ a = r["allocations"][0]
276
+ self.assertTrue(a["allocatorEffects"].endswith(text))
277
+ self.assertEqual(len(a["preservedMemoryScopes"]), len(declared))
278
+
279
+ def test_modeled_push_cs_uses_sp_before_consuming_the_segment_word(self):
280
+ c = Code().branch("e8", "child").label("after").emit("c3")
281
+ c.label("child").emit("55 89 e5 0e").label("service").branch("e8", "external").emit("5d c3")
282
+ c.label("external").emit("cb")
283
+ model = {"site": c.labels["service"], "returnBytes": 4, "preserves": ["ss"],
284
+ "evidence": "synthetic pushed-CS returning service", "preservesMemory": [scope(bytes=6)], "cases": [{}]}
285
+ r = report(c, "effects", registers=REGISTERS, callModels=[model])
286
+ self.assertTrue(r["completeWithinModel"])
287
+ declared = r["paths"][0]["conditionalModels"][0]["preservedMemoryScopes"][0]
288
+ self.assertEqual(declared["base"]["value"], REGISTERS["sp"] - 6)
289
+ self.assertEqual(r["paths"][0]["registers"]["bp"]["value"], REGISTERS["ebp"])
290
+
291
+
292
+ if __name__ == "__main__":
293
+ unittest.main()
@@ -1592,13 +1592,13 @@ class ReporterTests(unittest.TestCase):
1592
1592
  (root/"fixture.bin").write_bytes(data)
1593
1593
  cfg = configuration(data, source=str(root/"fixture.bin"), xxh3=xxhash.xxh3_128_hexdigest(data))
1594
1594
  stdin = [*ENGINE, "trace", "-"]
1595
- for protocol, accepted in ((None, False), (1, False), (2, True)):
1595
+ for protocol, accepted in ((None, False), (1, False), (2, False), (3, True)):
1596
1596
  prepared = dict(cfg) if protocol is None else {**cfg, "preparedProtocol": protocol}
1597
1597
  result = subprocess.run(stdin, input=json.dumps(prepared), capture_output=True, text=True, env=ENGINE_ENV)
1598
1598
  self.assertEqual(result.returncode, 0 if accepted else 1, result.stderr)
1599
1599
  if not accepted:
1600
1600
  self.assertIn("protocol", result.stderr)
1601
- path = root/"config.json"; path.write_text(json.dumps({**cfg, "preparedProtocol": 2}))
1601
+ path = root/"config.json"; path.write_text(json.dumps({**cfg, "preparedProtocol": 3}))
1602
1602
  result = subprocess.run([*ENGINE, "trace", str(path)], capture_output=True, text=True, env=ENGINE_ENV)
1603
1603
  self.assertEqual(result.returncode, 1)
1604
1604
  self.assertIn("set by the reader", result.stderr)