theSix

Repository layout

theSix/ ├── Cargo.toml ├── README.md ├── LICENSE ├── CHANGELOG.md ├── deny.toml ├── src/ │ ├── lib.rs │ ├── manager.rs │ ├── policy.rs │ ├── control/mod.rs │ ├── control/cachelito.rs │ ├── tier/mod.rs │ ├── tier/trait.rs │ ├── tier/fixed_tier_stub.rs │ ├── tier/l0.rs – l5.rs │ ├── tier/test.rs │ ├── tier/backends/ # ByteValue codec + real backends │ │ ├── mod.rs │ │ ├── l3_redis.rs # feature = "redis" │ │ ├── l4_sled.rs # feature = "sled" (persistent) │ │ └── l5_origin.rs # pluggable origin fetcher/writer │ ├── entry.rs │ ├── error.rs │ ├── identity.rs # IdentityContext + CacheContext builder │ ├── key.rs # Key trait + KeyRef borrowed view │ └── pool.rs # MemoryPool fixed-capacity allocator ├── specs/ │ ├── thesix.toml │ ├── cache_manager.toml │ ├── cachelito.toml │ ├── policy.toml │ ├── tiers.toml │ └── stampede.toml ├── tests/ │ ├── common/mod.rs # shared test helpers │ ├── hierarchy.rs │ ├── concurrency.rs │ ├── policy.rs │ ├── stampede.rs │ ├── integration.rs │ └── backends.rs # feature-gated backend tests └── benches/ └── cache_operations.rs

The important conceptual split is:

theSix │ ├── Cache Manager API / orchestration │ ├── Policy Engine decides what should happen │ ├── Cachelito coordinates concurrent state │ ├── Tier subsystem actual cache implementations │ └── Stampede subsystem single-flight / population control

The application should never need to know that L3 happens to be Redis.

specs/thesix.toml

This becomes the system-level contract.

[system] name = "theSix" version = "0.1" description = "Policy-driven six-tier cache orchestration for Rust" model = "control-plane-over-data-plane"

[architecture] tier_count = 6 application_selects_tier = false manager_selects_tier = true policy_selects_tier = true control_plane = "cachelito"

[principles] separate_control_plane = true separate_data_plane = true policy_driven_routing = true opaque_tier_topology = true single_flight_population = true generation_based_invalidation = true no_io_while_holding_control_guard = true

[guarantees] concurrent_readers = true tier_selection_is_deterministic = true tier_failure_is_isolated = true stampede_detection = true population_coordination = true

[non_goals] distributed_consensus = false general_persistence_layer = false application_business_logic = false global_cache_coherence = false

That last section matters.

You're explicitly saying:

theSix orchestrates caching. It is not trying to become a database, consensus protocol, or replacement for application semantics.

Humanity has enough projects that accidentally become databases.

specs/cache_manager.toml

This defines the public abstraction.

[manager] name = "CacheManager"

[operations] get = true get_or_fetch = true set = true invalidate = true remove = true refresh = true exists = true

[operations.promotion] enabled = true policy_controlled = true

[operations.demote] enabled = true policy_controlled = true

[routing] application_direct_tier_selection = false manager_resolves_policy = true manager_resolves_tier = true

[execution] async = true never_hold_control_guard_across_io = true

[errors] tier_failure_propagation = "policy" population_failure_propagation = "single_flight"

The application API should therefore conceptually become:

cache.get(key).await?;

or:

cache.get_or_fetch(key, fetcher).await?;

not:

cache.l3.get(key).await?;

That distinction is the whole point.

specs/cachelito.toml

This is where your morning realization gets formalized.

[control] name = "Cachelito" role = "cache-control-plane"

[storage] structure = "sharded-concurrent-map" implementation = "fixed-capacity sharded slot map"

[state] tracks_entry_state = true tracks_generation = true tracks_tier = true tracks_population = true tracks_expiration = true

[entry_states] values = [ "absent", "ready", "stale", "in_flight", "failed" ]

[coordination] single_flight = true reader_coalescing = true writer_coordination = true

[concurrency] multiple_readers = true sharded_state = true global_lock = false io_under_guard = false

