Milab 6496 binding profiling impl

.changeset/agreement-as-a-percentage.md

@@ -0,0 +1,13 @@
+---
+'@platforma-open/milaboratories.feature-integration.ui': minor
+---
+
+The agreement limit is a percentage, and the form's sections are named for what they hold.
+
+"Share of voting cells that must agree (0–1)" becomes "Voting cells that must agree (%)". A share is a number a reader has to translate, and this one has a floor most readers do not expect: agreement is measured among the cells that answered and the verdict takes the majority, so it can never fall to half or below. The field now runs from 51 to 100 and says why. The data keeps the 0–1 share, so `--min-agreement` and every stored project are unchanged.
+
+Its tooltip now leads with the default, which is **off**: no agreement test runs, a narrow majority stands, and the verdict reports how narrow it was.
+
+The tag-barcode FASTQ dataset is marked required, which `args()` has always enforced. The single-cell V(D)J dataset moves up beside it, so the two dataset inputs sit together above the panel.
+
+Three sections are renamed: a new **Panel Settings** header over the panel file and its columns, **Baseline (background) level** becomes **Baseline (Background) Parameters**, and **The reading** becomes **Threshold Parameters**.

.changeset/each-baseline-brings-its-own-rule.md

@@ -0,0 +1,18 @@
+---
+'@platforma-open/milaboratories.feature-integration.model': major
+'@platforma-open/milaboratories.feature-integration.ui': minor
+'@platforma-open/milaboratories.feature-integration.workflow': major
+'@platforma-open/milaboratories.feature-integration.per-cell-metrics': major
+---
+
+The tag-distribution baseline brings its own rule, and it is the one its method was published with.
+
+`what-plays-the-baseline` fixes that rule: on the raw counts, drop the counts above the 99th percentile, fit a two-component negative binomial mixture, label the higher-median component the signal one, and give each cell the probability that its count belongs to it. A cell reads bound at 0.9 or above. `count-becomes-a-state` is explicit that the score and cutoff of the declared rung do not apply — each baseline brings its own rule, a run selects one baseline, so exactly one rule calls the state.
+
+**This changes every verdict on a distribution-rung run.** The rung previously fitted a kernel density over log2 counts, split it at the deepest trough, took the median of the background as a comparator count, and then handed that count to the declared rung's score. The published method it followed never defines that number, and no run was reading the rule the rung was validated with.
+
+The separation test goes with it, and that is also the spec's instruction rather than an omission. The old fit rejected a tag whose two components did not stand far enough apart, on a threshold this block invented. `what-plays-the-baseline` refuses exactly that: the method assumes two components exist, a tag that bound nothing will be split anyway and its upper slice called signal, no published test replaces the eye, and "a test invented here would be this corpus doing the thing it refuses everywhere else". So the run shows the fit instead of judging it. **A tag nothing bound can now report bound cells.**
+
+`Maximum dip height` is removed from the settings, along with `--distribution-separation`, because a mixture has no trough to measure. The 300-cell condition stays.
+
+`referenceCount` is now null on every distribution-rung row. That rung's comparator is a fitted distribution rather than a reading, and a number there would read as a comparator that served.

.changeset/settings-named-from-the-glossary.md

@@ -0,0 +1,13 @@
+---
+'@platforma-open/milaboratories.feature-integration.ui': minor
+---
+
+Every setting is named from the spec glossary, and the form is grouped by what a setting decides.
+
+Seven labels change. "Admissibility gate (baseline UMIs)" and "Min UMIs per barcode" say **unique counts**, which is the glossary's word for a count of distinct molecules. "Minimum cell agreement" becomes "Share of voting cells that must agree", since the glossary's term is a **vote**. "Bound cutoff" becomes "Score at which a cell reads bound", naming the **score** it acts on. "Panel columns that define an identity" becomes "Panel columns that group tags into identities", naming the **grouping**. "High baseline reading" becomes "Line where a baseline reading counts as high", which says it is a line rather than a reading. "Cells needed to fit a tag's own distribution" becomes "Cells a sample needs for this baseline", dropping the method jargon.
+
+Four moves. The sample column joins the other panel-column pickers at the top, where it belongs: it is a panel input, and it was sitting below the baseline among the reading settings. The baseline's own cell condition moves up beside the baseline choice, because it is a condition on that choice. "Optional settings" becomes **The reading** and takes the agreement share, which was alone behind an "Advanced reading settings" accordion that now goes. The "Baseline thresholds" accordion goes too: the gate and the high-reading line both read a cell's own baseline reading, so both exist only under a declared tag, and they now sit in the baseline section with the rung they belong to. A header for two fields that vanish with the rung above them was a section the reader met empty more often than not.
+
+Both of those fields were gated on "not the fitted rung", which also showed them before any baseline was chosen. They are now gated on the declared rung itself.
+
+Three tooltips follow the same words, and the sticky-cell one now says what sticky means and that counting such cells is a measurement while setting them aside is the gate's job.

