cultcache-rs: re-registration judges the global rule over held records; pins for refused re-registration restoring the previous declaration; changelog Breaking entries for unique index semantics

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Libby 2026-11-11 07:36:59 +00:00
commit 7976f146fc
4 changed files with 100 additions and 10 deletions

View file

@ -10,10 +10,14 @@ only in git history.
- A single-file store written as `cultcache.store.v3` is read and written: a record that holds an element id (an owned list element with an `[CultElementId]` member, carried through every write) marks the store v3, and a v3 store is carried through a rewrite with its ids. A runtime from before this change refuses a v3 store by name.
- A write over a file the reader refuses (a zero-byte file, a truncated store, a stamp this runtime does not read) refuses with `CultCacheStoreUnreadable` and leaves the file as it is. A whole-store write used to replace such a file. This reverses 0.3.1, where `push_all` replaced a file with no readable stamp (healing it); the stamp rule now has one owner, the reader every write asks under the lock, and it accepts v1 and v3 (0.3.1 refused v3).
- `#[cultcache(index)]` means unique, as in C# `RefuseIndexSharing`: within one type and one alias no two records hold one non-blank value. A put, batch, push or load that would make two records hold a value is refused, naming both keys and the alias, and a store that already holds a duplicate does not open. A grouping index is no longer expressible; a consumer that relied on shared values must drop the `index` and look up by another way.
- `bool` index and lookup text renders `True` / `False`, as C# does, where it rendered `true` / `false`.
- `DatabaseEntry::UNIQUE_INDEXES` replaces `cult_indexes` as the one index declaration and changes type (its members are the unique aliases); a hand implementation overriding `cult_indexes` no longer compiles.
- `register_entry_type` over a type that already holds records re-judges them under the new declaration (unique indexes and the global rule) and refuses, changing nothing, when they violate it or cannot be decoded.
### Added
- Lookups, matching the C# `GetByName`, `GetByIndex` and `GetGlobal`. `#[cultcache(name)]` and `#[cultcache(index)]` / `#[cultcache(index = "alias")]` on `DatabaseEntry` fields and `#[cultcache(global)]` on the struct give `CultCache::get_by_name`, `get_by_index` and `get_global`. An empty name and a blank index value are not found; records of one type sharing a name or value find the one with the smallest key. A second record of a global type under another key is refused on every write path and on load with `CultCacheSecondGlobal`. Two `name` members, or two members with one index alias, are refused at compile time. A member's text comes from `CultLookupValue` (`String`, `Option` of one, integers, `bool`, `char`).
- Lookups, matching the C# `GetByName`, `GetByIndex` and `GetGlobal`. `#[cultcache(name)]` and `#[cultcache(index)]` / `#[cultcache(index = "alias")]` on `DatabaseEntry` fields and `#[cultcache(global)]` on the struct give `CultCache::get_by_name`, `get_by_index` and `get_global`. An empty name and a blank index value are not found; records of one type sharing a name find the one with the smallest key (an index value is unique, below). A second record of a global type under another key is refused on every write path and on load with `CultCacheSecondGlobal`. Two `name` members, or two members with one index alias, are refused at compile time. A member's text comes from `CultLookupValue` (`String`, `Option` of one, integers, `bool`, `char`).
- `SchemaConflictError`, the typed refusal of a write the catalog cannot describe: records of different types under one schema id, or an arrived schema and a registered one that share an id and disagree on the schema name. A whole-store write (`push_all`) refuses with it, names the schema id, the names involved and a record key, writes nothing and leaves the file as it is. A caller tells it apart with `error.downcast_ref::<SchemaConflictError>()`.
## [0.3.1]

View file

