pharos_runtime_database/

contract.rs

//! Bounded loading and validation for one app-owned logical database contract.

use std::collections::{BTreeMap, BTreeSet};
use std::path::Path;

use serde::{Deserialize, Deserializer, Serialize};

use crate::operations::{
    AppSchema, DatabaseError, Entity, Field, FieldDefault, FieldType, Identity, IndexKey,
    Migration, SchemaChange, operation_fingerprint, valid_identifier, validate_copy_field,
    validate_field_value, validate_predicate, validate_schema,
};
use serde_json::Value;

/// Builds a typed projection from the app's compiled entity contract.
/// Every requested field must declare its logical type; guesses from SQL storage
/// or field names would let one backend interpret app data differently.
pub fn schema_from_entity_catalog(
    document: &Value,
    app_id: &str,
    requested_entities: &[&str],
) -> Result<AppSchema, DatabaseError> {
    if !valid_identifier(app_id) || requested_entities.is_empty() || requested_entities.len() > 256
    {
        return Err(DatabaseError::InvalidContract);
    }
    let rows = document
        .get("entities")
        .and_then(Value::as_array)
        .ok_or(DatabaseError::InvalidContract)?;
    let mut entities = Vec::with_capacity(requested_entities.len());
    let mut requested = BTreeSet::new();
    for wanted in requested_entities {
        if !valid_identifier(wanted) || !requested.insert(*wanted) {
            return Err(DatabaseError::InvalidContract);
        }
        let row = rows
            .iter()
            .find(|row| row.get("entity_id").and_then(Value::as_str) == Some(*wanted))
            .ok_or(DatabaseError::InvalidContract)?;
        let table = row
            .get("table")
            .and_then(Value::as_str)
            .filter(|name| valid_identifier(name))
            .ok_or(DatabaseError::InvalidContract)?;
        let identity_field = row
            .get("identity_field")
            .and_then(Value::as_str)
            .filter(|name| valid_identifier(name))
            .ok_or(DatabaseError::InvalidContract)?;
        let field_rows = row
            .get("fields")
            .and_then(Value::as_array)
            .ok_or(DatabaseError::InvalidContract)?;
        let mut fields = Vec::with_capacity(field_rows.len());
        for entry in field_rows {
            let name = entry
                .get("field_id")
                .and_then(Value::as_str)
                .filter(|name| valid_identifier(name))
                .ok_or(DatabaseError::InvalidContract)?;
            let kind: FieldType = serde_json::from_value(
                entry
                    .get("field_type")
                    .cloned()
                    .ok_or(DatabaseError::InvalidContract)?,
            )
            .map_err(|_| DatabaseError::InvalidContract)?;
            let nullable = entry
                .get("nullable")
                .and_then(Value::as_bool)
                .unwrap_or(false);
            let max_length = match entry.get("max_length") {
                Some(value) => Some(
                    value
                        .as_u64()
                        .and_then(|number| u32::try_from(number).ok())
                        .ok_or(DatabaseError::InvalidContract)?,
                ),
                None => None,
            };
            let default = entry
                .get("field_default")
                .cloned()
                .map(serde_json::from_value::<FieldDefault>)
                .transpose()
                .map_err(|_| DatabaseError::InvalidContract)?;
            fields.push(Field {
                name: name.to_owned(),
                kind,
                nullable,
                max_length,
                default,
                references: None,
                on_delete: None,
                constraints: Vec::new(),
            });
        }
        let identity = match row.get("identity_kind").and_then(Value::as_str) {
            None | Some("auto_integer") => Identity::AutoInteger(identity_field.to_owned()),
            Some("natural") => Identity::Composite(vec![identity_field.to_owned()]),
            _ => return Err(DatabaseError::InvalidContract),
        };
        let unique = row
            .get("unique_keys")
            .cloned()
            .map(serde_json::from_value::<Vec<Vec<String>>>)
            .transpose()
            .map_err(|_| DatabaseError::InvalidContract)?
            .unwrap_or_default();
        entities.push(Entity {
            name: table.to_owned(),
            identity,
            fields,
            unique,
            indexes: Vec::new(),
            conditional_indexes: Vec::new(),
        });
    }
    let schema = AppSchema {
        app_id: app_id.to_owned(),
        entities,
    };
    validate_schema(&schema)?;
    Ok(schema)
}

