presolve_compiler/
production_optimization.rs

1//! Phase K entry-only production optimization reservations and policy constants.
2//!
3//! K0 records the immutable policy and diagnostic space without introducing an
4//! optimizer, production artifact, report, or executable behavior.
5
6use std::fmt;
7use std::str::FromStr;
8
9use serde::{Deserialize, Serialize};
10use sha2::{Digest, Sha256};
11
12use crate::ResumeBuildId;
13
14/// A Phase K diagnostic code reserved before optimization products exist.
15#[derive(Clone, Copy, Debug, Eq, PartialEq)]
16pub struct ProductionOptimizationDiagnosticReservation {
17    pub code: &'static str,
18    pub meaning: &'static str,
19}
20
21/// The contiguous public compiler diagnostic range reserved by K0.
22pub const PRODUCTION_OPTIMIZATION_DIAGNOSTIC_RESERVATIONS:
23    [ProductionOptimizationDiagnosticReservation; 16] = [
24    ProductionOptimizationDiagnosticReservation {
25        code: "PSC1112",
26        meaning: "Invalid optimization root",
27    },
28    ProductionOptimizationDiagnosticReservation {
29        code: "PSC1113",
30        meaning: "Invalid program fingerprint",
31    },
32    ProductionOptimizationDiagnosticReservation {
33        code: "PSC1114",
34        meaning: "Unsafe program deduplication",
35    },
36    ProductionOptimizationDiagnosticReservation {
37        code: "PSC1115",
38        meaning: "Invalid constant pool entry",
39    },
40    ProductionOptimizationDiagnosticReservation {
41        code: "PSC1116",
42        meaning: "Invalid shared chunk candidate",
43    },
44    ProductionOptimizationDiagnosticReservation {
45        code: "PSC1117",
46        meaning: "Production chunk cycle",
47    },
48    ProductionOptimizationDiagnosticReservation {
49        code: "PSC1118",
50        meaning: "Invalid runtime ordinal table",
51    },
52    ProductionOptimizationDiagnosticReservation {
53        code: "PSC1119",
54        meaning: "Production artifact mismatch",
55    },
56    ProductionOptimizationDiagnosticReservation {
57        code: "PSC1120",
58        meaning: "Unsafe binding write coalescing",
59    },
60    ProductionOptimizationDiagnosticReservation {
61        code: "PSC1121",
62        meaning: "Missing runtime cleanup",
63    },
64    ProductionOptimizationDiagnosticReservation {
65        code: "PSC1122",
66        meaning: "Invalid runtime cleanup order",
67    },
68    ProductionOptimizationDiagnosticReservation {
69        code: "PSC1123",
70        meaning: "Detached activation target",
71    },
72    ProductionOptimizationDiagnosticReservation {
73        code: "PSC1124",
74        meaning: "Invalid production failure record",
75    },
76    ProductionOptimizationDiagnosticReservation {
77        code: "PSC1125",
78        meaning: "Optimization report mismatch",
79    },
80    ProductionOptimizationDiagnosticReservation {
81        code: "PSC1126",
82        meaning: "Production budget regression",
83    },
84    ProductionOptimizationDiagnosticReservation {
85        code: "PSC1127",
86        meaning: "Production determinism failure",
87    },
88];
89
90/// The K0 integrity range follows the final J21 reservation exactly.
91pub const PRODUCTION_OPTIMIZATION_INTEGRITY_RESERVATION_START: u32 = 1385;
92/// K0 reserves 128 contiguous internal integrity codes, inclusively.
93pub const PRODUCTION_OPTIMIZATION_INTEGRITY_RESERVATION_END: u32 = 1512;
94
95/// The immutable compiler-owned `ProductionOptimizationPolicyV1` constants.
96///
97/// These constants are compiler-owned and are not user configuration.
98pub struct ProductionOptimizationPolicyV1;
99
100impl ProductionOptimizationPolicyV1 {
101    pub const SHARED_CHUNK_MIN_ROOT_COUNT: usize = 2;
102    pub const SHARED_CHUNK_MIN_PROGRAM_COUNT: usize = 1;
103    pub const SHARED_CHUNK_MIN_CANONICAL_BYTES: usize = 192;
104    pub const SHARED_CHUNK_MIN_NET_SAVED_BYTES: usize = 256;
105    pub const SHARED_CHUNK_MAX_DEPENDENCY_DEPTH: usize = 1;
106    pub const INLINE_LITERAL_MAX_UTF8_BYTES: usize = 24;
107    pub const CONSTANT_POOL_MIN_REUSE_COUNT: usize = 2;
108}
109
110/// Parse failure for a Phase K compiler identity.
111#[derive(Clone, Copy, Debug, Eq, PartialEq)]
112pub struct ProductionOptimizationIdentityParseError;
113
114impl fmt::Display for ProductionOptimizationIdentityParseError {
115    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
116        formatter.write_str("invalid production optimization identity")
117    }
118}
119
120impl std::error::Error for ProductionOptimizationIdentityParseError {}
121
122macro_rules! optimization_id {
123    ($name:ident) => {
124        #[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)]
125        #[serde(transparent)]
126        pub struct $name(String);
127
128        impl $name {
129            #[must_use]
130            pub fn as_str(&self) -> &str {
131                &self.0
132            }
133        }
134
135        impl fmt::Display for $name {
136            fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
137                self.0.fmt(formatter)
138            }
139        }
140    };
141}
142
143optimization_id!(OptimizationPolicyId);
144optimization_id!(ExecutableProgramFingerprint);
145optimization_id!(ConstantPoolEntryId);
146optimization_id!(RuntimeTableId);
147optimization_id!(ProductionArtifactId);
148optimization_id!(SharedChunkCandidateId);
149optimization_id!(ProductionChunkId);
150optimization_id!(OptimizationDecisionId);
151optimization_id!(OptimizationReportId);
152optimization_id!(BenchmarkFixtureId);
153optimization_id!(PerformanceBudgetId);
154
155impl OptimizationPolicyId {
156    pub const PRODUCTION_V1: &'static str = "optimization-policy:production-v1";
157
158    #[must_use]
159    pub fn production_v1() -> Self {
160        Self(Self::PRODUCTION_V1.to_string())
161    }
162}
163
164impl FromStr for OptimizationPolicyId {
165    type Err = ProductionOptimizationIdentityParseError;
166
167    fn from_str(value: &str) -> Result<Self, Self::Err> {
168        (value == Self::PRODUCTION_V1)
169            .then(|| Self(value.to_string()))
170            .ok_or(ProductionOptimizationIdentityParseError)
171    }
172}
173
174impl ExecutableProgramFingerprint {
175    #[must_use]
176    pub fn for_canonical_opcode_stream(stream: &[u8]) -> Self {
177        Self(format!("program-fingerprint:{}", canonical_hash(stream)))
178    }
179}
180
181impl ConstantPoolEntryId {
182    #[must_use]
183    pub fn for_canonical_value(type_tag: &str, canonical_value_bytes: &[u8]) -> Option<Self> {
184        canonical_label(type_tag).then(|| {
185            Self(format!(
186                "constant-pool:{type_tag}:{}",
187                canonical_hash(canonical_value_bytes)
188            ))
189        })
190    }
191}
192
193impl RuntimeTableId {
194    #[must_use]
195    pub fn for_artifact_table(artifact_kind: &str, table_kind: &str) -> Option<Self> {
196        (canonical_label(artifact_kind) && canonical_label(table_kind))
197            .then(|| Self(format!("runtime-table:{artifact_kind}:{table_kind}")))
198    }
199}
200
201impl ProductionArtifactId {
202    #[must_use]
203    pub fn for_canonical_packed_bytes(artifact_kind: &str, packed_bytes: &[u8]) -> Option<Self> {
204        canonical_label(artifact_kind).then(|| {
205            Self(format!(
206                "production-artifact:{artifact_kind}:{}",
207                canonical_hash(packed_bytes)
208            ))
209        })
210    }
211}
212
213impl SharedChunkCandidateId {
214    #[must_use]
215    pub fn for_roots_and_programs(
216        roots: &[String],
217        programs: &[ExecutableProgramFingerprint],
218    ) -> Option<Self> {
219        let roots = canonical_sorted(roots)?;
220        let programs =
221            canonical_sorted(&programs.iter().map(ToString::to_string).collect::<Vec<_>>())?;
222        Some(Self(format!(
223            "shared-chunk-candidate:{}",
224            canonical_hash(
225                format!(
226                    "roots\n{}\nprograms\n{}",
227                    roots.join("\n"),
228                    programs.join("\n")
229                )
230                .as_bytes()
231            )
232        )))
233    }
234}
235
236impl ProductionChunkId {
237    /// The stable identity of the single compiler-owned eager runtime module.
238    #[must_use]
239    pub fn eager_runtime_v1() -> Self {
240        Self("production-chunk:eager:runtime-v1".to_string())
241    }
242
243    #[must_use]
244    pub fn for_activation_roots_and_programs(
245        chunk_kind: &str,
246        activation_roots: &[String],
247        programs: &[ExecutableProgramFingerprint],
248    ) -> Option<Self> {
249        let roots = canonical_sorted(activation_roots)?;
250        let programs = canonical_sorted_or_empty(
251            &programs.iter().map(ToString::to_string).collect::<Vec<_>>(),
252        )?;
253        canonical_label(chunk_kind).then(|| {
254            Self(format!(
255                "production-chunk:{chunk_kind}:{}",
256                canonical_hash(
257                    format!(
258                        "roots\n{}\nprograms\n{}",
259                        roots.join("\n"),
260                        programs.join("\n")
261                    )
262                    .as_bytes()
263                )
264            ))
265        })
266    }
267}
268
269impl OptimizationDecisionId {
270    #[must_use]
271    pub fn for_canonical_subject(optimization_kind: &str, subject_id: &str) -> Option<Self> {
272        (canonical_label(optimization_kind) && canonical_subject(subject_id)).then(|| {
273            Self(format!(
274                "optimization-decision:{optimization_kind}:{subject_id}"
275            ))
276        })
277    }
278}
279
280impl OptimizationReportId {
281    #[must_use]
282    pub fn for_resume_build_id(build_id: &ResumeBuildId) -> Self {
283        Self(format!("optimization-report:{build_id}"))
284    }
285}
286
287impl BenchmarkFixtureId {
288    #[must_use]
289    pub fn for_fixture_relative_path(path: &str) -> Option<Self> {
290        canonical_fixture_relative_path(path).then(|| Self(format!("benchmark-fixture:{path}")))
291    }
292}
293
294impl PerformanceBudgetId {
295    #[must_use]
296    pub fn for_metric(metric_name: &str) -> Option<Self> {
297        canonical_label(metric_name).then(|| Self(format!("performance-budget:{metric_name}:v1")))
298    }
299}
300
301macro_rules! prefixed_parse {
302    ($name:ident, $prefix:literal) => {
303        impl FromStr for $name {
304            type Err = ProductionOptimizationIdentityParseError;
305
306            fn from_str(value: &str) -> Result<Self, Self::Err> {
307                value
308                    .strip_prefix($prefix)
309                    .filter(|payload| !payload.is_empty())
310                    .map(|_| Self(value.to_string()))
311                    .ok_or(ProductionOptimizationIdentityParseError)
312            }
313        }
314    };
315}
316
317prefixed_parse!(ExecutableProgramFingerprint, "program-fingerprint:");
318prefixed_parse!(ConstantPoolEntryId, "constant-pool:");
319prefixed_parse!(RuntimeTableId, "runtime-table:");
320prefixed_parse!(ProductionArtifactId, "production-artifact:");
321prefixed_parse!(SharedChunkCandidateId, "shared-chunk-candidate:");
322prefixed_parse!(ProductionChunkId, "production-chunk:");
323prefixed_parse!(OptimizationDecisionId, "optimization-decision:");
324prefixed_parse!(OptimizationReportId, "optimization-report:resume-build:");
325prefixed_parse!(BenchmarkFixtureId, "benchmark-fixture:");
326prefixed_parse!(PerformanceBudgetId, "performance-budget:");
327
328/// Immutable compiler-owned policy product. It is intentionally not a public
329/// artifact in K1 and has no optimizer or runtime consumer.
330#[derive(Clone, Debug, Eq, PartialEq)]
331pub struct ProductionOptimizationPolicy {
332    id: OptimizationPolicyId,
333}
334
335impl ProductionOptimizationPolicy {
336    #[must_use]
337    pub fn production_v1() -> Self {
338        Self {
339            id: OptimizationPolicyId::production_v1(),
340        }
341    }
342
343    #[must_use]
344    pub const fn id(&self) -> &OptimizationPolicyId {
345        &self.id
346    }
347}
348
349fn canonical_hash(bytes: &[u8]) -> String {
350    format!("{:x}", Sha256::digest(bytes))
351}
352
353fn canonical_label(value: &str) -> bool {
354    !value.is_empty()
355        && value.bytes().all(|byte| {
356            byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-' || byte == b'_'
357        })
358}
359
360fn canonical_subject(value: &str) -> bool {
361    !value.is_empty() && !value.contains(['\n', '\r'])
362}
363
364fn canonical_fixture_relative_path(value: &str) -> bool {
365    !value.is_empty()
366        && !value.starts_with('/')
367        && !value.contains('\\')
368        && value
369            .split('/')
370            .all(|segment| !segment.is_empty() && segment != "." && segment != "..")
371}
372
373fn canonical_sorted(values: &[String]) -> Option<Vec<String>> {
374    (!values.is_empty() && values.iter().all(|value| canonical_subject(value)))
375        .then(|| {
376            let mut sorted = values.to_vec();
377            sorted.sort();
378            if sorted.windows(2).any(|pair| pair[0] == pair[1]) {
379                return Vec::new();
380            }
381            sorted
382        })
383        .filter(|values| !values.is_empty())
384}
385
386fn canonical_sorted_or_empty(values: &[String]) -> Option<Vec<String>> {
387    if !values.iter().all(|value| canonical_subject(value)) {
388        return None;
389    }
390    let mut sorted = values.to_vec();
391    sorted.sort();
392    (!sorted.windows(2).any(|pair| pair[0] == pair[1])).then_some(sorted)
393}
394
395#[cfg(test)]
396mod tests {
397    use super::{
398        BenchmarkFixtureId, ConstantPoolEntryId, ExecutableProgramFingerprint,
399        OptimizationDecisionId, OptimizationPolicyId, OptimizationReportId, PerformanceBudgetId,
400        ProductionArtifactId, ProductionChunkId, ProductionOptimizationPolicy,
401        ProductionOptimizationPolicyV1, RuntimeTableId, SharedChunkCandidateId,
402        PRODUCTION_OPTIMIZATION_DIAGNOSTIC_RESERVATIONS,
403        PRODUCTION_OPTIMIZATION_INTEGRITY_RESERVATION_END,
404        PRODUCTION_OPTIMIZATION_INTEGRITY_RESERVATION_START,
405    };
406    use crate::ResumeBuildId;
407    use std::str::FromStr;
408
409    #[test]
410    fn k0_reserves_phase_k_ranges_and_inert_policy_without_products() {
411        let codes = PRODUCTION_OPTIMIZATION_DIAGNOSTIC_RESERVATIONS
412            .iter()
413            .map(|reservation| reservation.code)
414            .collect::<Vec<_>>();
415        assert_eq!(codes.first(), Some(&"PSC1112"));
416        assert_eq!(codes.last(), Some(&"PSC1127"));
417        assert_eq!(codes.len(), 16);
418        assert_eq!(PRODUCTION_OPTIMIZATION_INTEGRITY_RESERVATION_START, 1385);
419        assert_eq!(PRODUCTION_OPTIMIZATION_INTEGRITY_RESERVATION_END, 1512);
420        assert_eq!(
421            PRODUCTION_OPTIMIZATION_INTEGRITY_RESERVATION_END
422                - PRODUCTION_OPTIMIZATION_INTEGRITY_RESERVATION_START
423                + 1,
424            128
425        );
426        assert_eq!(
427            ProductionOptimizationPolicyV1::SHARED_CHUNK_MIN_ROOT_COUNT,
428            2
429        );
430        assert_eq!(
431            ProductionOptimizationPolicyV1::SHARED_CHUNK_MIN_PROGRAM_COUNT,
432            1
433        );
434        assert_eq!(
435            ProductionOptimizationPolicyV1::SHARED_CHUNK_MIN_CANONICAL_BYTES,
436            192
437        );
438        assert_eq!(
439            ProductionOptimizationPolicyV1::SHARED_CHUNK_MIN_NET_SAVED_BYTES,
440            256
441        );
442        assert_eq!(
443            ProductionOptimizationPolicyV1::SHARED_CHUNK_MAX_DEPENDENCY_DEPTH,
444            1
445        );
446        assert_eq!(
447            ProductionOptimizationPolicyV1::INLINE_LITERAL_MAX_UTF8_BYTES,
448            24
449        );
450        assert_eq!(
451            ProductionOptimizationPolicyV1::CONSTANT_POOL_MIN_REUSE_COUNT,
452            2
453        );
454    }
455
456    #[test]
457    fn k1_optimization_identities_are_typed_canonical_and_order_independent() {
458        let policy = ProductionOptimizationPolicy::production_v1();
459        assert_eq!(policy.id(), &OptimizationPolicyId::production_v1());
460        assert_eq!(policy.id().to_string(), "optimization-policy:production-v1");
461        assert_eq!(
462            OptimizationPolicyId::from_str("optimization-policy:production-v1"),
463            Ok(OptimizationPolicyId::production_v1())
464        );
465        assert!(OptimizationPolicyId::from_str("optimization-policy:development-v1").is_err());
466
467        let first =
468            ExecutableProgramFingerprint::for_canonical_opcode_stream(b"opcode\nread-state");
469        let second =
470            ExecutableProgramFingerprint::for_canonical_opcode_stream(b"opcode\nwrite-state");
471        assert_ne!(first, second);
472        assert_ne!(
473            first.to_string(),
474            ConstantPoolEntryId::for_canonical_value("string", b"opcode\nread-state")
475                .expect("canonical constant")
476                .to_string()
477        );
478        assert_eq!(
479            serde_json::from_str::<ExecutableProgramFingerprint>(
480                &serde_json::to_string(&first).expect("serialize fingerprint")
481            )
482            .expect("deserialize fingerprint"),
483            first
484        );
485
486        let roots = vec![
487            "resume-boundary:z".to_string(),
488            "resume-boundary:a".to_string(),
489        ];
490        let reversed_roots = vec![
491            "resume-boundary:a".to_string(),
492            "resume-boundary:z".to_string(),
493        ];
494        let programs = vec![second.clone(), first.clone()];
495        let reversed_programs = vec![first.clone(), second.clone()];
496        assert_eq!(
497            SharedChunkCandidateId::for_roots_and_programs(&roots, &programs),
498            SharedChunkCandidateId::for_roots_and_programs(&reversed_roots, &reversed_programs)
499        );
500        assert_eq!(
501            ProductionChunkId::for_activation_roots_and_programs("shared", &roots, &programs),
502            ProductionChunkId::for_activation_roots_and_programs(
503                "shared",
504                &reversed_roots,
505                &reversed_programs
506            )
507        );
508        assert!(SharedChunkCandidateId::for_roots_and_programs(
509            &["duplicate".to_string(), "duplicate".to_string()],
510            std::slice::from_ref(&first)
511        )
512        .is_none());
513
514        assert!(RuntimeTableId::for_artifact_table("production_runtime", "anchors").is_some());
515        assert!(RuntimeTableId::for_artifact_table("ProductionRuntime", "anchors").is_none());
516        assert!(
517            ProductionArtifactId::for_canonical_packed_bytes("production_runtime", b"packed")
518                .is_some()
519        );
520        assert!(OptimizationDecisionId::for_canonical_subject(
521            "deduplication",
522            "program-fingerprint:abc"
523        )
524        .is_some());
525        assert!(BenchmarkFixtureId::for_fixture_relative_path("fixtures/k/fixture.tsx").is_some());
526        assert!(BenchmarkFixtureId::for_fixture_relative_path("/host/fixture.tsx").is_none());
527        assert!(BenchmarkFixtureId::for_fixture_relative_path("fixtures/../fixture.tsx").is_none());
528        assert_eq!(
529            PerformanceBudgetId::for_metric("runtime_bytes")
530                .expect("metric")
531                .to_string(),
532            "performance-budget:runtime_bytes:v1"
533        );
534        assert_eq!(
535            OptimizationReportId::for_resume_build_id(&ResumeBuildId::for_public_inputs(
536                "canonical-inputs"
537            ))
538            .to_string(),
539            format!(
540                "optimization-report:{}",
541                ResumeBuildId::for_public_inputs("canonical-inputs")
542            )
543        );
544    }
545}
presolve_compiler/production_optimization.rs

presolve_compiler/
production_optimization.rs