[invariants] control_state_does_not_store_payload = true control_guard_must_not_cross_await = true control_guard_must_not_cross_io = true

This is the key architectural invariant:

Cachelito knows about cache state. It does not become another cache containing application payloads.

That keeps it genuinely in the control plane.

specs/policy.toml

This defines how the system decides which tier to use.

[policy] name = "default" mode = "deterministic"

[selection] latency = true capacity = true consistency = true availability = true entry_size = true ttl = true cost = true

[application] direct_tier_selection = false

[resolution] input = [ "operation", "key_metadata", "entry_metadata", "cache_state", "tier_health" ]

output = [ "selected_tier", "operation", "population_strategy" ]

[precedence] explicit_policy = 1 tier_health = 2 consistency_requirement = 3 latency_requirement = 4 capacity_requirement = 5 default_tier = 6

You can later turn this into a real Rust trait:

pub trait CachePolicy<K, V>: Send + Sync { fn select( &self, request: &CacheRequest<K, V>, state: &CacheState, ) -> PolicyDecision; }

And now the hierarchy becomes replaceable without rewriting the manager.

specs/tiers.toml

I would not hard-code your backend implementations into the fundamental theSix contract.

Instead:

[tiers] count = 6

[tier.l0] role = "request" scope = "request" persistent = false shared = false

[tier.l1] role = "hot-local" scope = "process" persistent = false shared = false

[tier.l2] role = "local" scope = "process" persistent = false shared = false

[tier.l3] role = "distributed" scope = "cluster" persistent = false shared = true

[tier.l4] role = "persistent" scope = "host" persistent = true shared = false

[tier.l5] role = "origin-fallback" scope = "external" persistent = false shared = true

[routing] manager_only = true policy_only = true

[health] health_checks = true failure_isolation = true

This is deliberately abstract.

You can then have a configuration such as:

[tier.l1] backend = "lru"

[tier.l2] backend = "moka"

(moka is a planned optional backend; not yet wired as a feature)

[tier.l3] backend = "redis"

[tier.l4] backend = "sled"

[tier.l5] backend = "origin"

without making those technologies part of the fundamental architecture.

That gives you freedom to eventually replace Sled, Redis, Moka, etc. without rewriting the conceptual system.

specs/stampede.toml

This one deserves its own specification because you already identified the failure mode.

[stampede] enabled = true strategy = "single-flight"

[ownership] one_population_owner = true waiters_join_existing_population = true

[timeouts] population_timeout = "5s" wait_timeout = "5s"

[failure] owner_failure_releases_state = true waiters_receive_population_error = true retry_after_failure = true

[retry] enabled = true max_attempts = 3 backoff = "exponential"

[invariants] duplicate_population_for_same_key = false stale_infinite_inflight_state = false owner_loss_recoverable = true

The important semantic distinction is:

Cache miss ≠ permission for every reader to populate the cache

Instead:

MISS │ ┌──────┴──────┐ │ │ ABSENT IN_FLIGHT │ │ become wait owner │ │ │ fetch │ │ │ publish ◄─────────┘

That's where Cachelito earns its keep.

Cargo manifest

For crates.io, I'd keep the actual package lean.

[package] name = "thesix" version = "0.1.0" edition = "2024" rust-version = "1.98"

description = "Policy-driven six-tier cache orchestration for Rust" license = "MIT" readme = "README.md" repository = "https://github.com/Metis-Avionics/theSix" homepage = "https://github.com/Metis-Avionics/theSix"

keywords = [ "cache", "caching", "concurrency", "async", "systems" ]

categories = [ "caching", "concurrency", "asynchronous" ]

[dependencies] dashmap = "..." tokio = { version = "...", features = ["sync", "time"] } thiserror = "..."

[dev-dependencies] tokio = { version = "...", features = ["macros", "rt-multi-thread", "test-util"] } criterion = "..."

[features] default = [] redis = ["dep:redis"] sled = ["dep:sled"]

[dependencies.redis] version = "..." optional = true

[dependencies.sled] version = "..." optional = true

I would not make every backend mandatory.

The core crate should contain the orchestration machinery. Backend integrations should be features or separate crates if they become sufficiently large.

