Engineering & roadmap

PB-013: Fix local-parity defects that give wrong answers

A new name. The same foundation. KratosForge is the upcoming name for Fabric Desktop by KratosBI. These guides preserve the app’s current labels and paths.

State: Proposed. Not approved for implementation. Priority: P1 (mandatory: required). Owner when approved: Master product (unassigned; recommend the Prove program).

1. PR title and ID#

Fix five local notebook behaviors that differ silently from Fabric or the app (PB-013)

2. Business problem#

The product's promise is that work developed on the PC behaves predictably when it moves to Fabric. Five behaviors break that silently; each either reports success when nothing happened or blocks a notebook for the wrong reason.

3. Current verified behavior#

  1. sidecar/fabric_desktop/fabric_run.py _FABRIC_ONLY treats notebookutils.variableLibrary as Fabric-only, but notebookutils_local.py implements variableLibrary for VL_Sources.
  2. notebook.py (around line 411): a %%sql cell with MERGE, UPDATE or DELETE prints a note and finishes with status ok, so Run all continues as if the write happened.
  3. notebookutils_local.py's docstring says Fabric-only parts "raise an error that says so", but session, lakehouse, warehouse, udf and connections are absent, giving a bare AttributeError.
  4. spark_local.py: insertInto = saveAsTable, and the writer's default mode is errorifexists, so df.write.insertInto(t) on an existing table raises; Spark's insertInto appends.
  5. schedule_service.py _run_notebook_here runs every code cell, including frozen ones; app/ui/notebook.js skips frozen cells in a run (line 543).

Items 1-5 come from code reading at b7b04cc; none is covered by a test that asserts the Fabric-matching behavior.

4. Desired behavior#

  1. variableLibrary notebooks are reported as able to run on the PC.
  2. Such cells end with a visible "skipped on this PC" state that stops Run all, with the reason.
  3. Each absent utility raises NotImplementedError with a sentence saying what to do instead.
  4. insertInto appends by default and honors overwrite=True.
  5. Scheduled runs skip frozen cells like the UI, and say how many were skipped.

5. In scope and out of scope#

In scope: the five fixes and their tests; notes in docs/notebooks.md. Out of scope: running MERGE locally (PB-015); the AST analyzer (PB-014).

6. Architecture and files#

fabric_run.py, notebook.py, notebookutils_local.py, spark_local.py, schedule_service.py, app/ui/notebook.js (display of the skipped state), tests in sidecar/tests/test_notebook.py, test_notebook_parity.py, test_schedules.py.

7. Functional requirements#

As in section 4, one requirement per defect, each with a test.

8. Nonfunctional requirements#

No change to how cells run in Fabric. Messages in plain language.

9. Dependencies#

None. PB-014 builds on fix 1.

10. Security and compatibility#

A scheduled run that used to run a frozen cell will stop running it; release notes must say so. Notebooks relying on insertInto raising will now append; release notes must say so.

11. Acceptance criteria#

  • One failing-then-passing test per defect.
  • pytest sidecar/tests and node --test app/tests/ui.test.cjs pass.
  • Release notes list the two behavior changes.

12. Unit and integration tests#

Five new tests (compute check, %%sql write status, utility messages, insertInto append, frozen in schedules).

13. Manual verification#

On Windows: run a notebook with a frozen cell from Monitor > Schedules > Run now and confirm the frozen cell was skipped.

14. Documentation#

docs/notebooks.md local limits section.

15. Rollback#

Revert the PR; no data or format change.

16. Definition of Done#

Merged, tests green, FEAT-NB-07 moves from Implemented but Unreliable after review, release notes written.

Need a hand?

Find a fix in troubleshooting, or share a reproducible issue with the community.

Get support ↗Improve this guide on GitHub ↗

Search documentation

Start typing to search all 105 guides.

Search runs in your browser esc to close