Skip to main content
Biology Scores are deterministic, profile-aware range-agreement heuristics. There are 18 component scores plus Biological Coherence: 13 baseline scores feed 12 domains, while five advanced scores remain outside the baseline denominator. The user workflow is in Biology Scores. This guide reflects scoring contract 2026-09-16.3. Treat the linked source as authoritative when updating definitions.

​
Ownership

​
Composition and scoring

Always call getScoreInputs(def). Reading the base definitions alone misses core-group substitutions, corrected weights, context-only markers and exclusions from optional test recommendations.
  1. Resolve canonical marker paths and the selected range. Marker category placement must not change storage identity or add an observation.
  2. Apply profile, specimen, collection and panel-route rules. Uninterpretable inputs remain visible as context with no scored weight.
  3. Score usable values against the supplied range. In-range values score 100; values outside lose points along the configured linear range-fit function. No applicable bound means no fit, not 100.
  4. Group correlated inputs by evidenceGroup. The family budget is distributed among its members, so a ratio and its source markers do not create independent extra votes.
  5. Compute the headline from usable core inputs only. refinedScore describes the broader available set internally; it must not silently replace the headline.
  6. Apply minimum anchor and recency gates. Preserve a numeric rawScore when a valid composition is blocked only by recency.
  7. Report reference-range alerts and discordant patterns independently of the average.
For a family, effective member weight is its share of the family budget. The score is the rounded weighted mean across the usable core families. Coverage is covered core requirements / total core requirements, using coreGroup to count alternatives once. Coverage is not optional-marker weight and does not numerically discount the headline score. Additional markers are described as supporting the core pattern, differing from it, measuring another dimension, or not assessable. Their absence does not reduce core coverage. Profile limitations can lower confidence independently. The generic fit function uses a half-bound buffer for one-sided ranges and an interval-width buffer for two-sided ranges, with clamping to 0–100. These are product heuristics, not calibrated probabilities. See biology-score-engine.ts for exact behavior and edge cases.

​
Important panel contracts

  • Metabolic: fasting context applies to glucose, insulin, HOMA-IR and TG/HDL. Glucose/insulin/HOMA-IR share one evidence family and must align to a draw.
  • Thyroid: TSH and FT4 are the equally weighted core. FT3 and antibodies are additional; FT3/FT4 is descriptive and reverse T3 does not score.
  • Cardiovascular: ApoB is the core anchor. Related lipid ratios and non-HDL are additional evidence, not extra core votes.
  • Inflammatory: CRP and hs-CRP are distinct assays within one alternative core requirement. GGT is additional liver/metabolic context.
  • Kidney: eGFR alternatives share a filtration requirement and weight 7; sodium and potassium each have weight 1.5. With a complete core this is 70/15/15. Electrolytes cannot establish a kidney score without an interpretable filtration route. Low muscle mass excludes affected creatinine-derived routes; urine-creatinine-normalized markers retain a context limitation.
  • Bone/mineral: ionized and total calcium share a requirement. When usable ionized calcium is present, total calcium becomes context. Total calcium without suitable same-draw albumin limits confidence.
  • Hormone/recovery: core hormone requirements follow profile sex and collection/therapy context. Progesterone is additional rather than a substitute for estradiol in the female Hormone Axis core.
  • Energy: select a complete same-draw urine lactate/pyruvate or blood lactate/pyruvate route. Do not cross specimen boundaries.
  • Gut: select stool calprotectin or the same-draw urine arabinose/HPHPA route. Zonulin and secretory IgA remain assay-specific context.
  • Nerve/muscle: CK plus B12/homocysteine evidence anchors the pattern; ordinary metabolic context alone cannot generate it.
selectCurrentCoreAlternatives() prevents an older alternative from invalidating a complete newer route. Newer unpaired specialty results can remain visible without replacing the valid pair. Genetic and sunlight context do not invent different numerical homocysteine or vitamin D targets. D-dimer remains outside point scoring. The planner excludes reverse T3, D-dimer, calcitriol, NfL and zonulin from routine optional completion suggestions.

​
Dates and presentation

Core inputs older than 180 days, a core span over 90 days, unknown dates and invalid future dates have explicit states. Supporting historical markers do not invalidate a current core panel. Panels with same-draw requirements apply their own tighter check first. Keep score, rawScore and historicalSnapshot distinct. A historical presentation must never become a current value for aggregation or AI. When no current domains exist, a separately calculated historical overview may be displayed if its breadth threshold is met. The page groups scored baseline and advanced cards separately from waiting cards. Within each scored group, attention/low-fit current results precede other current results, then historical results. The ordering is independent of AI processing and is not clinical triage. Every baseline card carries the overview membership/reason computed by the orchestrator.

​
Biological Coherence

panelTier, not the definition file, controls membership. Iron Handling and Blood Flow Context share the blood domain, with relative score weights 1.2 and 0.8 inside that domain. Average available current domain scores with these weights. Report weighted core coverage separately; do not multiply a domain’s score weight by its coverage. At least three domains and 25% overall core coverage are needed for an overview number. Missing domains reduce coverage, not the available-domain average. Shared markers mean domains are not independent confirmations of health. Lipid Membrane, Cellular Energy, Stress Hormone Context, Gut–Immune Signal and Nerve–Muscle Signal are excluded from this baseline denominator. Incomplete, older or mixed-date baseline scores have explicit exclusion labels in the contributor list.

​
Context review and AI explanations

Deterministic cards do not require an AI context review to unlock. Context review is optional, fingerprints its evidence, and returns allowlisted suggestions that require user action. Female-only flags are gated by profile sex. Explanation generation prepares context before comparing material keys. Stable fingerprints use canonical values/ranges and relevant interpretation context rather than display units, transient loading state or property order. Background and manual requests are deduplicated by profile and assessment; results must not land in another profile or replace changed evidence. Each result contains independently authored summary and text fields. The summary is complete plain text, at most 280 characters, without ellipses. The fuller Markdown uses Main signal, Context and Next check sections. Validate the response contract before saving, with a bounded repair attempt for providers that cannot enforce the JSON schema. computeBiologyScoreAssessments() prepares four standard windows × two range modes synchronously, restoring the caller’s settings. Identical evidence is deduplicated. One comparison-aware interpretation can cover these views through coveredMaterials; this is not eight separate purchases. Both mode shares the optimal interpretation key. Batch payloads are compacted and split before provider limits, so a shared pass may contain multiple calls. A single-score refresh refreshes that score. The overview refresh requests the set. Normal filter changes reuse matching records, including legacy answers where possible; they do not automatically purchase an upgrade to a combined interpretation.

​
Persistence and sync

Profile data owns biologyScoreAI and biologyScoreContextAI. Explanation records retain legacy top-level fields and up to 16 material-keyed records through bounded variants. mergeBiologyScoreAIRecords() chooses the freshest record per material and preserves comparison coverage. queueBiologyScoreWrite() serializes context and explanation writes before snapshots are taken. Save immediately through the profile persistence boundary; never add plaintext global storage for generated health text. Single-profile export/import, database backups and encrypted Sync must preserve the records and variants. Stale remote snapshots or per-row deltas must not replace a fresher compatible record.

​
Verification

Run only tests related to the changed boundary, for example:
Also select relevant Biology Scores unit or Playwright cases for core substitutions, weight attribution, assay separation, date gates, fingerprint reuse, interrupted saves, profile switches, unit changes, backup restore and mobile layout. GitHub Actions owns the exhaustive browser and combined-coverage run. Keep the user guide, AI surfaces map, prompt catalog and persistence documentation aligned with changes to the contract.