[davidackerman]

One PR for the consolidation of cellmap-flow, built the way #103 was: each item lands on its own branch and is merged here with a merge commit, and this description grows with it. The review behind it measured the repo at 130k lines (47.5k Python, 25k browser TypeScript, 11.5k dashboard JS and templates, 47k tests), found about 10.5k lines of TypeScript that repeat Python logic with about 90 places where the two copies disagree, and set three waves of work: (A) the confirmed bugs, the contract generated from the pydantic models, the constants both modes copy by hand turned into data, and the test suite cut to what protects behaviour; (B) the numeric core written once in Python and run in the browser through Pyodide, the Python joints (one way to add a model, one TrainingOptions), the 0.3.0 shims; (C) decided later. The plan and status live in consolidation_review/PLAN.md on the author's checkout.

Merged so far

Fix four confirmed bugs found in the dashboard review (fix-confirmed-bugs)

The browser ranked a sigmoid or tanh model as if its output were logits. web/src/backend/routes/rank.ts read every served model's raw output straight into the tally, where the server's twin (rank_routes._score) reads it as a probability by the model's output class, clipped, then its logit. A model whose manifest says it outputs probabilities had 0.1 read as "object": it scored half at 0 and its cut-off, which Use this model makes the seed threshold, landed between its two values. The route now converts with label-it's probability() and the served model's output_class; a logit model's score is unchanged within float32. The test fakes' served ModelInfo carries the manifest's output class, as the real one does.

A layer's URL now carries the dashboard's address and the chain's digest however its model was started. Only Submit's redraw (PUT /api/pipeline) put them in; startup, Submit's launches, Add a model, Use this model and a finetune's layer built the blob from the live steps alone. So an inference server running a merging postprocessor never posted its merged ids for such a layer (chunkmirage_ops._send_equivalences returns without a dashboard URL), and the first PUT of an unchanged chain redrew every layer because _shows() never matched. One helper, Session.layer_blob(), builds the blob from session.pipeline_spec with the address and digest, and every path uses it. The dashboard binds its port before the startup viewer's layers are built (bind_dashboard; create_and_run_app takes the bound server), so those carry the address too. The address is the dashboard's own, by IP, which a server on the cluster can reach, rather than the host the browser's request came by (a proxy's, or localhost over a tunnel); a request's host_url remains the fallback when none is bound. The layer snapshot tests pin what the layers now carry.

Export Config left a removed model in the YAML. The ✕ stopped the model and took its layer, but its config stayed among the session's models, so the exported YAML started it again with cellmap_flow yaml. remove_model now drops the config (drop_config, shared with Add a model and Use this model); a model unticked on Submit keeps its config for its row on the Models tab and the pipeline builder.

The two chunkmirage pins disagree, and are not bumped here. pyproject.toml pins 7331a3fc (3 Oct) and web/chunkmirage.lock d6fd94ae (16 Oct), 70 commits apart. A test (tests/web/test_pins.py) now asserts they agree, so they move together from now on. It is xfail(strict=True) for the moment: at d6fd94ae chunkmirage moved Cast to chunkmirage_contrib.ops (a second package in the same wheel), and serving/chunkmirage_ops.py imports it from chunkmirage.ops, so bumping pyproject would break layer_ops. Every other name cellmap-flow imports still exists there with the same signature; this was checked statically against a local chunkmirage checkout, not run against a live model server. Bumping needs the import moved to chunkmirage_contrib.ops, pyproject set to d6fd94ae, the marker removed, and the server tests run in an environment with that chunkmirage.

Generate the dashboard's contract from the pydantic models, and read a blank training field as the form's default (spec-contracts)

The dashboard's JavaScript speaks to the Flask routes in server mode and to web/src/backend in browser mode, and nothing held the two to one contract: the route lists, request shapes and shared numbers were copied by hand, and a Flask route added without a browser twin became a silent 503.

cellmap_flow/schema.py is now the one place. It exports a JSON Schema (draft 2020-12) of every request model (dashboard/requests.py, plus ResolveModel/AddModel/PipelineUpdate), the table of every route with where it is answered — both, stub, server or browser; the method and path from the app's url_map, the availability declared beside it, the two cross-checked so a new route without a declaration fails by name — and the constants both modes share (the rank score's, Undo's depth, the AI annotation's caps, the Finetune form's defaults, the chain steps' parameters). npm run gen in web/ writes web/src/generated/cellmap-flow.schema.json, cellmap-flow.ts (types by json-schema-to-typescript 16.0.0, with the constants, ROUTES and the step parameters as values) and docs/api.md; npm run gen:check diffs them. Today: 53 routes in both modes (7 of them browser stubs), 36 server-only, 5 browser-only.

