Skip to main content

type_bridge_schema_migration/
generate.rs

1//! Offline desired-state migration generation.
2//!
3//! Generation is the authoring half of the migration engine: the committed
4//! head's verified target schema is the source, the desired schema compiled
5//! from schema sources is the target, and the minimal fact delta between them
6//! becomes the next canonical manifest. Everything derives from the inputs —
7//! no timestamps, no environment — so a clean checkout regenerates identical
8//! bytes.
9
10use 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
43/// Manifest build rejections that only indict the claimed reverse program.
44///
45/// A structural inverse always exists, but it is recorded only when the
46/// verifier accepts it as a real semantic rollback; these codes downgrade the
47/// draft to an irreversible manifest instead of failing generation.
48const 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/// Inputs authoring the next migration for one application lineage.
56#[derive(Clone, Copy, Debug)]
57pub struct MigrationGenerationRequest<'a> {
58    /// Durable application label binding the migration lineage.
59    pub app_label: &'a str,
60    /// Author-supplied descriptive name; the ordinal prefix is allocated.
61    pub base_name: &'a str,
62    /// Exact declared source when history is empty.
63    pub genesis_source: &'a DeclaredSchema,
64    /// Desired schema compiled from the current schema sources.
65    pub desired: &'a DeclaredSchema,
66    /// Managed scope, semantic profile, and available capabilities.
67    pub context: &'a ManagedDeltaContext,
68}
69
70/// Inputs authoring one closed binding-neutral backfill migration.
71#[derive(Clone, Copy, Debug)]
72pub struct BackfillMigrationGenerationRequest<'a> {
73    /// Durable application label binding the migration lineage.
74    pub app_label: &'a str,
75    /// Author-supplied descriptive name; the ordinal prefix is allocated.
76    pub base_name: &'a str,
77    /// Exact declared source when history is empty.
78    pub genesis_source: &'a DeclaredSchema,
79    /// Desired schema compiled from the current schema sources.
80    pub desired: &'a DeclaredSchema,
81    /// Closed, already structurally validated backfill plan.
82    pub plan: &'a AttributeBackfillPlan,
83    /// Managed scope, semantic profile, and available capabilities.
84    pub context: &'a ManagedDeltaContext,
85}
86
87/// Result of one offline generation attempt.
88#[derive(Clone, Debug)]
89pub enum MigrationGenerationOutcome {
90    /// The head target already equals the desired schema.
91    UpToDate,
92    /// A new verified manifest was authored.
93    Generated(Box<GeneratedMigration>),
94}
95
96/// A freshly authored manifest with its exact canonical persistence bytes.
97#[derive(Clone, Debug)]
98pub struct GeneratedMigration {
99    manifest: VerifiedSchemaMigrationManifest,
100    canonical_bytes: Vec<u8>,
101}
102
103impl GeneratedMigration {
104    /// Return the verified manifest.
105    pub const fn manifest(&self) -> &VerifiedSchemaMigrationManifest {
106        &self.manifest
107    }
108
109    /// Return the exact canonical manifest bytes to persist.
110    pub fn canonical_bytes(&self) -> &[u8] {
111        &self.canonical_bytes
112    }
113
114    /// Return the stem-bound canonical file name for this manifest.
115    pub fn file_name(&self) -> String {
116        format!("{}.tbmigration.json", self.manifest.id().name().as_str())
117    }
118
119    /// Return the review-only TypeQL preview file name for this manifest.
120    pub fn preview_file_name(&self) -> String {
121        format!("{}.typeql", self.manifest.id().name().as_str())
122    }
123}
124
125/// Failure rendering a review-only TypeQL preview for a generated manifest.
126#[derive(Clone, Debug)]
127pub enum MigrationPreviewError {
128    /// Verification or replay of the manifest steps failed.
129    Diagnostic(Diagnostic),
130    /// Provider lowering rejected a statement unit.
131    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
157/// Author the next verified migration from the discovered history graph.
158///
159/// The source schema is the sole head's verified target (genesis when the
160/// graph is empty); a multi-head history is refused until an explicit merge
161/// migration joins it. Conditional operations receive verifier-derived
162/// assertion steps; the structural inverse is recorded only when the
163/// verifier accepts it as a real rollback program.
164pub 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
229/// Author one closed backfill against the exact committed history head.
230///
231/// Backfill authoring is deliberately separate from schema-delta generation:
232/// current Split-YAML must already equal the committed head so expand,
233/// backfill, and contract remain independently reviewable migrations.
234pub 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
289/// Render the review-only TypeQL preview of a verified manifest.
290///
291/// The preview replays the manifest steps and lowers every schema delta under
292/// the context's capabilities. Destructive units render without an approval —
293/// the preview is exactly what an operator inspects before granting one —
294/// while classes no approval can execute (backfill, opaque) surface their
295/// gate diagnostic instead of producing a misleading partial preview.
296pub 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(&current, schema_step.delta(), context).map_err(delta_diagnostic)?;
315        let coverage = verify_assertion_coverage(
316            &pending,
317            schema_step.delta(),
318            &current,
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
343/// Acquire the shared canonical-history authoring lock without waiting.
344///
345/// Callers that derive a candidate from the directory must acquire this lock
346/// before re-discovery and retain it through
347/// [`write_generated_migration_under_lock`]. This prevents two different
348/// candidates derived from one stale head from becoming sibling authorities.
349pub 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
361/// Publish a generated manifest while its directory's authoring lock is held.
362///
363/// The lock carries the exact retained directory capability, so a caller
364/// cannot accidentally validate one history and publish into another. An
365/// existing manifest is a conflict, never an overwrite. Both files are
366/// written completely to confined, flushed temporaries and published with
367/// no-replace links, preview first and authority manifest last.
368pub 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    // The advisory directory lock proves no live writer owns this preview;
383    // without a final manifest it is an interrupted, non-authoritative
384    // publication and can be recovered safely.
385    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            // A prior interrupted writer or concurrent identical writer may
421            // already have published the non-authoritative preview. Reuse it
422            // only when its bounded bytes are exact; never unlink another
423            // writer's candidate.
424            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
504/// Publish a completed temporary under its final name without replacing.
505///
506/// A hard link fails when the destination exists, which keeps publication
507/// atomic and conflict-detecting at once; the temporary is removed by the
508/// caller after both publications succeed.
509fn 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
531/// The integrity diagnostic names the failing operation and its
532/// underlying I/O failure so a production operator can distinguish
533/// permissions, exhaustion, and platform quirks without tracing the
534/// filesystem calls.
535fn 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/// Allocate the next ordinal-prefixed name in the lineage's local convention.
544///
545/// Ordinal prefixes are display/allocation conventions, never execution
546/// order; names without a numeric prefix simply do not participate.
547#[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
566/// Author verifier-derived assertion steps followed by the single delta step.
567fn 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        // Only conditional requirements become assertions. Destructive guard
606        // conditions are deliberately omitted: an approved destructive
607        // migration means the data loss is intended, and a NoRows guard would
608        // convert it into refuse-if-populated.
609        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}