fix(biochem): support Solr 9 nested stoichiometry children

[VibhavSetlur]

Summary

Solr 9 moved reaction stoichiometry from a single string field on the parent document to one nested child document per participant (doc_type:stoichiometry). This broke the UI in two ways, both fixed here:

1. Reaction quick-search returned HTTP 400 on the new index. RXN_SEARCH_FIELDS still contained stoichiometry, which no longer exists as a queryable parent field → undefined field stoichiometry.
2. Reaction detail never fetched participants. The [child] transformer was scoped to doc_type:thermodynamics only, so the nested stoichiometry children were silently dropped.

Two query paths also lacked a parent-document filter, so child documents could leak into results on the nested index.

Changes (lib/api/biochem.ts)

• New StoichiometryParticipant interface and a pure normalizeStoichiometry() that handles both schemas: nested children (ordered by _nest_path_, with participant_charge / participant_formula carried through) and the legacy coefficient:compound:compartment:0:"name" parent string. It never throws — malformed or missing input yields [].
• serializeStoichiometry() re-emits the legacy string format, so Reaction.stoichiometry keeps its existing shape and every current consumer is unaffected. participants?: StoichiometryParticipant[] is added alongside it.
• getReactionById() widens the nested child transformer to [child childFilter="doc_type:thermodynamics OR doc_type:stoichiometry" limit=200]. Thermodynamics children and atom-mapping fields are unchanged.
• RXN_SEARCH_FIELDS_NESTED drops stoichiometry on the nested schema only. A caller-supplied searchFields still wins.
• getCompoundsByIdsWithFields() adds fq=doc_type:compound; findReactionsForCompound() adds fq=doc_type:reaction and, on the nested schema, uses a block join {!parent which="doc_type:reaction"}doc_type:stoichiometry AND compound:<id> (guarded by an id regex, falling back to the legacy equation:*<id>* wildcard otherwise).

Schema selection reuses the existing hasNestedSchema() probe. On the legacy index every emitted URL is byte-identical to before — asserted directly in the tests.

Verification

CI mirror, all exit 0: npm run lint · npx tsc --noEmit · npm run test:run (354 passed, 4 skipped) · npm run build · npm audit --omit=dev --audit-level=high (0 vulnerabilities) · git diff --check.

New tests/unit/api/biochemStoichiometry.test.ts (7 tests) covers nested normalization with scrambled _nest_path_ order and mixed value types, legacy parse + round-trip, malformed/garbage input, the nested detail fl/fq and preserved thermo + atom-mapping fields, byte-identical legacy URLs, and the parent filters / block join.

Checked live against the new index (reactions_staging) through the exported functions:

check	result
getReactionById('rxn00001').participants	4 participants, correct order and signs (-1 cpd00001 H2O, -1 cpd00012 PPi, +2 cpd00009 Phosphate, +1 cpd00067 H+)
thermodynamics	4 records preserved (Group contribution, dGPredictor, dGPredictor-ModelSEED, eQuilibrator)
atom mapping	has_atom_mapping: true, atom_mapping_confidence: clean
quick search atp	2096 hits (was HTTP 400); 500-doc sample is 100% doc_type:reaction, zero child ids
findReactionsForCompound('cpd00002')	4702 hits, all parents — exactly matches the legacy wildcard count

Notes

• Patch release 3.4.1 — fix-only, no API or UI surface change.
• Participant metadata is normalized at the API boundary but no new UI is added; exposing charge/formula in the reaction view is left for a follow-up.