/// One backend-neutral app schema and its ordered additive migrations.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AppDataContract {
    pub schema: AppSchema,
    pub migrations: Vec<Migration>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub legacy_adoption: Option<LegacyAdoption>,
}

/// Reidentifies a source copy as a new app without selecting a database vendor.
/// Historical adoption belongs to the original app's populated database and
/// must not authorize a different app's fresh database.
pub fn reidentify_contract(
    contract: &AppDataContract,
    app_id: &str,
) -> Result<AppDataContract, DatabaseError> {
    validate_contract(contract)?;
    if !valid_identifier(app_id) {
        return Err(DatabaseError::InvalidInput);
    }
    if contract.schema.app_id == app_id {
        return Ok(contract.clone());
    }
    let mut renamed = contract.clone();
    renamed.schema.app_id = app_id.to_owned();
    renamed.legacy_adoption = None;
    for migration in &mut renamed.migrations {
        migration.app_id = app_id.to_owned();
        migration.checksum = migration_checksum(app_id, &migration.id, &migration.changes)?;
    }
    validate_contract(&renamed)?;
    Ok(renamed)
}

/// Rewrites string values in a fresh source copy and regenerates its migration
/// checksums. This is an authoring operation, never an applied-ledger update.
pub fn rewrite_source_contract_strings(
    contract: &AppDataContract,
    mut rewrite: impl FnMut(&str) -> String,
) -> Result<AppDataContract, DatabaseError> {
    validate_contract(contract)?;
    let mut value = serde_json::to_value(contract).map_err(|_| DatabaseError::InvalidContract)?;
    rewrite_contract_strings(&mut value, &mut rewrite, 0)?;
    let mut copied: AppDataContract =
        serde_json::from_value(value).map_err(|_| DatabaseError::InvalidContract)?;
    if copied == *contract {
        return Ok(copied);
    }
    // Imported source changes cannot adopt a ledger for the original contract.
    copied.legacy_adoption = None;
    for migration in &mut copied.migrations {
        migration.checksum =
            migration_checksum(&migration.app_id, &migration.id, &migration.changes)?;
    }
    if serde_json::to_vec(&copied)
        .map_err(|_| DatabaseError::InvalidContract)?
        .len()
        > 8 * 1024 * 1024
    {
        return Err(DatabaseError::CapacityExceeded);
    }
    validate_contract(&copied)?;
    Ok(copied)
}

/// Visits bounded JSON values without rewriting field or entity map keys.
fn rewrite_contract_strings(
    value: &mut Value,
    rewrite: &mut impl FnMut(&str) -> String,
    depth: usize,
) -> Result<(), DatabaseError> {
    if depth > 64 {
        return Err(DatabaseError::CapacityExceeded);
    }
    match value {
        Value::String(text) => *text = rewrite(text),
        Value::Array(values) => {
            for value in values {
                rewrite_contract_strings(value, rewrite, depth + 1)?;
            }
        }
        Value::Object(values) => {
            for value in values.values_mut() {
                rewrite_contract_strings(value, rewrite, depth + 1)?;
            }
        }
        _ => {}
    }
    Ok(())
}

/// Historical checksum sets prove populated-database adoption without naming
/// a backend or selecting a physical migration file in an app contract.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LegacyAdoption {
    pub logical_migrations: Vec<String>,
    #[serde(deserialize_with = "deserialize_legacy_ledgers")]
    pub ledgers: Vec<BTreeMap<String, String>>,
}