Cargo's packaging process verifies that the packaged crate can actually build from a clean extraction, and crates.io publishes versions permanently, so 0.1.0 should represent a deliberately bounded API rather than “whatever happened to compile tomorrow morning.”

The coding-agent prompt

This is the bit I'd actually hand to your agent tomorrow.

Build theSix

Implement "theSix", a production-oriented Rust library providing policy-driven six-tier cache orchestration.

Mission

Build a reusable Cargo package suitable for publication on crates.io.

TheSix is a cache orchestration system, not merely a cache implementation.

Its architecture is:

Application │ ▼ CacheManager │ ▼ Policy Engine │ ▼ Cachelito Control Plane │ ├── concurrency state ├── entry state ├── tier selection state ├── generation state ├── population ownership └── stampede coordination │ ▼ Six-Tier Data Plane │ ├── L0 request-local ├── L1 hot-local ├── L2 local ├── L3 distributed ├── L4 persistent └── L5 origin/fallback

Core architectural invariants

Application code MUST NOT select cache tiers directly.
CacheManager MUST own cache operations.
Policy MUST determine tier selection.
Cachelito MUST operate as the control plane.
Cachelito MUST NOT own application payload data.
Tier implementations MUST remain replaceable.
No control-plane lock/guard may be held across ".await".
No control-plane lock/guard may be held across network or disk I/O.
Multiple readers MUST be supported concurrently.
Cache population MUST support single-flight coordination.
A cache miss MUST NOT permit unlimited concurrent population.
A failed population MUST release the in-flight state.
Stale in-flight state MUST be recoverable.
Tier failure MUST be isolated where policy permits.
Cache invalidation MUST support generation-based protection against stale writes.

Public API

Implement approximately:

pub struct CacheManager<K, V, P> { ... }

impl<K, V, P> CacheManager<K, V, P> { pub async fn get( &self, key: &K, ) -> Result<Option, CacheError>;

pub async fn get_or_fetch<F, Fut>(
    &self,
    key: &K,
    fetch: F,
) -> Result<V, CacheError>
where
    F: FnOnce() -> Fut;

pub async fn set(
    &self,
    key: K,
    value: V,
) -> Result<(), CacheError>;

pub async fn invalidate(
    &self,
    key: &K,
) -> Result<(), CacheError>;

pub async fn remove(
    &self,
    key: &K,
) -> Result<(), CacheError>;

}

Do not expose tier selection through the normal application API.

If an administrative/debug API requires explicit tier inspection, keep it clearly separated from the normal data path.

Cachelito

Implement Cachelito as the control-plane state registry.

Use a pre-allocated, sharded slot map (theSix removes DashMap per TETANUS Rule 3: no heap allocation after init).

A control entry should contain enough metadata to represent:

pub enum EntryState { Absent, Ready, Stale, InFlight, Failed, }

plus:

selected tier
generation
expiration
population ownership
population timestamp
failure state where required

Do not store the actual cache payload in Cachelito.

Single-flight

For a given key:

first caller -> population owner other callers -> waiters

Only one population operation may own the key at a time unless the policy explicitly permits duplicate population.

The implementation MUST handle:

successful population
failed population
owner cancellation
owner timeout
waiter timeout
stale ownership
retry
generation changes during population

Policy engine

Define a policy abstraction capable of evaluating:

operation
key metadata
entry metadata
cache state
tier health
latency requirements
consistency requirements
entry size
TTL
capacity
availability

The policy returns a decision containing at minimum:

pub struct PolicyDecision { pub tier: TierId, pub operation: CacheOperation, pub population: PopulationStrategy, }

Do not couple the policy engine to Redis, Moka, LRU, Sled, or any particular storage technology.

Tier abstraction

Define a trait representing a cache tier.

The trait MUST support asynchronous operations without forcing the implementation to use a particular runtime internally beyond what is required by the public API.

At minimum support:

get
set
remove
contains
invalidate where applicable
health/state reporting

Tier implementations must be independently testable.

Tier topology

The system exposes six logical tiers:

L0 = request-local L1 = hot-local L2 = local L3 = distributed L4 = persistent L5 = origin/fallback

