Session State (state)

If the store is your application's hard drive, the state is its RAM.

In Carotene, the state block defines volatile, ephemeral memory. Data defined inside state is designed to be blazing fast, but it is not durable. If the server restarts or the user closes their browser, the state is cleared.

By strictly isolating RAM (state) from Disk (store), Carotene ensures that your AI coding agent never accidentally triggers an expensive, blocking database write when it only meant to toggle a UI loading spinner.

Contextual Defaults (The Magic)

Just like the store, Carotene's Inference Engine reads where the state block is located and generates the optimal in-memory infrastructure for that specific environment.

• Frontend Environment: The compiler infers a reactive memory slice. Depending on your target, it generates Zustand or Redux (React), Pinia (Vue), or ObservableObject (SwiftUI). It automatically wires up the reactivity, meaning your UI components will re-render instantly when the state changes.
• Backend Environment: The compiler infers a high-speed caching layer. By default, it generates a Redis connection and manages the serialization/deserialization of your data automatically.

domain Gaming {
  
  backend {
    // Generates a Redis cache for high-speed matchmaking
    state {
      model MatchmakingQueue {
        activePlayers: UUID[]
        averageWaitTime: Float
      }
    }
  }

  frontend {
    // Generates a local Zustand/Redux slice for the UI
    state {
      model UIContext {
        isSidebarOpen: Boolean { default: false }
        activeTheme: Enum(Light, Dark) { default: Dark }
      }
    }
  }
}

The Verb: Safe Memory Manipulation (mutates)

Because state does not hit the disk, it does not use the standard creates or updates verbs.

To grant the AI permission to change volatile memory, you use the mutates verb. This explicit separation of verbs acts as a massive psychological and architectural guardrail.

frontend {
  function ToggleTheme() {
    // The AI is explicitly granted permission to change the UI RAM
    mutates state.UIContext
  }
}

The Sandbox Guarantee: If the AI implements ToggleTheme and hallucinates a database call (ctx.db.user.update(...)), the Carotene execution sandbox fails the build. The AI only requested mutates, so the compiler physically withheld the database client from its environment.

Type Referencing & UI Composition

As we established in the Models & Validation section, you should never recreate your database schema inside your state. Instead, you use Cross-Boundary Type Referencing and Composition (includes) to pull data from your store into your volatile memory safely.

By referencing the store models directly, you guarantee that if the backend database schema changes, your frontend memory manager will automatically inherit the new types and validation rules without a single line of synchronization code.

Advanced Backend State: Ephemeral vs. Persistent Caching

While the frontend uses state primarily for UI reactivity, the backend uses state for high-performance operations that would otherwise cripple a Postgres database:

1. Rate Limiting: Storing IP addresses and request counts.
2. WebSockets & Pub/Sub: Holding active connection IDs and live chat rooms.
3. Session Management: Storing active JWTs or session tokens.

By default, backend state is transient. However, you can use the config block to override the Redis settings, dictating exactly how memory should be handled (e.g., setting strict Time-To-Live parameters).