/// Reads checksum sets from current app contracts and older saved projects.
/// Historical backend labels are discarded; adapters verify physical ledgers.
fn deserialize_legacy_ledgers<'de, D>(
    deserializer: D,
) -> Result<Vec<BTreeMap<String, String>>, D::Error>
where
    D: Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum LedgerInput {
        Sets(Vec<BTreeMap<String, String>>),
        Historical(BTreeMap<String, BTreeMap<String, String>>),
    }
    match LedgerInput::deserialize(deserializer)? {
        LedgerInput::Sets(sets) => Ok(sets),
        LedgerInput::Historical(sets) => {
            if sets.keys().any(|name| !valid_identifier(name)) {
                return Err(serde::de::Error::custom(
                    "invalid historical backend identifier",
                ));
            }
            Ok(sets.into_values().collect())
        }
    }
}

/// Reconstructs the schema at the end of the historical migration prefix.
/// Later logical migrations must not be required in an existing populated database.
pub fn legacy_adoption_schema(
    contract: &AppDataContract,
) -> Result<Option<AppSchema>, DatabaseError> {
    validate_contract(contract)?;
    let Some(adoption) = &contract.legacy_adoption else {
        return Ok(None);
    };
    schema_through_migrations(contract, adoption.logical_migrations.len()).map(Some)
}

/// Replays declaration changes through one migration boundary without exposing future fields.
pub fn schema_through_migrations(
    contract: &AppDataContract,
    count: usize,
) -> Result<AppSchema, DatabaseError> {
    if count == 0 || count > contract.migrations.len() {
        return Err(DatabaseError::InvalidContract);
    }
    let mut staged = BTreeMap::<String, Entity>::new();
    for migration in contract.migrations.iter().take(count) {
        for change in &migration.changes {
            match change {
                SchemaChange::CreateEntity(entity) => {
                    staged.insert(entity.name.clone(), entity.clone());
                }
                SchemaChange::RetireFieldConstraint { .. } => {}
                SchemaChange::ConvertField {
                    entity,
                    previous,
                    field,
                } => {
                    crate::conversion::apply_declaration(
                        staged
                            .get_mut(entity)
                            .ok_or(DatabaseError::InvalidContract)?,
                        previous,
                        field,
                    )?;
                }
                SchemaChange::WidenIntegerToDecimal { entity, field } => {
                    widen_integer_to_decimal(
                        staged
                            .get_mut(entity)
                            .ok_or(DatabaseError::InvalidContract)?,
                        field,
                    )?;
                }
                SchemaChange::AddField { entity, field } => {
                    staged
                        .get_mut(entity)
                        .ok_or(DatabaseError::InvalidContract)?
                        .fields
                        .push(field.clone());
                }
                SchemaChange::PromoteIdentity { entity, field } => {
                    promote_identity(
                        staged
                            .get_mut(entity)
                            .ok_or(DatabaseError::InvalidContract)?,
                        field,
                    )?;
                }
                SchemaChange::AddUnique { entity, fields } => {
                    staged
                        .get_mut(entity)
                        .ok_or(DatabaseError::InvalidContract)?
                        .unique
                        .push(fields.clone());
                }
                SchemaChange::AddIndex { entity, fields } => {
                    staged
                        .get_mut(entity)
                        .ok_or(DatabaseError::InvalidContract)?
                        .indexes
                        .push(fields.clone());
                }
                SchemaChange::AddConditionalIndex { entity, index } => {
                    staged
                        .get_mut(entity)
                        .ok_or(DatabaseError::InvalidContract)?
                        .conditional_indexes
                        .push(index.clone());
                }
                SchemaChange::SeedFrom { .. }
                | SchemaChange::Seed { .. }
                | SchemaChange::Backfill { .. }
                | SchemaChange::DeleteWhere { .. }
                | SchemaChange::CopyJsonRecords { .. }
                | SchemaChange::CopyField { .. } => {}
            }
        }
    }
    let schema = AppSchema {
        app_id: contract.schema.app_id.clone(),
        entities: staged.into_values().collect(),
    };
    validate_schema(&schema)?;
    Ok(schema)
}

