Calibration,
scoring &
tests.

{
  "module": "Compo 4.04",
  "name": "visual_mass_calibration_target_scoring_and_regression",
  "version": "1.1-corrective",
  "scope": "CALIBRATION_PROFILE_PROVIDER_TARGET_AWARE_LOCAL_MASS_SCORING_AND_TOPIC4_REGRESSION",
  "consumes": [
    "Compo4.00.VisualMassDescriptor / MassEvidenceRef / stage model",
    "Compo4.01.ShapeGeometricMassResult",
    "Compo4.02.CrossObjectContextMassResult",
    "Compo4.03.MassRelationSet / PairMassRelation / MassOrderingResult",
    "legacy owner evidence from Compo1.01 / Compo2.06 through Compo4.00 adapters",
    "MassCalibrationProfile (static config owned here)",
    "MassTarget",
    "StylePreset.massTarget?"
  ],
  "provides": [
    "MassCalibrationProfile",
    "MassCalibrationRegistry",
    "CalibratedMassValue",
    "MassTarget",
    "MassTargetComponentResult[]",
    "MassTargetScoreResult",
    "MetricResult[visualMass.system.localMassFit]",
    "Topic4RegressionCase[]",
    "Topic4RegressionSuite",
    "MassScoringInput"
  ],
  "owns_metrics": [
    "visualMass.system.absoluteBandFit",
    "visualMass.system.pairRelationFit",
    "visualMass.system.orderFit",
    "visualMass.system.shareFit",
    "visualMass.system.localMassFit",
    "visualMass.system.confidence"
  ],
  "descriptors_only": [
    "visualMass.system.targetCoverage",
    "visualMass.system.evidenceCoverage",
    "visualMass.system.calibrationCoverage",
    "visualMass.system.componentBreakdown",
    "visualMass.system.suppressionLog",
    "visualMass.system.status",
    "visualMass.system.profileVersion"
  ],
  "calibration_profile_schema": {
    "profileId": "string",
    "version": "string",
    "canonicalDomainRef": "string",
    "sourceAdapters": "map sourceKind/metricRef -> monotonic mapping spec",
    "mappingKinds": [
      "IDENTITY",
      "LINEAR_POSITIVE",
      "LOG_AFFINE_POSITIVE",
      "PIECEWISE_MONOTONIC"
    ],
    "outputDomain": "finite >=0",
    "fitDatasetRef": "optional external empirical dataset reference",
    "validityScope": "declared population/rendering/style scope",
    "confidence": "0..1",
    "provenance": "EMPIRICAL|STYLE_PRESET|INITIAL_HEURISTIC|STANDARD",
    "frozenDuringEvaluation": "true"
  },
  "calibration_policy": {
    "goal": "map heterogeneous owner mass magnitudes to one declared comparable canonical domain without stealing owner metric ownership",
    "monotonicity": "required within each source adapter unless an explicit empirical profile documents otherwise; default canonical profiles require monotonic increasing mappings",
    "nonnegative_output": "required",
    "identity_when_already_domain_matched": "preferred",
    "profile_is_configuration": "profile is not learned/refit from the scene being scored in the same pass",
    "profile_change": "invalidates/adapts 4.00 evidence then recomputes 4.02, 4.03 and 4.04",
    "lineage_preservation": "calibration changes numeric domain only; stage/derivedFrom/already-applied context lineage must be preserved",
    "profile_version_propagation": "profileId@version must propagate into 4.02 contextual mass and 4.03 relation sets"
  },
  "calibrated_mass_schema": {
    "objectRef": "string",
    "sourceMassRef": "owner-qualified source metric ref",
    "sourceKind": "POINT|LINE|SHAPE|TEXT|IMAGE|GROUP|CUSTOM",
    "sourceValue": "finite >=0",
    "calibratedValue": "finite >=0",
    "canonicalDomainRef": "profile canonicalDomainRef",
    "profileId": "string",
    "profileVersion": "string",
    "confidence": "0..1",
    "provenance": "object",
    "inputStage": "INTRINSIC|LOCAL_CONTEXTUALIZED preserved from source evidence",
    "alreadyAppliedContextRefs": "refs[] preserved through calibration",
    "alreadyAppliedChannels": "channels[] preserved through calibration",
    "sourceDerivedFrom": "refs[] preserved from owner evidence"
  },
  "mass_target_schema": {
    "targetId": "string",
    "comparisonSetRef": "string",
    "absoluteBands": "optional map objectRef -> [min,max] in canonical calibrated domain",
    "pairTargets": "optional [{aRef,bRef,logRatioRange? | order? | equivalence?}]",
    "orderTargets": "optional ordered tiers / precedence constraints",
    "shareTargets": "optional map objectRef -> [minShare,maxShare]",
    "requiredComponents": "subset ABSOLUTE_BAND|PAIR_RELATION|ORDER|SHARE",
    "optionalComponents": "same enum",
    "componentWeights": "positive finite map",
    "missingEvidencePolicy": "REQUIRE_REQUIRED|DIAGNOSTIC_IF_REQUIRED_MISSING|SCORE_WITH_COVERAGE",
    "calibrationProfileRef": "required profile id/version",
    "provenance": "STYLE_PRESET|EMPIRICAL|INITIAL_HEURISTIC"
  },
  "metric_exports": {
    "primary_vote": {
      "key": "visualMass.system.localMassFit",
      "owner": "Compo4.04",
      "scoringGroup": "VISUAL_MASS_TARGET_FIT",
      "composite": true,
      "componentOf": null,
      "dependsOn": [
        "visualMass.system.absoluteBandFit",
        "visualMass.system.pairRelationFit",
        "visualMass.system.orderFit",
        "visualMass.system.shareFit"
      ],
      "derivedFrom": [
        "Compo4.03.MassRelationSet",
        "Compo4.02.CrossObjectContextMassResult[]",
        "MassTarget"
      ],
      "independentVoteAllowed": false
    },
    "components": [
      {
        "key": "visualMass.system.absoluteBandFit",
        "componentOf": "visualMass.system.localMassFit",
        "scoringGroup": "VISUAL_MASS_TARGET_FIT",
        "independentVoteAllowed": false
      },
      {
        "key": "visualMass.system.pairRelationFit",
        "componentOf": "visualMass.system.localMassFit",
        "scoringGroup": "VISUAL_MASS_TARGET_FIT",
        "independentVoteAllowed": false
      },
      {
        "key": "visualMass.system.orderFit",
        "componentOf": "visualMass.system.localMassFit",
        "scoringGroup": "VISUAL_MASS_TARGET_FIT",
        "independentVoteAllowed": false
      },
      {
        "key": "visualMass.system.shareFit",
        "componentOf": "visualMass.system.localMassFit",
        "scoringGroup": "VISUAL_MASS_TARGET_FIT",
        "independentVoteAllowed": false
      }
    ]
  },
  "scoring_policy": {
    "explicit_target_required": true,
    "no_target": "DIAGNOSTIC_ONLY_LOCAL_SCORE_NA",
    "profile_match_required": true,
    "component_fit_domain": "0..1",
    "primary_score": "weighted mean applicable component fits",
    "components_of_primary": "diagnostic-only when primary composite is active",
    "N_A": "exclude, never zero-fill",
    "required_missing": "handled only by MassTarget.missingEvidencePolicy",
    "targetCoverage": "covered expected component families / expected component families",
    "evidenceCoverage": "covered expected target weight / total expected target weight",
    "confidence": "evidence confidence × calibration confidence × evidenceCoverage",
    "higher_fit": "means closer to explicit mass target only; not universal composition quality"
  },
  "component_fit_policy": {
    "absoluteBandFit": "1 inside target band; bounded decay outside using band-relative distance",
    "pairRelationFit": "compare 4.03 logRatio/order/equivalence descriptors to explicit target",
    "orderFit": "fraction of explicit precedence constraints satisfied, weighted if supplied",
    "shareFit": "1 inside target share interval; bounded decay outside",
    "no_implicit_target": "if a component family has no target constraints, it is N/A and excluded",
    "constraint_coverage": "each component family tracks available explicit constraints / total explicit constraints; partial family evidence lowers evidenceCoverage and may block required components"
  },
  "regression_scope": {
    "covers": [
      "Compo4.00",
      "Compo4.01",
      "Compo4.02",
      "Compo4.03",
      "Compo4.04"
    ],
    "owns_design_metrics": false,
    "baseline_policy": "expected outputs change only with explicit documented contract migration",
    "required_barriers": [
      "legacy point/line ownership retained",
      "no double contextualization",
      "4.01 occupancy namespace remains hullOccupancy",
      "4.01 canonical mass does not multiply occupancy twice",
      "4.02 missing context is not neutral zero evidence",
      "4.03 mixed domains/stages are incomparable",
      "mass order is not hierarchy",
      "mass share is not balance",
      "calibration profile frozen during evaluation",
      "no-target score is N/A",
      "no global leakage"
    ]
  },
  "hard_constraints": [
    "calibration maps source metrics but does not re-own them",
    "calibration profile is immutable during one evaluation pass",
    "scene being scored must not be used to refit its own calibration profile in the same pass",
    "profile mappings must return finite nonnegative values",
    "canonical default mappings must be monotonic increasing",
    "cross-object scoring requires matching calibration profile/domain",
    "4.04 must not reapply 4.02 context modifiers",
    "4.04 must not recompute 4.01 area/density or 4.03 relations under new aliases",
    "ratio/logRatio/share/order remain descriptors and may only affect score through explicit MassTarget",
    "components of localMassFit are diagnostic-only when the composite is active",
    "no explicit MassTarget means localMassFit=N/A",
    "missing required evidence is never injected as zero",
    "high mass is not universally good; low mass is not universally good",
    "mass fit is local Topic4 fit, not global balance/hierarchy",
    "negative space remains Topic5",
    "global balance/hierarchy/eye-flow remain future owners",
    "no beautyScore",
    "CalibratedMassValue must preserve source MassEvidenceStage and already-applied context lineage",
    "scoring input comparisonSetRef must match MassTarget.comparisonSetRef",
    "scoring input calibrationProfileRef/profile version and canonicalDomainRef must match the active profile",
    "invalid/nonpositive component weights are target errors, not silently replaced with defaults",
    "partial evidence inside a target component family must not silently drop missing object/pair/share/order constraints",
    "pair target lookup must support a reversed 4.03 pair relation by mathematically reversing its descriptors",
    "default canonical LINEAR_POSITIVE and LOG_AFFINE_POSITIVE mappings must be monotonic increasing over the declared nonnegative source domain"
  ],
  "initial_heuristics": {
    "default_outside_band_decay": {
      "value": 1.0,
      "provenance": "INITIAL_HEURISTIC"
    },
    "default_component_weight": {
      "value": 1.0,
      "provenance": "INITIAL_HEURISTIC"
    },
    "calibration_confidence_floor_for_ranking": {
      "value": 0.25,
      "provenance": "INITIAL_HEURISTIC"
    },
    "score_epsilon": {
      "value": 0.015,
      "provenance": "INITIAL_HEURISTIC"
    }
  },
  "correction_policy": {
    "foreign_mass_mutation": "FORBIDDEN",
    "absolute_mass_mismatch": "emit desired calibrated-mass direction; solver chooses owner parameter later",
    "pair_relation_mismatch": "consume 4.03 relation and emit relation correction request",
    "order_mismatch": "emit precedence correction intent only",
    "share_mismatch": "emit set-relative share correction intent only",
    "calibration_mismatch": "request explicit compatible MassCalibrationProfile; do not auto-fit from current scene",
    "balance_issue": "route to future global balance owner",
    "hierarchy_issue": "route to future hierarchy owner"
  },
  "deferred_inputs": [
    "Topic5 positive/negative space",
    "future global balance",
    "future hierarchy/focal-point owner",
    "empirical perceptual calibration datasets",
    "future Text/Image/Group source adapters"
  ],
  "recompute_when": [
    "calibration profile/version changes",
    "calibrated source mass changes",
    "4.02 contextual mass changes",
    "4.03 relation set changes",
    "MassTarget changes",
    "component weights/missing evidence policy changes"
  ],
  "finality": "TOPIC4_CALIBRATION_LOCAL_SCORING_AND_REGRESSION_ONLY",
  "mass_scoring_input_schema": {
    "comparisonSetRef": "must match MassTarget.comparisonSetRef",
    "calibrationProfileRef": "must exactly match target profileId@version",
    "canonicalDomainRef": "must match active profile canonicalDomainRef",
    "masses": "map objectRef->finite calibrated/contextual mass",
    "pairRelations": "4.03 relations from same set/profile/domain",
    "ordering": "4.03 ordering from same set/profile/domain",
    "massShares": "4.03 shares from same set/profile/domain",
    "evidenceConfidence": "0..1"
  }
}