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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scientific-method-engine
-Version: 0.1.0
+Version: 0.3.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

{scientific_method_engine-0.1.0 → scientific_method_engine-0.3.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.1.0"
+version = "0.3.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.1.0 → scientific_method_engine-0.3.0}/src/scientific_method_engine/cli.py

@@ -8,7 +8,7 @@ from . import PREPARED_PROTOCOL
 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|guards|allocation|dispatch> <config.json|->\n"
+         "effects|returns|memory|incoming|call-order|guards|allocation|dispatch> <config.json|->\n"
          "       scientific-method-engine ghidra-scripts")
 
 

{scientific_method_engine-0.1.0 → scientific_method_engine-0.3.0}/src/scientific_method_engine/x86/machine.py

@@ -1,7 +1,7 @@
 """Path-specific instruction effects. Unsupported semantics stop the path."""
 from copy import deepcopy
 from capstone.x86 import X86_OP_REG, X86_OP_IMM, X86_OP_MEM
-from .values import Value, const, unknown, op, extract, join, resize, sources, address_parts
+from .values import Value, const, unknown, op, extract, join, resize, sources, address_parts, producers
 
 REGISTERS = ("eax", "ebx", "ecx", "edx", "esi", "edi", "ebp", "esp", "cs", "ds", "es", "ss", "fs", "gs")
 ALIASES = {}
@@ -41,6 +41,8 @@ class State:
         self.sp, self.bp = ("esp", "ebp") if self.flat else ("sp", "bp")
         self.at = entry
         self.regs = {r: unknown("initial:" + r, ALIASES[r][2]) for r in REGISTERS}
