IcyDB Model

Application-model authoring, validation, and code generation for IcyDB.

This package owns the host-side declaration graph, reusable application types, validators and normalizers, and lowering into the bounded icydb-schema proposal contract. It does not own accepted schema, storage, planning, execution, or recovery authority.

Schema-only consumers depend on this package without depending on the IcyDB database runtime. Runtime-enabled consumers normally use the same surface through icydb::model, so their manifest names only the public icydb facade. Generated typed adapters are selected by the facade's entity/record macros. Direct model macros remain schema-only even when a runtime dependency is present; runtime consumers must import those macros from icydb::model.

Runtime-enabled entity fields and record members also receive schema-authored FieldRef constants, and entities implement EntitySource. The collision-safe source spelling is <Entity as icydb::traits::EntitySource>::ENTITY. They remove downstream string vocabularies but remain proposal/model convenience: accepted schema snapshots alone decide whether the referenced source is current.

Native declaration collection, build, node, fragment and graph errors require the explicit build Cargo feature. Without it, declarations retain their Rust types, typed adapter contracts, normalization and validation, without global registration or the source generator. Shared model libraries forward build to all reused model declarations; canister build dependencies opt in. This feature is host-only and does not establish runtime schema authority.

The three behavior families are intentionally separate:

• durable rules are bounded proposal metadata that become accepted root-field-plus-nominal-type constraints and are enforced by IcyDB across direct, nested, repeated, and finite recursive occurrences;
• validators are explicitly invoked Rust application checks; and
• normalizers are explicitly invoked Rust application transformations.

Generated adapters never execute validators or normalizers implicitly, and the database runtime never loads the authored model as enforcement authority.

Durable Rules

Durable rules use one closed typed operation with named operands:

#[newtype(
    item(prim = "Text", unbounded),
    ty(rule(
        name = "length",
        length_range_inclusive(min = 1, max = 40)
    ))
)]
pub struct DisplayName {}

The model compiler instantiates that rule for every persisted root field that can reach DisplayName. Proposal lowering then replaces the authored rule with an accepted targeted constraint. Typed, structural, SQL, batch, integrity, and recovery paths use the accepted snapshot; they never load this Rust declaration as runtime authority.

The complete operation grammar is documented in the icydb-model-macros README.

Explicit Application Behavior

Normalization and validation run only when application code asks for them:

use icydb_model::{NormalizeAndValidate as _, normalize, validate};
use icydb_model::{base::types::web::MimeType, visitor::VisitorError};

fn prepare_explicitly(mut value: MimeType) -> Result<MimeType, VisitorError> {
    normalize(&mut value)?;
    validate(&value)?;
    Ok(value)
}

fn prepare_conveniently(value: MimeType) -> Result<MimeType, VisitorError> {
    value.normalize_and_validate()
}

Direct validate checks the supplied value without normalizing it first. The consuming convenience always normalizes before validation. Neither operation persists behavior or changes database admission.

Artifact And Storage Boundaries

Model generation embeds artifacts produced by the canonical icydb-schema IC Wire encoders. Runtime application decodes and validates the same contract; the model package does not maintain another codec or convert retained data. Accepted snapshot formats and installation retirement obligations are defined in the persisted-format inventory.

References:

• Workspace overview: ../../README.md
• Schema authoring guide
• Design: ../../docs/design/archive/0.213-schema-authority-and-application-model-separation/0.213-design.md
• Release notes: ../../CHANGELOG.md