Codex/two thread shared node graph

README.md

@@ -5,35 +5,34 @@ CodexUI 1.0 is a native Qt 6 Widgets and browser frontend for the AISuite
 without introducing another backend, semantic cache, snapshot store, or
 persistence authority.
 
-The canonical process has two threads:
+The native app-server/UI data path has two threads:
 
 ```text
 Qt GUI thread
-    <-> bounded nonblocking Unix socketpair
+    <-> typed bounded SPSC queues + one eventfd per direction
 SNode.C client thread
     <-> codex-bridge
     <-> Codex app-server
 ```
 
-The Qt thread owns widgets plus a toolkit-neutral `UiSession`, which owns the
-`PresentationModel` and UI/UX state machine. Widgets exchange only semantic
-intents and value snapshots with that boundary. `FrontendSession` adapts its
-generic presentation client to the unchanged socketpair. The SNode.C thread
-owns the event loop, selected transport, `AISuite::OpenAICodex` frontend proxy
-SDK, native protocol normalization, and connection/controller telemetry. The
-threads exchange only bounded `codexui.presentation` JSONL commands and events.
+Both threads share one current `NodeGraph`. The SNode.C worker owns
+CodexBridge, native app-server decode/encode, protocol-to-graph updates, and
+all graph writes. Qt owns every widget and local interaction mechanic, reads
+the graph only through non-blocking access, renders visible nodes in bounded
+slices, and sends closed typed actions back to the worker. No app-server JSON,
+serialized internal state, mirror model, or socketpair crosses this boundary.
 
 ## Applications
 
-`codex-ui` is the canonical visual application. Its production shell renders
-the neutral `UiSessionView` API and sends semantic intents; it does not consume
-`PresentationModel` directly. There is no parallel legacy UI or alternate
-application target.
+`codex-ui` is the canonical visual application. Its production shell binds the
+existing widgets directly to shared nodes and sends typed node/runtime actions.
+There is no parallel legacy UI or alternate application target.
 
 `CodexWebUI` is the browser presentation. It uses the framework-neutral
 `@snodec/codex-frontend` SDK from AISuite, connects directly to the bridge over
-WebSocket, and follows the same controller, prompt, thread, turn, projection,
-and reconnect rules as the native application. Browser-only limitations are
+WebSocket, and implements the same visible controller, prompt, thread, turn,
+and reconnect behavior in its own TypeScript state path. It does not share the
+native in-process graph or its widget binding. Browser-only limitations are
 listed in the [1.0 contract](docs/web-1.0-contract.md).
 
 ## Build
@@ -87,10 +86,12 @@ are in [`web/README.md`](web/README.md).
 
 ## Architecture
 
-The complete thread model, presentation protocol, authority rules, normalized
-event vocabulary, public APIs, shell behavior, implementation report, and test
-boundaries are documented in
-[`docs/codex-architecture.md`](docs/codex-architecture.md).
+The implemented native thread model, node/state authority rules, typed
+mailboxes, protocol coverage, widget binding, and qualification boundaries are
+documented in
+[`docs/two-thread-shared-node-graph.md`](docs/two-thread-shared-node-graph.md).
+[`docs/codex-architecture.md`](docs/codex-architecture.md) is a concise product
+overview linking the native and browser-specific contracts.
 
 Current message routing, pending-prompt acknowledgment, scrolling, composer
 geometry, shell-output, Inspector, and desktop-integration decisions are

design/ux-decisions/thread-turn-model.md

@@ -18,8 +18,9 @@ Thread
 ```
 
 AISuite and the app-server are authoritative for thread, turn, item, and
-configuration semantics. CodexUI retains only bounded presentation state and
-client-local interaction state.
+configuration semantics. CodexUI keeps their current local representation in
+one shared `NodeGraph`; Qt retains only bounded widget mechanics, drafts, and
+other genuinely local interaction state.
 
 ## Thread selection and routing
 
@@ -77,28 +78,34 @@ ensures that a later prompt observes the active-turn state published by the
 preceding acknowledgment. Queues belonging to different threads are
 independent.
 
-Only the correlated `turn.start` or `turn.steer` completion callback can
-acknowledge a prompt. A successful callback begins a 500-millisecond accepted
-transition. Every submission carries a unique `clientUserMessageId`, allowing
+Only the correlated `turn/start` or `turn/steer` completion callback can
+acknowledge a prompt. A successful callback immediately ends pending feedback.
+Every submission carries a unique `clientUserMessageId`, allowing
 the authoritative user item to inherit the local card's stable visual key even
 when multiple prompts have identical text. Failure stops the animation and
 leaves an explicit error card.
 
 Prompt dispatch waits for once-per-connection-generation thread hydration. A
-provider-marked `notLoaded` thread is resumed first. A transient
-thread-not-found submission result triggers one resume-and-retry; a repeated
-failure becomes the card's terminal error. Failed hydration leaves the composer
-draft intact and requires an explicit reload before admission. Dispatch
-rechecks connection and recovery ownership at its queued execution boundary, so
-a disconnect cannot send and an in-flight resume cannot overlap a hydration
-read or another turn operation.
+provider-marked `notLoaded` thread is resumed first. Failed hydration leaves
+the composer draft intact and requires an explicit reload before admission.
+Dispatch rechecks connection and recovery ownership at its queued execution
+boundary, so a disconnect cannot send and an in-flight resume cannot overlap a
+hydration read or another turn operation.
+
+Once admitted, a non-idempotent prompt is never sent again automatically. A
+thread-not-found result is terminal for that dispatch. If thread deletion or a
+provider-generation reset races queued or in-flight work, the local prompt is
+reparented to explicit recovery state with its exact admitted text and
+attachment links retained. Its state records whether failure is definite or
+the provider outcome is uncertain; reconnect, reload, and hydration never
+resend it. A later attempt requires deliberate user action.
 
 ## Start, steer, and interrupt
 
-- An idle loaded thread uses `turn.start`.
-- An active thread uses `turn.steer` with the stable active turn ID.
+- An idle loaded thread uses `turn/start`.
+- An active thread uses `turn/steer` with the stable active turn ID.
 - A not-loaded thread is resumed before starting its turn.
-- Stop uses `turn.interrupt` for the stable active turn ID.
+- Stop uses `turn/interrupt` for the stable active turn ID.
 
 CodexUI does not fabricate turns or infer active identity from row position.
 
@@ -113,13 +120,13 @@ window, while Steer adds input to an existing turn.
 
 Operational items remain individual cards inside their turn; there is no
 second Activity batch or arbitrary visible grouping. Pending prompts remain
-thread-local presentation cards until acknowledgment supplies their
+thread-local graph nodes until acknowledgment supplies their
 authoritative turn and item position.
 
-`PresentationModel` is the retained normalized source. A pure projection adds
-local prompt admissions and emits stable keyed turn sections and cards. Initial
-display and all updates use the same reconcile path; retained card widgets are
-mutated in place, and a visually identical projection performs no layout work.
+The shared `NodeGraph` is the current native source. Local prompt admissions
+are nodes in that same graph. Initial display and all updates use stable keyed
+turn sections and cards; retained visible widgets are mutated in place, while
+an invisible or visually unchanged node performs no widget layout work.
 
 ## Thread lifecycle actions
 

docs/app-server-protocol/master-data-model.md

@@ -1,4 +1,13 @@
-# Codex app-server protocol: complete framework-neutral C++ master data model
+# Historical Codex app-server protocol and proposed master data model
+
+> **Historical, non-normative design research.** The pinned wire-method
+> inventory and schema observations in this document remain useful protocol
+> references. Its proposed journal, ledger, reducer, outbox, snapshot/cursor,
+> persistence, replay, and adapter runtime are rejected and are not CodexUI's
+> implemented architecture. The current native contract is
+> [`../two-thread-shared-node-graph.md`](../two-thread-shared-node-graph.md): one
+> current shared `NodeGraph`, exactly two relevant threads, two typed SPSC
+> queues, and two Linux eventfds.
 
 ## Scope and reproducible baseline