Columns,
widths,
gutters & spans.

ColumnLayoutSpec {
  layoutSpecRef,
  gridRef,

  columnCount: integer >= 1,

  widthMode:
    EQUAL |
    WEIGHTED |
    EXPLICIT,

  columnWeights[]?,
  columnWidths[]?,

  gutterSpec,

  normalizationMode:
    RAW_ONLY |
    RAW_AND_SHORT_N,

  normalizationContextRef?,
  confidence,
  provenance
}

ColumnTrack {
  columnIndex,
  x0,
  x1,
  widthRaw,
  widthShortN?,
  domainY0,
  domainY1
}

GutterTrack {
  gutterIndex,
  leftColumnIndex,
  rightColumnIndex,
  x0,
  x1,
  widthRaw,
  widthShortN?
}

ColumnSpanSpec {
  spanRef,
  gridRef,

  startColumnIndex,
  endColumnIndexExclusive,

  confidence,
  provenance
}

{
  "module": "Compo 8.01",
  "name": "columns_widths_gutters_and_spans",
  "version": "1.0-canonical",
  "canonical_main_title": "Columns, widths, gutters and spans",
  "topic": "08_КОЛОННАЯ_СЕТКА",
  "scope": "COLUMN_WIDTH_ALLOCATION_GUTTER_GEOMETRY_CONTIGUOUS_SPANS_AND_RESOLVED_1D_COLUMN_TRACKS",
  "consumes": [
    "Compo8.00.ColumnGrid",
    "Compo8.00.GridDomainBinding resolved to one rectangular grid domain",
    "Compo8.00.GridCoordinateContext",
    "explicit ColumnLayoutSpec",
    "explicit ColumnSpanSpec[]",
    "optional compatible Compo6.03.CanvasNormalizationContext"
  ],
  "provides": [
    "ColumnLayoutSpec",
    "ColumnTrack[]",
    "GutterTrack[]",
    "ResolvedColumnGeometry",
    "ColumnSpanSpec",
    "ResolvedColumnSpan[]",
    "ColumnGeometryDiagnostic[]",
    "columnGeometryRef for Compo8.02 / Compo8.03 / Compo8.04"
  ],
  "owns_metrics": [],
  "descriptors_only": [
    "grid.column.count",
    "grid.column.widthMode",
    "grid.column.widthRaw",
    "grid.column.widthShortN",
    "grid.gutter.widthRaw",
    "grid.gutter.widthShortN",
    "grid.span.startColumnIndex",
    "grid.span.endColumnIndexExclusive",
    "grid.span.widthRaw",
    "grid.span.widthShortN",
    "grid.span.contentColumnWidthSumRaw",
    "grid.span.internalGutterWidthSumRaw",
    "grid.column.geometryStatus"
  ],
  "column_layout_spec_schema": {
    "layoutSpecRef": "stable versioned ref",
    "gridRef": "must match Compo8.00 ColumnGrid.gridRef",
    "columnCount": "integer >=1",
    "widthMode": "EQUAL|WEIGHTED|EXPLICIT",
    "columnWeights": "required positive finite array length=columnCount for WEIGHTED",
    "columnWidths": "required positive finite array length=columnCount for EXPLICIT",
    "gutterSpec": "GutterSpec",
    "normalizationMode": "RAW_ONLY|RAW_AND_SHORT_N",
    "normalizationContextRef": "required for RAW_AND_SHORT_N",
    "confidence": "0..1",
    "provenance": "STANDARD|EMPIRICAL|INITIAL_HEURISTIC|STYLE_PRESET|DERIVED",
    "important": "8.01 never injects a default columnCount or default gutter"
  },
  "gutter_spec_schema": {
    "mode": "UNIFORM|EXPLICIT",
    "uniformWidth": "finite >=0 when mode=UNIFORM",
    "widths": "finite >=0 array length=columnCount-1 when mode=EXPLICIT",
    "unit": "inherits grid-domain source unit",
    "important": "for one column the resolved gutter list is empty"
  },
  "width_allocation": {
    "domainWidth": "W = domain.x1-domain.x0",
    "gutterTotal": "G = sum(resolved gutter widths)",
    "residual": "R = W-G",
    "EQUAL": "columnWidth_i = R/N",
    "WEIGHTED": "columnWidth_i = R * weight_i / sum(weights)",
    "EXPLICIT": "use supplied columnWidths; require sum(columnWidths)+G == W within fit tolerance",
    "unsatisfiable": "R<=EPS for EQUAL/WEIGHTED or explicit sum mismatch / nonpositive width",
    "no_autofit": "EXPLICIT widths are never silently stretched to fit the domain"
  },
  "column_track_schema": {
    "trackRef": "stable derived ref",
    "columnGeometryRef": "parent geometry ref",
    "columnIndex": "zero-based integer",
    "x0": "left boundary in source unit",
    "x1": "right boundary in source unit",
    "widthRaw": "x1-x0",
    "widthShortN": "optional normalized value",
    "domainY0": "grid domain top",
    "domainY1": "grid domain bottom",
    "status": "OK",
    "confidence": "0..1",
    "provenance": "DERIVED"
  },
  "gutter_track_schema": {
    "trackRef": "stable derived ref",
    "gutterIndex": "0..columnCount-2",
    "leftColumnIndex": "gutterIndex",
    "rightColumnIndex": "gutterIndex+1",
    "x0": "left gutter boundary",
    "x1": "right gutter boundary",
    "widthRaw": "x1-x0; may be zero",
    "widthShortN": "optional",
    "status": "OK",
    "confidence": "0..1",
    "provenance": "DERIVED"
  },
  "column_span_spec_schema": {
    "spanRef": "stable explicit ref",
    "gridRef": "same ColumnGrid",
    "startColumnIndex": "integer >=0",
    "endColumnIndexExclusive": "integer > startColumnIndex and <= columnCount",
    "confidence": "0..1",
    "provenance": "object",
    "baseline": "contiguous only"
  },
  "resolved_column_span_schema": {
    "spanRef": "source span ref",
    "columnGeometryRef": "resolved geometry lineage",
    "startColumnIndex": "inclusive",
    "endColumnIndexExclusive": "exclusive",
    "includedColumns": "ordered integer indices",
    "x0": "first column x0",
    "x1": "last column x1",
    "widthRaw": "x1-x0; includes internal gutters",
    "widthShortN": "optional",
    "contentColumnWidthSumRaw": "sum included column widths only",
    "internalGutterWidthSumRaw": "sum internal gutters",
    "identity": "widthRaw = contentColumnWidthSumRaw + internalGutterWidthSumRaw",
    "confidence": "0..1",
    "provenance": "DERIVED"
  },
  "partition_invariants": {
    "left_boundary": "first column.x0 == domain.x0",
    "right_boundary": "last column.x1 == domain.x1",
    "sequence": "column0, gutter0, column1, ... gutterN-2, columnN-1",
    "no_overlap": "adjacent interval boundaries coincide; no positive-area overlap",
    "no_gap": "every x in [domain.x0,domain.x1] belongs to a column or gutter interval",
    "track_counts": "columns=N, gutters=N-1",
    "canonical_order": "left-to-right by index"
  },
  "normalization": {
    "raw": "inherits domain source unit",
    "ShortN": "lengthRaw / CanvasNormalizationContext.shortSide",
    "required": "same canvas/sourceUnit, positive finite shortSide",
    "missing_context": "RAW_AND_SHORT_N result becomes N_A/INVALID according caller integration; 8.01 baseline returns N_A geometry normalization result rather than zero",
    "UV": "forbidden as metric width/gutter/span unit"
  },
  "ownership_map": {
    "8.00": "ColumnGrid root/domain/coordinate ownership",
    "8.01": "columns, widths, gutters, contiguous spans and resolved one-dimensional geometry",
    "8.02": "canonical GridLine[], GridNode[] and ColumnGrid node occupancy registry",
    "8.03": "placement candidates over resolved column geometry/topology",
    "8.04": "grid variants, local scoring and consolidated Topic8 tests",
    "9.x": "rows, 2D cells/regions and ModularGrid occupancy",
    "10.x": "alignment relations consuming already resolved grid evidence"
  },
  "semantic_firewalls": {
    "column_interval_vs_grid_line": "x0/x1 are track geometry boundaries; canonical GridLine objects are created only by 8.02",
    "span_vs_placement": "span geometry is an available region, not an object placement or occupancy claim",
    "gutter_vs_negative_space": "gutter is structural grid interval, not Topic5 global/free-space ownership",
    "width_ratio_vs_quality": "narrow/wide columns are descriptors until explicit target/scoring in 8.04",
    "column_count_vs_quality": "columnCount has no universal quality direction"
  },
  "metric_policy": {
    "direct_scoring": "FORBIDDEN in 8.01",
    "more_columns_is_better": "FORBIDDEN",
    "equal_columns_are_better": "FORBIDDEN",
    "narrower_gutters_are_better": "FORBIDDEN",
    "larger_span_is_better": "FORBIDDEN",
    "beautyScore": "FORBIDDEN"
  },
  "hard_constraints": [
    "8.01 owns resolved one-dimensional column geometry: ColumnTrack[], GutterTrack[], width allocation and contiguous ColumnSpan geometry.",
    "8.01 consumes an already valid Compo8.00 ColumnGrid root and a resolved rectangular grid domain; it does not choose the grid domain.",
    "No universal default column count exists.",
    "No universal default gutter width or gutter ratio exists.",
    "Column count must be an explicit integer >= 1.",
    "Baseline width allocation modes are EQUAL, WEIGHTED and EXPLICIT.",
    "EQUAL and WEIGHTED modes distribute only the residual domain width after explicit gutters are subtracted.",
    "EXPLICIT mode requires columnWidths + gutterWidths to equal the bound domain width within numerical fit tolerance; no silent stretching or clamping is allowed.",
    "Negative column widths and negative gutter widths are invalid.",
    "Resolved column widths must be strictly positive.",
    "Zero-width gutters are valid.",
    "For N columns, exactly N-1 gutter intervals exist.",
    "All track geometry is half-open in indexing and ordered left-to-right along the canonical X column axis.",
    "Column tracks and gutter tracks must form an exact non-overlapping partition of the rectangular grid-domain X extent.",
    "8.01 may expose x0/x1 interval boundaries as part of track geometry, but does not instantiate canonical GridLine or GridNode objects; 8.02 owns those.",
    "A ColumnSpan is contiguous and uses zero-based half-open indices [startColumnIndex,endColumnIndexExclusive).",
    "A span geometry extends from the left edge of the first included column to the right edge of the last included column and therefore includes internal gutters.",
    "Span contentColumnWidthSum excludes internal gutters and is reported separately from total span width.",
    "Disjoint multi-range spans are not owned by the baseline 8.01 contract.",
    "8.01 does not own node occupancy, cell occupancy, object placement, collision, candidate generation or scoring.",
    "SHORT_N width/gutter/span values require a compatible Compo6.03 normalization context inherited through 8.00.",
    "AXIS_FRACTION_UV is not a metric width/gutter representation.",
    "Uniform scaling must scale raw geometry linearly while preserving compatible SHORT_N values.",
    "Input order must not affect canonical left-to-right output ordering.",
    "N/A != 0.",
    "No beautyScore."
  ],
  "hard_rules": [
    "8.01 owns resolved one-dimensional column geometry: ColumnTrack[], GutterTrack[], width allocation and contiguous ColumnSpan geometry.",
    "8.01 consumes an already valid Compo8.00 ColumnGrid root and a resolved rectangular grid domain; it does not choose the grid domain.",
    "No universal default column count exists.",
    "No universal default gutter width or gutter ratio exists.",
    "Column count must be an explicit integer >= 1.",
    "Baseline width allocation modes are EQUAL, WEIGHTED and EXPLICIT.",
    "EQUAL and WEIGHTED modes distribute only the residual domain width after explicit gutters are subtracted.",
    "EXPLICIT mode requires columnWidths + gutterWidths to equal the bound domain width within numerical fit tolerance; no silent stretching or clamping is allowed.",
    "Negative column widths and negative gutter widths are invalid.",
    "Resolved column widths must be strictly positive.",
    "Zero-width gutters are valid.",
    "For N columns, exactly N-1 gutter intervals exist.",
    "All track geometry is half-open in indexing and ordered left-to-right along the canonical X column axis.",
    "Column tracks and gutter tracks must form an exact non-overlapping partition of the rectangular grid-domain X extent.",
    "8.01 may expose x0/x1 interval boundaries as part of track geometry, but does not instantiate canonical GridLine or GridNode objects; 8.02 owns those.",
    "A ColumnSpan is contiguous and uses zero-based half-open indices [startColumnIndex,endColumnIndexExclusive).",
    "A span geometry extends from the left edge of the first included column to the right edge of the last included column and therefore includes internal gutters.",
    "Span contentColumnWidthSum excludes internal gutters and is reported separately from total span width.",
    "Disjoint multi-range spans are not owned by the baseline 8.01 contract.",
    "8.01 does not own node occupancy, cell occupancy, object placement, collision, candidate generation or scoring.",
    "SHORT_N width/gutter/span values require a compatible Compo6.03 normalization context inherited through 8.00.",
    "AXIS_FRACTION_UV is not a metric width/gutter representation.",
    "Uniform scaling must scale raw geometry linearly while preserving compatible SHORT_N values.",
    "Input order must not affect canonical left-to-right output ordering.",
    "N/A != 0.",
    "No beautyScore."
  ],
  "soft_constraints": [],
  "preferences": [],
  "overrides_allowed_by": [
    "a newer explicit ColumnLayoutSpec may be used for future geometry resolution",
    "historical ResolvedColumnGeometry remains immutable and tied to its layoutSpecRef/domain snapshot"
  ],
  "initial_heuristics": {
    "fit_epsilon": {
      "formula": "max(1e-12, abs(domainWidth)*1e-12)",
      "provenance": "IMPLEMENTATION_HEURISTIC",
      "note": "used only for numerical equality/partition checks, never as design tolerance"
    }
  },
  "style_preset_values": [],
  "candidate_generation": {
    "placement_candidates": "NONE",
    "reason": "8.01 resolves one explicit geometry specification; 8.03 owns placement candidate generation"
  },
  "correction_policy": {
    "foreign_content_mutation": "FORBIDDEN",
    "invalid_or_unsatisfiable_layout_spec": "return INVALID/UNSATISFIABLE diagnostic; do not clamp widths/gutters",
    "missing_rect_domain": "route to 8.00/domain adapter",
    "missing_normalization_context": "return raw geometry plus N_A normalized representation or route to 6.03",
    "grid_line_or_node_request": "route to 8.02",
    "occupancy_request": "route to 8.02",
    "placement_request": "route to 8.03",
    "scoring_request": "route to 8.04"
  },
  "deferred_inputs": [
    "Compo8.02 GridLine/GridNode/occupancy contracts",
    "Compo8.03 placement candidates",
    "Compo8.04 variants/scoring/tests",
    "Topic9 row/cell modular-grid geometry",
    "future explicit non-contiguous span-family contract if ever needed"
  ],
  "recompute_when": [
    "grid domain geometry/version changes",
    "ColumnLayoutSpec changes",
    "columnCount changes",
    "widthMode/weights/explicit widths change",
    "gutterSpec changes",
    "normalization context changes",
    "span specs change"
  ],
  "tests": [
    "equal widths",
    "weighted widths",
    "explicit widths",
    "uniform gutters",
    "explicit gutters",
    "single-column zero gutter list",
    "unsatisfiable residual",
    "explicit sum mismatch",
    "partition exactness",
    "span indexing",
    "span identity",
    "ShortN scale invariance",
    "missing normalization",
    "no lines/nodes/occupancy",
    "determinism",
    "no scoring/global leakage"
  ],
  "finality": "RESOLVED_COLUMN_WIDTH_GUTTER_AND_CONTIGUOUS_SPAN_GEOMETRY_ONLY"
}