docs: mark stage 4 runtime gaps explicit

2 files changed, 22 insertions, 11 deletions

diff --git a/crates/fparkan-animation/src/lib.rs b/crates/fparkan-animation/src/lib.rs
index 9bf9ef5..53111f3 100644
--- a/crates/fparkan-animation/src/lib.rs
+++ b/crates/fparkan-animation/src/lib.rs
@@ -1,15 +1,18 @@
 #![forbid(unsafe_code)]
 #![allow(clippy::cast_precision_loss)]
 //! Deterministic animation sampling contracts.
+//!
+//! The current sampler is a portable reference path. Compatibility profiles
+//! that require runtime-captured x87 parity remain explicit evidence gaps.
 
 use std::fmt;
 
 /// Numeric profile.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum NumericProfile {
-    /// Portable reference.
+    /// Portable reference sampler implemented by this crate.
     PortableReference,
-    /// X87-compatible compatibility profile for captured parity vectors.
+    /// Reserved profile for future runtime-captured x87 parity vectors.
     X87Compatibility,
 }
 
@@ -424,8 +427,11 @@ impl PoseTrack {
         &self.keys
     }
 
-    /// Samples the pose track with linear translation and normalized quaternion
-    /// interpolation.
+    /// Samples the pose track with the portable reference path.
+    ///
+    /// `NumericProfile::X87Compatibility` is accepted so callers can keep the
+    /// compatibility contract explicit, but it does not yet select an
+    /// independently captured x87 runtime path.
     ///
     /// # Errors
     ///
diff --git a/crates/fparkan-fx/src/lib.rs b/crates/fparkan-fx/src/lib.rs
index fb8adff..b1b5071 100644
--- a/crates/fparkan-fx/src/lib.rs
+++ b/crates/fparkan-fx/src/lib.rs
@@ -1,5 +1,10 @@
 #![forbid(unsafe_code)]
 //! FXID effect contracts.
+//!
+//! FXID decoding and command framing are implemented as compatibility
+//! contracts. The create/update/emit lifecycle below is a deterministic
+//! reference stub until opcode timing, gates, RNG, and command-body semantics
+//! are backed by runtime-captured evidence.
 
 use fparkan_binary::{Cursor, DecodeError};
 use std::sync::Arc;
@@ -121,7 +126,7 @@ impl Default for Transform {
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 pub struct GameTime(pub u64);
 
-/// FX runtime state.
+/// FX reference-stub runtime state.
 #[derive(Clone, Debug)]
 pub struct FxState {
     /// Instance id.
@@ -322,12 +327,12 @@ pub fn decode_fxid(bytes: Arc<[u8]>) -> Result<FxDocument, FxError> {
     })
 }
 
-/// Creates an FX instance.
+/// Creates a deterministic FX reference-stub instance.
 ///
 /// # Errors
 ///
 /// Currently returns [`FxError`] only for future resource/lifecycle validation
-/// hooks; creation is deterministic for a decoded document.
+/// hooks. This function does not claim original runtime parity.
 pub fn create_instance(
     document: Arc<FxDocument>,
     seed: FxSeed,
@@ -344,21 +349,21 @@ pub fn create_instance(
     })
 }
 
-/// Updates FX simulation time without emitting side effects.
+/// Updates reference-stub FX simulation time without emitting side effects.
 ///
 /// # Errors
 ///
-/// Reserved for future runtime validation.
+/// Reserved for future runtime-captured compatibility validation.
 pub fn update(state: &mut FxState, time: GameTime) -> Result<(), FxError> {
     state.time = time;
     Ok(())
 }
 
-/// Emits active commands without advancing state.
+/// Emits reference-stub active commands without advancing state.
 ///
 /// # Errors
 ///
-/// Reserved for future resource/runtime validation.
+/// Reserved for future resource/runtime-captured compatibility validation.
 pub fn emit(state: &FxState, out: &mut Vec<FxEmission>) -> Result<(), FxError> {
     if state.lifecycle != FxLifecycle::Running {
         return Ok(());