Shape
generator,
scoring & tests.

ShapeCorrectionBranch {
  parentCandidateId,
  sourceCorrectionRequestId,
  targetOwner,
  proposalRef,
  childCandidateId,
  seedFork,
  repairDepth,
  dirtyOwners[],
  provenance: "DERIVED"
}

{
  "module": "Compo 3.06",
  "name": "shape_generator_scoring_and_tests",
  "version": "1.0-canonical",
  "scope": "BOUNDED_SHAPE_CANDIDATE_ORCHESTRATION_LOCAL_SCORING_AND_TOPIC3_REGRESSION",
  "consumes": [
    "Compo3.00.Shape / ShapeRole / ShapeGeometry contracts",
    "Compo3.01.PrimitiveValidationResult / PrimitiveToPathResult / proposal adapters",
    "Compo3.02.PathShapeGeometry / ContourIntersectionEvent[] / correction requests",
    "Compo3.03.MetricResult[shape.silhouette.localReadabilityScore]",
    "Compo3.03.SilhouetteCorrectionRequest[]",
    "Compo3.04.MetricResult[shape.region.localTopologyFit]",
    "Compo3.04.ShapeRegionCorrectionRequest[]",
    "Compo3.05.ShapeTransformDescriptor / ShapeWorldGeometryView",
    "Compo3.05.TransformCorrectionRequest[]",
    "ShapeProposalProvider[]",
    "ShapeSystemTarget",
    "Compo0.seed / lineage"
  ],
  "provides": [
    "ShapeGenerationIntent",
    "ShapeGenerationBudget",
    "ShapeProposal",
    "ShapeCandidate",
    "ShapeCandidateLineage",
    "ShapeSystemTarget",
    "ShapeSystemScoreResult",
    "ShapeSearchReport",
    "ShapeCorrectionBranch",
    "ShapeRegressionCase[]",
    "ShapeRegressionSuite"
  ],
  "owns_metrics": [
    "shapeSystem.localScore",
    "shapeSystem.localScoreConfidence"
  ],
  "descriptors_only": [
    "shapeSystem.targetCoverage",
    "shapeSystem.evidenceCoverage",
    "shapeSystem.groupBreakdown",
    "shapeSystem.suppressionLog",
    "shapeSystem.generationCost",
    "shapeSystem.correctionCost",
    "shapeSystem.localRankKey",
    "shapeSystem.stableTieBreak",
    "shapeSystem.lineage",
    "shapeSystem.searchReport"
  ],
  "candidate_schema": {
    "candidateId": "string",
    "parentCandidateId": "string|null",
    "lineageRootId": "string",
    "shapeRef": "canonical owner-produced shape snapshot/ref",
    "proposalRefs": "string[]",
    "metrics": "MetricResult[]",
    "hardViolations": "HardConstraintViolation[]",
    "generationDepth": "integer>=0",
    "repairDepth": "integer>=0",
    "generationCost": "number>=0 bookkeeping only",
    "correctionCost": "number>=0 bookkeeping only",
    "diversityKey": "string|null supplied by provider/adapter",
    "canonicalSignature": "string",
    "stableTieBreak": "string",
    "provenance": "object"
  },
  "generation_intent": {
    "intentId": "string",
    "shapeRole": "ShapeRole",
    "allowedGeometryKinds": "PRIMITIVE|PATH|COMPOUND[]",
    "allowedPrimitiveFamilies": "optional explicit list",
    "sourceShapeRefs": "optional immutable bases",
    "proposalProviderRefs": "explicit provider refs",
    "silhouetteTarget": "optional Compo3.03 target",
    "regionTarget": "optional Compo3.04 target",
    "transformVariantPolicy": "optional explicit policy; no default rotation/scale sweep",
    "hardConstraints": "typed constraints",
    "stylePresetRef": "optional",
    "seed": "required deterministic seed"
  },
  "generation_budget": {
    "maxBaseCandidates": 16,
    "maxProposalsPerBase": 12,
    "maxTotalCandidates": 64,
    "maxRepairDepth": 2,
    "maxCorrectionBranchesPerCandidate": 4,
    "maxDiversityPerBucket": 8,
    "maxRuntimeMs": "optional host budget"
  },
  "generation_policy": [
    "normalize intent and explicit provider set",
    "load immutable source/base seeds",
    "request bounded proposals from owning adapters",
    "expand without Cartesian product",
    "validate via owner results",
    "hard-filter before scoring",
    "deduplicate by canonicalSignature",
    "diversity-prune using explicit provider diversityKey",
    "request 3.03/3.04 owner metrics",
    "score locally under explicit ShapeSystemTarget",
    "materialize bounded owner-routed correction branches",
    "repeat until budget/depth/convergence stop"
  ],
  "proposal_policy": {
    "geometry_proposal_owner": "3.01/3.02/3.04 or explicit external owner",
    "transform_proposal_owner": "Core/3.05 adapter",
    "3.06_role": "orchestrates proposal refs; never directly mutates control points/primitive params/transform matrix",
    "transform_variants": "generated only when explicit TransformVariantPolicy or provider proposals exist",
    "generation_cost": "bookkeeping/tie-break only, never aesthetic score"
  },
  "target_schema": {
    "targetId": "string",
    "requiredGroups": "string[]",
    "optionalGroups": "string[]",
    "disabledGroups": "string[]",
    "silhouetteTarget": "optional Compo3.03 target",
    "regionTarget": "optional Compo3.04 target",
    "semanticMultipliers": "map group->positive finite number",
    "styleMultipliers": "map group->positive finite number",
    "groupVoteCaps": "map group->positive finite number",
    "requiredEvidencePolicy": "REQUIRE_ALL|DIAGNOSTIC_IF_MISSING|RANK_WITH_LOW_COVERAGE",
    "hardConstraints": "typed constraints",
    "stylePresetRef": "optional"
  },
  "allowed_primary_votes": {
    "shape.silhouette.localReadabilityScore": {
      "owner": "Compo3.03",
      "scoringGroup": "SILHOUETTE_READABILITY"
    },
    "shape.region.localTopologyFit": {
      "owner": "Compo3.04",
      "scoringGroup": "SHAPE_REGION_TOPOLOGY"
    }
  },
  "scoring_policy": {
    "explicit_target_required": true,
    "no_target": "DIAGNOSTIC_ONLY_LOCAL_SCORE_NULL",
    "hard_filter_before_score": true,
    "N_A": "EXCLUDE_NOT_ZERO",
    "components_of_active_composite": "SUPPRESS",
    "unknown_or_non_primary_metric": "DIAGNOSTIC_ONLY",
    "dependsOn_alone": "NEVER_SUPPRESS",
    "cross_group_direct_derivedFrom_overlap": "SUPPRESS_LOWER_PRIORITY_UNLESS_BOTH_EXPLICITLY_INDEPENDENT",
    "group_value": "weighted mean of selected canonical primary votes inside group; currently one canonical primary per group",
    "raw_group_weight": "baseWeight * semanticMultiplier * styleMultiplier",
    "group_weight": "min(raw_group_weight, groupVoteCap)",
    "effective_score_weight": "group_weight * MetricResult.confidence",
    "localScore": "weighted mean groupValue by effective_score_weight",
    "sceneConfidence": "weighted mean groupConfidence by group_weight",
    "targetCoverage": "covered expected groups / expected groups",
    "evidenceCoverage": "covered expected target weight / total expected target weight",
    "localScoreConfidence": "sceneConfidence * evidenceCoverage",
    "no_soft_aesthetic_penalty_layer": "owner fits already encode target interpretation; generation/correction cost remains non-aesthetic"
  },
  "ranking_policy": [
    "hard-feasible candidates only",
    "higher localScore outside scoreEpsilon",
    "higher targetCoverage",
    "higher localScoreConfidence outside confidenceEpsilon",
    "lower correctionCost",
    "lower generationCost",
    "stableTieBreak lexical"
  ],
  "initial_heuristics": {
    "score_epsilon": {
      "value": 0.015,
      "provenance": "INITIAL_HEURISTIC"
    },
    "confidence_epsilon": {
      "value": 0.03,
      "provenance": "INITIAL_HEURISTIC"
    },
    "default_group_vote_cap": {
      "value": 1.0,
      "provenance": "INITIAL_HEURISTIC"
    },
    "default_base_group_weight": {
      "value": 1.0,
      "provenance": "INITIAL_HEURISTIC"
    },
    "max_base_candidates": {
      "value": 16,
      "provenance": "IMPLEMENTATION_HEURISTIC"
    },
    "max_proposals_per_base": {
      "value": 12,
      "provenance": "IMPLEMENTATION_HEURISTIC"
    },
    "max_total_candidates": {
      "value": 64,
      "provenance": "IMPLEMENTATION_HEURISTIC"
    },
    "max_repair_depth": {
      "value": 2,
      "provenance": "IMPLEMENTATION_HEURISTIC"
    },
    "max_correction_branches_per_candidate": {
      "value": 4,
      "provenance": "IMPLEMENTATION_HEURISTIC"
    },
    "max_diversity_per_bucket": {
      "value": 8,
      "provenance": "IMPLEMENTATION_HEURISTIC"
    }
  },
  "hard_constraints": [
    "candidate hard violations are evaluated before local scoring",
    "candidate source snapshots are immutable; repair creates a child branch",
    "no full Cartesian product of proposal dimensions",
    "same intent+provider outputs+seed+versions produce same candidate ordering and lineage",
    "3.06 must not recalculate raw primitive/path/region/transform geometry under new metric names",
    "only canonical primary owner composites from 3.03 and 3.04 may vote in current Topic3 local score",
    "MetricResult componentOf active composite is diagnostic-only",
    "descriptor/raw complexity/area/bounds/transform magnitude cannot vote directly",
    "missing required evidence follows explicit requiredEvidencePolicy; never inject zero",
    "generationCost and correctionCost are not aesthetic scores",
    "visual mass/occupancy metrics from Topic4 are not owned or synthesized here",
    "positive/negative-space metrics from Topic5 are not owned or synthesized here",
    "global balance/hierarchy/eye-flow are not owned here",
    "no beautyScore"
  ],
  "correction_policy": {
    "foreign_mutation": "FORBIDDEN",
    "silhouette_mismatch": "consume 3.03 SilhouetteCorrectionRequest and route to 3.02/3.06 provider",
    "region_mismatch": "consume 3.04 ShapeRegionCorrectionRequest and route to 3.02/3.04 provider",
    "transform_invalid": "consume 3.05 TransformCorrectionRequest and route to Core transform owner",
    "new_branch": "immutable child candidate with parentCandidateId and deterministic seed fork",
    "max_depth": "bounded by ShapeGenerationBudget.maxRepairDepth"
  },
  "regression_scope": {
    "covers": [
      "Compo3.00",
      "Compo3.01",
      "Compo3.02",
      "Compo3.03",
      "Compo3.04",
      "Compo3.05",
      "Compo3.06"
    ],
    "owns_design_metrics": false,
    "baseline_policy": "expected outputs change only with explicit contract migration reason",
    "determinism": "same fixture/seed/version => same structural output"
  },
  "deferred_inputs": [
    "Topic4 visual mass / silhouette area / occupancy / density factor",
    "Topic5 positive and negative space",
    "Core ObjectTransform final migration",
    "global balance / hierarchy / eye-flow",
    "future global pipeline / final scene scorer",
    "style calibration datasets"
  ],
  "recompute_when": [
    "ShapeGenerationIntent or generation budget changes",
    "proposal provider version/output changes",
    "3.03/3.04 primary metric contract changes",
    "ShapeSystemTarget changes",
    "candidate hard-violation state changes",
    "owner correction creates new candidate branch",
    "Core transform version changes when candidate world evidence depends on it"
  ],
  "finality": "TOPIC3_LOCAL_SEARCH_SCORING_AND_REGRESSION_ONLY"
}