tests/web/test_schema.py fails when the generated files are stale, when a Flask route is added without a declaration, when the TypeScript router registers a route the table does not give the browser or misses one it does, and when the server form's defaults leave FinetuneSubmit's; web/test/unit/generated-routes.test.ts holds the router to ROUTES; CI's web job runs the check. The browser's DEFAULT_OPTIONS and LABEL_MAX_CHARS come from the generated file, and contracts.ts re-exports the request body types.

POST /api/finetune/submit read a field sent blank as 10 epochs, a batch of 2, MSE, LoRA rank 8, class balance off and distillation left to the trainer, while the Finetune tab shows 20, 8, margin, 64, on and 0.01; the defaults are the form's now, and the browser keeps only its own (the head's learning rate and BCE, no smoothing, one tile a step) as explicit overrides. One behaviour change for API callers that omit loss_type on a sparse session: they now train margin with λ = 0.01, what the form always sent, instead of the MSE-to-margin switch with λ = 0.5.

web/ARCHITECTURE.md states the rule this serves — one implementation per behaviour: a feature works in both modes only when its logic is written once (a shared Python core, chunkmirage, the dashboard JS, or generated contracts); otherwise the other mode answers unavailable — with the table of what is both-mode, browser-only and server-only. .github/copilot-instructions.md points at it.

Turn the constants and catalogs the browser app copied by hand from Python into data generated from Python (data-registries)

web/build/export_data.py writes web/src/generated/python-data.json from cellmap_flow. The file is committed, and npm run export:data and npm run render regenerate it. The app reads it through web/src/generated/python-data.ts instead of its own copies of: the normalizer and postprocessor registry, with each op's parameter defaults and whether the browser runs it; the default chain, which was written twice (build/render.py and src/state/index.ts); the organelle catalog, the prompt's sentences, and the AI-annotate limits, stage labels and key binding; the raw and prediction shaders, the prediction colours, the colour-control pattern and the layer keys tied to a source; the ranking's constants; the finetune jobs' terminal statuses, epoch patterns and restart marker; Label it's undo depth and large-box size; the unit table.

The app reads the JSON with the type TypeScript infers from it, so a field renamed in Python fails the typecheck where it is used. tests/web/test_python_data_fresh.py fails when the file is stale, and replaces test_layer_carry.py's regex scrape of viewer/state.ts.

