cortex_core/
version.rs

1//! Schema and crate version helpers.
2//!
3//! # Schema version policy
4//!
5//! [`crate::SCHEMA_VERSION`] tags every persisted Cortex record (events,
6//! traces, memories, principles, doctrine, context packs, audit records).
7//! It governs **on-disk** and **wire** compatibility, NOT the crate's
8//! semver.
9//!
10//! ## Bump rules
11//!
12//! Bump `SCHEMA_VERSION` **and** open an ADR in `docs/adr/` whenever any of
13//! the following changes:
14//!
15//! 1. A field is added, removed, or renamed in any `serde`-serialized struct
16//!    that crosses the persistence boundary (sqlite columns, JSONL log,
17//!    context-pack JSON).
18//! 2. The semantic meaning of a field changes (e.g. `confidence` switches
19//!    range or distribution), even if the JSON shape is unchanged.
20//! 3. The wire string of any `EventType` (or other tagged enum that carries
21//!    a `cortex.<entity>.<name>.v<N>` identifier) is renamed.
22//! 4. Hash framing changes (payload hash, event hash, chain framing) — these
23//!    invalidate previously-recorded chains and force a migration.
24//!
25//! ## What does NOT require a bump
26//!
27//! - Adding a brand-new variant to an open enum that ships with `serde(other)`
28//!   handling AND already-deployed readers that quarantine unknown variants.
29//! - Internal refactors that preserve the on-disk JSON byte-for-byte.
30//! - Adding new tables / files that older readers can ignore.
31//!
32//! When in doubt: bump and write the ADR. The cost of a one-line schema bump is
33//! orders of magnitude less than the cost of a silent shape drift in the
34//! ledger.
35
36/// Returns the `CARGO_PKG_VERSION` of `cortex-core`.
37#[must_use]
38pub fn crate_version() -> &'static str {
39    env!("CARGO_PKG_VERSION")
40}
41
42/// Returns the current schema version (re-export of [`crate::SCHEMA_VERSION`]).
43///
44/// Provided so downstream code can write `cortex_core::version::schema()`
45/// without a `use` of the constant.
46#[must_use]
47pub const fn schema() -> u16 {
48    crate::SCHEMA_VERSION
49}
50
51#[cfg(test)]
52mod tests {
53    use super::*;
54
55    /// Schema v2 atomic cutover acceptance (ADR 0018): this build of
56    /// `cortex-core` MUST report schema version `2`. If you are bumping the
57    /// schema again, update this test, write the ADR, and update
58    /// [`crate::version`]'s bump-rules doc.
59    #[test]
60    fn current_schema_version_is_2() {
61        assert_eq!(crate::SCHEMA_VERSION, 2);
62        assert_eq!(schema(), 2);
63    }
64
65    #[test]
66    fn crate_version_is_non_empty() {
67        assert!(!crate_version().is_empty());
68    }
69}
cortex_core/version.rs

cortex_core/
version.rs
