Skip to main content

Module version

cortex_core

Module version 

Source
Expand description

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.

Functions§

crate_version
Returns the CARGO_PKG_VERSION of cortex-core.
schema
Returns the current schema version (re-export of crate::SCHEMA_VERSION).