.changeset/the-minimum-never-reaches-the-baseline.md

@@ -0,0 +1,14 @@
+---
+'@platforma-open/milaboratories.feature-integration.model': major
+'@platforma-open/milaboratories.feature-integration.ui': minor
+'@platforma-open/milaboratories.feature-integration.workflow': minor
+'@platforma-open/milaboratories.feature-integration.per-cell-metrics': minor
+---
+
+The minimum count never reaches the baseline tag, and the setting that could make it is gone.
+
+`minimum-count-before-any-reference` states it as a rule rather than a preference: the minimum asks whether a count is evidence of binding, a tag declared to be bound by nothing is never evidence of binding, so the question does not arise for it. A cell's reference reading enters the comparison as it came back, and a small one is the measurement rather than noise to be cleared away.
+
+"Apply the minimum count to the baseline tag" is removed, along with `--minimum-applies-to-baseline` and the `minimumAppliesToBaseline` field. The exemption is now unconditional in `apply_floor`.
+
+**No verdict changes.** The setting was off by default and every rung already built its comparator from raw counts, so the default behaviour is what shipped. What changes is that the other behaviour can no longer be selected. A stored project that had switched it on now runs with the exemption in force, and reports fewer removed readings and fewer emptied cells than it did.

.changeset/the-quality-layer-reads-three-statuses.md

