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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scientific-method-engine
-Version: 0.2.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.2.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.2.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.2.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.2.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:
@@ -1376,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"),
@@ -1383,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.2.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.2.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.2.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()