scientific-method-engine 3.0.0__tar.gz → 3.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 (63) hide show
  1. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/PKG-INFO +9 -1
  2. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/README.md +8 -0
  3. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/cli.py +2 -0
  5. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/machine.py +53 -1
  6. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/memory_scopes.py +11 -2
  7. scientific_method_engine-3.1.0/src/scientific_method_engine/x86/relational.py +745 -0
  8. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/reports.py +18 -2
  9. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/trace.py +3 -2
  10. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_memory_scopes.py +5 -3
  11. scientific_method_engine-3.1.0/tests/test_relational_controls.py +561 -0
  12. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/.gitignore +0 -0
  13. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/LICENSE +0 -0
  14. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/__init__.py +0 -0
  15. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/__main__.py +0 -0
  16. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  17. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  18. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  19. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  20. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  21. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  22. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  23. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  24. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  25. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  26. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  27. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  28. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  29. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  30. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  31. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  32. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  33. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  34. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  35. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  36. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  37. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  38. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  39. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  40. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  41. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  42. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  43. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  44. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  45. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  46. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  47. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  48. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  49. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  50. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  51. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  52. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  53. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  54. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  55. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  56. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/oracle.py +0 -0
  57. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_dispatch.py +0 -0
  58. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_effect_order.py +0 -0
  59. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_nested_frame_request.py +0 -0
  60. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_oracle.py +0 -0
  61. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_pe.py +0 -0
  62. {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_table_continuations.py +0 -0
  63. {scientific_method_engine-3.0.0 → scientific_method_engine-3.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: 3.0.0
3
+ Version: 3.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
@@ -142,3 +142,11 @@ survive the model's memory invalidation, and each scope is reported with the mod
142
142
  return and the effect summary. Everything else the service may do stays unknown. This input needs
143
143
  prepared protocol 3, so upgrade the reader and the engine together. See the
144
144
  [call model contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#limits-and-assumptions).
145
+
146
+ The trace-family commands (`trace`, `arguments`, `effects`, `returns`, `guards`, `memory`,
147
+ `allocation`) check `relationalControls`: assertions over reported values (reach, order, last
148
+ writer, containment, value relation and value origin) evaluated on every bounded path. A violated
149
+ control fails the report. A control left undecided by a stop, a limit or an unread call is
150
+ reported as `undecided` and never counts as held. Access reports also give each byte's
151
+ `writeOrder`, or why it has no modeled value. See the
152
+ [controls contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#relational-controls).
@@ -126,3 +126,11 @@ survive the model's memory invalidation, and each scope is reported with the mod
126
126
  return and the effect summary. Everything else the service may do stays unknown. This input needs
127
127
  prepared protocol 3, so upgrade the reader and the engine together. See the
128
128
  [call model contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#limits-and-assumptions).
129
+
130
+ The trace-family commands (`trace`, `arguments`, `effects`, `returns`, `guards`, `memory`,
131
+ `allocation`) check `relationalControls`: assertions over reported values (reach, order, last
132
+ writer, containment, value relation and value origin) evaluated on every bounded path. A violated
133
+ control fails the report. A control left undecided by a stop, a limit or an unread call is
134
+ reported as `undecided` and never counts as held. Access reports also give each byte's
135
+ `writeOrder`, or why it has no modeled value. See the
136
+ [controls contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#relational-controls).
@@ -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 = "3.0.0"
8
+ version = "3.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"
@@ -17,6 +17,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
17
17
  "effects|returns|memory|incoming|call-order|guards|allocation|dispatch> <config.json|->\n"
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
+ "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
21
+ "a violated control fails the report; an undecided one is reported and never counts as held.\n"
20
22
  "Declared table continuations are separate conditional paths; ordinary computed transfers remain stopped.\n"
21
23
  "Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
22
24
  "callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
@@ -67,6 +67,17 @@ class State:
67
67
  # Keys grouped by (segment, base) so a write scans only groups that can alias it.
68
68
  self.memory_groups = {}
69
69
  self.memory_epoch = 0
70
+ # The order of the write event that stored each modeled byte. lost_memory holds the
71
+ # byteProducers "unwritten" row of bytes with no value that an ordinary write explains (a
72
+ # possibly aliasing write dropped them) or that a preservesMemory scope kept without a
73
+ # value. memory_cleared is the order of the event that dropped every byte (a modeled call),
74
+ # or None. writes maps each alias group to {domain: order of the last write with it} since
75
+ # that event, so a read of a byte this path never stored can name a write that may have
76
+ # stored it without scanning the writes of its own group.
77
+ self.memory_writers = {}
78
+ self.lost_memory = {}
79
+ self.memory_cleared = None
80
+ self.writes = {}
70
81
  # Bytes a preservesMemory scope kept without a value (ADR 0009): key -> the unknown term
71
82
  # name they had before the modeled call. They stay unread: no value, no producer.
72
83
  self.unread_memory = {}
@@ -161,6 +172,11 @@ class State:
161
172
  self.memory.clear()
162
173
  self.memory_groups.clear()
163
174
  self.unread_memory.clear()
175
+ self.memory_writers.clear()
176
+ self.lost_memory.clear()
177
+ self.writes.clear()
178
+ # The caller records the event that explains the loss right after clearing.
179
+ self.memory_cleared = len(self.events)
164
180
  self.memory_epoch += 1
165
181
 
166
182
  def unread_term(self, key):
@@ -171,6 +187,37 @@ class State:
171
187
  """The modeled value of one memory byte, or an unknown term produced by the current site."""
172
188
  return self.memory[key] if key in self.memory else unknown(self.unread_term(key), 8, self.at)
173
189
 
190
+ def unwritten(self, key):
191
+ """Why a byte has no modeled value: the cause and the order of the event behind it."""
192
+ # Writes to the key's own (segment, base) group store other offsets; any other write may alias.
193
+ # A later aliasing write is newer than the one that dropped the byte, so it is the one named.
194
+ lost = self.lost_memory.get(key)
195
+ group, a = key[:2], key_domain(key, self.bits, self.flat)
196
+ latest = None
197
+ for other, domains in self.writes.items():
198
+ if other == group:
199
+ continue
200
+ if a is None:
201
+ # Every write may alias a byte with no concrete domain; the group's newest decides.
202
+ order = max(domains.values())
203
+ else:
204
+ order = max((o for b, o in domains.items() if b is None or not (a[1] <= b[0] or b[1] <= a[0])), default=None)
205
+ if order is not None and (latest is None or order > latest):
206
+ latest = order
207
+ if latest is not None and (lost is None or lost["order"] is None or latest > lost["order"]):
208
+ return {"cause": "possibly written by an aliasing write", "order": latest}
209
+ if lost is not None:
210
+ return dict(lost)
211
+ if self.memory_cleared is not None:
212
+ return {"cause": "dropped by a modeled call", "order": self.memory_cleared}
213
+ return {"cause": "no write on this path", "order": None}
214
+
215
+ def byte_writer(self, index, key):
216
+ """The byteProducers row of one accessed byte: its producers and the write that stored it."""
217
+ if key in self.memory:
218
+ return {"index": index, "producers": producers(self.memory[key]), "writeOrder": self.memory_writers.get(key)}
219
+ return {"index": index, "producers": [], "writeOrder": None, "unwritten": self.unwritten(key)}
220
+
174
221
  def reg(self, name):
175
222
  root, low, bits = alias(name)
176
223
  value = extract(self.regs[root], low, bits)
@@ -225,6 +272,7 @@ class State:
225
272
  self.memory_epoch += 1
226
273
 
227
274
  written = written_domain(seg, base, delta, width, self.bits, self.flat)
275
+ self.writes.setdefault((seg, base), {})[written] = len(self.events)
228
276
  for group, members in list(self.memory_groups.items()):
229
277
  if group == (seg, base):
230
278
  continue
@@ -233,12 +281,16 @@ class State:
233
281
  uncertain.append(key)
234
282
  self.memory.pop(key, None)
235
283
  self.unread_memory.pop(key, None)
284
+ self.memory_writers.pop(key, None)
285
+ self.lost_memory[key] = {"cause": "dropped by a possibly aliasing write", "order": len(self.events)}
236
286
  members.discard(key)
237
287
  if not members:
238
288
  del self.memory_groups[group]
239
289
  for i, key in enumerate(keys):
240
290
  self.memory[key] = extract(write, i * 8, 8)
241
291
  self.unread_memory.pop(key, None)
292
+ self.memory_writers[key] = len(self.events)
293
+ self.lost_memory.pop(key, None)
242
294
  self.memory_groups.setdefault((seg, base), set()).update(keys)
243
295
  value = write
244
296
  missing = []
@@ -257,7 +309,7 @@ class State:
257
309
  event = self.event("write" if write is not None else "read", segment=segment.report(), offset=offset.report(),
258
310
  width=width, effectiveSegmentRegister=addressing_register, segmentInterpretation="base" if self.flat else "selector-paragraph", interval={"segment": seg, "base": base, "start": delta, "end": delta + width},
259
311
  value=value.report(), missingByteProducers=missing,
260
- byteProducers=[{"index": i, "producers": producers(self.memory[key]) if key in self.memory else []} for i, key in enumerate(keys)],
312
+ byteProducers=[self.byte_writer(i, key) for i, key in enumerate(keys)],
261
313
  guards=deepcopy(relevant), role=role,
262
314
  uncertainAliasesInvalidated=len(uncertain))
263
315
  f = self.frames[-1]
@@ -95,12 +95,21 @@ def capture_scopes(state, model):
95
95
  return values, unread, descriptions
96
96
 
97
97
 
98
- def retain_scopes(state, values, unread):
98
+ def scope_history(state, values, unread):
99
+ """Snapshot, before the call, the write that stored each captured byte and why each uncached one has no value."""
100
+ return ({key: state.memory_writers[key] for key in values if key in state.memory_writers},
101
+ {key: state.unwritten(key) for key in unread})
102
+
103
+
104
+ def retain_scopes(state, values, unread, history):
99
105
  """Put the captured bytes back after the model invalidated memory. Later writes still apply.
100
106
 
101
- All scoped keys are concrete linear bytes, so they share one alias group.
107
+ All scoped keys are concrete linear bytes, so they share one alias group. ``history`` from
108
+ ``scope_history`` keeps each byte's reported writer, or its reason for having no value.
102
109
  """
103
110
  state.memory.update(values)
104
111
  state.unread_memory.update(unread)
112
+ state.memory_writers.update(history[0])
113
+ state.lost_memory.update(history[1])
105
114
  if values or unread:
106
115
  state.memory_groups.setdefault((("linear",), ("absolute",)), set()).update(values, unread)