Struct AppState 

pub struct AppState {
    pub nats: Option<Client>,
    pub jetstream: Option<Context>,
    pub formations: Arc<RwLock<BTreeMap<Uuid, FormationRecord>>>,
    pub cells: Arc<RwLock<BTreeMap<String, CellRecord>>>,
    pub api_token: ApiToken,
    pub operator_id: Arc<OperatorId>,
    pub applied_cursor: Arc<AtomicU64>,
}

Fields

nats: Option<Client>

NATS connection used both by the WebSocket bridge and by future projection replay. Option because tests can drive the router without a live broker.

jetstream: Option<Context>

JetStream context (ADR-0011, ADR-0015). Populated alongside nats once the server confirms the CELLOS_EVENTS stream exists. Option so router tests without a live broker still build the state cleanly; the WS bridge falls through to a “broker not configured” close if this is None.

formations: Arc<RwLock<BTreeMap<Uuid, FormationRecord>>>

In-memory projection of formations. UUID-keyed for stable lookup.

cells: Arc<RwLock<BTreeMap<String, CellRecord>>>

In-memory projection of cells.

api_token: ApiToken

Bearer token required on every non-public route.

operator_id: Arc<OperatorId>

Operator identity attributed to every signed CloudEvent this server emits (ADR-0019 §Decision, §Implementation roadmap step 2).

Resolved from CELLOS_SERVER_OPERATOR_ID at startup; falls back to DEFAULT_OPERATOR_ID. Wrapped in Arc so the Clone-able AppState does not pay a string allocation on every handler call. cellos-core exposes OperatorId as a Clone + Hash newtype, but we still want to share one heap allocation across the many Principal::Operator { id: state.operator_id.as_ref().clone() } construction sites; Arc<OperatorId> is the cheapest honest shape.

applied_cursor: Arc<AtomicU64>

Highest JetStream stream-sequence the projection has applied (ADR-0015 §D2). The snapshot endpoint reports this as cursor so clients can open /ws/events?since=<cursor> and know they will not miss any event after the snapshot.

The WebSocket bridge bumps this monotonically as it forwards frames (see ws.rs). Until the bridge is migrated to a real JetStream consumer, this counter is per-process and resets on restart — that is acceptable for the MVP because every browser reconnect repeats the snapshot fetch.

Implementations

impl AppState

pub fn new(nats: Option<NatsClient>, api_token: impl Into<String>) -> Self

Constructor used by both main.rs and the test harness.

The operator identity defaults to DEFAULT_OPERATOR_ID; callers that need a different identity (production main, tests covering principal attribution) chain AppState::with_operator. Keeping the constructor signature stable preserves every existing test that builds AppState::new(None, "test") — the principal migration (ADR-0019 step 2) ships without churning unrelated test setups.

pub fn with_operator(self, operator_id: impl Into<String>) -> Self

Override the operator identity used to attribute admission-emitted CloudEvents. ADR-0019 §Implementation roadmap step 2: every signed event MUST declare its principal explicitly; this is where the server-side Principal::Operator is anchored.

pub fn principal(&self) -> Principal

Build the Principal every server-emitted signed CloudEvent attributes to. Pre-ADR-0019-step-3 we only emit Principal::Operator; the structured variant is preserved so a later wave can swap in Principal::Delegate for MCP-bridge admission without churning every emission site again.

pub fn with_jetstream(self, ctx: JsContext) -> Self

Attach a JetStream context. Called from main.rs after ensure_stream succeeds. Returns the same AppState for builder-style chaining in tests.

pub fn cursor(&self) -> u64

Current snapshot cursor — the highest seq the server has applied.

Red-team wave 2 (LOW-W2A-1): Acquire is sufficient here. We need to see writes that happen-before any successful bump_cursor (i.e. the projection-apply write inside apply_event_payload); the previous SeqCst enforced a global total order with every other SeqCst operation in the process (counter fetch_adds in sni_proxy, etc.) for no extra correctness gain on this read.

pub fn bump_cursor(&self, seq: u64)

Bump the snapshot cursor to at least seq. Monotonic; out-of-order values are ignored. Used by the WebSocket bridge as it forwards frames.

Red-team wave 2 (LOW-W2A-1): downgraded from SeqCst to AcqRel/Acquire. The CAS-loop structure (re-load on conflict, strict seq > current gate) guarantees monotonicity independent of the memory ordering chosen. AcqRel on success publishes the new cursor to every subsequent cursor() reader (snapshot GET handlers, primarily); Acquire on the reload picks up the observed value from the winner of the conflict.

pub async fn apply_event_payload(&self, payload: &[u8]) -> Result<ApplyOutcome>

Apply a single CloudEvent payload (raw JSON bytes from JetStream) to the in-memory projection.

This is shared between the boot-time replay path (jetstream::replay_projection) and the live WebSocket bridge (ws.rs). Centralising the apply logic guarantees that what the server reconstructs on startup is exactly what it applies live — there is no “replay-only” code path that could drift from the live one.

CloudEvent type discriminates the transition. Two event families mutate state today:

• formation.v1.* — server-emitted formation lifecycle, drives the formations projection (ADR-0010 admission gate output).
• cell.lifecycle.v1.* and cell.command.v1.completed — supervisor-emitted cell lifecycle (ARCH-001). Without this, the server replays cell events from JetStream but never updates the cells map and GET /v1/cells returns []. The cell projector landed alongside the formation projector so cellctl get cells reflects what the supervisor actually ran.

Unknown event types still advance the JetStream cursor at the caller (the apply contract is independent of whether the projection mutated), so audit gaps surface as ApplyOutcome::Ignored in the replay log rather than silent drops.

Trait Implementations

impl Clone for AppState

fn clone(&self) -> AppState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.