crtx-core 0.1.1

//! Schema and crate version helpers.
//!
//! # Schema version policy
//!
//! [`crate::SCHEMA_VERSION`] tags every persisted Cortex record (events,
//! traces, memories, principles, doctrine, context packs, audit records).
//! It governs **on-disk** and **wire** compatibility, NOT the crate's
//! semver.
//!
//! ## Bump rules
//!
//! Bump `SCHEMA_VERSION` **and** open an ADR in `docs/adr/` whenever any of
//! the following changes:
//!
//! 1. A field is added, removed, or renamed in any `serde`-serialized struct
//!    that crosses the persistence boundary (sqlite columns, JSONL log,
//!    context-pack JSON).
//! 2. The semantic meaning of a field changes (e.g. `confidence` switches
//!    range or distribution), even if the JSON shape is unchanged.
//! 3. The wire string of any `EventType` (or other tagged enum that carries
//!    a `cortex.<entity>.<name>.v<N>` identifier) is renamed.
//! 4. Hash framing changes (payload hash, event hash, chain framing) — these
//!    invalidate previously-recorded chains and force a migration.
//!
//! ## What does NOT require a bump
//!
//! - Adding a brand-new variant to an open enum that ships with `serde(other)`
//!   handling AND already-deployed readers that quarantine unknown variants.
//! - Internal refactors that preserve the on-disk JSON byte-for-byte.
//! - Adding new tables / files that older readers can ignore.
//!
//! When in doubt: bump and write the ADR. The cost of a one-line schema bump is
//! orders of magnitude less than the cost of a silent shape drift in the
//! ledger.

/// Returns the `CARGO_PKG_VERSION` of `cortex-core`.
#[must_use]
pub fn crate_version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}

/// Returns the current schema version (re-export of [`crate::SCHEMA_VERSION`]).
///
/// Provided so downstream code can write `cortex_core::version::schema()`
/// without a `use` of the constant.
#[must_use]
pub const fn schema() -> u16 {
    crate::SCHEMA_VERSION
}

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

    /// Schema v2 atomic cutover acceptance (ADR 0018): this build of
    /// `cortex-core` MUST report schema version `2`. If you are bumping the
    /// schema again, update this test, write the ADR, and update
    /// [`crate::version`]'s bump-rules doc.
    #[test]
    fn current_schema_version_is_2() {
        assert_eq!(crate::SCHEMA_VERSION, 2);
        assert_eq!(schema(), 2);
    }

    #[test]
    fn crate_version_is_non_empty() {
        assert!(!crate_version().is_empty());
    }
}