From 029039bf35c6f78977b1d914be826f5f84bf7fee Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Thu, 9 Jul 2026 11:54:25 -0400 Subject: [PATCH] Straighten the QMC version story in the docs that assert it Review follow-up on 5b016f3. Bumping the catalog to 0.3.0, I ran a mechanical find-and-replace over the version string and did not reread the sentences around it. Result: layout-ir's quality.rs credited the spacing_distortion refinement to v0.3.0 when that was v0.2.0, and engrave's quality.rs still announced v0.2.0 while implementing the v0.3.0 unit set. Each version now says what it actually did: v0.2.0 narrowed spacing_distortion's measurement DOMAIN to rhythmic columns; v0.3.0 narrowed vertical_density_penalty's CONTRIBUTING UNITS to one per realization of a gap band. Both narrowed what is measured over, not what it is normalized against -- so the transcribed constants (anchors, thresholds, warning fraction) have not moved since v0.1.0, which is the invariant worth stating and the reason the two revisions were safe. Swept for the same rot rather than fixing only the two reported. Three more present-tense claims pinned a version that will keep going stale: engrave and layout-ir DECISIONS both said "the companion (v0.2.0) ratifies/pins the nine axes", and the reference suite claimed RS-1 passes "under engrave v3, QMC v0.2.0 anchors" -- engrave is at 11. All three now cite the current version and name what is actually invariant across revisions. The remaining "QMC 0.1.0 -> 0.2.0" mentions are historical records of what that revision did and stay as they are. Docs only. Gate green; zero golden churn. Co-Authored-By: Claude Opus 4.8 (1M context) --- crates/epiphany-engrave/DECISIONS.md | 9 ++++++--- crates/epiphany-engrave/src/quality.rs | 11 +++++++---- crates/epiphany-layout-ir/DECISIONS.md | 3 ++- crates/epiphany-layout-ir/src/quality.rs | 12 ++++++++---- crates/epiphany-testkit/src/reference_suite.rs | 3 ++- 5 files changed, 25 insertions(+), 13 deletions(-) diff --git a/crates/epiphany-engrave/DECISIONS.md b/crates/epiphany-engrave/DECISIONS.md index 644640f..951882a 100644 --- a/crates/epiphany-engrave/DECISIONS.md +++ b/crates/epiphany-engrave/DECISIONS.md @@ -268,9 +268,12 @@ resolved: ## Quality metrics (2026-07) — decisions -The Quality Metric Catalog companion (v0.2.0) ratified the nine normative -axes' formal definitions, anchors, thresholds, and the -`QualityFloorApproached` trigger; `Engraver::resolve` now computes the real +The Quality Metric Catalog companion (ratified at v0.1.0; currently v0.3.0 — +the axis set, anchors, and thresholds are unchanged across both minor +revisions, which narrowed *what is measured over*, not what it is normalized +against) ratified the nine normative axes' formal definitions, anchors, +thresholds, and the `QualityFloorApproached` trigger; `Engraver::resolve` +now computes the real vector (the private `quality` module), replacing the all-worst placeholder. The catalog's normative constants (anchors, the Minimal/Standard threshold table, the 0.8 warning fraction, the tier/profile→column mappings) are diff --git a/crates/epiphany-engrave/src/quality.rs b/crates/epiphany-engrave/src/quality.rs index 5a0d5ce..fbaa7cd 100644 --- a/crates/epiphany-engrave/src/quality.rs +++ b/crates/epiphany-engrave/src/quality.rs @@ -1,10 +1,13 @@ //! **Real quality-metric computation** — the nine normative axes of the -//! *Quality Metric Catalog* companion (v0.2.0, Chapter 3), measured over what +//! *Quality Metric Catalog* companion (v0.3.0, Chapter 3), measured over what //! the pipeline already produced: the resolved world-frame geometry //! ([`CastLayout`]), the constrained input (slot identity, vertical bands), and -//! the declared page geometry. Normalization anchors, threshold tables, and the -//! warning fraction are the catalog's, transcribed in -//! [`epiphany_layout_ir::quality`]. +//! the declared page geometry. This module implements the v0.3.0 unit set: +//! `spacing_distortion` over rhythmic columns (v0.2.0) and +//! `vertical_density_penalty` over each *realization* of a gap band (v0.3.0). +//! Both revisions narrowed what is measured over, not what it is normalized +//! against: the anchors, threshold tables, and warning fraction are the +//! catalog's, transcribed unchanged in [`epiphany_layout_ir::quality`]. //! //! Every measurement here is a pure function of the solve's inputs and its //! resolved output — no clocks, no entropy, fixed iteration order — so repeated diff --git a/crates/epiphany-layout-ir/DECISIONS.md b/crates/epiphany-layout-ir/DECISIONS.md index 751c976..778ae5a 100644 --- a/crates/epiphany-layout-ir/DECISIONS.md +++ b/crates/epiphany-layout-ir/DECISIONS.md @@ -425,7 +425,8 @@ object is covered); the provenance-preservation contract itself is unchanged. ## Quality Metric Catalog constants (`src/quality.rs`, 2026-07) **Decision: the catalog's normative constants live in this crate, as a pure -transcription.** The Quality Metric Catalog companion (v0.2.0) pins the nine +transcription.** The Quality Metric Catalog companion (currently v0.3.0; every +number below is unchanged since v0.1.0) pins the nine axes' normalization anchors (`R_worst`), the clamped-linear normalization form `n = min(1, raw / R_worst)`, the Minimal/Standard threshold table, the `QualityFloorApproached` warning fraction (0.8), and the tier/profile → diff --git a/crates/epiphany-layout-ir/src/quality.rs b/crates/epiphany-layout-ir/src/quality.rs index ab392f2..78a0dac 100644 --- a/crates/epiphany-layout-ir/src/quality.rs +++ b/crates/epiphany-layout-ir/src/quality.rs @@ -1,10 +1,14 @@ //! The Quality Metric Catalog's normative constants (companion specification //! *Epiphany — Quality Metric Catalog*, v0.3.0): the per-axis normalization //! anchors, the per-tier metric threshold table, the profile→threshold-column -//! mapping, and the `QualityFloorApproached` warning fraction. (The v0.3.0 -//! `spacing_distortion` refinement scoped that axis's *measurement domain* to -//! rhythmic columns; it touched no anchor or threshold, so this transcription -//! of the numeric constants is unchanged.) +//! mapping, and the `QualityFloorApproached` warning fraction. +//! +//! **Neither minor revision so far has moved a number here.** v0.2.0 narrowed +//! `spacing_distortion`'s *measurement domain* to rhythmic columns; v0.3.0 +//! narrowed `vertical_density_penalty`'s *contributing units*, counting one per +//! realization of a gap band rather than one per band. Both changed what a +//! solver measures over, not what it normalizes against, so this transcription +//! of the numeric constants is unchanged across both. //! //! This module is a **transcription**, not an invention: every number here is //! pinned by the catalog and cited to its chapter. Solvers that compute real diff --git a/crates/epiphany-testkit/src/reference_suite.rs b/crates/epiphany-testkit/src/reference_suite.rs index 93fb6e4..f4c67bb 100644 --- a/crates/epiphany-testkit/src/reference_suite.rs +++ b/crates/epiphany-testkit/src/reference_suite.rs @@ -122,7 +122,8 @@ pub fn entries() -> Vec { construction: "fixtures::ten_measure_single_staff(0x000A_11CE)", build: rs1, // Passes every Minimal threshold under the reference engraver - // (engrave v3, QMC v0.2.0 anchors). Greedy first-fit alone left a + // (the QMC anchors it is scored against are unchanged through + // v0.3.0). Greedy first-fit alone left a // two-measure stub last system (width CV 0.61 -> clamped 1.0 > the // 0.90 threshold, the original P12-I11 miss); casting-off's // widow-rebalance phase now evens the split to a six/four