/// Checks historical migration evidence before a populated database can be
/// adopted into the logical ledger. A legacy checksum records what actually
/// ran; it is never inferred from the current physical table names.
pub fn verify_legacy_ledger(
    expected: &BTreeMap<String, String>,
    observed: &BTreeMap<String, String>,
) -> Result<(), DatabaseError> {
    if expected.is_empty() || expected.len() > 256 {
        return Err(DatabaseError::InvalidContract);
    }
    for (id, checksum) in expected {
        if !valid_identifier(id)
            || checksum.len() != 64
            || !checksum.bytes().all(|byte| byte.is_ascii_hexdigit())
        {
            return Err(DatabaseError::InvalidContract);
        }
    }
    if !expected.keys().any(|id| observed.contains_key(id)) {
        return Err(DatabaseError::MissingRecord);
    }
    for (id, checksum) in expected {
        match observed.get(id) {
            Some(actual) if actual == checksum => {}
            Some(_) => return Err(DatabaseError::Conflict),
            None => return Err(DatabaseError::Conflict),
        }
    }
    if observed.len() != expected.len() {
        return Err(DatabaseError::Conflict);
    }
    Ok(())
}

fn promote_identity(entity: &mut Entity, name: &str) -> Result<(), DatabaseError> {
    if !valid_identifier(name)
        || entity.identity != Identity::Composite(vec![name.to_owned()])
        || !entity.fields.iter().any(|field| {
            field.name == name
                && field.kind == FieldType::Integer
                && !field.nullable
                && field.default.is_none()
                && field.references.is_none()
                && field.constraints.is_empty()
        })
    {
        return Err(DatabaseError::InvalidContract);
    }
    entity.identity = Identity::AutoInteger(name.to_owned());
    Ok(())
}

/// Allows only a lossless integer-to-decimal change outside keys and relations.
fn widen_integer_to_decimal(entity: &mut Entity, name: &str) -> Result<(), DatabaseError> {
    if entity.identity.fields().contains(&name) {
        return Err(DatabaseError::InvalidContract);
    }
    let field = entity
        .fields
        .iter_mut()
        .find(|field| field.name == name)
        .ok_or(DatabaseError::InvalidContract)?;
    if field.kind != FieldType::Integer || field.references.is_some() {
        return Err(DatabaseError::InvalidContract);
    }
    field.kind = FieldType::Decimal;
    Ok(())
}

/// Computes the source checksum that every adapter must record in its ledger.
pub fn migration_checksum(
    app_id: &str,
    id: &str,
    changes: &[SchemaChange],
) -> Result<String, DatabaseError> {
    if !valid_identifier(app_id) || !valid_identifier(id) || changes.is_empty() {
        return Err(DatabaseError::InvalidContract);
    }
    operation_fingerprint(&(app_id, id, changes))
}

/// Validates one migration before an adapter writes its logical ledger.
pub fn validate_migration(schema: &AppSchema, migration: &Migration) -> Result<(), DatabaseError> {
    validate_schema(schema)?;
    if migration.app_id != schema.app_id
        || !valid_identifier(&migration.id)
        || migration.changes.is_empty()
        || migration.changes.len() > 256
        || migration.checksum
            != migration_checksum(&migration.app_id, &migration.id, &migration.changes)?
    {
        return Err(DatabaseError::InvalidContract);
    }
    Ok(())
}

