flowbook-python 0.1.0__tar.gz → 0.1.2__tar.gz

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/FORMAL_DEVELOPMENT.md

@@ -219,6 +219,25 @@ S →^{Edit(i, c)} S'
 S · (T, R, W) ⇒^{Edit(i, c)} S' · (T[i := STALE], R, W)
 ```
 
+**Meaningful-edit refinement (implementation).** The instrumentation classifies an
+edit by comparing the new source against a per-cell **AST fingerprint** Fᵢ captured
+on the last [Inst-Run]. Let `fp(c)` be the canonical AST of the edited source `c`
+(IPython input transform → `ast.parse` → `ast.dump`; `⊥` if unparseable):
+
+```
+            = T[i := STALE]   if fp(c) ≠ Fᵢ  or  fp(c) = ⊥   (meaningful / invalid)
+T'          = clear CODE_CHANGED at i        if fp(c) = Fᵢ   (cosmetic / reverted)
+```
+
+`fp` discards comments, blank lines, indentation, and source positions, so
+whitespace- and comment-only edits leave `T` unchanged. When `fp(c) = Fᵢ` the edit
+is semantically a no-op (or a round-trip back to the last-run source), so the
+`CODE_CHANGED` reason is cleared — the cell returns to CLEAN unless it is stale for
+another reason (e.g. `FORWARD_STALE`). Fingerprints are stored in
+`NotebookState.fingerprints`; `fp` is computed by `FlowbookKernel._source_fingerprint`
+(it owns source/transformer access); the clear path is
+`ReproducibilityEnforcer.clear_code_changed` → `NotebookState.clear_pre_execution_reasons`.
+
 **[Inst-Run]**
 
 ```
