[META]: Glossary and the load-bearing system invariants

[ELares]

This issue is the single source of truth for IronCache's vocabulary and for the load-bearing invariants every design, ADR, and review must respect. It exists so that "shard" means one thing across the tracker, and so that the properties we refuse to violate are stated once, ranked, and made CI-checkable where the language allows. It catalogs the issues that own each term and each invariant; it does not re-litigate their designs. Parent: #2. Related: #4, #5. Rolls up to #1.

Purpose

Fix the canonical meaning of project-wide terms and pin the system invariants so that cross-cutting claims stay coherent. When a design issue and a review disagree about what "tier" or "behavioral equivalence" means, this issue wins. Tenets resolve conflicts in order: Compatible > Efficient > Simple > Scalable > AI-Driven.

Glossary

• shard: the unit of keyspace partition. A key maps to a shard by k = HASH(KEY) % N, where N is at most the core count [dragonfly-shard-formula]. Distinct from a Redis-wire hash slot.
• slot: a Redis Cluster hash slot (0..16383), a protocol-level concept for client routing and resharding. Many slots map onto one IronCache shard; the two are not interchangeable.
• hot path: the per-request GET/SET execution path inside a shard's owning core. State touched here must be shard-local; no locks, no cross-core atomics [glommio-locks-never-necessary].
• advisor: an out-of-band component that observes traffic and proposes tuning (e.g. encoding thresholds, admission). Advisors never sit on the hot path and never make a decision the hot path must block on.
• codec: the wire-level encoder/decoder for RESP2/RESP3 frames. Strictly protocol; carries no storage semantics.
• encoding: the in-memory representation of a value (e.g. inline string, listpack-equivalent, hashtable). An implementation detail surfaced only through OBJECT ENCODING compatibility.
• tier: a storage level distinguished by latency/cost (e.g. in-memory vs cold/compressed). Orthogonal to shard and encoding.

Invariants

1. Shared-nothing: a key's shard is owned by exactly one core; there is no hot-path shared mutable state, and cross-shard work is explicit message passing [seastar-shared-nothing]. This replaces Redis's single command thread [redis-command-execution-single-threaded] with per-core ownership.
2. Determinism: time, network, disk, and RNG are reached only through abstractions, so a seeded replay of the same input yields byte-identical eviction and expiry decisions. No direct clock or rand calls on decision paths.
3. Memory honesty: maxmemory is accounted against allocator-attributed bytes, not naive object sizes [redis-maxmemory-accounting], so the limit is an honest bound rather than a fragmentation-blind estimate.
4. No fork: no persistence, snapshot, or maintenance path may call fork(). We avoid copy-on-write RSS doubling structurally; reclamation uses background threads, not process forks.
5. Behavioral-equivalence contract: the compatibility bar is behavioral equivalence with Redis, not bit-identical replies. Reply structure, types, and observable side effects must match; the precise error-text bar is deferred to the conformance issue. We pick behavioral equivalence over bit-identity because it preserves client compatibility (top tenet) without freezing internal representations the Efficient tenet needs to evolve.

CI-checkability

Where the property is mechanical, CI enforces it: a lint forbids fork() (and any libc fork binding) anywhere in the tree (invariant 4); a lint forbids direct std::time, Instant::now, and rand calls outside the approved abstraction modules (invariant 2); the hot-path crate denies the std::sync lock and shared-atomic imports (invariant 1). Invariants 3 and 5 are enforced by test suites, not lints, and owned by their respective issues below.

What this indexes

Every term and invariant above is owned by a design or decision issue. This issue links them and is the canonical reference reviewers cite; it is updated whenever a term's meaning or an invariant's wording changes.

Entries

• Shared-nothing / shard ownership: [DECISION]: Shared-nothing thread-per-core as the core concurrency model #24
• Cross-shard coordinator and message passing: [DESIGN]: Cross-shard coordinator and transaction/scripting surface #29
• Determinism and seeded-replay testing: [DECISION]: Design the runtime for determinism to enable DST #31
• Memory-honesty accounting and allocator choice: [DECISION]: Default global allocator and memory-accounting strategy #41
• No-fork reclamation and background drop: [DESIGN]: TTL expiration via per-shard timing wheel with lazy backstop and background reclamation #51
• Behavioral-equivalence and error-text bar: [DESIGN]: Conformance, differential, fuzz, property, and DST testing stack #95
• Encoding terminology and OBJECT ENCODING mapping: [DESIGN]: OBJECT ENCODING / DEBUG OBJECT compatibility mapping #40
• Tenets and conflict ordering: [META]: Scope, ranked tenets, and the five-pillar charter #2
• ADR cross-reference: [META]: ADR index, decision register, and record format #4
• Coherence enforcement across issues: [META]: Issue-tree coherence and deduplication audit #5

[ELares]

Pre-implementation audit (2026-06-13)

Verdict: valid

Issue #3 is the canonical glossary and load-bearing invariants index for IronCache. All 5 cited claims exist and the prose matches their recorded values; all 10 cross-references resolve to issues with coherent titles; leftover_tokens is empty. The design is technically accurate (slot range 0..16383, k=HASH(KEY)%N with N<=cores, allocator-attributed maxmemory, no-fork rationale) and consistent with the ranked tenets (AI/advisors kept off the hot path; behavioral-equivalence preserves the Compatible tenet). One low-severity note: the issue leans on redis-command-execution-single-threaded, whose ...

Action taken: No blocking change required.

[ELares]

Ratified in docs/GLOSSARY.md and docs/INVARIANTS.md (PR #167). One intentional refinement of this issue's Entries map: the No fork invariant's primary owner is recorded as #59 (the durability-stance decision that actually chooses forkless snapshotting), with #51 owning the background-drop half, rather than #51 alone. Fresh-eyes review agreed this is the more accurate attribution.