1use core::fmt;
20
21pub 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub enum ParityStatus {
53 Full,
55 Partial,
57 DivergentByDesign,
60}
61
62impl ParityStatus {
63 #[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#[derive(Debug, Clone, PartialEq, Eq)]
82pub struct Blocker {
83 pub id: &'static str,
85 pub summary: &'static str,
87 pub gates_stage: RolloutStage,
90}
91
92#[derive(Debug, Clone, PartialEq, Eq)]
94pub struct ParityArea {
95 pub id: &'static str,
97 pub surface: &'static str,
99 pub status: ParityStatus,
101 pub evidence: &'static str,
103 pub blocker_ids: Vec<&'static str>,
105 pub risks: Vec<&'static str>,
107}
108
109#[derive(Debug, Clone)]
112pub struct ParityScorecard {
113 pub areas: Vec<ParityArea>,
115 pub blockers: Vec<Blocker>,
117}
118
119impl ParityScorecard {
120 #[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 #[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 #[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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
275pub enum SupportTier {
276 Supported,
278 BestEffort,
281 Unsupported,
284}
285
286impl SupportTier {
287 #[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#[derive(Debug, Clone, PartialEq, Eq)]
300pub struct BrowserSupport {
301 pub browser: &'static str,
303 pub min_version: &'static str,
305 pub renderer_tiers: [SupportTier; 4],
307 pub criteria: &'static str,
309}
310
311#[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#[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#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
398pub enum RolloutStage {
399 InternalDogfood,
401 OptInFlag,
403 CanaryCohort,
405 DefaultEnablement,
407}
408
409impl RolloutStage {
410 pub const ALL: [RolloutStage; 4] = [
412 RolloutStage::InternalDogfood,
413 RolloutStage::OptInFlag,
414 RolloutStage::CanaryCohort,
415 RolloutStage::DefaultEnablement,
416 ];
417
418 #[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#[derive(Debug, Clone, PartialEq, Eq)]
432pub struct RolloutStagePlan {
433 pub stage: RolloutStage,
435 pub entry_criteria: Vec<&'static str>,
437 pub rollback_triggers: Vec<&'static str>,
439 pub telemetry_checkpoints: Vec<&'static str>,
441}
442
443#[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#[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#[must_use]
531pub fn stage_ready(scorecard: &ParityScorecard, stage: RolloutStage) -> bool {
532 scorecard.blockers.iter().all(|b| b.gates_stage > stage)
533}
534
535#[derive(Debug, Clone, Copy, PartialEq, Eq)]
541pub enum ChecklistCategory {
542 TestGate,
544 Docs,
546 Operational,
548}
549
550impl ChecklistCategory {
551 #[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#[derive(Debug, Clone, PartialEq, Eq)]
564pub struct ChecklistItem {
565 pub id: &'static str,
567 pub category: ChecklistCategory,
569 pub requirement: &'static str,
571 pub evidence: &'static str,
573}
574
575#[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#[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#[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 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 #[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 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 #[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}