Skip to main content

ftui_web/
release_readiness.rs

1//! FrankenTermJS release-readiness program (bd-2vr05.12).
2//!
3//! Converts implementation progress into safe-delivery artifacts, as data
4//! rather than prose: the xterm.js **parity scorecard** with blocker tracking
5//! (.12.1), the **browser support matrix** with pass criteria and fallback
6//! expectations (.12.2), the **staged rollout plan** with rollback triggers
7//! and telemetry checkpoints (.12.3), and the **go/no-go checklist** (.12.5).
8//! Everything is deterministic, unit-tested, and serializes to stable JSON so
9//! `scripts/frankenterm_js_release_rehearsal_e2e.sh` (.12.6) can bundle it
10//! into the signoff packet next to the harvested compat/stress evidence.
11//!
12//! **Honesty note:** the `frankenterm-web` WASM packaging crate is
13//! out-of-tree in this checkout. Every parity area names the in-tree
14//! evidence arm that proves its behavior (the `FTUI_*_COMPAT` /
15//! `FTUI_*_MATRIX` harnesses), and the standing packaging blocker is tracked
16//! openly in the scorecard instead of being papered over: readiness for the
17//! browser-facing stages is gated on it.
18
19use core::fmt;
20
21/// Schema version for release-readiness artifacts.
22pub const RELEASE_READINESS_SCHEMA_VERSION: &str = "frankenterm-release-readiness-v1";
23
24fn escape_json(text: &str) -> String {
25    let mut out = String::with_capacity(text.len());
26    for ch in text.chars() {
27        match ch {
28            '"' => out.push_str("\\\""),
29            '\\' => out.push_str("\\\\"),
30            '\n' => out.push_str("\\n"),
31            c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
32            c => out.push(c),
33        }
34    }
35    out
36}
37
38fn json_str_list(items: &[&str]) -> String {
39    items
40        .iter()
41        .map(|s| format!("\"{}\"", escape_json(s)))
42        .collect::<Vec<_>>()
43        .join(",")
44}
45
46// ============================================================================
47// Parity scorecard (.12.1)
48// ============================================================================
49
50/// Parity status for one functional area, versus xterm.js expectations.
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub enum ParityStatus {
53    /// Behavior matches the xterm.js expectation (possibly exceeding it).
54    Full,
55    /// Core works; named gaps remain (see blockers/risks).
56    Partial,
57    /// Intentionally different, documented in the migration guide
58    /// (divergence is a feature, not a gap — e.g. drain-driven events).
59    DivergentByDesign,
60}
61
62impl ParityStatus {
63    /// Stable wire string.
64    #[must_use]
65    pub const fn as_str(self) -> &'static str {
66        match self {
67            Self::Full => "full",
68            Self::Partial => "partial",
69            Self::DivergentByDesign => "divergent_by_design",
70        }
71    }
72}
73
74impl fmt::Display for ParityStatus {
75    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
76        f.write_str(self.as_str())
77    }
78}
79
80/// A tracked release blocker.
81#[derive(Debug, Clone, PartialEq, Eq)]
82pub struct Blocker {
83    /// Stable snake_case id.
84    pub id: &'static str,
85    /// What blocks and why it matters.
86    pub summary: &'static str,
87    /// Earliest rollout stage this blocker gates (everything from that
88    /// stage onward is not ready while the blocker is open).
89    pub gates_stage: RolloutStage,
90}
91
92/// One parity area row.
93#[derive(Debug, Clone, PartialEq, Eq)]
94pub struct ParityArea {
95    /// Stable snake_case area id.
96    pub id: &'static str,
97    /// Human description of the covered surface.
98    pub surface: &'static str,
99    /// Parity verdict.
100    pub status: ParityStatus,
101    /// In-tree evidence arm (crate::test-target) proving the behavior.
102    pub evidence: &'static str,
103    /// Ids of blockers affecting this area (subset of the scorecard's list).
104    pub blocker_ids: Vec<&'static str>,
105    /// Risk annotations reviewers must weigh.
106    pub risks: Vec<&'static str>,
107}
108
109/// The xterm.js parity scorecard: single source of truth for parity
110/// coverage, blockers, and risk annotations.
111#[derive(Debug, Clone)]
112pub struct ParityScorecard {
113    /// Parity rows, in stable order.
114    pub areas: Vec<ParityArea>,
115    /// Open blockers, in stable order.
116    pub blockers: Vec<Blocker>,
117}
118
119impl ParityScorecard {
120    /// The canonical scorecard for the current tree.
121    #[must_use]
122    pub fn canonical() -> Self {
123        let packaging = Blocker {
124            id: "wasm_packaging_out_of_tree",
125            summary: "the frankenterm-web WASM packaging crate (stable JS wrapper) is \
126                      out-of-tree in this checkout; browser-real E2E and npm delivery \
127                      cannot be certified from this repository alone",
128            gates_stage: RolloutStage::CanaryCohort,
129        };
130        Self {
131            areas: vec![
132                ParityArea {
133                    id: "lifecycle_rendering",
134                    surface: "init/resize/fit/render/destroy + renderer backends (dom-first)",
135                    status: ParityStatus::Full,
136                    evidence: "ftui-web::frankenterm_js_runtime_options_e2e",
137                    blocker_ids: vec![],
138                    risks: vec!["webgpu path certified only against simulated engines in-tree"],
139                },
140                ParityArea {
141                    id: "input_ime",
142                    surface: "keyboard/mouse/touch/paste + IME composition pipeline",
143                    status: ParityStatus::Full,
144                    evidence: "ftui-web::frankenterm_js_a11y_e2e",
145                    blocker_ids: vec![],
146                    risks: vec![],
147                },
148                ParityArea {
149                    id: "events_model",
150                    surface: "typed host events + errors (drain-driven, not push-driven)",
151                    status: ParityStatus::DivergentByDesign,
152                    evidence: "ftui-web::frankenterm_js_sdk_contract_compat",
153                    blocker_ids: vec![],
154                    risks: vec!["hosts porting onData habits must adopt the drain loop"],
155                },
156                ParityArea {
157                    id: "attach_transport",
158                    surface: "websocket attach state machine + flow control + reconnect",
159                    status: ParityStatus::Full,
160                    evidence: "ftui-pty::frankenterm_js_security_reliability_compat",
161                    blocker_ids: vec![],
162                    risks: vec![],
163                },
164                ParityArea {
165                    id: "viewport_scrollback",
166                    surface: "patches, viewport, scrollback, snapshot framing",
167                    status: ParityStatus::Full,
168                    evidence: "ftui-web::frankenterm_js_release_stress_e2e",
169                    blocker_ids: vec![],
170                    risks: vec![],
171                },
172                ParityArea {
173                    id: "search_selection_links",
174                    surface: "search, selection, OSC 8 links with open-policy",
175                    status: ParityStatus::Full,
176                    evidence: "ftui-web::frankenterm_js_markers_compat",
177                    blocker_ids: vec![],
178                    risks: vec![],
179                },
180                ParityArea {
181                    id: "accessibility",
182                    surface: "screen-reader mode, announcements, reduced motion/contrast",
183                    status: ParityStatus::Full,
184                    evidence: "ftui-web::frankenterm_js_a11y_e2e",
185                    blocker_ids: vec![],
186                    risks: vec![],
187                },
188                ParityArea {
189                    id: "addons",
190                    surface: "fit / image / ligatures / markers (xterm.js addon equivalents)",
191                    status: ParityStatus::Full,
192                    evidence: "ftui-text::frankenterm_js_ligature_parity_compat",
193                    blocker_ids: vec![],
194                    risks: vec![
195                        "image parity certified at protocol level (sixel/iTerm2), not pixel level",
196                    ],
197                },
198                ParityArea {
199                    id: "sdk_typing_adapters",
200                    surface: "stable API surface, .d.ts, first-party vanilla/React adapters",
201                    status: ParityStatus::Full,
202                    evidence: "ftui-web::frankenterm_js_sdk_validation_e2e",
203                    blocker_ids: vec![],
204                    risks: vec![],
205                },
206                ParityArea {
207                    id: "browser_delivery",
208                    surface: "npm package, browser-real E2E, WASM bundle size budget",
209                    status: ParityStatus::Partial,
210                    evidence: "ftui-web::frankenterm_js_sdk_contract_compat",
211                    blocker_ids: vec!["wasm_packaging_out_of_tree"],
212                    risks: vec![
213                        "everything above is engine-level certified; the JS wrapper \
214                                 must re-run the conformance gates when re-vendored",
215                    ],
216                },
217            ],
218            blockers: vec![packaging],
219        }
220    }
221
222    /// Areas currently blocked (transitively via their blocker ids).
223    #[must_use]
224    pub fn blocked_areas(&self) -> Vec<&ParityArea> {
225        self.areas
226            .iter()
227            .filter(|a| !a.blocker_ids.is_empty())
228            .collect()
229    }
230
231    /// Deterministic JSON.
232    #[must_use]
233    pub fn to_json(&self) -> String {
234        let areas = self
235            .areas
236            .iter()
237            .map(|a| {
238                format!(
239                    "{{\"id\":\"{}\",\"surface\":\"{}\",\"status\":\"{}\",\"evidence\":\"{}\",\"blockers\":[{}],\"risks\":[{}]}}",
240                    a.id,
241                    escape_json(a.surface),
242                    a.status.as_str(),
243                    a.evidence,
244                    json_str_list(&a.blocker_ids),
245                    json_str_list(&a.risks),
246                )
247            })
248            .collect::<Vec<_>>()
249            .join(",");
250        let blockers = self
251            .blockers
252            .iter()
253            .map(|b| {
254                format!(
255                    "{{\"id\":\"{}\",\"summary\":\"{}\",\"gates_stage\":\"{}\"}}",
256                    b.id,
257                    escape_json(b.summary),
258                    b.gates_stage.as_str(),
259                )
260            })
261            .collect::<Vec<_>>()
262            .join(",");
263        format!(
264            "{{\"schema\":\"{RELEASE_READINESS_SCHEMA_VERSION}\",\"artifact\":\"parity_scorecard\",\"areas\":[{areas}],\"blockers\":[{blockers}]}}"
265        )
266    }
267}
268
269// ============================================================================
270// Browser support matrix (.12.2)
271// ============================================================================
272
273/// Support tier for one browser/renderer cell.
274#[derive(Debug, Clone, Copy, PartialEq, Eq)]
275pub enum SupportTier {
276    /// Must pass the full conformance + compat lanes.
277    Supported,
278    /// Expected to work via the documented fallback; failures triage as bugs
279    /// but do not block release.
280    BestEffort,
281    /// Explicitly not targeted; the fallback chain must still land on a
282    /// supported renderer.
283    Unsupported,
284}
285
286impl SupportTier {
287    /// Stable wire string.
288    #[must_use]
289    pub const fn as_str(self) -> &'static str {
290        match self {
291            Self::Supported => "supported",
292            Self::BestEffort => "best_effort",
293            Self::Unsupported => "unsupported",
294        }
295    }
296}
297
298/// One browser row of the support matrix.
299#[derive(Debug, Clone, PartialEq, Eq)]
300pub struct BrowserSupport {
301    /// Browser family (engine-level: the in-tree lanes are engine-simulated).
302    pub browser: &'static str,
303    /// Minimum version line the criteria apply to.
304    pub min_version: &'static str,
305    /// Tier per renderer, in the fixed order dom/canvas/webgl/webgpu.
306    pub renderer_tiers: [SupportTier; 4],
307    /// Pass criteria + fallback expectation.
308    pub criteria: &'static str,
309}
310
311/// The browser support matrix with explicit pass/fail criteria.
312#[must_use]
313pub fn browser_support_matrix() -> Vec<BrowserSupport> {
314    vec![
315        BrowserSupport {
316            browser: "chromium",
317            min_version: "120",
318            renderer_tiers: [
319                SupportTier::Supported,
320                SupportTier::Supported,
321                SupportTier::Supported,
322                SupportTier::Supported,
323            ],
324            criteria: "all conformance + compat lanes green; webgpu is the preferred \
325                       high-performance backend, dom the guaranteed fallback",
326        },
327        BrowserSupport {
328            browser: "firefox",
329            min_version: "121",
330            renderer_tiers: [
331                SupportTier::Supported,
332                SupportTier::Supported,
333                SupportTier::Supported,
334                SupportTier::BestEffort,
335            ],
336            criteria: "webgpu best-effort behind the capability probe; automatic downgrade \
337                       to webgl/canvas must be observable in the option-update events",
338        },
339        BrowserSupport {
340            browser: "webkit_safari",
341            min_version: "17",
342            renderer_tiers: [
343                SupportTier::Supported,
344                SupportTier::Supported,
345                SupportTier::BestEffort,
346                SupportTier::BestEffort,
347            ],
348            criteria: "dom/canvas supported; gpu backends best-effort; IME + clipboard \
349                       policies must pass the a11y/IME matrix on the dom renderer",
350        },
351        BrowserSupport {
352            browser: "other_engines",
353            min_version: "-",
354            renderer_tiers: [
355                SupportTier::BestEffort,
356                SupportTier::BestEffort,
357                SupportTier::Unsupported,
358                SupportTier::Unsupported,
359            ],
360            criteria: "the capability probe must always land the fallback chain on dom; \
361                       a boot failure on ANY engine is release-blocking (boot guarantee)",
362        },
363    ]
364}
365
366/// Deterministic JSON for the support matrix.
367#[must_use]
368pub fn browser_support_matrix_json() -> String {
369    let rows = browser_support_matrix()
370        .iter()
371        .map(|r| {
372            let tiers = r
373                .renderer_tiers
374                .iter()
375                .map(|t| format!("\"{}\"", t.as_str()))
376                .collect::<Vec<_>>()
377                .join(",");
378            format!(
379                "{{\"browser\":\"{}\",\"min_version\":\"{}\",\"renderers\":{{\"order\":[\"dom\",\"canvas\",\"webgl\",\"webgpu\"],\"tiers\":[{tiers}]}},\"criteria\":\"{}\"}}",
380                r.browser,
381                r.min_version,
382                escape_json(r.criteria),
383            )
384        })
385        .collect::<Vec<_>>()
386        .join(",");
387    format!(
388        "{{\"schema\":\"{RELEASE_READINESS_SCHEMA_VERSION}\",\"artifact\":\"browser_support_matrix\",\"rows\":[{rows}]}}"
389    )
390}
391
392// ============================================================================
393// Staged rollout + rollback (.12.3)
394// ============================================================================
395
396/// Progressive rollout stages, in order.
397#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
398pub enum RolloutStage {
399    /// Maintainer-facing dogfood builds.
400    InternalDogfood,
401    /// Opt-in flag for early adopters.
402    OptInFlag,
403    /// Percentage canary of real hosts.
404    CanaryCohort,
405    /// FrankenTermJS is the default terminal.
406    DefaultEnablement,
407}
408
409impl RolloutStage {
410    /// All stages in rollout order.
411    pub const ALL: [RolloutStage; 4] = [
412        RolloutStage::InternalDogfood,
413        RolloutStage::OptInFlag,
414        RolloutStage::CanaryCohort,
415        RolloutStage::DefaultEnablement,
416    ];
417
418    /// Stable wire string.
419    #[must_use]
420    pub const fn as_str(self) -> &'static str {
421        match self {
422            Self::InternalDogfood => "internal_dogfood",
423            Self::OptInFlag => "opt_in_flag",
424            Self::CanaryCohort => "canary_cohort",
425            Self::DefaultEnablement => "default_enablement",
426        }
427    }
428}
429
430/// One stage of the rollout plan.
431#[derive(Debug, Clone, PartialEq, Eq)]
432pub struct RolloutStagePlan {
433    /// The stage.
434    pub stage: RolloutStage,
435    /// What must be true before entering the stage.
436    pub entry_criteria: Vec<&'static str>,
437    /// Automatic rollback triggers while in the stage (telemetry-derived).
438    pub rollback_triggers: Vec<&'static str>,
439    /// Telemetry checkpoints operators watch (JSONL event vocabularies).
440    pub telemetry_checkpoints: Vec<&'static str>,
441}
442
443/// The canonical staged rollout + rollback plan.
444#[must_use]
445pub fn rollout_plan() -> Vec<RolloutStagePlan> {
446    vec![
447        RolloutStagePlan {
448            stage: RolloutStage::InternalDogfood,
449            entry_criteria: vec![
450                "conformance CI gates green (frankenterm-conformance-gates job)",
451                "parity scorecard has no red areas (partial allowed with named risks)",
452            ],
453            rollback_triggers: vec![
454                "any semantic drift classification in the conformance/diff lanes",
455            ],
456            telemetry_checkpoints: vec![
457                "attach.transition timelines (drainAttachTransitionsJsonl)",
458                "adapter_transition/adapter_misuse JSONL (FTUI_SDK_ADAPTER_COMPAT vocabulary)",
459            ],
460        },
461        RolloutStagePlan {
462            stage: RolloutStage::OptInFlag,
463            entry_criteria: vec![
464                "stress/soak campaign executed with documented limits (FTUI_RELEASE_STRESS)",
465                "migration guide + API reference published and cross-linked",
466            ],
467            rollback_triggers: vec![
468                "attach.protocol_error rate above the stress-campaign baseline envelope",
469                "queue.overflow sustained on default buffer policy under real host load",
470            ],
471            telemetry_checkpoints: vec![
472                "SdkErrorKind code rates by class (errors JSONL)",
473                "event-drain latency vs the 16ms cadence recommendation",
474            ],
475        },
476        RolloutStagePlan {
477            stage: RolloutStage::CanaryCohort,
478            entry_criteria: vec![
479                "wasm_packaging_out_of_tree blocker resolved (JS wrapper re-vendored + \
480                 conformance gates re-run against it)",
481                "browser support matrix criteria verified on real supported browsers",
482            ],
483            rollback_triggers: vec![
484                "canary error-rate delta vs control beyond the agreed threshold",
485                "unrecoverable renderer-fallback loops (downgrade chain not settling)",
486            ],
487            telemetry_checkpoints: vec![
488                "per-browser renderer distribution (capability probe outcomes)",
489                "rollout checkpoint events per rehearsal script vocabulary",
490            ],
491        },
492        RolloutStagePlan {
493            stage: RolloutStage::DefaultEnablement,
494            entry_criteria: vec![
495                "go/no-go checklist fully signed off (all machine-checkable items green)",
496                "canary cohort stable for the agreed observation window",
497            ],
498            rollback_triggers: vec![
499                "any release-blocking regression: flip the default back (the opt-out \
500                 path must remain functional through at least one release)",
501            ],
502            telemetry_checkpoints: vec!["aggregate error budget across SdkErrorKind classes"],
503        },
504    ]
505}
506
507/// Deterministic JSON for the rollout plan.
508#[must_use]
509pub fn rollout_plan_json() -> String {
510    let stages = rollout_plan()
511        .iter()
512        .map(|s| {
513            format!(
514                "{{\"stage\":\"{}\",\"entry_criteria\":[{}],\"rollback_triggers\":[{}],\"telemetry_checkpoints\":[{}]}}",
515                s.stage.as_str(),
516                json_str_list(&s.entry_criteria),
517                json_str_list(&s.rollback_triggers),
518                json_str_list(&s.telemetry_checkpoints),
519            )
520        })
521        .collect::<Vec<_>>()
522        .join(",");
523    format!(
524        "{{\"schema\":\"{RELEASE_READINESS_SCHEMA_VERSION}\",\"artifact\":\"rollout_plan\",\"stages\":[{stages}]}}"
525    )
526}
527
528/// Readiness verdict for a stage given the current scorecard: a stage is
529/// ready only when no open blocker gates it or an earlier stage.
530#[must_use]
531pub fn stage_ready(scorecard: &ParityScorecard, stage: RolloutStage) -> bool {
532    scorecard.blockers.iter().all(|b| b.gates_stage > stage)
533}
534
535// ============================================================================
536// Go/no-go checklist (.12.5)
537// ============================================================================
538
539/// Checklist item category.
540#[derive(Debug, Clone, Copy, PartialEq, Eq)]
541pub enum ChecklistCategory {
542    /// Automated test gate (machine-checkable).
543    TestGate,
544    /// Documentation readiness.
545    Docs,
546    /// Human/operational signoff.
547    Operational,
548}
549
550impl ChecklistCategory {
551    /// Stable wire string.
552    #[must_use]
553    pub const fn as_str(self) -> &'static str {
554        match self {
555            Self::TestGate => "test_gate",
556            Self::Docs => "docs",
557            Self::Operational => "operational",
558        }
559    }
560}
561
562/// One go/no-go checklist item.
563#[derive(Debug, Clone, PartialEq, Eq)]
564pub struct ChecklistItem {
565    /// Stable snake_case id.
566    pub id: &'static str,
567    /// Category.
568    pub category: ChecklistCategory,
569    /// What must be verified.
570    pub requirement: &'static str,
571    /// Where the evidence lives (test target, script, doc, or role).
572    pub evidence: &'static str,
573}
574
575/// The final release checklist tying test gates, docs, and signoff.
576#[must_use]
577pub fn go_no_go_checklist() -> Vec<ChecklistItem> {
578    vec![
579        ChecklistItem {
580            id: "conformance_gates_green",
581            category: ChecklistCategory::TestGate,
582            requirement: "conformance/differential/fuzz CI gates green on the release rev",
583            evidence: "ci.yml::frankenterm-conformance-gates",
584        },
585        ChecklistItem {
586            id: "compat_arms_green",
587            category: ChecklistCategory::TestGate,
588            requirement: "every FTUI_*_COMPAT arm green (markers, parser hooks, image, \
589                          ligatures, security/reliability, sdk contract, sdk adapters)",
590            evidence: "scripts/frankenterm_js_release_rehearsal_e2e.sh",
591        },
592        ChecklistItem {
593            id: "stress_campaign_executed",
594            category: ChecklistCategory::TestGate,
595            requirement: "stress/soak campaign run with limits documented and within envelope",
596            evidence: "ftui-web::frankenterm_js_release_stress_e2e",
597        },
598        ChecklistItem {
599            id: "parity_scorecard_no_open_blockers",
600            category: ChecklistCategory::TestGate,
601            requirement: "parity scorecard reports zero open blockers for the target stage",
602            evidence: "ftui-web::release_readiness (parity_scorecard artifact)",
603        },
604        ChecklistItem {
605            id: "docs_aligned",
606            category: ChecklistCategory::Docs,
607            requirement: "contract, API reference, migration guide, and examples lockstep \
608                          tests green (docs cannot drift from runtime)",
609            evidence: "docs/frankenterm-js-sdk-reference.md + lockstep guards",
610        },
611        ChecklistItem {
612            id: "rollout_plan_agreed",
613            category: ChecklistCategory::Operational,
614            requirement: "stage entry criteria, rollback triggers, and telemetry \
615                          checkpoints reviewed by the release owner",
616            evidence: "release_readiness::rollout_plan",
617        },
618        ChecklistItem {
619            id: "rehearsal_signoff_packet",
620            category: ChecklistCategory::Operational,
621            requirement: "release rehearsal executed; signoff packet archived with all \
622                          JSONL evidence and this checklist",
623            evidence: "scripts/frankenterm_js_release_rehearsal_e2e.sh",
624        },
625    ]
626}
627
628/// Deterministic JSON for the checklist.
629#[must_use]
630pub fn go_no_go_checklist_json() -> String {
631    let items = go_no_go_checklist()
632        .iter()
633        .map(|i| {
634            format!(
635                "{{\"id\":\"{}\",\"category\":\"{}\",\"requirement\":\"{}\",\"evidence\":\"{}\"}}",
636                i.id,
637                i.category.as_str(),
638                escape_json(i.requirement),
639                escape_json(i.evidence),
640            )
641        })
642        .collect::<Vec<_>>()
643        .join(",");
644    format!(
645        "{{\"schema\":\"{RELEASE_READINESS_SCHEMA_VERSION}\",\"artifact\":\"go_no_go_checklist\",\"items\":[{items}]}}"
646    )
647}
648
649// ============================================================================
650// Tests
651// ============================================================================
652
653#[cfg(test)]
654mod tests {
655    use super::*;
656
657    #[test]
658    fn scorecard_blockers_and_areas_are_consistent() {
659        let card = ParityScorecard::canonical();
660        assert!(card.areas.len() >= 10, "scorecard must cover the surface");
661        let blocker_ids: Vec<&str> = card.blockers.iter().map(|b| b.id).collect();
662        for area in &card.areas {
663            for id in &area.blocker_ids {
664                assert!(
665                    blocker_ids.contains(id),
666                    "area {} references unknown blocker {id}",
667                    area.id
668                );
669            }
670            assert!(
671                area.evidence.contains("::"),
672                "evidence must name crate::target: {}",
673                area.evidence
674            );
675        }
676        // The packaging blocker is tracked honestly and gates the canary.
677        let blocked = card.blocked_areas();
678        assert!(
679            blocked.iter().any(|a| a.id == "browser_delivery"),
680            "browser delivery must be tracked as blocked while packaging is out-of-tree"
681        );
682    }
683
684    /// Every evidence hook must point at a REAL integration-test target in
685    /// the workspace: a scorecard citing a nonexistent (or wrong-crate)
686    /// suite would make readiness claims nobody can verify.
687    #[test]
688    fn scorecard_evidence_targets_exist_in_the_workspace() {
689        let workspace_crates = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
690            .parent()
691            .expect("crates/ dir");
692        for area in ParityScorecard::canonical().areas {
693            let (krate, target) = area
694                .evidence
695                .split_once("::")
696                .expect("evidence is crate::target");
697            let path = workspace_crates
698                .join(krate)
699                .join("tests")
700                .join(format!("{target}.rs"));
701            assert!(
702                path.is_file(),
703                "area {}: evidence target does not exist: {}",
704                area.id,
705                path.display()
706            );
707        }
708    }
709
710    #[test]
711    fn stage_readiness_respects_blocker_gates() {
712        let card = ParityScorecard::canonical();
713        assert!(stage_ready(&card, RolloutStage::InternalDogfood));
714        assert!(stage_ready(&card, RolloutStage::OptInFlag));
715        assert!(
716            !stage_ready(&card, RolloutStage::CanaryCohort),
717            "canary must be gated by the packaging blocker"
718        );
719        assert!(!stage_ready(&card, RolloutStage::DefaultEnablement));
720
721        // Resolving the blocker opens the later stages.
722        let mut resolved = card.clone();
723        resolved.blockers.clear();
724        assert!(stage_ready(&resolved, RolloutStage::DefaultEnablement));
725    }
726
727    #[test]
728    fn rollout_plan_covers_every_stage_in_order_with_rollback() {
729        let plan = rollout_plan();
730        assert_eq!(plan.len(), RolloutStage::ALL.len());
731        for (idx, stage_plan) in plan.iter().enumerate() {
732            assert_eq!(stage_plan.stage, RolloutStage::ALL[idx], "stage order");
733            assert!(!stage_plan.entry_criteria.is_empty());
734            assert!(
735                !stage_plan.rollback_triggers.is_empty(),
736                "every stage needs rollback triggers: {}",
737                stage_plan.stage.as_str()
738            );
739            assert!(!stage_plan.telemetry_checkpoints.is_empty());
740        }
741    }
742
743    #[test]
744    fn support_matrix_always_lands_on_a_supported_renderer() {
745        for row in browser_support_matrix() {
746            assert_ne!(
747                row.renderer_tiers[0],
748                SupportTier::Unsupported,
749                "{}: the dom fallback must never be unsupported (boot guarantee)",
750                row.browser
751            );
752        }
753    }
754
755    #[test]
756    fn checklist_items_are_unique_and_machine_locatable() {
757        let items = go_no_go_checklist();
758        let mut ids: Vec<&str> = items.iter().map(|i| i.id).collect();
759        let before = ids.len();
760        ids.sort_unstable();
761        ids.dedup();
762        assert_eq!(ids.len(), before, "checklist ids must be unique");
763        assert!(
764            items
765                .iter()
766                .any(|i| i.category == ChecklistCategory::TestGate),
767        );
768        assert!(items.iter().any(|i| i.category == ChecklistCategory::Docs));
769        assert!(
770            items
771                .iter()
772                .any(|i| i.category == ChecklistCategory::Operational),
773        );
774    }
775
776    /// Emits every readiness artifact for the rehearsal script to harvest
777    /// into the signoff packet (`FTUI_RELEASE_READINESS ` JSONL envelope).
778    #[test]
779    fn artifacts_emit_for_signoff_packet() {
780        for artifact in [
781            ParityScorecard::canonical().to_json(),
782            browser_support_matrix_json(),
783            rollout_plan_json(),
784            go_no_go_checklist_json(),
785        ] {
786            println!("FTUI_RELEASE_READINESS {artifact}");
787        }
788    }
789
790    #[test]
791    fn all_artifacts_serialize_deterministically_and_parse() {
792        let artifacts = [
793            ParityScorecard::canonical().to_json(),
794            browser_support_matrix_json(),
795            rollout_plan_json(),
796            go_no_go_checklist_json(),
797        ];
798        let again = [
799            ParityScorecard::canonical().to_json(),
800            browser_support_matrix_json(),
801            rollout_plan_json(),
802            go_no_go_checklist_json(),
803        ];
804        assert_eq!(artifacts, again, "artifacts must be byte-identical");
805        for artifact in &artifacts {
806            let parsed: serde_json::Value =
807                serde_json::from_str(artifact).expect("artifact JSON parses");
808            assert_eq!(
809                parsed["schema"].as_str(),
810                Some(RELEASE_READINESS_SCHEMA_VERSION)
811            );
812            assert!(parsed["artifact"].as_str().is_some());
813        }
814    }
815}