@@ -0,0 +1,41 @@
+---
+'@platforma-open/milaboratories.feature-integration.model': minor
+'@platforma-open/milaboratories.feature-integration.workflow': minor
+'@platforma-open/milaboratories.feature-integration.per-cell-metrics': minor
+---
+
+The quality layer reads three statuses, and the reagent table reads the frame each figure is about.
+
+A measurement is now **OK**, **warn** or **alert** and nothing else. One with no line behind it carries no status, and which of the two cases it is reads from the value: a number means nothing judges it, a reason in place of a number means nothing computed it. The row is there either way, and the coverage triple beside it still separates the two.
+
+**Warn is new.** Every inherited line arrives with a warn threshold and an error threshold, and the block held one number per measurement, so each pair was collapsed and a calibrated distinction discarded. Reads per cell at 4,000 read *alerting* and now warns, since one published number gives one boundary. The panel-assigned fraction at 0.49 read *alerting* and now warns, since only a wholly failed sample alerts.
+
+The two thresholds of a line are read independently, because the field warns on a direction and puts error at total failure for three of its four lines.
+
+**The reagent table's figures now come from the right side of the minimum.** Cells with any count and the median count per cell are read from the raw counts, cells called bound from the post-minimum states. The median was taken over bound cells alone, where it could only ever print a number above the cutoff's floor, so a half-degraded reagent showed a healthy figure. Every declared tag keeps a row, so a dead reagent reads as a zero rather than as an absence, and reference tags keep a row whose bound count is empty rather than zero.
+
+**Two measurements changed hands.** The panel-assigned fraction was filed against the *usable antigen reads* row and satisfies the *undeclared barcodes* row: its complement is that quantity exactly, and the line transfers with it. Its status no longer reaches its sample's rollup, because a reagent belongs to the run rather than to any one sample.
+
+**One measurement is new.** The fraction of reads whose cell barcode the chemistry could have produced, warning below 0.75 and alerting below 0.50. The refine-tags report already carried the step it reads. It is the one inherited line with a gradient at both ends rather than a catastrophe, and the reason a third status level exists.
+
+The per-sample quality frame gains a **Valid cell-barcode fraction** column.
+
+**The fitted background now leaves the function that fits it.** Under a population baseline the block fits a two-component mixture per tag and per sample, and kept only the failures. The background component's mean, its share of cells, and the signal mean beside it now reach the measurement set as one tag-level row: the median over the panel's samples that fitted, with the spread and the unfitted count in its detail. It is what a scientist reads to see whether a tag's counts separated at all, and it depends on no cutoff — which matters, because it is read in order to settle one.
+
+Under a declared baseline nothing is fitted, and every row says that rather than going missing.
+
+**The run's scores now have a spread.** The score is computed for every cell and identity, used for one comparison against the cutoff, and was then dropped. It reaches the measurement set as deciles: one figure for the whole run, because the cutoff is one number for the run. A scientist may move that cutoff to where their own run's scores separate, and that licence is unusable unless the scores are in front of them — until now it was set blind.
+
+The measurement carries no line, since a line here would be the block placing the cutoff instead. A population baseline yields a probability rather than a score, and under it the row says so rather than printing a number from the wrong rule. The measurement set gains a **run** grain, which is a grain of one.
+
+**The sticky measurement takes two forms, and the gate decides which.** The block carried two thresholds on a cell's reference reading: the admissibility gate, which sets a cell aside, and a separate observation line defaulted to 100, which counted cells as sticky. Only one exists in the spec. `060-parameter-set` lists seven parameters and a sticky line is not among them, and `290-reference-two-roles` is explicit that *how many are high* needs a high, and only a declared gate supplies one.
+
+So **Sticky cell threshold** is gone from the settings, along with its parameter and its `--high-reference-line` flag. With a gate declared, the cells counted high are the cells it set aside — one number, both jobs. With no gate declared, which is the default, there is no *high* to count and the measurement is the **spread of the reference readings** instead. That spread is what a scientist reads in order to place a gate, and until now a first run offered a count against a line nobody had chosen.
+
+A stored project carrying the old value keeps running; the field is simply no longer read.
+
+**Run quality is visible again, and it draws the three distributions.** The tab was hidden while the quality layer was being re-cut. It returns with the measurement table, the panel-versus-reads check, and a new Distributions section holding the three plots `330-the-quality-readout` asks for: the spread of the run's scores, the reference reading across cells, and the fitted background for each tag.
+
+The deciles and the fitted parameters go out as plottable frames rather than only as detail strings on a measurement row, because a number encoded in a string is one nobody can draw. Both decile sets are taken over the whole run: the cutoff is one number for the run and so is the gate, so each plot shows every cell its number will act on. The backgrounds are emitted at the fit's own `(sample, tag)` grain, since aggregating to the tag would hide a reagent that separated in one sample and not another.
+
+Each plot says so where it cannot exist: a run read against a population baseline has no scores to spread, and one read against a declared baseline tag fits no background.

.changeset/the-sample-report-is-the-measurement-set.md

@@ -0,0 +1,22 @@
+---
+'@platforma-open/milaboratories.feature-integration.model': minor
+'@platforma-open/milaboratories.feature-integration.workflow': minor
+'@platforma-open/milaboratories.feature-integration.per-cell-metrics': minor
+'@platforma-open/milaboratories.feature-integration.ui': minor
+---
+
+A sample's report is its own measurement set, and the Quality tag is that set's rollup.
+
+The Quality Checks tab listed **three** hand-written checks against a threshold the UI held itself, while the software computed **nine** sample-level measurements with their own statuses and their own line provenance. A reader opened a sample, met three rows and a green badge, and concluded the sample had been checked. Six measurements were omitted without saying so, and a list that silently drops what it could not check reads exactly like a list that checked everything and found nothing wrong.
+
+**The tab now lists every sample-level measurement the software declares**, in declaration order, including the ones nothing computed. Each row carries its status where a line stands behind it, its value, and — where there is no value — the reason in place of one. A measurement with no line carries no status and shows an em-dash: there is no fourth status word, and which of the two no-status cases applies is read from the value.
+
+**A blank and a zero are opposite findings, so nothing is ever blank.** Every valueless row states why: the aggregate-barcode fraction because nothing in this block detects aggregates, the sticky measurement because no cell of the sample carries a comparator reading, the read-level fractions because the refine-tags report supplied no step with input reads. The reasons travel in `result_qc.csv` too, on a `reason` column that previously carried only the deferred ones.
+
+**The sample's rolled-up status sits at the top of the list, with its coverage beside it** — how many measurements were judged, how many were computed with no line to judge them against, and how many nothing computed. Whether something is wrong and whether anybody looked are different questions and are answered separately.
+
+**The Main grid's Quality tag is that same rollup and is computed nowhere else.** The UI no longer holds a QC threshold of its own: `PANEL_ASSIGNED_LINE`, `qcChecks`, `qualityStatus` and `QcCheck` are gone, and with them the second copy of a line that could drift from the software's. The tag and the report beside it cannot disagree about one sample.
+
+A measurement whose finding belongs to a reagent rather than to the sample keeps its own status on its row and stays out of the sample's rollup, and its row says so — otherwise a reader meets a status on the page that the tag does not carry.
+
+The verdict step emits `result_qc_by_sample.json` alongside `result_qc.csv`, and the model reads it as `sampleQcReport`. The frame remains the artefact every other reader takes; the report is the same measurements keyed by sample, for a view that holds one sample at a time.

