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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scientific-method-engine
-Version: 0.3.0
+Version: 0.4.0
 Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
 Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
 Author: kibertoad
@@ -108,3 +108,8 @@ Commands, inputs, limits and acceptance rules are in
 [the bounded evidence reporter guide](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md).
 The reader and engine check that they speak the same prepared-config protocol and refuse to run
 otherwise.
+
+The `effects` command additionally emits path-local `effectOrdering` timelines,
+pre-call write prefixes and bounded local restoration witnesses. Unknown modeled
+or nested service effects stay separate; no return code establishes rollback or
+transactionality. See [the full contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#ordered-effect-path-summaries).

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

@@ -96,3 +96,8 @@ Commands, inputs, limits and acceptance rules are in
 [the bounded evidence reporter guide](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md).
 The reader and engine check that they speak the same prepared-config protocol and refuse to run
 otherwise.
+
+The `effects` command additionally emits path-local `effectOrdering` timelines,
+pre-call write prefixes and bounded local restoration witnesses. Unknown modeled
+or nested service effects stay separate; no return code establishes rollback or
+transactionality. See [the full contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#ordered-effect-path-summaries).

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

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

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

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

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

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

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

@@ -5,6 +5,7 @@ from capstone import CS_AC_READ, CS_AC_WRITE
 from capstone.x86 import X86_OP_IMM, X86_OP_MEM, X86_OP_REG
 from .machine import State, StopPath, REGISTERS, ALIASES, segment_register
 from .values import unknown
+from .effect_order import effect_ordering
 from .result_flow import return_flows
 from .image import Image, integer
 from .trace import (trace, walk, call_target, unsupported_transfer, uncovered, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON,
@@ -1379,6 +1380,8 @@ def _run_report(image, config, command):
         report = near_pointer_provenance(report, config)
     if command == "allocation":
         return allocations(report, config)
+    if command == "effects":
+        report = effect_ordering(report)
     if command == "returns":
         report = return_flows(report, config)
     if command != "trace":

scientific_method_engine-0.4.0/tests/test_effect_order.py

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