Occupied
mask /
free-space.

ObjectSupportRef {
  objectRef,
  supportRef,
  coordinateSpaceRef,

  supportMode,
  visibilityRef?,
  alphaSupportRef?,
  clipRef?,

  status,
  confidence,
  provenance
}

SpaceMaskPairResult {
  domainRef,
  policyRef,

  occupiedMask,
  freeMask,

  domainAreaPx2,
  occupiedAreaPx2,
  freeAreaPx2,
  occupiedFraction,
  freeFraction,

  exactness,
  approximationErrorBoundPx2?,
  confidence,
  status,
  provenance
}

{
  "module": "Compo 5.01",
  "name": "occupied_mask_and_free_space_mask",
  "version": "1.1-corrective",
  "scope": "SCENE_DOMAIN_SUPPORT_UNION_BINARY_OCCUPIED_MASK_AND_FREE_SPACE_COMPLEMENT",
  "consumes": [
    "Compo5.00.CompositionSpaceDomain",
    "Compo5.00.SpaceMaskPolicyRef",
    "ObjectSupportRef[] from Topic3/render adapters",
    "Compo3.05 world-to-domain transform adapter?",
    "Clip/Crop domain adapter?",
    "Visibility/Occlusion adapter? when VISIBLE_PAINT_SUPPORT is requested",
    "Intrinsic alpha/support evidence from paint/render owner? according mask policy"
  ],
  "provides": [
    "SpaceMaskPolicy",
    "ObjectSupportSet",
    "ObjectSupportRef",
    "SpaceMask",
    "OccupiedMaskResult",
    "FreeSpaceMaskResult",
    "SpaceMaskPairResult",
    "MetricResult[space.mask.occupiedAreaPx2]",
    "MetricResult[space.mask.freeAreaPx2]",
    "MetricResult[space.mask.occupiedFraction]",
    "MetricResult[space.mask.freeFraction]",
    "SpaceMaskCorrectionRequest[]"
  ],
  "owns_metrics": [
    "space.mask.occupiedAreaPx2",
    "space.mask.freeAreaPx2",
    "space.mask.occupiedFraction",
    "space.mask.freeFraction",
    "space.mask.confidence"
  ],
  "descriptors_only": [
    "space.mask.domainAreaPx2",
    "space.mask.representation",
    "space.mask.measurementStage",
    "space.mask.policyRef",
    "space.mask.supportSetHash",
    "space.mask.objectCount",
    "space.mask.exactness",
    "space.mask.approximationErrorBoundPx2",
    "space.mask.status"
  ],
  "space_mask_policy_schema": {
    "policyRef": "string",
    "supportMode": "GEOMETRIC_PAINT_SUPPORT|VISIBLE_PAINT_SUPPORT|CUSTOM_RENDER_SUPPORT",
    "alphaMode": "ANY_NONZERO|THRESHOLD|CUSTOM",
    "alphaThreshold": "required only for THRESHOLD; finite [0,1]",
    "includeOutlines": "boolean",
    "includeMasks": "boolean",
    "includeDecorativeObjects": "boolean or explicit semantic filter adapter",
    "occlusionMode": "IGNORE_FOR_UNION|VISIBLE_ONLY|CUSTOM",
    "boundaryRule": "CLOSED_SUPPORT|CUSTOM",
    "provenance": "STANDARD|STYLE_PRESET|EMPIRICAL|INITIAL_HEURISTIC"
  },
  "object_support_schema": {
    "objectRef": "string",
    "supportRef": "owner-qualified resolved support ref",
    "coordinateSpaceRef": "must be reconcilable with CompositionSpaceDomain",
    "supportMode": "must match/adapt to requested policy",
    "visibilityRef": "optional",
    "alphaSupportRef": "optional according policy",
    "clipRef": "optional",
    "status": "READY|N_A|PARTIAL|INVALID",
    "confidence": "0..1",
    "provenance": "object"
  },
  "space_mask_schema": {
    "maskRef": "string",
    "domainRef": "CompositionSpaceDomain ref",
    "policyRef": "SpaceMaskPolicy ref",
    "kind": "OCCUPIED|FREE",
    "representation": "VECTOR_REGION|RASTER_BINARY|HYBRID",
    "dataRef": "backend-specific immutable data ref",
    "measurementStage": "GEOMETRIC_SUPPORT|VISIBLE_SUPPORT|FREE_SPACE_DERIVED",
    "exactness": "EXACT|BOUNDED_APPROXIMATION",
    "confidence": "0..1",
    "provenance": "object",
    "supportSetRef": "ObjectSupportSet ref"
  },
  "mask_construction": {
    "step_1": "validate domain + policy + explicit support set state",
    "step_2": "adapt each included object support into domain coordinate space",
    "step_3": "resolve alpha/visibility/outline/mask support under SpaceMaskPolicy",
    "step_4": "clip each support to CompositionSpaceDomain",
    "step_5": "boolean union all included supports -> OccupiedMask",
    "step_6": "FreeMask = Domain minus OccupiedMask using same domain/policy",
    "step_7": "measure occupied/free area and fractions from the canonical masks",
    "step_8": "emit exactness/confidence/error/provenance"
  },
  "representation_policy": {
    "preferred": "exact vector boolean region when source supports robust exact/controlled geometry",
    "fallback": "deterministic raster binary mask or bounded polygonal approximation",
    "raster_sampling": "pixel/sample-cell rule must be explicit and deterministic",
    "anti_aliasing": "render antialias coverage is not automatically fractional free space; alphaMode resolves support to binary occupancy first",
    "hybrid": "allowed only when error bounds and conversion provenance are explicit"
  },
  "area_metrics": {
    "domainAreaPx2": "area of supplied CompositionSpaceDomain boundary; diagnostic input/derived helper, not canvas ownership",
    "occupiedAreaPx2": "measure(OccupiedMask)",
    "freeAreaPx2": "measure(FreeMask)",
    "occupiedFraction": "occupiedAreaPx2/domainAreaPx2",
    "freeFraction": "freeAreaPx2/domainAreaPx2",
    "complement_identity": "occupiedAreaPx2 + freeAreaPx2 = domainAreaPx2 within declared tolerance",
    "fraction_identity": "occupiedFraction + freeFraction = 1 within declared tolerance"
  },
  "metric_policy": {
    "occupied/free_area": "geometric scene-space descriptors only",
    "occupied/free_fraction": "scene-domain descriptors only",
    "direct_scoring": "FORBIDDEN in 5.01",
    "more_free_is_better": "FORBIDDEN",
    "more_occupied_is_better": "FORBIDDEN",
    "target_interpretation": "deferred to Compo5.04",
    "components_relation": "freeArea/fraction are algebraic complements of occupiedArea/fraction and must not become independent scoring votes"
  },
  "empty_and_full_semantics": {
    "explicit_empty_support_set": "valid OccupiedMask empty, occupiedArea=0, freeArea=domainArea, freeFraction=1",
    "fully_covered_domain": "valid FreeMask empty, freeArea=0, occupiedFraction=1",
    "missing_support_set": "N_A/PARTIAL according input policy; never treat as explicit empty scene",
    "all_supports_N_A": "N_A/PARTIAL, not empty occupancy",
    "zero_domain_area": "INVALID/N_A, fractions undefined"
  },
  "occlusion_alpha_policy": {
    "GEOMETRIC_PAINT_SUPPORT": "union resolved paint-support geometry; object-to-object occlusion does not subtract occupied union unless explicit policy says visible-only",
    "VISIBLE_PAINT_SUPPORT": "requires visibility/occlusion-resolved support adapter",
    "ANY_NONZERO": "alpha>owner epsilon is occupied support",
    "THRESHOLD": "alpha>=explicit threshold is occupied support",
    "CUSTOM": "requires owner-qualified binary support result",
    "important": "alpha magnitude remains Topic4 mass evidence; 5.01 uses alpha only to decide binary support membership under explicit policy"
  },
  "hard_constraints": [
    "one metric = one owner",
    "OccupiedMask and FreeMask must share the same CompositionSpaceDomain and SpaceMaskPolicy",
    "FreeMask is the complement of OccupiedMask inside the explicit domain",
    "object supports must be boolean-unioned; naive sum of per-object occupied areas is forbidden",
    "support outside the domain is clipped before occupied/free measurement",
    "4.01 hullOccupancy must not be reused as scene occupiedFraction",
    "visual mass values must not be used to infer occupied mask geometry",
    "alpha magnitude must not become fractional free-space area unless an explicit custom support policy defines binary membership",
    "render antialiasing is not a free-space metric",
    "missing support set is not equivalent to explicit empty support set",
    "zero free area is a valid result for fully occupied domain",
    "zero occupied area is a valid result for explicitly empty included support set",
    "occupiedFraction/freeFraction are descriptors, not scores",
    "occupiedFraction and freeFraction are algebraic complements and not independent votes",
    "scene masks remain separate from Topic8 grid occupancy",
    "connected empty regions/clearance remain Compo5.02",
    "figure-ground relations remain Compo5.03",
    "target-aware whitespace/free-space scoring remains Compo5.04",
    "global balance/hierarchy/eye-flow remain future owners",
    "N/A != 0",
    "no beautyScore",
    "ObjectSupportSet.state is mandatory; refs=[] is a valid empty scene only when state=EXPLICIT",
    "PARTIAL support set may produce diagnostics but must not publish canonical occupied/free fractions as if complete",
    "MISSING support set publishes N/A, never occupiedFraction=0/freeFraction=1"
  ],
  "initial_heuristics": {
    "vector_boolean_area_tolerance_px2": {
      "value": 1e-06,
      "provenance": "IMPLEMENTATION_HEURISTIC"
    },
    "raster_support_alpha_epsilon": {
      "value": 0.001,
      "provenance": "IMPLEMENTATION_HEURISTIC",
      "note": "used only for ANY_NONZERO when no stronger owner threshold exists"
    },
    "max_raster_cells": {
      "value": 4194304,
      "provenance": "IMPLEMENTATION_HEURISTIC"
    }
  },
  "correction_policy": {
    "foreign_geometry_mutation": "FORBIDDEN",
    "invalid_domain": "request domain/canvas owner correction",
    "coordinate_mismatch": "request transform/domain adapter",
    "unresolved_object_support": "route to Topic3/render support owner",
    "visibility_or_occlusion_missing": "request visibility/occlusion adapter",
    "alpha_policy_missing": "request paint/render support owner or explicit policy",
    "mask_boolean_failure": "request backend fallback with bounded error; do not invent area",
    "empty_region_issue": "route to Compo5.02",
    "figure_ground_issue": "route to Compo5.03",
    "target_preference_issue": "route to Compo5.04"
  },
  "deferred_inputs": [
    "Compo5.02 connected empty regions / clearance / breathing room",
    "Compo5.03 figure-ground relations",
    "Compo5.04 target-aware scoring/corrections/regression",
    "Topic6 canonical canvas/format/domain normalization",
    "Topic8 grid occupancy",
    "future global balance/hierarchy/eye-flow"
  ],
  "recompute_when": [
    "CompositionSpaceDomain boundary/version changes",
    "included support set changes",
    "any object support geometry changes",
    "mask policy changes",
    "visibility/occlusion/alpha support changes",
    "clip/crop domain changes",
    "vector/raster fallback policy or tolerance changes"
  ],
  "finality": "SCENE_OCCUPIED_AND_FREE_MASK_GEOMETRY_ONLY",
  "object_support_set_schema": {
    "supportSetRef": "string",
    "state": "EXPLICIT|PARTIAL|MISSING",
    "refs": "ObjectSupportRef[]",
    "unresolvedRefs": "optional refs[] for PARTIAL",
    "semantics": {
      "EXPLICIT": "complete included support set; refs may be empty and that is a valid empty scene",
      "PARTIAL": "some support evidence unresolved; canonical occupied/free metrics are N/A until completed",
      "MISSING": "support set not supplied; not equivalent to empty"
    },
    "confidence": "0..1",
    "provenance": "object"
  }
}