spec(t27f): a research reel through the same topic workflow -- GF16 vs bfloat16 NMSE (Closes #10010)

specs/t27f/reel_gf16_nmse.t27

@@ -0,0 +1,288 @@
+// SPDX-License-Identifier: Apache-2.0
+; specs/t27f/reel_gf16_nmse.t27 -- the second real T27F reel, and the first in another domain:
+; research, "how close does GF16 come to bfloat16", as the project's own NMSE protocol asks it.
+; gHashTag/trinity#1677 wants at least two very different domains on one widget and one workflow,
+; and a 27-step map that is source-grounded with its gaps named. The first reel
+; (reel_t27_basics.t27) is a course, routed to engineering; this one is a benchmark, routed to
+; research, and both go through the same code: topic_engine.t27 decides, topic_reel.t27 checks,
+; reel.t27 and deck.t27 draw. Nothing below is a rule of this file's own.
+
+; SOURCE: gHashTag/t27 at SOURCE_COMMIT, measured on MEASURED_ON. The protocol spec
+; specs/benchmarks/gf16_bfloat16_nmse.t27 and its mirror docs/GF16_BFLOAT16_NMSE_PROTOCOL.md, the
+; manifest schema schemas/nmse-protocol-v1.json, the roadmap docs/SCIENTIFIC_IMPROVEMENT_PLAN.md
+; (PUB-01, PUB-02), and what the repo already holds about GF16. Every cell names its source in
+; SOURCES; a cell with none is a gap and says in MISSING what would ground it.
+
+; BRIEF is the first three sentences of the protocol spec's header, verbatim. route_brief
+; counts gf16 twice and benchmark once, no other list is hit, so the domain is DOMAIN_RESEARCH.
+
+; LENSES: one row per lens. Steps 1-9 are the formats and why they compare at all; 10-18 the protocol
+; and the one run it asks for; 19-27 what may be said and what the repo has said so far.
+
+; MEASURED on 2026-10-17:
+;   - grounded: the source is in the repo at SOURCE_COMMIT (path and section in SOURCES).
+;   - test: t27c test-report and t27b test --check on the Railway lab passed all 7 tests of the
+;     protocol spec; a planted GF16_MANT_BITS = 8 turned 2 of them red under both, so they are real.
+;   - review: the PRs that wrote the protocol (#1399) and the spec rewrite (#5947) have 0 reviews.
+;   - live: GET https://t27.ai/t27/files/<path> returned 200 for the protocol spec and the schema,
+;     and 404 for the doc, FORMAT-SPEC-001.json, gf16_bench_results.json, the crosswalk and the paper
+;     draft; a made-up path returned 404, so 200 is not a catch-all.
+; The engine asks a research LEARN step for a source link, a PRACTICE step for a review or a passing
+; test, and a DELIVER step for a review. So: 15 published (sourced, earned, and live), 1 verified
+; (reporting rules: sourced, not live), 6 drafts (practice or deliver steps with neither a test nor a
+; review) and 5 gaps.
+
+; THE GAPS are the point of this reel. PUB-02 asks for one sealed bench/results/nmse-*.json; the repo
+; holds none, so the run, its schema check, the ratio per distribution and the paper's Delta_dB (which
+; PUB-02 forbids before that manifest) are gaps, and so is the chip repo's manifest:
+; gHashTag/tt-trinity-gamma tests/vectors/nmse_gf16_bf16.golden.json at GAMMA_COMMIT pins the seeds
+; but says measured_silicon false and harness_committed false. The only GF16/BF16 numbers in the repo,
+; conformance/gf16_bench_results.json (2026-04-05, no seed, no seal), are drawn as a draft that the
+; protocol itself says does not count.
+
+; Not claimed: no NMSE value, no ratio, no winner. No GIF or MP4; stills only, for the chat.
+; phi^2 + 1/phi^2 = 3 | TRINITY
+
+module reel_gf16_nmse;
+
+use t27f::reel::CELL_COUNT;
+use t27f::reel::DEMO_COUNT;
+use t27f::reel::DEMO_CELL;
+use t27f::reel::DEMO_LENS;
+use t27f::topic_engine::STATUS_GAP;
+use t27f::topic_engine::STATUS_DRAFT;
+use t27f::topic_engine::STATUS_VERIFIED;
+use t27f::topic_engine::STATUS_PUBLISHED;
+use t27f::topic_engine::STAGE_DELIVER;
+use t27f::topic_engine::STAGE_PRACTICE;
+use t27f::topic_engine::DOMAIN_RESEARCH;
+use t27f::topic_engine::CONTENT_WORDS;
+use t27f::topic_engine::ENGINEERING_WORDS;
+use t27f::topic_engine::RESEARCH_WORDS;
+use t27f::topic_engine::SALES_WORDS;
+use t27f::topic_engine::keyword_hits;
+use t27f::topic_engine::route_brief;
+use t27f::topic_engine::step_stage;
+use t27f::topic_reel::count_status;
+use t27f::topic_reel::count_true;
+use t27f::topic_reel::statuses_earned;
+use t27f::topic_reel::gaps_are_named;
+use t27f::topic_reel::slides_fit;
+use t27f::topic_reel::stage_slides_bare;
+
+pub const TOPIC_ID : str = "gf16-nmse";
+pub const SOURCE_REPO : str = "gHashTag/t27";
+pub const SOURCE_SPEC : str = "specs/benchmarks/gf16_bfloat16_nmse.t27";
+pub const SOURCE_COMMIT : str = "de2cff88243c179e5bbf21f8cb06e5da1ab833e8";
+pub const GAMMA_REPO : str = "gHashTag/tt-trinity-gamma";
+pub const GAMMA_COMMIT : str = "de484c4ff249356624ec508127fcbab880ee25fc";
+pub const LIVE_BASE : str = "https://t27.ai/t27/files/";
+pub const MEASURED_ON : str = "2026-10-17";
+
+pub const BRIEF : str = "GF16 against bfloat16 NMSE protocol (TRI-NET benchmark 0). The standard comparison of GoldenFloat GF16 and bfloat16 numeric fidelity, as normalised mean squared error over named reference distributions. Protocol only: no silicon number is asserted.";
+/// The domain route_brief gives that brief (see the_domain_is_routed_not_chosen).
+pub const DOMAIN : u8 = 3;
+
+pub const LENS_TITLES : [3]str = ["formats", "protocol", "claims"];
+
+pub const TITLES : [27]str = [
+    "NMSE, the measure",
+    "GF16: 1 | 6 | 9, bias 31",
+    "bfloat16: 1 | 8 | 7, bias 127",
+    "Both are 16 bits",
+    "Each bias is half the exponent range",
+    "GF16 trades exponent for mantissa",
+    "Why the same width makes it fair",
+    "Where P3109 places both",
+    "GF16 in the numeric SSOT",
+    "Five reference distributions",
+    "Check phi before any NMSE",
+    "What a manifest holds",
+    "The witness holds in f64",
+    "D_DEEP weights sum to one",
+    "NMSE is never negative",
+    "The sealed run, 5 x 10M samples",
+    "A manifest checked against its schema",
+    "The chip repo's manifest",
+    "Reading the ratio",
+    "Reporting rules",
+    "What is not claimed",
+    "Which way the ratio points",
+    "The old numbers, 2026-04-05",
+    "Why they do not count",
+    "The ratio per distribution",
+    "Delta_dB in the paper",
+    "The paper draft"
+];
+
+/// Where each cell's text comes from in SOURCE_REPO at SOURCE_COMMIT; "" is a gap.
+pub const SOURCES : [27]str = [
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 header, NMSE(F)",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 GF16_*",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 BF16_*",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 test both_layouts_are_sixteen_bits",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 test biases_are_half_the_exponent_range",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 test gf16_trades_exponent_for_mantissa",
+    "docs/GF16_BFLOAT16_NMSE_PROTOCOL.md section 3.3",
+    "docs/P3109_CROSSWALK_4PARAM.md rows bf16 and gf16",
+    "conformance/FORMAT-SPEC-001.json",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 DISTRIBUTIONS",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 WITNESS_TOLERANCE",
+    "schemas/nmse-protocol-v1.json",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 test identity_witnesses_hold_in_f64",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 test d_deep_mixture_weights_sum_to_one",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 test nmse_non_negative_and_zero_baseline_undefined",
+    "",
+    "",
+    "",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 header, the ratio",
+    "docs/GF16_BFLOAT16_NMSE_PROTOCOL.md section 8",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 NON_CLAIMS",
+    "specs/benchmarks/gf16_bfloat16_nmse.t27 test ratio_direction",
+    "conformance/gf16_bench_results.json",
+    "docs/GF16_BFLOAT16_NMSE_PROTOCOL.md section 6",
+    "",
+    "",
+    "docs/WHITEPAPER/gf_paper_v3_imrad_draft.md (PUB-01)"
+];
+
+/// What would ground each gap; "" for a cell that has its source.
+pub const MISSING : [27]str = [
+    "", "", "", "", "", "", "", "", "", "", "", "", "", "", "",
+    "bench/results/nmse-*.json, the sealed run PUB-02 asks for: the repo holds 0 such files",
+    "a manifest to check against schemas/nmse-protocol-v1.json: none exists",
+    "tt-trinity-gamma nmse_gf16_bf16.golden.json pins seeds only: measured_silicon false, harness_committed false",
+    "", "", "", "", "", "",
+    "an NMSE ratio per distribution: no run has produced one",
+    "a Delta_dB figure: PUB-02 forbids one before the manifest lands",
+    ""
+];
+
+/// The measurements per cell (see the header for how each was taken).
+pub const GROUNDED : [27]bool = [true, true, true, true, true, true, true, true, true, true, true, true, true, true, true, false, false, false, true, true, true, true, true, true, false, false, true];
+pub const TEST_PASS : [27]bool = [false, false, false, true, true, true, false, false, false, false, false, false, true, true, true, false, false, false, false, false, false, true, false, false, false, false, false];
+pub const REVIEWED : [27]bool = [false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false];
+pub const LIVE : [27]bool = [true, true, true, true, true, true, false, false, false, true, true, true, true, true, true, false, false, false, true, false, true, true, false, false, false, false, false];
+
+/// What a host passes the viewer, per cell: the status code and the step number as a label.
+pub const STATUS : [27]u8 = [5, 5, 5, 5, 5, 5, 3, 3, 3, 5, 5, 5, 5, 5, 5, 0, 0, 0, 5, 4, 5, 5, 3, 3, 0, 0, 3];
+pub const LABELS : [27]str = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27"];
+
+/// Slide text per demo scene, checked by topic_reel.t27 slides_fit (index scene*4+row).
+pub const HEAD : [5]str = [
+    "GF16 vs bfloat16 NMSE",
+    "Steps 1-9: formats",
+    "Witness first",
+    "Evidence",
+    "The missing run"
+];
+pub const ROWS : [20]str = [
+    "", "", "", "",
+    "", "", "", "",
+    "Step 11 of 27: check phi before NMSE",
+    "phi^2 + 1/phi^2 = 3 within 1e-15",
+    "A failed witness aborts the run",
+    "No manifest is written after a failure",
+    "7 of 7 protocol tests pass on the lab",
+    "15 published, 1 verified, 6 drafts",
+    "5 gaps: no measured run exists yet",
+    "Measured 2026-10-17",
+    "PUB-02: one sealed NMSE manifest",
+    "5 distributions, 10M samples each",
+    "Gaps stay gaps until a run lands",
+    ""
+];
+
+/// The protocol spec's own test count, which the evidence slide quotes.
+pub const PROTOCOL_TESTS : i32 = 7;
+
+pub fn step_number(cell: i32) -> i32 {
+    return cell + 1;
+}
+
+test the_domain_is_routed_not_chosen {
+    assert DOMAIN == DOMAIN_RESEARCH;
+    // gf16, gf16, benchmark; "bfloat16" is not "gf16", and no other list is hit
+    assert keyword_hits(BRIEF, BRIEF.len, RESEARCH_WORDS, RESEARCH_WORDS.len) == 3;
+    assert keyword_hits(BRIEF, BRIEF.len, CONTENT_WORDS, CONTENT_WORDS.len) == 0;
+    assert keyword_hits(BRIEF, BRIEF.len, ENGINEERING_WORDS, ENGINEERING_WORDS.len) == 0;
+    assert keyword_hits(BRIEF, BRIEF.len, SALES_WORDS, SALES_WORDS.len) == 0;
+    assert route_brief(BRIEF, BRIEF.len) == DOMAIN;
+}
+
+test every_step_is_a_cell {
+    assert CELL_COUNT == 27;
+    var c : i32 = 0;
+    while (c < CELL_COUNT) {
+        const i : usize = @intCast(c);
+        assert TITLES[i].len > 0;
+        var want : i32 = 1;
+        if (step_number(c) >= 10) {
+            want = 2;
+        }
+        const len : i32 = @intCast(LABELS[i].len);
+        assert len == want;
+        c = c + 1;
+    }
+    assert LENS_TITLES[2].len > 0;
+}
+
+test a_gap_is_named_not_filled {
+    assert gaps_are_named(SOURCES, MISSING, GROUNDED);
+    assert count_true(GROUNDED) == 22;
+    // a gap is drawn as a gap, and only a gap is
+    var c : i32 = 0;
+    while (c < CELL_COUNT) {
+        const i : usize = @intCast(c);
+        assert (STATUS[i] == STATUS_GAP) == (GROUNDED[i] == false);
+        c = c + 1;
+    }
+    // every gap is a DELIVER step: what is missing is the run and what follows it, not the protocol
+    assert step_stage(15) == STAGE_DELIVER;
+    assert step_stage(16) == STAGE_DELIVER;
+    assert step_stage(17) == STAGE_DELIVER;
+    assert step_stage(24) == STAGE_DELIVER;
+    assert step_stage(25) == STAGE_DELIVER;
+}
+
+test a_status_is_earned_not_chosen {
+    assert statuses_earned(STATUS, DOMAIN, GROUNDED, TEST_PASS, REVIEWED, LIVE);
+    // the evidence slide's "15 published, 1 verified, 6 drafts" and "5 gaps"
+    assert count_status(STATUS, STATUS_PUBLISHED) == 15;
+    assert count_status(STATUS, STATUS_VERIFIED) == 1;
+    assert count_status(STATUS, STATUS_DRAFT) == 6;
+    assert count_status(STATUS, STATUS_GAP) == 5;
+    assert count_true(REVIEWED) == 0;
+    // every passing test is one of the protocol's own tests, on a PRACTICE step
+    assert count_true(TEST_PASS) == PROTOCOL_TESTS;
+    var c : i32 = 0;
+    while (c < CELL_COUNT) {
+        const i : usize = @intCast(c);
+        if (TEST_PASS[i]) {
+            assert step_stage(@intCast(c)) == STAGE_PRACTICE;
+        }
+        c = c + 1;
+    }
+    // the old numbers have a source but no seed, seal, test or review: a draft, never published
+    assert STATUS[22] == STATUS_DRAFT;
+}
+
+test the_camera_is_the_demo_camera {
+    assert DEMO_COUNT == 5;
+    // scene 1 shows lens 0, the row HEAD[1] calls "Steps 1-9"
+    assert DEMO_LENS[1] == 0;
+    // scenes 2 and 3 focus cell 10, which the focus slide calls "Step 11": the witness
+    assert DEMO_CELL[2] == 10;
+    assert DEMO_CELL[3] == 10;
+    assert step_number(DEMO_CELL[2]) == 11;
+    assert STATUS[10] == STATUS_PUBLISHED;
+}
+
+test every_slide_fits_every_preset {
+    assert slides_fit(HEAD, ROWS);
+    assert stage_slides_bare(ROWS);
+}
+
+invariant twenty_seven_steps {
+    assert CELL_COUNT == 27;
+}