scientific-method-engine 0.3.0__tar.gz → 0.5.0__tar.gz

{scientific_method_engine-0.3.0 → scientific_method_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scientific-method-engine
-Version: 0.3.0
+Version: 0.5.0
 Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
 Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
 Author: kibertoad
@@ -108,3 +108,17 @@ Commands, inputs, limits and acceptance rules are in
 [the bounded evidence reporter guide](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md).
 The reader and engine check that they speak the same prepared-config protocol and refuse to run
 otherwise.
+
+The `effects` command additionally emits path-local `effectOrdering` timelines,
+pre-call write prefixes and bounded local restoration witnesses. Unknown modeled
+or nested service effects stay separate; no return code establishes rollback or
+transactionality. See [the full contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#ordered-effect-path-summaries).
+
+Evidenced segmented16 `indirectJumps` declarations also expose separate
+`declaredContinuationPaths`. Ordinary paths retain their unresolved transfer;
+conditional routes preserve prefix/child effects with target-choice, live-table
+and selector assumptions. Effects summaries never mark those routes complete.
+Concrete values/field addresses reject inconsistent rows; overlap and shared
+path/step/visit/total/boundary limits remain explicit. Partial-table splits are
+partial evidence, never complete dispatch or native-reachability claims. See the
+[table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).

{scientific_method_engine-0.3.0 → scientific_method_engine-0.5.0}/README.md

@@ -96,3 +96,17 @@ Commands, inputs, limits and acceptance rules are in
 [the bounded evidence reporter guide](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md).
 The reader and engine check that they speak the same prepared-config protocol and refuse to run
 otherwise.
+
+The `effects` command additionally emits path-local `effectOrdering` timelines,
+pre-call write prefixes and bounded local restoration witnesses. Unknown modeled
+or nested service effects stay separate; no return code establishes rollback or
+transactionality. See [the full contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#ordered-effect-path-summaries).
+
+Evidenced segmented16 `indirectJumps` declarations also expose separate
+`declaredContinuationPaths`. Ordinary paths retain their unresolved transfer;
+conditional routes preserve prefix/child effects with target-choice, live-table
+and selector assumptions. Effects summaries never mark those routes complete.
+Concrete values/field addresses reject inconsistent rows; overlap and shared
+path/step/visit/total/boundary limits remain explicit. Partial-table splits are
+partial evidence, never complete dispatch or native-reachability claims. See the
+[table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).

{scientific_method_engine-0.3.0 → scientific_method_engine-0.5.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "scientific-method-engine"
 # The release workflow writes the published version from the package's release tag.
-version = "0.3.0"
+version = "0.5.0"
 description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
 readme = "README.md"
 requires-python = ">=3.10"

{scientific_method_engine-0.3.0 → scientific_method_engine-0.5.0}/src/scientific_method_engine/cli.py

@@ -9,6 +9,8 @@ CONFIG_LIMIT = 1024 * 1024
 PREPARED_CONFIG_LIMIT = 16 * 1024 * 1024
 USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bounds|owner|callees|trace|uses|arguments|"
          "effects|returns|memory|incoming|call-order|guards|allocation|dispatch> <config.json|->\n"
+         "effects includes ordered path writes/calls and local restoration witnesses; transactionality remains unestablished.\n"
+         "Declared table continuations are separate conditional paths; ordinary computed transfers remain stopped.\n"
          "       scientific-method-engine ghidra-scripts")
 
 

{scientific_method_engine-0.3.0 → scientific_method_engine-0.5.0}/src/scientific_method_engine/x86/dispatch.py

@@ -1,4 +1,4 @@
-"""Explicit, source-derived indirect jump tables for CFG discovery only."""
+"""Explicit, source-derived indirect jump tables for CFG discovery and explicitly conditional path continuations."""
 from capstone.x86 import X86_OP_IMM
 from .image import integer
 

scientific_method_engine-0.5.0/src/scientific_method_engine/x86/effect_order.py

@@ -0,0 +1,95 @@
+"""Ordered, path-local effect evidence; no transactional or native-execution claims."""
+from bisect import bisect_right
+
+
+KINDS = {"read", "write", "call", "call-return", "return", "branch", "compare", "flag-assumption",
+         "arithmetic", "value-transfer", "conversion", "flag-write", "flags-save", "flags-restore", "local-iret", "string-operation", "declared-jump-continuation"}
+
+
+def _storage(event):
+    # Equal offsets alone cannot identify storage. Retain the segment/base expression
+    # and the complete access width; a narrower restore is a separate access.
+    if not all(k in event for k in ("segment", "offset", "width")):
+        return None
+    # Terms are hashable tuples; compare them directly instead of serializing each access.
+    return (event["segment"].get("expression"), event["offset"].get("expression"), event["width"],
+            event.get("segmentInterpretation"))
+
+
+def effect_ordering(report):
+    """Add bounded path timelines and explicit local restoration witnesses.
+
+    The existing tracer bounds every event. Prefix counts index a path's write
+    list instead of copying that list for every call (linear report size). A
+    witness restores one read value only; it says nothing about other storage,
+    aliases, external effects, resources or transactionality.
+    """
+    summaries = []
+    conditional_summaries = []
+    combined = [(False, i, p) for i, p in enumerate(report["paths"])]
+    combined += [(True, i, p) for i, p in enumerate(report.get("declaredContinuationPaths", []))]
+    for conditional, index, path in combined:
+        timeline, writes, calls, witnesses = [], [], [], []
+        snapshots = {}
+        pending = {}
+        unknown_orders = []
+        last_write = {}
+        for event in path["events"]:
+            kind = event["kind"]
+            if kind in KINDS:
+                timeline.append(event)
+            if kind == "read":
+                key = _storage(event)
+                if key is not None:
+                    snapshots.setdefault(key, {})[event["value"].get("expression")] = event
+            elif kind == "write":
+                key = _storage(event)
+                original = snapshots.get(key, {}).get(event["value"].get("expression"))
+                # An equal expression alone is not a restore: an independent constant store or a
+                # re-pushed return address can match it. The written value must derive from the read.
+                if (original is not None and last_write.get(key, -1) > original["order"]
+                        and original["site"] in event["value"].get("producers", ())):
+                    witnesses.append({"readOrder": original["order"], "restoreOrder": event["order"],
+                                      "entry": event["entry"], "width": event["width"],
+                                      "pathReturned": path["returned"],
+                                      "unknownEffectsBetweenCount": len(unknown_orders) - bisect_right(unknown_orders, original["order"]),
+                                      "meaning": "same complete storage/value expression restored locally; not transactionality"})
+                writes.append(event)
+                last_write[key] = event["order"]
+            elif kind == "call":
+                call = {"order": event["order"], "site": event["site"], "entry": event["entry"],
+                        "depth": event["depth"], "target": event.get("target"),
+                        "writesBeforeCount": len(writes), "status": "unresolved-or-stopped",
+                        "unknownEffects": True, "continuation": None, "_unknownStart": len(unknown_orders)}
+                calls.append(call)
+                pending.setdefault((event["site"], event["depth"]), []).append(call)
+            elif kind == "call-return":
+                stack = pending.get((event["callSite"], event["depth"]), [])
+                if stack:
+                    call = stack.pop()
+                    modeled = event.get("modeled", False)
+                    call.update(status="modeled-return" if modeled else "traced-return",
+                                unknownEffects=bool(modeled or event.get("unknownMemoryEffects") or len(unknown_orders) > call.pop("_unknownStart")),
+                                returnOrder=event["order"], writesAfterCount=len(writes),
+                                continuation="assumes balanced returning service; its memory/flag effects are unknown" if modeled
+                                else "local callee return reached within the instruction model")
+                if event.get("modeled") or event.get("unknownMemoryEffects"):
+                    unknown_orders.append(event["order"])
+        for call in calls:
+            call.pop("_unknownStart", None)
+        boundary = None
+        if path.get("stop"):
+            boundary = {"site": path.get("stopSite"), "reason": path["stop"],
+                        "writesBeforeCount": len(writes), "meaning": "later effects are not read"}
+        destination = conditional_summaries if conditional else summaries
+        destination.append({"path": index, "declaredJumpAssumptions": path.get("declaredJumpAssumptions", []), "returned": path["returned"], "stop": boundary,
+                          "guards": path["guards"], "timeline": timeline,
+                          "writeOrders": [w["order"] for w in writes], "calls": calls,
+                          "localRestorationWitnesses": witnesses,
+                          "effectCompleteWithinModel": bool(path["returned"] and not unknown_orders and not conditional),
+                          "transactionality": "not established; local writes and result codes cannot prove external rollback"})
+    report["effectOrdering"] = {"paths": summaries, "declaredContinuationPaths": conditional_summaries,
+                                "allPathsRead": report["completeWithinModel"],
+                                "nativeReachability": "unconfirmed",
+                                "meaning": "separate conditional paths; write prefixes index each path's writeOrders"}
+    return report

{scientific_method_engine-0.3.0 → scientific_method_engine-0.5.0}/src/scientific_method_engine/x86/reports.py

@@ -5,6 +5,7 @@ from capstone import CS_AC_READ, CS_AC_WRITE
 from capstone.x86 import X86_OP_IMM, X86_OP_MEM, X86_OP_REG
 from .machine import State, StopPath, REGISTERS, ALIASES, segment_register
 from .values import unknown
+from .effect_order import effect_ordering
 from .result_flow import return_flows
 from .image import Image, integer
 from .trace import (trace, walk, call_target, unsupported_transfer, uncovered, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON,
@@ -225,7 +226,8 @@ def uses(image, config):
             for root in established[index:]:
                 stops.setdefault(root, "entry not traced: entry or total instruction budget exhausted")
             break
-        report = trace(image, {**config, "entry": at, "totalSteps": remaining, "stringIterations": string_remaining})
+        report = trace(image, {**config, "entry": at, "totalSteps": remaining, "stringIterations": string_remaining},
+                       continue_declared_jumps=False)
         remaining -= report["stepsUsed"]
         string_remaining -= report["stringIterationsUsed"]
         if not report["completeWithinModel"]:
@@ -495,7 +497,7 @@ def dispatch(image, config):
         raise ValueError("Dispatch table mapping differs from PE source sections")
     for value in values:
         integer(value, 0, (1 << ALIASES[input_reg][2]) - 1, "input value")
-        report = trace(image, {**config, "registers": {**config.get("registers", {}), input_reg: value}})
+        report = trace(image, {**config, "registers": {**config.get("registers", {}), input_reg: value}}, continue_declared_jumps=False)
         outcomes = []
         for path in report["paths"]:
             reached = bool(path["instructionPath"]) and path["instructionPath"][-1] == site
@@ -593,7 +595,8 @@ def allocations(report, config):
                                 "observedExtentBytes": capacity,
                                 "capacity": "conditional on evidenced extent units and pointer identity" if extent else "unresolved: request units and bounded writes do not establish allocated extent",
                                 "rollback": "unproven; failure returns do not undo earlier writes"})
-    return {"allocations": results, "paths": report["paths"], "gaps": report["gaps"], "completeWithinModel": report["completeWithinModel"]}
+    return {"allocations": results, "paths": report["paths"], "declaredContinuationPaths": report["declaredContinuationPaths"],
+            "gaps": report["gaps"], "completeWithinModel": report["completeWithinModel"]}
 
 
 def operand_provenance(image, config):
@@ -1379,6 +1382,8 @@ def _run_report(image, config, command):
         report = near_pointer_provenance(report, config)
     if command == "allocation":
         return allocations(report, config)
+    if command == "effects":
+        report = effect_ordering(report)
     if command == "returns":
         report = return_flows(report, config)
     if command != "trace":

{scientific_method_engine-0.3.0 → scientific_method_engine-0.5.0}/src/scientific_method_engine/x86/trace.py

@@ -214,7 +214,14 @@ def snapshot(state):
     return {name: state.reg(name).report() for name in ALIASES}
 
 
-def trace(image, config):
+def trace(image, config, continue_declared_jumps=True):
+    """Trace bounded paths, preserving declared-table continuations as separate conditional evidence.
+
+    Ordinary paths run first. A path stopped at a declared indirect jump is then
+    continued once per surviving table target, so the continuations never take
+    budget from an ordinary path. Callers that read only ordinary paths pass
+    continue_declared_jumps=False.
+    """
     entry = integer(config.get("entry"), 0, len(image.data) - 1, "entry")
     if not any(entry in r["entries"] for r in image.regions):
         raise ValueError("Trace entry must be an established region entry")
@@ -246,6 +253,11 @@ def trace(image, config):
                 if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
                     raise ValueError("Invalid model register")
     pending, outputs, global_gaps = [State(entry, image, config)], [], []
+    conditional_outputs = []
+    # States stopped at a declared jump site, continued after the ordinary paths.
+    deferred = []
+    boundary_cache = {}
+    boundary_budget = integer(config.get("instructionLimit", 10000), 1, 100000, "instruction limit")
     created = 1
     total_steps = 0
     total_string_steps = 0
@@ -264,11 +276,88 @@ def trace(image, config):
         string_effect(s, ins, count, remaining)
 
     def finish(s, reason=None, returned=False):
-        outputs.append({"returned": returned, "stop": reason, "stopSite": None if returned else s.at, "steps": s.steps,
-                        "instructionPath": s.path, "guards": s.guards, "events": s.events,
-                        "registers": snapshot(s), "conditionalModels": s.conditional})
+        path = {"returned": returned, "stop": reason, "stopSite": None if returned else s.at, "steps": s.steps,
+                "instructionPath": s.path, "guards": s.guards, "events": s.events,
+                "registers": snapshot(s), "conditionalModels": s.conditional}
+        assumptions = getattr(s, "declared_jump_assumptions", [])
+        if assumptions:
+            path["declaredJumpAssumptions"] = assumptions
+            conditional_outputs.append(path)
+        else:
+            outputs.append(path)
 
-    while pending:
+    def declared_continuations(s):
+        # Each child follows one declared target under a recorded assumption. The operand
+        # keeps its traced value; no register or table word is assigned. s is a copy taken
+        # at the jump, so the operand read below never enters the stopped ordinary path.
+        nonlocal created, boundary_budget
+        declaration = image.indirect_jumps[s.at]
+        ins = image.decode(s.at)
+        root_entry = s.frames[-1]["entry"]
+        if root_entry not in boundary_cache:
+            if boundary_budget < 1:
+                global_gaps.append({"site": s.at, "reason": "conditional table boundary instruction limit"})
+                return
+            seen, walk_gaps, _, undecoded, contested = walk(image, [root_entry], boundary_budget)
+            boundary_budget -= max(1, len(seen) + len(undecoded) + len(contested))
+            # A truncated walk never saw the instructions that could contest a target start.
+            if any(g["reason"] == "instruction limit" for g in walk_gaps):
+                seen = {}
+            boundary_cache[root_entry] = seen
+        seen = boundary_cache[root_entry]
+        try:
+            value = s.get(ins, ins.operands[0], image)
+            address = s.address(ins, ins.operands[0]) if ins.operands[0].type == X86_OP_MEM else None
+        except StopPath as error:
+            global_gaps.append({"site": s.at, "reason": "conditional table operand unresolved: " + str(error)})
+            return
+        groups = {}
+        region = image.region(s.at)
+        choice_key = repr(value.term)
+        previous = getattr(s, "declared_jump_choices", {}).get(choice_key)
+        for row in declaration["rows"]:
+            if address is not None:
+                segment, offset, _ = address
+                # A table word inside another declared region uses that region's mapping; one
+                # outside every region is read as an extension of the jump's region.
+                row_region = image.region(row["operandSite"]) or region
+                row_offset = row_region["ip"] + row["operandSite"] - row_region["start"]
+                if segment.number is not None and offset.number is not None:
+                    if not 0 <= row_offset <= 65534 or segment.number * 16 + offset.number != row_region["segment"] * 16 + row_offset:
+                        continue
+            if value.number is not None and value.number != row["rawOffset"]:
+                continue
+            if previous is not None and row["rawOffset"] not in previous:
+                continue
+            groups.setdefault(row["target"], []).append(row)
+        for target, rows in groups.items():
+            if target not in seen:
+                global_gaps.append({"site": s.at, "target": target,
+                                    "reason": "conditional table target boundary is unresolved or instruction-limited"})
+                continue
+            if created >= max_paths:
+                global_gaps.append({"site": s.at, "reason": "path limit"})
+                break
+            child = deepcopy(s)
+            child.declared_jump_choices = {**getattr(child, "declared_jump_choices", {}),
+                                          choice_key: {r["rawOffset"] for r in rows}}
+            assumption = {"site": s.at, "target": target, "tableIndices": [r["index"] for r in rows],
+                          "operandSites": [r["operandSite"] for r in rows], "exhaustive": declaration["exhaustive"],
+                          "evidence": declaration["evidence"], "tableEvidence": declaration["table"]["evidence"],
+                          "operand": value.report(),
+                          "operandAddress": None if address is None else
+                              {"segment": address[0].report(), "offset": address[1].report(), "segmentRegister": address[2]},
+                          "meaning": "conditional target choice from source table; selector, live table contents and reachability unverified"}
+            child.declared_jump_assumptions = [*getattr(child, "declared_jump_assumptions", []), assumption]
+            child.event("declared-jump-continuation", **{k: v for k, v in assumption.items() if k != "site"})
+            child.at = target
+            pending.append(child)
+            created += 1
+
+    while pending or deferred:
+        if not pending:
+            declared_continuations(deferred.pop(0))
+            continue
         state = pending.pop()
         try:
             while True:
@@ -468,6 +557,8 @@ def trace(image, config):
                 if m in ("jmp", "ljmp"):
                     target, provenance = call_target(image, at, ins)
                     if target is None:
+                        if continue_declared_jumps and at in image.indirect_jumps:
+                            deferred.append(deepcopy(state))
                         raise StopPath("unresolved jump: " + provenance.get("reason", "outside mapped code"))
                     if m == "ljmp":
                         target_region = image.region(target)
@@ -519,7 +610,7 @@ def trace(image, config):
                 state.at = following
         except StopPath as error:
             finish(state, str(error))
-    return {"paths": outputs, "gaps": global_gaps,
+    return {"paths": outputs, "declaredContinuationPaths": conditional_outputs, "gaps": global_gaps,
             "completeWithinModel": not global_gaps and bool(outputs) and all(p["returned"] for p in outputs),
             "nativeReachability": "unconfirmed", "stepsUsed": total_steps, "stringIterationsUsed": total_string_steps,
             "limits": {"steps": max_steps, "paths": max_paths, "depth": max_depth}}

scientific_method_engine-0.5.0/tests/test_effect_order.py

@@ -0,0 +1,114 @@
+"""Synthetic path evidence; no original bytes or claims."""
+import unittest
+from test_x86 import Code, report
+
+
+class EffectOrderTests(unittest.TestCase):
+    def paths(self, result):
+        return result["effectOrdering"]["paths"]
+
+    def test_early_exit_has_distinct_write_contract_at_common_return(self):
+        c = Code().emit("85 c0").branch("74", "return").emit("c7 06 20 00 01 00").label("return").emit("c3")
+        r = report(c, "effects")
+        self.assertTrue(r["effectOrdering"]["allPathsRead"])
+        self.assertEqual(sorted(len(p["writeOrders"]) for p in self.paths(r)), [0, 1])
+        self.assertTrue(all(p["guards"] for p in self.paths(r)))
+        self.assertTrue(all(p["transactionality"].startswith("not established") for p in self.paths(r)))
+
+    def test_writes_before_modeled_failure_and_later_predicate_remain_separate(self):
+        c = Code().emit("c7 06 20 00 01 00").label("service").branch("e8", "serviceBody")
+        c.emit("83 3e 22 00 00").branch("74", "return").emit("c7 06 24 00 02 00").label("return").emit("c3")
+        c.label("serviceBody").emit("c3")
+        r = report(c, "effects", callModels=[{"site": c.labels["service"], "evidence": "synthetic conditional failure",
+                                               "cases": [{"registers": {"ax": 1}}]}])
+        for p in self.paths(r):
+            call = p["calls"][0]
+            self.assertEqual(call["writesBeforeCount"], 1)
+            self.assertEqual(call["status"], "modeled-return")
+            self.assertTrue(call["unknownEffects"])
+            self.assertFalse(p["effectCompleteWithinModel"])
+            branch = next(e for e in p["timeline"] if e["kind"] == "branch")
+            compare = next(e for e in p["timeline"] if e["kind"] == "compare")
+            self.assertGreater(compare["order"], call["returnOrder"])
+            self.assertGreater(branch["order"], compare["order"])
+            self.assertEqual(branch["flagProducer"], compare["site"])
+
+    def test_child_writes_are_not_lost_in_caller_bracket(self):
+        c = Code().emit("c7 06 20 00 01 00").branch("e8", "child").emit("c7 06 20 00 00 00 c3")
+        c.label("child").emit("c7 06 20 00 03 00 c3")
+        p = self.paths(report(c, "effects", registers={"ds": 0x2000, "ss": 0x3000, "sp": 0xff00}))[0]
+        writes = [e for e in p["timeline"] if e["kind"] == "write" and e.get("role") != "stack"]
+        self.assertTrue(any(e["entry"] == c.labels["child"] and e["value"]["value"] == 3 for e in writes))
+        self.assertEqual(p["calls"][0]["status"], "traced-return")
+        self.assertFalse(p["calls"][0]["unknownEffects"])
+
+    def test_unknown_nested_service_propagates_to_outer_call(self):
+        c = Code().branch("e8", "child").emit("c3").label("child").label("service").branch("e8", "external").emit("c3")
+        c.label("external").emit("c3")
+        r = report(c, "effects", callModels=[{"site": c.labels["service"], "evidence": "unknown child service", "cases": [{}]}])
+        p = self.paths(r)[0]
+        self.assertTrue(all(call["unknownEffects"] for call in p["calls"]))
+        self.assertFalse(p["effectCompleteWithinModel"])
+
+    def test_snapshot_restore_witness_does_not_cover_bypass_or_other_storage(self):
+        c = Code().emit("a1 20 00 c7 06 20 00 02 00 85 db").branch("74", "return")
+        c.emit("a3 20 00").label("return").emit("c3")
+        r = report(c, "effects")
+        self.assertEqual(sorted(len(p["localRestorationWitnesses"]) for p in self.paths(r)), [0, 1])
+        w = next(w for p in self.paths(r) for w in p["localRestorationWitnesses"])
+        self.assertEqual(w["width"], 2)
+        self.assertTrue(w["pathReturned"])
+        self.assertEqual(w["unknownEffectsBetweenCount"], 0)
+        for code in ["a1 20 00 c7 06 20 00 02 00 a3 22 00 c3",  # other storage
+                     "a1 20 00 c7 06 20 00 02 00 a2 20 00 c3",  # partial width
+                     "a1 20 00 c7 06 20 00 02 00 b8 03 00 a3 20 00 c3",  # changed value
+                     "a1 20 00 c7 06 20 00 02 00 26 a3 20 00 c3"]:  # other segment
+            self.assertFalse(self.paths(report(code, "effects"))[0]["localRestorationWitnesses"])
+
+    def test_equal_value_without_read_provenance_is_not_a_restore(self):
+        # An independent immediate store equals the value read earlier.
+        p = self.paths(report("c7 06 20 00 00 00 83 3e 20 00 00 c7 06 20 00 05 00 c7 06 20 00 00 00 c3", "effects"))[0]
+        self.assertFalse(p["localRestorationWitnesses"])
+        # A loop re-pushes the same return address into a stack slot another call overwrote.
+        c = Code().emit("b9 02 00").label("top").branch("e8", "a").branch("e8", "b").emit("49").branch("75", "top").emit("c3")
+        c.label("a").emit("c3").label("b").emit("c3")
+        r = report(c, "effects", registers={"ss": 0x3000, "sp": 0xff00})
+        self.assertTrue(any(p["returned"] for p in self.paths(r)))
+        self.assertFalse([w for p in self.paths(r) for w in p["localRestorationWitnesses"]])
+
+    def test_timeline_keeps_flag_assumptions_that_split_paths(self):
+        r = report("b9 02 00 f3 a4 c3", "effects")
+        self.assertEqual(len(self.paths(r)), 2)
+        values = sorted(next(e for e in p["timeline"] if e["kind"] == "flag-assumption")["value"]["value"] for p in self.paths(r))
+        self.assertEqual(values, [0, 1])
+
+    def test_restore_prefix_is_not_a_completed_return(self):
+        p = self.paths(report("a1 20 00 c7 06 20 00 02 00 a3 20 00 ee", "effects"))[0]
+        self.assertTrue(p["localRestorationWitnesses"])
+        self.assertFalse(p["localRestorationWitnesses"][0]["pathReturned"])
+        self.assertFalse(p["effectCompleteWithinModel"])
+
+    def test_unknown_service_between_snapshot_and_restore_remains_visible(self):
+        c = Code().emit("a1 20 00 50 c7 06 20 00 02 00").label("service").branch("e8", "child")
+        c.emit("58 a3 20 00 c3").label("child").emit("c3")
+        r = report(c, "effects", callModels=[{"site": c.labels["service"], "evidence": "unknown external effects", "cases": [{}]}])
+        p = self.paths(r)[0]
+        self.assertFalse(p["effectCompleteWithinModel"])
+        # The model invalidates stack memory too; no surviving snapshot value is guessed.
+        self.assertFalse(p["localRestorationWitnesses"])
+
+    def test_port_stop_and_path_caps_cannot_prove_absent_later_effects(self):
+        p = self.paths(report("c7 06 20 00 01 00 ee c7 06 22 00 02 00 c3", "effects"))[0]
+        self.assertFalse(p["returned"])
+        self.assertEqual(p["stop"]["writesBeforeCount"], 1)
+        self.assertIn("port", p["stop"]["reason"].lower())
+        r = report("85 c0 74 06 c7 06 20 00 01 00 c3", "effects", maxPaths=1)
+        self.assertFalse(r["effectOrdering"]["allPathsRead"])
+        self.assertTrue(r["gaps"])
+        r = report("c7 06 20 00 01 00 c3", "effects", maxSteps=1)
+        self.assertFalse(self.paths(r)[0]["returned"])
+        self.assertEqual(self.paths(r)[0]["stop"]["writesBeforeCount"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

scientific_method_engine-0.5.0/tests/test_table_continuations.py

@@ -0,0 +1,161 @@
+"""Conditional source-table routes never replace unresolved execution evidence."""
+import copy
+import unittest
+from test_dispatch import fixture
+from scientific_method_engine.x86.reports import run_report
+
+
+class TableContinuationTests(unittest.TestCase):
+    def test_stopped_path_is_retained_beside_conditional_child_routes(self):
+        data, config = fixture()
+        r = run_report(data, config, "effects")
+        self.assertFalse(r["completeWithinModel"])
+        self.assertFalse(any(p["returned"] for p in r["paths"]))
+        routes = r["declaredContinuationPaths"]
+        self.assertEqual(len(routes), 2)
+        self.assertTrue(all(p["returned"] for p in routes))
+        self.assertTrue(all(p["declaredJumpAssumptions"] for p in routes))
+        self.assertTrue(any(e["kind"] == "call" for p in routes for e in p["events"]))
+        self.assertTrue(all(not p["effectCompleteWithinModel"] for p in r["effectOrdering"]["declaredContinuationPaths"]))
+
+    def test_partial_table_and_concrete_mismatch_remain_unresolved(self):
+        data, config = fixture()
+        config["indirectJumps"][0]["exhaustive"] = False
+        r = run_report(data, config, "trace")
+        self.assertTrue(r["declaredContinuationPaths"])
+        self.assertTrue(all(not p["declaredJumpAssumptions"][0]["exhaustive"] for p in r["declaredContinuationPaths"]))
+        r = run_report(data, {**config, "registers": {"bx": 20}}, "trace")
+        self.assertFalse(r["declaredContinuationPaths"])
+        self.assertFalse(r["completeWithinModel"])
+
+    def test_duplicate_targets_share_one_conditional_route(self):
+        data, config = fixture()
+        data = bytearray(data)
+        data[34:36] = data[32:34]
+        r = run_report(bytes(data), config, "trace")
+        self.assertEqual(len(r["declaredContinuationPaths"]), 1)
+        self.assertEqual(r["declaredContinuationPaths"][0]["declaredJumpAssumptions"][0]["tableIndices"], [0, 1])
+
+    def test_overlap_targets_cannot_establish_a_continuation(self):
+        data, config = fixture()
+        data = bytearray(data)
+        data[8:12] = bytes.fromhex("b8 e8 00 c3")
+        data[34:36] = bytes.fromhex("09 00")
+        r = run_report(bytes(data), config, "trace")
+        self.assertFalse(r["declaredContinuationPaths"])
+        self.assertTrue(any("boundary" in g["reason"] for g in r["gaps"]))
+
+    def test_limits_do_not_leave_a_positive_continuation_contract(self):
+        data, config = fixture()
+        for change in ({"maxPaths": 1}, {"maxSteps": 1}, {"totalSteps": 1}, {"instructionLimit": 1}):
+            r = run_report(data, {**config, **change}, "trace")
+            self.assertFalse(any(p["returned"] for p in r["declaredContinuationPaths"]))
+            self.assertFalse(r["completeWithinModel"])
+
+    def test_conditional_loop_keeps_visits_and_prefix_write(self):
+        data, config = fixture()
+        data = bytearray(data)
+        data[0:8] = bytes.fromhex("c7 06 20 00 01 00 ff e3")
+        data[16:18] = bytes.fromhex("eb fe")
+        config = copy.deepcopy(config)
+        config["indirectJumps"][0]["site"] = 6
+        r = run_report(bytes(data), {**config, "visitLimit": 1}, "effects")
+        self.assertTrue(any(p["returned"] for p in r["declaredContinuationPaths"]))
+        self.assertTrue(any(p["stop"] and "repeated" in p["stop"] for p in r["declaredContinuationPaths"]))
+        self.assertTrue(all(p["timeline"][0]["kind"] == "write" for p in r["effectOrdering"]["declaredContinuationPaths"]))
+
+    def test_repeated_operand_cannot_choose_a_contradictory_target(self):
+        data, config = fixture()
+        data = bytearray(data)
+        data[16:18] = bytes.fromhex("eb ee")
+        r = run_report(bytes(data), {**config, "visitLimit": 3}, "trace")
+        returned = [p for p in r["declaredContinuationPaths"] if p["returned"]]
+        self.assertTrue(returned)
+        self.assertTrue(all({a["target"] for a in p["declaredJumpAssumptions"]} == {8} for p in returned))
+        self.assertTrue(any(p["stop"] and "repeated" in p["stop"] for p in r["declaredContinuationPaths"]))
+
+    def test_resolved_memory_field_selects_only_its_declared_row(self):
+        data, config = fixture()
+        data = bytearray(data)
+        data[0:3] = bytes.fromhex("2e ff 27")
+        r = run_report(bytes(data), {**config, "registers": {"bx": 32}}, "trace")
+        self.assertEqual(len(r["declaredContinuationPaths"]), 1)
+        a = r["declaredContinuationPaths"][0]["declaredJumpAssumptions"][0]
+        self.assertEqual(a["tableIndices"], [0])
+        self.assertEqual(a["operandAddress"]["segmentRegister"], "cs")
+        r = run_report(bytes(data), {**config, "registers": {"bx": 36}}, "trace")
+        self.assertFalse(r["declaredContinuationPaths"])
+
+    def test_prefix_mutation_precedes_child_failure_and_bypasses_clear(self):
+        data = bytearray([0x90] * 80)
+        data[0:8] = bytes.fromhex("c7 06 20 00 01 00 ff e3")
+        data[16:27] = bytes.fromhex("e8 1d 00 85 c0 74 05 b8 ff ff c3")
+        data[28:35] = bytes.fromhex("c7 06 20 00 00 00 c3")
+        data[40:44] = bytes.fromhex("b8 00 00 c3")
+        data[48:52] = bytes.fromhex("b8 ff ff c3")
+        data[64:68] = bytes.fromhex("10 00 28 00")
+        config = {"entry": 0, "registers": {"ds": 0x2000, "ss": 0x3000, "sp": 0xff00},
+                  "regions": [{"name": "synthetic", "start": 0, "end": 56, "ip": 0, "segment": 0x1000,
+                               "entries": [0], "evidence": "constructed bounded code"}],
+                  "indirectJumps": [{"site": 6, "exhaustive": True, "evidence": "synthetic BX choice",
+                      "table": {"start": 64, "count": 2, "stride": 2, "evidence": "synthetic word targets"}}]}
+        r = run_report(bytes(data), config, "effects")
+        failure = next(p for p in r["declaredContinuationPaths"] if p["returned"] and p["registers"]["ax"]["value"] == 65535)
+        write = next(e for e in failure["events"] if e["kind"] == "write" and e["site"] == 0)
+        call = next(e for e in failure["events"] if e["kind"] == "call" and e["site"] == 16)
+        self.assertLess(write["order"], call["order"])
+        self.assertFalse(any(e["kind"] == "write" and e["site"] == 28 for e in failure["events"]))
+        self.assertFalse(r["completeWithinModel"])
+        self.assertTrue(all(not p["effectCompleteWithinModel"] for p in r["effectOrdering"]["declaredContinuationPaths"]))
+
+    def test_continuations_never_take_budget_from_ordinary_paths(self):
+        data = bytearray([0x90] * 52)
+        data[0:2] = bytes.fromhex("72 1e")
+        data[2:8] = bytes.fromhex("85 c0 74 01 c3 c3")
+        data[32:34] = bytes.fromhex("ff e3")
+        data[40:45] = bytes.fromhex("85 c9 74 00 c3")
+        data[48:52] = bytes.fromhex("28 00 2c 00")
+        config = {"entry": 0, "maxPaths": 3,
+                  "regions": [{"name": "code", "start": 0, "end": 48, "segment": 4096, "ip": 0,
+                               "entries": [0], "evidence": "constructed mappings"}],
+                  "indirectJumps": [{"site": 32, "evidence": "constructed BX consumer", "exhaustive": True,
+                                     "table": {"start": 48, "count": 2, "stride": 2, "evidence": "constructed words"}}]}
+        declared = run_report(bytes(data), config, "trace")
+        plain = run_report(bytes(data), {k: v for k, v in config.items() if k != "indirectJumps"}, "trace")
+        self.assertEqual([(p["returned"], p["stop"]) for p in declared["paths"]],
+                         [(p["returned"], p["stop"]) for p in plain["paths"]])
+        self.assertEqual(len(declared["paths"]), 3)
+        self.assertTrue(any(g["reason"] == "path limit" and g["site"] == 32 for g in declared["gaps"]))
+
+    def test_operand_read_stays_out_of_the_stopped_ordinary_path(self):
+        data, config = fixture()
+        data = bytearray(data)
+        data[0:3] = bytes.fromhex("2e ff 27")
+        r = run_report(bytes(data), {**config, "registers": {"bx": 32}}, "trace")
+        self.assertFalse(any(e["kind"] == "read" for e in r["paths"][0]["events"]))
+        self.assertTrue(any(e["kind"] == "read" for e in r["declaredContinuationPaths"][0]["events"]))
+
+    def test_truncated_boundary_walk_establishes_no_target(self):
+        data, config = fixture()
+        r = run_report(data, {**config, "instructionLimit": 2}, "trace")
+        self.assertFalse(r["declaredContinuationPaths"])
+        self.assertTrue(any("boundary" in g["reason"] for g in r["gaps"]))
+
+    def test_field_address_uses_the_table_region_mapping(self):
+        data, config = fixture()
+        data = bytearray(data)
+        data[0:3] = bytes.fromhex("2e ff 27")
+        config = copy.deepcopy(config)
+        config["regions"][0]["end"] = 32
+        config["regions"].append({"name": "table", "start": 32, "end": 40, "segment": 4096, "ip": 0x100,
+                                  "entries": [36], "evidence": "constructed table mapping"})
+        r = run_report(bytes(data), {**config, "registers": {"bx": 0x100}}, "trace")
+        self.assertEqual([p["declaredJumpAssumptions"][0]["tableIndices"] for p in r["declaredContinuationPaths"]], [[0]])
+        r = run_report(bytes(data), {**config, "registers": {"bx": 32}}, "trace")
+        self.assertFalse(r["declaredContinuationPaths"])
+
+    def test_allocation_retains_the_conditional_routes(self):
+        data, config = fixture()
+        allocation = run_report(data, {**config, "allocations": [{"site": 8, "unitBytes": 16, "unitEvidence": "constructed unit",
+                                                                  "requestRegister": "bx"}]}, "allocation")
+        self.assertEqual(len(allocation["declaredContinuationPaths"]), 2)