+        # Producers per register byte, so a partial write replaces only the bytes it stores.
+        self.reg_sources = {r: [()] * (ALIASES[r][2] // 8) for r in REGISTERS}
         self.regs["esp"] = resize(unknown("entry:sp", self.bits), 32)
         self.setreg(self.sp, unknown("entry:sp", self.bits), None)
         self.segment_bases = {r: const(0, 32) if r in ("cs", "ds", "es", "ss") else unknown("initial-base:" + r, 32)
@@ -55,6 +57,8 @@ class State:
         self.memory_groups = {}
         self.memory_epoch = 0
         self.events = []
+        # Value transfers are recorded only for queries that trace declared return results.
+        self.value_transfers = bool(config.get("returnContracts"))
         self.guards = []
         self.assumptions = {}
         self.flags = None
@@ -134,7 +138,8 @@ class State:
 
     def reg(self, name):
         root, low, bits = alias(name)
-        return extract(self.regs[root], low, bits)
+        value = extract(self.regs[root], low, bits)
+        return Value(bits, value.term, tuple(sorted(set().union(*self.reg_sources[root][low // 8:(low + bits) // 8]))))
 
     def setreg(self, name, value, site):
         root, low, bits = alias(name)
@@ -147,6 +152,7 @@ class State:
             chunks = [extract(old, n, 8) for n in range(0, old.bits, 8)]
             chunks[low // 8:(low + bits) // 8] = [extract(value, n, 8) for n in range(0, bits, 8)]
             self.regs[root] = join(chunks)
+        self.reg_sources[root][low // 8:(low + bits) // 8] = [value.sources] * (bits // 8)
 
     def event(self, kind, **fields):
         event = {"kind": kind, "site": self.at, "entry": self.frames[-1]["entry"],
@@ -225,7 +231,7 @@ class State:
         event = self.event("write" if write is not None else "read", segment=segment.report(), offset=offset.report(),
                            width=width, effectiveSegmentRegister=addressing_register, segmentInterpretation="base" if self.flat else "selector-paragraph", interval={"segment": seg, "base": base, "start": delta, "end": delta + width},
                            value=value.report(), missingByteProducers=missing,
-                           byteProducers=[{"index": i, "producers": list(self.memory[key].sources) if key in self.memory else []} for i, key in enumerate(keys)],
+                           byteProducers=[{"index": i, "producers": producers(self.memory[key]) if key in self.memory else []} for i, key in enumerate(keys)],
                            guards=deepcopy(relevant), role=role,
                            uncertainAliasesInvalidated=len(uncertain))
         f = self.frames[-1]
@@ -234,7 +240,7 @@ class State:
         relative = (mem_delta - stack_delta) % (1 << self.bits)
         if write is None and segment.term == self.segment("ss").term and mem_base == stack_base and f["returnBytes"] <= relative < 1 << (self.bits - 1):
             event["argument"] = {"offsetFromEntrySP": relative, "width": width, "returnFrameBytes": f["returnBytes"],
-                                 "pushProducers": list(value.sources), "grouping": role or "consumed width only"}
+                                 "pushProducers": producers(value), "grouping": role or "consumed width only"}
         return value
 
     def address(self, ins, operand):
@@ -287,6 +293,19 @@ class State:
         return value
 
 
+# Synonymous and complementary branches on one flag producer share a single assumption.
+BRANCH_CONDITIONS = {}
+for names, condition in ((("je", "jz"), "z"), (("jb", "jc", "jnae"), "c"), (("jbe", "jna"), "be"),
+                         (("jl", "jnge"), "l"), (("jle", "jng"), "le"), (("js",), "s"),
+                         (("jo",), "o"), (("jp", "jpe"), "p")):
+    for name in names:
+        BRANCH_CONDITIONS[name] = (condition, False)
+for names, condition in ((("jne", "jnz"), "z"), (("jae", "jnb", "jnc"), "c"), (("ja", "jnbe"), "be"),
+                         (("jge", "jnl"), "l"), (("jg", "jnle"), "le"), (("jns",), "s"),
+                         (("jno",), "o"), (("jnp", "jpo"), "p")):
+    for name in names:
+        BRANCH_CONDITIONS[name] = (condition, True)
+
 CARRY_BRANCHES = {"jb": True, "jc": True, "jnae": True, "jae": False, "jnb": False, "jnc": False}
 # Branches taken when CF or OF is set; logic operations clear both whatever their operands.
 CLEARED_BY_LOGIC = {**CARRY_BRANCHES, "jo": True, "jno": False}
@@ -361,7 +380,18 @@ def ordinary(state, ins, image):
         if state.flat and operands[0].type == X86_OP_REG and ins.reg_name(operands[0].reg) in state.segment_bases:
             raise StopPath("Segment selector assignment requires a descriptor model")
         value = state.get(ins, operands[1], image)
-        state.put(ins, operands[0], resize(value, operands[0].size * 8, signed=m == "movsx"))
+        result = resize(value, operands[0].size * 8, signed=m == "movsx")
+        state.put(ins, operands[0], result)
+        if not state.value_transfers:
+            return
+
+        def location(operand):
+            return {"kind": "register", "register": ins.reg_name(operand.reg)} if operand.type == X86_OP_REG else {"kind": "memory"} if operand.type == X86_OP_MEM else {"kind": "immediate"}
+        destination_container = ALIASES[ins.reg_name(operands[0].reg)][0] if operands[0].type == X86_OP_REG else None
+        state.event("value-transfer", operation=m, source=location(operands[1]), destination=location(operands[0]),
+                    destinationContainer=destination_container, destinationContainerValue=state.reg(destination_container).report() if destination_container else None,
+                    sourceBits=value.bits, destinationBits=result.bits, sourceValue=value.report(), resultValue=result.report(),
+                    conversion="truncate" if result.bits < value.bits else "signExtend" if m == "movsx" else "zeroExtend" if result.bits > value.bits else "sameWidth")
         return
     if m == "xchg":
         values = [state.get(ins, operand, image) for operand in operands]
@@ -445,21 +475,25 @@ def ordinary(state, ins, image):
         # The prefix toggles the mode's default operand size (16-bit real mode, 32-bit flat).
         wide = (0x66 in ins.prefix) != state.flat
         source, destination = ("ax", "eax") if wide else ("al", "ax")
-        value = resize(state.reg(source), 32 if wide else 16, True)
+        source_value = state.reg(source)
+        value = resize(source_value, 32 if wide else 16, True)
         state.setreg(destination, value, state.at)
         state.event("conversion", sourceRegister=source, destinationRegister=destination,
                     effectiveOperandBits=32 if wide else 16, decoderMnemonic=m,
-                    mnemonicWidthMismatch=m != ("cwde" if wide else "cbw"), result=value.report())
+                    mnemonicWidthMismatch=m != ("cwde" if wide else "cbw"), result=value.report(),
+                    sourceValue=source_value.report(), sourceBits=source_value.bits, destinationBits=value.bits, conversion="signExtend")
         return
     if m in ("cwd", "cdq"):
         wide = (0x66 in ins.prefix) != state.flat
         source, destination = ("eax", "edx") if wide else ("ax", "dx")
         bits = 32 if wide else 16
-        value = resize(extract(state.reg(source), bits-1, 1), bits, signed=True)
+        source_value = state.reg(source)
+        value = resize(extract(source_value, bits-1, 1), bits, signed=True)
         state.setreg(destination, value, state.at)
         state.event("conversion", sourceRegister=source, destinationRegister=destination,
                     effectiveOperandBits=bits, decoderMnemonic=m,
-                    mnemonicWidthMismatch=m != ("cdq" if wide else "cwd"), result=value.report())
+                    mnemonicWidthMismatch=m != ("cdq" if wide else "cwd"), result=value.report(),
+                    sourceValue=source_value.report(), sourceBits=source_value.bits, destinationBits=value.bits, conversion="signFillHighHalf")
         return
     if m in ("clc", "stc", "cmc"):
         if m == "cmc":

{scientific_method_engine-0.1.0 → scientific_method_engine-0.3.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 .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,
                     RETURNS, INTERRUPTS, PORTS)
@@ -298,7 +299,9 @@ def uses(image, config):
             if state is None:
                 # Registers are unknown here; name them for this operand site so no entry value is implied.
                 state = State(at, image, {})
-                state.regs.update({r: unknown(f"CFG-operand:{at}:{r}", ALIASES[r][2]) for r in REGISTERS if r != "cs"})
+                for r in REGISTERS:
+                    if r != "cs":
+                        state.setreg(r, unknown(f"CFG-operand:{at}:{r}", ALIASES[r][2]), None)
             try:
                 segment_value, offset_value, segment_name = state.address(ins, operand)
             except StopPath as error:
@@ -994,6 +997,200 @@ def callees(image, config):
                               "that does not. Neither proves runtime recursion."}
 
 
+# These branches test CX/ECX (LOOPE/LOOPNE also ZF), so an adjacent CMP/TEST never describes their predicate.
+COUNT_BRANCHES = frozenset(("jcxz", "jecxz", "jrcxz", "loop", "loope", "loopne", "loopz", "loopnz"))
+
+
+def _operand_view(ins, o):
+    if o.type == X86_OP_REG:
+        return {"kind": "register", "name": ins.reg_name(o.reg), "width": o.size}
+    if o.type == X86_OP_IMM:
+        return {"kind": "immediate", "value": o.imm, "width": o.size}
+    if o.type == X86_OP_MEM:
+        return {"kind": "memory", "width": memory_width(ins, o), "segmentRegister": segment_register(ins, o.mem),
+                "baseRegister": ins.reg_name(o.mem.base) or None, "indexRegister": ins.reg_name(o.mem.index) or None,
+                "displacement": o.mem.disp}
+    return {"kind": "unresolved"}
+
+
+def _stack_cleanup(ins):
+    """The bytes an immediate ADD SP/ESP releases, or None for any other instruction or a negative immediate."""
+    if (ins is None or ins.mnemonic != "add" or len(ins.operands) != 2 or ins.operands[0].type != X86_OP_REG
+            or ins.reg_name(ins.operands[0].reg) not in ("sp", "esp") or ins.operands[1].type != X86_OP_IMM):
+        return None
+    bits = 8 * ins.operands[0].size
+    amount = ins.operands[1].imm & ((1 << bits) - 1)
+    return amount if 0 < amount < 1 << (bits - 1) else None
+
+
+def call_order(image, config):
+    """Group the confirmed incoming calls of each containing entry by necessary guards and CFG order."""
+    flat = incoming(image, config)
+    entry_limit = integer(config.get("entryLimit", 64), 1, 256, "entry limit")
+    analysis_limit = integer(config.get("analysisLimit", 1000000), 1, 10000000, "call order analysis limit")
+    established = entries(image)
+    bodies = {e: body(image, e, config.get("instructionLimit", 10000)) for e in established[:entry_limit]}
+    conflicts = _cross_entry_overlaps(bodies)
+    unchecked = established[entry_limit:]
+    sites = {r["site"] for r in flat["confirmed"]}
+    owners = {at: [e for e, b in bodies.items() if at in b["instructions"]] for at in sites}
+    reports = []
+    for entry, b in bodies.items():
+        selected = sorted(at for at in sites if entry in owners[at])
+        if not selected:
+            continue
+        usable = b["complete"] and not unchecked and not conflicts.get(entry) and not flat["truncated"] and all(owners[at] == [entry] for at in selected)
+        instructions, successors, branches, exits = b["instructions"], {}, [], set()
+        ending = {}
+        for at, ins in instructions.items():
+            ending.setdefault(at + ins.size, []).append(at)
+        for at, ins in instructions.items():
+            m, following = base_mnemonic(ins), at + ins.size
+            targets = []
+            if m in RETURNS or m == "hlt" or unsupported_transfer(image, ins):
+                pass
+            elif m in ("jmp", "ljmp"):
+                d = image.indirect_jumps.get(at)
+                targets = [r["target"] for r in d["rows"]] if d else [call_target(image, at, ins)[0]]
+            elif m.startswith("j") or m.startswith("loop"):
+                target = call_target(image, at, ins)[0]
+                targets = [target, following]
+                if target != following:
+                    producer = ending.get(at, []) if m not in COUNT_BRANCHES and at != entry else []
+                    comparison = instructions[producer[0]] if len(producer) == 1 else None
+                    context = ({"site": producer[0], "mnemonic": comparison.mnemonic,
+                                "operands": [_operand_view(comparison, o) for o in comparison.operands]}
+                               if comparison and comparison.mnemonic in ("cmp", "test") else None)
+                    for taken, to in ((True, target), (False, following)):
+                        if to is not None:
+                            branches.append({"site": at, "to": to, "taken": taken, "predicate": m,
+                                             "comparison": context, "interpretation": "necessary caller CFG edge, not a runtime value or preserved guard"})
+            else:
+                targets = [following]
+            successors[at] = sorted(set(t for t in targets if t in instructions))
+            # Returns, halts, unsupported frames and transfers out of the body leave the caller CFG.
+            if not targets or any(t not in instructions for t in targets):
+                exits.add(at)
+        predecessors = {}
+        for source, targets in successors.items():
+            for to in targets:
+                predecessors.setdefault(to, set()).add(source)
+        for guard in branches:
+            if guard["comparison"] and predecessors.get(guard["site"], set()) != {guard["comparison"]["site"]}:
+                guard["comparison"] = None
+        cache, spent, capped = {}, 0, False
+        def reachable(start, blocked=None, stops=frozenset()):
+            nonlocal spent, capped
+            key = (start, blocked, stops)
+            if key in cache:
+                return cache[key]
+            todo, seen = [start], set()
+            while todo:
+                at = todo.pop()
+                if at in seen or at not in instructions or at in stops:
+                    continue
+                if spent >= analysis_limit:
+                    capped = True
+                    return set()
+                spent += 1
+                seen.add(at)
+                todo.extend(to for to in successors[at] if (at, to) != blocked)
+            cache[key] = seen
+            return seen
+
+        def dominates(first, second):
+            """Whether every route from the entry to second passes first."""
+            return second not in reachable(entry, stops=frozenset((first,)))
+
+        def must_follow(first, second, guards):
+            """Whether every route from first's continuation reaches second before an exit or a guard revisit."""
+            start = first + instructions[first].size
+            if start == second:
+                return True
+            if start in guards:
+                return False
+            seen = reachable(start, stops=guards | {second})
+            return not seen & exits and not any(to in guards for at in seen for to in successors[at])
+        necessary = {at: [] for at in selected}
+        for guard in branches:
+            remaining = reachable(entry, (guard["site"], guard["to"]))
+            for at in selected:
+                if at not in remaining:
+                    necessary[at].append({k: v for k, v in guard.items() if k != "to"})
+        later = {at: reachable(at + instructions[at].size) & sites for at in selected}
+        rows = []
+        for at in selected:
+            following = at + instructions[at].size
+            amount = _stack_cleanup(instructions.get(following))
+            rows.append({"site": at, "necessaryGuards": necessary[at] if not capped else [],
+                         "cleanup": {"continuation": following, "site": following if amount is not None else None,
+                                     "argumentBytes": amount, "status": "observed after assumed return" if amount is not None else "unread cleanup",
+                                     "assumption": "callee returns to the next instruction"},
+                         "calleeEffects": {"status": "unresolved", "reason": "caller CFG never proves callee return success or restored/preserved state"}})
+        partitions = {}
+        for row in rows:
+            key = tuple((g["site"], g["taken"]) for g in row["necessaryGuards"])
+            partitions.setdefault(key, []).append(row["site"])
+        groups = []
+        for members in partitions.values():
+            shared_guards = next(r["necessaryGuards"] for r in rows if r["site"] == members[0]) if not capped else []
+            guard_sites = frozenset(g["site"] for g in shared_guards)
+            local_later = {at: reachable(at + instructions[at].size, stops=guard_sites) & sites for at in members}
+            pairs = [(a, z) for index, a in enumerate(members) for z in members[index + 1:]]
+            sequence = all((z in local_later[a]) != (a in local_later[z]) for a, z in pairs) and all(a not in local_later[a] for a in members)
+            alternatives = len(members) > 1 and all(z not in local_later[a] and a not in local_later[z] for a, z in pairs)
+            kind = "unread" if not usable or capped else "sequence" if sequence else "branchAlternatives" if alternatives else "unread"
+            order = sorted(members, key=lambda a: sum(a in local_later[z] for z in members if z != a)) if kind == "sequence" else None
+            # Equal single-edge guards do not make every member run: a later call may be reached around an
+            # earlier one (two branches to it, a jump table) or be skipped after it. Each call must dominate
+            # the next and the next must follow it on every route within the visit.
+            if order and not all(dominates(a, z) and must_follow(a, z, guard_sites) for a, z in zip(order, order[1:])):
+                kind, order = "unread", None
+            groups.append({"kind": kind, "sites": members, "order": order,
+                           "sharedGuards": shared_guards,
+                           "scope": "one visit past the shared guard edges" if guard_sites else "caller CFG",
+                           "mayRepeatAcrossGuardVisits": any(a in later[a] for a in members)})
+        if capped or not usable:
+            # A cycle found in a partial read still may repeat; finding none there proves nothing.
+            for group in groups:
+                group["mayRepeatAcrossGuardVisits"] = group["mayRepeatAcrossGuardVisits"] or None
+        if capped:
+            for group in groups:
+                group.update(kind="unread", order=None, sharedGuards=[])
+            for row in rows:
+                row["necessaryGuards"] = []
+        relations = []
+        for index, first in enumerate(selected):
+            for second in selected[index + 1:]:
+                forward, backward = second in later[first], first in later[second]
+                kind = ("unread" if not usable or capped or forward and backward else
+                        "sequence" if forward or backward else "branchAlternatives")
+                relations.append({"sites": [first, second], "kind": kind,
+                                  "order": [first, second] if kind == "sequence" and forward else [second, first] if kind == "sequence" else None})
+        if relations and all(r["kind"] == "branchAlternatives" for r in relations):
+            common = [g for g in rows[0]["necessaryGuards"] if all(any(g["site"] == h["site"] and g["taken"] == h["taken"] for h in row["necessaryGuards"]) for row in rows)]
+            groups = [{"kind": "branchAlternatives", "sites": selected, "order": None, "sharedGuards": common,
+                       "scope": "caller CFG", "mayRepeatAcrossGuardVisits": any(a in later[a] for a in selected)}]
+        reports.append({"entry": entry, "ranges": b["intervals"], "boundaryUsable": usable, "orderingUsable": usable and not capped,
+                        "gaps": b["gaps"], "conflicts": conflicts.get(entry, []), "analysisCapped": capped, "analysisSteps": spent,
+                        "calls": rows, "groups": groups, "relations": relations, "assumptions": b["assumedContinuations"]})
+    controls = config.get("orderControls", [])
+    if not isinstance(controls, list) or len(controls) > 256:
+        raise ValueError("Invalid call order controls")
+    for control in controls:
+        if not isinstance(control, dict) or control.get("kind") not in ("sequence", "branchAlternatives") or not isinstance(control.get("sites"), list) or not control["sites"] or len(control["sites"]) > 256 or any(type(at) is not int for at in control["sites"]) or type(control.get("entry")) is not int:
+            raise ValueError("Invalid call order control")
+        report = next((r for r in reports if r["entry"] == control.get("entry")), None)
+        # Sequence sites are compared in order; branch alternatives have none.
+        expected = control["sites"] if control["kind"] == "sequence" else sorted(control["sites"])
+        group = next((g for g in report["groups"] if g["kind"] == control["kind"] and (g["order"] if g["kind"] == "sequence" else sorted(g["sites"])) == expected), None) if report else None
+        if group is None:
+            raise ValueError("Call order positive control missed")
+    return {"incoming": flat, "callers": reports, "uncheckedEntries": unchecked, "orderControls": controls,
+            "unownedSites": sorted(at for at in sites if not owners[at]),
+            "interpretation": "Order and guards describe a conditional caller CFG. Cleanup follows an assumed return; callees' effects, successful return and state restoration remain unresolved."}
+
+
 def _body_report(b):
     return {k: v for k, v in b.items() if k != "instructions"} | {"instructionCount": len(b["instructions"])}
 
@@ -1158,6 +1355,8 @@ def _run_report(image, config, command):
         return owner(image, config)
     if command == "callees":
         return callees(image, config)
+    if command == "call-order":
+        return call_order(image, config)
     if command == "incoming":
         return incoming(image, config)
     if command == "operand-candidates":
@@ -1180,6 +1379,8 @@ def _run_report(image, config, command):
         report = near_pointer_provenance(report, config)
     if command == "allocation":
         return allocations(report, config)
+    if command == "returns":
+        report = return_flows(report, config)
     if command != "trace":
         kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "call-return", "return", "branch", "string-operation",
                              "flag-assumption", "flag-write", "flags-save", "flags-restore", "local-iret"),
@@ -1187,7 +1388,9 @@ def _run_report(image, config, command):
                  "guards": ("compare", "branch", "read", "write", "call", "call-return"),
                  "memory": ("read", "write", "address-formation")}[command]
         for path in report["paths"]:
-            path["events"] = [e for e in path["events"] if e["kind"] in kinds or
+            # Returns keep the transfers, conversions and reads that depend on a declared result.
+            consumed = {c["order"] for f in path.get("returnFlows", {}).get("results", ()) for c in f["consumers"]}
+            path["events"] = [e for e in path["events"] if e["kind"] in kinds or e["order"] in consumed or
                               (command == "effects" and e["kind"] == "read" and (e.get("nearPointerAccessCandidates") or e.get("nearPointerArgumentCandidates")))]
     return report
 

scientific_method_engine-0.3.0/src/scientific_method_engine/x86/result_flow.py

@@ -0,0 +1,131 @@
+"""Declared result roles and bounded producer dependencies across caller continuations."""
+from .image import integer
+from .machine import ALIASES, BRANCH_CONDITIONS
+from .values import result_marker
+
+
+def validate_contracts(config, image):
+    contracts = config.get("returnContracts", [])
+    if not isinstance(contracts, list) or len(contracts) > 256:
+        raise ValueError("At most 256 return contracts")
+    keys = set()
+    for c in contracts:
+        if not isinstance(c, dict):
+            raise ValueError("Return contract must be an object")
+        entry = integer(c.get("entry"), 0, len(image.data) - 1, "return contract entry")
+        register = c.get("register")
+        if not isinstance(register, str) or register not in ALIASES or not isinstance(c.get("evidence"), str) or not c["evidence"].strip():
+            raise ValueError("Return contract requires register and evidence")
+        if (entry, register) in keys:
+            raise ValueError("Return contract entry/register must be unique")
+        keys.add((entry, register))
+        bits = ALIASES[register][2]
+        failures = c.get("failures", [])
+        if not isinstance(failures, list) or len(failures) > 256 or any(type(n) is not int or not 0 <= n < 1 << bits for n in failures):
+            raise ValueError("Failure encodings must fit the consumed return width")
+        encodings = c.get("encodings", [])
+        if not isinstance(encodings, list) or len(encodings) > 256:
+            raise ValueError("At most 256 result encodings")
+        for encoding in encodings:
+            if not isinstance(encoding, dict) or type(encoding.get("value")) is not int or not 0 <= encoding["value"] < 1 << bits:
+                raise ValueError("Result encoding must fit the declared return width")
+            if not all(isinstance(encoding.get(k), str) and encoding[k].strip() for k in ("role", "evidence")):
+                raise ValueError("Result encoding requires role and evidence")
+    return contracts
+
+
+def result_contracts(state, contracts, entry):
+    rows = []
+    for c in contracts:
+        if c["entry"] != entry:
+            continue
+        register = c["register"]
+        # Tag the declared value with a marker unique to the return event about to be
+        # recorded. The instruction site would also tag the SP the return pops, every
+        # register a call model clobbers and every later execution of the same return.
+        # A producer dependency is still weaker than unchanged value identity.
+        state.setreg(register, state.reg(register), result_marker(len(state.events)))
+        value = state.reg(register)
+        rows.append({"entry": entry, "register": register, "value": value.report(),
+                     "failureEncodings": c.get("failures", []), "encodings": c.get("encodings", []),
+                     "matchesFailureEncoding": None if value.number is None else value.number in c.get("failures", []),
+                     "matchingRoles": None if value.number is None else [e for e in c.get("encodings", []) if e["value"] == value.number],
+                     "evidence": c["evidence"], "encodingsExhaustive": False, "successEstablished": False})
+    return rows
+
+
+# Sign and overflow tests read the operand as a signed value; carry tests as unsigned.
+DOMAINS = {"l": "signed", "le": "signed", "s": "signed", "o": "signed", "c": "unsigned", "be": "unsigned"}
+
+
+VALUE_FIELDS = ("sourceValue", "resultValue", "destinationContainerValue", "result", "value", "left", "right", "carry", "count")
+CONSUMER_KINDS = ("value-transfer", "conversion", "read", "write", "compare", "branch", "return")
+ROW_FIELDS = ("kind", "site", "entry", "depth", "order", "operation", "source", "destination", "sourceBits", "destinationBits",
+              "destinationContainer", "conversion", "sourceRegister", "destinationRegister", "effectiveOperandBits", "decoderMnemonic",
+              "width", "segment", "offset", "effectiveSegmentRegister", "predicate", "taken", "flagProducer")
+
+
+def _event_values(event):
+    values = {k: event[k] for k in VALUE_FIELDS if isinstance(event.get(k), dict)}
+    if event["kind"] == "return":
+        values.update({"return:" + c["register"]: c["value"] for c in event.get("resultContracts", [])})
+    return values
+
+
+def return_flows(report, config):
+    limit = integer(config.get("returnFlowLimit", 128), 1, 1024, "return flow limit")
+    consumer_limit = integer(config.get("returnConsumerLimit", 256), 1, 10000, "return consumer limit")
+    analysis_limit = integer(config.get("returnFlowAnalysisLimit", 1000000), 1, 10000000, "return flow analysis limit")
+    steps, capped = 0, False
+    for path in report["paths"]:
+        events = path["events"]
+        event_values = {}
+        flows, omitted = [], 0
+        for index, event in enumerate(events):
+            if event["kind"] != "return" and not (event["kind"] == "call-return" and event.get("modeled")):
+                continue
+            for contract in event.get("resultContracts", []):
+                if len(flows) >= limit or capped:
+                    omitted += 1
+                    continue
+                consumers, dropped, scanned = [], 0, True
+                marker = event["order"]
+                for later_index in range(index + 1, len(events)):
+                    if steps >= analysis_limit:
+                        capped, scanned = True, False
+                        break
+                    steps += 1
+                    later = events[later_index]
+                    if later["kind"] not in CONSUMER_KINDS:
+                        continue
+                    if later_index not in event_values:
+                        event_values[later_index] = _event_values(later)
+                    values = event_values[later_index]
+                    dependent = {k: v for k, v in values.items() if marker in v.get("resultOrigins", ())}
+                    if not dependent:
+                        continue
+                    if len(consumers) >= consumer_limit:
+                        dropped += 1
+                        continue
+                    row = {k: later[k] for k in ROW_FIELDS if k in later}
+                    widths = {k: "narrower" if v["bits"] < contract["value"]["bits"] else
+                              "wider" if v["bits"] > contract["value"]["bits"] else "sameWidth"
+                              for k, v in dependent.items()}
+                    row.update(values=values, dependentValueFields=list(dependent), returnWidthRelationships=widths,
+                               relationship="producer dependency only; not value or storage identity")
+                    if later["kind"] == "branch":
+                        condition = BRANCH_CONDITIONS.get(later.get("predicate"), (None,))[0]
+                        row["predicateDomain"] = DOMAINS.get(condition, "flags/equality")
+                    consumers.append(row)
+                flows.append({"originOrder": event["order"], "originSite": event["site"], "calleeEntry": contract["entry"],
+                              "callSite": event.get("callSite"), "callerEntry": event.get("callerEntry"),
+                              "conditionalModel": event.get("modeled", False), "resultContract": contract,
+                              "consumers": consumers, "consumersOmitted": dropped, "consumerScanComplete": scanned,
+                              "successEstablished": False})
+        path["returnFlows"] = {"results": flows, "resultsOmitted": omitted, "resultLimit": limit,
+                               "consumerLimit": consumer_limit,
+                               "complete": not omitted and all(not f["consumersOmitted"] and f["consumerScanComplete"] for f in flows)
+                                           and path["returned"] and not report["gaps"],
+                               "interpretation": "conditional static dependency paths; encodings are declared evidence, not live occurrence; a branch never establishes initialization, accepted contents or extent"}
+    report["returnFlowAnalysis"] = {"limit": analysis_limit, "steps": steps, "capped": capped}
+    return report

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

@@ -2,23 +2,10 @@
 from copy import deepcopy
 from capstone.x86 import X86_OP_IMM, X86_OP_REG, X86_OP_MEM
 from .image import integer
-from .machine import (State, StopPath, ordinary, predicate, REGISTERS, ALIASES, string_instruction, string_count,
-                      string_effect, check_string_form)
+from .machine import (State, StopPath, ordinary, predicate, REGISTERS, ALIASES, BRANCH_CONDITIONS, string_instruction,
+                      string_count, string_effect, check_string_form)
 from .values import const, unknown, sources, op, Value
-
-# Synonymous and complementary branches on one flag producer share a single assumption.
-BRANCH_CONDITIONS = {}
-for names, condition in ((("je", "jz"), "z"), (("jb", "jc", "jnae"), "c"), (("jbe", "jna"), "be"),
-                         (("jl", "jnge"), "l"), (("jle", "jng"), "le"), (("js",), "s"),
-                         (("jo",), "o"), (("jp", "jpe"), "p")):
-    for name in names:
-        BRANCH_CONDITIONS[name] = (condition, False)
-for names, condition in ((("jne", "jnz"), "z"), (("jae", "jnb", "jnc"), "c"), (("ja", "jnbe"), "be"),
-                         (("jge", "jnl"), "l"), (("jg", "jnle"), "le"), (("jns",), "s"),
-                         (("jno",), "o"), (("jnp", "jpo"), "p")):
-    for name in names:
-        BRANCH_CONDITIONS[name] = (condition, True)
-
+from .result_flow import validate_contracts, result_contracts
 
 def call_target(image, site, ins):
     if ins.mnemonic in ("lcall", "ljmp"):
@@ -237,6 +224,7 @@ def trace(image, config):
     integer(config.get("returnBytes", image.bits // 8), 2, 4, "returnBytes")
     if config.get("returnBytes", image.bits // 8) not in ((4,) if image.flat else (2, 4)):
         raise ValueError("returnBytes must agree with the selected near/far frame model")
+    contracts = validate_contracts(config, image)
     models = config.get("callModels", [])
     if not isinstance(models, list) or len(models) > 64:
         raise ValueError("At most 64 explicit call models")
@@ -386,7 +374,7 @@ def trace(image, config):
                             created += 1
                             for r in REGISTERS:
                                 if r not in model.get("preserves", []) and r not in ("esp", "cs"):
-                                    child.regs[r] = unknown(f"modeled-call:{at}:{r}", ALIASES[r][2], at)
+                                    child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
                             child.clear_memory()
                             child.forget_flags()
                             child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
@@ -395,7 +383,8 @@ def trace(image, config):
                                 child.setreg(r, const(n, ALIASES[r][2], at), at)
                             child.conditional.append({"site": at, "evidence": model["evidence"],
                                                       "assumption": "call returns with balanced stack; memory effects unresolved"})
-                            child.event("call-return", callSite=at, registers=snapshot(child), modeled=True,
+                            child.event("call-return", callSite=at, callerEntry=state.frames[-1]["entry"],
+                                        resultContracts=result_contracts(child, contracts, target), registers=snapshot(child), modeled=True,
                                         unknownMemoryEffects=True)
                             child.at = following
                             pending.append(child)
@@ -451,21 +440,10 @@ def trace(image, config):
                     if image.flat and m == "retf":
                         raise StopPath("Far return is outside the PE32 flat model")
                     frame = state.frames[-1]
-                    roles = []
-                    for contract in config.get("returnContracts", []):
-                        if contract.get("entry") != frame["entry"]:
-                            continue
-                        register = contract.get("register")
-                        if register not in ALIASES or not contract.get("evidence"):
-                            raise ValueError("Return contract requires register and evidence")
-                        value = state.reg(register)
-                        failures = contract.get("failures", [])
-                        if not isinstance(failures, list) or len(failures) > 256 or any(type(n) is not int or not 0 <= n < 1 << value.bits for n in failures):
-                            raise ValueError("Failure encodings must fit the consumed return width")
-                        roles.append({"register": register, "value": value.report(), "failureEncodings": failures,
-                                      "matchesFailureEncoding": None if value.number is None else value.number in failures,
-                                      "evidence": contract["evidence"]})
-                    state.event("return", registers=snapshot(state), cleanupBytes=ins.operands[0].imm if ins.operands else 0, resultContracts=roles)
+                    roles = result_contracts(state, contracts, frame["entry"])
+                    state.event("return", registers=snapshot(state), cleanupBytes=ins.operands[0].imm if ins.operands else 0,
+                                resultContracts=roles, callSite=frame.get("callSite"),
+                                callerEntry=state.frames[-2]["entry"] if len(state.frames) > 1 else None)
                     # The entry frame gets the same width and balance checks as a traced call.
                     expected = 4 if m == "retf" else image.bits // 8
                     if expected != frame["returnBytes"] or state.reg(state.sp).term != frame["sp"].term:

{scientific_method_engine-0.1.0 → scientific_method_engine-0.3.0}/src/scientific_method_engine/x86/values.py

@@ -22,8 +22,26 @@ class Value:
         return self.term[1] if self.term[0] == "constant" else None
 
     def report(self):
-        return {"bits": self.bits, "expression": self.term, "value": self.number,
-                "producers": list(self.sources)}
+        row = {"bits": self.bits, "expression": self.term, "value": self.number, "producers": producers(self)}
+        origins = result_origins(self)
+        if origins:
+            row["resultOrigins"] = origins
+        return row
+
+
+def result_marker(order):
+    """A source tag naming the return event at ``order``; instruction sites are never negative."""
+    return -order - 1
+
+
+def producers(v):
+    """The instruction sites among a value's sources, without return-result markers."""
+    return [s for s in v.sources if s >= 0]
+
+
+def result_origins(v):
+    """The event orders of the declared return results a value depends on."""
+    return sorted(-s - 1 for s in v.sources if s < 0)
 
 
 def const(n, bits, site=None):

{scientific_method_engine-0.1.0 → scientific_method_engine-0.3.0}/tests/test_x86.py

@@ -62,6 +62,163 @@ def events(result, kind):
     return [e for path in result["paths"] for e in path["events"] if e["kind"] == kind]
 
 
+class ReturnFlowTests(unittest.TestCase):
+    def flow(self, code, contracts, **extra):
+        return report(code, "returns", returnContracts=contracts, **extra)
+
+    def contract(self, entry, register="ax", **extra):
+        return {"entry": entry, "register": register, "evidence": "synthetic result contract", **extra}
+
+    def test_nested_failure_word_byte_store_zero_extension_and_nonzero_gate(self):
+        c = Code().branch("e8", "wrapper").emit("0f b6 c0 85 c0").branch("74", "zero").emit("c3")
+        c.label("zero").emit("c3").label("wrapper").branch("e8", "callee").emit("a2 20 00 a0 20 00 c3")
+        c.label("callee").emit("b8 ff ff c3")
+        r = self.flow(c, [self.contract(c.labels["callee"], failures=[65535]), self.contract(c.labels["wrapper"], "al")], registers={"ds": 8192, "ss": 8192, "sp": 32768})
+        self.assertTrue(r["completeWithinModel"])
+        rows = r["paths"][0]["returnFlows"]["results"]
+        failure = next(f for f in rows if f["calleeEntry"] == c.labels["callee"])
+        self.assertTrue(failure["resultContract"]["matchesFailureEncoding"])
+        self.assertEqual(failure["callerEntry"], c.labels["wrapper"])
+        store = next(e for e in failure["consumers"] if e["kind"] == "write")
+        self.assertEqual(store["width"], 1)
+        self.assertEqual(store["values"]["value"]["value"], 255)
+        self.assertEqual(store["returnWidthRelationships"]["value"], "narrower")
+        extension = next(e for e in failure["consumers"] if e.get("conversion") == "zeroExtend")
+        self.assertEqual((extension["sourceBits"], extension["destinationBits"]), (8, 16))
+        branch = next(e for e in failure["consumers"] if e["kind"] == "branch")
+        self.assertEqual((branch["predicate"], branch["taken"], branch["values"]["left"]["value"]), ("je", False, 255))
+        self.assertFalse(failure["successEstablished"])
+
+    def test_full_word_failure_normalization(self):
+        c = Code().branch("e8", "callee").emit("83 f8 ff").branch("74", "bad").emit("b0 01 c3")
+        c.label("bad").emit("b0 00 c3").label("callee").emit("b8 ff ff c3")
+        r = self.flow(c, [self.contract(c.labels["callee"], failures=[65535]), self.contract(0, "al")])
+        f = r["paths"][0]["returnFlows"]["results"][0]
+        branch = next(e for e in f["consumers"] if e["kind"] == "branch")
+        self.assertEqual((branch["values"]["left"]["bits"], branch["taken"]), (16, True))
+        self.assertEqual(branch["values"]["right"]["value"], 65535)
+        self.assertNotIn("right", branch["dependentValueFields"])
+        self.assertEqual(r["paths"][0]["registers"]["al"]["value"], 0)
+
+    def test_signed_consumer_and_raw_field_role_remain_distinct(self):
+        c = Code().branch("e8", "callee").emit("83 f8 01").branch("7c", "reject").emit("c3")
+        c.label("reject").emit("c3").label("callee").emit("b8 00 80 c3")
+        encoding = {"value": 32768, "role": "raw field", "evidence": "synthetic field contract"}
+        r = self.flow(c, [self.contract(c.labels["callee"], failures=[65535], encodings=[encoding])])
+        f = r["paths"][0]["returnFlows"]["results"][0]
+        self.assertFalse(f["resultContract"]["matchesFailureEncoding"])
+        self.assertEqual(f["resultContract"]["matchingRoles"], [encoding])
+        branch = next(e for e in f["consumers"] if e["kind"] == "branch")
+        self.assertEqual((branch["predicateDomain"], branch["taken"]), ("signed", True))
+
+    def test_sign_extension_and_unrelated_equal_constant(self):
+        c = Code().branch("e8", "callee").emit("0f be d0 bb ff ff 83 fb ff c3")
+        c.label("callee").emit("b0 ff c3")
+        r = self.flow(c, [self.contract(c.labels["callee"], "al", failures=[255])])
+        consumers = r["paths"][0]["returnFlows"]["results"][0]["consumers"]
+        extension = next(e for e in consumers if e.get("conversion") == "signExtend")
+        self.assertEqual(extension["values"]["resultValue"]["value"], 65535)
+        self.assertFalse(any(e["kind"] == "compare" for e in consumers))
+
+    def test_implicit_sign_extension_retains_effective_widths(self):
+        c = Code().branch("e8", "callee").emit("98 99 c3").label("callee").emit("b0 ff c3")
+        r = self.flow(c, [self.contract(c.labels["callee"], "al", failures=[255])])
+        rows = r["paths"][0]["returnFlows"]["results"][0]["consumers"]
+        conversions = [e for e in rows if e["kind"] == "conversion"]
+        self.assertEqual([e["conversion"] for e in conversions], ["signExtend", "signFillHighHalf"])
+        self.assertEqual((conversions[0]["sourceBits"], conversions[0]["destinationBits"]), (8, 16))
+
+    def test_sibling_high_byte_zeroing_is_retained_before_word_zero_gate(self):
+        c = Code().branch("e8", "callee").emit("b4 00 09 c0").branch("75", "nonzero").emit("c3")
+        c.label("nonzero").emit("c3").label("callee").emit("b0 ff c3")
+        r = self.flow(c, [self.contract(c.labels["callee"], "al", failures=[255])])
+        rows = r["paths"][0]["returnFlows"]["results"][0]["consumers"]
+        write = next(e for e in rows if e["kind"] == "value-transfer")
+        self.assertEqual(write["destination"]["register"], "ah")
+        self.assertEqual(write["values"]["sourceValue"]["value"], 0)
+        self.assertIn("destinationContainerValue", write["dependentValueFields"])
+        branch = next(e for e in rows if e["kind"] == "branch")
+        self.assertEqual((branch["operation"], branch["predicate"], branch["taken"], branch["values"]["left"]["value"]), ("or", "jne", True, 255))
+
+    def test_models_stops_and_all_summary_caps_remain_explicit(self):
+        c = Code().branch("e8", "callee").emit("a2 20 00 85 c0").branch("74", "end").emit("90")
+        c.label("end").emit("c3").label("callee").emit("b8 ff ff c3")
+        contracts = [self.contract(c.labels["callee"], failures=[65535]), self.contract(0)]
+        for extra in ({"returnFlowLimit": 1}, {"returnConsumerLimit": 1}, {"returnFlowAnalysisLimit": 1}, {"maxSteps": 2}, {"maxDepth": 1}):
+            r = self.flow(c, contracts, **extra)
+            self.assertFalse(r["paths"][0]["returnFlows"]["complete"])
+        r = self.flow(c, contracts, callModels=[{"site": 0, "evidence": "synthetic conditional case", "cases": [{"registers": {"ax": 65535}}]}])
+        f = r["paths"][0]["returnFlows"]["results"][0]
+        self.assertTrue(f["conditionalModel"])
+        self.assertTrue(r["paths"][0]["conditionalModels"])
+
+    def test_values_sharing_only_the_return_or_call_site_are_not_dependent(self):
+        # The return pops SP at its own site; a call model clobbers BX at the call site.
+        c = Code().branch("e8", "callee").emit("89 e5 39 e9 89 d9 c3").label("callee").emit("b8 ff ff c3")
+        contracts = [self.contract(c.labels["callee"])]
+        r = self.flow(c, contracts, registers={"ss": 8192, "sp": 32768})
+        self.assertEqual(r["paths"][0]["returnFlows"]["results"][0]["consumers"], [])
+        r = self.flow(c, contracts, callModels=[{"site": 0, "evidence": "synthetic conditional case", "cases": [{"registers": {"ax": 1}}]}])
+        f = r["paths"][0]["returnFlows"]["results"][0]
+        self.assertTrue(f["conditionalModel"])
+        self.assertEqual(f["consumers"], [])
+        self.assertNotIn(0, r["paths"][0]["registers"]["sp"].get("resultOrigins", []))
+
+    def test_each_execution_of_one_return_is_a_separate_origin(self):
+        c = Code().branch("e8", "callee").emit("89 c3").branch("e8", "callee").emit("89 c1 c3")
+        c.label("callee").emit("66 b8 ff ff 00 00 c3")
+        rows = self.flow(c, [self.contract(c.labels["callee"])])["paths"][0]["returnFlows"]["results"]
+        self.assertEqual(len(rows), 2)
+        self.assertEqual([[e["site"] for e in f["consumers"]] for f in rows], [[3], [8]])
+        self.assertEqual(rows[0]["resultContract"]["value"]["resultOrigins"], [rows[0]["originOrder"]])
+        self.assertTrue(all(isinstance(p, int) and p >= 0 for p in rows[0]["resultContract"]["value"]["producers"]))
+
+    def test_sign_flag_gate_is_a_signed_predicate(self):
+        c = Code().branch("e8", "callee").emit("85 c0").branch("78", "negative").emit("c3")
+        c.label("negative").emit("c3").label("callee").emit("b8 ff ff c3")
+        rows = self.flow(c, [self.contract(c.labels["callee"], failures=[65535])])["paths"][0]["returnFlows"]["results"][0]["consumers"]
+        branch = next(e for e in rows if e["kind"] == "branch")
+        self.assertEqual((branch["predicate"], branch["predicateDomain"], branch["taken"]), ("js", "signed", True))
+
+    def test_analysis_cap_marks_the_truncated_flow(self):
+        c = Code().branch("e8", "callee").emit("a2 20 00 85 c0").branch("74", "end").emit("90")
+        c.label("end").emit("c3").label("callee").emit("b8 ff ff c3")
+        r = self.flow(c, [self.contract(c.labels["callee"], failures=[65535]), self.contract(0)], returnFlowAnalysisLimit=1)
+        flows = r["paths"][0]["returnFlows"]
+        self.assertTrue(r["returnFlowAnalysis"]["capped"])
+        self.assertFalse(flows["results"][0]["consumerScanComplete"])
+        self.assertEqual(flows["resultsOmitted"], 1)
+        self.assertFalse(flows["complete"])
+        r = self.flow(c, [self.contract(c.labels["callee"], failures=[65535]), self.contract(0)])
+        self.assertTrue(all(f["consumerScanComplete"] for f in r["paths"][0]["returnFlows"]["results"]))
+        self.assertTrue(r["paths"][0]["returnFlows"]["complete"])
+
+    def test_overwriting_the_result_register_ends_the_dependency_byte_by_byte(self):
+        # mov ax,5 replaces both result bytes; mov al,5 leaves AH, so the word compare still depends on it.
+        for overwrite, dependent in (("b8 05 00", False), ("b0 05", True)):
+            c = Code().branch("e8", "callee").emit(overwrite + " 83 f8 03 c3").label("callee").emit("b8 ff ff c3")
+            rows = self.flow(c, [self.contract(c.labels["callee"], failures=[65535])])["paths"][0]["returnFlows"]["results"][0]["consumers"]
+            self.assertEqual(any(e["kind"] == "compare" for e in rows), dependent)
+        r = report("b8 01 00 b0 02 c3")
+        self.assertEqual(r["paths"][0]["registers"]["ah"]["producers"], [0])
+        self.assertEqual(r["paths"][0]["registers"]["ax"]["producers"], [0, 3])
+
+    def test_value_transfers_are_recorded_only_for_declared_results(self):
+        c = Code().branch("e8", "callee").emit("89 c3 89 d1 8b 16 20 00 c3").label("callee").emit("b8 ff ff c3")
+        self.assertEqual(events(report(c), "value-transfer"), [])
+        r = self.flow(c, [self.contract(c.labels["callee"])], registers={"ds": 8192})
+        consumers = r["paths"][0]["returnFlows"]["results"][0]["consumers"]
+        self.assertEqual([e["site"] for e in consumers if e["kind"] == "value-transfer"], [3])
+        # Transfers and reads that do not depend on the result stay out of the returns events.
+        self.assertEqual([e["site"] for e in r["paths"][0]["events"] if e["kind"] in ("value-transfer", "read")], [3])
+
+    def test_invalid_unreachable_contracts_are_rejected(self):
+        for bad in (self.contract(0, failures=[65536]), self.contract(0, encodings=[{"value": 1, "role": "failure"}]),
+                    self.contract(0, "fpu"), self.contract(0, ["ax"]), self.contract(0, evidence="")):
+            with self.assertRaises(ValueError):
+                self.flow(Code().emit("eb fe c3"), [bad], maxSteps=1)
+
+
 class CalleeGraphTests(unittest.TestCase):
     def graph(self, code, names, **extra):
         data = code.bytes()
@@ -349,6 +506,137 @@ class NearPointerSegmentTests(unittest.TestCase):
         self.assertTrue(all(p["dereferenceSegmentRegister"] == "es" and p["segmentRelationship"] == "sameWithinModel" for p in links))
 
 
+class CallOrderTests(unittest.TestCase):
+    def run_order(self, code, **extra):
+        data = code.bytes()
+        cfg = configuration(data, target=code.labels["helper"], **extra)
+        cfg["regions"][0]["entries"] = [0, code.labels["helper"]]
+        return run_report(data, cfg, "call-order"), cfg
+
+    def test_guarded_sequence_retains_shared_cmp_cleanup_and_unread_effects(self):
+        c = Code().emit("83 7e fa 05").branch("7c", "end")
+        c.label("one").branch("e8", "helper").emit("83 c4 08")
+        c.label("two").branch("e8", "helper").emit("83 c4 08")
+        c.label("end").emit("c3").label("helper").emit("c3")
+        r, cfg = self.run_order(c, controls=[c.labels["one"], c.labels["two"]], orderControls=[{"entry": 0, "kind": "sequence", "sites": [c.labels["one"], c.labels["two"]]}])
+        caller = r["callers"][0]
+        self.assertEqual(caller["groups"][0]["kind"], "sequence")
+        self.assertEqual(caller["groups"][0]["sharedGuards"][0]["comparison"]["operands"][0]["segmentRegister"], "ss")
+        self.assertTrue(all(row["cleanup"]["argumentBytes"] == 8 and row["calleeEffects"]["status"] == "unresolved" for row in caller["calls"]))
+        self.assertEqual(len(r["incoming"]["confirmed"]), 2)
+
+    def test_adjacent_comparison_is_not_claimed_when_another_edge_enters_the_branch(self):
+        c = Code().emit("85 c0").branch("74", "compare").branch("e9", "condition")
+        c.label("compare").emit("83 fb 05").label("condition").branch("7c", "end").branch("e8", "helper")
+        c.label("end").emit("c3").label("helper").emit("c3")
+        r, _ = self.run_order(c)
+        guards = r["callers"][0]["groups"][0]["sharedGuards"]
+        conditional = next(g for g in guards if g["site"] == c.labels["condition"])
+        self.assertIsNone(conditional["comparison"])
+
+    def test_sequence_order_comes_from_flow_not_ascending_addresses(self):
+        c = Code().branch("e9", "first").label("second").branch("e8", "helper").emit("c3")
+        c.label("first").branch("e8", "helper").branch("e9", "second").label("helper").emit("c3")
+        r, _ = self.run_order(c)
+        self.assertEqual(r["callers"][0]["groups"][0]["order"], [c.labels["first"], c.labels["second"]])
+
+    def test_branch_alternatives_do_not_become_a_sequence(self):
+        c = Code().emit("85 c0").branch("74", "other").branch("e8", "helper").emit("c3")
+        c.label("other").branch("e8", "helper").emit("c3").label("helper").emit("c3")
+        r, cfg = self.run_order(c)
+        self.assertEqual(r["callers"][0]["groups"][0]["kind"], "branchAlternatives")
+        cfg["orderControls"] = [{"entry": 0, "kind": "sequence", "sites": r["callers"][0]["groups"][0]["sites"]}]
+        with self.assertRaisesRegex(ValueError, "positive control"):
+            run_report(c.bytes(), cfg, "call-order")
+
+    def test_outer_loop_keeps_sequence_within_a_guard_visit_and_reports_recurrence(self):
+        c = Code().label("guard").emit("83 f8 05").branch("7c", "end")
+        c.label("one").branch("e8", "helper").label("two").branch("e8", "helper").branch("eb", "guard")
+        c.label("end").emit("c3").label("helper").emit("c3")
+        r, _ = self.run_order(c)
+        g = r["callers"][0]["groups"][0]
+        self.assertEqual(g["kind"], "sequence")
+        self.assertEqual(g["order"], [c.labels["one"], c.labels["two"]])
+        self.assertTrue(g["mayRepeatAcrossGuardVisits"])
+        self.assertEqual(g["scope"], "one visit past the shared guard edges")
+
+    def test_shared_ownership_never_verifies_order(self):
+        c = Code().emit("90").branch("e8", "helper").emit("c3").label("helper").emit("c3")
+        cfg = configuration(c.bytes(), target=c.labels["helper"])
+        cfg["regions"][0]["entries"] = [0, 1, c.labels["helper"]]
+        r = run_report(c.bytes(), cfg, "call-order")
+        self.assertTrue(r["callers"])
+        self.assertTrue(all(not caller["orderingUsable"] for caller in r["callers"]))
+        self.assertTrue(all(g["kind"] == "unread" for caller in r["callers"] for g in caller["groups"]))
+
+    def test_overlapping_entries_are_rejected_by_the_flat_boundary_inventory(self):
+        c = Code().emit("66 90").branch("e8", "helper").emit("c3").label("helper").emit("c3")
+        cfg = configuration(c.bytes(), target=c.labels["helper"])
+        cfg["regions"][0]["entries"] = [0, 1, c.labels["helper"]]
+        r = run_report(c.bytes(), cfg, "call-order")
+        self.assertFalse(r["incoming"]["confirmed"])
+        self.assertGreater(sum(r["incoming"]["counts"].values()), 0)
+        self.assertFalse(r["callers"])
+
+    def test_caps_and_recurring_calls_leave_order_unread(self):
+        c = Code().branch("e8", "helper").branch("e8", "helper").emit("c3").label("helper").emit("c3")
+        for options in ({"entryLimit": 1}, {"limit": 1}, {"instructionLimit": 1}, {"analysisLimit": 1}):
+            r, _ = self.run_order(c, **options)
+            self.assertTrue(all(g["kind"] == "unread" for caller in r["callers"] for g in caller["groups"]))
+        loop = Code().label("again").branch("e8", "helper").branch("eb", "again").label("helper").emit("c3")
+        r, _ = self.run_order(loop)
+        self.assertTrue(all(g["kind"] == "unread" for caller in r["callers"] for g in caller["groups"]))
+
+    def test_capped_analysis_does_not_deny_recurrence(self):
+        c = Code().branch("e8", "helper").emit("90 c3").label("helper").emit("c3")
+        r, _ = self.run_order(c, analysisLimit=1)
+        self.assertTrue(r["callers"][0]["analysisCapped"])
+        self.assertIsNone(r["callers"][0]["groups"][0]["mayRepeatAcrossGuardVisits"])
+
+    def test_a_call_reached_around_another_is_not_sequenced_after_it(self):
+        # Two branches reach the first call, so neither edge alone is necessary, and the JMP skips it.
+        c = Code().emit("85 c0").branch("74", "first").branch("75", "first").branch("eb", "second")
+        c.label("first").branch("e8", "helper").label("second").branch("e8", "helper").emit("c3").label("helper").emit("c3")
+        r, cfg = self.run_order(c)
+        self.assertEqual(r["callers"][0]["groups"][0]["kind"], "unread")
+        cfg["orderControls"] = [{"entry": 0, "kind": "sequence", "sites": [c.labels["first"], c.labels["second"]]}]
+        with self.assertRaisesRegex(ValueError, "positive control"):
+            run_report(c.bytes(), cfg, "call-order")
+
+    def test_a_call_that_can_be_skipped_after_another_is_not_sequenced_after_it(self):
+        c = Code().label("first").branch("e8", "helper").emit("85 c0").branch("74", "second").branch("75", "second").emit("c3")
+        c.label("second").branch("e8", "helper").emit("c3").label("helper").emit("c3")
+        r, _ = self.run_order(c)
+        self.assertEqual(r["callers"][0]["groups"][0]["kind"], "unread")
+
+    def test_alternatives_have_the_full_group_shape_and_unordered_controls(self):
+        c = Code().emit("85 c0").branch("74", "other").label("one").branch("e8", "helper").emit("c3")
+        c.label("other").branch("e8", "helper").emit("c3").label("helper").emit("c3")
+        r, _ = self.run_order(c, orderControls=[{"entry": 0, "kind": "branchAlternatives", "sites": [c.labels["other"], c.labels["one"]]}])
+        g = r["callers"][0]["groups"][0]
+        self.assertEqual(g["kind"], "branchAlternatives")
+        self.assertEqual((g["scope"], g["mayRepeatAcrossGuardVisits"]), ("caller CFG", False))
+
+    def test_count_branches_and_entry_branches_take_no_adjacent_comparison(self):
+        c = Code().emit("83 f8 05").branch("e3", "end").branch("e8", "helper").label("end").emit("c3").label("helper").emit("c3")
+        r, _ = self.run_order(c)
+        self.assertIsNone(r["callers"][0]["calls"][0]["necessaryGuards"][0]["comparison"])
+        # The CMP before the entry is its only CFG predecessor, but the entry is also entered from outside.
+        c = Code().label("compare").emit("83 f8 05").label("entry").branch("7c", "end").branch("e8", "helper").branch("eb", "compare")
+        c.label("end").emit("c3").label("helper").emit("c3")
+        data = c.bytes()
+        cfg = configuration(data, target=c.labels["helper"])
+        cfg["regions"][0]["entries"] = [c.labels["entry"], c.labels["helper"]]
+        r = run_report(data, cfg, "call-order")
+        self.assertIsNone(r["callers"][0]["calls"][0]["necessaryGuards"][0]["comparison"])
+
+    def test_a_negative_stack_adjustment_is_not_cleanup(self):
+        c = Code().branch("e8", "helper").emit("81 c4 00 80 c3").label("helper").emit("c3")
+        r, _ = self.run_order(c)
+        self.assertEqual(r["callers"][0]["calls"][0]["cleanup"]["status"], "unread cleanup")
+        self.assertIsNone(r["callers"][0]["calls"][0]["cleanup"]["argumentBytes"])
+
+
 class ReporterTests(unittest.TestCase):
     def test_register_parts_preserve_neighbor(self):
         r = report("b8 34 12 b0 00 c3")