scientific-method-engine 3.2.0__tar.gz → 4.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 (66) hide show
  1. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/PKG-INFO +5 -3
  2. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/README.md +4 -2
  3. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/cli.py +2 -1
  5. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/result_flow.py +3 -1
  6. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/trace.py +101 -31
  7. scientific_method_engine-4.0.0/tests/test_continuation_budget.py +179 -0
  8. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_table_continuations.py +4 -2
  9. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/.gitignore +0 -0
  10. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/LICENSE +0 -0
  11. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/__init__.py +0 -0
  12. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/__main__.py +0 -0
  13. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  14. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  15. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  16. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  17. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  18. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  19. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  20. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  21. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  22. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  23. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  24. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  25. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  26. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  27. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  28. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  29. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  30. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  31. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  32. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  33. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  34. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  35. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  36. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  37. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  38. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  39. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  40. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  41. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  42. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  43. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  44. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  45. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  46. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  47. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  48. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
  49. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/machine.py +0 -0
  50. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  51. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  52. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  53. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  54. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
  55. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/reports.py +0 -0
  56. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  57. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/oracle.py +0 -0
  58. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_dispatch.py +0 -0
  59. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_effect_order.py +0 -0
  60. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_loops.py +0 -0
  61. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_memory_scopes.py +0 -0
  62. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_nested_frame_request.py +0 -0
  63. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_oracle.py +0 -0
  64. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_pe.py +0 -0
  65. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_relational_controls.py +0 -0
  66. {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.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.2.0
3
+ Version: 4.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
@@ -135,8 +135,10 @@ Evidenced segmented16 `indirectJumps` declarations also expose separate
135
135
  `declaredContinuationPaths`. Ordinary paths retain their unresolved transfer;
136
136
  conditional routes preserve prefix/child effects with target-choice, live-table
137
137
  and selector assumptions. Effects summaries never mark those routes complete.
138
- Concrete values/field addresses reject inconsistent rows; overlap and shared
139
- path/step/visit/total/boundary limits remain explicit. Partial-table splits are
138
+ Concrete values/field addresses reject inconsistent rows. Continuations run after
139
+ every ordinary path on their own `continuationBudget` (paths, total and per-path steps,
140
+ visits, string iterations), so ordinary paths are the same with or without them. Overlap,
141
+ boundary and continuation limits remain explicit gaps or stops. Partial-table splits are
140
142
  partial evidence, never complete dispatch or native-reachability claims. See the
141
143
  [table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
142
144
 
@@ -119,8 +119,10 @@ Evidenced segmented16 `indirectJumps` declarations also expose separate
119
119
  `declaredContinuationPaths`. Ordinary paths retain their unresolved transfer;
120
120
  conditional routes preserve prefix/child effects with target-choice, live-table
121
121
  and selector assumptions. Effects summaries never mark those routes complete.
122
- Concrete values/field addresses reject inconsistent rows; overlap and shared
123
- path/step/visit/total/boundary limits remain explicit. Partial-table splits are
122
+ Concrete values/field addresses reject inconsistent rows. Continuations run after
123
+ every ordinary path on their own `continuationBudget` (paths, total and per-path steps,
124
+ visits, string iterations), so ordinary paths are the same with or without them. Overlap,
125
+ boundary and continuation limits remain explicit gaps or stops. Partial-table splits are
124
126
  partial evidence, never complete dispatch or native-reachability claims. See the
125
127
  [table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
126
128
 
@@ -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.2.0"
8
+ version = "4.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"
@@ -19,7 +19,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
19
19
  "callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges.\n"
20
20
  "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
21
21
  "a violated control fails the report; an undecided one is reported and never counts as held.\n"
22
- "Declared table continuations are separate conditional paths; ordinary computed transfers remain stopped.\n"
22
+ "Declared table continuations are separate conditional paths that spend continuationBudget\n"
23
+ "(paths, totalSteps, maxSteps, visitLimit, stringIterations); ordinary computed transfers remain stopped.\n"
23
24
  "Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
24
25
  "callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
25
26
  "Each traced path's loops record lists restart edges and what changed between iterations (loopIterationLimit).\n"
@@ -88,6 +88,8 @@ def return_flows(report, config):
88
88
  consumer_limit = integer(config.get("returnConsumerLimit", 256), 1, 10000, "return consumer limit")
89
89
  analysis_limit = integer(config.get("returnFlowAnalysisLimit", 1000000), 1, 10000000, "return flow analysis limit")
90
90
  steps, capped = 0, False
91
+ # Gaps raised while declared-table continuations ran say nothing about an ordinary path.
92
+ ordinary_gaps = [g for g in report["gaps"] if g.get("route") != "declaredContinuation"]
91
93
  for path in report["paths"]:
92
94
  events = path["events"]
93
95
  event_values = {}
@@ -138,7 +140,7 @@ def return_flows(report, config):
138
140
  path["returnFlows"] = {"results": flows, "resultsOmitted": omitted, "resultLimit": limit,
139
141
  "consumerLimit": consumer_limit,
140
142
  "complete": not omitted and all(not f["consumersOmitted"] and f["consumerScanComplete"] for f in flows)
141
- and path["returned"] and not report["gaps"],
143
+ and path["returned"] and not ordinary_gaps,
142
144
  "interpretation": "conditional static dependency paths; encodings are declared evidence, not live occurrence; a branch never establishes initialization, accepted contents or extent"}
143
145
  report["returnFlowAnalysis"] = {"limit": analysis_limit, "steps": steps, "capped": capped}
144
146
  return report
@@ -279,14 +279,34 @@ def snapshot(state):
279
279
  return {name: state.reg(name).report() for name in ALIASES}
280
280
 
281
281
 
282
+ STRING_BUDGET_STOP = "String iteration budget exhausted"
283
+ CONTINUATION_BUDGET_RANGES = {"paths": (0, 256), "totalSteps": (1, 100000), "maxSteps": (1, 10000),
284
+ "visitLimit": (1, 4096), "stringIterations": (0, 65536)}
285
+
286
+
287
+ def validate_continuation_budget(config):
288
+ """Return the fields a config sets in continuationBudget, rejecting unknown keys and out-of-range values."""
289
+ budget = config.get("continuationBudget", {})
290
+ if not isinstance(budget, dict):
291
+ raise ValueError("continuationBudget must be an object")
292
+ unknown_keys = sorted(set(budget) - set(CONTINUATION_BUDGET_RANGES))
293
+ if unknown_keys:
294
+ raise ValueError("continuationBudget accepts only " + ", ".join(CONTINUATION_BUDGET_RANGES)
295
+ + "; unknown: " + ", ".join(unknown_keys))
296
+ return {key: integer(value, *CONTINUATION_BUDGET_RANGES[key], "continuationBudget." + key)
297
+ for key, value in budget.items()}
298
+
299
+
282
300
  def trace(image, config, continue_declared_jumps=True, track_loops=True):
283
301
  """Trace bounded paths, preserving declared-table continuations as separate conditional evidence.
284
302
 
285
303
  Ordinary paths run first. A path stopped at a declared indirect jump is then
286
- continued once per surviving table target, so the continuations never take
287
- budget from an ordinary path. Callers that read only ordinary paths pass
288
- continue_declared_jumps=False. Callers that never report the paths pass
289
- track_loops=False, and their paths carry no ``loops`` record.
304
+ continued once per surviving table target. Continuations spend their own
305
+ continuationBudget, so ordinary paths are the same with or without them, and
306
+ what the ordinary paths spend never leaves the continuations without budget.
307
+ Callers that read only ordinary paths pass continue_declared_jumps=False.
308
+ Callers that never report the paths pass track_loops=False, and their paths
309
+ carry no ``loops`` record.
290
310
  """
291
311
  entry = integer(config.get("entry"), 0, len(image.data) - 1, "entry")
292
312
  if not any(entry in r["entries"] for r in image.regions):
@@ -322,6 +342,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
322
342
  for r, n in case.get("registers", {}).items():
323
343
  if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
324
344
  raise ValueError("Invalid model register")
345
+ explicit_continuation_budget = validate_continuation_budget(config)
325
346
  root = State(entry, image, config)
326
347
  # Each path carries its own loop record; forks copy it with the rest of the state.
327
348
  root.loops = (LoopTracker(integer(config.get("loopIterationLimit", 64), 1, 1024, "loopIterationLimit"))
@@ -340,6 +361,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
340
361
  checkpoints = set(config.get("checkpoints", []))
341
362
  # How often one path may pass the same instruction; a loop with a known bound needs it raised.
342
363
  visit_limit = integer(config.get("visitLimit", 4), 1, 4096, "visitLimit")
364
+ # An unset field takes the value of the matching ordinary input.
365
+ continuation_budget = {"paths": max_paths, "totalSteps": total_limit, "maxSteps": max_steps,
366
+ "visitLimit": visit_limit, "stringIterations": string_limit, **explicit_continuation_budget}
367
+ ordinary_max_paths = max_paths
368
+ # Set once every ordinary path has finished. From then on every traced state is a continuation.
369
+ continuing = False
370
+ first_continuation_gap = None
343
371
 
344
372
  def charge(n):
345
373
  nonlocal total_string_steps
@@ -357,6 +385,9 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
357
385
  string_effect(s, ins, count, remaining)
358
386
 
359
387
  def finish(s, reason=None, returned=False):
388
+ if continuing and reason and reason.startswith(STRING_BUDGET_STOP):
389
+ # machine.py names no budget; a continuation's string iterations come from continuationBudget.
390
+ reason = "Continuation s" + reason[1:]
360
391
  path = {"returned": returned, "stop": reason, "stopSite": None if returned else s.at, "steps": s.steps,
361
392
  "instructionPath": s.path, "guards": s.guards, "events": s.events,
362
393
  "registers": snapshot(s), "conditionalModels": s.conditional}
@@ -376,21 +407,6 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
376
407
  nonlocal created, boundary_budget
377
408
  declaration = image.indirect_jumps[s.at]
378
409
  ins = image.decode(s.at)
379
- root_entry = s.frames[-1]["entry"]
380
- if root_entry not in boundary_cache:
381
- if boundary_budget < 1:
382
- global_gaps.append({"site": s.at, "reason": "conditional table boundary instruction limit"})
383
- return
384
- seen, walk_gaps, _, _, contested = walk(image, [root_entry], boundary_budget)
385
- # walk drops rejected overlapping starts and contested instructions from seen,
386
- # but it decoded them, so they are charged with the established ones.
387
- overlapping = sum(g["reason"] == OVERLAP_REASON for g in walk_gaps)
388
- boundary_budget -= max(1, len(seen) + len(contested) + overlapping)
389
- # A truncated walk never saw the instructions that could contest a target start.
390
- if any(g["reason"] == "instruction limit" for g in walk_gaps):
391
- seen = {}
392
- boundary_cache[root_entry] = seen
393
- seen = boundary_cache[root_entry]
394
410
  try:
395
411
  value = s.get(ins, ins.operands[0], image)
396
412
  address = s.address(ins, ins.operands[0]) if ins.operands[0].type == X86_OP_MEM else None
@@ -416,6 +432,28 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
416
432
  if previous is not None and row["rawOffset"] not in previous:
417
433
  continue
418
434
  groups.setdefault(row["target"], []).append(row)
435
+ if not groups:
436
+ # No table row agrees with the operand, so no route exists to drop or to walk to.
437
+ return
438
+ if created >= max_paths:
439
+ # Spent or zero path budget: the routes are not followed, so no boundary walk is needed.
440
+ global_gaps.append({"site": s.at, "reason": "path limit"})
441
+ return
442
+ root_entry = s.frames[-1]["entry"]
443
+ if root_entry not in boundary_cache:
444
+ if boundary_budget < 1:
445
+ global_gaps.append({"site": s.at, "reason": "conditional table boundary instruction limit"})
446
+ return
447
+ seen, walk_gaps, _, _, contested = walk(image, [root_entry], boundary_budget)
448
+ # walk drops rejected overlapping starts and contested instructions from seen,
449
+ # but it decoded them, so they are charged with the established ones.
450
+ overlapping = sum(g["reason"] == OVERLAP_REASON for g in walk_gaps)
451
+ boundary_budget -= max(1, len(seen) + len(contested) + overlapping)
452
+ # A truncated walk never saw the instructions that could contest a target start.
453
+ if any(g["reason"] == "instruction limit" for g in walk_gaps):
454
+ seen = {}
455
+ boundary_cache[root_entry] = seen
456
+ seen = boundary_cache[root_entry]
419
457
  for target, rows in groups.items():
420
458
  if target not in seen:
421
459
  global_gaps.append({"site": s.at, "target": target,
@@ -435,26 +473,41 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
435
473
  {"segment": address[0].report(), "offset": address[1].report(), "segmentRegister": address[2]},
436
474
  "meaning": "conditional target choice from source table; selector, live table contents and reachability unverified"}
437
475
  child.declared_jump_assumptions = [*getattr(child, "declared_jump_assumptions", []), assumption]
476
+ if not hasattr(child, "continuation_steps"):
477
+ # Per-path continuation limits count from the first declared jump the path continues past.
478
+ child.continuation_steps, child.continuation_visits = 0, {}
438
479
  child.event("declared-jump-continuation", **{k: v for k, v in assumption.items() if k != "site"})
439
480
  child.at = target
440
481
  pending.append(child)
441
482
  created += 1
442
483
 
443
484
  # Ordinary paths all finish before the first declared continuation runs; their gaps come first.
444
- ordinary_gaps = None
445
485
  while pending or deferred:
446
486
  if not pending:
447
- if ordinary_gaps is None:
448
- ordinary_gaps = len(global_gaps)
487
+ if not continuing:
488
+ # Ordinary tracing is over. Its counters are final, and continuations start on their own budget.
489
+ continuing = True
490
+ ordinary_steps, ordinary_string_steps = total_steps, total_string_steps
491
+ created = total_steps = total_string_steps = 0
492
+ max_paths = continuation_budget["paths"]
493
+ total_limit = continuation_budget["totalSteps"]
494
+ string_limit = continuation_budget["stringIterations"]
495
+ first_continuation_gap = len(global_gaps)
449
496
  declared_continuations(deferred.pop(0))
450
497
  continue
451
498
  state = pending.pop()
452
499
  try:
453
500
  while True:
454
- if state.steps >= max_steps:
455
- raise StopPath("step limit; loop progress unresolved")
456
- if total_steps >= total_limit:
457
- raise StopPath("total instruction budget exhausted")
501
+ if continuing:
502
+ if state.continuation_steps >= continuation_budget["maxSteps"]:
503
+ raise StopPath("continuation step limit; loop progress unresolved")
504
+ if total_steps >= total_limit:
505
+ raise StopPath("continuation instruction budget exhausted")
506
+ else:
507
+ if state.steps >= max_steps:
508
+ raise StopPath("step limit; loop progress unresolved")
509
+ if total_steps >= total_limit:
510
+ raise StopPath("total instruction budget exhausted")
458
511
  total_steps += 1
459
512
  at = state.at
460
513
  ins = image.decode(at)
@@ -465,7 +518,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
465
518
  if state.loops is not None:
466
519
  state.loops.arrive(state, at, ins)
467
520
  state.visits[at] = state.visits.get(at, 0) + 1
468
- if state.visits[at] > visit_limit:
521
+ if continuing:
522
+ state.continuation_steps += 1
523
+ state.continuation_visits[at] = state.continuation_visits.get(at, 0) + 1
524
+ if state.continuation_visits[at] > continuation_budget["visitLimit"]:
525
+ raise StopPath(f"instruction repeated more than {continuation_budget['visitLimit']} times after "
526
+ "the declared jump; raise continuationBudget.visitLimit or read the loop's bound")
527
+ elif state.visits[at] > visit_limit:
469
528
  raise StopPath(f"instruction repeated more than {visit_limit} times; raise visitLimit or read the loop's bound")
470
529
  if at in checkpoints:
471
530
  state.event("checkpoint", registers=snapshot(state))
@@ -713,8 +772,19 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
713
772
  state.at = following
714
773
  except StopPath as error:
715
774
  finish(state, str(error))
775
+ if continuing:
776
+ # Only continuation states are traced after the switch: deferred states are popped only when
777
+ # pending is empty, and every state pending holds from then on descends from a continuation.
778
+ continuation_steps, continuation_string_steps = total_steps, total_string_steps
779
+ for gap in global_gaps[first_continuation_gap:]:
780
+ gap["route"] = "declaredContinuation"
781
+ else:
782
+ ordinary_steps, ordinary_string_steps = total_steps, total_string_steps
783
+ continuation_steps = continuation_string_steps = 0
716
784
  return {"paths": outputs, "declaredContinuationPaths": conditional_outputs, "gaps": global_gaps,
717
- "hardwareBoundaries": hardware_placement(outputs, conditional_outputs, global_gaps[:ordinary_gaps]),
718
- "completeWithinModel": not global_gaps and bool(outputs) and all(p["returned"] for p in outputs),
719
- "nativeReachability": "unconfirmed", "stepsUsed": total_steps, "stringIterationsUsed": total_string_steps,
720
- "limits": {"steps": max_steps, "paths": max_paths, "depth": max_depth}}
785
+ "hardwareBoundaries": hardware_placement(outputs, conditional_outputs, global_gaps[:first_continuation_gap]),
786
+ "completeWithinModel": not global_gaps[:first_continuation_gap] and bool(outputs) and all(p["returned"] for p in outputs),
787
+ "nativeReachability": "unconfirmed", "stepsUsed": ordinary_steps, "stringIterationsUsed": ordinary_string_steps,
788
+ "continuationStepsUsed": continuation_steps, "continuationStringIterationsUsed": continuation_string_steps,
789
+ "limits": {"steps": max_steps, "paths": ordinary_max_paths, "depth": max_depth,
790
+ "continuation": continuation_budget}}
@@ -0,0 +1,179 @@
1
+ """Declared-table continuations spend their own budget and never change the ordinary paths."""
2
+ import json
3
+ import unittest
4
+ import test_dispatch # noqa: F401 (puts the engine sources on sys.path)
5
+ from scientific_method_engine.x86.image import Image
6
+ from scientific_method_engine.x86.reports import run_report
7
+ from scientific_method_engine.x86.trace import trace
8
+
9
+ RETURN_ONE = bytes.fromhex("b8 01 00 c3")
10
+ SPIN = bytes.fromhex("eb fe")
11
+ COPY_TWO = bytes.fromhex("b9 02 00 fc f3 a4 c3")
12
+
13
+
14
+ def fan_out(stages, targets=(RETURN_ONE, bytes.fromhex("b8 02 00 c3"))):
15
+ """Build a function whose first branch reaches a declared table jump and whose other
16
+ branch forks on `stages` independent unknown bytes, so ordinary routes number 2**stages."""
17
+ code = bytearray(bytes.fromhex("72 00"))
18
+ for i in range(stages):
19
+ address = 0x100 + i
20
+ code += bytes([0x80, 0x3E, address & 0xFF, address >> 8, 0x00, 0x74, 0x00])
21
+ code += b"\xc3"
22
+ dispatcher = len(code)
23
+ code[1] = dispatcher - 2
24
+ code += bytes.fromhex("ff e3")
25
+ starts = []
26
+ for target in targets:
27
+ starts.append(len(code))
28
+ code += target
29
+ end = len(code)
30
+ table = len(code)
31
+ for start in starts:
32
+ code += start.to_bytes(2, "little")
33
+ config = {"entry": 0, "registers": {"ds": 0x2000, "es": 0x3000, "si": 0x10, "di": 0x20},
34
+ "regions": [{"name": "code", "start": 0, "end": end, "segment": 4096, "ip": 0,
35
+ "entries": [0], "evidence": "constructed mappings"}],
36
+ "indirectJumps": [{"site": dispatcher, "evidence": "constructed BX consumer", "exhaustive": True,
37
+ "table": {"start": table, "count": len(targets), "stride": 2,
38
+ "evidence": "constructed words"}}]}
39
+ return bytes(code), config, dispatcher
40
+
41
+
42
+ def ordinary(report):
43
+ """Everything a report says about ordinary paths, including derived analyses such as returnFlows."""
44
+ return json.dumps({"paths": report["paths"], "stepsUsed": report["stepsUsed"],
45
+ "stringIterationsUsed": report["stringIterationsUsed"],
46
+ "completeWithinModel": report["completeWithinModel"],
47
+ "effectPaths": report.get("effectOrdering", {}).get("paths"),
48
+ "allPathsRead": report.get("effectOrdering", {}).get("allPathsRead"),
49
+ "gaps": [g for g in report["gaps"] if "route" not in g]}, sort_keys=True)
50
+
51
+
52
+ class ContinuationBudgetTests(unittest.TestCase):
53
+ def test_continuations_run_after_ordinary_paths_spend_the_shared_budget(self):
54
+ data, config, dispatcher = fan_out(4)
55
+ r = run_report(data, {**config, "maxPaths": 8}, "effects")
56
+ self.assertEqual(len(r["paths"]), 8)
57
+ self.assertTrue(any(g["reason"] == "path limit" and "route" not in g for g in r["gaps"]))
58
+ routes = r["declaredContinuationPaths"]
59
+ self.assertEqual(sorted(p["registers"]["ax"]["value"] for p in routes), [1, 2])
60
+ self.assertTrue(all(p["returned"] and p["declaredJumpAssumptions"][0]["site"] == dispatcher for p in routes))
61
+ self.assertEqual(r["limits"]["paths"], 8)
62
+ self.assertEqual(r["limits"]["continuation"],
63
+ {"paths": 8, "totalSteps": 20000, "maxSteps": 512, "visitLimit": 4, "stringIterations": 4096})
64
+ self.assertEqual(r["continuationStepsUsed"], 4)
65
+ self.assertFalse(r["completeWithinModel"])
66
+ self.assertTrue(all(not p["effectCompleteWithinModel"] for p in r["effectOrdering"]["declaredContinuationPaths"]))
67
+
68
+ def test_ordinary_paths_are_identical_whatever_the_continuations_spend(self):
69
+ # Two stages leave every ordinary path returned except the one stopped at the jump.
70
+ for stages, max_paths in ((4, 8), (2, 64)):
71
+ data, config, _ = fan_out(stages)
72
+ config = {**config, "maxPaths": max_paths}
73
+ image = Image(data, config)
74
+ unread = trace(image, image.config, continue_declared_jumps=False)
75
+ for command in ("trace", "returns", "effects"):
76
+ baseline = run_report(data, {**config, "continuationBudget": {"paths": 0}}, command)
77
+ if command == "trace":
78
+ self.assertEqual(json.dumps(unread["paths"], sort_keys=True), json.dumps(baseline["paths"], sort_keys=True))
79
+ for budget in ({}, {"paths": 1}, {"paths": 256, "totalSteps": 100000, "maxSteps": 10000,
80
+ "visitLimit": 4096, "stringIterations": 65536},
81
+ {"totalSteps": 1}, {"maxSteps": 1}):
82
+ r = run_report(data, {**config, "continuationBudget": budget}, command)
83
+ self.assertEqual(ordinary(r), ordinary(baseline), (stages, command, budget))
84
+
85
+ def test_raising_the_continuation_budget_leaves_the_ordinary_report_size_alone(self):
86
+ data, config, _ = fan_out(6)
87
+ small = run_report(data, {**config, "maxPaths": 4}, "trace")
88
+ large = run_report(data, {**config, "maxPaths": 4, "continuationBudget": {"paths": 256}}, "trace")
89
+ self.assertEqual(len(large["paths"]), 4)
90
+ self.assertEqual(ordinary(large), ordinary(small))
91
+ self.assertEqual(len(large["declaredContinuationPaths"]), 2)
92
+
93
+ def test_path_limit_is_a_continuation_gap(self):
94
+ data, config, dispatcher = fan_out(2)
95
+ r = run_report(data, {**config, "continuationBudget": {"paths": 0}}, "trace")
96
+ self.assertFalse(r["declaredContinuationPaths"])
97
+ self.assertIn({"site": dispatcher, "reason": "path limit", "route": "declaredContinuation"}, r["gaps"])
98
+ self.assertFalse(r["completeWithinModel"])
99
+ r = run_report(data, {**config, "continuationBudget": {"paths": 1}}, "trace")
100
+ self.assertEqual(len(r["declaredContinuationPaths"]), 1)
101
+ self.assertIn({"site": dispatcher, "reason": "path limit", "route": "declaredContinuation"}, r["gaps"])
102
+
103
+ def test_a_spent_path_budget_leaves_one_gap_per_stopped_path(self):
104
+ # No boundary walk runs, so a boundary budget too small for one still leaves only the path-limit gap.
105
+ data, config, dispatcher = fan_out(1)
106
+ r = run_report(data, {**config, "instructionLimit": 1, "continuationBudget": {"paths": 0}}, "trace")
107
+ self.assertEqual([g for g in r["gaps"] if g.get("route")],
108
+ [{"site": dispatcher, "reason": "path limit", "route": "declaredContinuation"}])
109
+
110
+ def test_a_spent_path_budget_leaves_no_gap_where_no_row_matches(self):
111
+ # A concrete operand outside the table has no route to drop, whatever the path budget.
112
+ data, config, _ = fan_out(1)
113
+ config = {**config, "registers": {**config["registers"], "bx": 0x7777}}
114
+ for budget in ({}, {"paths": 0}):
115
+ r = run_report(data, {**config, "continuationBudget": budget}, "trace")
116
+ self.assertFalse(r["declaredContinuationPaths"])
117
+ self.assertFalse([g for g in r["gaps"] if g.get("route")], budget)
118
+
119
+ def test_forks_inside_a_continuation_spend_its_paths(self):
120
+ fork = bytes.fromhex("80 3e 00 02 00 74 00 c3")
121
+ data, config, _ = fan_out(2, targets=(fork,))
122
+ r = run_report(data, {**config, "continuationBudget": {"paths": 1}}, "trace")
123
+ self.assertEqual(len(r["declaredContinuationPaths"]), 1)
124
+ gaps = [g for g in r["gaps"] if g.get("route") == "declaredContinuation"]
125
+ self.assertEqual([g["reason"] for g in gaps], ["path limit"])
126
+ r = run_report(data, {**config, "continuationBudget": {"paths": 2}}, "trace")
127
+ self.assertEqual(len(r["declaredContinuationPaths"]), 2)
128
+ self.assertFalse(any(g.get("route") for g in r["gaps"]))
129
+
130
+ def test_total_and_per_path_step_limits_stop_continuations(self):
131
+ data, config, _ = fan_out(2)
132
+ r = run_report(data, {**config, "continuationBudget": {"totalSteps": 1}}, "trace")
133
+ # Each route needs two instructions, so the one budgeted step stops both.
134
+ self.assertEqual([p["stop"] for p in r["declaredContinuationPaths"]],
135
+ ["continuation instruction budget exhausted"] * 2)
136
+ self.assertEqual(r["continuationStepsUsed"], 1)
137
+ r = run_report(data, {**config, "continuationBudget": {"maxSteps": 1}}, "trace")
138
+ self.assertTrue(all(p["stop"] == "continuation step limit; loop progress unresolved"
139
+ for p in r["declaredContinuationPaths"]))
140
+ self.assertFalse(any(p["returned"] for p in r["declaredContinuationPaths"]))
141
+ self.assertFalse(r["completeWithinModel"])
142
+
143
+ def test_continuation_steps_count_from_the_declared_jump(self):
144
+ # The ordinary prefix (jc, jmp bx) takes two steps; maxSteps 2 would leave a whole-path count no room.
145
+ data, config, _ = fan_out(2)
146
+ r = run_report(data, {**config, "maxSteps": 2}, "trace")
147
+ self.assertTrue(all(p["returned"] for p in r["declaredContinuationPaths"]))
148
+ self.assertTrue(all(p["steps"] == 4 for p in r["declaredContinuationPaths"]))
149
+
150
+ def test_visit_limit_counts_repeats_after_the_declared_jump(self):
151
+ data, config, _ = fan_out(2, targets=(SPIN,))
152
+ r = run_report(data, {**config, "visitLimit": 2, "continuationBudget": {"visitLimit": 3}}, "trace")
153
+ (route,) = r["declaredContinuationPaths"]
154
+ self.assertEqual(route["stop"], "instruction repeated more than 3 times after the declared jump; "
155
+ "raise continuationBudget.visitLimit or read the loop's bound")
156
+ self.assertEqual(route["instructionPath"].count(route["stopSite"]), 4)
157
+ self.assertFalse(r["completeWithinModel"])
158
+
159
+ def test_string_iteration_limit_stops_a_continuation(self):
160
+ data, config, _ = fan_out(2, targets=(COPY_TWO,))
161
+ r = run_report(data, config, "trace")
162
+ self.assertTrue(r["declaredContinuationPaths"][0]["returned"])
163
+ self.assertEqual(r["continuationStringIterationsUsed"], 2)
164
+ self.assertEqual(r["stringIterationsUsed"], 0)
165
+ r = run_report(data, {**config, "stringIterations": 0, "continuationBudget": {"stringIterations": 1}}, "trace")
166
+ (route,) = r["declaredContinuationPaths"]
167
+ self.assertFalse(route["returned"])
168
+ self.assertEqual(route["stop"], "Continuation string iteration budget exhausted; remaining effects unresolved")
169
+
170
+ def test_invalid_budgets_are_rejected(self):
171
+ data, config, _ = fan_out(1)
172
+ for budget in ([], {"path": 1}, {"paths": 257}, {"paths": -1}, {"totalSteps": 0}, {"maxSteps": 10001},
173
+ {"visitLimit": 0}, {"stringIterations": 65537}, {"paths": True}, {"paths": 1.5}):
174
+ with self.assertRaises(ValueError, msg=budget):
175
+ run_report(data, {**config, "continuationBudget": budget}, "trace")
176
+
177
+
178
+ if __name__ == "__main__":
179
+ unittest.main()
@@ -47,7 +47,7 @@ class TableContinuationTests(unittest.TestCase):
47
47
 
48
48
  def test_limits_do_not_leave_a_positive_continuation_contract(self):
49
49
  data, config = fixture()
50
- for change in ({"maxPaths": 1}, {"maxSteps": 1}, {"totalSteps": 1}, {"instructionLimit": 1}):
50
+ for change in ({"continuationBudget": {"paths": 0}}, {"instructionLimit": 1}):
51
51
  r = run_report(data, {**config, **change}, "trace")
52
52
  self.assertFalse(any(p["returned"] for p in r["declaredContinuationPaths"]))
53
53
  self.assertFalse(r["completeWithinModel"])
@@ -125,7 +125,9 @@ class TableContinuationTests(unittest.TestCase):
125
125
  self.assertEqual([(p["returned"], p["stop"]) for p in declared["paths"]],
126
126
  [(p["returned"], p["stop"]) for p in plain["paths"]])
127
127
  self.assertEqual(len(declared["paths"]), 3)
128
- self.assertTrue(any(g["reason"] == "path limit" and g["site"] == 32 for g in declared["gaps"]))
128
+ # The ordinary paths spent all three paths, and the continuations still start on their own budget.
129
+ self.assertEqual(len(declared["declaredContinuationPaths"]), 3)
130
+ self.assertTrue(all(p["returned"] for p in declared["declaredContinuationPaths"]))
129
131
 
130
132
  def test_operand_read_stays_out_of_the_stopped_ordinary_path(self):
131
133
  data, config = fixture()