Fixes, because the data now has one source: the browser page offers only the steps it runs (it listed FillHoles, CellposeMasks, ChannelSelector, Dilate and EuclideanDistance, then answered 400 when one was ticked; each op's Python class now declares browser = True when the browser runs it, render.py lists only those, and a vitest test holds that set equal to the ports in web/src/infer), and the server reads μm (Greek mu) and the British spellings micrometre, nanometre, millimetre, centimetre, metre, picometre as lengths (it took them for nanometres; the browser now reads the same table).

Cut the test suite from 46.6k lines to 27.1k (cut-tests)

The tests had grown to 46,644 hand-written lines. A large share were wording and shape pins, or the same behaviour tested several times over. The rule now is one behavioural test per user-facing feature, in each mode (server and browser), at its outermost layer; parity tests check what both modes must agree on.

	before	after
Python tests (tests/)	25,632	14,660
TypeScript tests (web/test/**/*.ts)	18,530	9,950
Fixture generators (web/test/fixtures/make_*.py)	2,482	2,482 (unchanged)
Hand-written total	46,644	27,092
JSON fixtures	11,034 lines	8,447 lines
pytest	2,240 passed, 161 s serial	1,116 passed, 31 s on 8 workers
vitest	78 files, 1,567 passed	59 files, 762 passed

What went. Wording and shape pins: the CLI surface table, frozen bsub command lines, the served-metadata and chunk hashes, the RNG draw sequence, the per-platform loss tables, weight hashes and checkpoint keys, the annotation-volume byte pins, the finetune routes' table of 60 exact error strings, the blockwise task YAMLs byte for byte, the browser page's element-id lists, the prompt text, and roughly 500 assertions on error sentences in both languages; where a pin guarded real behaviour the test now checks a status code and the kind of error, a keyword, or yaml.safe_load and a few keys. Duplicates: TypeScript unit tests that hand-copied Python's numbers for ops a parity test already covers (the args codec, labels, Morton ids, norms, dtype, output), TS tests that repeated another TS file, and Python files whose behaviour another test covers. Layers: the launch command was tested at six layers, finetune submit at four and restart in about eight places; each keeps its outermost behavioural test plus the restart token and Shift+R. The Hub's training-graph snapshots (2,587 lines of JSON) are replaced by a small graph built inside the test.

What stays on purpose. Every AI-annotate secrets and egress test (key redaction, key-file mode and owner, keys in browser memory only, the destination acknowledgement, the dataset allow-list); the safe-Lambda whitelist in both modes; test_deployability whole; every parity test, fixture and generator; test_fixtures_fresh, test_io_metadata, test_url_map, test_layer_carry, finetune-rank and the Playwright specs; the real failure modes once each (OOM retry, a NaN batch, restart, resume after a dashboard restart, a server announcing its address only once it answers, the bsub-timeout job id, SIGHUP cleanup). Thirty-seven files were deleted; the branch's commits name the remaining test that covers each feature.

Also: CI runs pytest in parallel (pytest-xdist in the test extra and pixi's test feature, -n auto in both pytest steps; pixi.lock refreshed with pixi lock, adding only pytest-xdist and execnet), and docs/source/architecture.rst describes the suite as it is now instead of naming the snapshot tests as refactor guards.

Left for a follow-up: two source comments that now promise more than the tests check (finetune/losses.py's docstring; the "order, statuses and words" notes in web/src/backend/routes/ai-annotate.ts and view-labels.ts), and two functions with no caller left (tailer.trainer_outputs_from_log, PlanePlan.from_dict).

One definition of the training settings, and a trainer in parts (training-options)

cellmap_flow/finetune/options.py's TrainingOptions holds every setting a finetune trains with and its default, once: the mode (lora, full, or the browser's head, replacing "a LoRA rank of 0 means full"), rank and alpha, epochs, batch, learning rate, loss, margin, smoothing, class balance, distillation weight and scope, augmentation, mixed precision, the target type, channel and offsets, the model's output class, and the manifest's patches per epoch and rehearsal fraction. The submit and restart bodies (FinetuneSubmit, FinetuneRestart), the job's command line (every flag made from the model's fields; the old flag names are kept, so a running job still takes a restart), the run's metadata, the trainer and the browser's generated FINETUNE_DEFAULTS are all read from it, where seven layers each listed the settings with defaults that had drifted. TrainingOptions.for_session is what submit adjusts for a painted session or a distance or flow target; a restart's values are checked as the form's are, and a rank change across kinds is refused up front.

The trainer reads the model's output as its server does: output_class (serving.probe's unit / signed_unit / unbounded) comes from the running model's model_info, else --output-class, else one probe in the job, replacing the trainer's own sigmoid probe (and its four cache helpers), which took a tanh's [-1, 1] for logits while ranking and seeding read it as (p + 1) / 2.

lora_trainer.py (1,516 lines) becomes finetune/trainer/: loop.py (Finetuner; LoRAFinetuner kept as its old name), supervised.py (one SupervisedLoss for the 7-way construction and 5-way dispatch), distillation.py, recovery.py (precision, OOM, finite gradients), diagnostics.py, tensorboard.py; the checkpoint files are written and read by adaptation.py's strategies, and BatchLoopWrapper/SequentialWrapper sit with the other wrappers in trainable.py. Behaviour is unchanged apart from the output-class reading; the existing finetune tests pass with import-path edits, plus one test for the single definition and one for the tanh model. Hand-run CLIs with no flags now get the form's defaults (rank 64, 20 epochs, margin, smoothing 0.1, balance on, λ 0.01); the job manager always passed them explicitly, so dashboard runs are unchanged.

One model entry, one constructor path, one launcher (model-entry)

Every description of a model is a model entry, {type, name, env, **arguments} (models/entry.py), and registry.build_model is the only place a config is built from one: a YAML's models:, cellmap_flow infer <type>'s options, the pipeline builder's model form (type; class_name deprecated for one release), the Models tab's catalog, Hugging Face, zoo and Cellpose picks, Add a model and serve --model. Values are coerced by the constructors' annotations (entry.coerce), replacing coerce_cli_args, coerce_form_params, build_model's shorthand and the constructors' own parsers, so the same entry gives the same config from the CLI, a YAML and the form; the two type tables are one lookup.

