1use std::error::Error;
11use std::fmt;
12use std::io::{Read as _, Write};
13use std::path::PathBuf;
14
15use type_bridge_contract::diagnostic::{Diagnostic, DiagnosticCategory, DiagnosticCode};
16use type_bridge_contract::limits::StructuralLimits;
17use type_bridge_contract::migration::{
18 MigrationId, MigrationStep, MigrationStepId, SchemaDeltaStep,
19};
20use type_bridge_contract::migration_assertion::AssertionExpectation;
21use type_bridge_contract::migration_backfill::AttributeBackfillPlan;
22use type_bridge_contract::schema::{DeclaredSchema, SchemaDelta};
23use type_bridge_query::{MigrationAssertionValidationContext, lower_condition_to_plan};
24use type_bridge_schema::{
25 ManagedDeltaContext, SafetyClass, SafetyConditionDomainIndex, SafetyDerivationProfile,
26 apply_delta, derive_safety_conditions_with_domain_index, diff_managed, inverse_delta,
27 managed_schema_state, resolve,
28};
29
30use crate::history::MigrationHistoryGraph;
31use crate::lowering::{
32 SchemaFactCatalog, SchemaLoweringBinding, SchemaLoweringDiagnostic,
33 lower_schema_delta_with_verified_assertions,
34};
35use crate::manifest::{
36 SchemaMigrationDraft, VerifiedSchemaMigrationManifest, build_verified_manifest,
37 delta_diagnostic, encode_verified_manifest, verify_assertion_coverage,
38};
39use crate::profile::lowering_profile_binding;
40use crate::{MigrationAuthoringLock, MigrationDirectory};
41use type_bridge_contract::managed_scope::SemanticProfileBinding;
42
43const REVERSE_REJECTION_CODES: [&str; 4] = [
49 "migration_manifest_reverse_unresolved_safety",
50 "migration_manifest_reverse_requires_assertions",
51 "migration_manifest_inverse_replay_mismatch",
52 "migration_manifest_inverse_plan_invalid",
53];
54
55#[derive(Clone, Copy, Debug)]
57pub struct MigrationGenerationRequest<'a> {
58 pub app_label: &'a str,
60 pub base_name: &'a str,
62 pub genesis_source: &'a DeclaredSchema,
64 pub desired: &'a DeclaredSchema,
66 pub context: &'a ManagedDeltaContext,
68}
69
70#[derive(Clone, Copy, Debug)]
72pub struct BackfillMigrationGenerationRequest<'a> {
73 pub app_label: &'a str,
75 pub base_name: &'a str,
77 pub genesis_source: &'a DeclaredSchema,
79 pub desired: &'a DeclaredSchema,
81 pub plan: &'a AttributeBackfillPlan,
83 pub context: &'a ManagedDeltaContext,
85}
86
87#[derive(Clone, Debug)]
89pub enum MigrationGenerationOutcome {
90 UpToDate,
92 Generated(Box<GeneratedMigration>),
94}
95
96#[derive(Clone, Debug)]
98pub struct GeneratedMigration {
99 manifest: VerifiedSchemaMigrationManifest,
100 canonical_bytes: Vec<u8>,
101}
102
103impl GeneratedMigration {
104 pub const fn manifest(&self) -> &VerifiedSchemaMigrationManifest {
106 &self.manifest
107 }
108
109 pub fn canonical_bytes(&self) -> &[u8] {
111 &self.canonical_bytes
112 }
113
114 pub fn file_name(&self) -> String {
116 format!("{}.tbmigration.json", self.manifest.id().name().as_str())
117 }
118
119 pub fn preview_file_name(&self) -> String {
121 format!("{}.typeql", self.manifest.id().name().as_str())
122 }
123}
124
125#[derive(Clone, Debug)]
127pub enum MigrationPreviewError {
128 Diagnostic(Diagnostic),
130 Lowering(SchemaLoweringDiagnostic),
132}
133
134impl fmt::Display for MigrationPreviewError {
135 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
136 match self {
137 Self::Diagnostic(diagnostic) => diagnostic.fmt(formatter),
138 Self::Lowering(diagnostic) => diagnostic.fmt(formatter),
139 }
140 }
141}
142
143impl Error for MigrationPreviewError {}
144
145impl From<Diagnostic> for MigrationPreviewError {
146 fn from(value: Diagnostic) -> Self {
147 Self::Diagnostic(value)
148 }
149}
150
151impl From<SchemaLoweringDiagnostic> for MigrationPreviewError {
152 fn from(value: SchemaLoweringDiagnostic) -> Self {
153 Self::Lowering(value)
154 }
155}
156
157pub fn generate_next_migration(
165 graph: &MigrationHistoryGraph,
166 request: &MigrationGenerationRequest<'_>,
167) -> Result<MigrationGenerationOutcome, Diagnostic> {
168 for (id, _) in graph.manifests() {
169 if id.app_label().as_str() != request.app_label {
170 return Err(failure(
171 DiagnosticCategory::InvalidContract,
172 "migration_generation_foreign_app_label",
173 "history contains a migration from a different application lineage",
174 ));
175 }
176 }
177
178 let (source, parents) = match graph.default_head()? {
179 None => (request.genesis_source, Vec::new()),
180 Some(head) => (
181 graph
182 .manifest(head)
183 .expect("a graph head is always a graph member")
184 .target_schema(),
185 vec![head.clone()],
186 ),
187 };
188
189 let source_state = managed_schema_state(source, request.context).map_err(delta_diagnostic)?;
190 let desired_state =
191 managed_schema_state(request.desired, request.context).map_err(delta_diagnostic)?;
192 if source_state == desired_state {
193 return Ok(MigrationGenerationOutcome::UpToDate);
194 }
195 let delta = diff_managed(source, request.desired, request.context).map_err(delta_diagnostic)?;
196
197 let id = MigrationId::new(
198 request.app_label,
199 allocate_migration_name(graph, request.base_name),
200 )?;
201 if graph.manifest(&id).is_some() {
202 return Err(failure(
203 DiagnosticCategory::InvalidContract,
204 "migration_generation_duplicate_name",
205 "allocated migration identity already exists in verified history",
206 ));
207 }
208
209 let steps = author_steps(&delta, source, request.desired, request.context, true)?;
210 let draft = SchemaMigrationDraft::new(id.clone(), parents.clone(), steps)?;
211 let manifest = match build_verified_manifest(draft, (source, request.context)) {
212 Ok(manifest) => manifest,
213 Err(diagnostic) if REVERSE_REJECTION_CODES.contains(&diagnostic.code().as_str()) => {
214 let steps = author_steps(&delta, source, request.desired, request.context, false)?;
215 let draft = SchemaMigrationDraft::new(id, parents, steps)?;
216 build_verified_manifest(draft, (source, request.context))?
217 }
218 Err(diagnostic) => return Err(diagnostic),
219 };
220 let canonical_bytes = encode_verified_manifest(&manifest)?;
221 Ok(MigrationGenerationOutcome::Generated(Box::new(
222 GeneratedMigration {
223 manifest,
224 canonical_bytes,
225 },
226 )))
227}
228
229pub fn generate_backfill_migration(
235 graph: &MigrationHistoryGraph,
236 request: &BackfillMigrationGenerationRequest<'_>,
237) -> Result<GeneratedMigration, Diagnostic> {
238 for (id, _) in graph.manifests() {
239 if id.app_label().as_str() != request.app_label {
240 return Err(failure(
241 DiagnosticCategory::InvalidContract,
242 "migration_generation_foreign_app_label",
243 "history contains a migration from a different application lineage",
244 ));
245 }
246 }
247 let (source, parents) = match graph.default_head()? {
248 None => (request.genesis_source, Vec::new()),
249 Some(head) => (
250 graph
251 .manifest(head)
252 .expect("a graph head is always a graph member")
253 .target_schema(),
254 vec![head.clone()],
255 ),
256 };
257 let source_state = managed_schema_state(source, request.context).map_err(delta_diagnostic)?;
258 let desired_state =
259 managed_schema_state(request.desired, request.context).map_err(delta_diagnostic)?;
260 if source_state != desired_state {
261 return Err(failure(
262 DiagnosticCategory::InvalidContract,
263 "migration_backfill_generation_schema_drift",
264 "backfill authoring requires current Split-YAML to equal the committed head",
265 ));
266 }
267
268 let id = MigrationId::new(
269 request.app_label,
270 allocate_migration_name(graph, request.base_name),
271 )?;
272 if graph.manifest(&id).is_some() {
273 return Err(failure(
274 DiagnosticCategory::InvalidContract,
275 "migration_generation_duplicate_name",
276 "allocated migration identity already exists in verified history",
277 ));
278 }
279 let step = MigrationStep::backfill(MigrationStepId::new("backfill")?, request.plan.clone())?;
280 let draft = SchemaMigrationDraft::new(id, parents, vec![step])?;
281 let manifest = build_verified_manifest(draft, (source, request.context))?;
282 let canonical_bytes = encode_verified_manifest(&manifest)?;
283 Ok(GeneratedMigration {
284 manifest,
285 canonical_bytes,
286 })
287}
288
289pub fn render_migration_preview(
297 manifest: &VerifiedSchemaMigrationManifest,
298 context: &ManagedDeltaContext,
299) -> Result<String, MigrationPreviewError> {
300 let binding = SchemaLoweringBinding::for_context(context)?;
301 let safety_profile = SafetyDerivationProfile::new(
302 manifest.semantic_profile().clone(),
303 manifest.lowering_profile().clone(),
304 )?;
305 let mut current = manifest.source_schema().clone();
306 let mut pending = Vec::new();
307 let mut queries = Vec::new();
308 for step in manifest.steps() {
309 let Some(schema_step) = step.as_schema_delta() else {
310 pending.push(step);
311 continue;
312 };
313 let target =
314 apply_delta(¤t, schema_step.delta(), context).map_err(delta_diagnostic)?;
315 let coverage = verify_assertion_coverage(
316 &pending,
317 schema_step.delta(),
318 ¤t,
319 &target,
320 &safety_profile,
321 )?;
322 pending.clear();
323 let source_catalog = SchemaFactCatalog::new(current.facts().cloned())?;
324 let target_catalog = SchemaFactCatalog::new(target.facts().cloned())?;
325 let lowering = lower_schema_delta_with_verified_assertions(
326 schema_step.delta(),
327 &source_catalog,
328 &target_catalog,
329 &binding,
330 coverage.discharged_operation_indices(),
331 true,
332 )?;
333 for unit in lowering.units() {
334 for statement in unit.statements() {
335 queries.push(statement.query().to_owned());
336 }
337 }
338 current = target;
339 }
340 Ok(format!("{}\n", queries.join("\n\n")))
341}
342
343pub fn try_acquire_migration_authoring_lock(
350 directory: &MigrationDirectory,
351) -> Result<MigrationAuthoringLock<'_>, Diagnostic> {
352 directory.try_acquire_authoring_lock().map_err(|error| {
353 if error.kind() == std::io::ErrorKind::WouldBlock {
354 write_conflict()
355 } else {
356 write_failed("authoring lock acquisition", &error)
357 }
358 })
359}
360
361pub fn write_generated_migration_under_lock(
369 lock: &MigrationAuthoringLock<'_>,
370 generated: &GeneratedMigration,
371 preview: &str,
372) -> Result<PathBuf, Diagnostic> {
373 let directory = lock.directory;
374 let manifest_name = generated.file_name();
375 let preview_name = generated.preview_file_name();
376 if directory
377 .entry_exists(manifest_name.as_ref())
378 .map_err(|error| write_failed("manifest presence probe", &error))?
379 {
380 return Err(write_conflict());
381 }
382 if directory
386 .entry_exists(preview_name.as_ref())
387 .map_err(|error| write_failed("preview presence probe", &error))?
388 {
389 directory
390 .remove_file(preview_name.as_ref())
391 .map_err(|error| write_failed("interrupted preview recovery", &error))?;
392 }
393 let manifest_temp = write_unique_temporary(
394 directory,
395 &generated.file_name(),
396 generated.canonical_bytes(),
397 )?;
398 let preview_temp = match write_unique_temporary(
399 directory,
400 &generated.preview_file_name(),
401 preview.as_bytes(),
402 ) {
403 Ok(path) => path,
404 Err(error) => {
405 let _ = directory.remove_file(manifest_temp.as_ref());
406 return Err(error);
407 }
408 };
409 let cleanup = |published_preview: bool| {
410 let _ = directory.remove_file(manifest_temp.as_ref());
411 let _ = directory.remove_file(preview_temp.as_ref());
412 if published_preview {
413 let _ = directory.remove_file(preview_name.as_ref());
414 }
415 };
416
417 let published_preview = match publish_no_replace(directory, &preview_temp, &preview_name) {
418 Ok(()) => true,
419 Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
420 match read_existing_preview(directory, &preview_name) {
425 Ok(existing) if existing == preview.as_bytes() => false,
426 _ => {
427 cleanup(false);
428 return Err(write_conflict());
429 }
430 }
431 }
432 Err(error) => {
433 cleanup(false);
434 return Err(write_failed("preview publication link", &error));
435 }
436 };
437 if let Err(error) = publish_no_replace(directory, &manifest_temp, &manifest_name) {
438 cleanup(published_preview);
439 return Err(if error.kind() == std::io::ErrorKind::AlreadyExists {
440 write_conflict()
441 } else {
442 write_failed("manifest publication link", &error)
443 });
444 }
445 if let Err(error) = sync_authoring_directory(directory) {
446 let _ = directory.remove_file(manifest_temp.as_ref());
447 let _ = directory.remove_file(preview_temp.as_ref());
448 return Err(error);
449 }
450 let _ = directory.remove_file(manifest_temp.as_ref());
451 let _ = directory.remove_file(preview_temp.as_ref());
452 sync_authoring_directory(directory)?;
453 Ok(PathBuf::from(manifest_name))
454}
455
456fn read_existing_preview(directory: &MigrationDirectory, name: &str) -> std::io::Result<Vec<u8>> {
457 let limit = type_bridge_contract::limits::MAX_CANONICAL_BYTES;
458 let file = directory.open_regular_readonly(name.as_ref())?;
459 let mut bytes = Vec::new();
460 file.take(u64::try_from(limit).unwrap_or(u64::MAX).saturating_add(1))
461 .read_to_end(&mut bytes)?;
462 if bytes.len() > limit {
463 return Err(std::io::Error::other(
464 "migration preview exceeds byte ceiling",
465 ));
466 }
467 Ok(bytes)
468}
469
470fn write_unique_temporary(
471 directory: &MigrationDirectory,
472 final_name: &str,
473 bytes: &[u8],
474) -> Result<String, Diagnostic> {
475 use std::sync::atomic::{AtomicU64, Ordering};
476 static NEXT_TEMPORARY: AtomicU64 = AtomicU64::new(1);
477
478 for attempt in 0..128_u64 {
479 let nonce = NEXT_TEMPORARY.fetch_add(1, Ordering::Relaxed);
480 let name = format!(
481 ".{final_name}.{}.{}.{}.tmp",
482 std::process::id(),
483 nonce,
484 attempt
485 );
486 match directory.create_new(name.as_ref()) {
487 Ok(mut file) => {
488 if let Err(error) = file.write_all(bytes).and_then(|()| file.sync_all()) {
489 let _ = directory.remove_file(name.as_ref());
490 return Err(write_failed("temporary write", &error));
491 }
492 return Ok(name);
493 }
494 Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
495 Err(error) => return Err(write_failed("temporary creation", &error)),
496 }
497 }
498 Err(write_failed(
499 "temporary name allocation",
500 &std::io::Error::other("temporary name allocation exhausted"),
501 ))
502}
503
504fn publish_no_replace(
510 directory: &MigrationDirectory,
511 temporary: &str,
512 target: &str,
513) -> std::io::Result<()> {
514 directory.hard_link(temporary.as_ref(), target.as_ref())
515}
516
517fn sync_authoring_directory(directory: &MigrationDirectory) -> Result<(), Diagnostic> {
518 directory
519 .sync_all()
520 .map_err(|error| write_failed("directory sync", &error))
521}
522
523fn write_conflict() -> Diagnostic {
524 failure(
525 DiagnosticCategory::InvalidContract,
526 "migration_generation_write_conflict",
527 "generated migration file already exists in the target directory",
528 )
529}
530
531fn write_failed(operation: &'static str, error: &std::io::Error) -> Diagnostic {
536 failure(
537 DiagnosticCategory::Integrity,
538 "migration_generation_write_failed",
539 format!("generated migration file could not be created: {operation}: {error}"),
540 )
541}
542
543#[must_use]
548pub fn allocate_migration_name(graph: &MigrationHistoryGraph, base_name: &str) -> String {
549 let next = graph
550 .manifests()
551 .filter_map(|(id, _)| leading_ordinal(id.name().as_str()))
552 .max()
553 .unwrap_or(0)
554 .saturating_add(1);
555 format!("{next:04}_{base_name}")
556}
557
558fn leading_ordinal(name: &str) -> Option<u64> {
559 let (digits, _) = name.split_once('_')?;
560 if digits.is_empty() || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
561 return None;
562 }
563 digits.parse().ok()
564}
565
566fn author_steps(
568 delta: &SchemaDelta,
569 source: &DeclaredSchema,
570 target: &DeclaredSchema,
571 context: &ManagedDeltaContext,
572 with_reverse: bool,
573) -> Result<Vec<MigrationStep>, Diagnostic> {
574 let safety_profile = SafetyDerivationProfile::new(
575 SemanticProfileBinding::resolve(context.semantic_profile().clone())?,
576 lowering_profile_binding(context.semantic_profile())?,
577 )?;
578 let resolved = resolve(source, context.semantic_profile()).map_err(|diagnostics| {
579 diagnostics
580 .iter()
581 .next()
582 .map(|diagnostic| diagnostic.diagnostic().clone())
583 .unwrap_or_else(|| {
584 failure(
585 DiagnosticCategory::Integrity,
586 "migration_generation_resolution_failed",
587 "assertion source resolution failed without a diagnostic",
588 )
589 })
590 })?;
591 let source_state = managed_schema_state(source, context).map_err(delta_diagnostic)?;
592 let validation_context = MigrationAssertionValidationContext::new(&resolved, &source_state);
593
594 let mut steps = Vec::new();
595 let domain = SafetyConditionDomainIndex::new(source, target);
596 for (ordinal, operation) in delta.operations().iter().enumerate() {
597 let derived = derive_safety_conditions_with_domain_index(
598 ordinal,
599 operation,
600 source,
601 target,
602 &safety_profile,
603 &domain,
604 )?;
605 let required = derived
610 .conditions()
611 .iter()
612 .filter(|condition| condition.policy() == SafetyClass::Conditional);
613 for (index, condition) in required.enumerate() {
614 let validated = lower_condition_to_plan(
615 condition,
616 &validation_context,
617 StructuralLimits::CANONICAL,
618 )?;
619 steps.push(MigrationStep::assertion(
620 MigrationStepId::new(format!("assert-{ordinal}-{index}"))?,
621 validated.plan().clone(),
622 AssertionExpectation::NoRows,
623 )?);
624 }
625 }
626 let reverse = if with_reverse {
627 Some(inverse_delta(delta).map_err(delta_diagnostic)?)
628 } else {
629 None
630 };
631 steps.push(MigrationStep::from(SchemaDeltaStep::new(
632 MigrationStepId::new("schema-delta")?,
633 delta.clone(),
634 reverse,
635 )?));
636 Ok(steps)
637}
638
639fn failure(
640 category: DiagnosticCategory,
641 code: &'static str,
642 message: impl Into<String>,
643) -> Diagnostic {
644 Diagnostic::new(
645 category,
646 DiagnosticCode::new(code).expect("static generation diagnostic code is canonical"),
647 message,
648 )
649}