Skip to content

Refreshing a run, plans read from a file, and .xlsx reading, firmed up - #105

Open
matthewjones372 wants to merge 4 commits into
mainfrom
claude/stoic-pascal-v0q6pz
Open

matthewjones372 wants to merge 4 commits into
mainfrom
claude/stoic-pascal-v0q6pz

Conversation

@matthewjones372

@matthewjones372 matthewjones372 commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Three of the experimental features get the protections and tests they were missing, and move to "Built" in the README. The third, .xlsx reading, was added after this PR opened, because this session pushes to one branch.

Reading a model from an .xlsx workbook: new crate watershed-xlsx

The workbook reader moves out of the spreadsheet example into a crate of its own: Workbook::open, Model::build(&book, vary, outputs), Model::check() against Excel's saved values, then Model::set, value, inputs and outputs for Scenarios. The example now uses it, down from about 1,400 lines to about 450.

  • Bugs fixed while moving it:
    • A formula reading itself through other cells recursed without end.
    • VLOOKUP with column 0 panicked (u32 underflow).
    • AND and OR passed over TRUE and FALSE in a range.
    • Text with accents was garbled, read byte by byte.
    • A chain of cells thousands long could overflow the stack. Building now runs on a thread with a large stack, and a test follows a running total 200,000 cells long.
  • Loops (circular references) are found as strongly connected components (Tarjan), and refused only when the formulas followed go round them. Damodaran's valuation workbook has loops behind a switch that is off: with a cruder check, 9 of its inputs were refused.
  • Added:
    • Functions that may depend on an input: IFERROR, LOG, LOG10, POWER, SIGN, NPV, PMT (accurate near a rate of 0), SUMPRODUCT, CHOOSE, HLOOKUP, INDEX, MATCH (1, 0 and -1).
    • Functions of fixed values only: ROUND, ROUNDUP, ROUNDDOWN, INT, MOD, COUNT, COUNTA.
    • Defined names, whole columns (B:B), sheet names with quotes in them, Excel's errors written into formulas (#N/A), and TRUE() as LibreOffice writes it.
  • Refused now, where it used to guess:
    • An approximate lookup into keys out of order (Excel's answer then depends on how it searches).
    • Text chosen by a condition that depends on an input.
    • A number one way and TRUE or FALSE the other.
  • Tests (crates/watershed-xlsx/tests):
    • functions.xlsx is written by make.py and worked out by LibreOffice. It has 82 formulas covering every function, each repeated over 24 pairs of inputs. Every value must agree with LibreOffice's to twelve figures, on the graph and as a plan.
    • A sheet of formulas that must be refused, each with its reason.
    • Small workbooks written in the test, where Excel and LibreOffice differ (LibreOffice keeps TRUE as 1), plus shared formulas and the 200,000-cell chain.
    • Mutation checks: breaking the lookups, IFERROR, CHOOSE, NPV, case-insensitive text comparison or loop finding each fails a test. Two mutations first survived; a fixture and a tighter test were added for them.
  • Tried by hand on Damodaran's fcffsimpleginzu.xlsx (not in CI):
    • Each of its 15 inputs that reach the valuation was varied in turn; every translated cell agreed with Excel's saved values.
    • With each input raised by a tenth, the valuation matched LibreOffice recalculating the real workbook, to the 15 figures it saves.
    • The example's million trials still run in about 0.5 s on 4 cores.

Refreshing a batch after a change (Kept)

  • A forgotten input no longer leaves stale values. A refresh used to use only the inputs the caller named, so leaving one out silently left the kept values it reaches stale.
    • A Kept now notes which update its values are current as of. A refresh, or a patch, brings in every built-in input that has changed since, whether named or not.
    • Kept::changed(g) lists those inputs, and Kept::caught_up(g) marks values brought up to date elsewhere by a Patch.
    • The graph gains changed_in(id), the update in which a node last changed.
  • A changed graph shape is refused, not silently mishandled. What a change can reach was worked out once, when the Kept was made. Redefining or removing a node, or a total gaining or losing members (rows added to a collection, a group membership moved), breaks that.
    • The graph gains reshaped(), a count of such changes.
    • A refresh after one is refused with PlanError::Reshaped.
  • New randomized test: 40 random graphs, each run with nodes kept (the nearest the outputs, or random ones). Then 6 rounds of changes to built-in inputs, some to the value they already had, each refreshed naming every changed input, one, or none. Every kept value must equal making and running the plan again, bit for bit.
    • With the detection removed, it fails at seed 1, round 2 (none named).
    • A refresh after a redefinition is refused; with the check removed, that test fails.
  • Examples: the loans example's refresh section still matches a full re-run to the last bit.

Plans read from a file

  • Files are now checked for consistency. A file was only checked for being whole and unchanged. A hand-written file with a correct checksum could point a load past the slots, a group at a shape that doesn't exist, or a cluster's operands past the end. That would panic on the CPU, or read the wrong memory on a GPU.
  • Scenarios::check now runs on every load. It checks:
    • every number that points somewhere against what it points into: slots, constants, shared values, operands against what each program reads, levels and groups covering the nodes in order, shared programs reading only earlier values, outputs, and the clusters' shapes, operands and slots;
    • that every program leaves one value on a stack no deeper than 32;
    • that a scenario asks for no more slots than it has inputs and nodes.
  • Failures are refused with a new LoadError::NotWhole(reason).
  • Every plan the builder makes passes. This is asserted in debug builds, and the whole watershed-gpu test suite was run in debug.
  • New tests:
    • 13 kinds of tampering, each refused.
    • 3,000 random edits to a saved plan, with and without clusters, with the checksum recomputed: each is refused or runs without failing.
    • Run once by hand at 60,000 edits, with no failure. The fuzzing caught one problem in my first version: a file could ask for 2^62 slots per scenario.

Status in the README

  • Refreshing a batch after a change: now Built.
  • Saved plans and lots across GPUs: now Built, noting that lots have run on eight GPUs in one machine but not yet on several machines.
  • Reading a model from an .xlsx workbook: now Built, pointing at the new crate.
  • Fused kernels: stay Experimental; they need measurements on a GPU.

Checks

  • cargo test --workspace passes, including the new crate's 13 tests.
  • Clippy, including --features cuda, cargo fmt and cargo doc are clean.
  • Rust 1.85 could not be installed in the session, so CI's 1.85 job is the check that the new crate builds there.

Note for watershed-jvm: the API changes are additive. A Kept used after rows are added to a collection now gets PlanError::Reshaped instead of a refresh that could miss the new rows.

GPU: the GPU tests that read plans back from files should be re-run on a CUDA machine, since loading now checks plans.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AdzBXcxXfE7iKtPMVoTTfr

"Money with decimal columns", in Solid and React: a café's bill whose
quantities and prices are decimal fields, with net = qty * price, VAT as
round(net * 0.2d, 2) and gross = net + vat, each totalled exactly. A last
column, float(gross), is the same amount as an ordinary number: its total
comes to 23.159999999999997 where the bill's is 23.16. The bar shows the
exact total (totalExact, formatted with Intl.NumberFormat, which formats the
text exactly) beside the numbers' total. Edits and an Add a cookie button
show both follow.

The notes say the no-mixing rule (0.2d, float()), total against totalExact,
the 28 digits and the rounding functions, and how decimals go into put and
putMany.

tsconfig.base.json adds ES2023.Intl to lib, for Intl.NumberFormat's format
of a numeric string; browsers have had it since 2023.

A browser test per cookbook: the bill comes to 23.16 and the numbers to
23.159999999999997; a typed quantity and an added line keep it to the cent.
All 54 browser tests pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AdzBXcxXfE7iKtPMVoTTfr
Kept (refreshing a batch after a change):
- A refresh used only the inputs the caller named: one left out left the
  kept values it reaches stale, silently. Now a Kept notes which update its
  values are as of, and a refresh (or patch) brings in every input built
  into the plan that has changed in the graph since, named or not; changed()
  lists them, and caught_up() marks values brought up to date elsewhere by a
  Patch. The graph gains changed_in(id), the update a node last changed in.
- What a change reaches was worked out once, from the graph's shape when the
  Kept was made. Once a node is redefined or removed, or a total gains or
  loses members (rows added to a collection, a group membership moved), that
  no longer holds, and a refresh could miss what changed. The graph gains
  reshaped(), a count of such changes; a Kept notes it and a refresh after
  it is refused with PlanError::Reshaped.
- Test: forty random graphs, run with nodes kept (the nearest the outputs,
  or random ones), then six rounds of changes to built-in inputs (some to
  the value they had), refreshed naming every changed input, one, or none:
  every kept value equals making and running the plan again, to the last
  bit. With the detection taken out it fails at seed 1, round 2 (none
  named); a refresh after a redefinition is refused, and with the check
  taken out that test fails.

Plans read from a file:
- A file was checked for being whole and unchanged, not for holding
  together: one written by hand with a right sum could point a load past
  the slots, a group at a shape there is not, or a cluster's operands past
  the end, and panic on the CPU or read the wrong memory on a GPU. Now
  Scenarios::check, run on every load, checks every number that points
  somewhere against what it points into (slots, constants, shared values,
  operands against what each program reads, levels and groups covering the
  nodes in order, the shared values' programs reading only earlier ones,
  outputs, and the clusters' shapes, operands and slots), that every program
  leaves one value on a stack no deeper than 32, and that a scenario asks
  for no more slots than it has inputs and nodes. A file that fails is
  refused with LoadError::NotWhole. Every plan the builder makes passes
  (asserted in debug builds; the tests ran so).
- Tests: thirteen kinds of tampering each refused; 3,000 random changes to a
  saved plan, with and without clusters, the sum made right again, each
  refused or run without failing (60,000 tried once by hand: no failure; the
  first version of the check let a file ask for 2^62 slots, which this
  found).

The README moves both from experimental to built (lots on several machines
are still not tried); the watershed-gpu README says what each now checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AdzBXcxXfE7iKtPMVoTTfr
The spreadsheet example's workbook reader moves into watershed-xlsx, with
fixes, more functions, and tests against a spreadsheet program's values.

- Fixed: a formula that reads itself through other cells recursed without
  end; VLOOKUP with column 0 panicked; AND and OR passed over TRUE and
  FALSE in a range; text with accents was garbled; a chain of cells
  thousands long could overflow the stack.
- Loops (circular references) are found as strongly connected components,
  and refused only when the formulas followed go round them.
- Added: IFERROR, LOG, LOG10, POWER, SIGN, NPV, PMT, SUMPRODUCT, CHOOSE,
  HLOOKUP, INDEX, MATCH; ROUND, ROUNDUP, ROUNDDOWN, INT, MOD, COUNT and
  COUNTA of fixed values; defined names, whole columns, quoted sheet names
  with quotes in them, Excel's errors written into formulas.
- Approximate lookups into keys out of order are refused.
- tests/workbooks/functions.xlsx: 82 formulas, each over 24 pairs of
  inputs, worked out by LibreOffice, compared on the graph and as a plan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AdzBXcxXfE7iKtPMVoTTfr
@matthewjones372 matthewjones372 changed the title Refreshing a run, and plans read from a file, firmed up Refreshing a run, plans read from a file, and .xlsx reading, firmed up Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants