OrbitDock: Skill for Codex

API Transport Architecture

Use this skill when touching any of these areas:

• Rust HTTP or WebSocket transport
• Rust protocol contracts
• Swift client networking, stores, reconnect logic, or bootstrap flow
• dashboard, missions, detail, composer, conversation, or any new large UI surface
• API design for features that need to scale to many concurrent agents

Core Contract

• HTTP owns bootstrap, heavy reads, pagination, and mutation responses.
• WebSocket owns light realtime deltas, replay, heartbeats, and explicit refetch hints.
• The Rust server owns durable business truth.
• The client renders server state and derives presentation only.

Reserve control plane for runtime endpoint selection, primary-claim routing, and sync topology only. Do not create UI-facing umbrella endpoints named after app components; model those as normal REST resources such as sessions, conversations, capabilities, dashboard, missions, or library. Do not use control plane as the name of a UI-facing HTTP surface when the surface is really a compact sessions summary.

If a payload is large, expensive to build, expensive to decode, or likely to be needed only on demand, it belongs on HTTP.

Scale-First Rules

Design for hundreds of concurrent agents without stressing the UI thread, server transport, or reconnect path.

• Do not treat WebSocket like a catch-all state pipe.
• Do not push large snapshots repeatedly over WS.
• Do not rebuild whole screens or global projections for every small event.
• Do not make one store or object responsible for every surface in the app.
• Prefer narrow, surface-local updates and explicit refetch over broad invalidation storms.

Server Authority Rules

• Durable business fields stay on the Rust server.
• The client must not infer business truth from connector internals, channel presence, or transcript heuristics.
• Persist lifecycle or control changes through explicit domain transitions.
• SQLite is the durable source of truth for server-owned state.
• In-memory session state is actor-owned only; runtime, HTTP, WebSocket, connector, and client-facing code must not patch business fields directly.
• Derived affordances such as accepts_user_input, steerable, and can_interrupt are projected from primary server state, not stored as independently mutable truth.
• WebSocket transport forwards actor-produced deltas; it must not normalize or repair business state before delivery.
• Mutable caches, registries, and locks may own resources, but they must not become alternate business-state stores.