/// Validates migration identity, source checksums, and entity creation coverage.
pub fn validate_contract(contract: &AppDataContract) -> Result<(), DatabaseError> {
    validate_schema(&contract.schema)?;
    if contract.migrations.is_empty() || contract.migrations.len() > 256 {
        return Err(DatabaseError::InvalidContract);
    }
    if let Some(adoption) = &contract.legacy_adoption {
        if adoption.logical_migrations.is_empty()
            || adoption.logical_migrations.len() > contract.migrations.len()
            || adoption.ledgers.is_empty()
            || adoption.ledgers.len() > 32
            || adoption
                .logical_migrations
                .iter()
                .zip(&contract.migrations)
                .any(|(id, migration)| id != &migration.id)
        {
            return Err(DatabaseError::InvalidContract);
        }
        for expected in &adoption.ledgers {
            verify_legacy_ledger(expected, expected)?;
        }
    }
    let mut migrations = BTreeSet::new();
    let mut staged = BTreeMap::<String, Entity>::new();
    for migration in &contract.migrations {
        if migration.app_id != contract.schema.app_id
            || !valid_identifier(&migration.id)
            || !migrations.insert(&migration.id)
            || migration.changes.is_empty()
            || migration.changes.len() > 256
            || migration.checksum
                != migration_checksum(&migration.app_id, &migration.id, &migration.changes)?
        {
            return Err(DatabaseError::InvalidContract);
        }
        for change in &migration.changes {
            match change {
                SchemaChange::CreateEntity(entity) => {
                    if staged.insert(entity.name.clone(), entity.clone()).is_some()
                        || !contract
                            .schema
                            .entities
                            .iter()
                            .any(|item| item.name == entity.name)
                    {
                        return Err(DatabaseError::InvalidContract);
                    }
                }
                SchemaChange::RetireFieldConstraint { entity, field, .. } => {
                    if !staged.get(entity).is_some_and(|declaration| {
                        declaration.fields.iter().any(|item| item.name == *field)
                    }) {
                        return Err(DatabaseError::InvalidContract);
                    }
                    crate::conversion::normalize_field_change(&contract.schema, change)?;
                }
                SchemaChange::ConvertField {
                    entity,
                    previous,
                    field,
                } => {
                    crate::conversion::apply_declaration(
                        staged
                            .get_mut(entity)
                            .ok_or(DatabaseError::InvalidContract)?,
                        previous,
                        field,
                    )?;
                }
                SchemaChange::WidenIntegerToDecimal { entity, field } => {
                    widen_integer_to_decimal(
                        staged
                            .get_mut(entity)
                            .ok_or(DatabaseError::InvalidContract)?,
                        field,
                    )?;
                }
                SchemaChange::AddField { entity, field } => {
                    let declaration = staged
                        .get_mut(entity)
                        .ok_or(DatabaseError::InvalidContract)?;
                    if declaration
                        .fields
                        .iter()
                        .any(|existing| existing.name == field.name)
                    {
                        return Err(DatabaseError::InvalidContract);
                    }
                    declaration.fields.push(field.clone());
                }
                SchemaChange::PromoteIdentity { entity, field } => {
                    promote_identity(
                        staged
                            .get_mut(entity)
                            .ok_or(DatabaseError::InvalidContract)?,
                        field,
                    )?;
                }
                SchemaChange::AddUnique { entity, fields }
                | SchemaChange::AddIndex { entity, fields } => {
                    let declaration = staged
                        .get_mut(entity)
                        .ok_or(DatabaseError::InvalidContract)?;
                    if fields.is_empty()
                        || fields
                            .iter()
                            .any(|name| !declaration.fields.iter().any(|field| field.name == *name))
                    {
                        return Err(DatabaseError::InvalidContract);
                    }
                    if matches!(change, SchemaChange::AddUnique { .. }) {
                        declaration.unique.push(fields.clone());
                    } else {
                        declaration.indexes.push(fields.clone());
                    }
                }
                SchemaChange::AddConditionalIndex { entity, index } => {
                    let declaration = staged
                        .get_mut(entity)
                        .ok_or(DatabaseError::InvalidContract)?;
                    if index.keys.is_empty()
                        || index.keys.iter().any(|key| {
                            let name = match key {
                                IndexKey::Field(name) | IndexKey::Lowercase(name) => name,
                            };
                            !declaration.fields.iter().any(|field| field.name == *name)
                        })
                    {
                        return Err(DatabaseError::InvalidContract);
                    }
                    if let Some(filter) = &index.filter {
                        validate_predicate(declaration, filter)?;
                    }
                    declaration.conditional_indexes.push(index.clone());
                }
                SchemaChange::SeedFrom { .. } => {
                    crate::seed_from::queries(
                        &AppSchema {
                            app_id: contract.schema.app_id.clone(),
                            entities: staged.values().cloned().collect(),
                        },
                        change,
                    )?;
                }
                SchemaChange::Seed { entity, values } => {
                    let declaration = staged.get(entity).ok_or(DatabaseError::InvalidContract)?;
                    if values.is_empty()
                        || values
                            .keys()
                            .any(|name| !declaration.fields.iter().any(|field| field.name == *name))
                    {
                        return Err(DatabaseError::InvalidContract);
                    }
                    for (name, value) in values {
                        let field = declaration
                            .fields
                            .iter()
                            .find(|field| field.name == *name)
                            .ok_or(DatabaseError::InvalidContract)?;
                        validate_field_value(field, value)
                            .map_err(|_| DatabaseError::InvalidContract)?;
                    }
                }
                SchemaChange::Backfill {
                    entity,
                    filter,
                    values,
                } => {
                    let declaration = staged.get(entity).ok_or(DatabaseError::InvalidContract)?;
                    validate_predicate(declaration, filter)?;
                    if values.is_empty()
                        || values
                            .keys()
                            .any(|name| !declaration.fields.iter().any(|field| field.name == *name))
                    {
                        return Err(DatabaseError::InvalidContract);
                    }
                    for (name, value) in values {
                        let field = declaration
                            .fields
                            .iter()
                            .find(|field| field.name == *name)
                            .ok_or(DatabaseError::InvalidContract)?;
                        validate_field_value(field, value)
                            .map_err(|_| DatabaseError::InvalidContract)?;
                    }
                }
                SchemaChange::DeleteWhere { entity, filter } => {
                    let declaration = staged.get(entity).ok_or(DatabaseError::InvalidContract)?;
                    validate_predicate(declaration, filter)?;
                }
                SchemaChange::CopyJsonRecords {
                    source_entity,
                    source_field,
                    source_filter,
                    section,
                    target_entity,
                    fields,
                } => {
                    let source = staged
                        .get(source_entity)
                        .ok_or(DatabaseError::InvalidContract)?;
                    let target = staged
                        .get(target_entity)
                        .ok_or(DatabaseError::InvalidContract)?;
                    validate_json_record_copy(
                        source,
                        source_field,
                        source_filter,
                        section,
                        target,
                        fields,
                    )?;
                }
                SchemaChange::CopyField {
                    entity,
                    source,
                    target,
                    filter,
                } => {
                    let declaration = staged.get(entity).ok_or(DatabaseError::InvalidContract)?;
                    validate_copy_field(declaration, source, target, filter)?;
                }
            }
        }
    }
    if staged.len() != contract.schema.entities.len()
        || contract
            .schema
            .entities
            .iter()
            .any(|entity| staged.get(&entity.name) != Some(entity))
    {
        return Err(DatabaseError::InvalidContract);
    }
    Ok(())
}