@@ -401,13 +420,13 @@ Validity predicates are implemented inline within `check()`, following the [Inst
 
 The `check()` method implements [Inst-Run] exactly, with formal citations in comments:
 
-| main.tex          | FORMAL_DEVELOPMENT.md | Code                                                          |
-| ----------------- | --------------------- | ------------------------------------------------------------- |
-| Inst-Edit         | §3.4 [Inst-Edit]      | `mark_cell_edited()` in `kernel/reproducibility_enforcer.py`  |
-| Inst-Run          | §3.4 [Inst-Run]       | `check()` in `kernel/reproducibility_enforcer.py`             |
-| Inst-Insert       | §3.5 [Inst-Insert]    | `set_cell_order()` detecting new cells                        |
-| Inst-Delete       | §3.5 [Inst-Delete]    | `_handle_deletions()` in `kernel/reproducibility_enforcer.py` |
-| Inst-Move-Down/Up | §3.5 [Inst-Move-*]    | `_handle_moves()` in `kernel/reproducibility_enforcer.py`     |
+| main.tex          | FORMAL_DEVELOPMENT.md | Code                                                                                                                                                                                                                                                     |
+| ----------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Inst-Edit         | §3.4 [Inst-Edit]      | `mark_cell_edited()` (meaningful) / `clear_code_changed()` (cosmetic/revert) in `kernel/reproducibility_enforcer.py`; classified by `_process_cell_edit()` + `_source_fingerprint()` in `kernel/flowbook_kernel.py` against `NotebookState.fingerprints` |
+| Inst-Run          | §3.4 [Inst-Run]       | `check()` in `kernel/reproducibility_enforcer.py`                                                                                                                                                                                                        |
+| Inst-Insert       | §3.5 [Inst-Insert]    | `set_cell_order()` detecting new cells                                                                                                                                                                                                                   |
+| Inst-Delete       | §3.5 [Inst-Delete]    | `_handle_deletions()` in `kernel/reproducibility_enforcer.py`                                                                                                                                                                                            |
+| Inst-Move-Down/Up | §3.5 [Inst-Move-*]    | `_handle_moves()` in `kernel/reproducibility_enforcer.py`                                                                                                                                                                                                |
 
 **[Inst-Run] Implementation Structure:**
 

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowbook-python
-Version: 0.1.0
+Version: 0.1.2
 Summary: Reproducibility enforcement for Jupyter notebooks: a JupyterLab extension that enforces rerun consistency by tracking variable- and column-level dependencies between cells.
 Project-URL: Homepage, https://github.com/stephenfreund/FlowBook
 Project-URL: Bug Tracker, https://github.com/stephenfreund/FlowBook/issues
@@ -97,7 +97,7 @@ Description-Content-Type: text/markdown
 **Reproducibility enforcement for Jupyter notebooks.**
 
 FlowBook is a JupyterLab extension that enforces _rerun consistency_:
-re-executing each cell from the current state would produce a result
+re-executing any cell from the current state would produce a result
 consistent with a top-to-bottom execution of the notebook,
 regardless of which cells have been run, modified, and rerun.
 Cells whose inputs may have changed are marked _stale_,
@@ -108,6 +108,9 @@ When every cell is _clean_ — executed and rerun consistent —
 the notebook is guaranteed reproducible: running it top-to-bottom from
 an empty store yields exactly the outputs currently recorded.
 
+For technical details and a complete evaluation, see our arXiv paper: [FlowBook: Enforcing Reproducibility in Computational Notebooks
+](https://arxiv.org/abs/2605.01560).
+
 ## Quick Start
 
 Install FlowBook using `pip`:

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/README.md

@@ -10,7 +10,7 @@
 **Reproducibility enforcement for Jupyter notebooks.**
 
 FlowBook is a JupyterLab extension that enforces _rerun consistency_:
-re-executing each cell from the current state would produce a result
+re-executing any cell from the current state would produce a result
 consistent with a top-to-bottom execution of the notebook,
 regardless of which cells have been run, modified, and rerun.
 Cells whose inputs may have changed are marked _stale_,
@@ -21,6 +21,9 @@ When every cell is _clean_ — executed and rerun consistent —
 the notebook is guaranteed reproducible: running it top-to-bottom from
 an empty store yields exactly the outputs currently recorded.
 
+For technical details and a complete evaluation, see our arXiv paper: [FlowBook: Enforcing Reproducibility in Computational Notebooks
+](https://arxiv.org/abs/2605.01560).
+
 ## Quick Start
 
 Install FlowBook using `pip`:

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/flowbook/_version.py

@@ -1,4 +1,4 @@
 # This file is auto-generated by Hatchling. As such, do not:
 #   - modify
 #   - track in version control e.g. be sure to add to .gitignore
-__version__ = VERSION = '0.1.0'
+__version__ = VERSION = '0.1.2'

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/flowbook/kernel/flowbook_kernel.py

@@ -342,6 +342,7 @@ See checkpoint.py sections 13-14 for implementation details.
 ================================================================================
 """
 
+import ast
 import os
 import re
 import time
@@ -525,7 +526,7 @@ class FlowbookKernel(BaseFlowbookKernel, Magics):
         if msg_type == "notebook_structure":
             self._process_structure_update(msg["cell_order"])
         elif msg_type == "cell_edited":
-            self._process_cell_edit(msg["cell_id"])
+            self._process_cell_edit(msg["cell_id"], msg.get("source"))
         elif msg_type == "continue_after_violation":
             self._set_continue_after_violation(msg["enabled"])
         elif msg_type == "sync":
@@ -579,26 +580,94 @@ class FlowbookKernel(BaseFlowbookKernel, Magics):
                 log(f"[structure_update] ERROR: {e}")
                 log(f"[structure_update] Traceback: {traceback.format_exc()}")
 
-    def _process_cell_edit(self, cell_id: str) -> None:
-        """Process a cell_edited command. Marks the cell stale ([Inst-Edit])."""
+    def _source_fingerprint(self, source: str) -> Optional[str]:
+        """Canonical AST fingerprint of a cell's source ([Inst-Edit]).
+
+        Runs the source through IPython's input transformer so magics/`!`
+        commands become valid Python, then returns ``ast.dump`` of the parsed
+        tree. This is insensitive to comments, blank lines, indentation, and
+        source positions, so cosmetic edits produce an identical fingerprint.
+        Returns None when the (possibly partial) source cannot be parsed.
+        """
+        try:
+            transformed = self.shell.input_transformer_manager.transform_cell(source)
+            return ast.dump(ast.parse(transformed))
+        except (SyntaxError, ValueError):
+            return None
+
+    def _send_cell_edit_metadata(self, cell_id: str, stale_cells: list, icon: str, text: str) -> None:
+        """Emit metadata + status reflecting a cell's post-edit staleness."""
+        staleness_reasons = self._enforcer._notebook_state.get_all_reasons()
+        metadata = ReproducibilityMetadata(
+            cell_id=cell_id,
+            execution_seq=self._enforcer.seq_counter,
+            read_locs=[],
+            write_locs=[],
+            changed_locs=[],
+            stale_cells=stale_cells,
+            cell_order=self._enforcer.cell_order,
+            staleness_reasons=staleness_reasons,
+        )
+        self._send_flowbook_message(build_metadata_message(metadata))
+        self._send_flowbook_message(build_status_message(icon, text, cell_id=cell_id))
+
+    def _process_cell_edit(self, cell_id: str, source: Optional[str] = None) -> None:
+        """Process a cell_edited command ([Inst-Edit]).
+
+        Compares the edited source's AST fingerprint against the one captured when
+        the cell last executed. If they match, the edit is cosmetic
+        (whitespace/comments) or a round-trip back to the last-run source, so
+        CODE_CHANGED is cleared (the cell returns to clean unless stale for another
+        reason). Otherwise — including unparseable or sourceless edits — the cell is
+        marked stale, preserving the conservative legacy behavior.
+        """
         if not cell_id:
             return
-        stale_cells = self._enforcer.mark_cell_edited(cell_id)
-        if cell_id in stale_cells:
-            staleness_reasons = self._enforcer._notebook_state.get_all_reasons()
-            metadata = ReproducibilityMetadata(
-                cell_id=cell_id,
-                execution_seq=self._enforcer.seq_counter,
-                read_locs=[],
-                write_locs=[],
-                changed_locs=[],
-                stale_cells=stale_cells,
-                cell_order=self._enforcer.cell_order,
-                staleness_reasons=staleness_reasons,
+
+        new_fp = self._source_fingerprint(source) if source is not None else None
+        old_fp = self._enforcer.get_fingerprint(cell_id)
+
+        def _fp_repr(fp: Optional[str]) -> str:
+            if fp is None:
+                return "None"
+            return f"<{len(fp)}c #{hash(fp) & 0xffffffff:08x}>"
+
+        log(
+            f"[Inst-Edit] cell={cell_id} source_present={source is not None} "
+            f"new_fp={_fp_repr(new_fp)} old_fp={_fp_repr(old_fp)} "
+            f"match={new_fp is not None and old_fp is not None and new_fp == old_fp}"
+        )
+
+        if new_fp is not None and old_fp is not None and new_fp == old_fp:
+            # Source semantically matches the last execution — not stale due to code.
+            stale_before = set(self._enforcer.get_stale_cells())
+            stale_cells = self._enforcer.clear_code_changed(cell_id)
+            changed = set(stale_cells) != stale_before
+            log(
+                f"[Inst-Edit] cell={cell_id} DECISION=cosmetic/revert -> clear_code_changed "
+                f"(status_changed={changed}, stale_now={stale_cells})"
             )
-            self._send_flowbook_message(build_metadata_message(metadata))
-            self._send_flowbook_message(
-                build_status_message("✏️", "Cell edited, marked stale", cell_id=cell_id)
+            if changed:
+                self._send_cell_edit_metadata(
+                    cell_id, stale_cells, "↩️", "Edit reverted to last run, cleared"
+                )
+            return
+
+        if source is not None and new_fp is None:
+            reason = "unparseable"
+        elif source is None:
+            reason = "no-source"
+        else:
+            reason = "ast-differs"
+        stale_cells = self._enforcer.mark_cell_edited(cell_id)
+        marked = cell_id in stale_cells
+        log(
+            f"[Inst-Edit] cell={cell_id} DECISION=meaningful ({reason}) -> mark_cell_edited "
+            f"(marked_stale={marked}, stale_now={stale_cells})"
+        )
+        if marked:
+            self._send_cell_edit_metadata(
+                cell_id, stale_cells, "✏️", "Cell edited, marked stale"
             )
 
     def _set_continue_after_violation(self, enabled: bool) -> None:
@@ -1263,6 +1332,10 @@ class FlowbookKernel(BaseFlowbookKernel, Magics):
                 if cell_meta and "cell_order" in cell_meta:
                     self._enforcer.set_cell_order(cell_meta["cell_order"])
 
+                # Capture the raw source (before magic stripping) for the [Inst-Edit]
+                # fingerprint, so it matches the source the frontend/MCP send on edit.
+                original_code = code
+
                 # Check for notebook_structure magic (parse and remove if present)
                 code = self._process_structure_magic(code)
 
@@ -1470,6 +1543,17 @@ class FlowbookKernel(BaseFlowbookKernel, Magics):
                                 error(f"Reproducibility truncation: {err.message}")
                                 self._send_truncation_details(err.detail["truncation_details"])
 
+                    # [Inst-Edit] baseline: record the fingerprint of the source that
+                    # just committed, so future edits can be classified as meaningful
+                    # or cosmetic. Reached only on the committed path (rejected
+                    # executions return above).
+                    _baseline_fp = self._source_fingerprint(original_code)
+                    self._enforcer.set_fingerprint(self._cell_id, _baseline_fp)
+                    log(
+                        f"[Inst-Edit] cell={self._cell_id} stored baseline fingerprint "
+                        f"{'None' if _baseline_fp is None else f'<{len(_baseline_fp)}c #{hash(_baseline_fp) & 0xffffffff:08x}>'}"
+                    )
+
                     # Display results (no longer skip on violations since we don't reject)
                     skip_display = False
                     if (

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/flowbook/kernel/notebook_state.py

@@ -75,6 +75,11 @@ class NotebookState:
     execution_seq: Dict[str, int] = field(default_factory=dict)  # cell_id -> seq number
     structural_reads_values: Dict[str, Dict[str, Dict[str, str]]] = field(default_factory=dict)  # cell_id -> var -> attr -> value
     typed_changes: Dict[str, List["Change"]] = field(default_factory=dict)  # cell_id -> changes
+    # Canonical AST fingerprint of the source last executed for each cell.
+    # Used by [Inst-Edit] to decide whether a source edit is meaningful: an edit
+    # whose fingerprint matches this baseline is treated as cosmetic (clears
+    # CODE_CHANGED) rather than marking the cell stale.
+    fingerprints: Dict[str, str] = field(default_factory=dict)  # cell_id -> AST fingerprint
 
     # =========================================================================
     # Status Access
@@ -106,6 +111,21 @@ class NotebookState:
         """Get all reasons for a cell's staleness."""
         return self.get_status(cell_id).reasons
 
+    def set_fingerprint(self, cell_id: str, fingerprint: Optional[str]) -> None:
+        """Store the AST fingerprint of the source last executed for a cell.
+
+        Passing None (unparseable source) clears any stored fingerprint, which
+        makes subsequent edits fall through to the conservative mark-stale path.
+        """
+        if fingerprint is None:
+            self.fingerprints.pop(cell_id, None)
+        else:
+            self.fingerprints[cell_id] = fingerprint
+
+    def get_fingerprint(self, cell_id: str) -> Optional[str]:
+        """Return the AST fingerprint of the source last executed for a cell."""
+        return self.fingerprints.get(cell_id)
+
     def clear_pre_execution_reasons(self, cell_id: str) -> None:
         """Clear pre-execution reasons (NEVER_EXECUTED, CODE_CHANGED) from a cell.
 
@@ -487,6 +507,7 @@ class NotebookState:
         self.execution_seq.pop(deleted_cell, None)
         self.structural_reads_values.pop(deleted_cell, None)
         self.typed_changes.pop(deleted_cell, None)
+        self.fingerprints.pop(deleted_cell, None)
         if deleted_cell in self.cell_order:
             self.cell_order.remove(deleted_cell)
 
@@ -594,6 +615,7 @@ class NotebookState:
         self.execution_seq.clear()
         self.structural_reads_values.clear()
         self.typed_changes.clear()
+        self.fingerprints.clear()
 
     # =========================================================================
     # Debug/Inspection

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/flowbook/kernel/protocol.py

@@ -113,11 +113,17 @@ def build_notebook_structure_message(cell_order: List[str]) -> dict:
     }
 
 
-def build_cell_edited_message(cell_id: str) -> dict:
-    """Build a cell_edited message."""
+def build_cell_edited_message(cell_id: str, source: Optional[str] = None) -> dict:
+    """Build a cell_edited message.
+
+    The optional source is the cell's current text; the kernel uses it to decide
+    whether the edit is meaningful (AST changed) or cosmetic (whitespace/comments).
+    Omitting it preserves the legacy always-mark-stale behavior.
+    """
     return {
         "type": CELL_EDITED,
         "cell_id": cell_id,
+        "source": source,
     }
 
 

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/flowbook/kernel/reproducibility_enforcer.py

@@ -2054,6 +2054,31 @@ class ReproducibilityEnforcer:
 
             return self.get_stale_cells()
 
+    def set_fingerprint(self, cell_id: str, fingerprint: Optional[str]) -> None:
+        """Store the AST fingerprint of the source last executed for a cell.
+
+        Used by [Inst-Edit] to distinguish meaningful edits from cosmetic ones
+        (whitespace/comments). Computed by the kernel, which owns source access.
+        """
+        self._notebook_state.set_fingerprint(cell_id, fingerprint)
+
+    def get_fingerprint(self, cell_id: str) -> Optional[str]:
+        """Return the AST fingerprint of the source last executed for a cell."""
+        return self._notebook_state.get_fingerprint(cell_id)
+
+    def clear_code_changed(self, cell_id: str) -> List[str]:
+        """Clear the CODE_CHANGED reason for a cell (symmetric [Inst-Edit]).
+
+        Called when an edit brings a cell's source back to an AST identical to
+        what it last executed. Removes the CODE_CHANGED/NEVER_EXECUTED pre-execution
+        reasons, marking the cell clean only if no other staleness reason remains
+        (e.g. FORWARD_STALE from an upstream cell is preserved).
+
+        Returns current stale cells list.
+        """
+        self._notebook_state.clear_pre_execution_reasons(cell_id)
+        return self.get_stale_cells()
+
     def get_execution_records_size(self) -> int:
         """
         Calculate approximate memory size of execution records in bytes.

flowbook_python-0.1.2/flowbook/kernel/tests/test_meaningful_edit.py

@@ -0,0 +1,243 @@
+"""
+Tests for the meaningful-edit refinement of [Inst-Edit].
+
+A source edit only marks a cell stale when it changes the cell's meaning. Edits
+that touch only whitespace, blank lines, indentation, or comments are cosmetic
+and leave the cell's status untouched; an edit that brings the source back to an
+AST identical to the last execution clears the CODE_CHANGED reason.
+
+Covers:
+- FlowbookKernel._source_fingerprint (AST canonicalization, magics, syntax errors)
+- NotebookState fingerprint storage (set/get/clear/delete)
+- ReproducibilityEnforcer.clear_code_changed (symmetric clear)
+- FlowbookKernel._process_cell_edit (end-to-end edit classification)
+"""
+
+import pytest
+
+from flowbook.kernel.flowbook_kernel import FlowbookKernel
+from flowbook.kernel.notebook_state import NotebookState
+from flowbook.kernel.models import Reason, ReasonType
+from flowbook.kernel.tests.conftest import ReproducibilityTestHelper
+
+
+def _make_kernel(enforcer=None):
+    """Build a FlowbookKernel shell with just enough wiring to test edits.
+
+    Uses __new__ to skip the heavy IPython kernel init, then attaches a real
+    IPython InteractiveShell (its input_transformer_manager makes magics
+    fingerprint correctly) and captures outgoing flowbook messages.
+    """
+    from IPython.core.interactiveshell import InteractiveShell
+
+    kernel = FlowbookKernel.__new__(FlowbookKernel)
+    kernel.shell = InteractiveShell.instance()
+
+    sent = []
+    kernel._send_flowbook_message = lambda msg: sent.append(msg)
+    kernel._sent_messages = sent
+    if enforcer is not None:
+        kernel._enforcer = enforcer
+    return kernel
+
+
+# ---------------------------------------------------------------------------
+# _source_fingerprint
+# ---------------------------------------------------------------------------
+
+
+class TestSourceFingerprint:
+    def setup_method(self):
+        self.kernel = _make_kernel()
+
+    def fp(self, src):
+        return self.kernel._source_fingerprint(src)
+
+    def test_comment_only_edit_is_equal(self):
+        assert self.fp("x = 1  # original") == self.fp("x = 1  # changed comment")
+
+    def test_added_comment_line_is_equal(self):
+        assert self.fp("x = 1") == self.fp("# leading note\nx = 1")
+
+    def test_whitespace_and_blank_lines_equal(self):
+        assert self.fp("x=1") == self.fp("x = 1   ")
+        assert self.fp("x = 1") == self.fp("\n\nx = 1\n\n")
+
+    def test_reindented_block_is_equal(self):
+        a = "def f():\n    return 1"
+        b = "def f():\n        return 1"  # different indent width, same structure
+        assert self.fp(a) == self.fp(b)
+
+    def test_string_literal_change_differs(self):
+        assert self.fp('x = "hello"') != self.fp('x = "world"')
+
+    def test_real_code_change_differs(self):
+        assert self.fp("x = 1") != self.fp("x = 2")
+        assert self.fp("x = 1") != self.fp("y = 1")
+
+    def test_underscore_numeric_literal_is_equal(self):
+        assert self.fp("x = 1000") == self.fp("x = 1_000")
+
+    def test_int_vs_float_literal_differs(self):
+        assert self.fp("x = 1") != self.fp("x = 1.0")
+
+    def test_magics_are_parseable_and_stable(self):
+        a = "%timeout 5\nx = 1  # a"
+        b = "%timeout 5\nx = 1  # b"
+        assert self.fp(a) is not None
+        assert self.fp(a) == self.fp(b)
+
+    def test_shell_command_parseable(self):
+        assert self.fp("!ls -la") is not None
+
+    def test_syntax_error_returns_none(self):
+        assert self.fp("x = ") is None
+        assert self.fp("def f(:\n    pass") is None
+
+
+# ---------------------------------------------------------------------------
+# NotebookState fingerprint storage
+# ---------------------------------------------------------------------------
+
+
+class TestNotebookStateFingerprints:
+    def test_set_and_get(self):
+        ns = NotebookState()
+        ns.set_fingerprint("a", "FP")
+        assert ns.get_fingerprint("a") == "FP"
+
+    def test_get_unknown_is_none(self):
+        ns = NotebookState()
+        assert ns.get_fingerprint("missing") is None
+
+    def test_set_none_clears(self):
+        ns = NotebookState()
+        ns.set_fingerprint("a", "FP")
+        ns.set_fingerprint("a", None)
+        assert ns.get_fingerprint("a") is None
+
+    def test_delete_pops_fingerprint(self):
+        ns = NotebookState()
+        ns.cell_order = ["a"]
+        ns.set_fingerprint("a", "FP")
+        ns.handle_delete("a")
+        assert ns.get_fingerprint("a") is None
+
+    def test_clear_drops_fingerprints(self):
+        ns = NotebookState()
+        ns.set_fingerprint("a", "FP")
+        ns.clear()
+        assert ns.get_fingerprint("a") is None
+
+
+# ---------------------------------------------------------------------------
+# Enforcer.clear_code_changed
+# ---------------------------------------------------------------------------
+
+
+class TestClearCodeChanged:
+    def test_clear_only_code_changed_goes_clean(self):
+        helper = ReproducibilityTestHelper()
+        helper.set_cell_order(["a"])
+        helper.execute_cell("a", {}, {"x": 1}, writes={"x"})
+        sdc = helper.sdc
+        sdc._notebook_state.set_stale("a", {Reason(ReasonType.CODE_CHANGED)})
+        assert "a" in sdc.get_stale_cells()
+
+        stale = sdc.clear_code_changed("a")
+        assert "a" not in stale
+        assert sdc._notebook_state.is_clean("a")
+
+    def test_clear_preserves_other_reason(self):
+        helper = ReproducibilityTestHelper()
+        helper.set_cell_order(["a"])
+        helper.execute_cell("a", {}, {"x": 1}, writes={"x"})
+        sdc = helper.sdc
+        sdc._notebook_state.set_stale(
+            "a",
+            {
+                Reason(ReasonType.CODE_CHANGED),
+                Reason(ReasonType.FORWARD_STALE, loc="x", cell_id="z"),
+            },
+        )
+
+        stale = sdc.clear_code_changed("a")
+        assert "a" in stale  # FORWARD_STALE keeps it stale
+        reasons = {r.type for r in sdc._notebook_state.get_reasons("a")}
+        assert ReasonType.CODE_CHANGED not in reasons
+        assert ReasonType.FORWARD_STALE in reasons
+
+
+# ---------------------------------------------------------------------------
+# _process_cell_edit end-to-end
+# ---------------------------------------------------------------------------
+
+
+def _setup_executed_cell(source="x = 1"):
+    """Return (kernel, enforcer) with cell 'a' executed and fingerprinted."""
+    helper = ReproducibilityTestHelper()
+    helper.set_cell_order(["a"])
+    helper.execute_cell("a", {}, {"x": 1}, writes={"x"})
+    sdc = helper.sdc
+    kernel = _make_kernel(enforcer=sdc)
+    sdc.set_fingerprint("a", kernel._source_fingerprint(source))
+    return kernel, sdc
+
+
+class TestProcessCellEdit:
+    def test_cosmetic_edit_stays_clean_no_message(self):
+        kernel, sdc = _setup_executed_cell("x = 1")
+        kernel._process_cell_edit("a", "x = 1   # just a comment")
+        assert sdc._notebook_state.is_clean("a")
+        assert kernel._sent_messages == []
+
+    def test_whitespace_edit_stays_clean(self):
+        kernel, sdc = _setup_executed_cell("x = 1")
+        kernel._process_cell_edit("a", "\n\nx=1\n")
+        assert sdc._notebook_state.is_clean("a")
+        assert kernel._sent_messages == []
+
+    def test_meaningful_edit_marks_stale_and_emits(self):
+        kernel, sdc = _setup_executed_cell("x = 1")
+        kernel._process_cell_edit("a", "x = 2")
+        assert "a" in sdc.get_stale_cells()
+        assert any(m.get("type") == "metadata" for m in kernel._sent_messages)
+
+    def test_syntax_error_marks_stale(self):
+        kernel, sdc = _setup_executed_cell("x = 1")
+        kernel._process_cell_edit("a", "x = ")
+        assert "a" in sdc.get_stale_cells()
+
+    def test_revert_to_last_run_clears_staleness(self):
+        kernel, sdc = _setup_executed_cell("x = 1")
+        # First, a meaningful edit marks it stale.
+        kernel._process_cell_edit("a", "x = 2")
+        assert "a" in sdc.get_stale_cells()
+        kernel._sent_messages.clear()
+        # Editing back to source with the last-run AST clears CODE_CHANGED.
+        kernel._process_cell_edit("a", "x = 1  # back to original")
+        assert sdc._notebook_state.is_clean("a")
+        assert any(m.get("type") == "metadata" for m in kernel._sent_messages)
+
+    def test_cosmetic_edit_preserves_other_staleness(self):
+        kernel, sdc = _setup_executed_cell("x = 1")
+        sdc._notebook_state.set_stale(
+            "a", {Reason(ReasonType.FORWARD_STALE, loc="x", cell_id="z")}
+        )
+        kernel._process_cell_edit("a", "x = 1  # comment only")
+        # Still stale for the upstream reason; no spurious status flash.
+        assert "a" in sdc.get_stale_cells()
+        reasons = {r.type for r in sdc._notebook_state.get_reasons("a")}
+        assert ReasonType.FORWARD_STALE in reasons
+        assert kernel._sent_messages == []
+
+    def test_unexecuted_cell_without_fingerprint_marks_stale(self):
+        # No record / no fingerprint -> falls through to conservative mark.
+        helper = ReproducibilityTestHelper()
+        helper.set_cell_order(["a"])
+        helper.execute_cell("a", {}, {"x": 1}, writes={"x"})
+        sdc = helper.sdc
+        kernel = _make_kernel(enforcer=sdc)
+        # No set_fingerprint -> get_fingerprint is None -> mark stale on any edit.
+        kernel._process_cell_edit("a", "x = 1  # comment")
+        assert "a" in sdc.get_stale_cells()

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/flowbook/labextension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowbook",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Reproducibility enforcement for Jupyter notebooks: a JupyterLab extension that enforces rerun consistency by tracking variable- and column-level dependencies between cells.",
   "keywords": [
     "jupyter",
@@ -139,7 +139,7 @@
     "outputDir": "flowbook/labextension",
     "schemaDir": "schema",
     "_build": {
-      "load": "static/remoteEntry.97e370ce33befeb5451b.js",
+      "load": "static/remoteEntry.9c89c62fdbe6db112e2d.js",
       "extension": "./extension",
       "style": "./style"
     }

{flowbook_python-0.1.0 → flowbook_python-0.1.2}/flowbook/labextension/schemas/flowbook/package.json.orig

@@ -1,6 +1,6 @@
 {
     "name": "flowbook",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Reproducibility enforcement for Jupyter notebooks: a JupyterLab extension that enforces rerun consistency by tracking variable- and column-level dependencies between cells.",
     "keywords": [
         "jupyter",