The logical roles MUST remain stable even if backend implementations change.

Backend selection is configuration.

Concurrency

Design explicitly for:

many concurrent readers
concurrent reads and writes
concurrent operations on unrelated keys
contention on the same key
contention on different shards
tier failures
population races

Never solve concurrency by placing one global "RwLock" around the entire cache hierarchy.

Do not hold a shard/slot guard or equivalent control-plane reference across an await point.

Generation safety

Every population operation must capture the relevant generation.

A population result MUST NOT overwrite a newer generation.

Example:

generation 41 │ ├── population starts │ generation 42 │ └── invalidation │ population 41 completes │ X reject stale publication

Error model

Define structured errors for:

cache miss
tier unavailable
policy failure
serialization failure
population failure
timeout
cancellation
stale generation
configuration error

Do not collapse every failure into a generic string.

Testing

Build deterministic tests for:

basic get/set
tier traversal
policy selection
concurrent readers
concurrent writer/readers
single-flight population
100 concurrent requests for one missing key
population failure
owner cancellation
waiter timeout
stale generation rejection
tier failure
tier recovery
invalidation
promotion
demotion
concurrent unrelated keys
shard contention
policy replacement
complete six-tier integration

The test suite MUST prove that a concurrent cache miss does not produce uncontrolled duplicate population.

Benchmarks

Benchmark separately:

uncontended get
concurrent get
same-key contention
unrelated-key contention
policy evaluation
Cachelito lookup
single-flight coordination
tier traversal

Do not optimize prematurely. Establish measurements first.

Documentation

Write crate-level documentation explaining:

architecture
control plane vs data plane
CacheManager
Cachelito
policy engine
six logical tiers
single-flight semantics
generation invalidation
concurrency guarantees
failure modes

Include at least one complete example showing an application calling:

manager.get_or_fetch(&key, fetcher).await

without knowing which cache tier is used.

Quality gates

Before considering implementation complete:

cargo fmt --check cargo check cargo test cargo clippy --all-targets --all-features -- -D warnings cargo doc --no-deps cargo package --list cargo publish --dry-run

Do not publish automatically.

API discipline

Keep the initial public API small.

Prefer private implementation details and explicit internal modules over exposing every internal structure.

Do not expose the control-plane slot map directly.

Do not expose individual cache tiers through the default API.

Do not expose internal locks.

Do not expose Cachelito's internal storage representation.

TheSix's value is the orchestration abstraction.

Design rule

When an implementation decision conflicts with the architectural invariants, preserve the invariants and redesign the implementation.

Do not introduce a workaround that makes the public API aware of internal cache topology.

Deliverables

Produce:

compilable crate
Cargo.toml
src/
tests/
benchmarks
README
API documentation
architecture documentation
TOML specifications under "specs/"
CHANGELOG
license
CI configuration suitable for a public crates.io project

Do not claim the crate is production-ready until the concurrency and stampede tests demonstrate the required invariants.That prompt is deliberately strict about architecture before implementation. That's where I think theSix could become genuinely good rather than merely becoming “Rayan's six caches in a trench coat.”

One thing I'd change from your current instinct

Don't make theSix synonymous with your current six backend technologies.

Make it synonymous with the six-tier orchestration model.

That distinction gives you this:

theSix 0.1 │ ├── L0 request ├── L1 hot-local ├── L2 local ├── L3 distributed ├── L4 persistent └── L5 origin

while the implementation can evolve:

0.2 → fixed-capacity slot maps + L0–L2 in-memory + Redis + Sled + origin (moka planned)

0.2 → different persistent tier

0.3 → different distributed backend

0.4 → smarter admission policy

1.0 → stable orchestration API

That is what makes it a crate rather than a snapshot of one particular infrastructure stack.

And because crates.io versions are effectively permanent, I'd be particularly conservative about the public API before 1.0.

TheSix can then become one of those primitives you pull into a new project instead of spending three days rebuilding your own cache hierarchy because apparently suffering is a required dependency of software engineering.

thesix 0.2.0

theSix

(moka is a planned optional backend; not yet wired as a feature)