.github/workflows/build.yaml

@@ -24,7 +24,7 @@ jobs:
     with:
       app-name: 'Block: Feature Integration'
       app-name-slug: 'block-feature-integration'
-      node-version: '20.x'
+      node-version: '22.x'
       gha-runner-label: hz-ubuntu-dind
       build-script-name: 'build:dev-local'
       build-before-publish-script-name: 'build:release'

.github/workflows/mark-stable.yaml

@@ -15,7 +15,7 @@ jobs:
     uses: milaboratory/github-ci/.github/workflows/block-mark-stable.yaml@v4
     with:
       app-name: 'Block: Feature Integration - Mark Stable'
-      node-version: '20.x'
+      node-version: '22.x'
       npmrc-config: |
         {
           "registries": {

.github/workflows/python-tests.yaml

@@ -51,7 +51,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
-        with: { node-version: '20.x', cache: 'pnpm' }
+        with: { node-version: '22.x', cache: 'pnpm' }
       - run: pnpm install --frozen-lockfile
       - uses: astral-sh/setup-uv@v5
         with: { version: "${{ env.UV_VERSION }}" }

.gitignore

@@ -29,7 +29,15 @@ software/test-data/manual/**
 !software/test-data/manual/**/
 !software/test-data/manual/**/*.py
 !software/test-data/manual/**/*.md
+# ...except these dev design/calibration notes — kept on disk, not version-controlled.
+software/test-data/manual/design-and-schemas.md
+software/test-data/manual/real-data-calibration.md
 !software/test-data/manual/assets/whitelist_cells.txt
+# Generated runs are ignored WHATEVER their extension. The `*.md` exception above exists for the
+# hand-written docs beside the generators, and a generated run carries its own RUN.md report — which
+# describes the panel that drove it, and that panel may be a real one supplied from outside the repo.
+# Nothing a generator writes is recipe, so nothing under runs/ is tracked.
+software/test-data/manual/runs/**
 
 # Local working docs / scratch — not version-controlled
 docs/superpowers/

block/package.json

@@ -48,7 +48,7 @@
       "support": "mailto:support@milaboratories.com",
       "description": "Assign antigens to single cells from BEAM / LIBRA-seq style feature-barcode reads",
       "longDescription": "file:../docs/description.md",
-      "changelog": "file:../CHANGELOG.md",
+      "changelog": "file:./CHANGELOG.md",
       "tags": [
         "single-cell",
         "vdj",

block/src/agents-extra.ts

@@ -3,6 +3,6 @@
 // surface should expose.
 //
 // In the future this file will host JS functions the MCP runtime
-// can execute. The `.d.ts` declarations stay visible to the agent;
-// the JS bodies execute in the MCP code-execution context (the
-// agent sees the types but not the implementation).
+// can execute. The `.d.ts` declarations stay visible to the agent.
+// The JS bodies execute in the MCP code-execution context, so the
+// agent sees the types but not the implementation.

model/package.json

@@ -22,6 +22,7 @@
     "check": "ts-builder check --target block-model"
   },
   "dependencies": {
+    "@milaboratories/graph-maker": "catalog:",
     "@milaboratories/helpers": "catalog:",
     "@platforma-sdk/model": "catalog:"
   },