@ -2804,33 +2804,40 @@ impl CultCache {
existing_type
));
}
// The projector decides what the held records hold, so a changed declaration re-derives the holder table over
// them; a held violation (or a record the new type cannot decode) refuses the registration and changes nothing.
// The declaration decides what the held records hold (index projector, global flag), so a changed declaration
// re-judges them; a held violation (or a record the new type cannot decode) refuses the registration and
// changes nothing.
let previous = self.projectors.get(T::TYPE).copied();
let was_global = self.globals.contains(T::TYPE);
if T::UNIQUE_INDEXES.is_empty() {
self.projectors.remove(T::TYPE);
} else {
self.projectors.insert(T::TYPE.to_string(), project_indexes::<T>);
}
if T::GLOBAL {
self.globals.insert(T::TYPE.to_string());
} else {
self.globals.remove(T::TYPE);
}
let held_type = self.entries.range((T::TYPE.to_string(), String::new())..).next().is_some_and(|((held, _), _)| held == T::TYPE);
if held_type {
match self.judge_image(&self.entries) {
match self.refuse_second_globals(&self.entries).and_then(|()| self.judge_image(&self.entries)) {
Ok(holders) => self.index_holders = holders,
Err(refusal) => {
match previous {
Some(project) => self.projectors.insert(T::TYPE.to_string(), project),
None => self.projectors.remove(T::TYPE),
};
if was_global {
self.globals.insert(T::TYPE.to_string());
} else {
self.globals.remove(T::TYPE);
}
return Err(refusal);
}
}
}
self.definitions.insert(T::TYPE.to_string(), T::SCHEMA_NAME);
if T::GLOBAL {
self.globals.insert(T::TYPE.to_string());
} else {
self.globals.remove(T::TYPE);
}
self.schema_name_definitions
.insert(T::SCHEMA_NAME.to_string(), T::TYPE.to_string());
Ok(())

View file

@ -48,7 +48,7 @@ struct Zed {
}
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
#[cultcache(type = "settings", global)]
#[cultcache(type = "settings", schema = "tests.settings", global)]
struct Settings {
#[cultcache(key = 0)]
value: String,
@ -217,6 +217,40 @@ fn a_global_is_none_until_written_and_survives_a_reopen() {
assert_eq!(reopened(&path).get_global::<Settings>().unwrap(), Some(settings("durable authority")));
}
/// `Settings` as an ordinary type: the same type id and schema, no global rule.
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
#[cultcache(type = "settings", schema = "tests.settings")]
struct LooseSettings {
#[cultcache(key = 0)]
value: String,
}
// Declaring a held type global judges the records it holds: two are already a second, so the registration is
// refused and the type stays ordinary.
#[test]
fn registering_a_type_global_over_two_held_records_is_refused_and_changes_nothing() {
let mut cache = CultCache::new();
cache.register_entry_type::<LooseSettings>().unwrap();
cache.put("a", &LooseSettings { value: "one".into() }).unwrap();
cache.put("b", &LooseSettings { value: "two".into() }).unwrap();
let refusal = cache.register_entry_type::<Settings>().unwrap_err();
assert!(refusal.downcast_ref::<CultCacheSecondGlobal>().is_some(), "{refusal:#}");
cache.put("c", &LooseSettings { value: "three".into() }).unwrap();
assert_eq!(cache.get_all_with_keys::<LooseSettings>().unwrap().len(), 3, "still ordinary");
}
// One held record may become the global; dropping the rule again restores the ordinary type.
#[test]
fn registering_a_type_global_over_one_held_record_is_admitted() {
let mut cache = CultCache::new();
cache.register_entry_type::<LooseSettings>().unwrap();
cache.put("a", &LooseSettings { value: "one".into() }).unwrap();
cache.register_entry_type::<Settings>().unwrap();
assert!(cache.put("b", &Settings { value: "two".into() }).is_err(), "a second global is refused");
}
#[test]
fn a_type_that_is_not_a_global_has_no_global() {
let mut cache = cache();

View file

@ -611,6 +611,51 @@ fn registering_an_index_over_colliding_held_records_is_refused_and_changes_nothi
assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), None);
}
/// The same type and schema declaring Sku as an integer: the held text cannot be decoded as one.
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
#[cultcache(type = "unique_item", schema = "tests.unique_item")]
struct Retyped {
#[cultcache(key = 0, index = "Sku")]
sku: i64,
}
/// A refused re-registration leaves the previous declaration in force: it keeps judging, so a later duplicate is refused.
#[test]
fn a_refused_reregistration_keeps_the_previous_index_judging() {
let mut cache = CultCache::new();
cache.register_entry_type::<Unique>().unwrap();
cache.put("a", &unique("S")).unwrap();
cache.put("b", &unique("T")).unwrap();
// A different declaration over the same type (Category is the unique alias) collides on held records.
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
#[cultcache(type = "unique_item", schema = "tests.unique_item")]
struct ByCat {
#[cultcache(key = 0)]
sku: String,
#[cultcache(key = 1, index = "Cat")]
category: String,
}
assert!(cache.register_entry_type::<ByCat>().is_err(), "a and b both hold category c");
assert!(cache.put("z", &unique("S")).is_err(), "the previous index still judges");
assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), cache.get::<Unique>("a").unwrap());
cache.put("z", &unique("U")).unwrap();
}
// A held record the new declaration cannot decode refuses the registration; the unindexed declaration stays.
#[test]
fn registering_an_index_over_an_undecodable_held_record_is_refused_and_changes_nothing() {
let mut cache = CultCache::new();
cache.register_entry_type::<Twin>().unwrap();
cache.put("a", &Twin { sku: "S".into(), category: "x".into() }).unwrap();
assert!(cache.register_entry_type::<Retyped>().is_err());
cache.put("b", &Twin { sku: "S".into(), category: "y".into() }).unwrap();
assert_eq!(cache.get_all_with_keys::<Twin>().unwrap().len(), 2, "no index judges the duplicate");
}
// Dropping the declaration releases the holders.
#[test]
fn registering_without_the_index_releases_the_holders() {