/// Validates historical JSON adoption without selecting a database vendor.
pub fn validate_json_record_copy(
    source: &Entity,
    source_field: &str,
    filter: &crate::operations::Predicate,
    section: &str,
    target: &Entity,
    fields: &[String],
) -> Result<(), DatabaseError> {
    if source.name == target.name
        || !valid_identifier(section)
        || fields.is_empty()
        || fields.len() > 64
        || source
            .fields
            .iter()
            .find(|field| field.name == source_field)
            .is_none_or(|field| !matches!(field.kind, FieldType::Text | FieldType::Json))
    {
        return Err(DatabaseError::InvalidContract);
    }
    validate_predicate(source, filter)?;
    let mut seen = BTreeSet::new();
    for name in fields {
        if !seen.insert(name) || !target.fields.iter().any(|field| field.name == *name) {
            return Err(DatabaseError::InvalidContract);
        }
    }
    if target
        .identity
        .fields()
        .iter()
        .any(|name| !fields.iter().any(|field| field == name))
    {
        return Err(DatabaseError::InvalidContract);
    }
    Ok(())
}

/// Reads one verified app-owned contract without following symlinks or oversized input.
pub fn load_contract(path: &Path, expected_app_id: &str) -> Result<AppDataContract, DatabaseError> {
    let metadata = std::fs::symlink_metadata(path).map_err(|_| DatabaseError::InvalidContract)?;
    if !metadata.file_type().is_file() || metadata.len() == 0 || metadata.len() > 8 * 1024 * 1024 {
        return Err(DatabaseError::InvalidContract);
    }
    let bytes = std::fs::read(path).map_err(|_| DatabaseError::InvalidContract)?;
    if bytes.len() > 8 * 1024 * 1024 {
        return Err(DatabaseError::InvalidContract);
    }
    let contract: AppDataContract =
        serde_json::from_slice(&bytes).map_err(|_| DatabaseError::InvalidContract)?;
    if contract.schema.app_id != expected_app_id {
        return Err(DatabaseError::InvalidContract);
    }
    validate_contract(&contract)?;
    Ok(contract)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Historical adoption checksums have no adapter selector in app contracts.
    #[test]
    fn historical_ledger_sets_are_backend_neutral() {
        let entity = Entity {
            name: "record".to_owned(),
            identity: Identity::AutoInteger("id".to_owned()),
            fields: vec![Field {
                name: "id".to_owned(),
                kind: FieldType::Integer,
                nullable: false,
                max_length: None,
                default: None,
                references: None,
                on_delete: None,
                constraints: Vec::new(),
            }],
            unique: Vec::new(),
            indexes: Vec::new(),
            conditional_indexes: Vec::new(),
        };
        let changes = vec![SchemaChange::CreateEntity(entity.clone())];
        let migration = Migration {
            app_id: "probe".to_owned(),
            id: "create_record".to_owned(),
            checksum: migration_checksum("probe", "create_record", &changes).expect("checksum"),
            changes,
        };
        let mut contract = AppDataContract {
            schema: AppSchema {
                app_id: "probe".to_owned(),
                entities: vec![entity],
            },
            migrations: vec![migration],
            legacy_adoption: Some(LegacyAdoption {
                logical_migrations: vec!["create_record".to_owned()],
                ledgers: vec![BTreeMap::from([("old_record".to_owned(), "a".repeat(64))])],
            }),
        };
        assert_eq!(validate_contract(&contract), Ok(()));
        let historical = serde_json::json!({
            "logical_migrations": ["create_record"],
            "ledgers": {"retired_adapter": {"old_record": "a".repeat(64)}}
        });
        let normalized: LegacyAdoption =
            serde_json::from_value(historical).expect("read historical saved project");
        assert_eq!(
            normalized.ledgers,
            contract.legacy_adoption.as_ref().expect("adoption").ledgers
        );
        let emitted = serde_json::to_value(&normalized).expect("write normalized contract");
        assert!(emitted["ledgers"].is_array());
        contract
            .legacy_adoption
            .as_mut()
            .expect("adoption")
            .ledgers
            .push(BTreeMap::new());
        assert_eq!(
            validate_contract(&contract),
            Err(DatabaseError::InvalidContract)
        );
    }

    #[test]
    fn populated_database_requires_exact_historical_ledger() {
        let expected = BTreeMap::from([
            ("base".to_owned(), "a".repeat(64)),
            ("add_field".to_owned(), "b".repeat(64)),
        ]);
        assert_eq!(verify_legacy_ledger(&expected, &expected), Ok(()));
        let mut missing = expected.clone();
        missing.remove("add_field");
        assert_eq!(
            verify_legacy_ledger(&expected, &missing),
            Err(DatabaseError::Conflict)
        );
        let unrelated = BTreeMap::from([("other_app".to_owned(), "c".repeat(64))]);
        assert_eq!(
            verify_legacy_ledger(&expected, &unrelated),
            Err(DatabaseError::MissingRecord)
        );
        let mut drifted = expected.clone();
        drifted.insert("base".to_owned(), "c".repeat(64));
        assert_eq!(
            verify_legacy_ledger(&expected, &drifted),
            Err(DatabaseError::Conflict)
        );
        let mut newer = expected.clone();
        newer.insert("unknown".to_owned(), "d".repeat(64));
        assert_eq!(
            verify_legacy_ledger(&expected, &newer),
            Err(DatabaseError::Conflict)
        );
    }
}