serving.launch.launch starts every server (infer, yaml, add --run, the Models tab, the Training tab's ranking): resolve_data_path(scale), the saved-settings fallback, start_hosts. This fixes the Models tab serving a config with scale at the session path. The dashboard's five run_* and four launch loops are one data-driven path over built configs; a catalog model's config now stays in the session (Export Config lists it), and a missing catalog folder is refused at Submit instead of failing on the node.

One bioimage entry builder and one voxel-size rule (the config's: given, else declared, else trained at); configs/bio and bioimage_catalog read io.metadata's unit table, so pm, cm and m models are accepted. The Models tab's JS is one module per list under dashboard/models/, each with payload() and untick(); there is no DOM harness in this environment, so a click through the Models tab in a browser is worth doing before merge.

Tests: one per new behaviour (the same entry three ways; the dashboard honours scale; the zoo accepts pm/cm/m); the launch tests patch jobs.launch.start_hosts alone. The legacy command/cellmap_flow_server paths are kept for the release that removes them.

The paint logic written once, in Python, run by the browser too (pyodide-pilot)

chunkmirage is pinned at 7307e36b for both modes (pyproject.toml and web/chunkmirage.lock), the commit that merged the one hook this needs upstream (JaneliaSciComp/chunkmirage#46: a page's own Python loaded into the engine's Pyodide workers and called by module path); Cast is imported from chunkmirage_contrib.ops, where chunkmirage moved it, and the pins test is no longer an xfail. The serving tests pass against that chunkmirage; no live model server on the cluster was run.

cellmap_flow/portable/ is the Python both modes run (standard library, numpy, scipy, pydantic, Pillow only; tests/portable/test_boundary.py enforces it): the rank score moved whole from finetune/rank.py (re-exported there) and the maths of Use this model's paint carry out of session/volume.carry_paint, which keeps the zarr reads and writes. On the way this fixed the server carrying a uint8 paint volume onto a uint16 one (numpy 2 refused the 65535 cap).

The browser bundles those files as text and runs them in chunkmirage's Pyodide worker: Inference.python is chunkmirage's Engine.call by module path. Pyodide and numpy load in the background when a dataset opens (one worker). web/src/finetune/rank.ts and carry.ts (383 lines) are deleted with their unit tests; the rank routes are tested on the same Python in node's Pyodide (pyodide@0.28.3; skipped without the network).

Measured on the built app in headless Chromium on a Linux workstation: Python ready 3.2 s after the dataset opens (3.7–4.3 s after page load; 10.2 MB over the wire, once per browser), first rank call 0.05 s, warm 0.02 s, a 32-chunk scoring loop 0.4 s. Not yet measured on a Mac.

The volume reader is worldarray (worldarray-trial, named before the trial succeeded)

worldarray 0.1.0 (PyPI, from tag v0.1.0 = 5e9d17d) is the shared tensorstore reader the architecture review asked for: placement in nm, level choice, padded and resampled reads, written once where seven of cellmap's repositories carried a diverged copy. ImageDataInterface now composes a WorldArray; pyproject.toml pins worldarray>=0.1,<1 and pixi.lock is refreshed. cellmap_flow/io/ goes from 2,201 to 1,059 lines (14 files, +499 −1,591 against the branch point, the lockfile among them) and keeps what is cellmap-flow's: the chain and channel classes, s<N> level names, path forms, the corner-floor ROI rule, ArrayMeta and its five users, io/paths, io/ome's writer. store.prepare and source.reader_context are gone. Browser app unchanged apart from the exported unit table.

Behaviour follows worldarray's spec (docs/spec.md there), and seven parity rows in tests/utils/test_io_metadata.py moved with it, each by up to half a voxel or a rounding step: COSEM translate and zarr v3 transform attributes are voxel centres (as OME translation already was); offsets are never rounded; a group's multiscales transform outranks an array's resolution; an N5 level with downsamplingFactors and no offset is placed as BigDataViewer places it (David confirmed); the nearest level on a tie is the finer; a resampling block cut short by the data's end is the mean of what it has. jrc_hela-2's N5 and OME-Zarr copies now give the same corner (checked against the real bucket). Four rounds of the trial fed worldarray's fixes (S3/GCS env, N5 string units, http ancestor probing, read overhead, pinned-axis callables); the record is consolidation_review/worldarray_trial.md in the working tree.

Full suite against the PyPI install: 1,141 passed, the one known import-hygiene failure. No live run on the cluster.

Live try on a workstation (no bsub, CPU)

cellmap_flow view on jrc_jurkat-1 with the models as local processes: mito_aff_unet_setup_16 served its layer end to end (resampled 13.76 → 16 nm read through worldarray, chunkmirage blocks, Neuroglancer). jrc_mus-livers_16nm_to_8nm_mito failed every chunk, and its warm-up, with "padded input size per channel: (1 x 1 x 1)": a bug from before this PR in the cellmap model type, which read the metadata's training input_shape (216³) while cellmap_models traces the TorchScript at inference_input_shape (288³), the only shape a traced UNet runs at. Fixed here (the inference shapes when present, with a test); the two liver models in models.yaml are the ones affected.

https://claude.ai/code/session_01EzWMS4pG3tm1ZtvKULfSfW